X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fman3%2FSSL_CTX_set_tlsext_ticket_key_cb.pod;h=88e70c5fa23591f308edcc014970cae4b94e1dac;hb=8c47e55ee69500e31e80458682c6e022294cd0be;hp=71f879227535a0701fdf31abecc452518dfe22b7;hpb=28b86f313b43cc70d11054d3830ef82e7af8290a;p=openssl.git diff --git a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod index 71f8792275..88e70c5fa2 100644 --- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod +++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod @@ -9,9 +9,9 @@ SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing #include long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, - int (*cb)(SSL *s, unsigned char key_name[16], - unsigned char iv[EVP_MAX_IV_LENGTH], - EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); + int (*cb)(SSL *s, unsigned char key_name[16], + unsigned char iv[EVP_MAX_IV_LENGTH], + EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); =head1 DESCRIPTION @@ -38,7 +38,7 @@ ticket information or it starts a full TLS handshake to create a new session ticket. Before the callback function is started I and I have been -initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively. +initialised with L and L respectively. For new sessions tickets, when the client doesn't present a session ticket, or an attempted retrieval of the ticket failed, or a renew option was indicated, @@ -112,70 +112,72 @@ exactly as if a full negotiation had occurred. If an attacker can obtain the key used to encrypt a session ticket, they can obtain the master secret for any ticket using that key and decrypt any traffic -using that session: even if the ciphersuite supports forward secrecy. As +using that session: even if the cipher suite supports forward secrecy. As a result applications may wish to use multiple keys and avoid using long term keys stored in files. Applications can use longer keys to maintain a consistent level of security. -For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key +For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key the overall security is only 128 bits because breaking the ticket key will enable an attacker to obtain the session keys. -=head1 EXAMPLES - -Reference Implementation: - SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb); - .... - - static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc) - { - if (enc) { /* create new session */ - if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) { - return -1; /* insufficient random */ - } - - key = currentkey(); /* something that you need to implement */ - if ( !key ) { - /* current key doesn't exist or isn't valid */ - key = createkey(); /* something that you need to implement. - * createkey needs to initialise, a name, - * an aes_key, a hmac_key and optionally - * an expire time. */ - if ( !key ) { /* key couldn't be created */ - return 0; - } - } - memcpy(key_name, key->name, 16); - - EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv); - HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); - - return 1; - - } else { /* retrieve session */ - key = findkey(name); - - if (!key || key->expire < now() ) { - return 0; - } - - HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); - EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv ); - - if (key->expire < ( now() - RENEW_TIME ) ) - /* return 2 - this session will get a new ticket even though the current is still valid */ - return 2; - - return 1; - - } - } +=head1 RETURN VALUES +returns 0 to indicate the callback function was set. +=head1 EXAMPLES -=head1 RETURN VALUES +Reference Implementation: -returns 0 to indicate the callback function was set. + SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb); + ... + + static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], + unsigned char *iv, EVP_CIPHER_CTX *ctx, + HMAC_CTX *hctx, int enc) + { + if (enc) { /* create new session */ + if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0) + return -1; /* insufficient random */ + + key = currentkey(); /* something that you need to implement */ + if (key == NULL) { + /* current key doesn't exist or isn't valid */ + key = createkey(); /* + * Something that you need to implement. + * createkey needs to initialise a name, + * an aes_key, a hmac_key and optionally + * an expire time. + */ + if (key == NULL) /* key couldn't be created */ + return 0; + } + memcpy(key_name, key->name, 16); + + EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv); + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + + return 1; + + } else { /* retrieve session */ + key = findkey(name); + + if (key == NULL || key->expire < now()) + return 0; + + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv); + + if (key->expire < now() - RENEW_TIME) { + /* + * return 2 - This session will get a new ticket even though the + * current one is still valid. + */ + return 2; + } + return 1; + } + } =head1 SEE ALSO @@ -188,9 +190,9 @@ L, =head1 COPYRIGHT -Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (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.