Document Channel ID functions and a few random extras. Change-Id: I34a6352d265615ee08bb18fd537acf70a558f014 Reviewed-on: https://boringssl-review.googlesource.com/5940 Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h index be40cf2..8d3f191 100644 --- a/include/openssl/ssl.h +++ b/include/openssl/ssl.h
@@ -284,6 +284,10 @@ /* SSL_set_accept_state configures |ssl| to be a server. */ OPENSSL_EXPORT void SSL_set_accept_state(SSL *ssl); +/* SSL_is_server returns one if |ssl| is configured as a server and zero + * otherwise. */ +OPENSSL_EXPORT int SSL_is_server(SSL *ssl); + /* SSL_set_bio configures |ssl| to read from |rbio| and write to |wbio|. |ssl| * takes ownership of the two |BIO|s. If |rbio| and |wbio| are the same, |ssl| * only takes ownership of one reference. @@ -425,7 +429,8 @@ /* SSL_ERROR_WANT_CHANNEL_ID_LOOKUP indicates the operation failed looking up * the Channel ID key. The caller may retry the operation when |channel_id_cb| - * is ready to return a key or one has been configured externally. + * is ready to return a key or one has been configured with + * |SSL_set1_tls_channel_id|. * * See also |SSL_CTX_set_channel_id_cb|. */ #define SSL_ERROR_WANT_CHANNEL_ID_LOOKUP 9 @@ -482,6 +487,11 @@ * |version|. */ OPENSSL_EXPORT void SSL_set_max_version(SSL *ssl, uint16_t version); +/* SSL_version returns the TLS or DTLS protocol version used by |ssl|, which is + * one of the |*_VERSION| values. (E.g. |TLS1_2_VERSION|.) Before the version + * is negotiated, the result is undefined. */ +OPENSSL_EXPORT int SSL_version(const SSL *ssl); + /* Options. * @@ -844,6 +854,16 @@ OPENSSL_EXPORT int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); +/* SSL_CTX_set_default_passwd_cb sets the password callback for PEM-based + * convenience functions called on |ctx|. */ +OPENSSL_EXPORT void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, + pem_password_cb *cb); + +/* SSL_CTX_set_default_passwd_cb_userdata sets the userdata parameter for + * |ctx|'s password callback. */ +OPENSSL_EXPORT void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, + void *data); + /* Custom private keys. */ @@ -941,6 +961,21 @@ * extension was negotiated. Otherwise, it returns zero. */ OPENSSL_EXPORT int SSL_get_extms_support(const SSL *ssl); +/* SSL_get_current_cipher returns the cipher used in the current outgoing + * connection state, or NULL if the null cipher is active. */ +OPENSSL_EXPORT const SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); + +/* SSL_session_reused returns one if |ssl| performed an abbreviated handshake + * and zero otherwise. + * + * TODO(davidben): Hammer down the semantics of this API while a handshake, + * initial or renego, is in progress. */ +OPENSSL_EXPORT int SSL_session_reused(const SSL *ssl); + +/* SSL_get_secure_renegotiation_support returns one if the peer supports secure + * renegotiation (RFC 5746) and zero otherwise. */ +OPENSSL_EXPORT int SSL_get_secure_renegotiation_support(const SSL *ssl); + /* Custom extensions. * @@ -1195,11 +1230,16 @@ * the session. */ OPENSSL_EXPORT SSL_SESSION *SSL_get1_session(SSL *ssl); -/* SSL_CTX_set_timeout sets the lifetime of sessions created in |ctx| to - * |timeout|. */ +/* SSL_DEFAULT_SESSION_TIMEOUT is the default lifetime, in seconds, of a + * session. */ +#define SSL_DEFAULT_SESSION_TIMEOUT (2 * 60 * 60) + +/* SSL_CTX_set_timeout sets the lifetime, in seconds, of sessions created in + * |ctx| to |timeout|. */ OPENSSL_EXPORT long SSL_CTX_set_timeout(SSL_CTX *ctx, long timeout); -/* SSL_CTX_get_timeout returns the lifetime of sessions created in |ctx|. */ +/* SSL_CTX_get_timeout returns the lifetime, in seconds, of sessions created in + * |ctx|. */ OPENSSL_EXPORT long SSL_CTX_get_timeout(const SSL_CTX *ctx); /* SSL_CTX_set_session_id_context sets |ctx|'s session ID context to |sid_ctx|. @@ -1223,6 +1263,10 @@ OPENSSL_EXPORT int SSL_set_session_id_context(SSL *ssl, const uint8_t *sid_ctx, unsigned sid_ctx_len); +/* SSL_SESSION_CACHE_MAX_SIZE_DEFAULT is the default maximum size of a session + * cache. */ +#define SSL_SESSION_CACHE_MAX_SIZE_DEFAULT (1024 * 20) + /* SSL_CTX_sess_set_cache_size sets the maximum size of |ctx|'s internal session * cache to |size|. It returns the previous value. */ OPENSSL_EXPORT unsigned long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, @@ -1663,6 +1707,54 @@ #define OPENSSL_NPN_NO_OVERLAP 2 +/* Channel ID. + * + * See draft-balfanz-tls-channelid-01. */ + +/* SSL_CTX_enable_tls_channel_id either configures a TLS server to accept TLS + * Channel IDs from clients, or configures a client to send TLS Channel IDs to + * a server. It returns one. */ +OPENSSL_EXPORT int SSL_CTX_enable_tls_channel_id(SSL_CTX *ctx); + +/* SSL_enable_tls_channel_id either configures a TLS server to accept TLS + * Channel IDs from clients, or configures a client to send TLS Channel IDs to + * server. It returns one. */ +OPENSSL_EXPORT int SSL_enable_tls_channel_id(SSL *ssl); + +/* SSL_CTX_set1_tls_channel_id configures a TLS client to send a TLS Channel ID + * to compatible servers. |private_key| must be a P-256 EC key. It returns one + * on success and zero on error. */ +OPENSSL_EXPORT int SSL_CTX_set1_tls_channel_id(SSL_CTX *ctx, + EVP_PKEY *private_key); + +/* SSL_set1_tls_channel_id configures a TLS client to send a TLS Channel ID to + * compatible servers. |private_key| must be a P-256 EC key. It returns one on + * success and zero on error. */ +OPENSSL_EXPORT int SSL_set1_tls_channel_id(SSL *ssl, EVP_PKEY *private_key); + +/* SSL_get_tls_channel_id gets the client's TLS Channel ID from a server |SSL*| + * and copies up to the first |max_out| bytes into |out|. The Channel ID + * consists of the client's P-256 public key as an (x,y) pair where each is a + * 32-byte, big-endian field element. It returns 0 if the client didn't offer a + * Channel ID and the length of the complete Channel ID otherwise. */ +OPENSSL_EXPORT size_t SSL_get_tls_channel_id(SSL *ssl, uint8_t *out, + size_t max_out); + +/* SSL_CTX_set_channel_id_cb sets a callback to be called when a TLS Channel ID + * is requested. The callback may set |*out_pkey| to a key, passing a reference + * to the caller. If none is returned, the handshake will pause and + * |SSL_get_error| will return |SSL_ERROR_WANT_CHANNEL_ID_LOOKUP|. + * + * See also |SSL_ERROR_WANT_CHANNEL_ID_LOOKUP|. */ +OPENSSL_EXPORT void SSL_CTX_set_channel_id_cb( + SSL_CTX *ctx, void (*channel_id_cb)(SSL *ssl, EVP_PKEY **out_pkey)); + +/* SSL_CTX_get_channel_id_cb returns the callback set by + * |SSL_CTX_set_channel_id_cb|. */ +OPENSSL_EXPORT void (*SSL_CTX_get_channel_id_cb(SSL_CTX *ctx))( + SSL *ssl, EVP_PKEY **out_pkey); + + /* DTLS-SRTP. * * See RFC 5764. */ @@ -1820,6 +1912,22 @@ CRYPTO_EX_free *free_func); +/* Obscure functions. */ + +/* SSL_get_rc4_state sets |*read_key| and |*write_key| to the RC4 states for + * the read and write directions. It returns one on success or zero if |ssl| + * isn't using an RC4-based cipher suite. */ +OPENSSL_EXPORT int SSL_get_rc4_state(const SSL *ssl, const RC4_KEY **read_key, + const RC4_KEY **write_key); + +/* SSL_get_structure_sizes returns the sizes of the SSL, SSL_CTX and + * SSL_SESSION structures so that a test can ensure that outside code agrees on + * these values. */ +OPENSSL_EXPORT void SSL_get_structure_sizes(size_t *ssl_size, + size_t *ssl_ctx_size, + size_t *ssl_session_size); + + /* Underdocumented functions. * * Functions below here haven't been touched up and may be underdocumented. */ @@ -1917,10 +2025,6 @@ * and zero on failure. */ OPENSSL_EXPORT int SSL_set_mtu(SSL *ssl, unsigned mtu); -/* SSL_get_secure_renegotiation_support returns one if the peer supports secure - * renegotiation (RFC 5746) and zero otherwise. */ -OPENSSL_EXPORT int SSL_get_secure_renegotiation_support(const SSL *ssl); - /* SSL_CTX_set_msg_callback installs |cb| as the message callback for |ctx|. * This callback will be called when sending or receiving low-level record * headers, complete handshake messages, ChangeCipherSpec, and alerts. @@ -1966,10 +2070,6 @@ #define SSL_MAX_CERT_LIST_DEFAULT 1024 * 100 /* 100k max cert list */ -#define SSL_SESSION_CACHE_MAX_SIZE_DEFAULT (1024 * 20) - -#define SSL_DEFAULT_SESSION_TIMEOUT (2 * 60 * 60) - /* ssl_early_callback_ctx is passed to certain callbacks that are called very * early on during the server handshake. At this point, much of the SSL* hasn't * been filled out and only the ClientHello can be depended on. */ @@ -2008,11 +2108,6 @@ OPENSSL_EXPORT int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); -OPENSSL_EXPORT void SSL_CTX_set_channel_id_cb( - SSL_CTX *ctx, void (*channel_id_cb)(SSL *ssl, EVP_PKEY **pkey)); -OPENSSL_EXPORT void (*SSL_CTX_get_channel_id_cb(SSL_CTX *ctx))(SSL *ssl, - EVP_PKEY **pkey); - /* SSL_enable_signed_cert_timestamps causes |ssl| (which must be the client end * of a connection) to request SCTs from the server. See * https://tools.ietf.org/html/rfc6962. It returns one. */ @@ -2202,46 +2297,10 @@ * WARNING: This function breaks the usual return value convention. */ OPENSSL_EXPORT int DTLSv1_handle_timeout(SSL *ssl); -/* SSL_session_reused returns one if |ssl| performed an abbreviated handshake - * and zero otherwise. - * - * TODO(davidben): Hammer down the semantics of this API while a handshake, - * initial or renego, is in progress. */ -OPENSSL_EXPORT int SSL_session_reused(const SSL *ssl); - /* SSL_total_renegotiations returns the total number of renegotiation handshakes * peformed by |ssl|. This includes the pending renegotiation, if any. */ OPENSSL_EXPORT int SSL_total_renegotiations(const SSL *ssl); -/* SSL_CTX_enable_tls_channel_id either configures a TLS server to accept TLS - * client IDs from clients, or configures a client to send TLS client IDs to - * a server. It returns one. */ -OPENSSL_EXPORT int SSL_CTX_enable_tls_channel_id(SSL_CTX *ctx); - -/* SSL_enable_tls_channel_id either configures a TLS server to accept TLS - * client IDs from clients, or configure a client to send TLS client IDs to - * server. It returns one. */ -OPENSSL_EXPORT int SSL_enable_tls_channel_id(SSL *ssl); - -/* SSL_CTX_set1_tls_channel_id configures a TLS client to send a TLS Channel ID - * to compatible servers. |private_key| must be a P-256 EC key. It returns one - * on success and zero on error. */ -OPENSSL_EXPORT int SSL_CTX_set1_tls_channel_id(SSL_CTX *ctx, - EVP_PKEY *private_key); - -/* SSL_set1_tls_channel_id configures a TLS client to send a TLS Channel ID to - * compatible servers. |private_key| must be a P-256 EC key. It returns one on - * success and zero on error. */ -OPENSSL_EXPORT int SSL_set1_tls_channel_id(SSL *ssl, EVP_PKEY *private_key); - -/* SSL_get_tls_channel_id gets the client's TLS Channel ID from a server SSL* - * and copies up to the first |max_out| bytes into |out|. The Channel ID - * consists of the client's P-256 public key as an (x,y) pair where each is a - * 32-byte, big-endian field element. It returns 0 if the client didn't offer a - * Channel ID and the length of the complete Channel ID otherwise. */ -OPENSSL_EXPORT size_t SSL_get_tls_channel_id(SSL *ssl, uint8_t *out, - size_t max_out); - /* SSL_get0_certificate_types, for a client, sets |*out_types| to an array * containing the client certificate types requested by a server. It returns the * length of the array. */ @@ -2255,10 +2314,6 @@ OPENSSL_EXPORT void SSL_CTX_set_cert_store(SSL_CTX *, X509_STORE *); OPENSSL_EXPORT int SSL_want(const SSL *s); -/* SSL_get_current_cipher returns the cipher used in the current outgoing - * connection state, or NULL if the null cipher is active. */ -OPENSSL_EXPORT const SSL_CIPHER *SSL_get_current_cipher(const SSL *s); - OPENSSL_EXPORT int SSL_get_fd(const SSL *s); OPENSSL_EXPORT int SSL_get_rfd(const SSL *s); OPENSSL_EXPORT int SSL_get_wfd(const SSL *s); @@ -2300,11 +2355,6 @@ OPENSSL_EXPORT void SSL_CTX_set_cert_verify_callback( SSL_CTX *ctx, int (*cb)(X509_STORE_CTX *, void *), void *arg); -OPENSSL_EXPORT void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, - pem_password_cb *cb); -OPENSSL_EXPORT void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, - void *u); - OPENSSL_EXPORT int SSL_CTX_set_purpose(SSL_CTX *s, int purpose); OPENSSL_EXPORT int SSL_set_purpose(SSL *s, int purpose); OPENSSL_EXPORT int SSL_CTX_set_trust(SSL_CTX *s, int trust); @@ -2316,10 +2366,6 @@ OPENSSL_EXPORT X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx); OPENSSL_EXPORT X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl); -/* SSL_get_version returns a string describing the TLS version used by |s|. For - * example, "TLSv1.2" or "SSLv3". */ -OPENSSL_EXPORT const char *SSL_get_version(const SSL *s); - OPENSSL_EXPORT STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *s); /* SSL_renegotiate_pending returns one if |ssl| is in the middle of a @@ -2341,8 +2387,6 @@ OPENSSL_EXPORT int SSL_add_client_CA(SSL *ssl, X509 *x); OPENSSL_EXPORT int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *x); -OPENSSL_EXPORT long SSL_get_default_timeout(const SSL *s); - OPENSSL_EXPORT STACK_OF(X509_NAME) *SSL_dup_CA_list(STACK_OF(X509_NAME) *sk); OPENSSL_EXPORT void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode); @@ -2351,7 +2395,6 @@ OPENSSL_EXPORT int SSL_get_quiet_shutdown(const SSL *ssl); OPENSSL_EXPORT void SSL_set_shutdown(SSL *ssl, int mode); OPENSSL_EXPORT int SSL_get_shutdown(const SSL *ssl); -OPENSSL_EXPORT int SSL_version(const SSL *ssl); OPENSSL_EXPORT int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx); OPENSSL_EXPORT int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, @@ -2401,28 +2444,12 @@ OPENSSL_EXPORT void SSL_set_max_send_fragment(SSL *ssl, size_t max_send_fragment); -OPENSSL_EXPORT int SSL_cache_hit(SSL *s); -OPENSSL_EXPORT int SSL_is_server(SSL *s); - /* SSL_CTX_set_dos_protection_cb sets a callback that is called once the * resumption decision for a ClientHello has been made. It can return 1 to * allow the handshake to continue or zero to cause the handshake to abort. */ OPENSSL_EXPORT void SSL_CTX_set_dos_protection_cb( SSL_CTX *ctx, int (*cb)(const struct ssl_early_callback_ctx *)); -/* SSL_get_structure_sizes returns the sizes of the SSL, SSL_CTX and - * SSL_SESSION structures so that a test can ensure that outside code agrees on - * these values. */ -OPENSSL_EXPORT void SSL_get_structure_sizes(size_t *ssl_size, - size_t *ssl_ctx_size, - size_t *ssl_session_size); - -/* SSL_get_rc4_state sets |*read_key| and |*write_key| to the RC4 states for - * the read and write directions. It returns one on success or zero if |ssl| - * isn't using an RC4-based cipher suite. */ -OPENSSL_EXPORT int SSL_get_rc4_state(const SSL *ssl, const RC4_KEY **read_key, - const RC4_KEY **write_key); - /* Deprecated functions. */ @@ -2684,6 +2711,16 @@ #define SSL_OP_TLS_BLOCK_PADDING_BUG 0 #define SSL_OP_TLS_ROLLBACK_BUG 0 +/* SSL_cache_hit calls |SSL_session_resumed|. */ +OPENSSL_EXPORT int SSL_cache_hit(SSL *ssl); + +/* SSL_get_default_timeout returns |SSL_DEFAULT_SESSION_TIMEOUT|. */ +OPENSSL_EXPORT long SSL_get_default_timeout(const SSL *ssl); + +/* SSL_get_version returns a string describing the TLS version used by |ssl|. + * For example, "TLSv1.2" or "SSLv3". */ +OPENSSL_EXPORT const char *SSL_get_version(const SSL *ssl); + /* Private structures. * @@ -2918,7 +2955,7 @@ int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey); /* get channel id callback */ - void (*channel_id_cb)(SSL *ssl, EVP_PKEY **pkey); + void (*channel_id_cb)(SSL *ssl, EVP_PKEY **out_pkey); CRYPTO_EX_DATA ex_data;
diff --git a/ssl/ssl_file.c b/ssl/ssl_file.c index 95deaae..25e1cc1 100644 --- a/ssl/ssl_file.c +++ b/ssl/ssl_file.c
@@ -624,4 +624,12 @@ return ret; } +void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb) { + ctx->default_passwd_callback = cb; +} + +void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *data) { + ctx->default_passwd_callback_userdata = data; +} + IMPLEMENT_PEM_rw(SSL_SESSION, SSL_SESSION, PEM_STRING_SSL_SESSION, SSL_SESSION)
diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c index 6b7be62..572fdde 100644 --- a/ssl/ssl_lib.c +++ b/ssl/ssl_lib.c
@@ -1199,8 +1199,8 @@ return X509_VERIFY_PARAM_get_depth(s->param); } -int SSL_get_extms_support(const SSL *s) { - return s->s3->tmp.extended_master_secret == 1; +int SSL_get_extms_support(const SSL *ssl) { + return ssl->s3->tmp.extended_master_secret == 1; } int (*SSL_get_verify_callback(const SSL *s))(int, X509_STORE_CTX *) { @@ -1272,7 +1272,7 @@ return X509_check_private_key(ssl->cert->x509, ssl->cert->privatekey); } -long SSL_get_default_timeout(const SSL *s) { +long SSL_get_default_timeout(const SSL *ssl) { return SSL_DEFAULT_SESSION_TIMEOUT; } @@ -1823,14 +1823,6 @@ s, out, out_len, label, label_len, context, context_len, use_context); } -void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb) { - ctx->default_passwd_callback = cb; -} - -void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u) { - ctx->default_passwd_callback_userdata = u; -} - void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*cb)(X509_STORE_CTX *, void *), void *arg) { @@ -1989,8 +1981,8 @@ } } -const char *SSL_get_version(const SSL *s) { - return ssl_get_version(s->version); +const char *SSL_get_version(const SSL *ssl) { + return ssl_get_version(ssl->version); } const char *SSL_SESSION_get_version(const SSL_SESSION *session) { @@ -2040,11 +2032,11 @@ return NULL; } -const SSL_CIPHER *SSL_get_current_cipher(const SSL *s) { - if (s->aead_write_ctx == NULL) { +const SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl) { + if (ssl->aead_write_ctx == NULL) { return NULL; } - return s->aead_write_ctx->cipher; + return ssl->aead_write_ctx->cipher; } const COMP_METHOD *SSL_get_current_compression(SSL *s) { return NULL; } @@ -2700,9 +2692,9 @@ return version; } -int SSL_cache_hit(SSL *s) { return s->hit; } +int SSL_cache_hit(SSL *ssl) { return SSL_session_reused(ssl); } -int SSL_is_server(SSL *s) { return s->server; } +int SSL_is_server(SSL *ssl) { return ssl->server; } void SSL_CTX_set_dos_protection_cb( SSL_CTX *ctx, int (*cb)(const struct ssl_early_callback_ctx *)) {