[thirdparty/openssl.git] / doc / man3 / SSL_CTX_set_cipher_list.pod

=pod

=head1 NAME

SSL_CTX_set_cipher_list,
SSL_set_cipher_list,
SSL_CTX_set_ciphersuites,
SSL_set_ciphersuites,
OSSL_default_cipher_list,
OSSL_default_ciphersuites
- choose list of available SSL_CIPHERs

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
 int SSL_set_cipher_list(SSL *ssl, const char *str);

 int SSL_CTX_set_ciphersuites(SSL_CTX *ctx, const char *str);
 int SSL_set_ciphersuites(SSL *s, const char *str);

 const char *OSSL_default_cipher_list(void);
 const char *OSSL_default_ciphersuites(void);

=head1 DESCRIPTION

SSL_CTX_set_cipher_list() sets the list of available ciphers (TLSv1.2 and below)
for B<ctx> using the control string B<str>. The format of the string is described
in L<ciphers(1)>. The list of ciphers is inherited by all
B<ssl> objects created from B<ctx>. This function does not impact TLSv1.3
ciphersuites. Use SSL_CTX_set_ciphersuites() to configure those.

SSL_set_cipher_list() sets the list of ciphers (TLSv1.2 and below) only for
B<ssl>.

SSL_CTX_set_ciphersuites() is used to configure the available TLSv1.3
ciphersuites for B<ctx>. This is a simple colon (":") separated list of TLSv1.3
ciphersuite names in order of perference. Valid TLSv1.3 ciphersuite names are:

=over 4

=item TLS_AES_128_GCM_SHA256

=item TLS_AES_256_GCM_SHA384

=item TLS_CHACHA20_POLY1305_SHA256

=item TLS_AES_128_CCM_SHA256

=item TLS_AES_128_CCM_8_SHA256

=back

An empty list is permissible. The default value for the this setting is:

"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

SSL_set_ciphersuites() is the same as SSL_CTX_set_ciphersuites() except it
configures the ciphersuites for B<ssl>.

OSSL_default_cipher_list() returns the default cipher string for TLSv1.2
(and earlier) ciphers. OSSL_default_ciphersuites() returns the default
cipher string for TLSv1.3 ciphersuites.

=head1 NOTES

The control string B<str> for SSL_CTX_set_cipher_list() and
SSL_set_cipher_list() should be universally usable and not depend
on details of the library configuration (ciphers compiled in). Thus no
syntax checking takes place. Items that are not recognized, because the
corresponding ciphers are not compiled in or because they are mistyped,
are simply ignored. Failure is only flagged if no ciphers could be collected
at all.

It should be noted, that inclusion of a cipher to be used into the list is
a necessary condition. On the client side, the inclusion into the list is
also sufficient unless the security level excludes it. On the server side,
additional restrictions apply. All ciphers have additional requirements.
ADH ciphers don't need a certificate, but DH-parameters must have been set.
All other ciphers need a corresponding certificate and key.

A RSA cipher can only be chosen, when a RSA certificate is available.
RSA ciphers using DHE need a certificate and key and additional DH-parameters
(see L<SSL_CTX_set_tmp_dh_callback(3)>).

A DSA cipher can only be chosen, when a DSA certificate is available.
DSA ciphers always use DH key exchange and therefore need DH-parameters
(see L<SSL_CTX_set_tmp_dh_callback(3)>).

