SSL_CTX_set_session_ticket_cb.pod 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192
  1. =pod
  2. =head1 NAME
  3. SSL_CTX_set_session_ticket_cb,
  4. SSL_SESSION_get0_ticket_appdata,
  5. SSL_SESSION_set1_ticket_appdata,
  6. SSL_CTX_generate_session_ticket_fn,
  7. SSL_CTX_decrypt_session_ticket_fn - manage session ticket application data
  8. =head1 SYNOPSIS
  9. #include <openssl/ssl.h>
  10. typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg);
  11. typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss,
  12. const unsigned char *keyname,
  13. size_t keyname_len,
  14. SSL_TICKET_STATUS status,
  15. void *arg);
  16. int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx,
  17. SSL_CTX_generate_session_ticket_fn gen_cb,
  18. SSL_CTX_decrypt_session_ticket_fn dec_cb,
  19. void *arg);
  20. int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len);
  21. int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len);
  22. =head1 DESCRIPTION
  23. SSL_CTX_set_set_session_ticket_cb() sets the application callbacks B<gen_cb>
  24. and B<dec_cb> that are used by a server to set and get application data stored
  25. with a session, and placed into a session ticket. Either callback function may
  26. be set to NULL. The value of B<arg> is passed to the callbacks.
  27. B<gen_cb> is the application defined callback invoked when a session ticket is
  28. about to be created. The application can call SSL_SESSION_set1_ticket_appdata()
  29. at this time to add application data to the session ticket. The value of B<arg>
  30. is the same as that given to SSL_CTX_set_session_ticket_cb(). The B<gen_cb>
  31. callback is defined as type B<SSL_CTX_generate_session_ticket_fn>.
  32. B<dec_cb> is the application defined callback invoked after session ticket
  33. decryption has been attempted and any session ticket application data is
  34. available. If ticket decryption was successful then the B<ss> argument contains
  35. the session data. The B<keyname> and B<keyname_len> arguments identify the key
  36. used to decrypt the session ticket. The B<status> argument is the result of the
  37. ticket decryption. See the L</NOTES> section below for further details. The value
  38. of B<arg> is the same as that given to SSL_CTX_set_session_ticket_cb(). The
  39. B<dec_cb> callback is defined as type B<SSL_CTX_decrypt_session_ticket_fn>.
  40. SSL_SESSION_set1_ticket_appdata() sets the application data specified by
  41. B<data> and B<len> into B<ss> which is then placed into any generated session
  42. tickets. It can be called at any time before a session ticket is created to
  43. update the data placed into the session ticket. However, given that sessions
  44. and tickets are created by the handshake, the B<gen_cb> is provided to notify
  45. the application that a session ticket is about to be generated.
  46. SSL_SESSION_get0_ticket_appdata() assigns B<data> to the session ticket
  47. application data and assigns B<len> to the length of the session ticket
  48. application data from B<ss>. The application data can be set via
  49. SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be assigned
  50. to B<data> and 0 will be assigned to B<len> if there is no session ticket
  51. application data. SSL_SESSION_get0_ticket_appdata() can be called any time
  52. after a session has been created. The B<dec_cb> is provided to notify the
  53. application that a session ticket has just been decrypted.
  54. =head1 NOTES
  55. When the B<dec_cb> callback is invoked, the SSL_SESSION B<ss> has not yet been
  56. assigned to the SSL B<s>. The B<status> indicates the result of the ticket
  57. decryption. The callback must check the B<status> value before performing any
  58. action, as it is called even if ticket decryption fails.
  59. The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify
  60. the key that was used to encrypt the session ticket.
  61. The B<status> argument can be any of these values:
  62. =over 4
  63. =item SSL_TICKET_EMPTY
  64. Empty ticket present. No ticket data will be used and a new ticket should be
  65. sent to the client. This only occurs in TLSv1.2 or below. In TLSv1.3 it is not
  66. valid for a client to send an empty ticket.
  67. =item SSL_TICKET_NO_DECRYPT
  68. The ticket couldn't be decrypted. No ticket data will be used and a new ticket
  69. should be sent to the client.
  70. =item SSL_TICKET_SUCCESS
  71. A ticket was successfully decrypted, any session ticket application data should
  72. be available. A new ticket should not be sent to the client.
  73. =item SSL_TICKET_SUCCESS_RENEW
  74. Same as B<SSL_TICKET_SUCCESS>, but a new ticket should be sent to the client.
  75. =back
  76. The return value can be any of these values:
  77. =over 4
  78. =item SSL_TICKET_RETURN_ABORT
  79. The handshake should be aborted, either because of an error or because of some
  80. policy. Note that in TLSv1.3 a client may send more than one ticket in a single
  81. handshake. Therefore, just because one ticket is unacceptable it does not mean
  82. that all of them are. For this reason this option should be used with caution.
  83. =item SSL_TICKET_RETURN_IGNORE
  84. Do not use a ticket (if one was available). Do not send a renewed ticket to the
  85. client.
  86. =item SSL_TICKET_RETURN_IGNORE_RENEW
  87. Do not use a ticket (if one was available). Send a renewed ticket to the client.
  88. If the callback does not wish to change the default ticket behaviour then it
  89. should return this value if B<status> is B<SSL_TICKET_EMPTY> or
  90. B<SSL_TICKET_NO_DECRYPT>.
  91. =item SSL_TICKET_RETURN_USE
  92. Use the ticket. Do not send a renewed ticket to the client. It is an error for
  93. the callback to return this value if B<status> has a value other than
  94. B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>.
  95. If the callback does not wish to change the default ticket behaviour then it
  96. should return this value if B<status> is B<SSL_TICKET_SUCCESS>.
  97. =item SSL_TICKET_RETURN_USE_RENEW
  98. Use the ticket. Send a renewed ticket to the client. It is an error for the
  99. callback to return this value if B<status> has a value other than
  100. B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>.
  101. If the callback does not wish to change the default ticket behaviour then it
  102. should return this value if B<status> is B<SSL_TICKET_SUCCESS_RENEW>.
  103. =back
  104. If B<status> has the value B<SSL_TICKET_EMPTY> or B<SSL_TICKET_NO_DECRYPT> then
  105. no session data will be available and the callback must not use the B<ss>
  106. argument. If B<status> has the value B<SSL_TICKET_SUCCESS> or
  107. B<SSL_TICKET_SUCCESS_RENEW> then the application can call
  108. SSL_SESSION_get0_ticket_appdata() using the session provided in the B<ss>
  109. argument to retrieve the application data.
  110. When the B<gen_cb> callback is invoked, the SSL_get_session() function can be
  111. used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata().
  112. By default, in TLSv1.2 and below, a new session ticket is not issued on a
  113. successful resumption and therefore B<gen_cb> will not be called. In TLSv1.3 the
  114. default behaviour is to always issue a new ticket on resumption. In both cases
  115. this behaviour can be changed if a ticket key callback is in use (see
  116. L<SSL_CTX_set_tlsext_ticket_key_cb(3)>).
  117. =head1 RETURN VALUES
  118. The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and
  119. SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on
  120. failure.
  121. The B<gen_cb> callback must return 1 to continue the connection. A return of 0
  122. will terminate the connection with an INTERNAL_ERROR alert.
  123. The B<dec_cb> callback must return a value as described in L</NOTES> above.
  124. =head1 SEE ALSO
  125. L<ssl(7)>,
  126. L<SSL_get_session(3)>
  127. =head1 HISTORY
  128. The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata()
  129. and SSL_SESSION_get_ticket_appdata() functions were added in OpenSSL 1.1.1.
  130. =head1 COPYRIGHT
  131. Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
  132. Licensed under the Apache License 2.0 (the "License"). You may not use
  133. this file except in compliance with the License. You can obtain a copy
  134. in the file LICENSE in the source distribution or at
  135. L<https://www.openssl.org/source/license.html>.
  136. =cut