Erlang -- Certificate records

User's Guide
Reference Manual
Release Notes
PDF
Top

public_key
User's Guide
Version 0.16

Expand All
Contract All

Chapters

- Introduction
  - Top of chapter
  - Purpose
  - Prerequisites
  - Performance tips
- Public key records
  - Top of chapter
  - RSA as defined by the PKCS-1 standard and RFC 3447.
  - DSA as defined by Digital Signature Standard (NIST FIPS PUB 186-2)
- Certificate records
  - Top of chapter
  - Common Data Types
  - PKIX Certificates
  - Standard certificate extensions
  - Private Internet Extensions
  - CRL and CRL Extensions Profile
- Using the public_key API
  - Top of chapter
  - General information
  - PEM files
  - RSA public key cryptography
  - Digital signatures
  - SSH files

# 3 Certificate records

This chapter briefly describes erlang records derived from asn1 specifications used to handle X509 certificates. The intent is to describe the data types and not to specify the meaning of each component for this we refer you to RFC 5280.

Use the following include directive to get access to the records and constant macros (OIDs) described in the following sections.

     -include_lib("public_key/include/public_key.hrl").

The used asn1 specifications are available asn1 subdirectory of the application public_key.

### 3.1 Common Data Types

Common non standard erlang data types used to described the record fields in the below sections are defined in public key reference manual or follows here.

oid() - a tuple of integers as generated by the asn1 compiler.

time() = uct_time() | general_time()

uct_time() = {utcTime, "YYMMDDHHMMSSZ"}

general_time() = {generalTime, "YYYYMMDDHHMMSSZ"}

