diff --git a/doc/api/errors.md b/doc/api/errors.md index cf21c142d6dd97..0831b83e01df6d 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1857,6 +1857,11 @@ vector for denial-of-service attacks. An attempt was made to issue Server Name Indication from a TLS server-side socket, which is only valid from a client. + +### ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED + +Failed to set PSK identity hint. Hint may be too long. + ### ERR_TRACE_EVENTS_CATEGORY_REQUIRED diff --git a/doc/api/tls.md b/doc/api/tls.md index ad73586ae96549..80fc015d9287f4 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -118,6 +118,40 @@ SNI (Server Name Indication) are TLS handshake extensions: * SNI: Allows the use of one TLS server for multiple hostnames with different SSL certificates. +### Pre-shared keys + + + +TLS-PSK support is available as an alternative to normal certificate-based +authentication. It uses a pre-shared key instead of certificates to +authenticate a TLS connection, providing mutual authentication. +TLS-PSK and public key infrastructure are not mutually exclusive. Clients and +servers can accommodate both, choosing either of them during the normal cipher +negotiation step. + +TLS-PSK is only a good choice where means exist to securely share a +key with every connecting machine, so it does not replace PKI +(Public Key Infrastructure) for the majority of TLS uses. +The TLS-PSK implementation in OpenSSL has seen many security flaws in +recent years, mostly because it is used only by a minority of applications. +Please consider all alternative solutions before switching to PSK ciphers. +Upon generating PSK it is of critical importance to use sufficient entropy as +discussed in [RFC 4086][]. Deriving a shared secret from a password or other +low-entropy sources is not secure. + +PSK ciphers are disabled by default, and using TLS-PSK thus requires explicitly +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 but currently only those that use SHA256 digest are +supported they can be retrieved via `openssl ciphers -v -s -tls1_3 -psk`. + +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 +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. + ### Client-initiated renegotiation attack mitigation @@ -1207,6 +1241,9 @@ being issued by trusted CA (`options.ca`).