path: root/lib/ssl/doc/src/ssl_crl_cache_api.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2015</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    </legalnotice>
    <title>ssl_crl_cache_api</title>
    <file>ssl_crl_cache_api.xml</file>
  </header>
  
  <module since="OTP 18.0">ssl_crl_cache_api</module>
  <modulesummary>API for a SSL/TLS CRL (Certificate Revocation List) cache.</modulesummary>
  <description>
    <p>
      When SSL/TLS performs certificate path validation according to
      <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280 </url>
      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 the
      behavior of the API needed 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.
    </p>
  </description>


  <!--
      ================================================================
      =  Data types                                                  =
      ================================================================
  -->

  <datatypes>
    
     <datatype>
	<name name="crl_cache_ref"/>
	<desc>
	  <p>Reference to the CRL cache.</p>
	</desc>
      </datatype>


     <datatype>
	<name name="dist_point"/>
	<desc>
	  <p>For description see <seealso 
	  marker="public_key:public_key_records"> X509 certificates records</seealso></p>
	</desc>
     </datatype>      
   </datatypes>
  
  <funcs>
      <func>
      <name since="OTP 18.0">fresh_crl(DistributionPoint, CRL) -> FreshCRL</name>
      <fsummary> <c>fun fresh_crl/2 </c> will be used as input option <c>update_crl</c> to
      public_key:pkix_crls_validate/3 </fsummary>
      <type>
	<v> DistributionPoint = <seealso marker="#type-dist_point"> dist_point() </seealso> </v>
	<v> CRL = [<seealso
	marker="public_key:public_key#type-der_encoded">public_key:der_encoded()</seealso>] </v>
	<v> FreshCRL = [<seealso
	marker="public_key:public_key#type-der_encoded">public_key:der_encoded()</seealso>] </v>
      </type>
      <desc>
	<p> <c>fun fresh_crl/2 </c> will be used as input option <c>update_crl</c> to
	<seealso marker="public_key:public_key#pkix_crls_validate-3">public_key:pkix_crls_validate/3 </seealso> </p>
      </desc>
    </func>
    
    <func>
      <name since="OTP 19.0">lookup(DistributionPoint, Issuer, DbHandle) -> not_available | CRLs </name>
      <name since="OTP 18.0">lookup(DistributionPoint, DbHandle) -> not_available | CRLs </name>
      <fsummary> </fsummary>
      <type>
	<v> DistributionPoint = <seealso marker="#type-dist_point"> dist_point() </seealso> </v>
        <v> Issuer = <seealso
	marker="public_key:public_key#type-issuer_name">public_key:issuer_name()</seealso> </v>
	<v> DbHandle = <seealso marker="#type-crl_cache_ref"> crl_cache_ref() </seealso></v>
	<v> CRLs = [<seealso
	   marker="public_key:public_key#type-der_encoded">public_key:der_encoded()</seealso>] </v>
	</type>
	<desc> <p>Lookup the CRLs belonging to the distribution point <c> Distributionpoint</c>.
	This function may choose to only look in the cache or to follow distribution point
	links depending on how the cache is administrated. </p>

	<p>The <c>Issuer</c> argument contains the issuer name of the
	certificate to be checked.  Normally the returned CRL should
	be issued by this issuer, except if the <c>cRLIssuer</c> field
	of <c>DistributionPoint</c> has a value, in which case that
	value should be used instead.</p>

	<p>In an earlier version of this API, the <c>lookup</c>
	function received two arguments, omitting <c>Issuer</c>.  For
	compatibility, this is still supported: if there is no
	<c>lookup/3</c> function in the callback module,
	<c>lookup/2</c> is called instead.</p>
	</desc>
    </func>
    
    <func>
      <name since="OTP 18.0">select(Issuer, DbHandle) -> CRLs </name>
      <fsummary>Select the CRLs in the cache that are issued by <c>Issuer</c></fsummary>
      <type>
	<v> Issuer = <seealso
	marker="public_key:public_key#type-issuer_name">public_key:issuer_name()</seealso></v>
	<v> DbHandle = <seealso marker="#type-crl_cache_ref"> cache_ref() </seealso></v>
	</type>
	<desc>
	  <p>Select the CRLs in the cache that are issued by <c>Issuer</c> </p>
	</desc>
    </func>
  </funcs>
</erlref>