libnx  v4.6.0
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 /// Values for __nx_ssl_service_type, controls which ssl service to initialize.
12 typedef enum {
13  SslServiceType_Default = 0, ///< Initialize the ssl service.
14  SslServiceType_System = 1, ///< [15.0.0+] Initialize the ssl:s service. On older versions this is the same as ::SslServiceType_Default.
15 } SslServiceType;
16 
17 /// CaCertificateId
18 typedef enum {
19  SslCaCertificateId_All = -1, ///< [3.0.0+] All
20 
21  SslCaCertificateId_NintendoCAG3 = 1, ///< NintendoCAG3
22  SslCaCertificateId_NintendoClass2CAG3 = 2, ///< NintendoClass2CAG3
23  SslCaCertificateId_NintendoRootCAG4 = 3, ///< [16.0.0+] "Nintendo Root CA G4"
24 
25  SslCaCertificateId_AmazonRootCA1 = 1000, ///< AmazonRootCA1
26  SslCaCertificateId_StarfieldServicesRootCertificateAuthorityG2 = 1001, ///< StarfieldServicesRootCertificateAuthorityG2
27  SslCaCertificateId_AddTrustExternalCARoot = 1002, ///< AddTrustExternalCARoot
28  SslCaCertificateId_COMODOCertificationAuthority = 1003, ///< COMODOCertificationAuthority
29  SslCaCertificateId_UTNDATACorpSGC = 1004, ///< UTNDATACorpSGC
30  SslCaCertificateId_UTNUSERFirstHardware = 1005, ///< UTNUSERFirstHardware
31  SslCaCertificateId_BaltimoreCyberTrustRoot = 1006, ///< BaltimoreCyberTrustRoot
32  SslCaCertificateId_CybertrustGlobalRoot = 1007, ///< CybertrustGlobalRoot
33  SslCaCertificateId_VerizonGlobalRootCA = 1008, ///< VerizonGlobalRootCA
34  SslCaCertificateId_DigiCertAssuredIDRootCA = 1009, ///< DigiCertAssuredIDRootCA
35  SslCaCertificateId_DigiCertAssuredIDRootG2 = 1010, ///< DigiCertAssuredIDRootG2
36  SslCaCertificateId_DigiCertGlobalRootCA = 1011, ///< DigiCertGlobalRootCA
37  SslCaCertificateId_DigiCertGlobalRootG2 = 1012, ///< DigiCertGlobalRootG2
38  SslCaCertificateId_DigiCertHighAssuranceEVRootCA = 1013, ///< DigiCertHighAssuranceEVRootCA
39  SslCaCertificateId_EntrustnetCertificationAuthority2048 = 1014, ///< EntrustnetCertificationAuthority2048
40  SslCaCertificateId_EntrustRootCertificationAuthority = 1015, ///< EntrustRootCertificationAuthority
41  SslCaCertificateId_EntrustRootCertificationAuthorityG2 = 1016, ///< EntrustRootCertificationAuthorityG2
42  SslCaCertificateId_GeoTrustGlobalCA2 = 1017, ///< GeoTrustGlobalCA2 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
43  SslCaCertificateId_GeoTrustGlobalCA = 1018, ///< GeoTrustGlobalCA ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
44  SslCaCertificateId_GeoTrustPrimaryCertificationAuthorityG3 = 1019, ///< GeoTrustPrimaryCertificationAuthorityG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
45  SslCaCertificateId_GeoTrustPrimaryCertificationAuthority = 1020, ///< GeoTrustPrimaryCertificationAuthority ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
46  SslCaCertificateId_GlobalSignRootCA = 1021, ///< GlobalSignRootCA
47  SslCaCertificateId_GlobalSignRootCAR2 = 1022, ///< GlobalSignRootCAR2
48  SslCaCertificateId_GlobalSignRootCAR3 = 1023, ///< GlobalSignRootCAR3
49  SslCaCertificateId_GoDaddyClass2CertificationAuthority = 1024, ///< GoDaddyClass2CertificationAuthority
50  SslCaCertificateId_GoDaddyRootCertificateAuthorityG2 = 1025, ///< GoDaddyRootCertificateAuthorityG2
51  SslCaCertificateId_StarfieldClass2CertificationAuthority = 1026, ///< StarfieldClass2CertificationAuthority
52  SslCaCertificateId_StarfieldRootCertificateAuthorityG2 = 1027, ///< StarfieldRootCertificateAuthorityG2
53  SslCaCertificateId_thawtePrimaryRootCAG3 = 1028, ///< thawtePrimaryRootCAG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
54  SslCaCertificateId_thawtePrimaryRootCA = 1029, ///< thawtePrimaryRootCA ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
55  SslCaCertificateId_VeriSignClass3PublicPrimaryCertificationAuthorityG3 = 1030, ///< VeriSignClass3PublicPrimaryCertificationAuthorityG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
56  SslCaCertificateId_VeriSignClass3PublicPrimaryCertificationAuthorityG5 = 1031, ///< VeriSignClass3PublicPrimaryCertificationAuthorityG5 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
57  SslCaCertificateId_VeriSignUniversalRootCertificationAuthority = 1032, ///< VeriSignUniversalRootCertificationAuthority ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted)
58  SslCaCertificateId_DSTRootCAX3 = 1033, ///< [6.0.0+] DSTRootCAX3
59  SslCaCertificateId_USERTrustRsaCertificationAuthority = 1034, ///< [10.0.3+] "USERTrust RSA Certification Authority"
60  SslCaCertificateId_ISRGRootX10 = 1035, ///< [10.1.0+] "ISRG Root X10"
61  SslCaCertificateId_USERTrustEccCertificationAuthority = 1036, ///< [10.1.0+] "USERTrust ECC Certification Authority"
62  SslCaCertificateId_COMODORsaCertificationAuthority = 1037, ///< [10.1.0+] "COMODO RSA Certification Authority"
63  SslCaCertificateId_COMODOEccCertificationAuthority = 1038, ///< [10.1.0+] "COMODO ECC Certification Authority"
64  SslCaCertificateId_AmazonRootCA2 = 1039, ///< [11.0.0+] "Amazon Root CA 2"
65  SslCaCertificateId_AmazonRootCA3 = 1040, ///< [11.0.0+] "Amazon Root CA 3"
66  SslCaCertificateId_AmazonRootCA4 = 1041, ///< [11.0.0+] "Amazon Root CA 4"
67  SslCaCertificateId_DigiCertAssuredIDRootG3 = 1042, ///< [11.0.0+] "DigiCert Assured ID Root G3"
68  SslCaCertificateId_DigiCertGlobalRootG3 = 1043, ///< [11.0.0+] "DigiCert Global Root G3"
69  SslCaCertificateId_DigiCertTrustedRootG4 = 1044, ///< [11.0.0+] "DigiCert Trusted Root G4"
70  SslCaCertificateId_EntrustRootCertificationAuthorityEC1 = 1045, ///< [11.0.0+] "Entrust Root Certification Authority - EC1"
71  SslCaCertificateId_EntrustRootCertificationAuthorityG4 = 1046, ///< [11.0.0+] "Entrust Root Certification Authority - G4"
72  SslCaCertificateId_GlobalSignECCRootCAR4 = 1047, ///< [11.0.0+] "GlobalSign ECC Root CA - R4"
73  SslCaCertificateId_GlobalSignECCRootCAR5 = 1048, ///< [11.0.0+] "GlobalSign ECC Root CA - R5"
74  SslCaCertificateId_GlobalSignECCRootCAR6 = 1049, ///< [11.0.0+] "GlobalSign ECC Root CA - R6"
75  SslCaCertificateId_GTSRootR1 = 1050, ///< [11.0.0+] "GTS Root R1"
76  SslCaCertificateId_GTSRootR2 = 1051, ///< [11.0.0+] "GTS Root R2"
77  SslCaCertificateId_GTSRootR3 = 1052, ///< [11.0.0+] "GTS Root R3"
78  SslCaCertificateId_GTSRootR4 = 1053, ///< [11.0.0+] "GTS Root R4"
79  SslCaCertificateId_SecurityCommunicationRootCA = 1054, ///< [12.0.0+] "Security Communication RootCA"
80  SslCaCertificateId_GlobalSignRootE4 = 1055, ///< [15.0.0+] "GlobalSign Root E4"
81  SslCaCertificateId_GlobalSignRootR4 = 1056, ///< [15.0.0+] "GlobalSign Root R4"
82  SslCaCertificateId_TTeleSecGlobalRootClass2 = 1057, ///< [15.0.0+] "T-TeleSec GlobalRoot Class 2"
83  SslCaCertificateId_DigiCertTLSECCP384RootG5 = 1058, ///< [16.0.0+] "DigiCert TLS ECC P384 Root G5"
84  SslCaCertificateId_DigiCertTLSRSA4096RootG5 = 1059, ///< [16.0.0+] "DigiCert TLS RSA4096 Root G5"
85 } SslCaCertificateId;
86 
87 /// TrustedCertStatus
88 typedef enum {
89  SslTrustedCertStatus_Invalid = -1, ///< Invalid
90  SslTrustedCertStatus_Removed = 0, ///< Removed
91  SslTrustedCertStatus_EnabledTrusted = 1, ///< EnabledTrusted
92  SslTrustedCertStatus_EnabledNotTrusted = 2, ///< EnabledNotTrusted
93  SslTrustedCertStatus_Revoked = 3, ///< Revoked
94 } SslTrustedCertStatus;
95 
96 /// FlushSessionCacheOptionType
97 typedef enum {
98  SslFlushSessionCacheOptionType_SingleHost = 0, ///< SingleHost. Uses the input string.
99  SslFlushSessionCacheOptionType_AllHosts = 1, ///< AllHosts. Doesn't use the input string.
100 } SslFlushSessionCacheOptionType;
101 
102 /// DebugOptionType
103 typedef enum {
104  SslDebugOptionType_AllowDisableVerifyOption = 0, ///< AllowDisableVerifyOption
105 } SslDebugOptionType;
106 
107 /// 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).
108 typedef enum {
109  SslVersion_Auto = BIT(0), ///< TLS version min = 1.0, max = 1.2.
110  SslVersion_TlsV10 = BIT(3), ///< TLS 1.0.
111  SslVersion_TlsV11 = BIT(4), ///< TLS 1.1.
112  SslVersion_TlsV12 = BIT(5), ///< TLS 1.2.
113  SslVersion_TlsV13 = BIT(6), ///< [11.0.0+] TLS 1.3.
114  SslVersion_Auto24 = BIT(24), ///< [11.0.0+] Same as Auto.
115 } SslVersion;
116 
117 /// CertificateFormat
118 typedef enum {
119  SslCertificateFormat_Pem = 1, ///< Pem
120  SslCertificateFormat_Der = 2, ///< Der
121 } SslCertificateFormat;
122 
123 /// InternalPki
124 typedef enum {
125  SslInternalPki_DeviceClientCertDefault = 1, ///< DeviceClientCertDefault. Enables using the DeviceCert.
126 } SslInternalPki;
127 
128 /// ContextOption
129 typedef enum {
130  SslContextOption_CrlImportDateCheckEnable = 1, ///< CrlImportDateCheckEnable. The default value at the time of \ref sslCreateContext is value 1.
131 } SslContextOption;
132 
133 /// VerifyOption. The default bitmask value at the time of \ref sslContextCreateConnection is ::SslVerifyOption_PeerCa | ::SslVerifyOption_HostName.
134 /// [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.
135 /// [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.
136 typedef enum {
137  SslVerifyOption_PeerCa = BIT(0), ///< PeerCa
138  SslVerifyOption_HostName = BIT(1), ///< HostName
139  SslVerifyOption_DateCheck = BIT(2), ///< DateCheck
140  SslVerifyOption_EvCertPartial = BIT(3), ///< EvCertPartial
141  SslVerifyOption_EvPolicyOid = BIT(4), ///< [6.0.0+] EvPolicyOid
142  SslVerifyOption_EvCertFingerprint = BIT(5), ///< [6.0.0+] EvCertFingerprint
143 } SslVerifyOption;
144 
145 /// IoMode. The default value at the time of \ref sslContextCreateConnection is ::SslIoMode_Blocking.
146 /// 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.
147 typedef enum {
148  SslIoMode_Blocking = 1, ///< Blocking. Timeout = 5 minutes.
149  SslIoMode_NonBlocking = 2, ///< NonBlocking. Timeout = 0.
150 } SslIoMode;
151 
152 /// PollEvent
153 typedef enum {
154  SslPollEvent_Read = BIT(0), ///< Read
155  SslPollEvent_Write = BIT(1), ///< Write
156  SslPollEvent_Except = BIT(2), ///< Except
157 } SslPollEvent;
158 
159 /// SessionCacheMode
160 typedef enum {
161  SslSessionCacheMode_None = 0, ///< None
162  SslSessionCacheMode_SessionId = 1, ///< SessionId
163  SslSessionCacheMode_SessionTicket = 2, ///< SessionTicket
164 } SslSessionCacheMode;
165 
166 /// RenegotiationMode
167 typedef enum {
168  SslRenegotiationMode_None = 0, ///< None
169  SslRenegotiationMode_Secure = 1, ///< Secure
170 } SslRenegotiationMode;
171 
172 /// OptionType. The default bool flags value for these at the time of \ref sslContextCreateConnection is cleared.
173 typedef enum {
174  SslOptionType_DoNotCloseSocket = 0, ///< DoNotCloseSocket. See \ref sslConnectionSetSocketDescriptor. This is only available if \ref sslConnectionSetSocketDescriptor wasn't used yet.
175  SslOptionType_GetServerCertChain = 1, ///< [3.0.0+] GetServerCertChain. See \ref sslConnectionDoHandshake.
176  SslOptionType_SkipDefaultVerify = 2, ///< [5.0.0+] SkipDefaultVerify. Checked by \ref sslConnectionSetVerifyOption, see \ref SslVerifyOption.
177  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.
178 } SslOptionType;
179 
180 /// PrivateOptionType
181 typedef enum {
182  SslPrivateOptionType_DtlsSession = 1, ///< \ref sslConnectionSetSessionCacheMode will throw an error if the input ::SslSessionCacheMode is non-zero and this option flag is set.
183  SslPrivateOptionType_SetCipher = 2, ///< [17.0.0+] This exclusively enables the cipher suite specified in the input u32 value passed to \ref sslConnectionSetPrivateOption (all other ciphers disabled).
184 } SslPrivateOptionType;
185 
186 /// AlpnProtoState
187 typedef enum {
188  SslAlpnProtoState_NoSupport = 0, ///< NoSupport
189  SslAlpnProtoState_Negotiated = 1, ///< Negotiated
190  SslAlpnProtoState_NoOverlap = 2, ///< NoOverlap
191  SslAlpnProtoState_Selected = 3, ///< Selected
192  SslAlpnProtoState_EarlyValue = 4, ///< EarlyValue
193 } SslAlpnProtoState;
194 
195 /// SslContext
196 typedef struct {
197  Service s; ///< ISslContext
198 } SslContext;
199 
200 /// SslConnection
201 typedef struct {
202  Service s; ///< ISslConnection
203 } SslConnection;
204 
205 /// BuiltInCertificateInfo
206 typedef struct {
207  u32 cert_id; ///< \ref SslCaCertificateId
208  u32 status; ///< \ref SslTrustedCertStatus
209  u64 cert_size; ///< CertificateSize
210  u8 *cert_data; ///< CertificateData (converted from an offset to a ptr), in DER format.
212 
213 /// SslServerCertDetailHeader
214 typedef struct {
215  u64 magicnum; ///< Magicnum.
216  u32 cert_total; ///< Total certs.
217  u32 pad; ///< Padding.
219 
220 /// SslServerCertDetailEntry
221 typedef struct {
222  u32 size; ///< Size.
223  u32 offset; ///< Offset.
225 
226 /// CipherInfo
227 typedef struct {
228  char cipher[0x40]; ///< Cipher string.
229  char protocol_version[0x8]; ///< Protocol version string.
230 } SslCipherInfo;
231 
232 /// KeyAndCertParams
233 typedef struct {
234  u32 unk_x0; ///< Must be value 1.
235  s32 key_size; ///< Key size in bits.
236  u64 public_exponent; ///< Public exponent, must be non-zero. Only the low 4-bytes are used.
237  char common_name[0x40]; ///< CN (Common Name) NUL-terminated string.
238  u32 common_name_len; ///< Length of common_name excluding NUL-terminator. Must be 0x1-0x3F.
240 
241 /// Initialize ssl. A default value of 0x3 can be used for num_sessions. This must be 0x1-0x4.
242 Result sslInitialize(u32 num_sessions);
243 
244 /// Exit ssl.
245 void sslExit(void);
246 
247 /// Gets the Service object for the actual ssl service session.
248 Service* sslGetServiceSession(void);
249 
250 /**
251  * @brief CreateContext
252  * @note The CertStore is used automatically, regardless of what cmds are used.
253  * @param[out] c \ref SslContext
254  * @param[in] ssl_version \ref SslVersion
255  */
256 Result sslCreateContext(SslContext *c, u32 ssl_version);
257 
258 /**
259  * @brief GetContextCount
260  * @note Not used by official sw.
261  * @param[out] out Output value.
262  */
263 Result sslGetContextCount(u32 *out);
264 
265 /**
266  * @brief GetCertificates
267  * @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.
268  * @param[in] size Output buffer size, this should be the size from \ref sslGetCertificateBufSize.
269  * @param[in] ca_cert_ids Input array of \ref SslCaCertificateId.
270  * @param[in] count Size of the ca_cert_ids array in entries.
271  * @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.
272  */
273 Result sslGetCertificates(void* buffer, u32 size, u32 *ca_cert_ids, u32 count, u32 *total_out);
274 
275 /**
276  * @brief GetCertificateBufSize
277  * @param[in] ca_cert_ids Input array of \ref SslCaCertificateId.
278  * @param[in] count Size of the ca_cert_ids array in entries.
279  * @param[out] out Output size.
280  */
281 Result sslGetCertificateBufSize(u32 *ca_cert_ids, u32 count, u32 *out);
282 
283 /**
284  * @brief FlushSessionCache
285  * @note Only available on [5.0.0+].
286  * @param[in] str Input string. Must be NULL with ::SslFlushSessionCacheOptionType_AllHosts.
287  * @param[in] str_bufsize String buffer size, excluding NUL-terminator. Hence, this should be actual_bufsize-1. This must be 0 with ::SslFlushSessionCacheOptionType_AllHosts.
288  * @param[in] type \ref SslFlushSessionCacheOptionType
289  * @param[out] out Output value.
290  */
291 Result sslFlushSessionCache(const char *str, size_t str_bufsize, SslFlushSessionCacheOptionType type, u32 *out);
292 
293 /**
294  * @brief SetDebugOption
295  * @note Only available on [6.0.0+].
296  * @note The official impl of this doesn't actually use the cmd.
297  * @param[in] buffer Input buffer, must not be NULL. The u8 from here is copied to state.
298  * @param[in] size Buffer size, must not be 0.
299  * @param[in] type \ref SslDebugOptionType
300  */
301 Result sslSetDebugOption(const void* buffer, size_t size, SslDebugOptionType type);
302 
303 /**
304  * @brief GetDebugOption
305  * @note Only available on [6.0.0+].
306  * @param[out] buffer Output buffer, must not be NULL. An u8 is written here loaded from state.
307  * @param[in] size Buffer size, must not be 0.
308  * @param[in] type \ref SslDebugOptionType
309  */
310 Result sslGetDebugOption(void* buffer, size_t size, SslDebugOptionType type);
311 
312 /**
313  * @brief ClearTls12FallbackFlag
314  * @note Only available on [14.0.0+].
315  */
316 Result sslClearTls12FallbackFlag(void);
317 
318 /**
319  * @brief SetThreadCoreMask
320  * @param[in] mask CoreMask
321  * @note Only available on [15.0.0+] with ::SslServiceType_System.
322  */
323 Result sslSetThreadCoreMask(u64 mask);
324 
325 /**
326  * @brief GetThreadCoreMask
327  * @param[out] out Output CoreMask.
328  * @note Only available on [15.0.0+] with ::SslServiceType_System.
329  */
330 Result sslGetThreadCoreMask(u64 *out);
331 
332 ///@name ISslContext
333 ///@{
334 
335 /**
336  * @brief Closes a Context object.
337  * @param c \ref SslContext
338  */
339 void sslContextClose(SslContext *c);
340 
341 /**
342  * @brief SetOption
343  * @note Prior to 4.x this is stubbed.
344  * @param c \ref SslContext
345  * @param[in] option \ref SslContextOption
346  * @param[in] value Value to set. With ::SslContextOption_CrlImportDateCheckEnable, this must be 0 or 1.
347  */
348 Result sslContextSetOption(SslContext *c, SslContextOption option, s32 value);
349 
350 /**
351  * @brief GetOption
352  * @note Prior to 4.x this is stubbed.
353  * @param c \ref SslContext
354  * @param[in] option \ref SslContextOption
355  * @param[out] out Output value.
356  */
357 Result sslContextGetOption(SslContext *c, SslContextOption option, s32 *out);
358 
359 /**
360  * @brief CreateConnection
361  * @param c \ref SslContext
362  * @param[out] conn Output \ref SslConnection.
363  */
364 Result sslContextCreateConnection(SslContext *c, SslConnection *conn);
365 
366 /**
367  * @brief GetConnectionCount
368  * @note Not exposed by official sw.
369  * @param c \ref SslContext
370  * @param[out] out Output value.
371  */
372 Result sslContextGetConnectionCount(SslContext *c, u32 *out);
373 
374 /**
375  * @brief ImportServerPki
376  * @note A maximum of 71 ServerPki objects (associated with the output Id) can be imported.
377  * @param c \ref SslContext
378  * @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).
379  * @param[in] size Input buffer size.
380  * @param[in] format \ref SslCertificateFormat
381  * @param[out] id Output Id. Optional, can be NULL.
382  */
383 Result sslContextImportServerPki(SslContext *c, const void* buffer, u32 size, SslCertificateFormat format, u64 *id);
384 
385 /**
386  * @brief ImportClientPki
387  * @note An error is thrown internally if this cmd or \ref sslContextRegisterInternalPki was already used previously.
388  * @param c \ref SslContext
389  * @param[in] pkcs12 PKCS#12 input buffer, must not be NULL.
390  * @param[in] pkcs12_size pkcs12 buffer size.
391  * @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.
392  * @param[in] pw_size Password buffer size, this can only be 0 if pw is NULL.
393  * @param[out] id Output Id. Optional, can be NULL.
394  */
395 Result sslContextImportClientPki(SslContext *c, const void* pkcs12, u32 pkcs12_size, const char *pw, u32 pw_size, u64 *id);
396 
397 /**
398  * @brief Remove the specified *Pki, or on [3.0.0+] Crl.
399  * @param c \ref SslContext
400  * @param[in] id Id
401  */
402 Result sslContextRemovePki(SslContext *c, u64 id);
403 
404 /**
405  * @brief RegisterInternalPki
406  * @note An error is thrown internally if this cmd or \ref sslContextImportClientPki was already used previously.
407  * @param c \ref SslContext
408  * @param[in] internal_pki \ref SslInternalPki
409  * @param[out] id Output Id. Optional, can be NULL.
410  */
411 Result sslContextRegisterInternalPki(SslContext *c, SslInternalPki internal_pki, u64 *id);
412 
413 /**
414  * @brief AddPolicyOid
415  * @param c \ref SslContext
416  * @param[in] str Input string.
417  * @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.
418  */
419 Result sslContextAddPolicyOid(SslContext *c, const char *str, u32 str_bufsize);
420 
421 /**
422  * @brief ImportCrl
423  * @note Only available on [3.0.0+].
424  * @param c \ref SslContext
425  * @param[in] buffer Input buffer, must not be NULL. This contains the DER CRL.
426  * @param[in] size Input buffer size.
427  * @param[out] id Output Id. Optional, can be NULL.
428  */
429 Result sslContextImportCrl(SslContext *c, const void* buffer, u32 size, u64 *id);
430 
431 /**
432  * @brief ImportClientCertKeyPki
433  * @note Only available on [16.0.0+].
434  * @param c \ref SslContext
435  * @param[in] cert Input cert buffer,
436  * @param[in] cert_size Size of the cert buffer.
437  * @param[in] key Input key buffer.
438  * @param[in] key_size Size of the key buffer.
439  * @param[in] format \ref SslCertificateFormat for the cert and key.
440  * @param[out] id Output Id. Optional, can be NULL.
441  */
442 Result sslContextImportClientCertKeyPki(SslContext *c, const void* cert, u32 cert_size, const void* key, u32 key_size, SslCertificateFormat format, u64 *id);
443 
444 /**
445  * @brief GeneratePrivateKeyAndCert
446  * @note Only available on [16.0.0+].
447  * @param c \ref SslContext
448  * @param[out] cert Output cert buffer,
449  * @param[in] cert_size Size of the cert buffer.
450  * @param[out] key Output key buffer.
451  * @param[in] key_size Size of the key buffer.
452  * @param[in] val Must be value 1.
453  * @param[in] params \ref SslKeyAndCertParams
454  * @param[out] out_certsize Actual size of the generated cert data.
455  * @param[out] out_keysize Actual size of the generated key data.
456  */
457 Result sslContextGeneratePrivateKeyAndCert(SslContext *c, void* cert, u32 cert_size, void* key, u32 key_size, u32 val, const SslKeyAndCertParams *params, u32 *out_certsize, u32 *out_keysize);
458 
459 /**
460  * @brief CreateConnectionForSystem
461  * @note Only available on [15.0.0+] with ::SslServiceType_System.
462  * @param c \ref SslContext
463  * @param[out] conn Output \ref SslConnection.
464  */
465 Result sslContextCreateConnectionForSystem(SslContext *c, SslConnection *conn);
466 
467 ///@}
468 
469 ///@name ISslConnection
470 ///@{
471 
472 /**
473  * @brief Closes a Connection object.
474  * @param c \ref SslConnection
475  */
476 void sslConnectionClose(SslConnection *c);
477 
478 /**
479  * @brief SetSocketDescriptor. Do not use directly, use \ref socketSslConnectionSetSocketDescriptor instead.
480  * @note An error is thrown if this was used previously.
481  * @param c \ref SslConnection
482  * @param[in] sockfd sockfd
483  * @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).
484  */
485 Result sslConnectionSetSocketDescriptor(SslConnection *c, int sockfd, int *out_sockfd);
486 
487 /**
488  * @brief SetHostName
489  * @param c \ref SslConnection
490  * @param[in] str Input string.
491  * @param[in] str_bufsize String buffer size. This must not be >0xff.
492  */
493 Result sslConnectionSetHostName(SslConnection *c, const char* str, u32 str_bufsize);
494 
495 /**
496  * @brief SetVerifyOption
497  * @param c \ref SslConnection
498  * @param[in] verify_option Input bitmask of \ref SslVerifyOption.
499  */
500 Result sslConnectionSetVerifyOption(SslConnection *c, u32 verify_option);
501 
502 /**
503  * @brief SetIoMode
504  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
505  * @param c \ref SslConnection
506  * @param[in] mode \ref SslIoMode
507  */
508 Result sslConnectionSetIoMode(SslConnection *c, SslIoMode mode);
509 
510 /**
511  * @brief GetSocketDescriptor. Do not use directly, use \ref socketSslConnectionGetSocketDescriptor instead.
512  * @note This gets the input sockfd which was previously saved in state by \ref sslConnectionSetSocketDescriptor.
513  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
514  * @param c \ref SslConnection
515  * @param[out] sockfd Output sockfd.
516  */
517 Result sslConnectionGetSocketDescriptor(SslConnection *c, int *sockfd);
518 
519 /**
520  * @brief GetHostName
521  * @param c \ref SslConnection
522  * @param[out] str Output string buffer.
523  * @param[in] str_bufsize String buffer size, must be large enough for the entire output string.
524  * @param[out] out Output string length.
525  */
526 Result sslConnectionGetHostName(SslConnection *c, char *str, u32 str_bufsize, u32 *out);
527 
528 /**
529  * @brief GetVerifyOption
530  * @param c \ref SslConnection
531  * @param[out] out Output bitmask of \ref SslVerifyOption.
532  */
533 Result sslConnectionGetVerifyOption(SslConnection *c, u32 *out);
534 
535 /**
536  * @brief GetIoMode
537  * @param c \ref SslConnection
538  * @param[out] out \ref SslIoMode
539  */
540 Result sslConnectionGetIoMode(SslConnection *c, SslIoMode *out);
541 
542 /**
543  * @brief DoHandshake
544  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
545  * @note \ref sslConnectionSetHostName must have been used previously with a non-empty string when ::SslVerifyOption_HostName is set.
546  * @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).
547  * @note No certs are returned when ::SslVerifyOption_PeerCa is not set.
548  * @param c \ref SslConnection
549  * @param[out] out_size Total data size which was written to server_certbuf. Optional, can be NULL.
550  * @param[out] total_certs Total certs which were written to server_certbuf, can be NULL.
551  * @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.
552  * @param[in] server_certbuf_size Optional output server cert buffer size, can be 0.
553  */
554 Result sslConnectionDoHandshake(SslConnection *c, u32 *out_size, u32 *total_certs, void* server_certbuf, u32 server_certbuf_size);
555 
556 /**
557  * @brief Parses the output server_certbuf from \ref sslConnectionDoHandshake where ::SslOptionType_GetServerCertChain is set.
558  * @param[in] certbuf server_certbuf from \ref sslConnectionDoHandshake, must not be NULL.
559  * @param[in] certbuf_size out_size from \ref sslConnectionDoHandshake.
560  * @param[in] cert_index Cert index, must be within the range of certs stored in certbuf.
561  * @param[out] cert Ptr for the ouput DER cert, must not be NULL.
562  * @param[out] cert_size Size for the ouput cert, must not be NULL.
563  */
564 Result sslConnectionGetServerCertDetail(const void* certbuf, u32 certbuf_size, u32 cert_index, void** cert, u32 *cert_size);
565 
566 /**
567  * @brief Read
568  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
569  * @param c \ref SslConnection
570  * @param[out] buffer Output buffer, must not be NULL.
571  * @param[in] size Output buffer size, must not be 0.
572  * @param[out] out_size Actual transferred size.
573  */
574 Result sslConnectionRead(SslConnection *c, void* buffer, u32 size, u32 *out_size);
575 
576 /**
577  * @brief Write
578  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
579  * @param c \ref SslConnection
580  * @param[in] buffer Input buffer, must not be NULL.
581  * @param[in] size Input buffer size, must not be 0.
582  * @param[out] out_size Actual transferred size.
583  */
584 Result sslConnectionWrite(SslConnection *c, const void* buffer, u32 size, u32 *out_size);
585 
586 /**
587  * @brief Pending
588  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
589  * @param c \ref SslConnection
590  * @param[out] out Output value.
591  */
592 Result sslConnectionPending(SslConnection *c, s32 *out);
593 
594 /**
595  * @brief Peek
596  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
597  * @param c \ref SslConnection
598  * @param[out] buffer Output buffer, must not be NULL.
599  * @param[in] size Output buffer size, must not be 0.
600  * @param[out] out_size Output size.
601  */
602 Result sslConnectionPeek(SslConnection *c, void* buffer, u32 size, u32 *out_size);
603 
604 /**
605  * @brief Poll
606  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
607  * @param c \ref SslConnection
608  * @param[in] in_pollevent Input bitmask of \ref SslPollEvent.
609  * @param[out] out_pollevent Output bitmask of \ref SslPollEvent.
610  * @param[in] timeout Timeout in milliseconds.
611  */
612 Result sslConnectionPoll(SslConnection *c, u32 in_pollevent, u32 *out_pollevent, u32 timeout);
613 
614 /**
615  * @brief GetVerifyCertError
616  * @note The value in state is cleared after loading it.
617  * @param c \ref SslConnection
618  */
619 Result sslConnectionGetVerifyCertError(SslConnection *c);
620 
621 /**
622  * @brief GetNeededServerCertBufferSize
623  * @param c \ref SslConnection
624  * @param[out] out Output value.
625  */
626 Result sslConnectionGetNeededServerCertBufferSize(SslConnection *c, u32 *out);
627 
628 /**
629  * @brief SetSessionCacheMode
630  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
631  * @param c \ref SslConnection
632  * @param[in] mode \ref SslSessionCacheMode
633  */
634 Result sslConnectionSetSessionCacheMode(SslConnection *c, SslSessionCacheMode mode);
635 
636 /**
637  * @brief GetSessionCacheMode
638  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
639  * @param c \ref SslConnection
640  * @param[out] out \ref SslSessionCacheMode
641  */
642 Result sslConnectionGetSessionCacheMode(SslConnection *c, SslSessionCacheMode *out);
643 
644 /**
645  * @brief GetSessionCacheMode
646  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
647  * @param c \ref SslConnection
648  */
649 Result sslConnectionFlushSessionCache(SslConnection *c);
650 
651 /**
652  * @brief SetRenegotiationMode
653  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
654  * @param c \ref SslConnection
655  * @param[in] mode \ref SslRenegotiationMode
656  */
657 Result sslConnectionSetRenegotiationMode(SslConnection *c, SslRenegotiationMode mode);
658 
659 /**
660  * @brief GetRenegotiationMode
661  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
662  * @param c \ref SslConnection
663  * @param[out] out \ref SslRenegotiationMode
664  */
665 Result sslConnectionGetRenegotiationMode(SslConnection *c, SslRenegotiationMode *out);
666 
667 /**
668  * @brief SetOption
669  * @param c \ref SslConnection
670  * @param[in] option \ref SslOptionType
671  * @param[in] flag Input flag value.
672  */
673 Result sslConnectionSetOption(SslConnection *c, SslOptionType option, bool flag);
674 
675 /**
676  * @brief GetOption
677  * @param c \ref SslConnection
678  * @param[in] option \ref SslOptionType
679  * @param[out] out Output flag value.
680  */
681 Result sslConnectionGetOption(SslConnection *c, SslOptionType option, bool *out);
682 
683 /**
684  * @brief GetVerifyCertErrors
685  * @note An error is thrown when the cmd is successful, if the two output u32s match.
686  * @param[out] out0 First output value, must not be NULL.
687  * @param[out] out1 Second output value.
688  * @param[out] errors Output array of Result, must not be NULL.
689  * @param[in] count Size of the errors array in entries.
690  */
691 Result sslConnectionGetVerifyCertErrors(SslConnection *c, u32 *out0, u32 *out1, Result *errors, u32 count);
692 
693 /**
694  * @brief GetCipherInfo
695  * @note Only available on [4.0.0+].
696  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
697  * @param c \ref SslConnection
698  * @param[out] out \ref SslCipherInfo
699  */
700 Result sslConnectionGetCipherInfo(SslConnection *c, SslCipherInfo *out);
701 
702 /**
703  * @brief SetNextAlpnProto
704  * @note Only available on [9.0.0+].
705  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
706  * @note ::SslOptionType_EnableAlpn should be set at the time of using \ref sslConnectionDoHandshake, otherwise using this cmd will have no affect.
707  * @param c \ref SslConnection
708  * @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.
709  * @param[in] size Input buffer size, must not be 0. Must be at least 0x2.
710  */
711 Result sslConnectionSetNextAlpnProto(SslConnection *c, const u8 *buffer, u32 size);
712 
713 /**
714  * @brief GetNextAlpnProto
715  * @note Only available on [9.0.0+].
716  * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully.
717  * @note The output will be all-zero/empty if not available - such as when this was used before \ref sslConnectionDoHandshake.
718  * @param c \ref SslConnection
719  * @param[out] state \ref SslAlpnProtoState
720  * @param[out] out Output string length.
721  * @param[out] buffer Output string buffer, must not be NULL.
722  * @param[in] size Output buffer size, must not be 0.
723  */
724 Result sslConnectionGetNextAlpnProto(SslConnection *c, SslAlpnProtoState *state, u32 *out, u8 *buffer, u32 size);
725 
726 /**
727  * @brief SetDtlsSocketDescriptor. Do not use directly, use \ref socketSslConnectionSetDtlsSocketDescriptor instead.
728  * @note Only available on [16.0.0+].
729  * @note An error is thrown if this was used previously.
730  * @param c \ref SslConnection
731  * @param[in] sockfd sockfd
732  * @param[in] Input sockaddr.
733  * @param[in] size Input sockaddr size.
734  * @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).
735  */
736 Result sslConnectionSetDtlsSocketDescriptor(SslConnection *c, int sockfd, const void* buf, size_t size, int *out_sockfd);
737 
738 /**
739  * @brief GetDtlsHandshakeTimeout
740  * @note Only available on [16.0.0+].
741  * @param c \ref SslConnection
742  * @param[out] out Output nanoseconds value.
743  */
744 Result sslConnectionGetDtlsHandshakeTimeout(SslConnection *c, u64 *out);
745 
746 /**
747  * @brief SetPrivateOption
748  * @note Only available on [16.0.0+].
749  * @param c \ref SslConnection
750  * @param[in] option \ref SslPrivateOptionType
751  * @param[in] value Input value.
752  */
753 Result sslConnectionSetPrivateOption(SslConnection *c, SslPrivateOptionType option, u32 value);
754 
755 /**
756  * @brief SetSrtpCiphers
757  * @note Only available on [16.0.0+].
758  * @param c \ref SslConnection
759  * @param[in] ciphers Input array of u16s. Each entry must be value 1-2, otherwise the entry is ignored.
760  * @param[in] count Total entries in the ciphers array, the maximum is 4.
761  */
762 Result sslConnectionSetSrtpCiphers(SslConnection *c, const u16 *ciphers, u32 count);
763 
764 /**
765  * @brief GetSrtpCipher
766  * @note Only available on [16.0.0+].
767  * @param c \ref SslConnection
768  * @param[out] out Output value.
769  */
770 Result sslConnectionGetSrtpCipher(SslConnection *c, u16 *out);
771 
772 /**
773  * @brief ExportKeyingMaterial
774  * @note Only available on [16.0.0+].
775  * @param c \ref SslConnection
776  * @param[out] outbuf Output buffer.
777  * @param[in] outbuf_size Output buffer size.
778  * @param[in] label Input label string.
779  * @param[in] label_size Size of the label buffer excluding NUL-terminator.
780  * @param[in] context Optional input context buffer, can be NULL.
781  * @param[in] context_size Size of context, if specified this must be <0xFFFF.
782  */
783 Result sslConnectionExportKeyingMaterial(SslConnection *c, u8 *outbuf, u32 outbuf_size, const char *label, u32 label_size, const void* context, u32 context_size);
784 
785 /**
786  * @brief SetIoTimeout
787  * @note Only available on [16.0.0+].
788  * @param c \ref SslConnection
789  * @param[in] timeout Input timeout value.
790  */
791 Result sslConnectionSetIoTimeout(SslConnection *c, u32 timeout);
792 
793 /**
794  * @brief GetIoTimeout
795  * @note Only available on [16.0.0+].
796  * @param c \ref SslConnection
797  * @param[out] out Output timeout value.
798  */
799 Result sslConnectionGetIoTimeout(SslConnection *c, u32 *out);
800 
801 ///@}
802 
Service object structure.
Definition: service.h:14
BuiltInCertificateInfo.
Definition: ssl.h:206
u32 status
SslTrustedCertStatus
Definition: ssl.h:208
u8 * cert_data
CertificateData (converted from an offset to a ptr), in DER format.
Definition: ssl.h:210
u64 cert_size
CertificateSize.
Definition: ssl.h:209
u32 cert_id
SslCaCertificateId
Definition: ssl.h:207
CipherInfo.
Definition: ssl.h:227
SslConnection.
Definition: ssl.h:201
Service s
ISslConnection.
Definition: ssl.h:202
SslContext.
Definition: ssl.h:196
Service s
ISslContext.
Definition: ssl.h:197
KeyAndCertParams.
Definition: ssl.h:233
u32 common_name_len
Length of common_name excluding NUL-terminator. Must be 0x1-0x3F.
Definition: ssl.h:238
u64 public_exponent
Public exponent, must be non-zero. Only the low 4-bytes are used.
Definition: ssl.h:236
u32 unk_x0
Must be value 1.
Definition: ssl.h:234
s32 key_size
Key size in bits.
Definition: ssl.h:235
SslServerCertDetailEntry.
Definition: ssl.h:221
u32 offset
Offset.
Definition: ssl.h:223
u32 size
Size.
Definition: ssl.h:222
SslServerCertDetailHeader.
Definition: ssl.h:214
u32 cert_total
Total certs.
Definition: ssl.h:216
u32 pad
Padding.
Definition: ssl.h:217
u64 magicnum
Magicnum.
Definition: ssl.h:215
#define BIT(n)
Creates a bitmask from a bit number.
Definition: types.h:54
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
uint16_t u16
16-bit unsigned integer.
Definition: types.h:20
u32 Result
Function error code result type.
Definition: types.h:44
int32_t s32
32-bit signed integer.
Definition: types.h:27
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21