Document PSK functions in ssl.h. Change-Id: Iac58d28570d429236de1d2bc40b631e252b8e710 Reviewed-on: https://boringssl-review.googlesource.com/5893 Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h index 243840b..63a0bdd 100644 --- a/include/openssl/ssl.h +++ b/include/openssl/ssl.h
@@ -1477,6 +1477,93 @@ SSL *ssl); +/* Pre-shared keys. + * + * Connections may be configured with PSK (Pre-Shared Key) cipher suites. These + * authenticate using out-of-band pre-shared keys rather than certificates. See + * RFC 4279. + * + * This implementation uses NUL-terminated C strings for identities and identity + * hints, so values with a NUL character are not supported. (RFC 4279 does not + * specify the format of an identity.) */ + +/* PSK_MAX_IDENTITY_LEN is the maximum supported length of a PSK identity, + * excluding the NUL terminator. */ +#define PSK_MAX_IDENTITY_LEN 128 + +/* PSK_MAX_PSK_LEN is the maximum supported length of a pre-shared key. */ +#define PSK_MAX_PSK_LEN 256 + +/* SSL_CTX_set_psk_client_callback sets the callback to be called when PSK is + * negotiated on the client. This callback must be set to enable PSK cipher + * suites on the client. + * + * The callback is passed the identity hint in |hint| or NULL if none was + * provided. It should select a PSK identity and write the identity and the + * corresponding PSK to |identity| and |psk|, respectively. The identity is + * written as a NUL-terminated C string of length (excluding the NUL terminator) + * at most |max_identity_len|. The PSK's length must be at most |max_psk_len|. + * The callback returns the length of the PSK or 0 if no suitable identity was + * found. */ +OPENSSL_EXPORT void SSL_CTX_set_psk_client_callback( + SSL_CTX *ctx, + unsigned (*psk_client_callback)( + SSL *ssl, const char *hint, char *identity, + unsigned max_identity_len, uint8_t *psk, unsigned max_psk_len)); + +/* SSL_set_psk_client_callback sets the callback to be called when PSK is + * negotiated on the client. This callback must be set to enable PSK cipher + * suites on the client. See also |SSL_CTX_set_psk_client_callback|. */ +OPENSSL_EXPORT void SSL_set_psk_client_callback( + SSL *ssl, unsigned (*psk_client_callback)(SSL *ssl, const char *hint, + char *identity, + unsigned max_identity_len, + uint8_t *psk, + unsigned max_psk_len)); + +/* SSL_CTX_set_psk_server_callback sets the callback to be called when PSK is + * negotiated on the server. This callback must be set to enable PSK cipher + * suites on the server. + * + * The callback is passed the identity in |identity|. It should write a PSK of + * length at most |max_psk_len| to |psk| and return the number of bytes written + * or zero if the PSK identity is unknown. */ +OPENSSL_EXPORT void SSL_CTX_set_psk_server_callback( + SSL_CTX *ctx, + unsigned (*psk_server_callback)(SSL *ssl, const char *identity, + uint8_t *psk, + unsigned max_psk_len)); + +/* SSL_set_psk_server_callback sets the callback to be called when PSK is + * negotiated on the server. This callback must be set to enable PSK cipher + * suites on the server. See also |SSL_CTX_set_psk_server_callback|. */ +OPENSSL_EXPORT void SSL_set_psk_server_callback( + SSL *ssl, + unsigned (*psk_server_callback)(SSL *ssl, const char *identity, + uint8_t *psk, + unsigned max_psk_len)); + +/* SSL_CTX_use_psk_identity_hint configures server connections to advertise an + * identity hint of |identity_hint|. It returns one on success and zero on + * error. */ +OPENSSL_EXPORT int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, + const char *identity_hint); + +/* SSL_use_psk_identity_hint configures server connections to advertise an + * identity hint of |identity_hint|. It returns one on success and zero on + * error. */ +OPENSSL_EXPORT int SSL_use_psk_identity_hint(SSL *ssl, + const char *identity_hint); + +/* SSL_get_psk_identity_hint returns the PSK identity hint advertised for |ssl| + * or NULL if there is none. */ +OPENSSL_EXPORT const char *SSL_get_psk_identity_hint(const SSL *ssl); + +/* SSL_get_psk_identity, after the handshake completes, returns the PSK identity + * that was negotiated by |ssl| or NULL if PSK was not used. */ +OPENSSL_EXPORT const char *SSL_get_psk_identity(const SSL *ssl); + + /* ex_data functions. * * See |ex_data.h| for details. */ @@ -1799,37 +1886,6 @@ * are rejected. (Renegotiations requested by a client are always rejected.) */ OPENSSL_EXPORT void SSL_set_reject_peer_renegotiations(SSL *ssl, int reject); -/* the maximum length of the buffer given to callbacks containing the resulting - * identity/psk */ -#define PSK_MAX_IDENTITY_LEN 128 -#define PSK_MAX_PSK_LEN 256 -OPENSSL_EXPORT void SSL_CTX_set_psk_client_callback( - SSL_CTX *ctx, - unsigned int (*psk_client_callback)( - SSL *ssl, const char *hint, char *identity, - unsigned int max_identity_len, uint8_t *psk, unsigned int max_psk_len)); -OPENSSL_EXPORT void SSL_set_psk_client_callback( - SSL *ssl, unsigned int (*psk_client_callback)(SSL *ssl, const char *hint, - char *identity, - unsigned int max_identity_len, - uint8_t *psk, - unsigned int max_psk_len)); -OPENSSL_EXPORT void SSL_CTX_set_psk_server_callback( - SSL_CTX *ctx, - unsigned int (*psk_server_callback)(SSL *ssl, const char *identity, - uint8_t *psk, - unsigned int max_psk_len)); -OPENSSL_EXPORT void SSL_set_psk_server_callback( - SSL *ssl, - unsigned int (*psk_server_callback)(SSL *ssl, const char *identity, - uint8_t *psk, - unsigned int max_psk_len)); -OPENSSL_EXPORT int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, - const char *identity_hint); -OPENSSL_EXPORT int SSL_use_psk_identity_hint(SSL *s, const char *identity_hint); -OPENSSL_EXPORT const char *SSL_get_psk_identity_hint(const SSL *s); -OPENSSL_EXPORT const char *SSL_get_psk_identity(const SSL *s); - #define SSL_NOTHING 1 #define SSL_WRITING 2 #define SSL_READING 3