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