X-Git-Url: https://git.openssl.org/?a=blobdiff_plain;f=doc%2Fssl%2FSSL_CONF_cmd.pod;h=4f83f5996719b55224ad24c4505c6e63dd21d414;hb=ed233db7421b98b2058da2a07f6c46b52917b918;hp=552d4a890c2c54668d40c57dd69527bf929fb99e;hpb=ba1cb9a5531de859abe8d3e09821e7ba47d72bbf;p=openssl.git diff --git a/doc/ssl/SSL_CONF_cmd.pod b/doc/ssl/SSL_CONF_cmd.pod index 552d4a890c..4f83f59967 100644 --- a/doc/ssl/SSL_CONF_cmd.pod +++ b/doc/ssl/SSL_CONF_cmd.pod @@ -74,7 +74,7 @@ B). Curve names are case sensitive. =item B<-named_curve> -This sets the temporary curve used for ephemeral ECDH modes. Only used by +This sets the temporary curve used for ephemeral ECDH modes. Only used by servers The B argument is a curve name or the special value B which @@ -85,14 +85,14 @@ can be either the B name (e.g. B) or an OpenSSL OID name =item B<-cipher> Sets the cipher suite list to B. Note: syntax checking of B is -currently not performed unless a B or B structure is +currently not performed unless a B or B structure is associated with B. =item B<-cert> Attempts to use the file B as the certificate for the appropriate -context. It currently uses SSL_CTX_use_cerificate_chain_file if an B -structure is set or SSL_use_certifcate_file with filetype PEM if an B +context. It currently uses SSL_CTX_use_certificate_chain_file() if an B +structure is set or SSL_use_certificate_file() with filetype PEM if an B structure is set. This option is only supported if certificate operations are permitted. @@ -101,7 +101,7 @@ are permitted. Attempts to use the file B as the private key for the appropriate context. This option is only supported if certificate operations are permitted. Note: if no B<-key> option is set then a private key is -not loaded: it does not currently use the B<-cert> file. +not loaded unless the flag B is set. =item B<-dhparam> @@ -109,19 +109,40 @@ Attempts to use the file B as the set of temporary DH parameters for the appropriate context. This option is only supported if certificate operations are permitted. -=item B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> +=item B<-min_protocol>, B<-max_protocol> -Disables protocol support for SSLv2, SSLv3, TLS 1.0, TLS 1.1 or TLS 1.2 -by setting the corresponding options B, B, -B, B and B respectively. +Sets the minimum and maximum supported protocol. +Currently supported protocol values are B, B, +B, B for TLS and B, B for DTLS, +and B for no limit. +If the either bound is not specified then only the other bound applies, +if specified. +To restrict the supported protocol versions use these commands rather +than the deprecated alternative commands below. + +=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> + +Disables protocol support for SSLv3, TLS 1.0, TLS 1.1 or TLS 1.2 +by setting the corresponding options B, B, +B and B respectively. +These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>. =item B<-bugs> Various bug workarounds are set, same as setting B. +=item B<-comp> + +Enables support for SSL/TLS compression, same as clearing +B. +This command was introduced in OpenSSL 1.1.0. +As of OpenSSL 1.1.0, compression is off by default. + =item B<-no_comp> -Disables support for SSL/TLS compression, same as setting B. +Disables support for SSL/TLS compression, same as setting +B. +As of OpenSSL 1.1.0, compression is off by default. =item B<-no_ticket> @@ -153,20 +174,13 @@ Set by default. enables strict mode protocol handling. Equivalent to setting B. -=item B<-debug_broken_protocol> - -disables various checks and permits several kinds of broken protocol behaviour -for testing purposes: it should B be used in anything other than a test -environment. Only supported if OpenSSL is configured with -B<-DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL>. - =back =head1 SUPPORTED CONFIGURATION FILE COMMANDS Currently supported B names for configuration files (i.e. when the flag B is set) are listed below. All configuration file -B names and are case insensitive so B is recognised +B names are case insensitive so B is recognised as well as B. Unless otherwise stated the B names are also case insensitive. @@ -177,14 +191,14 @@ Note: the command prefix (if set) alters the recognised B values. =item B Sets the cipher suite list to B. Note: syntax checking of B is -currently not performed unless an B or B structure is +currently not performed unless an B or B structure is associated with B. =item B Attempts to use the file B as the certificate for the appropriate -context. It currently uses SSL_CTX_use_cerificate_chain_file if an B -structure is set or SSL_use_certifcate_file with filetype PEM if an B +context. It currently uses SSL_CTX_use_certificate_chain_file() if an B +structure is set or SSL_use_certificate_file() with filetype PEM if an B structure is set. This option is only supported if certificate operations are permitted. @@ -192,8 +206,14 @@ are permitted. Attempts to use the file B as the private key for the appropriate context. This option is only supported if certificate operations -are permitted. Note: if no B<-key> option is set then a private key is -not loaded: it does not currently use the B file. +are permitted. Note: if no B option is set then a private key is +not loaded unless the B is set. + +=item B, B, B, B + +These options indicate a file or directory used for building certificate +chains or verifying certificate chains. These options are only supported +if certificate operations are permitted. =item B @@ -244,7 +264,7 @@ B). Curve names are case sensitive. =item B -This sets the temporary curve used for ephemeral ECDH modes. Only used by +This sets the temporary curve used for ephemeral ECDH modes. Only used by servers The B argument is a curve name or the special value B which @@ -252,22 +272,57 @@ picks an appropriate curve based on client and server preferences. The curve can be either the B name (e.g. B) or an OpenSSL OID name (e.g B). Curve names are case sensitive. +=item B + +This sets the minimum supported SSL, TLS or DTLS version. + +Currently supported protocol values are B, B, B, +B, B and B. +The value B will disable the limit. + +=item B + +This sets the maximum supported SSL, TLS or DTLS version. + +Currently supported protocol values are B, B, B, +B, B and B. +The value B will disable the limit. + =item B -The supported versions of the SSL or TLS protocol. +This can be used to enable or disable certain versions of the SSL, +TLS or DTLS protocol. + +The B argument is a comma separated list of supported protocols +to enable or disable. +If a protocol is preceded by B<-> that version is disabled. -The B argument is a comma separated list of supported protocols to -enable or disable. If an protocol is preceded by B<-> that version is disabled. -All versions are enabled by default, though applications may choose to -explicitly disable some. Currently supported protocol values are B, -B, B, B and B. The special value B refers -to all supported versions. +All protocol versions are enabled by default. +You need to disable at least one protocol version for this setting have any +effect. +Only enabling some protocol versions does not disable the other protocol +versions. + +Currently supported protocol values are B, B, B, +B, B and B. +The special value B refers to all supported versions. + +This can't enable protocols that are disabled using B +or B, but can disable protocols that are still allowed +by them. + +The B command is fragile and deprecated; do not use it. +Use B and B instead. +If you do use B, make sure that the resulting range of enabled +protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make +sure to also leave TLS 1.1 enabled. =item B The B argument is a comma separated list of various flags to set. -If a flag string is preceded B<-> it is disabled. See the -B function for more details of individual options. +If a flag string is preceded B<-> it is disabled. +See the L function for more details of +individual options. Each option is listed below. Where an operation is enabled by default the B<-flag> syntax is needed to disable it. @@ -306,6 +361,27 @@ B permits the use of unsafe legacy renegotiation for OpenSSL clients only. Equivalent to B. Set by default. +=item B + +The B argument is a comma separated list of flags to set. + +B enables peer verification: for clients only. + +B requests but does not require a certificate from the client. +Servers only. + +B requests and requires a certificate from the client: an error +occurs if the client does not present a certificate. Servers only. + +B requests a certificate from a client only on the initial connection: +not when renegotiating. Servers only. + +=item B, B + +A file or directory of certificates in PEM format whose names are used as the +set of acceptable names for client CAs. Servers only. This option is only +supported if certificate operations are permitted. + =back =head1 SUPPORTED COMMAND TYPES @@ -332,6 +408,11 @@ The value is a file name. The value is a directory name. +=item B + +The value string is not used e.g. a command line option which doesn't take an +argument. + =back =head1 NOTES @@ -339,16 +420,16 @@ The value is a directory name. The order of operations is significant. This can be used to set either defaults or values which cannot be overridden. For example if an application calls: - SSL_CONF_cmd(ctx, "Protocol", "-SSLv2"); + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); SSL_CONF_cmd(ctx, userparam, uservalue); -it will disable SSLv2 support by default but the user can override it. If +it will disable SSLv3 support by default but the user can override it. If however the call sequence is: SSL_CONF_cmd(ctx, userparam, uservalue); - SSL_CONF_cmd(ctx, "Protocol", "-SSLv2"); + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); -SSLv2 is B disabled and attempt to override this by the user are +SSLv3 is B disabled and attempt to override this by the user are ignored. By checking the return code of SSL_CTX_cmd() it is possible to query if a @@ -372,7 +453,7 @@ can be checked instead. If -3 is returned a required argument is missing and an error is indicated. If 0 is returned some other error occurred and this can be reported back to the user. -The function SSL_CONF_cmd_value_type() can be used by applications to +The function SSL_CONF_cmd_value_type() can be used by applications to check for the existence of a command or to perform additional syntax checking or translation of the command value. For example if the return value is B an application could translate a relative @@ -384,18 +465,42 @@ Set supported signature algorithms: SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); -Enable all protocols except SSLv3 and SSLv2: +There are various ways to select the supported procotols. + +This set the minimum protocol version to TLSv1, and so disables SSLv3. +This is the recommended way to disable protocols. + + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1"); - SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2"); +The following also disables SSLv3: + + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); + +The following will first enable all protocols, and then disable +SSLv3. +If no protocol versions were disabled before this has the same effect as +"-SSLv3", but if some versions were disables this will re-enable them before +disabling SSLv3. + + SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3"); Only enable TLSv1.2: + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2"); + SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2"); + +This also only enables TLSv1.2: + SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2"); Disable TLS session tickets: SSL_CONF_cmd(ctx, "Options", "-SessionTicket"); +Enable compression: + + SSL_CONF_cmd(ctx, "Options", "Compression"); + Set supported curves to P-256, P-384: SSL_CONF_cmd(ctx, "Curves", "P-256:P-384"); @@ -425,14 +530,24 @@ SSL_CONF_finish() returns 1 for success and 0 for failure. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L =head1 HISTORY SSL_CONF_cmd() was first added to OpenSSL 1.0.2 +B doesn't have effect since 1.1.0, but the macro is retained +for backwards compatibility. + +B was first added to OpenSSL 1.1.0. In earlier versions of +OpenSSL passing a command which didn't take an argument would return +B. + +B and B where added in OpenSSL 1.1.0. + =cut