=head1 NAME
-SSL_CONF_cmd_value_type, SSL_CONF_finish,
+SSL_CONF_cmd_value_type,
SSL_CONF_cmd - send configuration command
=head1 SYNOPSIS
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
SSL_CONF_cmd_value_type() returns the type of value that B<cmd> 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<cmd> names for command lines (i.e. when the
The syntax of B<value> is identical to B<-sigalgs>. If not set then
the value set for B<-sigalgs> will be used instead.
+=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.
+
+The B<value> argument is a colon separated list of groups. The group can be
+either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
+applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). 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.
+
=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.
+This is a synonym for the "-groups" command.
-The B<value> argument is a colon separated list of curves. The curve can be
-either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
-B<prime256v1>). Curve names are case sensitive.
=item B<-named_curve>
=item B<-cipher>
-Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
-currently not performed unless a B<SSL> or B<SSL_CTX> structure is
+Sets the TLSv1.2 and below ciphersuite list to B<value>. This list will be
+combined with any configured TLSv1.3 ciphersuites. Note: syntax checking
+of B<value> is currently not performed unless a B<SSL> or B<SSL_CTX> structure is
associated with B<cctx>.
+=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.
+
+
=item B<-cert>
Attempts to use the file B<value> as the certificate for the appropriate
length on send. A B<value> of 0 or 1 turns off padding. Otherwise, the
B<value> must be >1 or <=16384.
+=item B<-no_renegotiation>
+
+Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
+B<SSL_OP_NO_RENEGOTIATION>.
+
=item B<-min_protocol>, B<-max_protocol>
Sets the minimum and maximum supported protocol.
signature algorithm or elliptic curve to use for an incoming connection.
Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. 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<SSL_OP_PRIORITIZE_CHACHA>.
+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.
clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>.
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<SSL_CERT_FLAG_TLS_STRICT>.
+=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<SSL_OP_NO_ANTI_REPLAY>.
+
=back
=head1 SUPPORTED CONFIGURATION FILE COMMANDS
=item B<CipherString>
-Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is
-currently not performed unless an B<SSL> or B<SSL_CTX> structure is
-associated with B<cctx>.
+Sets the ciphersuite list for TLSv1.2 and below to B<value>. This list will be
+combined with any configured TLSv1.3 ciphersuites. Note: syntax
+checking of B<value> is currently not performed unless an B<SSL> or B<SSL_CTX>
+structure is associated with B<cctx>.
+
+=item B<Ciphersuites>
+
+Sets the available ciphersuites for TLSv1.3 to B<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.
=item B<Certificate>
length on send. A B<value> of 0 or 1 turns off padding. Otherwise, the
B<value> must be >1 or <=16384.
+=item B<NoRenegotiation>
+
+Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
+B<SSL_OP_NO_RENEGOTIATION>.
+
=item B<SignatureAlgorithms>
This sets the supported signature algorithms for TLS v1.2. For clients this
The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then
the value set for B<SignatureAlgorithms> will be used instead.
-=item B<Curves>
+=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.
-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<value> argument is a colon separated list of groups. The group can be
+either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
+applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). 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.
+
+=item B<Curves>
-The B<value> argument is a colon separated list of curves. The curve can be
-either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g
-B<prime256v1>). Curve names are case sensitive.
+This is a synonym for the "Groups" command.
=item B<MinProtocol>
B<DHSingle>: enable single use DH keys, set by default. Inverse of
B<SSL_OP_DH_SINGLE>. Only used by servers.
-B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of
+B<ECDHSingle>: enable single use ECDH keys, set by default. Inverse of
B<SSL_OP_ECDH_SINGLE>. Only used by servers.
-B<ServerPreference> use server and not client preference order when
+B<ServerPreference>: 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<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers.
-B<NoResumptionOnRenegotiation> set
+B<PrioritizeChaCha>: 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<SSL_OP_PRIORITIZE_CHACHA>.
+Only used by servers.
+
+B<NoResumptionOnRenegotiation>: set
B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers.
-B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation.
+B<UnsafeLegacyRenegotiation>: permits the use of unsafe legacy renegotiation.
Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
-B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation
+B<UnsafeLegacyServerConnect>: permits the use of unsafe legacy renegotiation
for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>.
Set by default.
default. Inverse of B<SSL_OP_NO_ENCRYPT_THEN_MAC>: that is,
B<-EncryptThenMac> is the same as setting B<SSL_OP_NO_ENCRYPT_THEN_MAC>.
+B<AllowNoDHEKEX>: 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<SSL_OP_ALLOW_NO_DHE_KEX>.
+
+B<MiddleboxCompat>: 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<SSL_OP_ENABLE_MIDDLEBOX_COMPAT>.
+
+B<AntiReplay>: 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<SSL_OP_NO_ANTI_REPLAY>.
+
=item B<VerifyMode>
The B<value> argument is a comma separated list of flags to set.
B<Once> requests a certificate from a client only on the initial connection:
not when renegotiating. Servers only.
+B<RequestPostHandshake> 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<RequiresPostHandshake> 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<ClientCAFile>, B<ClientCAPath>
A file or directory of certificates in PEM format whose names are used as the
ignored.
By checking the return code of SSL_CONF_cmd() it is possible to query if a
-given B<cmd> is recognised, this is useful is SSL_CONF_cmd() values are
+given B<cmd> 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
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<cmd> is recognised and B<value> is
error in the syntax of B<value> 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<SSL_CONF_CTX_new(3)>,
B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0.
+B<AllowNoDHEKEX> and B<PrioritizeChaCha> 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
this file except in compliance with the License. You can obtain a copy
projects / openssl.git / blobdiff