libnx  v4.2.2
ssl.h
1 /**
2  * @file fs.h
3  * @brief SSL service IPC wrapper, for using client-mode TLS. See also: https://switchbrew.org/wiki/SSL_services
4  * @author yellows8
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../sf/service.h"
10 
11 /// CaCertificateId
12 typedef enum {
13  SslCaCertificateId_All = -1, ///< [3.0.0+] All
14 
15  SslCaCertificateId_NintendoCAG3 = 1, ///< NintendoCAG3
16  SslCaCertificateId_NintendoClass2CAG3 = 2, ///< NintendoClass2CAG3
17 
18  SslCaCertificateId_AmazonRootCA1 = 1000, ///< AmazonRootCA1
19  SslCaCertificateId_StarfieldServicesRootCertificateAuthorityG2 = 1001, ///< StarfieldServicesRootCertificateAuthorityG2
20  SslCaCertificateId_AddTrustExternalCARoot = 1002, ///< AddTrustExternalCARoot
21  SslCaCertificateId_COMODOCertificationAuthority = 1003, ///< COMODOCertificationAuthority
22  SslCaCertificateId_UTNDATACorpSGC = 1004, ///< UTNDATACorpSGC
23  SslCaCertificateId_UTNUSERFirstHardware = 1005, ///< UTNUSERFirstHardware
24  SslCaCertificateId_BaltimoreCyberTrustRoot = 1006, ///< BaltimoreCyberTrustRoot
25  SslCaCertificateId_CybertrustGlobalRoot = 1007, ///< CybertrustGlobalRoot
26  SslCaCertificateId_VerizonGlobalRootCA = 1008, ///< VerizonGlobalRootCA
27  SslCaCertificateId_DigiCertAssuredIDRootCA = 1009, ///< DigiCertAssuredIDRootCA
28  SslCaCertificateId_DigiCertAssuredIDRootG2 = 1010, ///< DigiCertAssuredIDRootG2
29  SslCaCertificateId_DigiCertGlobalRootCA = 1011, ///< DigiCertGlobalRootCA
30  SslCaCertificateId_DigiCertGlobalRootG2 = 1012, ///< DigiCertGlobalRootG2
31  SslCaCertificateId_DigiCertHighAssuranceEVRootCA = 1013, ///< DigiCertHighAssuranceEVRootCA
32  SslCaCertificateId_EntrustnetCertificationAuthority2048 = 1014, ///< EntrustnetCertificationAuthority2048
33  SslCaCertificateId_EntrustRootCertificationAuthority = 1015, ///< EntrustRootCertificationAuthority
34  SslCaCertificateId_EntrustRootCertificationAuthorityG2 = 1016, ///< EntrustRootCertificationAuthorityG2
35  SslCaCertificateId_GeoTrustGlobalCA2 = 1017, ///< GeoTrustGlobalCA2 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
36  SslCaCertificateId_GeoTrustGlobalCA = 1018, ///< GeoTrustGlobalCA ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
37  SslCaCertificateId_GeoTrustPrimaryCertificationAuthorityG3 = 1019, ///< GeoTrustPrimaryCertificationAuthorityG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
38  SslCaCertificateId_GeoTrustPrimaryCertificationAuthority = 1020, ///< GeoTrustPrimaryCertificationAuthority ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
39  SslCaCertificateId_GlobalSignRootCA = 1021, ///< GlobalSignRootCA
40  SslCaCertificateId_GlobalSignRootCAR2 = 1022, ///< GlobalSignRootCAR2
41  SslCaCertificateId_GlobalSignRootCAR3 = 1023, ///< GlobalSignRootCAR3
42  SslCaCertificateId_GoDaddyClass2CertificationAuthority = 1024, ///< GoDaddyClass2CertificationAuthority
43  SslCaCertificateId_GoDaddyRootCertificateAuthorityG2 = 1025, ///< GoDaddyRootCertificateAuthorityG2
44  SslCaCertificateId_StarfieldClass2CertificationAuthority = 1026, ///< StarfieldClass2CertificationAuthority
45  SslCaCertificateId_StarfieldRootCertificateAuthorityG2 = 1027, ///< StarfieldRootCertificateAuthorityG2
46  SslCaCertificateId_thawtePrimaryRootCAG3 = 1028, ///< thawtePrimaryRootCAG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
47  SslCaCertificateId_thawtePrimaryRootCA = 1029, ///< thawtePrimaryRootCA ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
48  SslCaCertificateId_VeriSignClass3PublicPrimaryCertificationAuthorityG3 = 1030, ///< VeriSignClass3PublicPrimaryCertificationAuthorityG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
49  SslCaCertificateId_VeriSignClass3PublicPrimaryCertificationAuthorityG5 = 1031, ///< VeriSignClass3PublicPrimaryCertificationAuthorityG5 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
50  SslCaCertificateId_VeriSignUniversalRootCertificationAuthority = 1032, ///< VeriSignUniversalRootCertificationAuthority ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
51  SslCaCertificateId_DSTRootCAX3 = 1033, ///< [6.0.0+] DSTRootCAX3
52 } SslCaCertificateId;
53 
54 /// TrustedCertStatus
55 typedef enum {
56  SslTrustedCertStatus_Invalid = -1, ///< Invalid
57  SslTrustedCertStatus_Removed = 0, ///< Removed
58  SslTrustedCertStatus_EnabledTrusted = 1, ///< EnabledTrusted
59  SslTrustedCertStatus_EnabledNotTrusted = 2, ///< EnabledNotTrusted
60  SslTrustedCertStatus_Revoked = 3, ///< Revoked
61 } SslTrustedCertStatus;
62 
63 /// FlushSessionCacheOptionType
64 typedef enum {
65  SslFlushSessionCacheOptionType_SingleHost = 0, ///< SingleHost. Uses the input string.
66  SslFlushSessionCacheOptionType_AllHosts = 1, ///< AllHosts. Doesn't use the input string.
67 } SslFlushSessionCacheOptionType;
68 
69 /// DebugOptionType
70 typedef enum {
71  SslDebugOptionType_AllowDisableVerifyOption = 0, ///< AllowDisableVerifyOption
72 } SslDebugOptionType;
73 
74 /// SslVersion. This is a bitmask which controls the min/max TLS versions to use, depending on which lowest/highest bits are set (if Auto* isn't set).
75 typedef enum {
76  SslVersion_Auto = BIT(0), ///< TLS version min = 1.0, max = 1.2.
77  SslVersion_TlsV10 = BIT(3), ///< TLS 1.0.
78  SslVersion_TlsV11 = BIT(4), ///< TLS 1.1.
79  SslVersion_TlsV12 = BIT(5), ///< TLS 1.2.
80  SslVersion_TlsV13 = BIT(6), ///< [11.0.0+] TLS 1.3.
81  SslVersion_Auto24 = BIT(24), ///< [11.0.0+] Same as Auto.
82 } SslVersion;
83 
84 /// CertificateFormat
85 typedef enum {
86  SslCertificateFormat_Pem = 1, ///< Pem
87  SslCertificateFormat_Der = 2, ///< Der
88 } SslCertificateFormat;
89 
90 /// InternalPki
91 typedef enum {
92  SslInternalPki_DeviceClientCertDefault = 1, ///< DeviceClientCertDefault. Enables using the DeviceCert.
93 } SslInternalPki;
94 
95 /// ContextOption
96 typedef enum {
97  SslContextOption_CrlImportDateCheckEnable = 1, ///< CrlImportDateCheckEnable. The default value at the time of \ref sslCreateContext is value 1.
98 } SslContextOption;
99 
100 /// VerifyOption. The default bitmask value at the time of \ref sslContextCreateConnection is ::SslVerifyOption_PeerCa | ::SslVerifyOption_HostName.
101 /// [5.0.0+] \ref sslConnectionSetVerifyOption: (::SslVerifyOption_PeerCa | ::SslVerifyOption_HostName) must be set, unless: ::SslOptionType_SkipDefaultVerify is set, or [9.0.0+] ::SslDebugOptionType_AllowDisableVerifyOption is set.
102 /// [6.0.0+] \ref sslConnectionSetVerifyOption: Following that, if ::SslVerifyOption_EvPolicyOid is set, then the following options must be set (besides the previously mentioned one): ::SslVerifyOption_PeerCa and ::SslVerifyOption_DateCheck.
103 typedef enum {
104  SslVerifyOption_PeerCa = BIT(0), ///< PeerCa
105  SslVerifyOption_HostName = BIT(1), ///< HostName
106  SslVerifyOption_DateCheck = BIT(2), ///< DateCheck
107  SslVerifyOption_EvCertPartial = BIT(3), ///< EvCertPartial
108  SslVerifyOption_EvPolicyOid = BIT(4), ///< [6.0.0+] EvPolicyOid
109  SslVerifyOption_EvCertFingerprint = BIT(5), ///< [6.0.0+] EvCertFingerprint
110 } SslVerifyOption;
111 
112 /// IoMode. The default value at the time of \ref sslContextCreateConnection is ::SslIoMode_Blocking.
113 /// The socket non-blocking flag is always set regardless of this field, this is only used internally for calculating the timeout used by various cmds.
114 typedef enum {
115  SslIoMode_Blocking = 1, ///< Blocking. Timeout = 5 minutes.
116  SslIoMode_NonBlocking = 2, ///< NonBlocking. Timeout = 0.
117 } SslIoMode;
118 
119 /// PollEvent
120 typedef enum {
121  SslPollEvent_Read = BIT(0), ///< Read
122  SslPollEvent_Write = BIT(1), ///< Write
123  SslPollEvent_Except = BIT(2), ///< Except
124 } SslPollEvent;
125 
126 /// SessionCacheMode
127 typedef enum {
128  SslSessionCacheMode_None = 0, ///< None
129  SslSessionCacheMode_SessionId = 1, ///< SessionId
130  SslSessionCacheMode_SessionTicket = 2, ///< SessionTicket
131 } SslSessionCacheMode;
132 
133 /// RenegotiationMode
134 typedef enum {
135  SslRenegotiationMode_None = 0, ///< None
136  SslRenegotiationMode_Secure = 1, ///< Secure
137 } SslRenegotiationMode;
138 
139 /// OptionType. The default bool flags value for these at the time of \ref sslContextCreateConnection is cleared.
140 typedef enum {
141  SslOptionType_DoNotCloseSocket = 0, ///< DoNotCloseSocket. See \ref sslConnectionSetSocketDescriptor. This is only available if \ref sslConnectionSetSocketDescriptor wasn't used yet.
142  SslOptionType_GetServerCertChain = 1, ///< [3.0.0+] GetServerCertChain. See \ref sslConnectionDoHandshake.
143  SslOptionType_SkipDefaultVerify = 2, ///< [5.0.0+] SkipDefaultVerify. Checked by \ref sslConnectionSetVerifyOption, see \ref SslVerifyOption.
144  SslOptionType_EnableAlpn = 3, ///< [9.0.0+] EnableAlpn. Only available with \ref sslConnectionSetOption. \ref sslConnectionSetSocketDescriptor should have been used prior to this - this will optionally use state setup by that, without throwing an error if that cmd wasn't used.
145 } SslOptionType;
146 
147 /// AlpnProtoState
148 typedef enum {
149  SslAlpnProtoState_NoSupport = 0, ///< NoSupport
150  SslAlpnProtoState_Negotiated = 1, ///< Negotiated
151  SslAlpnProtoState_NoOverlap = 2, ///< NoOverlap
152  SslAlpnProtoState_Selected = 3, ///< Selected
153  SslAlpnProtoState_EarlyValue = 4, ///< EarlyValue
154 } SslAlpnProtoState;
155 
156 /// SslContext
157 typedef struct {
158  Service s; ///< ISslContext
159 } SslContext;
160 
161 /// SslConnection
162 typedef struct {
163  Service s; ///< ISslConnection
164 } SslConnection;
165 
166 /// BuiltInCertificateInfo
167 typedef struct {
168  u32 cert_id; ///< \ref SslCaCertificateId
169  u32 status; ///< \ref SslTrustedCertStatus
170  u64 cert_size; ///< CertificateSize
171  u8 *cert_data; ///< CertificateData (converted from an offset to a ptr), in DER format.
172 } SslBuiltInCertificateInfo;
173 
174 /// SslServerCertDetailHeader
175 typedef struct {
176  u64 magicnum; ///< Magicnum.
177  u32 cert_total; ///< Total certs.
178  u32 pad; ///< Padding.
179 } SslServerCertDetailHeader;
180 
181 /// SslServerCertDetailEntry
182 typedef struct {
183  u32 size; ///< Size.
184  u32 offset; ///< Offset.
185 } SslServerCertDetailEntry;
186 
187 /// CipherInfo
188 typedef struct {
189  char cipher[0x40]; ///< Cipher string.
190  char protocol_version[0x8]; ///< Protocol version string.
191 } SslCipherInfo;
192 
193 /// Initialize ssl. A default value of 0x3 can be used for num_sessions. This must be 0x1-0x4.
194 Result sslInitialize(u32 num_sessions);
195 
196 /// Exit ssl.
197 void sslExit(void);
198 
199 /// Gets the Service object for the actual ssl service session.
200 Service* sslGetServiceSession(void);
201 
202 /**
203  * @brief CreateContext
204  * @note The CertStore is used automatically, regardless of what cmds are used.
205  * @param[out] c \ref SslContext
206  * @param[in] ssl_version \ref SslVersion
207  */
208 Result sslCreateContext(SslContext *c, u32 ssl_version);
209 
210 /**
211  * @brief GetContextCount
212  * @note Not used by official sw.
213  * @param[out] out Output value.
214  */
215 Result sslGetContextCount(u32 *out);
216 
217 /**
218  * @brief GetCertificates
219  * @param[in] buffer Output buffer. The start of this buffer is an array of \ref SslBuiltInCertificateInfo, with the specified count. The cert data (SslBuiltInCertificateInfo::data) is located after this array.
220  * @param[in] size Output buffer size, this should be the size from \ref sslGetCertificateBufSize.
221  * @param[in] ca_cert_ids Input array of \ref SslCaCertificateId.
222  * @param[in] count Size of the ca_cert_ids array in entries.
223  * @param[out] total_out [3.0.0+] Total output entries. Will always match count on pre-3.0.0. This will differ from count when ::SslCaCertificateId_All is used.
224  */
225 Result sslGetCertificates(void* buffer, u32 size, u32 *ca_cert_ids, u32 count, u32 *total_out);
226 
227 /**
228  * @brief GetCertificateBufSize
229  * @param[in] ca_cert_ids Input array of \ref SslCaCertificateId.
230  * @param[in] count Size of the ca_cert_ids array in entries.
231  * @param[out] out Output size.
232  */
233 Result sslGetCertificateBufSize(u32 *ca_cert_ids, u32 count, u32 *out);
234 
235 /**
236  * @brief FlushSessionCache
237  * @note Only available on [5.0.0+].
238  * @param[in] str Input string. Must be NULL with ::SslFlushSessionCacheOptionType_AllHosts.
239  * @param[in] str_bufsize String buffer size, excluding NUL-terminator. Hence, this should be actual_bufsize-1. This must be 0 with ::SslFlushSessionCacheOptionType_AllHosts.
240  * @param[in] type \ref SslFlushSessionCacheOptionType
241  * @param[out] out Output value.
242  */
243 Result sslFlushSessionCache(const char *str, size_t str_bufsize, SslFlushSessionCacheOptionType type, u32 *out);
244 
245 /**
246  * @brief SetDebugOption
247  * @note Only available on [6.0.0+].
248  * @note The official impl of this doesn't actually use the cmd.
249  * @param[in] buffer Input buffer, must not be NULL. The u8 from here is copied to state.
250  * @param[in] size Buffer size, must not be 0.
251  * @param[in] type \ref SslDebugOptionType
252  */
253 Result sslSetDebugOption(const void* buffer, size_t size, SslDebugOptionType type);
254 
255 /**
256  * @brief GetDebugOption
257  * @note Only available on [6.0.0+].
258  * @param[out] buffer Output buffer, must not be NULL. An u8 is written here loaded from state.
259  * @param[in] size Buffer size, must not be 0.
260  * @param[in] type \ref SslDebugOptionType
261  */
262 Result sslGetDebugOption(void* buffer, size_t size, SslDebugOptionType type);
263 
264 ///@name ISslContext
265 ///@{
266 
267 /**
268  * @brief Closes a Context object.
269  * @param c \ref SslContext
270  */
271 void sslContextClose(SslContext *c);
272 
273 /**
274  * @brief SetOption
275  * @note Prior to 4.x this is stubbed.
276  * @param c \ref SslContext
277  * @param[in] option \ref SslContextOption
278  * @param[in] value Value to set. With ::SslContextOption_CrlImportDateCheckEnable, this must be 0 or 1.
279  */
280 Result sslContextSetOption(SslContext *c, SslContextOption option, s32 value);
281 
282 /**
283  * @brief GetOption
284  * @note Prior to 4.x this is stubbed.
285  * @param c \ref SslContext
286  * @param[in] option \ref SslContextOption
287  * @param[out] out Output value.
288  */
289 Result sslContextGetOption(SslContext *c, SslContextOption option, s32 *out);
290 
291 /**
292  * @brief CreateConnection
293  * @param c \ref SslContext
294  * @param[out] conn Output \ref SslConnection.
295  */
296 Result sslContextCreateConnection(SslContext *c, SslConnection *conn);
297 
298 /**
299  * @brief GetConnectionCount
300  * @note Not exposed by official sw.
301  * @param c \ref SslContext
302  * @param[out] out Output value.
303  */
304 Result sslContextGetConnectionCount(SslContext *c, u32 *out);
305 
306 /**
307  * @brief ImportServerPki
308  * @note A maximum of 71 ServerPki objects (associated with the output Id) can be imported.
309  * @param c \ref SslContext
310  * @param[in] buffer Input buffer containing the cert data, must not be NULL. This can contain multiple certs. The certs can be CAs or server certs (no pubkeys).
311  * @param[in] size Input buffer size.
312  * @param[in] format \ref SslCertificateFormat
313  * @param[out] id Output Id. Optional, can be NULL.
314  */
315 Result sslContextImportServerPki(SslContext *c, const void* buffer, u32 size, SslCertificateFormat format, u64 *id);
316 
317 /**
318  * @brief ImportClientPki
319  * @note An error is thrown internally if this cmd or \ref sslContextRegisterInternalPki was already used previously.
320  * @param c \ref SslContext
321  * @param[in] pkcs12 PKCS#12 input buffer, must not be NULL.
322  * @param[in] pkcs12_size pkcs12 buffer size.
323  * @param[in] pw ASCII password string buffer, this can only be NULL if pw_size is 0. This will be internally copied to another buffer which was allocated with size=pw_size+1, for NUL-termination.
324  * @param[in] pw_size Password buffer size, this can only be 0 if pw is NULL.
325  * @param[out] id Output Id. Optional, can be NULL.
326  */
327 Result sslContextImportClientPki(SslContext *c, const void* pkcs12, u32 pkcs12_size, const char *pw, u32 pw_size, u64 *id);
328 
329 /**
330  * @brief Remove the specified *Pki, or on [3.0.0+] Crl.
331  * @param c \ref SslContext
332  * @param[in] id Id
333  */
334 Result sslContextRemovePki(SslContext *c, u64 id);
335 
336 /**
337  * @brief RegisterInternalPki
338  * @note An error is thrown internally if this cmd or \ref sslContextImportClientPki was already used previously.
339  * @param c \ref SslContext
340  * @param[in] internal_pki \ref SslInternalPki
341  * @param[out] id Output Id. Optional, can be NULL.
342  */
343 Result sslContextRegisterInternalPki(SslContext *c, SslInternalPki internal_pki, u64 *id);
344 
345 /**
346  * @brief AddPolicyOid
347  * @param c \ref SslContext
348  * @param[in] str Input string.
349  * @param[in] str_bufsize String buffer size, excluding NUL-terminator (must not match the string length). Hence, this should be actual_bufsize-1. This must not be >0xff.
350  */
351 Result sslContextAddPolicyOid(SslContext *c, const char *str, u32 str_bufsize);
352 
353 /**
354  * @brief ImportCrl
355  * @note Only available on [3.0.0+].
356  * @param c \ref SslContext
357  * @param[in] buffer Input buffer, must not be NULL. This contains the DER CRL.
358  * @param[in] size Input buffer size.
359  * @param[out] id Output Id. Optional, can be NULL.
360  */
361 Result sslContextImportCrl(SslContext *c, const void* buffer, u32 size, u64 *id);
362 
363 ///@}
364 
365 ///@name ISslConnection
366 ///@{
367 
368 /**
369  * @brief Closes a Connection object.
370  * @param c \ref SslConnection
371  */
372 void sslConnectionClose(SslConnection *c);
373 
374 /**
375  * @brief SetSocketDescriptor. Do not use directly, use \ref socketSslConnectionSetSocketDescriptor instead.
376  * @note An error is thrown if this was used previously.
377  * @param c \ref SslConnection
378  * @param[in] sockfd sockfd
379  * @param[out] out_sockfd sockfd. Prior to using \ref sslConnectionClose, this must be closed if it's not negative (it will be -1 if ::SslOptionType_DoNotCloseSocket is set).
380  */
381 Result sslConnectionSetSocketDescriptor(SslConnection *c, int sockfd, int *out_sockfd);
382 
383 /**
384  * @brief SetHostName
385  * @param c \ref SslConnection
386  * @param[in] str Input string.
387  * @param[in] str_bufsize String buffer size. This must not be >0xff.
388  */
389 Result sslConnectionSetHostName(SslConnection *c, const char* str, u32 str_bufsize);
390 
391 /**
392  * @brief SetVerifyOption
393  * @param c \ref SslConnection
394  * @param[in] verify_option Input bitmask of \ref SslVerifyOption.
395  */
396 Result sslConnectionSetVerifyOption(SslConnection *c, u32 verify_option);
397 
398 /**
399  * @brief SetIoMode
400  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
401  * @param c \ref SslConnection
402  * @param[in] mode \ref SslIoMode
403  */
404 Result sslConnectionSetIoMode(SslConnection *c, SslIoMode mode);
405 
406 /**
407  * @brief GetSocketDescriptor. Do not use directly, use \ref socketSslConnectionGetSocketDescriptor instead.
408  * @note This gets the input sockfd which was previously saved in state by \ref sslConnectionSetSocketDescriptor.
409  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
410  * @param c \ref SslConnection
411  * @param[out] sockfd Output sockfd.
412  */
413 Result sslConnectionGetSocketDescriptor(SslConnection *c, int *sockfd);
414 
415 /**
416  * @brief GetHostName
417  * @param c \ref SslConnection
418  * @param[out] str Output string buffer.
419  * @param[in] str_bufsize String buffer size, must be large enough for the entire output string.
420  * @param[out] out Output string length.
421  */
422 Result sslConnectionGetHostName(SslConnection *c, char *str, u32 str_bufsize, u32 *out);
423 
424 /**
425  * @brief GetVerifyOption
426  * @param c \ref SslConnection
427  * @param[out] out Output bitmask of \ref SslVerifyOption.
428  */
429 Result sslConnectionGetVerifyOption(SslConnection *c, u32 *out);
430 
431 /**
432  * @brief GetIoMode
433  * @param c \ref SslConnection
434  * @param[out] out \ref SslIoMode
435  */
436 Result sslConnectionGetIoMode(SslConnection *c, SslIoMode *out);
437 
438 /**
439  * @brief DoHandshake
440  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
441  * @note \ref sslConnectionSetHostName must have been used previously with a non-empty string when ::SslVerifyOption_HostName is set.
442  * @note The DoHandshakeGetServerCert cmd is only used if both server_certbuf/server_certbuf_size are set, otherwise the DoHandshake cmd is used (in which case out_size/total_certs will be left at value 0).
443  * @note No certs are returned when ::SslVerifyOption_PeerCa is not set.
444  * @param c \ref SslConnection
445  * @param[out] out_size Total data size which was written to server_certbuf. Optional, can be NULL.
446  * @param[out] total_certs Total certs which were written to server_certbuf, can be NULL.
447  * @param[out] server_certbuf Optional output server cert buffer, can be NULL. Normally this just contains the server cert DER, however with ::SslOptionType_GetServerCertChain set this will contain the full chain (\ref sslConnectionGetServerCertDetail can be used to parse that). With ::SslIoMode_NonBlocking this buffer will be only filled in once - when this cmd returns successfully the buffer will generally be empty.
448  * @param[in] server_certbuf_size Optional output server cert buffer size, can be 0.
449  */
450 Result sslConnectionDoHandshake(SslConnection *c, u32 *out_size, u32 *total_certs, void* server_certbuf, u32 server_certbuf_size);
451 
452 /**
453  * @brief Parses the output server_certbuf from \ref sslConnectionDoHandshake where ::SslOptionType_GetServerCertChain is set.
454  * @param[in] certbuf server_certbuf from \ref sslConnectionDoHandshake, must not be NULL.
455  * @param[in] certbuf_size out_size from \ref sslConnectionDoHandshake.
456  * @param[in] cert_index Cert index, must be within the range of certs stored in certbuf.
457  * @param[out] cert Ptr for the ouput DER cert, must not be NULL.
458  * @param[out] cert_size Size for the ouput cert, must not be NULL.
459  */
460 Result sslConnectionGetServerCertDetail(const void* certbuf, u32 certbuf_size, u32 cert_index, void** cert, u32 *cert_size);
461 
462 /**
463  * @brief Read
464  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
465  * @param c \ref SslConnection
466  * @param[out] buffer Output buffer, must not be NULL.
467  * @param[in] size Output buffer size, must not be 0.
468  * @param[out] out_size Actual transferred size.
469  */
470 Result sslConnectionRead(SslConnection *c, void* buffer, u32 size, u32 *out_size);
471 
472 /**
473  * @brief Write
474  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
475  * @param c \ref SslConnection
476  * @param[in] buffer Input buffer, must not be NULL.
477  * @param[in] size Input buffer size, must not be 0.
478  * @param[out] out_size Actual transferred size.
479  */
480 Result sslConnectionWrite(SslConnection *c, const void* buffer, u32 size, u32 *out_size);
481 
482 /**
483  * @brief Pending
484  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
485  * @param c \ref SslConnection
486  * @param[out] out Output value.
487  */
488 Result sslConnectionPending(SslConnection *c, s32 *out);
489 
490 /**
491  * @brief Peek
492  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
493  * @param c \ref SslConnection
494  * @param[out] buffer Output buffer, must not be NULL.
495  * @param[in] size Output buffer size, must not be 0.
496  * @param[out] out_size Output size.
497  */
498 Result sslConnectionPeek(SslConnection *c, void* buffer, u32 size, u32 *out_size);
499 
500 /**
501  * @brief Poll
502  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
503  * @param c \ref SslConnection
504  * @param[in] in_pollevent Input bitmask of \ref SslPollEvent.
505  * @param[out] out_pollevent Output bitmask of \ref SslPollEvent.
506  * @param[in] timeout Timeout in milliseconds.
507  */
508 Result sslConnectionPoll(SslConnection *c, u32 in_pollevent, u32 *out_pollevent, u32 timeout);
509 
510 /**
511  * @brief GetVerifyCertError
512  * @note The value in state is cleared after loading it.
513  * @param c \ref SslConnection
514  */
515 Result sslConnectionGetVerifyCertError(SslConnection *c);
516 
517 /**
518  * @brief GetNeededServerCertBufferSize
519  * @param c \ref SslConnection
520  * @param[out] out Output value.
521  */
522 Result sslConnectionGetNeededServerCertBufferSize(SslConnection *c, u32 *out);
523 
524 /**
525  * @brief SetSessionCacheMode
526  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
527  * @param c \ref SslConnection
528  * @param[in] mode \ref SslSessionCacheMode
529  */
530 Result sslConnectionSetSessionCacheMode(SslConnection *c, SslSessionCacheMode mode);
531 
532 /**
533  * @brief GetSessionCacheMode
534  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
535  * @param c \ref SslConnection
536  * @param[out] out \ref SslSessionCacheMode
537  */
538 Result sslConnectionGetSessionCacheMode(SslConnection *c, SslSessionCacheMode *out);
539 
540 /**
541  * @brief GetSessionCacheMode
542  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
543  * @param c \ref SslConnection
544  */
545 Result sslConnectionFlushSessionCache(SslConnection *c);
546 
547 /**
548  * @brief SetRenegotiationMode
549  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
550  * @param c \ref SslConnection
551  * @param[in] mode \ref SslRenegotiationMode
552  */
553 Result sslConnectionSetRenegotiationMode(SslConnection *c, SslRenegotiationMode mode);
554 
555 /**
556  * @brief GetRenegotiationMode
557  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
558  * @param c \ref SslConnection
559  * @param[out] out \ref SslRenegotiationMode
560  */
561 Result sslConnectionGetRenegotiationMode(SslConnection *c, SslRenegotiationMode *out);
562 
563 /**
564  * @brief SetOption
565  * @param c \ref SslConnection
566  * @param[in] option \ref SslOptionType
567  * @param[in] flag Input flag value.
568  */
569 Result sslConnectionSetOption(SslConnection *c, SslOptionType option, bool flag);
570 
571 /**
572  * @brief GetOption
573  * @param c \ref SslConnection
574  * @param[in] option \ref SslOptionType
575  * @param[out] out Output flag value.
576  */
577 Result sslConnectionGetOption(SslConnection *c, SslOptionType option, bool *out);
578 
579 /**
580  * @brief GetVerifyCertErrors
581  * @note An error is thrown when the cmd is successful, if the two output u32s match.
582  * @param[out] out0 First output value, must not be NULL.
583  * @param[out] out1 Second output value.
584  * @param[out] errors Output array of Result, must not be NULL.
585  * @param[in] count Size of the errors array in entries.
586  */
587 Result sslConnectionGetVerifyCertErrors(SslConnection *c, u32 *out0, u32 *out1, Result *errors, u32 count);
588 
589 /**
590  * @brief GetCipherInfo
591  * @note Only available on [4.0.0+].
592  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
593  * @param c \ref SslConnection
594  * @param[out] out \ref SslCipherInfo
595  */
596 Result sslConnectionGetCipherInfo(SslConnection *c, SslCipherInfo *out);
597 
598 /**
599  * @brief SetNextAlpnProto
600  * @note Only available on [9.0.0+].
601  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
602  * @note ::SslOptionType_EnableAlpn should be set at the time of using \ref sslConnectionDoHandshake, otherwise using this cmd will have no affect.
603  * @param c \ref SslConnection
604  * @param[in] buffer Input buffer, must not be NULL. This contains an array of {u8 size, {data with the specified size}}, which must be within the buffer-size bounds.
605  * @param[in] size Input buffer size, must not be 0. Must be at least 0x2.
606  */
607 Result sslConnectionSetNextAlpnProto(SslConnection *c, const u8 *buffer, u32 size);
608 
609 /**
610  * @brief GetNextAlpnProto
611  * @note Only available on [9.0.0+].
612  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
613  * @note The output will be all-zero/empty if not available - such as when this was used before \ref sslConnectionDoHandshake.
614  * @param c \ref SslConnection
615  * @param[out] state \ref SslAlpnProtoState
616  * @param[out] out Output string length.
617  * @param[out] buffer Output string buffer, must not be NULL.
618  * @param[in] size Output buffer size, must not be 0.
619  */
620 Result sslConnectionGetNextAlpnProto(SslConnection *c, SslAlpnProtoState *state, u32 *out, u8 *buffer, u32 size);
621 
622 ///@}
623 
SslBuiltInCertificateInfo::cert_data
u8 * cert_data
CertificateData (converted from an offset to a ptr), in DER format.
Definition: ssl.h:171
SslBuiltInCertificateInfo
BuiltInCertificateInfo.
Definition: ssl.h:167
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
SslBuiltInCertificateInfo::cert_id
u32 cert_id
SslCaCertificateId
Definition: ssl.h:168
SslServerCertDetailHeader
SslServerCertDetailHeader.
Definition: ssl.h:175
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
SslContext::s
Service s
ISslContext.
Definition: ssl.h:158
SslConnection::s
Service s
ISslConnection.
Definition: ssl.h:163
Result
u32 Result
Function error code result type.
Definition: types.h:44
SslServerCertDetailEntry
SslServerCertDetailEntry.
Definition: ssl.h:182
SslServerCertDetailHeader::pad
u32 pad
Padding.
Definition: ssl.h:178
SslConnection
SslConnection.
Definition: ssl.h:162
SslContext
SslContext.
Definition: ssl.h:157
SslServerCertDetailEntry::offset
u32 offset
Offset.
Definition: ssl.h:184
SslServerCertDetailHeader::cert_total
u32 cert_total
Total certs.
Definition: ssl.h:177
SslBuiltInCertificateInfo::cert_size
u64 cert_size
CertificateSize.
Definition: ssl.h:170
BIT
#define BIT(n)
Creates a bitmask from a bit number.
Definition: types.h:54
Service
Service object structure.
Definition: service.h:13
SslCipherInfo
CipherInfo.
Definition: ssl.h:188
SslBuiltInCertificateInfo::status
u32 status
SslTrustedCertStatus
Definition: ssl.h:169
SslServerCertDetailHeader::magicnum
u64 magicnum
Magicnum.
Definition: ssl.h:176
SslServerCertDetailEntry::size
u32 size
Size.
Definition: ssl.h:183
Generated by   doxygen 1.8.17