diff options
author | Todd Short <tshort@akamai.com> | 2017-03-15 13:25:55 -0400 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2018-03-12 10:31:09 +0000 |
commit | df0fed9aab239e2e9a269d06637a6442051dee3b (patch) | |
tree | c2c6c9ea189603c90dad7bd60814143f2c267800 /doc/man3 | |
parent | f1c00b93e2138e5a45e8b500dec6bb3b2e035771 (diff) | |
download | openssl-new-df0fed9aab239e2e9a269d06637a6442051dee3b.tar.gz |
Session Ticket app data
Adds application data into the encrypted session ticket
Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3802)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/SSL_CTX_set_session_ticket_cb.pod | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/doc/man3/SSL_CTX_set_session_ticket_cb.pod b/doc/man3/SSL_CTX_set_session_ticket_cb.pod new file mode 100644 index 0000000000..e9aeb909f0 --- /dev/null +++ b/doc/man3/SSL_CTX_set_session_ticket_cb.pod @@ -0,0 +1,149 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_ticket_cb, +SSL_SESSION_get0_ticket_appdata, +SSL_SESSION_set1_ticket_appdata, +SSL_CTX_generate_session_ticket_fn, +SSL_CTX_decrypt_session_ticket_fn - manage session ticket application data + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg); + typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss, + const unsigned char *keyname, + size_t keyname_len, + SSL_TICKET_RETURN retv, + void *arg); + int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx, + SSL_CTX_generate_session_ticket_fn gen_cb, + SSL_CTX_decrypt_session_ticket_fn dec_cb, + void *arg); + int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len); + int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len); + +=head1 DESCRIPTION + +SSL_CTX_set_set_session_ticket_cb() sets the application callbacks B<gen_cb> +and B<dec_cb> that are used by a server to set and get application data stored +with a session, and placed into a session ticket. Either callback function may +be set to NULL. The value of B<arg> is passed to the callbacks. + +B<gen_cb> is the application defined callback invoked when a session ticket is +about to be created. The application can call SSL_SESSION_set1_ticket_appdata() +at this time to add application data to the session ticket. The value of B<arg> +is the same as that given to SSL_CTX_set_session_ticket_cb(). The B<gen_cb> +callback is defined as type B<SSL_CTX_generate_session_ticket_fn>. + +B<dec_cb> is the application defined callback invoked after session ticket +decryption has been attempted and any session ticket application data is available. +The application can call SSL_SESSION_get_ticket_appdata() at this time to retrieve +the application data. The value of B<arg> is the same as that given to +SSL_CTX_set_session_ticket_cb(). The B<retv> arguement is the result of the ticket +decryption. The B<keyname> and B<keyname_len> identify the key used to decrypt the +session ticket. The B<dec_cb> callback is defined as type +B<SSL_CTX_decrypt_session_ticket_fn>. + +SSL_SESSION_set1_ticket_appdata() sets the application data specified by +B<data> and B<len> into B<ss> which is then placed into any generated session +tickets. It can be called at any time before a session ticket is created to +update the data placed into the session ticket. However, given that sessions +and tickets are created by the handshake, the B<gen_cb> is provided to notify +the application that a session ticket is about to be generated. + +SSL_SESSION_get0_ticket_appdata() assigns B<data> to the session ticket +application data and assigns B<len> to the length of the session ticket +application data from B<ss>. The application data can be set via +SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be assigned +to B<data> and 0 will be assigned to B<len> if there is no session ticket +application data. SSL_SESSION_get0_ticket_appdata() can be called any time +after a session has been created. The B<dec_cb> is provided to notify the +application that a session ticket has just been decrypted. + +=head1 NOTES + +When the B<dec_cb> callback is invoked, the SSL_SESSION B<ss> has not yet been +assigned to the SSL B<s>. The B<retv> indicates the result of the ticket +decryption which can be modified by the callback before being returned. The +callback must check the B<retv> value before performing any action, as it's +called even if ticket decryption fails. + +The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify +the key that was used to encrypt the session ticket. + +When the B<gen_cb> callback is invoked, the SSL_get_session() function can be +used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata(). + +=head1 RETURN VALUES + +The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and +SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on +failure. + +The B<gen_cb> callback must return 1 to continue the connection. A return of 0 +will terminate the connection with an INTERNAL_ERROR alert. + +The B<dec_cb> callback must return one of the following B<SSL_TICKET_RETURN> +values. Under normal circumstances the B<retv> value is returned unmodified, +but the callback can change the behavior of the post-ticket decryption code +by returning something different. The B<dec_cb> callback must check the B<retv> +value before performing any action. + + typedef int SSL_TICKET_RETURN; + +=over 4 + +=item SSL_TICKET_FATAL_ERR_MALLOC + +Fatal error, malloc failure. + +=item SSL_TICKET_FATAL_ERR_OTHER + +Fatal error, either from parsing or decrypting the ticket. + +=item SSL_TICKET_NONE + +No ticket present. + +=item SSL_TICKET_EMPTY + +Empty ticket present. + +=item SSL_TICKET_NO_DECRYPT + +The ticket couldn't be decrypted. + +=item SSL_TICKET_SUCCESS + +A ticket was successfully decrypted, any session ticket application data should +be available. + +=item TICKET_SUCCESS_RENEW + +Same as B<TICKET_SUCCESS>, but the ticket needs to be renewed. + +=back + +=head1 SEE ALSO + +L<ssl(7)>, +L<SSL_get_session(3)> + +=head1 HISTORY + +SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata() and +SSL_SESSION_get_ticket_appdata() were added to OpenSSL 1.1.1. + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |