lib/libssl/man/SSL_set_shutdown.3

   1 .\"     $OpenBSD: SSL_set_shutdown.3,v 1.2 2016/12/04 12:20:54 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2001, 2005 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: December 4 2016 $
  52 .Dt SSL_SET_SHUTDOWN 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_set_shutdown ,
  56 .Nm SSL_get_shutdown
  57 .Nd manipulate shutdown state of an SSL connection
  58 .Sh SYNOPSIS
  59 .In openssl/ssl.h
  60 .Ft void
  61 .Fn SSL_set_shutdown "SSL *ssl" "int mode"
  62 .Ft int
  63 .Fn SSL_get_shutdown "const SSL *ssl"
  64 .Sh DESCRIPTION
  65 .Fn SSL_set_shutdown
  66 sets the shutdown state of
  67 .Fa ssl
  68 to
  69 .Fa mode .
  70 .Pp
  71 .Fn SSL_get_shutdown
  72 returns the shutdown mode of
  73 .Fa ssl .
  74 .Pp
  75 The shutdown state of an ssl connection is a bitmask of:
  76 .Bl -tag -width Ds
  77 .It 0
  78 No shutdown setting, yet.
  79 .It Dv SSL_SENT_SHUTDOWN
  80 A
  81 .Dq close notify
  82 shutdown alert was sent to the peer; the connection is being considered closed
  83 and the session is closed and correct.
  84 .It Dv SSL_RECEIVED_SHUTDOWN
  85 A shutdown alert was received form the peer, either a normal
  86 .Dq close notify
  87 or a fatal error.
  88 .El
  89 .Pp
  90 .Dv SSL_SENT_SHUTDOWN
  91 and
  92 .Dv SSL_RECEIVED_SHUTDOWN
  93 can be set at the same time.
  94 .Pp
  95 The shutdown state of the connection is used to determine the state of the
  96 .Fa ssl
  97 session.
  98 If the session is still open when
  99 .Xr SSL_clear 3
 100 or
 101 .Xr SSL_free 3
 102 is called, it is considered bad and removed according to RFC2246.
 103 The actual condition for a correctly closed session is
 104 .Dv SSL_SENT_SHUTDOWN
 105 (according to the TLS RFC, it is acceptable to only send the
 106 .Dq close notify
 107 alert but to not wait for the peer's answer when the underlying connection is
 108 closed).
 109 .Fn SSL_set_shutdown
 110 can be used to set this state without sending a close alert to the peer (see
 111 .Xr SSL_shutdown 3 ) .
 112 .Pp
 113 If a
 114 .Dq close notify
 115 was received,
 116 .Dv SSL_RECEIVED_SHUTDOWN
 117 will be set, but to set
 118 .Dv SSL_SENT_SHUTDOWN
 119 the application must still call
 120 .Xr SSL_shutdown 3
 121 or
 122 .Fn SSL_set_shutdown
 123 itself.
 124 .Sh RETURN VALUES
 125 .Fn SSL_set_shutdown
 126 does not return diagnostic information.
 127 .Pp
 128 .Fn SSL_get_shutdown
 129 returns the current setting.
 130 .Sh SEE ALSO
 131 .Xr ssl 3 ,
 132 .Xr SSL_clear 3 ,
 133 .Xr SSL_CTX_set_quiet_shutdown 3 ,
 134 .Xr SSL_free 3 ,
 135 .Xr SSL_shutdown 3