From 7ba4144d71899fa7eb9e1f35c50e3633772aa283 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 12 Jan 2018 16:04:26 +0100 Subject: ssl: Add new API functions for cipher suite handling --- lib/ssl/doc/src/ssl.xml | 95 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 84 insertions(+), 11 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 8fcda78ed5..70bb4f759b 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -138,17 +138,20 @@ sslsocket() =

opaque()

 - protocol() = + protocol_version() =

sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'

 ciphers() = -

= [ciphersuite()] | string()

-

According to old API.

 +

= [ciphersuite()]

+

Tuples and string formats accepted by versions + before ssl-8.2.4 will be converted for backwards compatibility

 ciphersuite() = - -

{key_exchange(), cipher(), MAC::hash()} | - {key_exchange(), cipher(), MAC::hash(), PRF::hash()}

 +

+ #{key_exchange := key_exchange(), + cipher := cipher(), + mac := MAC::hash() | aead, + prf := PRF::hash() | default_prf}

key_exchange()=

rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk @@ -165,6 +168,12 @@ prf_random() =

client_random | server_random

 + cipher_filters() = +

[{key_exchange | cipher | mac | prf, algo_filter()}])

 + + algo_filter() = +

fun(key_exchange() | cipher() | hash() | aead | default_prf) -> true | false

+ srp_param_type() =

srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 | srp_6144 | srp_8192

 @@ -456,7 +465,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3 with the selected CA as trusted anchor and the rest of the chain.

- {versions, [protocol()]} + {versions, [protocol_version()]}

TLS protocol versions supported by started clients and servers. This option overrides the application environment option protocol_version. If the environment option is not set, it defaults @@ -829,14 +838,34 @@ fun(srp, Username :: string(), UserState :: term()) -> + + + append_cipher_suites(Deferred, Suites) -> ciphers() + + + Deferred = ciphers() | cipher_filters() + Suites = ciphers() + +

Make Deferred suites become the least preferred + suites, that is put them at the end of the cipher suite list + Suites after removing them from Suites if + present. Deferred may be a list of cipher suits or a + list of filters in which case the filters are use on Suites to + extract the Deferred cipher list.

+ + + cipher_suites() -> - cipher_suites(Type) -> ciphers() + cipher_suites(Type) -> old_ciphers() Returns a list of supported cipher suites. Type = erlang | openssl | all -

Returns a list of supported cipher suites. + +

Returns a list of supported cipher suites. + This function will become deprecated in OTP 21, and replaced + by ssl:cipher-suites/2 cipher_suites() is equivalent to cipher_suites(erlang). Type openssl is provided for backwards compatibility with the old SSL, which used OpenSSL. cipher_suites(all) returns @@ -844,12 +873,25 @@ fun(srp, Username :: string(), UserState :: term()) -> in cipher_suites(erlang) but included in cipher_suites(all) are not used unless explicitly configured by the user.

+ + + + + cipher_suites(Supported, Version) -> ciphers() + Returns a list of all default or + all supported cipher suites. + + Supported = default | all + Version = protocol_version() + +

Returns all default or all supported cipher suites for a + TLS version

 eccs() -> - eccs(protocol()) -> [named_curve()] + eccs(protocol_version()) -> [named_curve()] Returns a list of supported ECCs.

Returns a list of supported ECCs. eccs() @@ -1008,6 +1050,21 @@ fun(srp, Username :: string(), UserState :: term()) -> + + filter_cipher_suites(Suites, Filters) -> ciphers() + + + Suites = ciphers() + Filters = cipher_filters() + +

Removes cipher suites if any of the filter functions + returns false for any part of the cipher suite. This function + also calls default filter functions to make sure the cipher + suites are supported by crypto. If no filter function is supplied for some + part the default behaviour is fun(Algorithm) -> true.

+ + + format_error(Reason) -> string() Returns an error string. @@ -1105,6 +1162,22 @@ fun(srp, Username :: string(), UserState :: term()) ->

Returns the address and port number of the peer.

 + + + prepend_cipher_suites(Preferred, Suites) -> ciphers() + + + Preferred = ciphers() | cipher_filters() + Suites = ciphers() + +

Make Preferred suites become the most preferred + suites that is put them at the head of the cipher suite list + Suites after removing them from Suites if + present. Preferred may be a list of cipher suits or a + list of filters in which case the filters are use on Suites to + extract the preferred cipher list.

+ + prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()} @@ -1332,7 +1405,7 @@ fun(srp, Username :: string(), UserState :: term()) -> Returns version information relevant for the SSL application. - versions_info() = {app_vsn, string()} | {supported | available, [protocol()] + versions_info() = {app_vsn, string()} | {supported | available, [protocol_version()]

Returns version information relevant for the SSL -- cgit v1.2.3 From cece38b7dccf8563b44eb095ba202f55e07e807f Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 30 Jan 2018 16:53:54 +0100 Subject: ssl: Add UG examles --- lib/ssl/doc/src/using_ssl.xml | 46 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml index 61918a346d..775066ef7d 100644 --- a/lib/ssl/doc/src/using_ssl.xml +++ b/lib/ssl/doc/src/using_ssl.xml @@ -153,7 +153,51 @@ ok -

+
+ Customizing cipher suits + +

Fetch default cipher suite list for an TLS/DTLS version. Change default + to all to get all possible cipher suites.

+ 1> Default = ssl:cipher_suites(default, 'tlsv1.2'). + [#{cipher => aes_256_gcm,key_exchange => ecdhe_ecdsa, + mac => aead,prf => sha384}, ....] + + +

In OTP 20 it is desirable to remove all cipher suites + that uses rsa kexchange (removed from default in 21)

+ 2> NoRSA = + ssl:filter_cipher_suites(Default, + [{key_exchange, fun(rsa) -> false; + (_) -> true end}]). + [...] + + +

Pick just a few suites

+ 3> Suites = + ssl:filter_cipher_suites(Default, + [{key_exchange, fun(ecdh_ecdsa) -> true; + (_) -> false end}, + {cipher, fun(aes_128_cbc) ->true; + (_) ->false end}]). + [#{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa, + mac => sha256,prf => sha256}, + #{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,mac => sha, + prf => default_prf}] + + +

Make some particular suites the most preferred, or least + preferred by changing prepend to append.

+ 4>ssl:prepend_cipher_suites(Suites, Default). + [#{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa, + mac => sha256,prf => sha256}, + #{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,mac => sha, + prf => default_prf}, + #{cipher => aes_256_cbc,key_exchange => ecdhe_ecdsa, + mac => sha384,prf => sha384}, ...] + +
+ +
Using an Engine Stored Key

Erlang ssl application is able to use private keys provided -- cgit v1.2.3 From b16d7d7e4cfa15ab00e5ce43f50619d02bc2f986 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Thu, 1 Feb 2018 14:28:22 +0100 Subject: ssl: Make sure anonymous suites are handled separately Preferably customized cipher suites will be based on the default value. But all may be used as base and hence it will be good to handle anonymous suites separately as they are intended for testing purposes. --- lib/ssl/doc/src/ssl.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 70bb4f759b..3db5aa19ac 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -881,10 +881,10 @@ fun(srp, Username :: string(), UserState :: term()) -> Returns a list of all default or all supported cipher suites. - Supported = default | all + Supported = default | all | anonymous Version = protocol_version() -

Returns all default or all supported cipher suites for a +

Returns all default or all supported (except anonymous), or all anonymous cipher suites for a TLS version

-- cgit v1.2.3