Nodejs/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2024-11-21 10:59:27 +00:00
Code Issues Actions 25 Packages Projects Releases Wiki Activity

doc: move all TLS-PSK documentation to its section

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/35717
Reviewed-By: Rich Trott <rtrott@gmail.com>
This commit is contained in:
Alba Mendez 2024-05-25 20:33:34 +02:00 committed by GitHub
parent e818eee5af
commit 0d7b5a938c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 29 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/api/tls.md
View File

@ -173,6 +173,8 @@ specifying a cipher suite with the `ciphers` option. The list of available
ciphers can be retrieved via `openssl ciphers -v 'PSK'`. All TLS 1.3
ciphers are eligible for PSK and can be retrieved via
`openssl ciphers -v -s -tls1_3 -psk`.
On the client connection, a custom `checkServerIdentity` should be passed
because the default one will fail in the absence of a certificate.
According to the [RFC 4279][], PSK identities up to 128 bytes in length and
PSKs up to 64 bytes in length must be supported. As of OpenSSL 1.1.0
@ -181,6 +183,30 @@ maximum identity size is 128 bytes, and maximum PSK length is 256 bytes.
The current implementation doesn't support asynchronous PSK callbacks due to the
limitations of the underlying OpenSSL API.
To use TLS-PSK, client and server must specify the `pskCallback` option,
a function that returns the PSK to use (which must be compatible with
the selected cipher's digest).
It will be called first on the client:
* hint: {string} optional message sent from the server to help the client
decide which identity to use during negotiation.
Always `null` if TLS 1.3 is used.
* Returns: {Object} in the form
`{ psk: <Buffer|TypedArray|DataView>, identity: <string> }` or `null`.
Then on the server:
* socket: {tls.TLSSocket} the server socket instance, equivalent to `this`.
* identity: {string} identity parameter sent from the client.
* Returns: {Buffer|TypedArray|DataView} the PSK (or `null`).
A return value of `null` stops the negotiation process and sends an
`unknown_psk_identity` alert message to the other party.
If the server wishes to hide the fact that the PSK identity was not known,
the callback must provide some random data as `psk` to make the connection
fail with `decrypt_error` before negotiation is finished.
### Client-initiated renegotiation attack mitigation
<!-- type=misc -->
@ -1646,25 +1672,7 @@ changes:
verified against the list of supplied CAs. An `'error'` event is emitted if
verification fails; `err.code` contains the OpenSSL error code. **Default:**
`true`.
* `pskCallback` {Function}
* hint: {string} optional message sent from the server to help client
decide which identity to use during negotiation.
Always `null` if TLS 1.3 is used.
* Returns: {Object} An object in the form
`{ psk: <Buffer|TypedArray|DataView>, identity: <string> }`
or `null` to stop the negotiation process. `psk` must be
compatible with the selected cipher's digest.
`identity` must use UTF-8 encoding.
When negotiating TLS-PSK (pre-shared keys), this function is called
with optional identity `hint` provided by the server or `null`
in case of TLS 1.3 where `hint` was removed.
It will be necessary to provide a custom `tls.checkServerIdentity()`
for the connection as the default one will try to check host name/IP
of the server against the certificate but that's not applicable for PSK
because there won't be a certificate present.
More information can be found in the [RFC 4279][].
* `pskCallback` {Function} For TLS-PSK negotiation, see [Pre-shared keys][].
* `ALPNProtocols`: {string\[]|Buffer\[]|TypedArray\[]|DataView\[]|Buffer|
TypedArray|DataView}
An array of strings, `Buffer`s, `TypedArray`s, or `DataView`s, or a
@ -2123,25 +2131,7 @@ changes:
default callback with high-level API will be used (see below).
* `ticketKeys`: {Buffer} 48-bytes of cryptographically strong pseudorandom
data. See [Session Resumption][] for more information.
* `pskCallback` {Function}
* socket: {tls.TLSSocket} the server [`tls.TLSSocket`][] instance for
this connection.
* identity: {string} identity parameter sent from the client.
* Returns: {Buffer|TypedArray|DataView} pre-shared key that must either be
a buffer or `null` to stop the negotiation process. Returned PSK must be
compatible with the selected cipher's digest.
When negotiating TLS-PSK (pre-shared keys), this function is called
with the identity provided by the client.
If the return value is `null` the negotiation process will stop and an
"unknown\_psk\_identity" alert message will be sent to the other party.
If the server wishes to hide the fact that the PSK identity was not known,
the callback must provide some random data as `psk` to make the connection
fail with "decrypt\_error" before negotiation is finished.
PSK ciphers are disabled by default, and using TLS-PSK thus
requires explicitly specifying a cipher suite with the `ciphers` option.
More information can be found in the [RFC 4279][].
* `pskCallback` {Function} For TLS-PSK negotiation, see [Pre-shared keys][].
* `pskIdentityHint` {string} optional hint to send to a client to help
with selecting the identity during TLS-PSK negotiation. Will be ignored
in TLS 1.3. Upon failing to set pskIdentityHint `'tlsClientError'` will be
@ -2292,6 +2282,7 @@ added:
[Mozilla's publicly trusted list of CAs]: https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt
[OCSP request]: https://en.wikipedia.org/wiki/OCSP_stapling
[OpenSSL Options]: crypto.md#openssl-options
[Pre-shared keys]: #pre-shared-keys
[RFC 2246]: https://www.ietf.org/rfc/rfc2246.txt
[RFC 4086]: https://tools.ietf.org/html/rfc4086
[RFC 4279]: https://tools.ietf.org/html/rfc4279