lib/libssl/man/SSL_SESSION_get_id.3

   1 .\" $OpenBSD: SSL_SESSION_get_id.3,v 1.6 2018/03/24 00:55:37 schwarze Exp $
   2 .\" full merge up to:
   3 .\" OpenSSL SSL_SESSION_set1_id 17b60280 Dec 21 09:08:25 2017 +0100
   4 .\"
   5 .\" This file was written by Remi Gacogne <rgacogne-github@coredump.fr>
   6 .\" and Matt Caswell <matt@openssl.org>.
   7 .\" Copyright (c) 2016, 2017 The OpenSSL Project.  All rights reserved.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\"
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\"
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in
  18 .\"    the documentation and/or other materials provided with the
  19 .\"    distribution.
  20 .\"
  21 .\" 3. All advertising materials mentioning features or use of this
  22 .\"    software must display the following acknowledgment:
  23 .\"    "This product includes software developed by the OpenSSL Project
  24 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  25 .\"
  26 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  27 .\"    endorse or promote products derived from this software without
  28 .\"    prior written permission. For written permission, please contact
  29 .\"    openssl-core@openssl.org.
  30 .\"
  31 .\" 5. Products derived from this software may not be called "OpenSSL"
  32 .\"    nor may "OpenSSL" appear in their names without prior written
  33 .\"    permission of the OpenSSL Project.
  34 .\"
  35 .\" 6. Redistributions of any form whatsoever must retain the following
  36 .\"    acknowledgment:
  37 .\"    "This product includes software developed by the OpenSSL Project
  38 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  39 .\"
  40 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  41 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  43 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  44 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  46 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  47 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  48 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  49 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  51 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  52 .\"
  53 .Dd $Mdocdate: March 24 2018 $
  54 .Dt SSL_SESSION_GET_ID 3
  55 .Os
  56 .Sh NAME
  57 .Nm SSL_SESSION_get_id ,
  58 .Nm SSL_SESSION_set1_id
  59 .Nd get and set the SSL session ID
  60 .Sh SYNOPSIS
  61 .In openssl/ssl.h
  62 .Ft const unsigned char *
  63 .Fo SSL_SESSION_get_id
  64 .Fa "const SSL_SESSION *s"
  65 .Fa "unsigned int *len"
  66 .Fc
  67 .Ft int
  68 .Fo SSL_SESSION_set1_id
  69 .Fa "SSL_SESSION *s"
  70 .Fa "const unsigned char *sid"
  71 .Fa "unsigned int sid_len"
  72 .Fc
  73 .Sh DESCRIPTION
  74 .Fn SSL_SESSION_get_id
  75 returns a pointer to the internal session ID value for the session
  76 .Fa s .
  77 The length of the ID in bytes is stored in
  78 .Pf * Fa len .
  79 The length may be 0.
  80 The caller should not free the returned pointer directly.
  81 .Pp
  82 .Fn SSL_SESSION_set1_id
  83 sets the session ID for
  84 .Fa s
  85 to a copy of the
  86 .Fa sid
  87 of length
  88 .Fa sid_len .
  89 .Sh RETURN VALUES
  90 .Fn SSL_SESSION_get_id
  91 returns a pointer to the session ID value.
  92 .Pp
  93 .Fn SSL_SESSION_set1_id
  94 returns 1 for success and 0 for failure,
  95 for example if the supplied session ID length exceeds
  96 .Dv SSL_MAX_SSL_SESSION_ID_LENGTH .
  97 .Sh SEE ALSO
  98 .Xr ssl 3 ,
  99 .Xr SSL_copy_session_id 3 ,
 100 .Xr SSL_get_session 3 ,
 101 .Xr SSL_SESSION_get_compress_id 3 ,
 102 .Xr SSL_SESSION_get_protocol_version 3 ,
 103 .Xr SSL_SESSION_has_ticket 3 ,
 104 .Xr SSL_SESSION_new 3
 105 .Sh HISTORY
 106 .Fn SSL_SESSION_get_id
 107 first appeared in OpenSSL 0.9.8 and has been available since
 108 .Ox 4.5 .
 109 .Pp
 110 .Fn SSL_SESSION_set1_id
 111 first appeared in OpenSSL 1.1.0 and has been available since
 112 .Ox 6.3 .