From 4e0a5e36b38e3f15ed8f7d700d26f2424a47111c Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 11 Feb 2015 14:53:10 +0100 Subject: ssl: Integrate public_key CRL verification with the ssl application --- lib/ssl/doc/src/Makefile | 4 +- lib/ssl/doc/src/refman.xml | 19 +----- lib/ssl/doc/src/ssl.xml | 45 ++++++++++++-- lib/ssl/doc/src/ssl_crl_cache.xml | 66 +++++++++++++++++++++ lib/ssl/doc/src/ssl_crl_cache_api.xml | 97 +++++++++++++++++++++++++++++++ lib/ssl/doc/src/ssl_session_cache_api.xml | 6 +- 6 files changed, 212 insertions(+), 25 deletions(-) create mode 100644 lib/ssl/doc/src/ssl_crl_cache.xml create mode 100644 lib/ssl/doc/src/ssl_crl_cache_api.xml (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/Makefile b/lib/ssl/doc/src/Makefile index fb12499ef7..cfbf98f6e3 100644 --- a/lib/ssl/doc/src/Makefile +++ b/lib/ssl/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1999-2012. All Rights Reserved. +# Copyright Ericsson AB 1999-2015. All Rights Reserved. # # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in @@ -37,7 +37,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = refman.xml -XML_REF3_FILES = ssl.xml ssl_session_cache_api.xml +XML_REF3_FILES = ssl.xml ssl_crl_cache.xml ssl_crl_cache.xml ssl_session_cache_api.xml XML_REF6_FILES = ssl_app.xml XML_PART_FILES = release_notes.xml usersguide.xml diff --git a/lib/ssl/doc/src/refman.xml b/lib/ssl/doc/src/refman.xml index ae11198edb..d5f2219af9 100644 --- a/lib/ssl/doc/src/refman.xml +++ b/lib/ssl/doc/src/refman.xml @@ -4,7 +4,7 @@
- 19992013 + 19992015 Ericsson AB. All Rights Reserved. @@ -28,23 +28,10 @@ B refman.sgml
- -

The SSL application provides secure communication over - sockets. -

-

This product includes software developed by the OpenSSL Project for - use in the OpenSSL Toolkit (http://www.openssl.org/). -

-

This product includes cryptographic software written by Eric Young - (eay@cryptsoft.com). -

-

This product includes software written by Tim Hudson - (tjh@cryptsoft.com). -

-

For full OpenSSL and SSLeay license texts, see Licenses.

- + + diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 7a5f72710a..c9b02d44ec 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -51,9 +51,9 @@ IDEA cipher suites are not supported as they have become deprecated by the latest TLS spec so there is not any real motivation to implement them. - CRL and policy certificate extensions are not supported - yet. However CRL verification is supported by public_key, only not integrated - in ssl yet. + CRL validation is supported. + Policy certificate extensions are not supported + yet. Support for 'Server Name Indication' extension client side (RFC 6066 section 3). @@ -301,10 +301,47 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revo Possible such reasons see public_key:pkix_path_validation/3 + + + {crl_check, boolean() | peer | best_effort ) + + Perform CRL (Certificate Revocation List) verification + + public_key:pkix_crls_validate/3, during the + public_key:pkix_path_validation/3 + invokation on all the certificates in the peer certificate chain. Defaults to + false. + +

peer - check is only performed on + the peer certificate.

+ +

best_effort - if certificate revokation status can not be determined + it will be accepted as valid.

+

The CA certificates specified for the connection will be used to + construct the certificate chain validating the CRLs.

+ +

The CRLs will be fetched from a local or external cache + ssl_crl_cache_api(3).

 - {partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | unknown_ca } + {crl_cache, {Module::atom, {DbHandle::internal | term(), Args::list()}} + +

Module defaults to ssl_crl_cache with DbHandle internal and an + empty argument list. The following arguments may be specified for the internal cache.

+ + {http, timeout()} + + Enables fetching of CRLs specified as http URIs in X509 cerificate extensions. + Requires the OTP inets application. + + + + + {partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | unknown_ca + Claim an intermediat CA in the chain as trusted. TLS will then perform the public_key:pkix_path_validation/3 with the selected CA as trusted anchor and the rest of the chain. diff --git a/lib/ssl/doc/src/ssl_crl_cache.xml b/lib/ssl/doc/src/ssl_crl_cache.xml new file mode 100644 index 0000000000..1ed76d3e2a --- /dev/null +++ b/lib/ssl/doc/src/ssl_crl_cache.xml @@ -0,0 +1,66 @@ + + + + +
+ + 20152015 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + ssl_crl_cache + ssl_crl_cache.xml +
+ + ssl_crl_cache + CRL cache + +

+ Implements an internal CRL (Certificate Revocation List) cache. + In addition to implementing the ssl_cache_crl_api + the following functions are available. +

+ + + + + insert(CRLSrc) -> ok | {error, Reason} + insert(URI, CRLSrc) -> ok | {error, Reason} + + + CRLSrc = {file, string()} | {der, [ der_encoded() ]} + URI = http_uri:uri() + Reason = term() + + + Insert CRLs into the ssl applications local cache. + + + + + delete(Entries) -> ok | {error, Reason} + + + Entries = http_uri:uri() | {file, string()} | {der, [ der_encoded() ]} + Reason = term() + + + Delete CRLs from the ssl applications local cache. + + + + \ No newline at end of file diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml new file mode 100644 index 0000000000..24365c9f59 --- /dev/null +++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml @@ -0,0 +1,97 @@ + + + + +
+ + 20152015 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + ssl_crl_cache_api + ssl_crl_cache_api.xml +
+ + ssl_crl_cache_api + API for a SSL/TLS CRL (Certificate Revocation List) cache. + +

+ When SSL/TLS performs certificate path validation according to + RFC 5280 it should + also perform CRL validation checks. To enable the CRL checks the application + needs access to CRLs. A database of CRLs can be set up in many different ways. + This module provides an API to integrate an arbitrary CRL cache with the erlang + ssl application. It is also used by the application itself to provide a simple + default implementation of a CRL cache. +

+ + +
+ Common Data Types + +

The following data types are used in the functions below: +

+ +

cache_ref() = opaque()

+

dist_point() = #'DistributionPoint'{} see X509 certificates records

+
+ + + + lookup(DistributionPoint, DbHandle) -> not_available | CRLs + + + DistributionPoint = dist_point() + DbHandle = cache_ref() + CRLs = [public_key:der_encoded()] + +

Lookup the CRLs belonging to the distribution point Distributionpoint

. + This function may choose to only look in the cache or to follow distribution point + links depending on how the cache is administrated. + + + + + select(Issuer, DbHandle) -> CRLs + Select the CRLs in the cache that are issued by Issuer + + Issuer = public_key:issuer_name() + DbHandle = cache_ref() + + +

Select the CRLs in the cache that are issued by Issuer

+ + + + + fresh_crl(DistributionPoint, CRL) -> FreshCRL + fun fresh_crl/2 will be used as input option update_crl to + public_key:pkix_crls_validate/3 + + DistributionPoint = dist_point() + CRL = [public_key:der_encoded()] + FreshCRL = [public_key:der_encoded()] + + +

fun fresh_crl/2 will be used as input option update_crl to + public_key:pkix_crls_validate/3

+ + + + \ No newline at end of file diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml index cb97bbfbb2..9f87d31e90 100644 --- a/lib/ssl/doc/src/ssl_session_cache_api.xml +++ b/lib/ssl/doc/src/ssl_session_cache_api.xml @@ -4,7 +4,7 @@
- 19992014 + 19992015 Ericsson AB. All Rights Reserved. @@ -119,14 +119,14 @@ select_session(Cache, PartialKey) -> [session()] - >Selects sessions that could be reused. + Selects a sessions that could be reused. Cache = cache_ref() PartialKey = partialkey() Session = session() -

Selects sessions that could be reused. Should be callable +

Selects a sessions that could be reused. Should be callable from any process.

-- cgit v1.2.3