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`).