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