X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FSSL_CONF_cmd.pod;h=ea1f1e8503fde6e4f86c2c6bcb379f5fa8a4e341;hp=6731cf724ae3c4b96c0a7d3adbdbb4979a15f5f2;hb=1903a9b77af1aa289ce858de90790f3e2749fea9;hpb=47f7cf051bbb5d67778f6250c3c85341afea86d6 diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod index 6731cf724a..ea1f1e8503 100644 --- a/doc/man3/SSL_CONF_cmd.pod +++ b/doc/man3/SSL_CONF_cmd.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_CONF_cmd_value_type, SSL_CONF_finish, +SSL_CONF_cmd_value_type, SSL_CONF_cmd - send configuration command =head1 SYNOPSIS @@ -11,7 +11,6 @@ SSL_CONF_cmd - send configuration command int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value); int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd); - int SSL_CONF_finish(SSL_CONF_CTX *cctx); =head1 DESCRIPTION @@ -22,10 +21,6 @@ framework for command line options or configuration files. SSL_CONF_cmd_value_type() returns the type of value that B refers to. -The function SSL_CONF_finish() must be called after all configuration -operations have been completed. It is used to finalise any operations -or to process defaults. - =head1 SUPPORTED COMMAND LINE COMMANDS Currently supported B names for command lines (i.e. when the @@ -38,61 +33,64 @@ prefix for command line commands is B<-> and that is reflected below. =item B<-sigalgs> -This sets the supported signature algorithms for TLS v1.2. For clients this +This sets the supported signature algorithms for TLSv1.2 and TLSv1.3. +For clients this value is used directly for the supported signature algorithms extension. For servers it is used to determine which signature algorithms to support. The B argument should be a colon separated list of signature algorithms -in order of decreasing preference of the form B. B +in order of decreasing preference of the form B or +B. B is one of B, B or B and B is a supported algorithm OID short name such as B, B, B, B of B. Note: algorithm and hash names are case sensitive. +B is one of the signature schemes defined in TLSv1.3, +specified using the IETF name, e.g., B, B, +or B. If this option is not set then all signature algorithms supported by the OpenSSL library are permissible. +Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by +using B as the B or by using one of the B +identifiers) are ignored in TLSv1.3 and will not be negotiated. + =item B<-client_sigalgs> This sets the supported signature algorithms associated with client -authentication for TLS v1.2. For servers the value is used in the supported -signature algorithms field of a certificate request. For clients it is -used to determine which signature algorithm to with the client certificate. +authentication for TLSv1.2 and TLSv1.3. +For servers the value is used in the +B field of a B message. +For clients it is +used to determine which signature algorithm to use with the client certificate. If a server does not request a certificate this option has no effect. The syntax of B is identical to B<-sigalgs>. If not set then the value set for B<-sigalgs> will be used instead. -=item B<-curves> - -This sets the supported elliptic curves. For clients the curves are -sent using the supported curves extension. For servers it is used -to determine which curve to use. This setting affects curves used for both -signatures and key exchange, if applicable. - -The B argument is a colon separated list of curves. 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<-groups> This sets the supported groups. For clients, the groups are sent using the supported groups extension. For servers, it is used -to determine which group to use. This setting affects groups used for both -signatures and key exchange, if applicable. It also affects the preferred -key_share sent by a client in a TLSv1.3 compatible connection. +to determine which group to use. This setting affects groups used for +signatures (in TLSv1.2 and earlier) and key exchange. The first group listed +will also be used for the B sent by a client in a TLSv1.3 +B. The B argument is a colon separated list of groups. The group can be either the B name (e.g. B), some other commonly used name where -applicable (e.g. B) or an OpenSSL OID name (e.g B). Group -names are case sensitive. The list should be in order of preference with the -most preferred group first. The first listed group will be the one used for a -key_share by a TLSv1.3 client. +applicable (e.g. B, B) or an OpenSSL OID name +(e.g B). Group names are case sensitive. The list should be in +order of preference with the most preferred group first. + +Currently supported groups for B are B, B, B, +B, B, B, B, B, B, +B. =item B<-curves> This is a synonym for the "-groups" command. - =item B<-named_curve> This sets the temporary curve used for ephemeral ECDH modes. Only used by @@ -105,10 +103,19 @@ 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 +Sets the TLSv1.2 and below ciphersuite list to B. This list will be +combined with any configured TLSv1.3 ciphersuites. Note: syntax checking +of B is currently not performed unless a B or B structure is associated with B. +=item B<-ciphersuites> + +Sets the available ciphersuites for TLSv1.3 to value. This is a simple colon +(":") separated list of TLSv1.3 ciphersuite names in order of preference. This +list will be combined any configured TLSv1.2 and below ciphersuites. +See L for more information. + + =item B<-cert> Attempts to use the file B as the certificate for the appropriate @@ -132,17 +139,22 @@ operations are permitted. =item B<-record_padding> -Attempts to pad TLS 1.3 records so that they are a multiple of B in +Attempts to pad TLSv1.3 records so that they are a multiple of B in length on send. A B of 0 or 1 turns off padding. Otherwise, the B must be >1 or <=16384. +=item B<-no_renegotiation> + +Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +B. + =item B<-min_protocol>, B<-max_protocol> Sets the minimum and maximum supported protocol. Currently supported protocol values are B, B, -B, B for TLS and B, B for DTLS, +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 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. @@ -182,6 +194,13 @@ Use server and not client preference order when determining which cipher suite, signature algorithm or elliptic curve to use for an incoming connection. Equivalent to B. Only used by servers. +=item B<-prioritize_chacha> + +Prioritize ChaCha ciphers when the client has a ChaCha20 cipher at the top of +its preference list. This usually indicates a client without AES hardware +acceleration (e.g. mobile) is in use. Equivalent to B. +Only used by servers. Requires B<-serverpref>. + =item B<-no_resumption_on_reneg> set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers. @@ -197,11 +216,28 @@ permits or prohibits the use of unsafe legacy renegotiation for OpenSSL clients only. Equivalent to setting or clearing B. Set by default. +=item B<-allow_no_dhe_kex> + +In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means +that there will be no forward secrecy for the resumed session. + =item B<-strict> enables strict mode protocol handling. Equivalent to setting B. +=item B<-anti_replay>, B<-no_anti_replay> + +Switches replay protection, on or off respectively. With replay protection on, +OpenSSL will automatically detect if a session ticket has been used more than +once, TLSv1.3 has been negotiated, and early data is enabled on the server. A +full handshake is forced if a session ticket is used a second or subsequent +time. Anti-Replay is on by default unless overridden by a configuration file and +is only used by servers. Anti-replay measures are required for compliance with +the TLSv1.3 specification. Some applications may be able to mitigate the replay +risks in other ways and in such cases the built-in OpenSSL functionality is not +required. Switching off anti-replay is equivalent to B. + =back =head1 SUPPORTED CONFIGURATION FILE COMMANDS @@ -218,9 +254,17 @@ 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 -associated with B. +Sets the ciphersuite list for TLSv1.2 and below to B. This list will be +combined with any configured TLSv1.3 ciphersuites. Note: syntax +checking of B is currently not performed unless an B or B +structure is associated with B. + +=item B + +Sets the available ciphersuites for TLSv1.3 to B. This is a simple colon +(":") separated list of TLSv1.3 ciphersuite names in order of preference. This +list will be combined any configured TLSv1.2 and below ciphersuites. +See L for more information. =item B @@ -264,31 +308,43 @@ operations are permitted. =item B -Attempts to pad TLS 1.3 records so that they are a multiple of B in +Attempts to pad TLSv1.3 records so that they are a multiple of B in length on send. A B of 0 or 1 turns off padding. Otherwise, the B must be >1 or <=16384. =item B -This sets the supported signature algorithms for TLS v1.2. For clients this +This sets the supported signature algorithms for TLSv1.2 and TLSv1.3. +For clients this value is used directly for the supported signature algorithms extension. For servers it is used to determine which signature algorithms to support. The B argument should be a colon separated list of signature algorithms -in order of decreasing preference of the form B. B +in order of decreasing preference of the form B or +B. B is one of B, B or B and B is a supported algorithm OID short name such as B, B, B, B of B. Note: algorithm and hash names are case sensitive. +B is one of the signature schemes defined in TLSv1.3, +specified using the IETF name, e.g., B, B, +or B. If this option is not set then all signature algorithms supported by the OpenSSL library are permissible. +Note: algorithms which specify a PKCS#1 v1.5 signature scheme (either by +using B as the B or by using one of the B +identifiers) are ignored in TLSv1.3 and will not be negotiated. + =item B This sets the supported signature algorithms associated with client -authentication for TLS v1.2. For servers the value is used in the supported -signature algorithms field of a certificate request. For clients it is -used to determine which signature algorithm to with the client certificate. +authentication for TLSv1.2 and TLSv1.3. +For servers the value is used in the +B field of a B message. +For clients it is +used to determine which signature algorithm to use with the client certificate. +If a server does not request a certificate this option has no effect. The syntax of B is identical to B. If not set then the value set for B will be used instead. @@ -297,16 +353,20 @@ the value set for B will be used instead. This sets the supported groups. For clients, the groups are sent using the supported groups extension. For servers, it is used -to determine which group to use. This setting affects groups used for both -signatures and key exchange, if applicable. It also affects the preferred -key_share sent by a client in a TLSv1.3 compatible connection. +to determine which group to use. This setting affects groups used for +signatures (in TLSv1.2 and earlier) and key exchange. The first group listed +will also be used for the B sent by a client in a TLSv1.3 +B. The B argument is a colon separated list of groups. The group can be either the B name (e.g. B), some other commonly used name where -applicable (e.g. B) or an OpenSSL OID name (e.g B). Group -names are case sensitive. The list should be in order of preference with the -most preferred group first. The first listed group will be the one used for a -key_share by a TLSv1.3 client. +applicable (e.g. B, B) or an OpenSSL OID name +(e.g B). Group names are case sensitive. The list should be in +order of preference with the most preferred group first. + +Currently supported groups for B are B, B, B, +B, B, B, B, B, B, +B. =item B @@ -317,7 +377,7 @@ This is a synonym for the "Groups" command. This sets the minimum supported SSL, TLS or DTLS version. Currently supported protocol values are B, B, B, -B, B and B. +B, B, B and B. The value B will disable the limit. =item B @@ -325,7 +385,7 @@ The value B will disable the limit. This sets the maximum supported SSL, TLS or DTLS version. Currently supported protocol values are B, B, B, -B, B and B. +B, B, B and B. The value B will disable the limit. =item B @@ -344,7 +404,7 @@ Only enabling some protocol versions does not disable the other protocol versions. Currently supported protocol values are B, B, B, -B, B and 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 @@ -383,21 +443,29 @@ B: enable various bug workarounds. Same as B. B: enable single use DH keys, set by default. Inverse of B. Only used by servers. -B enable single use ECDH keys, set by default. Inverse of +B: enable single use ECDH keys, set by default. Inverse of B. Only used by servers. -B use server and not client preference order when +B: use server and not client preference order when determining which cipher suite, signature algorithm or elliptic curve to use for an incoming connection. Equivalent to B. Only used by servers. -B set +B: prioritizes ChaCha ciphers when the client has a +ChaCha20 cipher at the top of its preference list. This usually indicates +a mobile client is in use. Equivalent to B. +Only used by servers. + +B: set B flag. Only used by servers. -B permits the use of unsafe legacy renegotiation. +B: disables all attempts at renegotiation in TLSv1.2 and +earlier, same as setting B. + +B: permits the use of unsafe legacy renegotiation. Equivalent to B. -B permits the use of unsafe legacy renegotiation +B: permits the use of unsafe legacy renegotiation for OpenSSL clients only. Equivalent to B. Set by default. @@ -405,6 +473,29 @@ B: use encrypt-then-mac extension, enabled by default. Inverse of B: that is, B<-EncryptThenMac> is the same as setting B. +B: In TLSv1.3 allow a non-(ec)dhe based key exchange mode on +resumption. This means that there will be no forward secrecy for the resumed +session. Equivalent to B. + +B: If set then dummy Change Cipher Spec (CCS) messages are sent +in TLSv1.3. This has the effect of making TLSv1.3 look more like TLSv1.2 so that +middleboxes that do not understand TLSv1.3 will not drop the connection. This +option is set by default. A future version of OpenSSL may not set this by +default. Equivalent to B. + +B: If set then OpenSSL will automatically detect if a session ticket +has been used more than once, TLSv1.3 has been negotiated, and early data is +enabled on the server. A full handshake is forced if a session ticket is used a +second or subsequent time. This option is set by default and is only used by +servers. Anti-replay measures are required to comply with the TLSv1.3 +specification. Some applications may be able to mitigate the replay risks in +other ways and in such cases the built-in OpenSSL functionality is not required. +Disabling anti-replay is equivalent to setting B. + +B: use extended master secret extension, enabled by +default. Inverse of B: that is, +B<-ExtendedMasterSecret> is the same as setting B. + =item B The B argument is a comma separated list of flags to set. @@ -420,6 +511,18 @@ 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. +B configures the connection to support requests but does +not require a certificate from the client post-handshake. A certificate will +not be requested during the initial handshake. The server application must +provide a mechanism to request a certificate post-handshake. Servers only. +TLSv1.3 only. + +B configures the connection to support requests and +requires a certificate from the client post-handshake: an error occurs if the +client does not present a certificate. A certificate will not be requested +during the initial handshake. The server application must provide a mechanism +to request a certificate post-handshake. Servers only. TLSv1.3 only. + =item B, B A file or directory of certificates in PEM format whose names are used as the @@ -446,7 +549,7 @@ The value is a string without any specific structure. =item B -The value is a file name. +The value is a filename. =item B @@ -477,7 +580,7 @@ SSLv3 is B disabled and attempt to override this by the user are ignored. By checking the return code of SSL_CONF_cmd() it is possible to query if a -given B is recognised, this is useful is SSL_CONF_cmd() values are +given B is recognised, this is useful if SSL_CONF_cmd() values are mixed with additional application specific operations. For example an application might call SSL_CONF_cmd() and if it returns @@ -503,6 +606,23 @@ checking or translation of the command value. For example if the return value is B an application could translate a relative pathname to an absolute pathname. +=head1 RETURN VALUES + +SSL_CONF_cmd() returns 1 if the value of B is recognised and B is +B used and 2 if both B and B are used. In other words it +returns the number of arguments processed. This is useful when processing +command lines. + +A return value of -2 means B is not recognised. + +A return value of -3 means B is recognised and the command requires a +value but B is NULL. + +A return code of 0 indicates that both B and B are valid but an +error occurred attempting to perform the operation: for example due to an +error in the syntax of B in this case the error queue may provide +additional information. + =head1 EXAMPLES Set supported signature algorithms: @@ -549,31 +669,9 @@ Set supported curves to P-256, P-384: SSL_CONF_cmd(ctx, "Curves", "P-256:P-384"); -Set automatic support for any elliptic curve for key exchange: - - SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic"); - -=head1 RETURN VALUES - -SSL_CONF_cmd() returns 1 if the value of B is recognised and B is -B used and 2 if both B and B are used. In other words it -returns the number of arguments processed. This is useful when processing -command lines. - -A return value of -2 means B is not recognised. - -A return value of -3 means B is recognised and the command requires a -value but B is NULL. - -A return code of 0 indicates that both B and B are valid but an -error occurred attempting to perform the operation: for example due to an -error in the syntax of B in this case the error queue may provide -additional information. - -SSL_CONF_finish() returns 1 for success and 0 for failure. - =head1 SEE ALSO +L, L, L, L, @@ -583,22 +681,24 @@ L =head1 HISTORY -SSL_CONF_cmd() was first added to OpenSSL 1.0.2 +The SSL_CONF_cmd() function was added in OpenSSL 1.0.2. -B doesn't have effect since 1.1.0, but the macro is retained -for backwards compatibility. +The B option 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 +The B was added in 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. +B and B were added in OpenSSL 1.1.1. + =head1 COPYRIGHT -Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2012-2018 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at L.