SSL_CTX_set_generate_session_id.pod 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138
  1. =pod
  2. =head1 NAME
  3. SSL_CTX_set_generate_session_id, SSL_set_generate_session_id,
  4. SSL_has_matching_session_id, GEN_SESSION_CB
  5. - manipulate generation of SSL session IDs (server only)
  6. =head1 SYNOPSIS
  7. #include <openssl/ssl.h>
  8. typedef int (*GEN_SESSION_CB)(SSL *ssl, unsigned char *id,
  9. unsigned int *id_len);
  10. int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb);
  11. int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb);
  12. int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id,
  13. unsigned int id_len);
  14. =head1 DESCRIPTION
  15. SSL_CTX_set_generate_session_id() sets the callback function for generating
  16. new session ids for SSL/TLS sessions for B<ctx> to be B<cb>.
  17. SSL_set_generate_session_id() sets the callback function for generating
  18. new session ids for SSL/TLS sessions for B<ssl> to be B<cb>.
  19. SSL_has_matching_session_id() checks, whether a session with id B<id>
  20. (of length B<id_len>) is already contained in the internal session cache
  21. of the parent context of B<ssl>.
  22. =head1 NOTES
  23. When a new session is established between client and server, the server
  24. generates a session id. The session id is an arbitrary sequence of bytes.
  25. The length of the session id is between 1 and 32 bytes. The session id is not
  26. security critical but must be unique for the server. Additionally, the session id is
  27. transmitted in the clear when reusing the session so it must not contain
  28. sensitive information.
  29. Without a callback being set, an OpenSSL server will generate a unique
  30. session id from pseudo random numbers of the maximum possible length.
  31. Using the callback function, the session id can be changed to contain
  32. additional information like e.g. a host id in order to improve load balancing
  33. or external caching techniques.
  34. The callback function receives a pointer to the memory location to put
  35. B<id> into and a pointer to the maximum allowed length B<id_len>. The
  36. buffer at location B<id> is only guaranteed to have the size B<id_len>.
  37. The callback is only allowed to generate a shorter id and reduce B<id_len>;
  38. the callback B<must never> increase B<id_len> or write to the location
  39. B<id> exceeding the given limit.
  40. The location B<id> is filled with 0x00 before the callback is called, so the
  41. callback may only fill part of the possible length and leave B<id_len>
  42. untouched while maintaining reproducibility.
  43. Since the sessions must be distinguished, session ids must be unique.
  44. Without the callback a random number is used, so that the probability
  45. of generating the same session id is extremely small (2^256 for SSLv3/TLSv1).
  46. In order to assure the uniqueness of the generated session id, the callback must call
  47. SSL_has_matching_session_id() and generate another id if a conflict occurs.
  48. If an id conflict is not resolved, the handshake will fail.
  49. If the application codes e.g. a unique host id, a unique process number, and
  50. a unique sequence number into the session id, uniqueness could easily be
  51. achieved without randomness added (it should however be taken care that
  52. no confidential information is leaked this way). If the application can not
  53. guarantee uniqueness, it is recommended to use the maximum B<id_len> and
  54. fill in the bytes not used to code special information with random data
  55. to avoid collisions.
  56. SSL_has_matching_session_id() will only query the internal session cache,
  57. not the external one. Since the session id is generated before the
  58. handshake is completed, it is not immediately added to the cache. If
  59. another thread is using the same internal session cache, a race condition
  60. can occur in that another thread generates the same session id.
  61. Collisions can also occur when using an external session cache, since
  62. the external cache is not tested with SSL_has_matching_session_id()
  63. and the same race condition applies.
  64. The callback must return 0 if it cannot generate a session id for whatever
  65. reason and return 1 on success.
  66. =head1 RETURN VALUES
  67. SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
  68. return 1 on success and 0 for failure.
  69. SSL_has_matching_session_id() returns 1 if another session with the
  70. same id is already in the cache, or 0 otherwise.
  71. =head1 EXAMPLES
  72. The callback function listed will generate a session id with the
  73. server id given, and will fill the rest with pseudo random bytes:
  74. const char session_id_prefix = "www-18";
  75. #define MAX_SESSION_ID_ATTEMPTS 10
  76. static int generate_session_id(SSL *ssl, unsigned char *id,
  77. unsigned int *id_len)
  78. {
  79. unsigned int count = 0;
  80. do {
  81. RAND_pseudo_bytes(id, *id_len);
  82. /*
  83. * Prefix the session_id with the required prefix. NB: If our
  84. * prefix is too long, clip it - but there will be worse effects
  85. * anyway, e.g. the server could only possibly create 1 session
  86. * ID (i.e. the prefix!) so all future session negotiations will
  87. * fail due to conflicts.
  88. */
  89. memcpy(id, session_id_prefix, strlen(session_id_prefix) < *id_len ?
  90. strlen(session_id_prefix) : *id_len);
  91. } while (SSL_has_matching_session_id(ssl, id, *id_len)
  92. && ++count < MAX_SESSION_ID_ATTEMPTS);
  93. if (count >= MAX_SESSION_ID_ATTEMPTS)
  94. return 0;
  95. return 1;
  96. }
  97. =head1 SEE ALSO
  98. L<ssl(7)>, L<SSL_get_version(3)>
  99. =head1 COPYRIGHT
  100. Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
  101. Licensed under the Apache License 2.0 (the "License"). You may not use
  102. this file except in compliance with the License. You can obtain a copy
  103. in the file LICENSE in the source distribution or at
  104. L<https://www.openssl.org/source/license.html>.
  105. =cut