When these conditions are not met for any cipher in the list (e.g. a
client only supports export RSA ciphers with an asymmetric key length
of 512 bits and the server is not configured to use temporary RSA
keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
and the handshake will fail.

OSSL_default_cipher_list() and OSSL_default_ciphersuites() replace
SSL_DEFAULT_CIPHER_LIST and TLS_DEFAULT_CIPHERSUITES, respectively. The
cipher list defines are deprecated as of 3.0.0.

=head1 RETURN VALUES

SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
could be selected and 0 on complete failure.

SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() return 1 if the requested
ciphersuite list was configured, and 0 otherwise.

=head1 SEE ALSO

L<ssl(7)>, L<SSL_get_ciphers(3)>,
L<SSL_CTX_use_certificate(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)>,
L<ciphers(1)>

=head1 HISTORY

OSSL_default_cipher_list() and OSSL_default_ciphersites() are new in 3.0.0.

=head1 COPYRIGHT

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.

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<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
615513ba RL	1	=pod
	2
	3	=head1 NAME
	4
9d2674cd MC	5	SSL_CTX_set_cipher_list,
	6	SSL_set_cipher_list,
	7	SSL_CTX_set_ciphersuites,
5d120511 TS	8	SSL_set_ciphersuites,
	9	OSSL_default_cipher_list,
	10	OSSL_default_ciphersuites
9d2674cd	11	- choose list of available SSL_CIPHERs
615513ba RL	12
	13	=head1 SYNOPSIS
	14
	15	#include <openssl/ssl.h>
	16
	17	int SSL_CTX_set_cipher_list(SSL_CTX ctx, const char str);
	18	int SSL_set_cipher_list(SSL ssl, const char str);
	19
9d2674cd MC	20	int SSL_CTX_set_ciphersuites(SSL_CTX ctx, const char str);
	21	int SSL_set_ciphersuites(SSL s, const char str);
	22
5d120511 TS	23	const char *OSSL_default_cipher_list(void);
	24	const char *OSSL_default_ciphersuites(void);
	25
615513ba RL	26	=head1 DESCRIPTION
615513ba RL	27
9d2674cd MC	28	SSL_CTX_set_cipher_list() sets the list of available ciphers (TLSv1.2 and below)
9d2674cd MC	29	for B<ctx> using the control string B<str>. The format of the string is described
9b86974e	30	in L<ciphers(1)>. The list of ciphers is inherited by all
9d2674cd MC	31	B<ssl> objects created from B<ctx>. This function does not impact TLSv1.3
	32	ciphersuites. Use SSL_CTX_set_ciphersuites() to configure those.
	33
	34	SSL_set_cipher_list() sets the list of ciphers (TLSv1.2 and below) only for
	35	B<ssl>.
	36
	37	SSL_CTX_set_ciphersuites() is used to configure the available TLSv1.3
	38	ciphersuites for B<ctx>. This is a simple colon (":") separated list of TLSv1.3
	39	ciphersuite names in order of perference. Valid TLSv1.3 ciphersuite names are:
	40
	41	=over 4
	42
	43	=item TLS_AES_128_GCM_SHA256
	44
	45	=item TLS_AES_256_GCM_SHA384
	46
	47	=item TLS_CHACHA20_POLY1305_SHA256
615513ba	48
9d2674cd MC	49	=item TLS_AES_128_CCM_SHA256
	50
	51	=item TLS_AES_128_CCM_8_SHA256
	52
	53	=back
	54
	55	An empty list is permissible. The default value for the this setting is:
	56
	57	"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
	58
	59	SSL_set_ciphersuites() is the same as SSL_CTX_set_ciphersuites() except it
	60	configures the ciphersuites for B<ssl>.
615513ba	61
5d120511 TS	62	OSSL_default_cipher_list() returns the default cipher string for TLSv1.2
	63	(and earlier) ciphers. OSSL_default_ciphersuites() returns the default
	64	cipher string for TLSv1.3 ciphersuites.
	65
615513ba RL	66	=head1 NOTES
615513ba RL	67
9d2674cd MC	68	The control string B<str> for SSL_CTX_set_cipher_list() and
9d2674cd MC	69	SSL_set_cipher_list() should be universally usable and not depend
615513ba RL	70	on details of the library configuration (ciphers compiled in). Thus no
615513ba RL	71	syntax checking takes place. Items that are not recognized, because the
c69c47b9	72	corresponding ciphers are not compiled in or because they are mistyped,
615513ba RL	73	are simply ignored. Failure is only flagged if no ciphers could be collected
	74	at all.
	75
dd3430a6 RL	76	It should be noted, that inclusion of a cipher to be used into the list is
dd3430a6 RL	77	a necessary condition. On the client side, the inclusion into the list is
0f817d3b DSH	78	also sufficient unless the security level excludes it. On the server side,
	79	additional restrictions apply. All ciphers have additional requirements.
	80	ADH ciphers don't need a certificate, but DH-parameters must have been set.
	81	All other ciphers need a corresponding certificate and key.
6d3dec92 LJ	82
6d3dec92 LJ	83	A RSA cipher can only be chosen, when a RSA certificate is available.
0b30fc90	84	RSA ciphers using DHE need a certificate and key and additional DH-parameters
9b86974e	85	(see L<SSL_CTX_set_tmp_dh_callback(3)>).
6d3dec92 LJ	86
6d3dec92 LJ	87	A DSA cipher can only be chosen, when a DSA certificate is available.
3e3dac9f	88	DSA ciphers always use DH key exchange and therefore need DH-parameters
9b86974e	89	(see L<SSL_CTX_set_tmp_dh_callback(3)>).
6d3dec92 LJ	90
6d3dec92 LJ	91	When these conditions are not met for any cipher in the list (e.g. a
b9b6a7e5	92	client only supports export RSA ciphers with an asymmetric key length
6d3dec92 LJ	93	of 512 bits and the server is not configured to use temporary RSA
	94	keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
	95	and the handshake will fail.
dd3430a6	96
5d120511 TS	97	OSSL_default_cipher_list() and OSSL_default_ciphersuites() replace
	98	SSL_DEFAULT_CIPHER_LIST and TLS_DEFAULT_CIPHERSUITES, respectively. The
	99	cipher list defines are deprecated as of 3.0.0.
	100
615513ba RL	101	=head1 RETURN VALUES
	102
	103	SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
	104	could be selected and 0 on complete failure.
	105
9d2674cd MC	106	SSL_CTX_set_ciphersuites() and SSL_set_ciphersuites() return 1 if the requested
	107	ciphersuite list was configured, and 0 otherwise.
	108
615513ba RL	109	=head1 SEE ALSO
615513ba RL	110
b97fdb57	111	L<ssl(7)>, L<SSL_get_ciphers(3)>,
9b86974e	112	L<SSL_CTX_use_certificate(3)>,
9b86974e RS	113	L<SSL_CTX_set_tmp_dh_callback(3)>,
9b86974e RS	114	L<ciphers(1)>
615513ba	115
5d120511 TS	116	=head1 HISTORY
	117
	118	OSSL_default_cipher_list() and OSSL_default_ciphersites() are new in 3.0.0.
	119
e2f92610 RS	120	=head1 COPYRIGHT
e2f92610 RS	121
b0edda11	122	Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
e2f92610	123
4746f25a	124	Licensed under the Apache License 2.0 (the "License"). You may not use
e2f92610 RS	125	this file except in compliance with the License. You can obtain a copy
	126	in the file LICENSE in the source distribution or at
	127	L<https://www.openssl.org/source/license.html>.
	128
	129	=cut