SSL_CONF_cmd.pod revision 289848
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, TLS 1.0, TLS 1.1 or TLS 1.2 115by setting the corresponding options B<SSL_OP_NO_SSL2>, B<SSL_OP_NO_SSL3>, 116B<SSL_OP_NO_TLS1>, B<SSL_OP_NO_TLS1_1> and B<SSL_OP_NO_TLS1_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. 261All versions are enabled by default, though applications may choose to 262explicitly disable some. Currently supported protocol values are B<SSLv2>, 263B<SSLv3>, B<TLSv1>, B<TLSv1.1> and B<TLSv1.2>. The special value B<ALL> refers 264to all supported versions. 265 266=item B<Options> 267 268The B<value> argument is a comma separated list of various flags to set. 269If a flag string is preceded B<-> it is disabled. See the 270B<SSL_CTX_set_options> function for more details of individual options. 271 272Each option is listed below. Where an operation is enabled by default 273the B<-flag> syntax is needed to disable it. 274 275B<SessionTicket>: session ticket support, enabled by default. Inverse of 276B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting 277B<SSL_OP_NO_TICKET>. 278 279B<Compression>: SSL/TLS compression support, enabled by default. Inverse 280of B<SSL_OP_NO_COMPRESSION>. 281 282B<EmptyFragments>: use empty fragments as a countermeasure against a 283SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It 284is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>. 285 286B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>. 287 288B<DHSingle>: enable single use DH keys, set by default. Inverse of 289B<SSL_OP_DH_SINGLE>. Only used by servers. 290 291B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of 292B<SSL_OP_ECDH_SINGLE>. Only used by servers. 293 294B<ServerPreference> use server and not client preference order when 295determining which cipher suite, signature algorithm or elliptic curve 296to use for an incoming connection. Equivalent to 297B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers. 298 299B<NoResumptionOnRenegotiation> set 300B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers. 301 302B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation. 303Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>. 304 305B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation 306for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>. 307Set by default. 308 309=back 310 311=head1 SUPPORTED COMMAND TYPES 312 313The function SSL_CONF_cmd_value_type() currently returns one of the following 314types: 315 316=over 4 317 318=item B<SSL_CONF_TYPE_UNKNOWN> 319 320The B<cmd> string is unrecognised, this return value can be use to flag 321syntax errors. 322 323=item B<SSL_CONF_TYPE_STRING> 324 325The value is a string without any specific structure. 326 327=item B<SSL_CONF_TYPE_FILE> 328 329The value is a file name. 330 331=item B<SSL_CONF_TYPE_DIR> 332 333The value is a directory name. 334 335=back 336 337=head1 NOTES 338 339The order of operations is significant. This can be used to set either defaults 340or values which cannot be overridden. For example if an application calls: 341 342 SSL_CONF_cmd(ctx, "Protocol", "-SSLv2"); 343 SSL_CONF_cmd(ctx, userparam, uservalue); 344 345it will disable SSLv2 support by default but the user can override it. If 346however the call sequence is: 347 348 SSL_CONF_cmd(ctx, userparam, uservalue); 349 SSL_CONF_cmd(ctx, "Protocol", "-SSLv2"); 350 351SSLv2 is B<always> disabled and attempt to override this by the user are 352ignored. 353 354By checking the return code of SSL_CTX_cmd() it is possible to query if a 355given B<cmd> is recognised, this is useful is SSL_CTX_cmd() values are 356mixed with additional application specific operations. 357 358For example an application might call SSL_CTX_cmd() and if it returns 359-2 (unrecognised command) continue with processing of application specific 360commands. 361 362Applications can also use SSL_CTX_cmd() to process command lines though the 363utility function SSL_CTX_cmd_argv() is normally used instead. One way 364to do this is to set the prefix to an appropriate value using 365SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the 366following argument to B<value> (which may be NULL). 367 368In this case if the return value is positive then it is used to skip that 369number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is 370returned then B<cmd> is not recognised and application specific arguments 371can be checked instead. If -3 is returned a required argument is missing 372and an error is indicated. If 0 is returned some other error occurred and 373this can be reported back to the user. 374 375The function SSL_CONF_cmd_value_type() can be used by applications to 376check for the existence of a command or to perform additional syntax 377checking or translation of the command value. For example if the return 378value is B<SSL_CONF_TYPE_FILE> an application could translate a relative 379pathname to an absolute pathname. 380 381=head1 EXAMPLES 382 383Set supported signature algorithms: 384 385 SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); 386 387Enable all protocols except SSLv3 and SSLv2: 388 389 SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2"); 390 391Only enable TLSv1.2: 392 393 SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2"); 394 395Disable TLS session tickets: 396 397 SSL_CONF_cmd(ctx, "Options", "-SessionTicket"); 398 399Set supported curves to P-256, P-384: 400 401 SSL_CONF_cmd(ctx, "Curves", "P-256:P-384"); 402 403Set automatic support for any elliptic curve for key exchange: 404 405 SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic"); 406 407=head1 RETURN VALUES 408 409SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is 410B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it 411returns the number of arguments processed. This is useful when processing 412command lines. 413 414A return value of -2 means B<cmd> is not recognised. 415 416A return value of -3 means B<cmd> is recognised and the command requires a 417value but B<value> is NULL. 418 419A return code of 0 indicates that both B<cmd> and B<value> are valid but an 420error occurred attempting to perform the operation: for example due to an 421error in the syntax of B<value> in this case the error queue may provide 422additional information. 423 424SSL_CONF_finish() returns 1 for success and 0 for failure. 425 426=head1 SEE ALSO 427 428L<SSL_CONF_CTX_new(3)|SSL_CONF_CTX_new(3)>, 429L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>, 430L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>, 431L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>, 432L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)> 433 434=head1 HISTORY 435 436SSL_CONF_cmd() was first added to OpenSSL 1.0.2 437 438=cut 439