1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimSSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only) 6e71b7053SJung-uk Kim 7e71b7053SJung-uk Kim=head1 SYNOPSIS 8e71b7053SJung-uk Kim 9e71b7053SJung-uk Kim #include <openssl/ssl.h> 10e71b7053SJung-uk Kim 11e71b7053SJung-uk Kim int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, 12e71b7053SJung-uk Kim unsigned int sid_ctx_len); 13e71b7053SJung-uk Kim int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, 14e71b7053SJung-uk Kim unsigned int sid_ctx_len); 15e71b7053SJung-uk Kim 16e71b7053SJung-uk Kim=head1 DESCRIPTION 17e71b7053SJung-uk Kim 18e71b7053SJung-uk KimSSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length 19e71b7053SJung-uk KimB<sid_ctx_len> within which a session can be reused for the B<ctx> object. 20e71b7053SJung-uk Kim 21e71b7053SJung-uk KimSSL_set_session_id_context() sets the context B<sid_ctx> of length 22e71b7053SJung-uk KimB<sid_ctx_len> within which a session can be reused for the B<ssl> object. 23e71b7053SJung-uk Kim 24e71b7053SJung-uk Kim=head1 NOTES 25e71b7053SJung-uk Kim 26e71b7053SJung-uk KimSessions are generated within a certain context. When exporting/importing 27e71b7053SJung-uk Kimsessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible, 28e71b7053SJung-uk Kimto re-import a session generated from another context (e.g. another 2958f35182SJung-uk Kimapplication), which might lead to malfunctions. Therefore, each application 30e71b7053SJung-uk Kimmust set its own session id context B<sid_ctx> which is used to distinguish 31e71b7053SJung-uk Kimthe contexts and is stored in exported sessions. The B<sid_ctx> can be 32e71b7053SJung-uk Kimany kind of binary data with a given length, it is therefore possible 33e71b7053SJung-uk Kimto use e.g. the name of the application and/or the hostname and/or service 34e71b7053SJung-uk Kimname ... 35e71b7053SJung-uk Kim 36e71b7053SJung-uk KimThe session id context becomes part of the session. The session id context 37e71b7053SJung-uk Kimis set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and 38e71b7053SJung-uk KimSSL_set_session_id_context() functions are therefore only useful on the 39e71b7053SJung-uk Kimserver side. 40e71b7053SJung-uk Kim 41e71b7053SJung-uk KimOpenSSL clients will check the session id context returned by the server 42e71b7053SJung-uk Kimwhen reusing a session. 43e71b7053SJung-uk Kim 44e71b7053SJung-uk KimThe maximum length of the B<sid_ctx> is limited to 45da327cd2SJung-uk KimB<SSL_MAX_SID_CTX_LENGTH>. 46e71b7053SJung-uk Kim 47e71b7053SJung-uk Kim=head1 WARNINGS 48e71b7053SJung-uk Kim 49e71b7053SJung-uk KimIf the session id context is not set on an SSL/TLS server and client 50e71b7053SJung-uk Kimcertificates are used, stored sessions 51e71b7053SJung-uk Kimwill not be reused but a fatal error will be flagged and the handshake 52e71b7053SJung-uk Kimwill fail. 53e71b7053SJung-uk Kim 54e71b7053SJung-uk KimIf a server returns a different session id context to an OpenSSL client 55e71b7053SJung-uk Kimwhen reusing a session, an error will be flagged and the handshake will 56e71b7053SJung-uk Kimfail. OpenSSL servers will always return the correct session id context, 57e71b7053SJung-uk Kimas an OpenSSL server checks the session id context itself before reusing 58e71b7053SJung-uk Kima session as described above. 59e71b7053SJung-uk Kim 60e71b7053SJung-uk Kim=head1 RETURN VALUES 61e71b7053SJung-uk Kim 62e71b7053SJung-uk KimSSL_CTX_set_session_id_context() and SSL_set_session_id_context() 63e71b7053SJung-uk Kimreturn the following values: 64e71b7053SJung-uk Kim 65e71b7053SJung-uk Kim=over 4 66e71b7053SJung-uk Kim 67e71b7053SJung-uk Kim=item Z<>0 68e71b7053SJung-uk Kim 69e71b7053SJung-uk KimThe length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded 70da327cd2SJung-uk Kimthe maximum allowed length of B<SSL_MAX_SID_CTX_LENGTH>. The error 71e71b7053SJung-uk Kimis logged to the error stack. 72e71b7053SJung-uk Kim 73e71b7053SJung-uk Kim=item Z<>1 74e71b7053SJung-uk Kim 75e71b7053SJung-uk KimThe operation succeeded. 76e71b7053SJung-uk Kim 77e71b7053SJung-uk Kim=back 78e71b7053SJung-uk Kim 79e71b7053SJung-uk Kim=head1 SEE ALSO 80e71b7053SJung-uk Kim 81e71b7053SJung-uk KimL<ssl(7)> 82e71b7053SJung-uk Kim 83e71b7053SJung-uk Kim=head1 COPYRIGHT 84e71b7053SJung-uk Kim 8558f35182SJung-uk KimCopyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved. 86e71b7053SJung-uk Kim 87*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 88e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 89e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 90e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 91e71b7053SJung-uk Kim 92e71b7053SJung-uk Kim=cut 93