1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_session_id - manipulate generation of SSL session IDs (server only)
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id,
   12:                                unsigned int *id_len);
   13: 
   14:  int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb);
   15:  int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb);
   16:  int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id,
   17:                                  unsigned int id_len);
   18: 
   19: =head1 DESCRIPTION
   20: 
   21: SSL_CTX_set_generate_session_id() sets the callback function for generating
   22: new session ids for SSL/TLS sessions for B<ctx> to be B<cb>.
   23: 
   24: SSL_set_generate_session_id() sets the callback function for generating
   25: new session ids for SSL/TLS sessions for B<ssl> to be B<cb>.
   26: 
   27: SSL_has_matching_session_id() checks, whether a session with id B<id>
   28: (of length B<id_len>) is already contained in the internal session cache
   29: of the parent context of B<ssl>.
   30: 
   31: =head1 NOTES
   32: 
   33: When a new session is established between client and server, the server
   34: generates a session id. The session id is an arbitrary sequence of bytes.
   35: The length of the session id is 16 bytes for SSLv2 sessions and between
   36: 1 and 32 bytes for SSLv3/TLSv1. The session id is not security critical
   37: but must be unique for the server. Additionally, the session id is
   38: transmitted in the clear when reusing the session so it must not contain
   39: sensitive information.
   40: 
   41: Without a callback being set, an OpenSSL server will generate a unique
   42: session id from pseudo random numbers of the maximum possible length.
   43: Using the callback function, the session id can be changed to contain
   44: additional information like e.g. a host id in order to improve load balancing
   45: or external caching techniques.
   46: 
   47: The callback function receives a pointer to the memory location to put
   48: B<id> into and a pointer to the maximum allowed length B<id_len>. The
   49: buffer at location B<id> is only guaranteed to have the size B<id_len>.
   50: The callback is only allowed to generate a shorter id and reduce B<id_len>;
   51: the callback B<must never> increase B<id_len> or write to the location
   52: B<id> exceeding the given limit.
   53: 
   54: If a SSLv2 session id is generated and B<id_len> is reduced, it will be
   55: restored after the callback has finished and the session id will be padded
   56: with 0x00. It is not recommended to change the B<id_len> for SSLv2 sessions.
   57: The callback can use the L<SSL_get_version(3)|SSL_get_version(3)> function
   58: to check, whether the session is of type SSLv2.
   59: 
   60: The location B<id> is filled with 0x00 before the callback is called, so the
   61: callback may only fill part of the possible length and leave B<id_len>
   62: untouched while maintaining reproducibility.
   63: 
   64: Since the sessions must be distinguished, session ids must be unique.
   65: Without the callback a random number is used, so that the probability
   66: of generating the same session id is extremely small (2^128 possible ids
   67: for an SSLv2 session, 2^256 for SSLv3/TLSv1). In order to assure the
   68: uniqueness of the generated session id, the callback must call
   69: SSL_has_matching_session_id() and generate another id if a conflict occurs.
   70: If an id conflict is not resolved, the handshake will fail.
   71: If the application codes e.g. a unique host id, a unique process number, and
   72: a unique sequence number into the session id, uniqueness could easily be
   73: achieved without randomness added (it should however be taken care that
   74: no confidential information is leaked this way). If the application can not
   75: guarantee uniqueness, it is recommended to use the maximum B<id_len> and
   76: fill in the bytes not used to code special information with random data
   77: to avoid collisions.
   78: 
   79: SSL_has_matching_session_id() will only query the internal session cache,
   80: not the external one. Since the session id is generated before the
   81: handshake is completed, it is not immediately added to the cache. If
   82: another thread is using the same internal session cache, a race condition
   83: can occur in that another thread generates the same session id.
   84: Collisions can also occur when using an external session cache, since
   85: the external cache is not tested with SSL_has_matching_session_id()
   86: and the same race condition applies.
   87: 
   88: When calling SSL_has_matching_session_id() for an SSLv2 session with
   89: reduced B<id_len>, the match operation will be performed using the
   90: fixed length required and with a 0x00 padded id.
   91: 
   92: The callback must return 0 if it cannot generate a session id for whatever
   93: reason and return 1 on success.
   94: 
   95: =head1 EXAMPLES
   96: 
   97: The callback function listed will generate a session id with the
   98: server id given, and will fill the rest with pseudo random bytes:
   99: 
  100:  const char session_id_prefix = "www-18";
  101: 
  102:  #define MAX_SESSION_ID_ATTEMPTS 10
  103:  static int generate_session_id(const SSL *ssl, unsigned char *id,
  104:                               unsigned int *id_len)
  105:       {
  106:       unsigned int count = 0;
  107:       const char *version;
  108: 
  109:       version = SSL_get_version(ssl);
  110:       if (!strcmp(version, "SSLv2"))
  111:           /* we must not change id_len */;
  112: 
  113:       do      {
  114:               RAND_pseudo_bytes(id, *id_len);
  115:               /* Prefix the session_id with the required prefix. NB: If our
  116:                * prefix is too long, clip it - but there will be worse effects
  117:                * anyway, eg. the server could only possibly create 1 session
  118:                * ID (ie. the prefix!) so all future session negotiations will
  119:                * fail due to conflicts. */
  120:               memcpy(id, session_id_prefix,
  121:                       (strlen(session_id_prefix) < *id_len) ?
  122:                       strlen(session_id_prefix) : *id_len);
  123:               }
  124:       while(SSL_has_matching_session_id(ssl, id, *id_len) &&
  125:               (++count < MAX_SESSION_ID_ATTEMPTS));
  126:       if(count >= MAX_SESSION_ID_ATTEMPTS)
  127:               return 0;
  128:       return 1;
  129:       }
  130: 
  131: 
  132: =head1 RETURN VALUES
  133: 
  134: SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
  135: always return 1.
  136: 
  137: SSL_has_matching_session_id() returns 1 if another session with the
  138: same id is already in the cache.
  139: 
  140: =head1 SEE ALSO
  141: 
  142: L<ssl(3)|ssl(3)>, L<SSL_get_version(3)|SSL_get_version(3)>
  143: 
  144: =head1 HISTORY
  145: 
  146: SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id()
  147: and SSL_has_matching_session_id() have been introduced in
  148: OpenSSL 0.9.7.
  149: 
  150: =cut