diff --git a/doc/api/tls.md b/doc/api/tls.md index 292b27ae05d981..c6cf5041c35402 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -115,6 +115,26 @@ 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 also available as an alternative to normal certificate-based +authentication. TLS-PSK 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, with the variety determined by the normal cipher +negotiation step. + +Note that 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 for the majority +of TLS uses. + +The TLS-PSK implementation in OpenSSL has also 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. + ### Client-initiated renegotiation attack mitigation @@ -851,6 +871,9 @@ similar to: