lib/libssl/man/SSL_set_tmp_ecdh.3

   1 .\"     $OpenBSD: SSL_set_tmp_ecdh.3,v 1.5 2018/03/23 14:28:16 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: March 23 2018 $
  18 .Dt SSL_SET_TMP_ECDH 3
  19 .Os
  20 .Sh NAME
  21 .Nm SSL_set_tmp_ecdh ,
  22 .Nm SSL_CTX_set_tmp_ecdh ,
  23 .Nm SSL_set_ecdh_auto ,
  24 .Nm SSL_CTX_set_ecdh_auto ,
  25 .Nm SSL_set_tmp_ecdh_callback ,
  26 .Nm SSL_CTX_set_tmp_ecdh_callback
  27 .Nd select a curve for ECDH ephemeral key exchange
  28 .Sh SYNOPSIS
  29 .In openssl/ssl.h
  30 .Ft long
  31 .Fo SSL_set_tmp_ecdh
  32 .Fa "SSL *ssl"
  33 .Fa "EC_KEY *ecdh"
  34 .Fc
  35 .Ft long
  36 .Fo SSL_CTX_set_tmp_ecdh
  37 .Fa "SSL_CTX *ctx"
  38 .Fa "EC_KEY *ecdh"
  39 .Fc
  40 .Ft long
  41 .Fo SSL_set_ecdh_auto
  42 .Fa "SSL *ssl"
  43 .Fa "int state"
  44 .Fc
  45 .Ft long
  46 .Fo SSL_CTX_set_ecdh_auto
  47 .Fa "SSL_CTX *ctx"
  48 .Fa "int state"
  49 .Fc
  50 .Ft void
  51 .Fo SSL_set_tmp_ecdh_callback
  52 .Fa "SSL *ssl"
  53 .Fa "EC_KEY *(*ecdh)(SSL *ssl, int is_export, int keylength)"
  54 .Fc
  55 .Ft void
  56 .Fo SSL_CTX_set_tmp_ecdh_callback
  57 .Fa "SSL_CTX *ctx"
  58 .Fa "EC_KEY *(*ecdh)(SSL *ssl, int is_export, int keylength)"
  59 .Fc
  60 .Sh DESCRIPTION
  61 Automatic EC curve selection and generation is always enabled in
  62 LibreSSL, and applications cannot manually provide EC keys for use
  63 with ECDHE key exchange.
  64 .Pp
  65 The only remaining effect of
  66 .Fn SSL_set_tmp_ecdh
  67 is that the curve of the given
  68 .Fa ecdh
  69 key becomes the only curve enabled for the
  70 .Fa ssl
  71 connection, so it is equivalent to calling
  72 .Xr SSL_set1_groups_list 3
  73 with the same single curve name.
  74 .Pp
  75 .Fn SSL_CTX_set_tmp_ecdh
  76 has the same effect on all connections that will be created from
  77 .Fa ctx
  78 in the future.
  79 .Pp
  80 The functions
  81 .Fn SSL_set_ecdh_auto ,
  82 .Fn SSL_CTX_set_ecdh_auto ,
  83 .Fn SSL_set_tmp_ecdh_callback ,
  84 and
  85 .Fn SSL_CTX_set_tmp_ecdh_callback
  86 are deprecated and have no effect.
  87 .Sh RETURN VALUES
  88 .Fn SSL_set_tmp_ecdh
  89 and
  90 .Fn SSL_CTX_set_tmp_ecdh
  91 return 1 on success or 0 on failure.
  92 .Pp
  93 .Fn SSL_set_ecdh_auto ,
  94 .Fn SSL_CTX_set_ecdh_auto ,
  95 .Fn SSL_set_tmp_ecdh_callback ,
  96 and
  97 .Fn SSL_CTX_set_tmp_ecdh_callback
  98 always return 1.
  99 .Sh SEE ALSO
 100 .Xr ssl 3 ,
 101 .Xr SSL_CTX_set1_groups 3 ,
 102 .Xr SSL_CTX_set_cipher_list 3 ,
 103 .Xr SSL_CTX_set_options 3 ,
 104 .Xr SSL_CTX_set_tmp_dh_callback 3 ,
 105 .Xr SSL_new 3
 106 .Sh HISTORY
 107 .Fn SSL_set_tmp_ecdh ,
 108 .Fn SSL_CTX_set_tmp_ecdh ,
 109 .Fn SSL_set_tmp_ecdh_callback ,
 110 and
 111 .Fn SSL_CTX_set_tmp_ecdh_callback
 112 first appeared in OpenSSL 0.9.8 and have been available since
 113 .Ox 4.5 .
 114 .Pp
 115 .Fn SSL_CTX_set_ecdh_auto
 116 and
 117 .Fn SSL_set_ecdh_auto
 118 first appeared in OpenSSL 1.0.2 and have been available since
 119 .Ox 5.7 .