1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only)
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx,
   12:                                     unsigned int sid_ctx_len);
   13:  int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
   14:                                 unsigned int sid_ctx_len);
   15: 
   16: =head1 DESCRIPTION
   17: 
   18: SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length
   19: B<sid_ctx_len> within which a session can be reused for the B<ctx> object.
   20: 
   21: SSL_set_session_id_context() sets the context B<sid_ctx> of length
   22: B<sid_ctx_len> within which a session can be reused for the B<ssl> object.
   23: 
   24: =head1 NOTES
   25: 
   26: Sessions are generated within a certain context. When exporting/importing
   27: sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible,
   28: to re-import a session generated from another context (e.g. another
   29: application), which might lead to malfunctions. Therefore each application
   30: must set its own session id context B<sid_ctx> which is used to distinguish
   31: the contexts and is stored in exported sessions. The B<sid_ctx> can be
   32: any kind of binary data with a given length, it is therefore possible
   33: to use e.g. the name of the application and/or the hostname and/or service
   34: name ...
   35: 
   36: The session id context becomes part of the session. The session id context
   37: is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and
   38: SSL_set_session_id_context() functions are therefore only useful on the
   39: server side.
   40: 
   41: OpenSSL clients will check the session id context returned by the server
   42: when reusing a session.
   43: 
   44: The maximum length of the B<sid_ctx> is limited to
   45: B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
   46: 
   47: =head1 WARNINGS
   48: 
   49: If the session id context is not set on an SSL/TLS server and client
   50: certificates are used, stored sessions
   51: will not be reused but a fatal error will be flagged and the handshake
   52: will fail.
   53: 
   54: If a server returns a different session id context to an OpenSSL client
   55: when reusing a session, an error will be flagged and the handshake will
   56: fail. OpenSSL servers will always return the correct session id context,
   57: as an OpenSSL server checks the session id context itself before reusing
   58: a session as described above.
   59: 
   60: =head1 RETURN VALUES
   61: 
   62: SSL_CTX_set_session_id_context() and SSL_set_session_id_context()
   63: return the following values:
   64: 
   65: =over 4
   66: 
   67: =item 0
   68: 
   69: The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded
   70: the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error
   71: is logged to the error stack.
   72: 
   73: =item 1
   74: 
   75: The operation succeeded.
   76: 
   77: =back
   78: 
   79: =head1 SEE ALSO
   80: 
   81: L<ssl(3)|ssl(3)>
   82: 
   83: =cut