aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/src
diff options
context:
space:
mode:
authorIngela Anderton Andin <[email protected]>2019-02-20 15:51:21 +0100
committerIngela Anderton Andin <[email protected]>2019-02-22 10:14:52 +0100
commit3058ef6bb7a2a3f96cfde819976ee7a52be65364 (patch)
treefa8004cde069e3c6e84ada2e428c7ae50a426685 /lib/ssl/src
parentf06f5bf23a3cd1f040c8ab6f059097d22161abc7 (diff)
downloadotp-3058ef6bb7a2a3f96cfde819976ee7a52be65364.tar.gz
otp-3058ef6bb7a2a3f96cfde819976ee7a52be65364.tar.bz2
otp-3058ef6bb7a2a3f96cfde819976ee7a52be65364.zip
ssl: Enhance documentation after "use-spec-rewrite"
Diffstat (limited to 'lib/ssl/src')
-rw-r--r--lib/ssl/src/ssl.erl390
-rw-r--r--lib/ssl/src/ssl_cipher_format.erl8
-rw-r--r--lib/ssl/src/ssl_connection.hrl2
-rw-r--r--lib/ssl/src/ssl_handshake.erl4
-rw-r--r--lib/ssl/src/tls_handshake.erl2
5 files changed, 201 insertions, 205 deletions
diff --git a/lib/ssl/src/ssl.erl b/lib/ssl/src/ssl.erl
index c39a6f1603..3a8a068d5a 100644
--- a/lib/ssl/src/ssl.erl
+++ b/lib/ssl/src/ssl.erl
@@ -64,159 +64,153 @@
-export_type([socket/0,
sslsocket/0,
socket_option/0,
- tls_client_option/0,
- tls_option/0,
- tls_server_option/0,
active_msgs/0,
- erl_cipher_suite/0,
- protocol_version/0,
- dtls_version/0,
- tls_version/0,
- prf_random/0,
- hello_extensions/0,
- error_alert/0,
- session_id/0,
- path/0,
- hostname/0,
host/0,
- prf/0,
- srp_param_type/0,
- cipher_filters/0,
- ssl_imp/0,
- private_key_type/0,
+ tls_option/0,
+ tls_client_option/0,
+ tls_server_option/0,
+ erl_cipher_suite/0,
+ old_cipher_suite/0,
+ ciphers/0,
cipher/0,
hash/0,
- key_algo/0,
- sign_algo/0
- ]).
+ kex_algo/0,
+ prf_random/0,
+ cipher_filters/0,
+ sign_algo/0,
+ protocol_version/0,
+ protocol_extensions/0,
+ session_id/0,
+ error_alert/0,
+ srp_param_type/0]).
+
%% -------------------------------------------------------------------------------------------------------
-type socket() :: gen_tcp:socket().
--type socket_option() :: socket_connect_option() | socket_listen_option().
--type socket_connect_option() :: gen_tcp:connect_option() | gen_udp:option().
--type socket_listen_option() :: gen_tcp:listen_option() | gen_udp:option().
--opaque sslsocket() :: #sslsocket{}.
--type tls_option() :: tls_client_option() | tls_server_option().
--type tls_client_option() :: client_option() | socket_connect_option() | transport_option().
--type tls_server_option() :: server_option() | socket_listen_option() | transport_option().
--type active_msgs() :: {ssl, sslsocket(), Data::binary() | list()} | {ssl_closed, sslsocket()} |
- {ssl_error, sslsocket(), Reason::term()}.
--type transport_option() :: {cb_info, {CallbackModule::atom(), DataTag::atom(),
+-type socket_option() :: gen_tcp:connect_option() | gen_tcp:listen_option() | gen_udp:option().
+-type sslsocket() :: any().
+-type tls_option() :: tls_client_option() | tls_server_option().
+-type tls_client_option() :: client_option() | common_option() | socket_option() | transport_option().
+-type tls_server_option() :: server_option() | common_option() | socket_option() | transport_option().
+-type active_msgs() :: {ssl, sslsocket(), Data::binary() | list()} | {ssl_closed, sslsocket()} |
+ {ssl_error, sslsocket(), Reason::term()}.
+-type transport_option() :: {cb_info, {CallbackModule::atom(), DataTag::atom(),
ClosedTag::atom(), ErrTag::atom()}}.
--type path() :: file:filename().
--type host() :: hostname() | ip_address().
--type hostname() :: string().
--type ip_address() :: inet:ip_address().
--type session_id() :: binary().
--type protocol_version() :: tls_version() | dtls_version().
--type tls_version() :: tlsv1 | 'tlsv1.1' | 'tlsv1.2' | 'tlsv1.3' | legacy_version().
--type dtls_version() :: 'dtlsv1' | 'dtlsv1.2'.
--type legacy_version() :: sslv3.
--type verify_type() :: verify_none | verify_peer.
--type cipher() :: aes_128_cbc |
- aes_256_cbc |
- aes_128_gcm |
- aes_256_gcm |
- chacha20_poly1305 |
- legacy_cipher().
--type legacy_cipher() :: rc4_128 |
- des_cbc |
- '3des_ede_cbc'.
-
--type hash() :: sha |
- sha2() |
- legacy_hash().
-
--type sha2() :: sha224 |
- sha256 |
- sha384 |
- sha512.
-
--type legacy_hash() :: md5.
-
--type sign_algo() :: rsa | dsa | ecdsa.
--type key_algo() :: rsa |
- dhe_rsa | dhe_dss |
- ecdhe_ecdsa | ecdh_ecdsa | ecdh_rsa |
- srp_rsa| srp_dss |
- psk | dhe_psk | rsa_psk |
- dh_anon | ecdh_anon | srp_anon |
- any. %% TLS 1.3
--type prf() :: hash() | default_prf.
--type erl_cipher_suite() :: #{key_exchange := key_algo(),
- cipher := cipher(),
- mac := hash() | aead,
- prf := hash() | default_prf %% Old cipher suites, version dependent
- }.
-
--type named_curve() :: sect571r1 |
- sect571k1 |
- secp521r1 |
- brainpoolP512r1 |
- sect409k1 |
- sect409r1 |
- brainpoolP384r1 |
- secp384r1 |
- sect283k1 |
- sect283r1 |
- brainpoolP256r1 |
- secp256k1 |
- secp256r1 |
- sect239k1 |
- sect233k1 |
- sect233r1 |
- secp224k1 |
- secp224r1 |
- sect193r1 |
- sect193r2 |
- secp192k1 |
- secp192r1 |
- sect163k1 |
- sect163r1 |
- sect163r2 |
- secp160k1 |
- secp160r1 |
- secp160r2.
-
--type srp_param_type() :: srp_1024 |
- srp_1536 |
- srp_2048 |
- srp_3072 |
- srp_4096 |
- srp_6144 |
- srp_8192.
-
--type error_alert() :: {tls_alert, {tls_alert(), Description::string()}}.
-
--type tls_alert() ::
- close_notify |
- unexpected_message |
- bad_record_mac |
- record_overflow |
- handshake_failure |
- bad_certificate |
- unsupported_certificate |
- certificate_revoked |
- certificate_expired |
- certificate_unknown |
- illegal_parameter |
- unknown_ca |
- access_denied |
- decode_error |
- decrypt_error |
- export_restriction|
- protocol_version |
- insufficient_security |
- internal_error |
- inappropriate_fallback |
- user_canceled |
- no_renegotiation |
- unsupported_extension |
- certificate_unobtainable |
- unrecognized_name |
- bad_certificate_status_response |
- bad_certificate_hash_value |
- unknown_psk_identity |
- no_application_protocol.
+-type host() :: hostname() | ip_address().
+-type hostname() :: string().
+-type ip_address() :: inet:ip_address().
+-type session_id() :: binary().
+-type protocol_version() :: tls_version() | dtls_version().
+-type tls_version() :: tlsv1 | 'tlsv1.1' | 'tlsv1.2' | 'tlsv1.3' | legacy_version().
+-type dtls_version() :: 'dtlsv1' | 'dtlsv1.2'.
+-type legacy_version() :: sslv3.
+-type verify_type() :: verify_none | verify_peer.
+-type cipher() :: aes_128_cbc |
+ aes_256_cbc |
+ aes_128_gcm |
+ aes_256_gcm |
+ chacha20_poly1305 |
+ legacy_cipher().
+-type legacy_cipher() :: rc4_128 |
+ des_cbc |
+ '3des_ede_cbc'.
+
+-type hash() :: sha |
+ sha2() |
+ legacy_hash().
+
+-type sha2() :: sha224 |
+ sha256 |
+ sha384 |
+ sha512.
+
+-type legacy_hash() :: md5.
+
+-type sign_algo() :: rsa | dsa | ecdsa.
+-type kex_algo() :: rsa |
+ dhe_rsa | dhe_dss |
+ ecdhe_ecdsa | ecdh_ecdsa | ecdh_rsa |
+ srp_rsa| srp_dss |
+ psk | dhe_psk | rsa_psk |
+ dh_anon | ecdh_anon | srp_anon |
+ any. %% TLS 1.3
+-type erl_cipher_suite() :: #{key_exchange := kex_algo(),
+ cipher := cipher(),
+ mac := hash() | aead,
+ prf := hash() | default_prf %% Old cipher suites, version dependent
+ }.
+
+-type old_cipher_suite() :: {kex_algo(), cipher(), hash()} % Pre TLS 1.2
+ %% TLS 1.2, internally PRE TLS 1.2 will use default_prf
+ | {kex_algo(), cipher(), hash() | aead, hash()}.
+
+-type named_curve() :: sect571r1 |
+ sect571k1 |
+ secp521r1 |
+ brainpoolP512r1 |
+ sect409k1 |
+ sect409r1 |
+ brainpoolP384r1 |
+ secp384r1 |
+ sect283k1 |
+ sect283r1 |
+ brainpoolP256r1 |
+ secp256k1 |
+ secp256r1 |
+ sect239k1 |
+ sect233k1 |
+ sect233r1 |
+ secp224k1 |
+ secp224r1 |
+ sect193r1 |
+ sect193r2 |
+ secp192k1 |
+ secp192r1 |
+ sect163k1 |
+ sect163r1 |
+ sect163r2 |
+ secp160k1 |
+ secp160r1 |
+ secp160r2.
+
+-type srp_param_type() :: srp_1024 |
+ srp_1536 |
+ srp_2048 |
+ srp_3072 |
+ srp_4096 |
+ srp_6144 |
+ srp_8192.
+
+-type error_alert() :: {tls_alert, {tls_alert(), Description::string()}}.
+
+-type tls_alert() :: close_notify |
+ unexpected_message |
+ bad_record_mac |
+ record_overflow |
+ handshake_failure |
+ bad_certificate |
+ unsupported_certificate |
+ certificate_revoked |
+ certificate_expired |
+ certificate_unknown |
+ illegal_parameter |
+ unknown_ca |
+ access_denied |
+ decode_error |
+ decrypt_error |
+ export_restriction|
+ protocol_version |
+ insufficient_security |
+ internal_error |
+ inappropriate_fallback |
+ user_canceled |
+ no_renegotiation |
+ unsupported_extension |
+ certificate_unobtainable |
+ unrecognized_name |
+ bad_certificate_status_response |
+ bad_certificate_hash_value |
+ unknown_psk_identity |
+ no_application_protocol.
%% -------------------------------------------------------------------------------------------------------
-type common_option() :: {protocol, protocol()} |
{handshake, handshake_completion()} |
@@ -239,43 +233,44 @@
{log_alert, log_alert()} |
{hibernate_after, hibernate_after()} |
{padding_check, padding_check()} |
- {beast_mitigation, beast_mitigation()}.
-
--type protocol() :: tls | dtls.
--type handshake_completion() :: hello | full.
--type cert() :: public_key:der_encoded().
--type cert_pem() :: ssl:path().
--type key() :: {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo',
+ {beast_mitigation, beast_mitigation()} |
+ {ssl_imp, ssl_imp()}.
+
+-type protocol() :: tls | dtls.
+-type handshake_completion() :: hello | full.
+-type cert() :: public_key:der_encoded().
+-type cert_pem() :: file:filename().
+-type key() :: {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo',
public_key:der_encoded()} |
#{algorithm := rsa | dss | ecdsa,
engine := crypto:engine_ref(),
key_id := crypto:key_id(),
password => crypto:password()}.
--type key_pem() :: ssl:path().
--type key_password() :: string().
--type cipher_suites() :: ciphers().
--type ciphers() :: [erl_cipher_suite()] |
- string(). % (according to old API)
--type cipher_filters() :: list({key_exchange | cipher | mac | prf,
- algo_filter()}).
--type algo_filter() :: fun((key_algo()|cipher()|hash()|aead|default_prf) -> true | false).
--type eccs() :: [named_curve()].
--type secure_renegotiation() :: boolean().
+-type key_pem() :: file:filename().
+-type key_password() :: string().
+-type cipher_suites() :: ciphers().
+-type ciphers() :: [erl_cipher_suite()] |
+ string(). % (according to old API)
+-type cipher_filters() :: list({key_exchange | cipher | mac | prf,
+ algo_filter()}).
+-type algo_filter() :: fun((kex_algo()|cipher()|hash()|aead|default_prf) -> true | false).
+-type eccs() :: [named_curve()].
+-type secure_renegotiation() :: boolean().
-type allowed_cert_chain_length() :: integer().
--type custom_verify() :: {Verifyfun :: fun(), InitialUserState :: term()}.
--type crl_check() :: boolean() | peer | best_effort.
--type crl_cache_opts() :: [term()].
--type handshake_size() :: integer().
--type hibernate_after() :: timeout().
--type root_fun() :: fun().
--type protocol_versions() :: [protocol_version()].
--type signature_algs() :: [{hash(), sign_algo()}].
--type custom_user_lookup() :: {Lookupfun :: fun(), UserState :: term()}.
--type padding_check() :: boolean().
--type beast_mitigation() :: one_n_minus_one | zero_n | disabled.
--type srp_identity() :: {Username :: string(), Password :: string()}.
--type psk_identity() :: string().
--type log_alert() :: boolean().
+-type custom_verify() :: {Verifyfun :: fun(), InitialUserState :: term()}.
+-type crl_check() :: boolean() | peer | best_effort.
+-type crl_cache_opts() :: [term()].
+-type handshake_size() :: integer().
+-type hibernate_after() :: timeout().
+-type root_fun() :: fun().
+-type protocol_versions() :: [protocol_version()].
+-type signature_algs() :: [{hash(), sign_algo()}].
+-type custom_user_lookup() :: {Lookupfun :: fun(), UserState :: term()}.
+-type padding_check() :: boolean().
+-type beast_mitigation() :: one_n_minus_one | zero_n | disabled.
+-type srp_identity() :: {Username :: string(), Password :: string()}.
+-type psk_identity() :: string().
+-type log_alert() :: boolean().
%% -------------------------------------------------------------------------------------------------------
@@ -294,10 +289,10 @@
{fallback, fallback()}.
-type client_verify_type() :: verify_type().
--type client_reuse_session() :: ssl:session_id().
+-type client_reuse_session() :: session_id().
-type client_reuse_sessions() :: boolean() | save.
-type client_cacerts() :: [public_key:der_encoded()].
--type client_cafile() :: ssl:path().
+-type client_cafile() :: file:filename().
-type app_level_protocol() :: binary().
-type client_alpn() :: [app_level_protocol()].
-type client_preferred_next_protocols() :: {Precedence :: server | client,
@@ -308,9 +303,10 @@
-type client_psk_identity() :: psk_identity().
-type client_srp_identity() :: srp_identity().
-type customize_hostname_check() :: list().
--type sni() :: HostName :: ssl:hostname() | disable.
+-type sni() :: HostName :: hostname() | disable.
-type client_signature_algs() :: signature_algs().
-type fallback() :: boolean().
+-type ssl_imp() :: new | old.
%% -------------------------------------------------------------------------------------------------------
@@ -334,38 +330,38 @@
{signature_algs, server_signature_algs()}.
-type server_cacerts() :: [public_key:der_encoded()].
--type server_cafile() :: ssl:path().
+-type server_cafile() :: file:filename().
-type server_alpn() :: [app_level_protocol()].
-type server_next_protocol() :: [app_level_protocol()].
-type server_psk_identity() :: psk_identity().
-type dh_der() :: binary().
--type dh_file() :: ssl:path().
+-type dh_file() :: file:filename().
-type server_verify_type() :: verify_type().
-type fail_if_no_peer_cert() :: boolean().
-type server_signature_algs() :: signature_algs().
-type server_reuse_session() :: fun().
-type server_reuse_sessions() :: boolean().
--type sni_hosts() :: [{ssl:hostname(), [server_option() | common_option()]}].
+-type sni_hosts() :: [{hostname(), [server_option() | common_option()]}].
-type sni_fun() :: fun().
-type honor_cipher_order() :: boolean().
-type honor_ecc_order() :: boolean().
-type client_renegotiation() :: boolean().
%% -------------------------------------------------------------------------------------------------------
-
--type ssl_imp() :: new | old.
-
-
-type prf_random() :: client_random | server_random.
+-type protocol_extensions() :: #{renegotiation_info => binary(),
+ signature_algs => signature_algs(),
+ alpn => app_level_protocol(),
+ srp => binary(),
+ next_protocol => app_level_protocol(),
+ ec_point_formats => [0..2],
+ elliptic_curves => [public_key:oid()],
+ sni => hostname()}.
+%% -------------------------------------------------------------------------------------------------------
--type private_key_type() :: rsa | %% Backwards compatibility
- dsa | %% Backwards compatibility
- 'RSAPrivateKey' |
- 'DSAPrivateKey' |
- 'ECPrivateKey' |
- 'PrivateKeyInfo'.
+%%%--------------------------------------------------------------------
+%%% API
+%%%--------------------------------------------------------------------
--type hello_extensions() :: #{signature_algs => sign_algo()}. %% TODO
-%% -------------------------------------------------------------------------------------------------------
%%--------------------------------------------------------------------
%%
%% Description: Utility function that starts the ssl and applications
@@ -745,13 +741,13 @@ negotiated_protocol(#sslsocket{pid = [Pid|_]}) when is_pid(Pid) ->
ssl_connection:negotiated_protocol(Pid).
%%--------------------------------------------------------------------
--spec cipher_suites() -> [ssl_cipher_format:old_erl_cipher_suite()] | [string()].
+-spec cipher_suites() -> [old_cipher_suite()] | [string()].
%%--------------------------------------------------------------------
cipher_suites() ->
cipher_suites(erlang).
%%--------------------------------------------------------------------
-spec cipher_suites(erlang | openssl | all) ->
- [ssl_cipher_format:old_erl_cipher_suite() | string()].
+ [old_cipher_suite() | string()].
%% Description: Returns all supported cipher suites.
%%--------------------------------------------------------------------
cipher_suites(erlang) ->
diff --git a/lib/ssl/src/ssl_cipher_format.erl b/lib/ssl/src/ssl_cipher_format.erl
index f7af96583f..1d28e1e3b4 100644
--- a/lib/ssl/src/ssl_cipher_format.erl
+++ b/lib/ssl/src/ssl_cipher_format.erl
@@ -34,15 +34,15 @@
-type internal_cipher() :: null | ssl:cipher().
-type internal_hash() :: null | ssl:hash().
--type internal_key_algo() :: null | ssl:key_algo().
--type internal_erl_cipher_suite() :: #{key_exchange := internal_key_algo(),
+-type internal_kex_algo() :: null | ssl:kex_algo().
+-type internal_erl_cipher_suite() :: #{key_exchange := internal_kex_algo(),
cipher := internal_cipher(),
mac := internal_hash() | aead,
prf := internal_hash() | default_prf %% Old cipher suites, version dependent
}.
--type old_erl_cipher_suite() :: {ssl:key_algo(), internal_cipher(), internal_hash()} % Pre TLS 1.2
+-type old_erl_cipher_suite() :: {ssl:kex_algo(), internal_cipher(), internal_hash()} % Pre TLS 1.2
%% TLS 1.2, internally PRE TLS 1.2 will use default_prf
- | {ssl:key_algo(), internal_cipher(), internal_hash(),
+ | {ssl:kex_algo(), internal_cipher(), internal_hash(),
internal_hash() | default_prf}.
-type cipher_suite() :: binary().
-type openssl_cipher_suite() :: string().
diff --git a/lib/ssl/src/ssl_connection.hrl b/lib/ssl/src/ssl_connection.hrl
index 83013e7fba..7bf90fdb2d 100644
--- a/lib/ssl/src/ssl_connection.hrl
+++ b/lib/ssl/src/ssl_connection.hrl
@@ -69,7 +69,7 @@
hashsign_algorithm = {undefined, undefined},
cert_hashsign_algorithm = {undefined, undefined},
%% key exchange
- kex_algorithm :: ssl:key_algo(),
+ kex_algorithm :: ssl:kex_algo(),
kex_keys :: {PublicKey :: binary(), PrivateKey :: binary()} | #'ECPrivateKey'{} | undefined | secret_printout(),
diffie_hellman_params:: #'DHParameter'{} | undefined | secret_printout(),
srp_params :: #srp_user{} | secret_printout() | 'undefined',
diff --git a/lib/ssl/src/ssl_handshake.erl b/lib/ssl/src/ssl_handshake.erl
index 27c071d6dd..9ba62b3a12 100644
--- a/lib/ssl/src/ssl_handshake.erl
+++ b/lib/ssl/src/ssl_handshake.erl
@@ -729,7 +729,7 @@ decode_hello_extensions(Extensions) ->
dec_hello_extensions(Extensions, #hello_extensions{}).
%%--------------------------------------------------------------------
--spec decode_server_key(binary(), ssl:key_algo(), ssl_record:ssl_version()) ->
+-spec decode_server_key(binary(), ssl:kex_algo(), ssl_record:ssl_version()) ->
#server_key_params{}.
%%
%% Description: Decode server_key data and return appropriate type
@@ -738,7 +738,7 @@ decode_server_key(ServerKey, Type, Version) ->
dec_server_key(ServerKey, key_exchange_alg(Type), Version).
%%--------------------------------------------------------------------
--spec decode_client_key(binary(), ssl:key_algo(), ssl_record:ssl_version()) ->
+-spec decode_client_key(binary(), ssl:kex_algo(), ssl_record:ssl_version()) ->
#encrypted_premaster_secret{}
| #client_diffie_hellman_public{}
| #client_ec_diffie_hellman_public{}
diff --git a/lib/ssl/src/tls_handshake.erl b/lib/ssl/src/tls_handshake.erl
index fbb81f56fe..0f0de5936a 100644
--- a/lib/ssl/src/tls_handshake.erl
+++ b/lib/ssl/src/tls_handshake.erl
@@ -82,7 +82,7 @@ client_hello(Host, Port, ConnectionStates,
-spec hello(#server_hello{} | #client_hello{}, #ssl_options{},
ssl_record:connection_states() | {inet:port_number(), #session{}, db_handle(),
atom(), ssl_record:connection_states(),
- binary() | undefined, ssl:key_algo()},
+ binary() | undefined, ssl:kex_algo()},
boolean()) ->
{tls_record:tls_version(), ssl:session_id(),
ssl_record:connection_states(), alpn | npn, binary() | undefined}|