lib/libcrypto/man/ENGINE_set_default.3

   1 .\" $OpenBSD: ENGINE_set_default.3,v 1.3 2018/04/18 12:56:50 jmc Exp $
   2 .\" content checked up to:
   3 .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
   4 .\"
   5 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
   6 .\"
   7 .\" Permission to use, copy, modify, and distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  16 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: April 18 2018 $
  20 .Dt ENGINE 3
  21 .Os
  22 .Sh NAME
  23 .Nm ENGINE_set_default ,
  24 .Nm ENGINE_set_default_string ,
  25 .Nm ENGINE_set_default_RSA ,
  26 .Nm ENGINE_set_default_DSA ,
  27 .Nm ENGINE_set_default_ECDH ,
  28 .Nm ENGINE_set_default_ECDSA ,
  29 .Nm ENGINE_set_default_DH ,
  30 .Nm ENGINE_set_default_RAND ,
  31 .Nm ENGINE_set_default_ciphers ,
  32 .Nm ENGINE_set_default_digests
  33 .Nd register an ENGINE as the default for an algorithm
  34 .Sh SYNOPSIS
  35 .Ft int
  36 .Fo ENGINE_set_default_RSA
  37 .Fa "ENGINE *e"
  38 .Fc
  39 .Ft int
  40 .Fo ENGINE_set_default_DSA
  41 .Fa "ENGINE *e"
  42 .Fc
  43 .Ft int
  44 .Fo ENGINE_set_default_ECDH
  45 .Fa "ENGINE *e"
  46 .Fc
  47 .Ft int
  48 .Fo ENGINE_set_default_ECDSA
  49 .Fa "ENGINE *e"
  50 .Fc
  51 .Ft int
  52 .Fo ENGINE_set_default_DH
  53 .Fa "ENGINE *e"
  54 .Fc
  55 .Ft int
  56 .Fo ENGINE_set_default_RAND
  57 .Fa "ENGINE *e"
  58 .Fc
  59 .Ft int
  60 .Fo ENGINE_set_default_ciphers
  61 .Fa "ENGINE *e"
  62 .Fc
  63 .Ft int
  64 .Fo ENGINE_set_default_digests
  65 .Fa "ENGINE *e"
  66 .Fc
  67 .Ft int
  68 .Fo ENGINE_set_default
  69 .Fa "ENGINE *e"
  70 .Fa "unsigned int flags"
  71 .Fc
  72 .Ft int
  73 .Fo ENGINE_set_default_string
  74 .Fa "ENGINE *e"
  75 .Fa "const char *list"
  76 .Fc
  77 .Sh DESCRIPTION
  78 These functions register
  79 .Fa e
  80 as implementing the respective algorithm
  81 like the functions described in the
  82 .Xr ENGINE_register_RSA 3
  83 manual page do it.
  84 In addition, they call
  85 .Xr ENGINE_init 3
  86 on
  87 .Fa e
  88 and select
  89 .Fa e
  90 as the default implementation of the respective algorithm to be
  91 returned by the functions described in
  92 .Xr ENGINE_get_default_RSA 3
  93 in the future.
  94 If another engine was previously selected
  95 as the default implementation of the respective algorithm,
  96 .Xr ENGINE_finish 3
  97 is called on that previous engine.
  98 .Pp
  99 If
 100 .Fa e
 101 implements more than one cipher or digest,
 102 .Fn ENGINE_set_default_ciphers
 103 and
 104 .Fn ENGINE_set_default_digests
 105 register and select it for all these ciphers and digests, respectively.
 106 .Pp
 107 .Fn ENGINE_set_default
 108 registers
 109 .Fa e
 110 as the default implementation of all algorithms specified by the
 111 .Fa flags
 112 by calling the appropriate ones among the other functions.
 113 Algorithms can be selected by combining any number of the
 114 following constants with bitwise OR:
 115 .Dv ENGINE_METHOD_ALL ,
 116 .Dv ENGINE_METHOD_RSA ,
 117 .Dv ENGINE_METHOD_DSA ,
 118 .Dv ENGINE_METHOD_ECDH ,
 119 .Dv ENGINE_METHOD_ECDSA ,
 120 .Dv ENGINE_METHOD_DH ,
 121 .Dv ENGINE_METHOD_RAND ,
 122 .Dv ENGINE_METHOD_CIPHERS ,
 123 .Dv ENGINE_METHOD_DIGESTS ,
 124 .Dv ENGINE_METHOD_PKEY_METHS ,
 125 and
 126 .Dv ENGINE_METHOD_PKEY_ASN1_METHS .
 127 .Pp
 128 .Fn ENGINE_set_default_string
 129 is similar except that it selects the algorithms according to the string
 130 .Fa def_list ,
 131 which contains an arbitrary number of comma-separated keywords from
 132 the following list: ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS,
 133 DIGESTS, PKEY_CRYPTO, PKEY_ASN1, and PKEY.
 134 PKEY_CRYPTO corresponds to
 135 .Dv ENGINE_METHOD_PKEY_METHS ,
 136 PKEY_ASN1 to
 137 .Dv ENGINE_METHOD_PKEY_ASN1_METHS ,
 138 and PKEY selects both.
 139 .Sh RETURN VALUES
 140 These functions return 1 on success or 0 on error.
 141 They fail if
 142 .Xr ENGINE_init 3
 143 fails or if insufficient memory is available.
 144 .Sh SEE ALSO
 145 .Xr ENGINE_get_default_RSA 3 ,
 146 .Xr ENGINE_init 3 ,
 147 .Xr ENGINE_new 3 ,
 148 .Xr ENGINE_register_RSA 3 ,
 149 .Xr ENGINE_set_RSA 3 ,
 150 .Xr ENGINE_unregister_RSA 3
 151 .Sh HISTORY
 152 .Fn ENGINE_set_default ,
 153 .Fn ENGINE_set_default_RSA ,
 154 .Fn ENGINE_set_default_DSA ,
 155 .Fn ENGINE_set_default_DH ,
 156 and
 157 .Fn ENGINE_set_default_RAND
 158 first appeared in OpenSSL 0.9.7 and have been available since
 159 .Ox 2.9 .
 160 .Pp
 161 .Fn ENGINE_set_default_string ,
 162 .Fn ENGINE_set_default_ciphers ,
 163 and
 164 .Fn ENGINE_set_default_digests
 165 first appeared in OpenSSL 0.9.7 and have been available since
 166 .Ox 3.2 .
 167 .Pp
 168 .Fn ENGINE_set_default_ECDH
 169 and
 170 .Fn ENGINE_set_default_ECDSA
 171 first appeared in OpenSSL 0.9.8 and have been available since
 172 .Ox 4.5 .
 173 .Sh CAVEATS
 174 Failure of
 175 .Xr ENGINE_finish 3
 176 is ignored.
 177 .Sh BUGS
 178 Even when
 179 .Fn ENGINE_set_default
 180 or
 181 .Fn ENGINE_set_default_string
 182 fail, they typically still register
 183 .Fa e
 184 for some algorithms, but usually not for all it could be registered
 185 for by calling the individual functions.