doc/ssl/SSL_CONF_cmd.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CONF_cmd - send configuration command
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ssl.h>
  10
  11  int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value);
  12
  13 =head1 DESCRIPTION
  14
  15 The function SSL_CONF_cmd() performs configuration operation B<cmd> with
  16 optional parameter B<value> on B<ctx>. Its purpose is to simplify application
  17 configuration of B<SSL_CTX> or B<SSL> structures by providing a common
  18 framework for command line options or configuration files.
  19
  20 =head1 SUPPORTED COMMAND LINE COMMANDS
  21
  22 Currently supported B<cmd> names for command lines (i.e. when the
  23 flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names
  24 and are case sensitive. Unless otherwise stated commands can be used by
  25 both clients and servers and the B<value> parameter is not used. The default
  26 prefix for command line commands is B<-> and that is reflected below.
  27
  28 =over 4
  29
  30 =item B<-sigalgs>
  31
  32 This sets the supported signature algorithms for TLS v1.2. For clients this
  33 value is used directly for the supported signature algorithms extension. For
  34 servers it is used to determine which signature algorithms to support.
  35
  36 The B<value> argument should be a colon separated list of signature algorithms
  37 in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
  38 is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
  39 OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
  40 Note: algorithm and hash names are case sensitive.
  41
  42 If this option is not set then all signature algorithms supported by the
  43 OpenSSL library are permissible.
  44
  45 =item B<-client_sigalgs>
  46
  47 This sets the supported signature algorithms associated with client
  48 authentication for TLS v1.2. For servers the value is used in the supported
  49 signature algorithms field of a certificate request. For clients it is
  50 used to determine which signature algorithm to with the client certificate.
  51 If a server does not request a certificate this option has no effect.
  52
  53 The syntax of B<value> is identical to B<-sigalgs>. If not set then
  54 the value set for B<-sigalgs> will be used instead.
  55
  56 =item B<-curves>
  57
  58 This sets the supported elliptic curves. For clients the curves are
  59 sent using the supported curves extension. For servers it is used
  60 to determine which curve to use. This setting affects curves used for both
  61 signatures and key exchange, if applicable.
  62
  63 The B<value> argument is a colon separated list of curves. The curve can be
  64 either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
  65 B<prime256v1>). Curve names are case sensitive.
  66
  67 =item B<-named_curve>
  68
  69 This sets the temporary curve used for ephemeral ECDH modes. Only used by
  70 servers
  71
  72 The B<value> argument is a curve name or the special value B<auto> which
  73 picks an appropriate curve based on client and server preferences. The curve
  74 can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
  75 (e.g B<prime256v1>). Curve names are case sensitive.
  76
  77 =item B<-cipher>
  78
  79 Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
  80 currently not performed unless a B<SSL> or B<SSL_CTX> structure is
  81 associated with B<cctx>.
  82
  83 =item B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
  84
  85 Disables protocol support for SSLv2, SSLv3, TLS 1.0, TLS 1.1 or TLS 1.2
  86 by setting the corresponding options B<SSL_OP_NO_SSL2>, B<SSL_OP_NO_SSL3>,
  87 B<SSL_OP_NO_TLS1>, B<SSL_OP_NO_TLS1_1> and B<SSL_OP_NO_TLS1_2> respectively.
  88
  89 =item B<-bugs>
  90
  91 Various bug workarounds are set, same as setting B<SSL_OP_ALL>.
  92
  93 =item B<-no_comp>
  94
  95 Disables support for SSL/TLS compression, same as setting B<SSL_OP_NO_COMPRESS>.
  96
  97 =item B<-no_ticket>
  98
  99 Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>.
 100
 101 =item B<-serverpref>
 102
 103 Use server and not client preference order when determining which cipher suite,
 104 signature algorithm or elliptic curve to use for an incoming connection.
 105 Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
 106
 107 =item B<-legacyrenegotiation>
 108
 109 permits the use of unsafe legacy renegotiation. Equivalent to setting
 110 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
 111
 112 =item B<-legacy_server_connect>, B<-no_legacy_server_connect>
 113
 114 permits or prohibits the use of unsafe legacy renegotiation for OpenSSL
 115 clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
 116 Set by default.
 117
 118 =item B<-strict>
 119
 120 enables strict mode protocol handling. Equivalent to setting
 121 B<SSL_CERT_FLAG_TLS_STRICT>.
 122
 123 =item B<-debug_broken_protocol>
 124
 125 disables various checks and permits several kinds of broken protocol behaviour
 126 for testing purposes: it should B<NEVER> be used in anything other than a test
 127 environment. Only supported if OpenSSL is configured with
 128 B<-DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL>.
 129
 130 =back
 131
 132 =head1 SUPPORTED CONFIGURATION FILE COMMANDS
 133
 134 Currently supported B<cmd> names for configuration files (i.e. when the
 135 flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file
 136 B<cmd> names and are case insensitive so B<signaturealgorithms> is recognised
 137 as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names
 138 are also case insensitive.
 139
 140 Note: the command prefix (if set) alters the recognised B<cmd> values.
 141
 142 =over 4
 143
 144 =item B<CipherString>
 145
 146 Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
 147 currently not performed unless an B<SSL> or B<SSL_CTX> structure is
 148 associated with B<cctx>.
 149
 150 =item B<SignatureAlgorithms>
 151
 152 This sets the supported signature algorithms for TLS v1.2. For clients this
 153 value is used directly for the supported signature algorithms extension. For
 154 servers it is used to determine which signature algorithms to support.
 155
 156 The B<value> argument should be a colon separated list of signature algorithms
 157 in order of decreasing preference of the form B<algorithm+hash>. B<algorithm>
 158 is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm
 159 OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>.
 160 Note: algorithm and hash names are case sensitive.
 161
 162 If this option is not set then all signature algorithms supported by the
 163 OpenSSL library are permissible.
 164
 165 =item B<ClientSignatureAlgorithms>
 166
 167 This sets the supported signature algorithms associated with client
 168 authentication for TLS v1.2. For servers the value is used in the supported
 169 signature algorithms field of a certificate request. For clients it is
 170 used to determine which signature algorithm to with the client certificate.
 171
 172 The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
 173 the value set for B<SignatureAlgorithms> will be used instead.
 174
 175 =item B<Curves>
 176
 177 This sets the supported elliptic curves. For clients the curves are
 178 sent using the supported curves extension. For servers it is used
 179 to determine which curve to use. This setting affects curves used for both
 180 signatures and key exchange, if applicable.
 181
 182 The B<value> argument is a colon separated list of curves. The curve can be
 183 either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
 184 B<prime256v1>). Curve names are case sensitive.
 185
 186 =item B<ECDHParameters>
 187
 188 This sets the temporary curve used for ephemeral ECDH modes. Only used by
 189 servers
 190
 191 The B<value> argument is a curve name or the special value B<Automatic> which
 192 picks an appropriate curve based on client and server preferences. The curve
 193 can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name
 194 (e.g B<prime256v1>). Curve names are case sensitive.
 195
 196 =item B<Protocol>
 197
 198 The supported versions of the SSL or TLS protocol.
 199
 200 The B<value> argument is a comma separated list of supported protocols to
 201 enable or disable. If an protocol is preceded by B<-> that version is disabled.
 202 All versions are enabled by default, though applications may choose to
 203 explicitly disable some. Currently supported protocol values are B<SSLv2>,
 204 B<SSLv3>, B<TLSv1>, B<TLSv1.1> and B<TLSv1.2>. The special value B<ALL> refers
 205 to all supported versions.
 206
 207 =item B<Options>
 208
 209 The B<value> argument is a comma separated list of various flags to set.
 210 If a flag string is preceded B<-> it is disabled. See the
 211 B<SSL_CTX_set_options> function for more details of individual options.
 212
 213 Each option is listed below. Where an operation is enabled by default
 214 the B<-flag> syntax is needed to disable it.
 215
 216 B<SessionTicket>: session ticket support, enabled by default. Inverse of
 217 B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting
 218 B<SSL_OP_NO_TICKET>.
 219
 220 B<Compression>: SSL/TLS compression support, enabled by default. Inverse
 221 of B<SSL_OP_NO_COMPRESSION>.
 222
 223 B<EmptyFragments>: use empty fragments as a countermeasure against a
 224 SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It
 225 is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>.
 226
 227 B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>.
 228
 229 B<DHSingle>: enable single use DH keys, set by default. Inverse of
 230 B<SSL_OP_DH_SINGLE>. Only used by servers.
 231
 232 B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of
 233 B<SSL_OP_ECDH_SINGLE>. Only used by servers.
 234
 235 B<ServerPreference> use server and not client preference order when
 236 determining which cipher suite, signature algorithm or elliptic curve
 237 to use for an incoming connection.  Equivalent to
 238 B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
 239
 240 B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation.
 241 Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
 242
 243 B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
 244 for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
 245 Set by default.
 246
 247 =back
 248
 249 =head1 NOTES
 250
 251 The order of operations is significant. This can be used to set either defaults
 252 or values which cannot be overridden. For example if an application calls:
 253
 254  SSL_CONF_cmd(ctx, "Protocol", "-SSLv2");
 255  SSL_CONF_cmd(ctx, userparam, uservalue);
 256
 257 it will disable SSLv2 support by default but the user can override it. If
 258 however the call sequence is:
 259
 260  SSL_CONF_cmd(ctx, userparam, uservalue);
 261  SSL_CONF_cmd(ctx, "Protocol", "-SSLv2");
 262
 263 SSLv2 is B<always> disabled and attempt to override this by the user are
 264 ignored.
 265
 266 By checking the return code of SSL_CTX_cmd() it is possible to query if a
 267 given B<cmd> is recognised, this is useful is SSL_CTX_cmd() values are
 268 mixed with additional application specific operations.
 269
 270 For example an application might call SSL_CTX_cmd() and if it returns
 271 -2 (unrecognised command) continue with processing of application specific
 272 commands.
 273
 274 Applications can also use SSL_CTX_cmd() to process command lines though the
 275 utility function SSL_CTX_cmd_argv() is normally used instead. One way
 276 to do this is to set the prefix to an appropriate value using
 277 SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the
 278 following argument to B<value> (which may be NULL).
 279
 280 In this case if the return value is positive then it is used to skip that
 281 number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is
 282 returned then B<cmd> is not recognised and application specific arguments
 283 can be checked instead. If -3 is returned a required argument is missing
 284 and an error is indicated. If 0 is returned some other error occurred and
 285 this can be reported back to the user.
 286
 287 =head1 EXAMPLES
 288
 289 Set supported signature algorithms:
 290
 291  SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256");
 292
 293 Enable all protocols except SSLv3 and SSLv2:
 294
 295  SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2");
 296
 297 Only enable TLSv1.2:
 298
 299  SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2");
 300
 301 Disable TLS session tickets:
 302
 303  SSL_CONF_cmd(ctx, "Options", "-SessionTicket");
 304
 305 Set supported curves to P-256, P-384:
 306
 307  SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
 308
 309 Set automatic support for any elliptic curve for key exchange:
 310
 311  SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic");
 312
 313 =head1 RETURN VALUES
 314
 315 SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
 316 B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
 317 returns the number of arguments processed. This is useful when processing
 318 command lines.
 319
 320 A return value of -2 means B<cmd> is not recognised.
 321
 322 A return value of -3 means B<cmd> is recognised and the command requires a
 323 value but B<value> is NULL.
 324
 325 A return code of 0 indicates that both B<cmd> and B<value> are valid but an
 326 error occurred attempting to perform the operation: for example due to an
 327 error in the syntax of B<value> in this case the error queue may provide
 328 additional information.
 329
 330 =head1 SEE ALSO
 331
 332 L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>,
 333 L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>,
 334 L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>,
 335 L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>,
 336 L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)>
 337
 338 =head1 HISTORY
 339
 340 SSL_CONF_cmd() was first added to OpenSSL 1.0.2
 341
 342 =cut