Nintendo Switch Brew

SSL services: Difference between revisions

← Older editNewer edit →
No edit summary
(36 intermediate revisions by the same user not shown)
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
Retrieved from "https://switchbrew.org/wiki/SSL_services"