/** * @file fs.h * @brief SSL service IPC wrapper, for using client-mode TLS. See also: https://switchbrew.org/wiki/SSL_services * @author yellows8 * @copyright libnx Authors */ #pragma once #include "../types.h" #include "../sf/service.h" /// Values for __nx_ssl_service_type, controls which ssl service to initialize. typedef enum { SslServiceType_Default = 0, ///< Initialize the ssl service. SslServiceType_System = 1, ///< [15.0.0+] Initialize the ssl:s service. On older versions this is the same as ::SslServiceType_Default. } SslServiceType; /// CaCertificateId typedef enum { SslCaCertificateId_All = -1, ///< [3.0.0+] All SslCaCertificateId_NintendoCAG3 = 1, ///< NintendoCAG3 SslCaCertificateId_NintendoClass2CAG3 = 2, ///< NintendoClass2CAG3 SslCaCertificateId_NintendoRootCAG4 = 3, ///< [16.0.0+] "Nintendo Root CA G4" SslCaCertificateId_AmazonRootCA1 = 1000, ///< AmazonRootCA1 SslCaCertificateId_StarfieldServicesRootCertificateAuthorityG2 = 1001, ///< StarfieldServicesRootCertificateAuthorityG2 SslCaCertificateId_AddTrustExternalCARoot = 1002, ///< AddTrustExternalCARoot SslCaCertificateId_COMODOCertificationAuthority = 1003, ///< COMODOCertificationAuthority SslCaCertificateId_UTNDATACorpSGC = 1004, ///< UTNDATACorpSGC SslCaCertificateId_UTNUSERFirstHardware = 1005, ///< UTNUSERFirstHardware SslCaCertificateId_BaltimoreCyberTrustRoot = 1006, ///< BaltimoreCyberTrustRoot SslCaCertificateId_CybertrustGlobalRoot = 1007, ///< CybertrustGlobalRoot SslCaCertificateId_VerizonGlobalRootCA = 1008, ///< VerizonGlobalRootCA SslCaCertificateId_DigiCertAssuredIDRootCA = 1009, ///< DigiCertAssuredIDRootCA SslCaCertificateId_DigiCertAssuredIDRootG2 = 1010, ///< DigiCertAssuredIDRootG2 SslCaCertificateId_DigiCertGlobalRootCA = 1011, ///< DigiCertGlobalRootCA SslCaCertificateId_DigiCertGlobalRootG2 = 1012, ///< DigiCertGlobalRootG2 SslCaCertificateId_DigiCertHighAssuranceEVRootCA = 1013, ///< DigiCertHighAssuranceEVRootCA SslCaCertificateId_EntrustnetCertificationAuthority2048 = 1014, ///< EntrustnetCertificationAuthority2048 SslCaCertificateId_EntrustRootCertificationAuthority = 1015, ///< EntrustRootCertificationAuthority SslCaCertificateId_EntrustRootCertificationAuthorityG2 = 1016, ///< EntrustRootCertificationAuthorityG2 SslCaCertificateId_GeoTrustGlobalCA2 = 1017, ///< GeoTrustGlobalCA2 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_GeoTrustGlobalCA = 1018, ///< GeoTrustGlobalCA ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_GeoTrustPrimaryCertificationAuthorityG3 = 1019, ///< GeoTrustPrimaryCertificationAuthorityG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_GeoTrustPrimaryCertificationAuthority = 1020, ///< GeoTrustPrimaryCertificationAuthority ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_GlobalSignRootCA = 1021, ///< GlobalSignRootCA SslCaCertificateId_GlobalSignRootCAR2 = 1022, ///< GlobalSignRootCAR2 SslCaCertificateId_GlobalSignRootCAR3 = 1023, ///< GlobalSignRootCAR3 SslCaCertificateId_GoDaddyClass2CertificationAuthority = 1024, ///< GoDaddyClass2CertificationAuthority SslCaCertificateId_GoDaddyRootCertificateAuthorityG2 = 1025, ///< GoDaddyRootCertificateAuthorityG2 SslCaCertificateId_StarfieldClass2CertificationAuthority = 1026, ///< StarfieldClass2CertificationAuthority SslCaCertificateId_StarfieldRootCertificateAuthorityG2 = 1027, ///< StarfieldRootCertificateAuthorityG2 SslCaCertificateId_thawtePrimaryRootCAG3 = 1028, ///< thawtePrimaryRootCAG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_thawtePrimaryRootCA = 1029, ///< thawtePrimaryRootCA ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_VeriSignClass3PublicPrimaryCertificationAuthorityG3 = 1030, ///< VeriSignClass3PublicPrimaryCertificationAuthorityG3 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_VeriSignClass3PublicPrimaryCertificationAuthorityG5 = 1031, ///< VeriSignClass3PublicPrimaryCertificationAuthorityG5 ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_VeriSignUniversalRootCertificationAuthority = 1032, ///< VeriSignUniversalRootCertificationAuthority ([8.0.0+] ::SslTrustedCertStatus is ::SslTrustedCertStatus_EnabledNotTrusted) SslCaCertificateId_DSTRootCAX3 = 1033, ///< [6.0.0+] DSTRootCAX3 SslCaCertificateId_USERTrustRsaCertificationAuthority = 1034, ///< [10.0.3+] "USERTrust RSA Certification Authority" SslCaCertificateId_ISRGRootX10 = 1035, ///< [10.1.0+] "ISRG Root X10" SslCaCertificateId_USERTrustEccCertificationAuthority = 1036, ///< [10.1.0+] "USERTrust ECC Certification Authority" SslCaCertificateId_COMODORsaCertificationAuthority = 1037, ///< [10.1.0+] "COMODO RSA Certification Authority" SslCaCertificateId_COMODOEccCertificationAuthority = 1038, ///< [10.1.0+] "COMODO ECC Certification Authority" SslCaCertificateId_AmazonRootCA2 = 1039, ///< [11.0.0+] "Amazon Root CA 2" SslCaCertificateId_AmazonRootCA3 = 1040, ///< [11.0.0+] "Amazon Root CA 3" SslCaCertificateId_AmazonRootCA4 = 1041, ///< [11.0.0+] "Amazon Root CA 4" SslCaCertificateId_DigiCertAssuredIDRootG3 = 1042, ///< [11.0.0+] "DigiCert Assured ID Root G3" SslCaCertificateId_DigiCertGlobalRootG3 = 1043, ///< [11.0.0+] "DigiCert Global Root G3" SslCaCertificateId_DigiCertTrustedRootG4 = 1044, ///< [11.0.0+] "DigiCert Trusted Root G4" SslCaCertificateId_EntrustRootCertificationAuthorityEC1 = 1045, ///< [11.0.0+] "Entrust Root Certification Authority - EC1" SslCaCertificateId_EntrustRootCertificationAuthorityG4 = 1046, ///< [11.0.0+] "Entrust Root Certification Authority - G4" SslCaCertificateId_GlobalSignECCRootCAR4 = 1047, ///< [11.0.0+] "GlobalSign ECC Root CA - R4" SslCaCertificateId_GlobalSignECCRootCAR5 = 1048, ///< [11.0.0+] "GlobalSign ECC Root CA - R5" SslCaCertificateId_GlobalSignECCRootCAR6 = 1049, ///< [11.0.0+] "GlobalSign ECC Root CA - R6" SslCaCertificateId_GTSRootR1 = 1050, ///< [11.0.0+] "GTS Root R1" SslCaCertificateId_GTSRootR2 = 1051, ///< [11.0.0+] "GTS Root R2" SslCaCertificateId_GTSRootR3 = 1052, ///< [11.0.0+] "GTS Root R3" SslCaCertificateId_GTSRootR4 = 1053, ///< [11.0.0+] "GTS Root R4" SslCaCertificateId_SecurityCommunicationRootCA = 1054, ///< [12.0.0+] "Security Communication RootCA" SslCaCertificateId_GlobalSignRootE4 = 1055, ///< [15.0.0+] "GlobalSign Root E4" SslCaCertificateId_GlobalSignRootR4 = 1056, ///< [15.0.0+] "GlobalSign Root R4" SslCaCertificateId_TTeleSecGlobalRootClass2 = 1057, ///< [15.0.0+] "T-TeleSec GlobalRoot Class 2" SslCaCertificateId_DigiCertTLSECCP384RootG5 = 1058, ///< [16.0.0+] "DigiCert TLS ECC P384 Root G5" SslCaCertificateId_DigiCertTLSRSA4096RootG5 = 1059, ///< [16.0.0+] "DigiCert TLS RSA4096 Root G5" } SslCaCertificateId; /// TrustedCertStatus typedef enum { SslTrustedCertStatus_Invalid = -1, ///< Invalid SslTrustedCertStatus_Removed = 0, ///< Removed SslTrustedCertStatus_EnabledTrusted = 1, ///< EnabledTrusted SslTrustedCertStatus_EnabledNotTrusted = 2, ///< EnabledNotTrusted SslTrustedCertStatus_Revoked = 3, ///< Revoked } SslTrustedCertStatus; /// FlushSessionCacheOptionType typedef enum { SslFlushSessionCacheOptionType_SingleHost = 0, ///< SingleHost. Uses the input string. SslFlushSessionCacheOptionType_AllHosts = 1, ///< AllHosts. Doesn't use the input string. } SslFlushSessionCacheOptionType; /// DebugOptionType typedef enum { SslDebugOptionType_AllowDisableVerifyOption = 0, ///< AllowDisableVerifyOption } SslDebugOptionType; /// 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). typedef enum { SslVersion_Auto = BIT(0), ///< TLS version min = 1.0, max = 1.2. SslVersion_TlsV10 = BIT(3), ///< TLS 1.0. SslVersion_TlsV11 = BIT(4), ///< TLS 1.1. SslVersion_TlsV12 = BIT(5), ///< TLS 1.2. SslVersion_TlsV13 = BIT(6), ///< [11.0.0+] TLS 1.3. SslVersion_Auto24 = BIT(24), ///< [11.0.0+] Same as Auto. } SslVersion; /// CertificateFormat typedef enum { SslCertificateFormat_Pem = 1, ///< Pem SslCertificateFormat_Der = 2, ///< Der } SslCertificateFormat; /// InternalPki typedef enum { SslInternalPki_DeviceClientCertDefault = 1, ///< DeviceClientCertDefault. Enables using the DeviceCert. } SslInternalPki; /// ContextOption typedef enum { SslContextOption_CrlImportDateCheckEnable = 1, ///< CrlImportDateCheckEnable. The default value at the time of \ref sslCreateContext is value 1. } SslContextOption; /// VerifyOption. The default bitmask value at the time of \ref sslContextCreateConnection is ::SslVerifyOption_PeerCa | ::SslVerifyOption_HostName. /// [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. /// [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. typedef enum { SslVerifyOption_PeerCa = BIT(0), ///< PeerCa SslVerifyOption_HostName = BIT(1), ///< HostName SslVerifyOption_DateCheck = BIT(2), ///< DateCheck SslVerifyOption_EvCertPartial = BIT(3), ///< EvCertPartial SslVerifyOption_EvPolicyOid = BIT(4), ///< [6.0.0+] EvPolicyOid SslVerifyOption_EvCertFingerprint = BIT(5), ///< [6.0.0+] EvCertFingerprint } SslVerifyOption; /// IoMode. The default value at the time of \ref sslContextCreateConnection is ::SslIoMode_Blocking. /// 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. typedef enum { SslIoMode_Blocking = 1, ///< Blocking. Timeout = 5 minutes. SslIoMode_NonBlocking = 2, ///< NonBlocking. Timeout = 0. } SslIoMode; /// PollEvent typedef enum { SslPollEvent_Read = BIT(0), ///< Read SslPollEvent_Write = BIT(1), ///< Write SslPollEvent_Except = BIT(2), ///< Except } SslPollEvent; /// SessionCacheMode typedef enum { SslSessionCacheMode_None = 0, ///< None SslSessionCacheMode_SessionId = 1, ///< SessionId SslSessionCacheMode_SessionTicket = 2, ///< SessionTicket } SslSessionCacheMode; /// RenegotiationMode typedef enum { SslRenegotiationMode_None = 0, ///< None SslRenegotiationMode_Secure = 1, ///< Secure } SslRenegotiationMode; /// OptionType. The default bool flags value for these at the time of \ref sslContextCreateConnection is cleared. typedef enum { SslOptionType_DoNotCloseSocket = 0, ///< DoNotCloseSocket. See \ref sslConnectionSetSocketDescriptor. This is only available if \ref sslConnectionSetSocketDescriptor wasn't used yet. SslOptionType_GetServerCertChain = 1, ///< [3.0.0+] GetServerCertChain. See \ref sslConnectionDoHandshake. SslOptionType_SkipDefaultVerify = 2, ///< [5.0.0+] SkipDefaultVerify. Checked by \ref sslConnectionSetVerifyOption, see \ref SslVerifyOption. 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. } SslOptionType; /// PrivateOptionType typedef enum { SslPrivateOptionType_DtlsSession = 1, ///< \ref sslConnectionSetSessionCacheMode will throw an error if the input ::SslSessionCacheMode is non-zero and this option flag is set. 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). } SslPrivateOptionType; /// AlpnProtoState typedef enum { SslAlpnProtoState_NoSupport = 0, ///< NoSupport SslAlpnProtoState_Negotiated = 1, ///< Negotiated SslAlpnProtoState_NoOverlap = 2, ///< NoOverlap SslAlpnProtoState_Selected = 3, ///< Selected SslAlpnProtoState_EarlyValue = 4, ///< EarlyValue } SslAlpnProtoState; /// SslContext typedef struct { Service s; ///< ISslContext } SslContext; /// SslConnection typedef struct { Service s; ///< ISslConnection } SslConnection; /// BuiltInCertificateInfo typedef struct { u32 cert_id; ///< \ref SslCaCertificateId u32 status; ///< \ref SslTrustedCertStatus u64 cert_size; ///< CertificateSize u8 *cert_data; ///< CertificateData (converted from an offset to a ptr), in DER format. } SslBuiltInCertificateInfo; /// SslServerCertDetailHeader typedef struct { u64 magicnum; ///< Magicnum. u32 cert_total; ///< Total certs. u32 pad; ///< Padding. } SslServerCertDetailHeader; /// SslServerCertDetailEntry typedef struct { u32 size; ///< Size. u32 offset; ///< Offset. } SslServerCertDetailEntry; /// CipherInfo typedef struct { char cipher[0x40]; ///< Cipher string. char protocol_version[0x8]; ///< Protocol version string. } SslCipherInfo; /// KeyAndCertParams typedef struct { u32 unk_x0; ///< Must be value 1. s32 key_size; ///< Key size in bits. u64 public_exponent; ///< Public exponent, must be non-zero. Only the low 4-bytes are used. char common_name[0x40]; ///< CN (Common Name) NUL-terminated string. u32 common_name_len; ///< Length of common_name excluding NUL-terminator. Must be 0x1-0x3F. } SslKeyAndCertParams; /// Initialize ssl. A default value of 0x3 can be used for num_sessions. This must be 0x1-0x4. Result sslInitialize(u32 num_sessions); /// Exit ssl. void sslExit(void); /// Gets the Service object for the actual ssl service session. Service* sslGetServiceSession(void); /** * @brief CreateContext * @note The CertStore is used automatically, regardless of what cmds are used. * @param[out] c \ref SslContext * @param[in] ssl_version \ref SslVersion */ Result sslCreateContext(SslContext *c, u32 ssl_version); /** * @brief GetContextCount * @note Not used by official sw. * @param[out] out Output value. */ Result sslGetContextCount(u32 *out); /** * @brief GetCertificates * @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. * @param[in] size Output buffer size, this should be the size from \ref sslGetCertificateBufSize. * @param[in] ca_cert_ids Input array of \ref SslCaCertificateId. * @param[in] count Size of the ca_cert_ids array in entries. * @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. */ Result sslGetCertificates(void* buffer, u32 size, u32 *ca_cert_ids, u32 count, u32 *total_out); /** * @brief GetCertificateBufSize * @param[in] ca_cert_ids Input array of \ref SslCaCertificateId. * @param[in] count Size of the ca_cert_ids array in entries. * @param[out] out Output size. */ Result sslGetCertificateBufSize(u32 *ca_cert_ids, u32 count, u32 *out); /** * @brief FlushSessionCache * @note Only available on [5.0.0+]. * @param[in] str Input string. Must be NULL with ::SslFlushSessionCacheOptionType_AllHosts. * @param[in] str_bufsize String buffer size, excluding NUL-terminator. Hence, this should be actual_bufsize-1. This must be 0 with ::SslFlushSessionCacheOptionType_AllHosts. * @param[in] type \ref SslFlushSessionCacheOptionType * @param[out] out Output value. */ Result sslFlushSessionCache(const char *str, size_t str_bufsize, SslFlushSessionCacheOptionType type, u32 *out); /** * @brief SetDebugOption * @note Only available on [6.0.0+]. * @note The official impl of this doesn't actually use the cmd. * @param[in] buffer Input buffer, must not be NULL. The u8 from here is copied to state. * @param[in] size Buffer size, must not be 0. * @param[in] type \ref SslDebugOptionType */ Result sslSetDebugOption(const void* buffer, size_t size, SslDebugOptionType type); /** * @brief GetDebugOption * @note Only available on [6.0.0+]. * @param[out] buffer Output buffer, must not be NULL. An u8 is written here loaded from state. * @param[in] size Buffer size, must not be 0. * @param[in] type \ref SslDebugOptionType */ Result sslGetDebugOption(void* buffer, size_t size, SslDebugOptionType type); /** * @brief ClearTls12FallbackFlag * @note Only available on [14.0.0+]. */ Result sslClearTls12FallbackFlag(void); /** * @brief SetThreadCoreMask * @param[in] mask CoreMask * @note Only available on [15.0.0+] with ::SslServiceType_System. */ Result sslSetThreadCoreMask(u64 mask); /** * @brief GetThreadCoreMask * @param[out] out Output CoreMask. * @note Only available on [15.0.0+] with ::SslServiceType_System. */ Result sslGetThreadCoreMask(u64 *out); ///@name ISslContext ///@{ /** * @brief Closes a Context object. * @param c \ref SslContext */ void sslContextClose(SslContext *c); /** * @brief SetOption * @note Prior to 4.x this is stubbed. * @param c \ref SslContext * @param[in] option \ref SslContextOption * @param[in] value Value to set. With ::SslContextOption_CrlImportDateCheckEnable, this must be 0 or 1. */ Result sslContextSetOption(SslContext *c, SslContextOption option, s32 value); /** * @brief GetOption * @note Prior to 4.x this is stubbed. * @param c \ref SslContext * @param[in] option \ref SslContextOption * @param[out] out Output value. */ Result sslContextGetOption(SslContext *c, SslContextOption option, s32 *out); /** * @brief CreateConnection * @param c \ref SslContext * @param[out] conn Output \ref SslConnection. */ Result sslContextCreateConnection(SslContext *c, SslConnection *conn); /** * @brief GetConnectionCount * @note Not exposed by official sw. * @param c \ref SslContext * @param[out] out Output value. */ Result sslContextGetConnectionCount(SslContext *c, u32 *out); /** * @brief ImportServerPki * @note A maximum of 71 ServerPki objects (associated with the output Id) can be imported. * @param c \ref SslContext * @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). * @param[in] size Input buffer size. * @param[in] format \ref SslCertificateFormat * @param[out] id Output Id. Optional, can be NULL. */ Result sslContextImportServerPki(SslContext *c, const void* buffer, u32 size, SslCertificateFormat format, u64 *id); /** * @brief ImportClientPki * @note An error is thrown internally if this cmd or \ref sslContextRegisterInternalPki was already used previously. * @param c \ref SslContext * @param[in] pkcs12 PKCS#12 input buffer, must not be NULL. * @param[in] pkcs12_size pkcs12 buffer size. * @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. * @param[in] pw_size Password buffer size, this can only be 0 if pw is NULL. * @param[out] id Output Id. Optional, can be NULL. */ Result sslContextImportClientPki(SslContext *c, const void* pkcs12, u32 pkcs12_size, const char *pw, u32 pw_size, u64 *id); /** * @brief Remove the specified *Pki, or on [3.0.0+] Crl. * @param c \ref SslContext * @param[in] id Id */ Result sslContextRemovePki(SslContext *c, u64 id); /** * @brief RegisterInternalPki * @note An error is thrown internally if this cmd or \ref sslContextImportClientPki was already used previously. * @param c \ref SslContext * @param[in] internal_pki \ref SslInternalPki * @param[out] id Output Id. Optional, can be NULL. */ Result sslContextRegisterInternalPki(SslContext *c, SslInternalPki internal_pki, u64 *id); /** * @brief AddPolicyOid * @param c \ref SslContext * @param[in] str Input string. * @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. */ Result sslContextAddPolicyOid(SslContext *c, const char *str, u32 str_bufsize); /** * @brief ImportCrl * @note Only available on [3.0.0+]. * @param c \ref SslContext * @param[in] buffer Input buffer, must not be NULL. This contains the DER CRL. * @param[in] size Input buffer size. * @param[out] id Output Id. Optional, can be NULL. */ Result sslContextImportCrl(SslContext *c, const void* buffer, u32 size, u64 *id); /** * @brief ImportClientCertKeyPki * @note Only available on [16.0.0+]. * @param c \ref SslContext * @param[in] cert Input cert buffer, * @param[in] cert_size Size of the cert buffer. * @param[in] key Input key buffer. * @param[in] key_size Size of the key buffer. * @param[in] format \ref SslCertificateFormat for the cert and key. * @param[out] id Output Id. Optional, can be NULL. */ Result sslContextImportClientCertKeyPki(SslContext *c, const void* cert, u32 cert_size, const void* key, u32 key_size, SslCertificateFormat format, u64 *id); /** * @brief GeneratePrivateKeyAndCert * @note Only available on [16.0.0+]. * @param c \ref SslContext * @param[out] cert Output cert buffer, * @param[in] cert_size Size of the cert buffer. * @param[out] key Output key buffer. * @param[in] key_size Size of the key buffer. * @param[in] val Must be value 1. * @param[in] params \ref SslKeyAndCertParams * @param[out] out_certsize Actual size of the generated cert data. * @param[out] out_keysize Actual size of the generated key data. */ 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); /** * @brief CreateConnectionForSystem * @note Only available on [15.0.0+] with ::SslServiceType_System. * @param c \ref SslContext * @param[out] conn Output \ref SslConnection. */ Result sslContextCreateConnectionForSystem(SslContext *c, SslConnection *conn); ///@} ///@name ISslConnection ///@{ /** * @brief Closes a Connection object. * @param c \ref SslConnection */ void sslConnectionClose(SslConnection *c); /** * @brief SetSocketDescriptor. Do not use directly, use \ref socketSslConnectionSetSocketDescriptor instead. * @note An error is thrown if this was used previously. * @param c \ref SslConnection * @param[in] sockfd sockfd * @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). */ Result sslConnectionSetSocketDescriptor(SslConnection *c, int sockfd, int *out_sockfd); /** * @brief SetHostName * @param c \ref SslConnection * @param[in] str Input string. * @param[in] str_bufsize String buffer size. This must not be >0xff. */ Result sslConnectionSetHostName(SslConnection *c, const char* str, u32 str_bufsize); /** * @brief SetVerifyOption * @param c \ref SslConnection * @param[in] verify_option Input bitmask of \ref SslVerifyOption. */ Result sslConnectionSetVerifyOption(SslConnection *c, u32 verify_option); /** * @brief SetIoMode * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[in] mode \ref SslIoMode */ Result sslConnectionSetIoMode(SslConnection *c, SslIoMode mode); /** * @brief GetSocketDescriptor. Do not use directly, use \ref socketSslConnectionGetSocketDescriptor instead. * @note This gets the input sockfd which was previously saved in state by \ref sslConnectionSetSocketDescriptor. * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[out] sockfd Output sockfd. */ Result sslConnectionGetSocketDescriptor(SslConnection *c, int *sockfd); /** * @brief GetHostName * @param c \ref SslConnection * @param[out] str Output string buffer. * @param[in] str_bufsize String buffer size, must be large enough for the entire output string. * @param[out] out Output string length. */ Result sslConnectionGetHostName(SslConnection *c, char *str, u32 str_bufsize, u32 *out); /** * @brief GetVerifyOption * @param c \ref SslConnection * @param[out] out Output bitmask of \ref SslVerifyOption. */ Result sslConnectionGetVerifyOption(SslConnection *c, u32 *out); /** * @brief GetIoMode * @param c \ref SslConnection * @param[out] out \ref SslIoMode */ Result sslConnectionGetIoMode(SslConnection *c, SslIoMode *out); /** * @brief DoHandshake * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @note \ref sslConnectionSetHostName must have been used previously with a non-empty string when ::SslVerifyOption_HostName is set. * @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). * @note No certs are returned when ::SslVerifyOption_PeerCa is not set. * @param c \ref SslConnection * @param[out] out_size Total data size which was written to server_certbuf. Optional, can be NULL. * @param[out] total_certs Total certs which were written to server_certbuf, can be NULL. * @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. * @param[in] server_certbuf_size Optional output server cert buffer size, can be 0. */ Result sslConnectionDoHandshake(SslConnection *c, u32 *out_size, u32 *total_certs, void* server_certbuf, u32 server_certbuf_size); /** * @brief Parses the output server_certbuf from \ref sslConnectionDoHandshake where ::SslOptionType_GetServerCertChain is set. * @param[in] certbuf server_certbuf from \ref sslConnectionDoHandshake, must not be NULL. * @param[in] certbuf_size out_size from \ref sslConnectionDoHandshake. * @param[in] cert_index Cert index, must be within the range of certs stored in certbuf. * @param[out] cert Ptr for the ouput DER cert, must not be NULL. * @param[out] cert_size Size for the ouput cert, must not be NULL. */ Result sslConnectionGetServerCertDetail(const void* certbuf, u32 certbuf_size, u32 cert_index, void** cert, u32 *cert_size); /** * @brief Read * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[out] buffer Output buffer, must not be NULL. * @param[in] size Output buffer size, must not be 0. * @param[out] out_size Actual transferred size. */ Result sslConnectionRead(SslConnection *c, void* buffer, u32 size, u32 *out_size); /** * @brief Write * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[in] buffer Input buffer, must not be NULL. * @param[in] size Input buffer size, must not be 0. * @param[out] out_size Actual transferred size. */ Result sslConnectionWrite(SslConnection *c, const void* buffer, u32 size, u32 *out_size); /** * @brief Pending * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[out] out Output value. */ Result sslConnectionPending(SslConnection *c, s32 *out); /** * @brief Peek * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[out] buffer Output buffer, must not be NULL. * @param[in] size Output buffer size, must not be 0. * @param[out] out_size Output size. */ Result sslConnectionPeek(SslConnection *c, void* buffer, u32 size, u32 *out_size); /** * @brief Poll * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[in] in_pollevent Input bitmask of \ref SslPollEvent. * @param[out] out_pollevent Output bitmask of \ref SslPollEvent. * @param[in] timeout Timeout in milliseconds. */ Result sslConnectionPoll(SslConnection *c, u32 in_pollevent, u32 *out_pollevent, u32 timeout); /** * @brief GetVerifyCertError * @note The value in state is cleared after loading it. * @param c \ref SslConnection */ Result sslConnectionGetVerifyCertError(SslConnection *c); /** * @brief GetNeededServerCertBufferSize * @param c \ref SslConnection * @param[out] out Output value. */ Result sslConnectionGetNeededServerCertBufferSize(SslConnection *c, u32 *out); /** * @brief SetSessionCacheMode * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[in] mode \ref SslSessionCacheMode */ Result sslConnectionSetSessionCacheMode(SslConnection *c, SslSessionCacheMode mode); /** * @brief GetSessionCacheMode * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[out] out \ref SslSessionCacheMode */ Result sslConnectionGetSessionCacheMode(SslConnection *c, SslSessionCacheMode *out); /** * @brief GetSessionCacheMode * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection */ Result sslConnectionFlushSessionCache(SslConnection *c); /** * @brief SetRenegotiationMode * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[in] mode \ref SslRenegotiationMode */ Result sslConnectionSetRenegotiationMode(SslConnection *c, SslRenegotiationMode mode); /** * @brief GetRenegotiationMode * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[out] out \ref SslRenegotiationMode */ Result sslConnectionGetRenegotiationMode(SslConnection *c, SslRenegotiationMode *out); /** * @brief SetOption * @param c \ref SslConnection * @param[in] option \ref SslOptionType * @param[in] flag Input flag value. */ Result sslConnectionSetOption(SslConnection *c, SslOptionType option, bool flag); /** * @brief GetOption * @param c \ref SslConnection * @param[in] option \ref SslOptionType * @param[out] out Output flag value. */ Result sslConnectionGetOption(SslConnection *c, SslOptionType option, bool *out); /** * @brief GetVerifyCertErrors * @note An error is thrown when the cmd is successful, if the two output u32s match. * @param[out] out0 First output value, must not be NULL. * @param[out] out1 Second output value. * @param[out] errors Output array of Result, must not be NULL. * @param[in] count Size of the errors array in entries. */ Result sslConnectionGetVerifyCertErrors(SslConnection *c, u32 *out0, u32 *out1, Result *errors, u32 count); /** * @brief GetCipherInfo * @note Only available on [4.0.0+]. * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @param c \ref SslConnection * @param[out] out \ref SslCipherInfo */ Result sslConnectionGetCipherInfo(SslConnection *c, SslCipherInfo *out); /** * @brief SetNextAlpnProto * @note Only available on [9.0.0+]. * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @note ::SslOptionType_EnableAlpn should be set at the time of using \ref sslConnectionDoHandshake, otherwise using this cmd will have no affect. * @param c \ref SslConnection * @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. * @param[in] size Input buffer size, must not be 0. Must be at least 0x2. */ Result sslConnectionSetNextAlpnProto(SslConnection *c, const u8 *buffer, u32 size); /** * @brief GetNextAlpnProto * @note Only available on [9.0.0+]. * @note \ref sslConnectionSetSocketDescriptor must have been used prior to this successfully. * @note The output will be all-zero/empty if not available - such as when this was used before \ref sslConnectionDoHandshake. * @param c \ref SslConnection * @param[out] state \ref SslAlpnProtoState * @param[out] out Output string length. * @param[out] buffer Output string buffer, must not be NULL. * @param[in] size Output buffer size, must not be 0. */ Result sslConnectionGetNextAlpnProto(SslConnection *c, SslAlpnProtoState *state, u32 *out, u8 *buffer, u32 size); /** * @brief SetDtlsSocketDescriptor. Do not use directly, use \ref socketSslConnectionSetDtlsSocketDescriptor instead. * @note Only available on [16.0.0+]. * @note An error is thrown if this was used previously. * @param c \ref SslConnection * @param[in] sockfd sockfd * @param[in] Input sockaddr. * @param[in] size Input sockaddr size. * @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). */ Result sslConnectionSetDtlsSocketDescriptor(SslConnection *c, int sockfd, const void* buf, size_t size, int *out_sockfd); /** * @brief GetDtlsHandshakeTimeout * @note Only available on [16.0.0+]. * @param c \ref SslConnection * @param[out] out Output nanoseconds value. */ Result sslConnectionGetDtlsHandshakeTimeout(SslConnection *c, u64 *out); /** * @brief SetPrivateOption * @note Only available on [16.0.0+]. * @param c \ref SslConnection * @param[in] option \ref SslPrivateOptionType * @param[in] value Input value. */ Result sslConnectionSetPrivateOption(SslConnection *c, SslPrivateOptionType option, u32 value); /** * @brief SetSrtpCiphers * @note Only available on [16.0.0+]. * @param c \ref SslConnection * @param[in] ciphers Input array of u16s. Each entry must be value 1-2, otherwise the entry is ignored. * @param[in] count Total entries in the ciphers array, the maximum is 4. */ Result sslConnectionSetSrtpCiphers(SslConnection *c, const u16 *ciphers, u32 count); /** * @brief GetSrtpCipher * @note Only available on [16.0.0+]. * @param c \ref SslConnection * @param[out] out Output value. */ Result sslConnectionGetSrtpCipher(SslConnection *c, u16 *out); /** * @brief ExportKeyingMaterial * @note Only available on [16.0.0+]. * @param c \ref SslConnection * @param[out] outbuf Output buffer. * @param[in] outbuf_size Output buffer size. * @param[in] label Input label string. * @param[in] label_size Size of the label buffer excluding NUL-terminator. * @param[in] context Optional input context buffer, can be NULL. * @param[in] context_size Size of context, if specified this must be <0xFFFF. */ Result sslConnectionExportKeyingMaterial(SslConnection *c, u8 *outbuf, u32 outbuf_size, const char *label, u32 label_size, const void* context, u32 context_size); /** * @brief SetIoTimeout * @note Only available on [16.0.0+]. * @param c \ref SslConnection * @param[in] timeout Input timeout value. */ Result sslConnectionSetIoTimeout(SslConnection *c, u32 timeout); /** * @brief GetIoTimeout * @note Only available on [16.0.0+]. * @param c \ref SslConnection * @param[out] out Output timeout value. */ Result sslConnectionGetIoTimeout(SslConnection *c, u32 *out); ///@}