Line 1: |
Line 1: |
| = ssl = | | = ssl = |
| This is "nn::ssl::sf::ISslService". sdknso uses SessionManager with this, where the additional session-count is user-specified (default is 0x2). An error is thrown when the input value is less than 1 or >4. | | This is "nn::ssl::sf::ISslService". sdknso uses SessionManager with this, where the additional session-count is user-specified (default is 0x2). An error is thrown when the input value is less than 1 or >4. |
| + | |
| + | This service implements client-mode TLS using [https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS NSS]. |
| + | |
| + | Note that SystemPrograms generally use [[#RegisterInternalPki]] (see [[libcurl]]). However, [[Internet_Browser|web-applets]] use [[#GetCertificates]] with [[#CaCertificateId]] All - [[#RegisterInternalPki]] is not used. |
| | | |
| {| class="wikitable" border="1" | | {| class="wikitable" border="1" |
Line 134: |
Line 138: |
| | | |
| === ImportServerPki === | | === ImportServerPki === |
− | Takes a type-0x5 input buffer and a [[#CertificateFormat]], returns an output u64. | + | Takes a type-0x5 input buffer and a [[#CertificateFormat]], returns an output u64 Id. |
| + | |
| + | The input buffer can contain multiple certs. A maximum of 71 ServerPki objects (associated with the output Id) can be imported. |
| + | |
| + | The certs can be CAs or server certs (no pubkeys). |
| | | |
| === ImportClientPki === | | === ImportClientPki === |
− | Takes two type-0x5 input buffers, returns an output u64. | + | Takes two type-0x5 input buffers, returns an output u64 Id. |
| + | |
| + | The first buffer contains the PKCS#12 data, the second buffer contains the optional (addr=NULL/size=0) ASCII password. The password is copied to a heap buffer with size+1, for NUL-termination. |
| + | |
| + | An error is thrown if this cmd or [[#RegisterInternalPki]] was already used previously. |
| | | |
| === RemoveServerPki === | | === RemoveServerPki === |
− | Takes an input u64, no output. | + | Takes an input u64 Id, no output. |
| | | |
| === RemoveClientPki === | | === RemoveClientPki === |
− | Takes an input u64, no output. | + | Takes an input u64 Id, no output. |
| | | |
| === RegisterInternalPki === | | === RegisterInternalPki === |
− | Takes an input [[#InternalPki]], returns an output u64. | + | Takes an input [[#InternalPki]], returns an output u64 Id. |
| + | |
| + | An error is thrown if this cmd or [[#ImportClientPki]] was already used previously. |
| | | |
| === AddPolicyOid === | | === AddPolicyOid === |
Line 154: |
Line 168: |
| | | |
| === ImportCrl === | | === ImportCrl === |
− | Takes a type-0x5 input buffer, returns an output u64. | + | Takes a type-0x5 input buffer, returns an output u64 Id. |
| + | |
| + | The input buffer contains the DER CRL. |
| | | |
| === RemoveCrl === | | === RemoveCrl === |
− | Takes an input u64, no output. | + | Takes an input u64 Id, no output. |
| | | |
| === ISslConnection === | | === ISslConnection === |
Line 228: |
Line 244: |
| An error is thrown if this was used previously. | | An error is thrown if this was used previously. |
| | | |
− | The input sockfd is used with [[Sockets_services#DuplicateSocket|DuplicateSocket]], with the output sockfd from that being written into state. If the field which would be used for the input u64 (PID set by [[#CreateContext]]) is zero however, it instead uses the input sockfd directly and returns -1 for the sockfd. An error is thrown if DuplicateSocket fails. When DuplicateSocket is successful, the input sockfd is returned as the output sockfd, however if [[#OptionType|DoNotCloseSocket]] is set it will instead return -1 for the sockfd.
| + | internal_sockfd = output from [[Sockets_services#DuplicateSocket|DuplicateSocket]], with the input sockfd. If the field which would be used for the input u64 (PID set by [[#CreateContext]]) is zero however, it instead uses internal_sockfd=input_sockfd directly without DuplicateSocket and later returns -1 for the sockfd. An error is thrown if DuplicateSocket fails. The input sockfd is later returned as the output sockfd, however if [[#OptionType|DoNotCloseSocket]] is set it will instead return -1 for the sockfd. Then [[Sockets_services#GetPeerName|GetPeerName]] is used with internal_sockfd, throwing an error if this fails. internal_sockfd is used for state initialization, and the input_sockfd is written into state. |
| | | |
| Immediately prior to closing the [[#ISslConnection]] object, sdknso will close the sockfd which was returned by this cmd if it is not negative. | | Immediately prior to closing the [[#ISslConnection]] object, sdknso will close the sockfd which was returned by this cmd if it is not negative. |
Line 251: |
Line 267: |
| | | |
| [[#SetSocketDescriptor]] must have been used prior to this successfully. | | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
| + | |
| + | This gets the input_sockfd which was previously saved in state by [[#SetSocketDescriptor]]. |
| | | |
| ==== GetHostName ==== | | ==== GetHostName ==== |
Line 265: |
Line 283: |
| ==== DoHandshake ==== | | ==== DoHandshake ==== |
| No input/output. | | No input/output. |
| + | |
| + | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
| + | |
| + | The [[#SetHostName|hostname]] must be set (non-empty string) when [[#VerifyOption]] HostName is set, otherwise an error is thrown. |
| | | |
| This will also set a callback eventually for saving an [[Error_Report_services|error-report]] when needed, which just contains the ErrorCode loaded from a Result in state. This sysmodule doesn't save any other reports elsewhere. | | This will also set a callback eventually for saving an [[Error_Report_services|error-report]] when needed, which just contains the ErrorCode loaded from a Result in state. This sysmodule doesn't save any other reports elsewhere. |
Line 272: |
Line 294: |
| | | |
| Same as [[#DoHandshake]] except the params for the func called internally are user-specified, instead of all 0. | | Same as [[#DoHandshake]] except the params for the func called internally are user-specified, instead of all 0. |
| + | |
| + | The buffer contains the output server cert DER. The first u32 is the output size, the second u32 is the total certs in the buffer. |
| + | |
| + | When [[#OptionType|GetServerCertChain]] is set, the output buffer contains the full chain. This buffer can then be parsed by a seperate sdknso func: |
| + | * The header is at +0. +0 must match a magicnum (0x4E4D684374726543 "CertChMN"), and the u32 at +0x4 must be larger than the input cert_index. |
| + | * The data at +0x10 is the 0x8-byte array-entries, for each cert. Entry +0x0 is the u32 size, and +0x4 is the u32 offset. These are copied to the output "nn::ssl::Connection::ServerCertDetail" struct, for the entry with the input cert_index: +0 = u32 size, +8 = address (input_buffer+offset). |
| + | |
| + | No certs are returned when [[#VerifyOption|PeerCa]] is not set. |
| + | |
| + | When [[#IoMode]] is NonBlocking the buffer will be only filled in once - when this cmd returns successfully the buffer will generally be empty. |
| | | |
| ==== Read ==== | | ==== Read ==== |
Line 277: |
Line 309: |
| | | |
| [[#SetSocketDescriptor]] must have been used prior to this successfully. | | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
| + | |
| + | The output u32 is the actual transferred size. |
| | | |
| ==== Write ==== | | ==== Write ==== |
Line 282: |
Line 316: |
| | | |
| [[#SetSocketDescriptor]] must have been used prior to this successfully. | | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
| + | |
| + | The output u32 is the actual transferred size. |
| | | |
| ==== Pending ==== | | ==== Pending ==== |
Line 289: |
Line 325: |
| | | |
| ==== Peek ==== | | ==== Peek ==== |
− | Takes a type-0x6 output buffer, returns an output u32. | + | Takes a type-0x6 output buffer, returns an output u32 size. |
| | | |
| [[#SetSocketDescriptor]] must have been used prior to this successfully. | | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
Line 297: |
Line 333: |
| | | |
| [[#SetSocketDescriptor]] must have been used prior to this successfully. | | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
| + | |
| + | The u32 is the timeout in milliseconds. |
| | | |
| ==== GetVerifyCertError ==== | | ==== GetVerifyCertError ==== |
Line 341: |
Line 379: |
| ==== GetVerifyCertErrors ==== | | ==== GetVerifyCertErrors ==== |
| Takes a type-0x6 output buffer, returns two output u32s. | | Takes a type-0x6 output buffer, returns two output u32s. |
| + | |
| + | On success, sdknso will throw an error if the two output u32s don't match. |
| | | |
| ==== GetCipherInfo ==== | | ==== GetCipherInfo ==== |
Line 355: |
Line 395: |
| | | |
| [[#SetSocketDescriptor]] must have been used prior to this successfully. | | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
| + | |
| + | The buffer size must be at least 0x2. |
| + | |
| + | [[#OptionType|EnableAlpn]] should be set at the time of using DoHandshake*, otherwise using this cmd will have no affect. |
| + | |
| + | The buffer contains an array of {u8 size, {data with the specified size}}, which must be within the buffer-size bounds. |
| | | |
| ==== GetNextAlpnProto ==== | | ==== GetNextAlpnProto ==== |
Line 360: |
Line 406: |
| | | |
| [[#SetSocketDescriptor]] must have been used prior to this successfully. | | [[#SetSocketDescriptor]] must have been used prior to this successfully. |
| + | |
| + | The buffer contains the output string. The u32 is the output string length. |
| + | |
| + | The output will be all-zero/empty if not available - such as when this was used before DoHandshake*. |
| | | |
| = SslVersion = | | = SslVersion = |
− | This is "nn::ssl::sf::SslVersion" or "nn::ssl::Context::SslVersion". | + | This is "nn::ssl::sf::SslVersion" or "nn::ssl::Context::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). Auto uses min=1.0/max=1.2. |
| | | |
| {| class="wikitable" border="1" | | {| class="wikitable" border="1" |
| |- | | |- |
− | ! Value | + | ! Bit |
| ! Description | | ! Description |
| |- | | |- |
− | | 0x1 || Auto | + | | 0 || Auto |
| |- | | |- |
− | | 0x8 || TlsV10 | + | | 3 || TlsV10 |
| |- | | |- |
− | | 0x10 || TlsV11 | + | | 4 || TlsV11 |
| |- | | |- |
− | | 0x20 || TlsV12 | + | | 5 || TlsV12 |
| |} | | |} |
| | | |
Line 462: |
Line 512: |
| ! Description | | ! Description |
| |- | | |- |
− | | -1 || All | + | | -1 || [3.0.0+] All |
| |- | | |- |
| | 1 || NintendoCAG3 | | | 1 || NintendoCAG3 |
Line 502: |
Line 552: |
| | 1016 || EntrustRootCertificationAuthorityG2 | | | 1016 || EntrustRootCertificationAuthorityG2 |
| |- | | |- |
− | | 1017 || GeoTrustGlobalCA2 | + | | 1017 || GeoTrustGlobalCA2 ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
− | | 1018 || GeoTrustGlobalCA | + | | 1018 || GeoTrustGlobalCA ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
− | | 1019 || GeoTrustPrimaryCertificationAuthorityG3 | + | | 1019 || GeoTrustPrimaryCertificationAuthorityG3 ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
− | | 1020 || GeoTrustPrimaryCertificationAuthority | + | | 1020 || GeoTrustPrimaryCertificationAuthority ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
| | 1021 || GlobalSignRootCA | | | 1021 || GlobalSignRootCA |
Line 524: |
Line 574: |
| | 1027 || StarfieldRootCertificateAuthorityG2 | | | 1027 || StarfieldRootCertificateAuthorityG2 |
| |- | | |- |
− | | 1028 || thawtePrimaryRootCAG3 | + | | 1028 || thawtePrimaryRootCAG3 ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
− | | 1029 || thawtePrimaryRootCA | + | | 1029 || thawtePrimaryRootCA ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
− | | 1030 || VeriSignClass3PublicPrimaryCertificationAuthorityG3 | + | | 1030 || VeriSignClass3PublicPrimaryCertificationAuthorityG3 ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
− | | 1031 || VeriSignClass3PublicPrimaryCertificationAuthorityG5 | + | | 1031 || VeriSignClass3PublicPrimaryCertificationAuthorityG5 ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
− | | 1032 || VeriSignUniversalRootCertificationAuthority | + | | 1032 || VeriSignUniversalRootCertificationAuthority ([8.0.0+] [[#TrustedCertStatus]] is EnabledNotTrusted) |
| |- | | |- |
| | 1033 || [6.0.0+] DSTRootCAX3 | | | 1033 || [6.0.0+] DSTRootCAX3 |
| + | |- |
| + | | 1034 || [10.0.3+] "USERTrust RSA Certification Authority" |
| |} | | |} |
| | | |
Line 551: |
Line 603: |
| | | |
| An error is thrown by [[#RegisterInternalPki]] when the input value does not match "DeviceClientCertDefault". | | An error is thrown by [[#RegisterInternalPki]] when the input value does not match "DeviceClientCertDefault". |
| + | |
| + | "DeviceClientCertDefault" enables using the DeviceCert. |
| | | |
| = ContextOption = | | = ContextOption = |
| This is "nn::ssl::sf::ContextOption" or "nn::ssl::Context::ContextOption". | | This is "nn::ssl::sf::ContextOption" or "nn::ssl::Context::ContextOption". |
| + | |
| + | The default value for CrlImportDateCheckEnable at the time of [[#ISslContext]] object creation is value 1. |
| | | |
| {| class="wikitable" border="1" | | {| class="wikitable" border="1" |
Line 603: |
Line 659: |
| = IoMode = | | = IoMode = |
| This is "nn::ssl::sf::IoMode" or "nn::ssl::Connection::IoMode". At the time of [[#ISslConnection]] object creation, the default value is 1. | | This is "nn::ssl::sf::IoMode" or "nn::ssl::Connection::IoMode". At the time of [[#ISslConnection]] object creation, the default value is 1. |
| + | |
| + | The socket non-blocking flag is always set regardless of this field, this is only used for calculating the timeout (converted from milliseconds) passed to the NSS funcs used by various cmds. NonBlocking = 0, Blocking = 300000 (5 minutes). |
| | | |
| {| class="wikitable" border="1" | | {| class="wikitable" border="1" |
Line 679: |
Line 737: |
| | | |
| [[#SetOption_2|SetOption]] with "DoNotCloseSocket" is only available when [[#SetSocketDescriptor]] was not used previously. "EnableAlpn" can optionally use the state setup by [[#SetSocketDescriptor]], but it will return 0 regardless. | | [[#SetOption_2|SetOption]] with "DoNotCloseSocket" is only available when [[#SetSocketDescriptor]] was not used previously. "EnableAlpn" can optionally use the state setup by [[#SetSocketDescriptor]], but it will return 0 regardless. |
| + | |
| + | See [[#SetNextAlpnProto]] for "EnableAlpn", and [[#DoHandshakeGetServerCert]] for "GetServerCertChain". |
| | | |
| = AlpnProtoState = | | = AlpnProtoState = |
Line 719: |
Line 779: |
| * [6.0.0+] "/ssl_CaFingerprints.bdf" | | * [6.0.0+] "/ssl_CaFingerprints.bdf" |
| | | |
− | The content of this SystemData was updated with the following system-versions: [[3.0.0]], [[6.0.0]], [[8.0.0]]. | + | The content of this SystemData was updated with the following system-versions: [[3.0.0]], [[6.0.0]], [[8.0.0]]. See [[#CaCertificateId]] for the ssl_TrustedCerts changes. |
| + | |
| + | [[#ISslContext]] automatically uses this CertStore, regardless of the used cmds. |
| | | |
| These have the following structure: | | These have the following structure: |
Line 748: |
Line 810: |
| | 0x4 | | | 0x4 |
| | 0x4 | | | 0x4 |
− | | ? | + | | [[#TrustedCertStatus]] |
| |- | | |- |
| | 0x8 | | | 0x8 |