From 9a913b0219188a96f55d5f266bc2ce52c034aa4c Mon Sep 17 00:00:00 2001 From: Andreas Schultz Date: Mon, 14 Jan 2013 18:19:09 +0100 Subject: SSL: add documentation for PSK and SRP ciphers options --- lib/ssl/doc/src/ssl.xml | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index e9858a3220..d78deb3252 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -79,6 +79,7 @@ {keyfile, path()} | {password, string()} | {cacerts, [der_encoded()]} | {cacertfile, path()} | |{dh, der_encoded()} | {dhfile, path()} | {ciphers, ciphers()} | + {user_lookup_fun, {fun(), term()}}, {psk_identity, string()}, {srp_identity, {string(), string()}} | {ssl_imp, ssl_imp()} | {reuse_sessions, boolean()} | {reuse_session, fun()} {next_protocols_advertised, [binary()]} | {client_preferred_next_protocols, client | server, [binary()]} @@ -123,6 +124,7 @@ {key_exchange(), cipher(), hash()}

key_exchange() = rsa | dhe_dss | dhe_rsa | dh_anon + | psk | dhe_psk | rsa_psk | srp_anon | srp_dss | srp_rsa

cipher() = rc4_128 | des_cbc | '3des_ede_cbc' @@ -134,6 +136,9 @@

prf_random() = client_random | server_random

+

srp_param_type() = srp_1024 | srp_1536 | srp_2048 | srp_3072 + | srp_4096 | srp_6144 | srp_8192

+
@@ -292,6 +297,35 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | undefined is specified (this is the default), the process will never go into hibernation. + + {user_lookup_fun, {Lookupfun :: fun(), UserState :: term()}} + +

The lookup fun should be defined as:

+ +fun(psk, PSKIdentity, UserState :: term()) -> + {ok, SharedSecret :: binary()} | error; +fun(srp, Username, UserState :: term()) -> + {ok, {SRPParams :: srp_param_type(), Salt :: binary(), UserPassHash :: binary()}} | error. + + +

For PSK cipher suites, the lookup fun will be called in the client and server the find + the shared secret. On the client, PSKIdentity will be set to hint presented by the server + or undefined. On the server, PSKIdentity is the identity presented by the client. + For SRP cipher suites, the fun will only be used by the server to find the SRP values. +

+ +

For SRP, the required values on a server will usually be precalculated and kept in a passwd + like file. A sample SRP lookup fun that calculates the values on the fly for a single user entry + with a static password could be:

+ + Salt = ssl:random_bytes(16), + UserPassHash = crypto:sha([Salt, crypto:sha([Username, <<$:>>, <<"secret">>])]), + {ok, {srp_1024, Salt, UserPassHash}}. + ]]> + + +
@@ -334,6 +368,14 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | server does not support Next Protocol Negotiation the connection will be aborted if no default protocol is supplied.

+ + {psk_identity, string()} + Specifies the identity the client presents to the server. The matching secret is + found by calling the user_look_fun. + + {srp_identity, {Username :: string(), Password :: string()} + Specifies the Username and Password to use to authenticate to the server. + @@ -396,6 +438,10 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | using negotiated_next_protocol/1 method. + {psk_identity, string()} + Specifies the server identity hint the server presents to the client. + + -- cgit v1.2.3 From 5ddcb614a0a96a54ed1a7aa3cba3356b85021096 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 15 Mar 2013 10:20:09 +0100 Subject: ssl: Add option to list all available ciper suites and enhanced documentation --- lib/ssl/doc/src/ssl.xml | 56 +++++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 27 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index d78deb3252..2501db858a 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -184,13 +184,16 @@ {ciphers, ciphers()} The cipher suites that should be supported. The function - cipher_suites/0 can be used to find all available - ciphers. Additionally some anonymous cipher suites ({dh_anon, - rc4_128, md5}, {dh_anon, des_cbc, sha}, {dh_anon, - '3des_ede_cbc', sha}, {dh_anon, aes_128_cbc, sha}, {dh_anon, - aes_256_cbc, sha}) are supported for testing purposes and will - only work if explicitly enabled by this option and they are supported/enabled - by the peer also. + cipher_suites/0 can be used to find all ciphers that are + supported by default. cipher_suites(all) may be called + to find all available cipher suites. + Pre-Shared Key (RFC 4279 and + RFC 5487), + Secure Remote Password (RFC 5054) + and anonymous cipher suites only work if explicitly enabled by + this option and they are supported/enabled by the peer also. + Note that anonymous cipher suites are supported for testing purposes + only and should not be used when security matters. {ssl_imp, new | old} @@ -200,10 +203,10 @@ {secure_renegotiate, boolean()} Specifies if to reject renegotiation attempt that does - not live up to RFC 5746. By default secure_renegotiate is + not live up to RFC 5746. By default secure_renegotiate is set to false i.e. secure renegotiation will be used if possible but it will fallback to unsecure renegotiation if the peer - does not support RFC 5746. + does not support RFC 5746. {depth, integer()} @@ -305,25 +308,22 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} | fun(psk, PSKIdentity, UserState :: term()) -> {ok, SharedSecret :: binary()} | error; fun(srp, Username, UserState :: term()) -> - {ok, {SRPParams :: srp_param_type(), Salt :: binary(), UserPassHash :: binary()}} | error. + {ok, {SRPParams :: srp_param_type(), Salt :: binary(), DerivedKey :: binary()}} | error. -

For PSK cipher suites, the lookup fun will be called in the client and server the find - the shared secret. On the client, PSKIdentity will be set to hint presented by the server - or undefined. On the server, PSKIdentity is the identity presented by the client. - For SRP cipher suites, the fun will only be used by the server to find the SRP values. +

For Pre-Shared Key (PSK) cipher suites, the lookup fun will + be called by the client and server to determine the shared + secret. When called by the client, PSKIdentity will be set to the + hint presented by the server or undefined. When called by the + server, PSKIdentity is the identity presented by the client.

-

For SRP, the required values on a server will usually be precalculated and kept in a passwd - like file. A sample SRP lookup fun that calculates the values on the fly for a single user entry - with a static password could be:

- - Salt = ssl:random_bytes(16), - UserPassHash = crypto:sha([Salt, crypto:sha([Username, <<$:>>, <<"secret">>])]), - {ok, {srp_1024, Salt, UserPassHash}}. - ]]> - +

For Secure Remote Password (SRP), the fun will only be used by the server to obtain + parameters that it will use to generate its session keys. DerivedKey should be + derived according to RFC 2945 and + RFC 5054: + crypto:sha([Salt, crypto:sha([Username, <<$:>>, Password])]) +

@@ -473,13 +473,16 @@ user_lookup(srp, Username, _UserState) -> cipher_suites(Type) -> ciphers() Returns a list of supported cipher suites - Type = erlang | openssl + Type = erlang | openssl | all

Returns a list of supported cipher suites. cipher_suites() is equivalent to cipher_suites(erlang). Type openssl is provided for backwards compatibility with - old ssl that used openssl. + old ssl that used openssl. cipher_suites(all) returns + all available cipher suites. The cipher suites not present + in cipher_suites(erlang) but in included in cipher_suites(all) + will not be used unless explicitly configured by the user.

@@ -867,7 +870,6 @@ user_lookup(srp, Username, _UserState) -> -
-- cgit v1.2.3