general_name() = {rfc822Name, string()} | {dNSName, string()} | {x400Address, string()} | {directoryName, {rdnSequence, [#AttributeTypeAndValue'{}]}} | | {eidPartyName, special_string()} | {eidPartyName, special_string(), special_string()} | {uniformResourceIdentifier, string()} | {ipAddress, string()} | {registeredId, oid()} | {otherName, term()}

special_string() = {teletexString, string()} | {printableString, string()} | {universalString, string()} | {utf8String, string()} | {bmpString, string()}

dist_reason() = unused | keyCompromise | cACompromise | affiliationChanged | superseded | cessationOfOperation | certificateHold | privilegeWithdrawn | aACompromise

### 3.2 PKIX Certificates

    #'Certificate'{
    		tbsCertificate,        % #'TBSCertificate'{}
    		signatureAlgorithm,    % #'AlgorithmIdentifier'{}
    		signature              % {0, binary()} - asn1 compact bitstring
    	       }.

    #'TBSCertificate'{
    	  version,              % v1 | v2 | v3
    	  serialNumber,         % integer()
    	  signature,            % #'AlgorithmIdentifier'{}
    	  issuer,               % {rdnSequence, [#AttributeTypeAndValue'{}]}
    	  validity,             % #'Validity'{}
    	  subject,              % {rdnSequence, [#AttributeTypeAndValue'{}]}
    	  subjectPublicKeyInfo, % #'SubjectPublicKeyInfo'{}
    	  issuerUniqueID,       % binary() | asn1_novalue
    	  subjectUniqueID,      % binary() | asn1_novalue
    	  extensions            % [#'Extension'{}]
    	 }.

    #'AlgorithmIdentifier'{
    	  algorithm,  % oid()
    	  parameters  % asn1_der_encoded()
    	 }.

    #'OTPCertificate'{
    		tbsCertificate,        % #'OTPTBSCertificate'{}
    		signatureAlgorithm,    % #'SignatureAlgorithm'
    		signature              % {0, binary()} - asn1 compact bitstring
    	       }.

    #'OTPTBSCertificate'{
    	  version,              % v1 | v2 | v3
    	  serialNumber,         % integer()
    	  signature,            % #'SignatureAlgorithm'
    	  issuer,               % {rdnSequence, [#AttributeTypeAndValue'{}]}
    	  validity,             % #'Validity'{}
    	  subject,              % {rdnSequence, [#AttributeTypeAndValue'{}]}
    	  subjectPublicKeyInfo, % #'SubjectPublicKeyInfo'{}
    	  issuerUniqueID,       % binary() | asn1_novalue
    	  subjectUniqueID,      % binary() | asn1_novalue
    	  extensions            % [#'Extension'{}]
    	 }.

    #'SignatureAlgorithm'{
    	  algorithm,  % id_signature_algorithm()
    	  parameters  % asn1_novalue | #'Dss-Parms'{}
    	 }.

id_signature_algorithm() = ?oid_name_as_erlang_atom for available oid names see table below. Ex: ?'id-dsa-with-sha1'

OID name
id-dsa-with-sha1
md2WithRSAEncryption
md5WithRSAEncryption
sha1WithRSAEncryption
ecdsa-with-SHA1

Table 3.1: Signature algorithm oids

    #'AttributeTypeAndValue'{
    	  type,   % id_attributes()
    	  value   % term()
    	 }.

id_attributes()

OID name | Value type
id-at-name | special_string()
id-at-surname | special_string()
id-at-givenName | special_string()
id-at-initials | special_string()
id-at-generationQualifier | special_string()
id-at-commonName | special_string()
id-at-localityName | special_string()
id-at-stateOrProvinceName | special_string()
id-at-organizationName | special_string()
id-at-title | special_string()
id-at-dnQualifier | {printableString, string()}
id-at-countryName | {printableString, string()}
id-at-serialNumber | {printableString, string()}
id-at-pseudonym | special_string()

Table 3.2: Attribute oids

    #'Validity'{
    	  notBefore, % time()
    	  notAfter   % time()
    	 }.

    #'SubjectPublicKeyInfo'{
    	  algorithm,       % #AlgorithmIdentifier{}
    	  subjectPublicKey % binary()
    	 }.

    #'SubjectPublicKeyInfoAlgorithm'{
    	  algorithm,  % id_public_key_algorithm()
    	  parameters  % public_key_params()
    	 }.

id_public_key_algorithm()

OID name
rsaEncryption
id-dsa
dhpublicnumber
ecdsa-with-SHA1
id-keyExchangeAlgorithm

Table 3.3: Public key algorithm oids

    #'Extension'{
    	  extnID,    % id_extensions() | oid()
    	  critical,  % boolean()
    	  extnValue  % asn1_der_encoded()
    	 }.

id_extensions() Standard Certificate Extensions, Private Internet Extensions, CRL Extensions and CRL Entry Extensions.

### 3.3 Standard certificate extensions

OID name | Value type
id-ce-authorityKeyIdentifier | #'AuthorityKeyIdentifier'{}
id-ce-subjectKeyIdentifier | oid()
id-ce-keyUsage | [key_usage()]
id-ce-privateKeyUsagePeriod | #'PrivateKeyUsagePeriod'{}
id-ce-certificatePolicies | #'PolicyInformation'{}
id-ce-policyMappings | #'PolicyMappings_SEQOF'{}
id-ce-subjectAltName | general_name()
id-ce-issuerAltName | general_name()
id-ce-subjectDirectoryAttributes | [#'Attribute'{}]
id-ce-basicConstraints | #'BasicConstraints'{}
id-ce-nameConstraints | #'NameConstraints'{}
id-ce-policyConstraints | #'PolicyConstraints'{}
id-ce-extKeyUsage | [id_key_purpose()]
id-ce-cRLDistributionPoints | #'DistributionPoint'{}
id-ce-inhibitAnyPolicy | integer()
id-ce-freshestCRL | [#'DistributionPoint'{}]

Table 3.4: Standard Certificate Extensions

key_usage() = digitalSignature | nonRepudiation | keyEncipherment| dataEncipherment | keyAgreement | keyCertSign | cRLSign | encipherOnly | decipherOnly

id_key_purpose()

OID name
id-kp-serverAuth
id-kp-clientAuth
id-kp-codeSigning
id-kp-emailProtection
id-kp-timeStamping
id-kp-OCSPSigning

Table 3.5: Key purpose oids

    #'AuthorityKeyIdentifier'{
    	  keyIdentifier,	    % oid()
    	  authorityCertIssuer,      % general_name()
    	  authorityCertSerialNumber % integer()
    	 }.

    #'PrivateKeyUsagePeriod'{
    	  notBefore,   % general_time()
    	  notAfter     % general_time()
    	 }.

    #'PolicyInformation'{
    	  policyIdentifier,  % oid()
    	  policyQualifiers   % [#PolicyQualifierInfo{}]
    	 }.

    #'PolicyQualifierInfo'{
    	  policyQualifierId,   % oid()
    	  qualifier            % string() | #'UserNotice'{}
    	 }.

    #'UserNotice'{
             noticeRef,   % #'NoticeReference'{}
    	 explicitText % string()
    	 }.

    #'NoticeReference'{
             organization,    % string()
    	 noticeNumbers    % [integer()]
    	 }.

    #'PolicyMappings_SEQOF'{
    	  issuerDomainPolicy,  % oid()
    	  subjectDomainPolicy  % oid()
    	 }.

    #'Attribute'{
              type,  % oid()
    	  values % [asn1_der_encoded()]
    	  }).

    #'BasicConstraints'{
    	  cA,		    % boolean()
    	  pathLenConstraint % integer()
    	 }).

    #'NameConstraints'{
    	  permittedSubtrees, % [#'GeneralSubtree'{}]
    	  excludedSubtrees   % [#'GeneralSubtree'{}]
    	 }).

    #'GeneralSubtree'{
    	  base,    % general_name()
    	  minimum, % integer()
    	  maximum  % integer()
    	 }).

    #'PolicyConstraints'{
    	  requireExplicitPolicy, % integer()
    	  inhibitPolicyMapping   % integer()
    	 }).

    #'DistributionPoint'{
    	  distributionPoint, % general_name() | [#AttributeTypeAndValue{}]
    	  reasons,           % [dist_reason()]
    	  cRLIssuer          % general_name()
    	 }).

