3 Certificate records

This chapter briefly describes erlang records derived from ASN1 specifications used to handle X509 certificates and CertificationRequest. 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 and PKCS-10.

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.

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()}

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  % 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, % #'OTPSubjectPublicKeyInfo'{}
	  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

id-dsaWithSHA1 (ISO alt oid to above)

md2WithRSAEncryption

md5WithRSAEncryption

sha1WithRSAEncryption

sha-1WithRSAEncryption (ISO alt oid to above)

sha224WithRSAEncryption

sha256WithRSAEncryption

sha512WithRSAEncryption

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

id-keyExchangeAlgorithm

id-ecPublicKey

Table 3.3: Public key algorithm oids

#'Extension'{
	  extnID,    % id_extensions() | oid() 
	  critical,  % boolean()
	  extnValue  % 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

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 % [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, % {fullName, [general_name()]} | {nameRelativeToCRLIssuer,
	  [#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,         % {fullName, [general_name()]} | {nameRelativeToCRLIssuer,
	  [#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

PKCS#10 Certification Request

#'CertificationRequest'{
          certificationRequestInfo #'CertificationRequestInfo'{},
	  signatureAlgorithm	   #'CertificationRequest_signatureAlgorithm'{}}.
	  signature                {0, binary()} - ASN1 compact bitstring
	  }

#'CertificationRequestInfo'{
	  version       atom(),
	  subject       {rdnSequence, [#AttributeTypeAndValue'{}]} ,
	  subjectPKInfo #'CertificationRequestInfo_subjectPKInfo'{},
	  attributes    [#'AttributePKCS-10' {}]
	  }

#'CertificationRequestInfo_subjectPKInfo'{
          algorithm		#'CertificationRequestInfo_subjectPKInfo_algorithm'{}
	  subjectPublicKey 	 {0, binary()} - ASN1 compact bitstring
	  }

#'CertificationRequestInfo_subjectPKInfo_algorithm'{
     algorithm = oid(),
     parameters = der_encoded()
}	  

#'CertificationRequest_signatureAlgorithm'{
     algorithm = oid(),
     parameters = der_encoded()
     }

#'AttributePKCS-10'{
    type = oid(),
    values = [der_encoded()]
}