### 3.4 Private Internet Extensions

OID name | Value type
id-pe-authorityInfoAccess | [#'AccessDescription'{}]
id-pe-subjectInfoAccess | [#'AccessDescription'{}]

Table 3.6: Private Internet Extensions

    #'AccessDescription'{
               accessMethod,    % oid()
    	   accessLocation   % general_name()
    	 }).

### 3.5 CRL and CRL Extensions Profile

    #'CertificateList'{
              tbsCertList,        % #'TBSCertList{}
              signatureAlgorithm, % #'AlgorithmIdentifier'{}
              signature           % {0, binary()} - asn1 compact bitstring
    	  }).

    #'TBSCertList'{
          version,             % v2 (if defined)
          signature,           % #AlgorithmIdentifier{}
          issuer,              % {rdnSequence, [#AttributeTypeAndValue'{}]}
          thisUpdate,          % time()
          nextUpdate,          % time()
          revokedCertificates, % [#'TBSCertList_revokedCertificates_SEQOF'{}]
          crlExtensions        % [#'Extension'{}]
          }).

    #'TBSCertList_revokedCertificates_SEQOF'{
             userCertificate,      % integer()
     	 revocationDate,       % timer()
    	 crlEntryExtensions    % [#'Extension'{}]
    	 }).

#### CRL Extensions

OID name | Value type
id-ce-authorityKeyIdentifier | #'AuthorityKeyIdentifier{}
id-ce-issuerAltName | {rdnSequence, [#AttributeTypeAndValue'{}]}
id-ce-cRLNumber | integer()
id-ce-deltaCRLIndicator | integer()
id-ce-issuingDistributionPoint | #'IssuingDistributionPoint'{}
id-ce-freshestCRL | [#'Distributionpoint'{}]

Table 3.7: CRL Extensions

    #'IssuingDistributionPoint'{
              distributionPoint,         % general_name() | [#AttributeTypeAndValue'{}]
    	  onlyContainsUserCerts,     % boolean()
    	  onlyContainsCACerts,       % boolean()
    	  onlySomeReasons,           % [dist_reason()]
    	  indirectCRL,               % boolean()
    	  onlyContainsAttributeCerts % boolean()
    	  }).

#### CRL Entry Extensions

OID name | Value type
id-ce-cRLReason | crl_reason()
id-ce-holdInstructionCode | oid()
id-ce-invalidityDate | general_time()
id-ce-certificateIssuer | general_name()

Table 3.8: CRL Entry Extensions

crl_reason() = unspecified | keyCompromise | cACompromise | affiliationChanged | superseded | cessationOfOperation | certificateHold | removeFromCRL | privilegeWithdrawn | aACompromise