From a99b7ff68aa194c260134ab2461af1a14a03e697 Mon Sep 17 00:00:00 2001 From: tmanevik Date: Thu, 23 Apr 2015 15:06:05 +0200 Subject: Editorial changes --- lib/public_key/doc/src/cert_records.xml | 265 ++++++++------ lib/public_key/doc/src/introduction.xml | 23 +- lib/public_key/doc/src/part.xml | 9 +- lib/public_key/doc/src/public_key.xml | 505 +++++++++++++++----------- lib/public_key/doc/src/public_key_records.xml | 40 +- lib/public_key/doc/src/records.xml | 47 +++ lib/public_key/doc/src/ref_man.xml | 4 +- lib/public_key/doc/src/using_public_key.xml | 221 +++++------ 8 files changed, 643 insertions(+), 471 deletions(-) create mode 100644 lib/public_key/doc/src/records.xml diff --git a/lib/public_key/doc/src/cert_records.xml b/lib/public_key/doc/src/cert_records.xml index 857a39bf40..4d4533fe21 100644 --- a/lib/public_key/doc/src/cert_records.xml +++ b/lib/public_key/doc/src/cert_records.xml @@ -23,7 +23,7 @@ The Initial Developer of the Original Code is Ericsson AB. - Certificate records + Certificate Records Ingela Anderton Andin @@ -34,66 +34,81 @@ cert_records.xml -

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 semantics of each component. For information on the -semantics, please see This section briefly describes Erlang records derived from ASN.1 + specifications used to handle X509 certificates and CertificationRequest. + The scope is to describe the data types of each component, + not the semantics. For information on the semantics, refer 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.

+ 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. -

+

The used ASN.1 specifications are available in the asn1 subdirectory + of the public_key application.

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

+

Common non-standard Erlang + data types used to describe the record fields in the + following sections are defined in the public_key Reference Manual, or + follows here:

-

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

- -

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

+ + 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, binary()}

+

| {bmpString, string()}

+ + + dist_reason() + =

unused

+

| keyCompromise

+

| cACompromise

+

| affiliationChanged

+

| superseded

+

| cessationOfOperation

+

| certificateHold

+

| privilegeWithdrawn

+

| aACompromise

+ + +
- PKIX Certificates + PKIX Certificates +

Erlang representation of PKIX certificates derived from ASN.1 + specifications and RFC 5280 are as follows:

#'Certificate'{ tbsCertificate, % #'TBSCertificate'{} @@ -117,8 +132,7 @@ semantics, please see + }. #'OTPCertificate'{ @@ -143,20 +157,20 @@ semantics, please see + }. -

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

+

Here, id_signature_algorithm() = ?OID name, for available OID names, for example +?id-dsa-with-sha1. That is, by prepending "?" to the OID name, represented as an Erlang atom.

+

The available OID names are as follows:

- OID name + OID Name id-dsa-with-sha1 - id-dsaWithSHA1 (ISO alt oid to above) + id-dsaWithSHA1 (ISO or OID to above) md2WithRSAEncryption @@ -168,7 +182,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

sha1WithRSAEncryption - sha-1WithRSAEncryption (ISO alt oid to above) + sha-1WithRSAEncryption (ISO or OID to above) sha224WithRSAEncryption @@ -182,21 +196,24 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

ecdsa-with-SHA1 - Signature algorithm oids + Signature Algorithm OIDs
+

The data type 'AttributeTypeAndValue', is represented as + the following erlang record:

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

id_attributes()

+

The attribute OID name atoms and their corresponding value types +are as follows:

- OID name - Value type + OID Name + Value Type id-at-name @@ -254,9 +271,12 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

id-at-pseudonym special_string() - Attribute oids + Attribute OIDs
+

The data types 'Validity', 'SubjectPublicKeyInfo', and +'SubjectPublicKeyInfoAlgorithm' are represented as the following Erlang records:

+ #'Validity'{ notBefore, % time() @@ -271,13 +291,12 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

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

id_public_key_algorithm()

+

The public-key algorithm OID name atoms are as follows:

- OID name + OID Name rsaEncryption @@ -294,7 +313,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

id-ecPublicKey - Public key algorithm oids + Public-Key Algorithm OIDs
@@ -302,8 +321,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

extnID, % id_extensions() | oid() critical, % boolean() extnValue % der_encoded() - }. - + }.

id_extensions() Standard Certificate Extensions, @@ -316,12 +334,15 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

- Standard certificate extensions - + Standard Certificate Extensions + +

The standard certificate extensions OID name atoms and their + corresponding value types are as follows:

+ - OID name - Value type + OID Name + Value Type id-ce-authorityKeyIdentifier @@ -333,7 +354,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

 id-ce-keyUsage - [key_usage()] + [key_usage()] id-ce-privateKeyUsagePeriod @@ -400,17 +421,26 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

Standard Certificate Extensions
-

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

+

Here:

+ + key_usage() + =

digitalSignature

+

| nonRepudiation

+

| keyEncipherment

+

| dataEncipherment

+

| keyAgreement

+

| keyCertSign

+

| cRLSign

+

| encipherOnly

+

| decipherOnly

+ + -

id_key_purpose()

+

And for id_key_purpose():

- OID name + OID Name id-kp-serverAuth @@ -430,7 +460,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

id-kp-OCSPSigning - Key purpose oids + Key Purpose OIDs
@@ -501,8 +531,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

[#AttributeTypeAndValue{}]} reasons, % [dist_reason()] cRLIssuer % [general_name()] - }). - + }).
@@ -510,10 +539,13 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

Private Internet Extensions +

The private internet extensions OID name atoms and their corresponding value + types are as follows:

+ - OID name - Value type + OID Name + Value Type id-pe-authorityInfoAccess @@ -530,13 +562,15 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'AccessDescription'{ accessMethod, % oid() accessLocation % general_name() - }). - + }).
- CRL and CRL Extensions Profile + CRL and CRL Extensions Profile + +

Erlang representation of CRL and CRL extensions profile + derived from ASN.1 specifications and RFC 5280 are as follows:

#'CertificateList'{ @@ -559,17 +593,19 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

userCertificate, % integer() revocationDate, % timer() crlEntryExtensions % [#'Extension'{}] - }). - + }).
- CRL Extensions + CRL Extensions + +

The CRL extensions OID name atoms and their corresponding value types are as follows:

+
- OID name - Value type + OID Name + Value Type id-ce-authorityKeyIdentifier @@ -599,6 +635,9 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

CRL Extensions
+

Here, the data type 'IssuingDistributionPoint' is represented as + the following Erlang record:

+ #'IssuingDistributionPoint'{ distributionPoint, % {fullName, [general_name()]} | {nameRelativeToCRLIssuer, @@ -608,18 +647,19 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

onlySomeReasons, % [dist_reason()] indirectCRL, % boolean() onlyContainsAttributeCerts % boolean() - }). - + }).
- CRL Entry Extensions + CRL Entry Extensions + +

The CRL entry extensions OID name atoms and their corresponding value types are as follows:

- OID name - Value type + OID Name + Value Type id-ce-cRLReason @@ -639,17 +679,31 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

CRL Entry Extensions
-

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

+ + +

Here:

+ + crl_reason() + =

unspecifiedc>

+

| keyCompromise

+

| cACompromise

+

| affiliationChanged

+

| superseded

+

| cessationOfOperation

+

| certificateHold

+

| removeFromCRL

+

| privilegeWithdrawn

+

| aACompromise

+ + +
PKCS#10 Certification Request +

Erlang representation of a PKCS#10 certification request + derived from ASN.1 specifications and RFC 5280 are as follows:

#'CertificationRequest'{ certificationRequestInfo #'CertificationRequestInfo'{}, @@ -682,8 +736,7 @@ oid names see table below. Ex: ?'id-dsa-with-sha1'

#'AttributePKCS-10'{ type = oid(), values = [der_encoded()] -} - +}
diff --git a/lib/public_key/doc/src/introduction.xml b/lib/public_key/doc/src/introduction.xml index bf11a092d8..17f4e5155a 100644 --- a/lib/public_key/doc/src/introduction.xml +++ b/lib/public_key/doc/src/introduction.xml @@ -36,27 +36,28 @@
Purpose -

public_key deals with public key related file formats, digital - signatures and +

The public_key application deals with public-key related file + formats, digital signatures, and X-509 certificates. It is a library application that - provides encode/decode, sign/verify, encrypt/decrypt and similar - functionality, it does not read or write files it expects or returns + provides encode/decode, sign/verify, encrypt/decrypt, and similar + functionality. It does not read or write files, it expects or returns file contents or partial file contents as binaries.

Prerequisites -

It is assumed that the reader has a basic understanding - of the concepts of using public keys and digital certificates.

+

It is assumed that the reader is familiar with the Erlang programming + language and has a basic understanding of the concepts of using public-keys + and digital certificates.

- Performance tips -

The public_key decode and encode functions will try to use the NIFs - which are in the ASN1 compilers runtime modules if they can be found. - So for the best performance you want to have the ASN1 application in the - path of your system.

+ Performance Tips +

The public_key decode- and encode-functions try to use the NIFs + in the ASN.1 compilers runtime modules, if they can be found. + Thus, to have the ASN.1 application in the + path of your system gives the best performance.

diff --git a/lib/public_key/doc/src/part.xml b/lib/public_key/doc/src/part.xml index 73146c8e2a..d3cc9303bd 100644 --- a/lib/public_key/doc/src/part.xml +++ b/lib/public_key/doc/src/part.xml @@ -31,15 +31,14 @@ part.xml -

This application provides an API to public key infrastructure +

This application provides an API to public-key infrastructure from RFC - 5280 (X.509 certificates) and public key formats defined by + 5280 (X.509 certificates) and public-key formats defined by the - PKCS-standard

+ PKCS standard.

 - - + diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index b86d0fe0ab..ddaa8c2530 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -31,11 +31,11 @@ public_key - API module for public key infrastructure. + API module for public-key infrastructure. -

This module provides functions to handle public key infrastructure. It can - encode/decode different file formats (PEM, openssh), sign and verify digital signatures and validate - certificate paths and certificate revocation lists. +

This module provides functions to handle public-key infrastructure. It can + encode/decode different file formats (PEM, OpenSSH), sign and verify digital signatures, + and validate certificate paths and certificate revocation lists.

@@ -43,94 +43,152 @@ public_key - public_key requires the crypto and asn1 applications, the latter since R16 (hopefully the runtime dependency on asn1 will - be removed again in the future). + public_key requires the crypto and ASN.1 applications, + the latter as OTP R16 (hopefully the runtime dependency on ASN.1 will + be removed again in the future). Supports RFC 5280 - - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile - Supports PKCS-1 - RSA Cryptography Standard - Supports DSS- Digital Signature Standard (DSA - Digital Signature Algorithm) - Supports PKCS-3 - Diffie-Hellman Key Agreement Standard - Supports PKCS-5 - Password-Based Cryptography Standard - Supports PKCS-8 - Private-Key Information Syntax Standard - Supports PKCS-10 - Certification Request Syntax Standard + Internet X.509 Public-Key Infrastructure Certificate and Certificate Revocation List + (CRL) Profile + Supports PKCS-1 - + RSA Cryptography Standard + Supports DSS - + Digital Signature Standard (DSA - Digital Signature Algorithm) + Supports + PKCS-3 - + Diffie-Hellman Key Agreement Standard + Supports PKCS-5 - + Password-Based Cryptography Standard + Supports PKCS-8 - + Private-Key Information Syntax Standard + Supports PKCS-10 - + Certification Request Syntax Standard
- COMMON DATA TYPES + DATA TYPES -

All records used in this manual +

All records used in this Reference Manual are generated from ASN.1 specifications and are documented in the User's Guide. See Public key records and X.509 Certificate records. + marker="public_key_records">Public-key Records and X.509 Certificate Records.

Use the following include directive to get access to the - records and constant macros described here and in the User's Guide.

+ records and constant macros described here and in the User's Guide:

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

Data Types

- -

oid() - Object Identifier, a tuple of integers as generated by the ASN1 compiler.

- -

boolean() = true | false

- -

string() = [bytes()]

- -

der_encoded() = binary()

- -

pki_asn1_type() = 'Certificate' | 'RSAPrivateKey'| 'RSAPublicKey' | - 'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' | - 'SubjectPublicKeyInfo' | 'PrivateKeyInfo' | - 'CertificationRequest' | 'ECPrivateKey' | 'EcpkParameters'

- -

pem_entry () = {pki_asn1_type(), binary(), %% DER or encrypted DER - not_encrypted | cipher_info()}

- -

cipher_info() = {"RC2-CBC | "DES-CBC" | "DES-EDE3-CBC", - crypto:rand_bytes(8) | {#'PBEParameter{}, digest_type()} |#'PBES2-params'{}}

- -

public_key() = rsa_public_key() | dsa_public_key() | ec_public_key()

-

private_key() = rsa_private_key() | dsa_private_key() | ec_private_key()

-

rsa_public_key() = #'RSAPublicKey'{}

- -

rsa_private_key() = #'RSAPrivateKey'{}

- -

dsa_public_key() = {integer(), #'Dss-Parms'{}}

- -

dsa_private_key() = #'DSAPrivateKey'{}

- -

ec_public_key() = {#'ECPoint'{}, #'EcpkParameters'{} | - {namedCurve, oid()}}

- -

ec_private_key() = #'ECPrivateKey'{}

- -

public_crypt_options() = [{rsa_pad, rsa_padding()}].

- -

rsa_padding() = 'rsa_pkcs1_padding' | 'rsa_pkcs1_oaep_padding' | - 'rsa_no_padding'

+

The following data types are used in the functions for public_key:

-

digest_type() - Union of below digest types

+ + oid() +

Object identifier, a tuple of integers as generated by the ASN.1 compiler.

 + + boolean() +

= true | false

 + + string() +

= [bytes()]

 + + der_encoded() +

= binary()

 + + pki_asn1_type() + =

'Certificate'

+

| 'RSAPrivateKey'

+

| 'RSAPublicKey'

+

| 'DSAPrivateKey'

+

| 'DSAPublicKey'

+

| 'DHParameter'

+

| 'SubjectPublicKeyInfo'

+

| 'PrivateKeyInfo'

+

| 'CertificationRequest'

+

| 'ECPrivateKey'

+

| 'EcpkParameters'

 + + pem_entry () +

= {pki_asn1_type(), binary(), %% DER or encrypted DER not_encrypted

+

| cipher_info()}

 + + cipher_info() +

= {"RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC", crypto:rand_bytes(8)

+

| {#'PBEParameter{}, digest_type()} | #'PBES2-params'{}}

+ + + public_key() +

= rsa_public_key() | dsa_public_key() | ec_public_key()

 + + private_key() +

= rsa_private_key() | dsa_private_key() | ec_private_key()

 + + rsa_public_key() +

= #'RSAPublicKey'{}

 + + rsa_private_key() +

= #'RSAPrivateKey'{}

 + + dsa_public_key() +

= {integer(), #'Dss-Parms'{}}

 + + dsa_private_key() +

= #'DSAPrivateKey'{}

 + + ec_public_key() +

= {#'ECPoint'{}, #'EcpkParameters'{} | {namedCurve, oid()}}

 + + ec_private_key() +

= #'ECPrivateKey'{}

 + + public_crypt_options() +

= [{rsa_pad, rsa_padding()}]

 + + rsa_padding() +

= 'rsa_pkcs1_padding'

+

| 'rsa_pkcs1_oaep_padding'

+

| 'rsa_no_padding'

+ + + digest_type() +

Union of rsa_digest_type(), dss_digest_type(), + and ecdsa_digest_type().

 + + rsa_digest_type() +

= 'md5' | 'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'

 + + dss_digest_type() +

= 'sha'

 + + ecdsa_digest_type() +

= 'sha'| 'sha224' | 'sha256' | 'sha384' | 'sha512'

 + + crl_reason() +

= unspecified

+

| keyCompromise

+

| cACompromise

+

| affiliationChanged

+

| superseded

+

| cessationOfOperation

+

| certificateHold

+

| privilegeWithdrawn

+

| aACompromise

+ + + issuer_name() +

= {rdnSequence,[#'AttributeTypeAndValue'{}]}

+ + + ssh_file() +

= openssh_public_key

+

| rfc4716_public_key

+

| known_hosts

+

| auth_keys

+ + -

rsa_digest_type() = 'md5' | 'sha' | 'sha224' | 'sha256' | 'sha384' | - 'sha512'

- -

dss_digest_type() = 'sha'

- -

ecdsa_digest_type() = 'sha'| 'sha224' | 'sha256' | 'sha384' | 'sha512'

- -

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

- -

issuer_name() = {rdnSequence,[#'AttributeTypeAndValue'{}]}

- -

ssh_file() = openssh_public_key | rfc4716_public_key | known_hosts | - auth_keys

@@ -138,12 +196,12 @@ - + - + @@ -151,13 +209,13 @@ - + - + - - + +
@@ -166,27 +224,27 @@ compute_key(OthersKey, MyKey)-> compute_key(OthersKey, MyKey, Params)-> - Compute shared secret + Computes shared secret. OthersKey = #'ECPoint'{} | binary(), MyKey = #'ECPrivateKey'{} | binary() Params = #'DHParameter'{} -

Compute shared secret

+

Computes shared secret.

 decrypt_private(CipherText, Key) -> binary() decrypt_private(CipherText, Key, Options) -> binary() - Public key decryption. + Public-key decryption. CipherText = binary() Key = rsa_private_key() Options = public_crypt_options() -

Public key decryption using the private key. See also Public-key decryption using the private key. See also crypto:private_decrypt/4

 @@ -194,156 +252,156 @@ decrypt_public(CipherText, Key) - > binary() decrypt_public(CipherText, Key, Options) - > binary() - + Public-key decryption. CipherText = binary() Key = rsa_public_key() Options = public_crypt_options() -

Public key decryption using the public key. See also Public-key decryption using the public key. See also crypto:public_decrypt/4

 der_decode(Asn1type, Der) -> term() - Decodes a public key ASN.1 DER encoded entity. + Decodes a public-key ASN.1 DER encoded entity. Asn1Type = atom() - ASN.1 type present in the public_key applications - asn1 specifications. + ASN.1 type present in the public_key applications + ASN.1 specifications. Der = der_encoded() -

Decodes a public key ASN.1 DER encoded entity.

+

Decodes a public-key ASN.1 DER encoded entity.

 der_encode(Asn1Type, Entity) -> der_encoded() - Encodes a public key entity with asn1 DER encoding. + Encodes a public-key entity with ASN.1 DER encoding. Asn1Type = atom() - Asn1 type present in the public_key applications + ASN.1 type present in the public_key applications ASN.1 specifications. Entity = term() - The erlang representation of Asn1Type + Erlang representation of Asn1Type -

Encodes a public key entity with ASN.1 DER encoding.

+

Encodes a public-key entity with ASN.1 DER encoding.

 generate_key(Params) -> {Public::binary(), Private::binary()} | #'ECPrivateKey'{} - Generates a new keypair + Generates a new keypair. - Params = #'DHParameter'{} | {namedCurve, oid()} | #'ECParameters'{} + Params = #'DHParameter'{} | {namedCurve, oid()} | #'ECParameters'{} -

Generates a new keypair

+

Generates a new keypair.

 pem_decode(PemBin) -> [pem_entry()] - Decode PEM binary data and return - entries as ASN.1 DER encoded entities. + Decodes PEM binary data and returns + entries as ASN.1 DER encoded entities. PemBin = binary() Example {ok, PemBin} = file:read_file("cert.pem"). -

Decode PEM binary data and return +

Decodes PEM binary data and returns entries as ASN.1 DER encoded entities.

 pem_encode(PemEntries) -> binary() - Creates a PEM binary + Creates a PEM binary. PemEntries = [pem_entry()] -

Creates a PEM binary

+

Creates a PEM binary.

 pem_entry_decode(PemEntry) -> term() pem_entry_decode(PemEntry, Password) -> term() - Decodes a pem entry. + Decodes a PEM entry. - PemEntry = pem_entry() - Password = string() + PemEntry = pem_entry() + Password = string() -

Decodes a PEM entry. pem_decode/1 returns a list of PEM - entries. Note that if the PEM entry is of type - 'SubjectPublickeyInfo' it will be further decoded to an - rsa_public_key() or dsa_public_key().

+

Decodes a PEM entry. pem_decode/1 returns a list of PEM + entries. Notice that if the PEM entry is of type + 'SubjectPublickeyInfo', it is further decoded to an + rsa_public_key() or dsa_public_key().

 pem_entry_encode(Asn1Type, Entity) -> pem_entry() pem_entry_encode(Asn1Type, Entity, {CipherInfo, Password}) -> pem_entry() - Creates a PEM entry that can be fed to pem_encode/1. + Creates a PEM entry that can be fed to pem_encode/1. Asn1Type = pki_asn1_type() Entity = term() - The Erlang representation of - Asn1Type. If Asn1Type is 'SubjectPublicKeyInfo' - then Entity must be either an rsa_public_key() or a - dsa_public_key() and this function will create the appropriate + Erlang representation of + Asn1Type. If Asn1Type is 'SubjectPublicKeyInfo', + Entity must be either an rsa_public_key() or a + dsa_public_key() and this function creates the appropriate 'SubjectPublicKeyInfo' entry. CipherInfo = cipher_info() Password = string() -

Creates a PEM entry that can be feed to pem_encode/1.

+

Creates a PEM entry that can be feed to pem_encode/1.

 encrypt_private(PlainText, Key) -> binary() - Public key encryption using the private key. + Public-key encryption using the private key. PlainText = binary() Key = rsa_private_key() -

Public key encryption using the private key. +

Public-key encryption using the private key. See also crypto:private_encrypt/4

+ marker="crypto:crypto#private_encrypt/4">crypto:private_encrypt/4.

 encrypt_public(PlainText, Key) -> binary() - Public key encryption using the public key. + Public-key encryption using the public key. PlainText = binary() Key = rsa_public_key() -

Public key encryption using the public key. See also crypto:public_encrypt/4

+

Public-key encryption using the public key. See also crypto:public_encrypt/4.

 pkix_decode_cert(Cert, otp|plain) -> #'Certificate'{} | #'OTPCertificate'{} - Decodes an ASN.1 DER encoded PKIX x509 certificate. + Decodes an ASN.1 DER-encoded PKIX x509 certificate. Cert = der_encoded() -

Decodes an ASN.1 DER encoded PKIX certificate. The otp option - will use the customized ASN.1 specification OTP-PKIX.asn1 for +

Decodes an ASN.1 DER-encoded PKIX certificate. Option otp + uses the customized ASN.1 specification OTP-PKIX.asn1 for decoding and also recursively decode most of the standard parts.

 @@ -355,54 +413,54 @@ certificate. Asn1Type = atom() - The ASN.1 type can be 'Certificate', 'OTPCertificate' or a subtype of either . + The ASN.1 type can be 'Certificate', 'OTPCertificate' or a subtype of either. Entity = #'Certificate'{} | #'OTPCertificate'{} | a valid subtype

DER encodes a PKIX x509 certificate or part of such a certificate. This function must be used for encoding certificates or parts of certificates - that are decoded/created in the otp format, whereas for the plain format this - function will directly call der_encode/2.

+ that are decoded/created in the otp format, whereas for the plain format this + function directly calls der_encode/2.

 pkix_is_issuer(Cert, IssuerCert) -> boolean() - Checks if IssuerCert issued Cert + Checks if IssuerCert issued Cert. Cert = der_encoded() | #'OTPCertificate'{} IssuerCert = der_encoded() | #'OTPCertificate'{} -

Checks if IssuerCert issued Cert

+

Checks if IssuerCert issued Cert.

 pkix_is_fixed_dh_cert(Cert) -> boolean() - Checks if a Certificate is a fixed Diffie-Hellman Cert. + Checks if a certificate is a fixed Diffie-Hellman certificate. Cert = der_encoded() | #'OTPCertificate'{} -

Checks if a Certificate is a fixed Diffie-Hellman Cert.

+

Checks if a certificate is a fixed Diffie-Hellman certificate.

 pkix_is_self_signed(Cert) -> boolean() - Checks if a Certificate is self signed. + Checks if a certificate is self-signed. Cert = der_encoded() | #'OTPCertificate'{} -

Checks if a Certificate is self signed.

+

Checks if a certificate is self-signed.

 pkix_issuer_id(Cert, IssuedBy) -> {ok, IssuerID} | {error, Reason} - Returns the issuer id. + Returns the issuer id. Cert = der_encoded() | #'OTPCertificate'{} IssuedBy = self | other @@ -411,43 +469,43 @@ Reason = term() -

Returns the issuer id.

+

Returns the issuer id.

 pkix_normalize_name(Issuer) -> Normalized - Normalizes a issuer name so that it can be easily - compared to another issuer name. + Normalizes an issuer name so that it can be easily + compared to another issuer name. Issuer = issuer_name() Normalized = issuer_name() -

Normalizes a issuer name so that it can be easily +

Normalizes an issuer name so that it can be easily compared to another issuer name.

 pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicKeyInfo, PolicyTree}} | {error, {bad_cert, Reason}} - Performs a basic path validation according to RFC 5280. + Performs a basic path validation according to RFC 5280. - TrustedCert = #'OTPCertificate'{} | der_encoded() | atom() - Normally a trusted certificate but it can also be a path validation + TrustedCert = #'OTPCertificate'{} | der_encode() | atom() + Normally a trusted certificate, but it can also be a path-validation error that can be discovered while - constructing the input to this function and that should be run through the verify_fun. - For example unknown_ca or selfsigned_peer + constructing the input to this function and that is to be run through the verify_fun. + Examples are unknown_ca and selfsigned_peer. - CertChain = [der_encoded()] - A list of DER encoded certificates in trust order ending with the peer certificate. - Options = proplists:proplist() + CertChain = [der_encode()] + A list of DER-encoded certificates in trust order ending with the peer certificate. + Options = proplists:proplist() PublicKeyInfo = {?'rsaEncryption' | ?'id-dsa', rsa_public_key() | integer(), 'NULL' | 'Dss-Parms'{}} - PolicyTree = term() - At the moment this will always be an empty list as Policies are not currently supported - Reason = cert_expired | invalid_issuer | invalid_signature | name_not_permitted | + PolicyTree = term() + At the moment this is always an empty list as policies are not currently supported. + Reason = cert_expired | invalid_issuer | invalid_signature | name_not_permitted | missing_basic_constraint | invalid_key_usage | {revoked, crl_reason()} | atom() @@ -455,17 +513,17 @@

Performs a basic path validation according to RFC 5280. - However CRL validation is done separately by pkix_crls_validate/3 and should be called - from the supplied verify_fun + However, CRL validation is done separately by pkix_crls_validate/3 and is to be called + from the supplied verify_fun.

- -

Available options are:

+

Available options:

+ {verify_fun, fun()} -

The fun should be defined as:

+

The fun must be defined as:

fun(OtpCert :: #'OTPCertificate'{}, @@ -478,53 +536,53 @@ fun(OtpCert :: #'OTPCertificate'{}, {unknown, UserState :: term()}. -

If the verify callback fun returns {fail, Reason}, the +

If the verify callback fun returns {fail, Reason}, the verification process is immediately stopped. If the verify - callback fun returns {valid, UserState}, the verification - process is continued, this can be used to accept specific path - validation errors such as selfsigned_peer as well as - verifying application specific extensions. If called with an - extension unknown to the user application the return value - {unknown, UserState} should be used.

+ callback fun returns {valid, UserState}, the verification + process is continued. This can be used to accept specific path + validation errors, such as selfsigned_peer, as well as + verifying application-specific extensions. If called with an + extension unknown to the user application, the return value + {unknown, UserState} is to be used.

 {max_path_length, integer()} The max_path_length is the maximum number of non-self-issued - intermediate certificates that may follow the peer certificate - in a valid certification path. So if max_path_length is 0 the PEER must - be signed by the trusted ROOT-CA directly, if 1 the path can - be PEER, CA, ROOT-CA, if it is 2 PEER, CA, CA, ROOT-CA and so - on. + intermediate certificates that can follow the peer certificate + in a valid certification path. So, if max_path_length is 0, the PEER must + be signed by the trusted ROOT-CA directly, if it is 1, the path can + be PEER, CA, ROOT-CA, if it is 2, the path can + be PEER, CA, CA, ROOT-CA, and so on. -

Possible reasons for a bad certificate are:

+

Possible reasons for a bad certificate:

cert_expired - The certificate is no longer valid as its expiration date has passed. +

Certificate is no longer valid as its expiration date has passed.

 invalid_issuer - The certificate issuer name does not match the name of the issuer certificate in the chain. +

Certificate issuer name does not match the name of the issuer certificate in the chain.

 invalid_signature - The certificate was not signed by its issuer certificate in the chain. +

Certificate was not signed by its issuer certificate in the chain.

 name_not_permitted - Invalid Subject Alternative Name extension. +

Invalid Subject Alternative Name extension.

 missing_basic_constraint - Certificate, required to have the basic constraints extension, does not have - a basic constraints extension. +

Certificate, required to have the basic constraints extension, does not have + a basic constraints extension.

 invalid_key_usage - Certificate key is used in an invalid way according to the key usage extension. +

Certificate key is used in an invalid way according to the key-usage extension.

 {revoked, crl_reason()} - Certificate has been revoked. +

Certificate has been revoked.

 atom() - Application specific error reason that should be checked by the verify_fun +

Application-specific error reason that is to be checked by the verify_fun.

 @@ -543,44 +601,47 @@ fun(OtpCert :: #'OTPCertificate'{}, pkix_crls_validate(OTPCertificate, DPAndCRLs, Options) -> CRLStatus() - Performs CRL validation. + Performs CRL validation. - OTPCertificate = #'OTPCertificate'{} - DPAndCRLs = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] - Options = proplists:proplist() - CRLStatus() = valid | {bad_cert, revocation_status_undetermined} | + OTPCertificate = #'OTPCertificate'{} + DPAndCRLs = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] + Options = proplists:proplist() + CRLStatus() = valid | {bad_cert, revocation_status_undetermined} | {bad_cert, {revoked, crl_reason()}} -

Performs CRL validation. It is intended to be called from +

Performs CRL validation. It is intended to be called from the verify fun of pkix_path_validation/3 -

+ .

+ +

Available options:

+ -

Available options are:

+ {update_crl, fun()} -

The fun has the following type spec:

+

The fun has the following type specification:

fun(#'DistributionPoint'{}, #'CertificateList'{}) -> #'CertificateList'{} -

The fun should use the information in the distribution point to acesses - the lates possible version of the CRL. If this fun is not specified - public_key will use the default implementation: +

The fun uses the information in the distribution point to access + the latest possible version of the CRL. If this fun is not specified, + public_key uses the default implementation:

fun(_DP, CRL) -> CRL end {issuer_fun, fun()} -

The fun has the following type spec:

+

The fun has the following type specification:

fun(#'DistributionPoint'{}, #'CertificateList'{}, {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) -> {ok, #'OTPCertificate'{}, [der_encoded]} -

The fun should return the root certificate and certificate chain +

The fun returns the root certificate and certificate chain that has signed the CRL.

fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain} @@ -635,83 +696,83 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, Key = rsa_public_key() | dsa_public_key() -

Signs a 'OTPTBSCertificate'. Returns the corresponding - der encoded certificate.

+

Signs an 'OTPTBSCertificate'. Returns the corresponding + DER-encoded certificate.

 pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType} - Translates signature algorithm oid to erlang digest and signature algorithm types. + Translates signature algorithm OID to Erlang digest and signature algorithm types. AlgorithmId = oid() - Signature oid from a certificate or a certificate revocation list - DigestType = rsa_digest_type() | dss_digest_type() + Signature OID from a certificate or a certificate revocation list. + DigestType = rsa_digest_type() | dss_digest_type() SignatureType = rsa | dsa -

Translates signature algorithm oid to erlang digest and signature types. +

Translates signature algorithm OID to Erlang digest and signature types.

pkix_verify(Cert, Key) -> boolean() - Verify pkix x.509 certificate signature. + Verifies PKIX x.509 certificate signature. Cert = der_encoded() Key = rsa_public_key() | dsa_public_key() -

Verify PKIX x.509 certificate signature.

+

Verifies PKIX x.509 certificate signature.

 sign(Msg, DigestType, Key) -> binary() - Create digital signature. + Creates a digital signature. Msg = binary() | {digest,binary()} - The msg is either the binary "plain text" data to be - signed or it is the hashed value of "plain text" i.e. the + The Msg is either the binary "plain text" data to be + signed or it is the hashed value of "plain text", that is, the digest. DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type() Key = rsa_private_key() | dsa_private_key() | ec_private_key() -

Creates a digital signature.

+

Creates a digital signature.

 ssh_decode(SshBin, Type) -> [{public_key(), Attributes::list()}] - Decodes a ssh file-binary. + Decodes an SSH file-binary. SshBin = binary() Example {ok, SshBin} = file:read_file("known_hosts"). - Type = public_key | ssh_file() - If Type is public_key the binary may be either - a rfc4716 public key or a openssh public key. + Type = public_key | ssh_file() + If Type is public_key the binary can be either + an RFC4716 public key or an OpenSSH public key. -

Decodes a ssh file-binary. In the case of know_hosts or - auth_keys the binary may include one or more lines of the +

Decodes an SSH file-binary. In the case of know_hosts or + auth_keys, the binary can include one or more lines of the file. Returns a list of public keys and their attributes, possible attribute values depends on the file type represented by the binary.

- rfc4716 attributes - see RFC 4716 - {headers, [{string(), utf8_string()}]} - auth_key attributes - see man sshd + RFC4716 attributes - see RFC 4716. +

{headers, [{string(), utf8_string()}]}

 + auth_key attributes - see manual page for sshd. {comment, string()} {options, [string()]} - {bits, integer()} - In ssh version 1 files - known_host attributes - see man sshd +

{bits, integer()} - In SSH version 1 files.

 + known_host attributes - see manual page for sshd. {hostnames, [string()]} {comment, string()} - {bits, integer()} - In ssh version 1 files +

{bits, integer()} - In SSH version 1 files.

 @@ -719,16 +780,16 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, ssh_encode([{Key, Attributes}], Type) -> binary() - Encodes a list of ssh file entries to a binary. + Encodes a list of SSH file entries to a binary. Key = public_key() Attributes = list() Type = ssh_file() -

Encodes a list of ssh file entries (public keys and attributes) to a binary. Possible - attributes depends on the file type, see ssh_decode/2

+

Encodes a list of SSH file entries (public keys and attributes) to a binary. Possible + attributes depend on the file type, see ssh_decode/2 .

 @@ -737,14 +798,14 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, Verifies a digital signature. Msg = binary() | {digest,binary()} - The msg is either the binary "plain text" data - or it is the hashed value of "plain text" i.e. the digest. + The Msg is either the binary "plain text" data + or it is the hashed value of "plain text", that is, the digest. DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type() Signature = binary() Key = rsa_public_key() | dsa_public_key() | ec_public_key() -

Verifies a digital signature

+

Veryfies a digital signature.

 diff --git a/lib/public_key/doc/src/public_key_records.xml b/lib/public_key/doc/src/public_key_records.xml index a7dfc41449..24f5faf38e 100644 --- a/lib/public_key/doc/src/public_key_records.xml +++ b/lib/public_key/doc/src/public_key_records.xml @@ -23,7 +23,7 @@ The Initial Developer of the Original Code is Ericsson AB. - Public key records + Public-Key Records Ingela Anderton Andin @@ -34,14 +34,14 @@ public_key_records.xml -

This chapter briefly describes Erlang records derived from ASN1 +

This section briefly describes Erlang records derived from ASN.1 specifications used to handle public and private keys. - The intent is to describe the data types - and not to specify the semantics of each component. For information on the - semantics, please see the relevant standards and RFCs.

+ The scope is to describe the data types of each component, + not the semantics. For information on the + semantics, refer to the relevant standards and RFCs.

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

+ records and constant macros described in the following sections:

-include_lib("public_key/include/public_key.hrl"). @@ -49,13 +49,15 @@ 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

+ data types used to describe the record fields in the + following sections are defined in the public_key Reference Manual.

- RSA as defined by the PKCS-1 standard and <url href="http://www.ietf.org/rfc/rfc3447.txt"> RFC 3447 </url> + The RSA According to PKCS-1 and RFC 3447 +

RSA as defined by the PKCS-1 standard and + RFC 3447 follows:

#'RSAPublicKey'{ @@ -80,15 +82,15 @@ prime, % integer() exponent, % integer() coefficient % integer() - }. - + }.
- DSA as defined by - <url href="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf"> Digital Signature Standard (NIST FIPS PUB 186-2) </url> - + DSA According to DSS +

The DSA as defined by the + + Digital Signature Standard (DSS), NIST FIPS PUB 186-2 follows:

#'DSAPrivateKey',{ @@ -104,13 +106,13 @@ p, % integer() q, % integer() g % integer() - }. - + }.
- ECC (Elliptic Curve) <url href="http://www.ietf.org/rfc/rfc3447.txt"> RFC 5480 </url> - + ECC According to RFC 5480 +

The Elliptic Curve (ECC) as defined by + RFC 5480 follows:

#'ECPrivateKey'{ diff --git a/lib/public_key/doc/src/records.xml b/lib/public_key/doc/src/records.xml new file mode 100644 index 0000000000..75265791af --- /dev/null +++ b/lib/public_key/doc/src/records.xml @@ -0,0 +1,47 @@ + + + + +
+ + 2008 + 2014 + 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + Records + Tommy Månevik + + 2015-04-01 + + records.xml +
+ +

This section describes Erlang records derived from ASN.1 specifications, + used to handle the following: +

+ + Public and private keys + X509 certificates and CertificationRequest + + + + + + + + diff --git a/lib/public_key/doc/src/ref_man.xml b/lib/public_key/doc/src/ref_man.xml index b7078891d4..9c80cf4b9f 100644 --- a/lib/public_key/doc/src/ref_man.xml +++ b/lib/public_key/doc/src/ref_man.xml @@ -31,8 +31,8 @@ ref_man.xml -

Provides functions to handle public key infrastructure - from RFC 3280 (X.509 certificates) and some parts of the PKCS-standard. +

The public_key application provides functions to handle public-key infrastructure + from RFC 3280 (X.509 certificates) and parts of the PKCS standard.

diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml index 450bd7e35f..69b8c0dcb9 100644 --- a/lib/public_key/doc/src/using_public_key.xml +++ b/lib/public_key/doc/src/using_public_key.xml @@ -22,27 +22,27 @@ Getting Started + + + + using_public_key.xml -
- General information +

This section describes examples of how to use the + public_key API. Keys and certificates used in the following + sections are generated only for testing the public_key + application.

-

This chapter is dedicated to showing some - examples of how to use the public_key API. Keys and certificates - used in the following sections are generated only for the purpose - of testing the public key application.

+

Some shell printouts in the following examples + are abbreviated for increased readability.

-

Note that some shell printouts, in the following examples, - have been abbreviated for increased readability.

- -
- +
- PEM files -

Public key data (keys, certificates etc) may be stored in PEM format. PEM files - comes from the Private Enhanced Mail Internet standard and has a - structure that looks like this:

+ PEM Files +

Public-key data (keys, certificates, and so on) can be stored in + Privacy Enhanced Mail (PEM) format. + The PEM files have the following structure:

<text> -----BEGIN <SOMETHING>----- @@ -51,19 +51,20 @@ -----END <SOMETHING>----- <text> -

A file can contain several BEGIN/END blocks. Text lines between - blocks are ignored. Attributes, if present, are currently ignored except - for Proc-Type and DEK-Info that are used when the DER data is - encrypted.

+

A file can contain several BEGIN/END blocks. Text lines between + blocks are ignored. Attributes, if present, are ignored except + for Proc-Type and DEK-Info, which are used when DER + data is encrypted.

- DSA private key + DSA Private Key +

A DSA private key can look as follows:

+

File handling is not done by the public_key application.

 -

Note file handling is not done by the public_key application.

1> {ok, PemBin} = file:read_file("dsa.pem"). {ok,<<"-----BEGIN DSA PRIVATE KEY-----\nMIIBuw"...>>} -

This PEM file only has one entry, a private DSA key.

+

The following PEM file has only one entry, a private DSA key:

2> [DSAEntry] = public_key:pem_decode(PemBin). [{'DSAPrivateKey',<<48,130,1,187,2,1,0,2,129,129,0,183, 179,230,217,37,99,144,157,21,228,204, @@ -80,21 +81,20 @@
- RSA private key encrypted with a password. + RSA Private Key with Password +

An RSA private key encrypted with a password can look as follows:

1> {ok, PemBin} = file:read_file("rsa.pem"). {ok,<<"Bag Attribut"...>>} -

This PEM file only has one entry a private RSA key.

+

The following PEM file has only one entry, a private RSA key:

2>[RSAEntry] = public_key:pem_decode(PemBin). [{'RSAPrivateKey',<<224,108,117,203,152,40,15,77,128,126, 221,195,154,249,85,208,202,251,109, 119,120,57,29,89,19,9,...>>, - {"DES-EDE3-CBC",<<"kÙeø¼pµL">>}}] - - + {"DES-EDE3-CBC",<<"kÙeø¼pµL">>}}] -

In this example the password is "abcd1234".

+

In this following example, the password is "abcd1234":

3> Key = public_key:pem_entry_decode(RSAEntry, "abcd1234"). #'RSAPrivateKey'{version = 'two-prime', modulus = 1112355156729921663373...2737107, @@ -110,11 +110,12 @@
X509 Certificates +

The following is an example of X509 certificates:

1> {ok, PemBin} = file:read_file("cacerts.pem"). {ok,<<"-----BEGIN CERTIFICATE-----\nMIIC7jCCAl"...>>} -

This file includes two certificates

+

The following file includes two certificates:

2> [CertEntry1, CertEntry2] = public_key:pem_decode(PemBin). [{'Certificate',<<48,130,2,238,48,130,2,87,160,3,2,1,2,2, 9,0,230,145,97,214,191,2,120,150,48,13, @@ -124,7 +125,7 @@ 1,48,13,6,9,42,134,72,134,247,...>>>, not_encrypted}] -

Certificates may of course be decoded as usual ...

+

Certificates can be decoded as usual:

2> Cert = public_key:pem_entry_decode(CertEntry1). #'Certificate'{ tbsCertificate = @@ -212,22 +213,23 @@ signature = {0, <<163,186,7,163,216,152,63,47,154,234,139,73,154,96,120, - 165,2,52,196,195,109,167,192,...>>}} - - -

Parts of certificates can be decoded with - public_key:der_decode/2 using that parts ASN.1 type. - Although application specific certificate - extension requires application specific ASN.1 decode/encode-functions. - Example, the first value of the rdnSequence above is of ASN.1 type - 'X520CommonName'. ({2,5,4,3} = ?id-at-commonName)

+ 165,2,52,196,195,109,167,192,...>>}} + +

Parts of certificates can be decoded with + public_key:der_decode/2, using the ASN.1 type of that part. + However, an application-specific certificate extension requires + application-specific ASN.1 decode/encode-functions. + In the recent example, the first value of rdnSequence is + of ASN.1 type 'X520CommonName'. ({2,5,4,3} = ?id-at-commonName):

public_key:der_decode('X520CommonName', <<19,8,101,114,108,97,110,103,67,65>>). {printableString,"erlangCA"} -

... but certificates can also be decode using the pkix_decode_cert/2 that - can customize and recursively decode standard parts of a certificate.

+

However, certificates can also be decoded using pkix_decode_cert/2, + which can customize and recursively decode standard parts of a certificate:

+ 3>{_, DerCert, _} = CertEntry1. + 4> public_key:pkix_decode_cert(DerCert, otp). #'OTPCertificate'{ tbsCertificate = @@ -316,28 +318,26 @@ signature = {0, <<163,186,7,163,216,152,63,47,154,234,139,73,154,96,120, - 165,2,52,196,195,109,167,192,...>>}} - + 165,2,52,196,195,109,167,192,...>>}} -

This call is equivalent to public_key:pem_entry_decode(CertEntry1)

+

This call is equivalent to public_key:pem_entry_decode(CertEntry1):

5> public_key:pkix_decode_cert(DerCert, plain). -#'Certificate'{ ...} - +#'Certificate'{ ...}
- Encoding public key data to PEM format + Encoding Public-Key Data to PEM Format -

If you have public key data and and want to create a PEM file - you can do that by calling the functions - public_key:pem_entry_encode/2 and pem_encode/1 and then saving the - result to a file. For example assume you have PubKey = - 'RSAPublicKey'{} then you can create a PEM-"RSA PUBLIC KEY" file - (ASN.1 type 'RSAPublicKey') or a PEM-"PUBLIC KEY" file - ('SubjectPublicKeyInfo' ASN.1 type).

+

If you have public-key data and want to create a PEM file + this can be done by calling functions + public_key:pem_entry_encode/2 and pem_encode/1 and + saving the result to a file. For example, assume that you have + PubKey = 'RSAPublicKey'{}. Then you can create a PEM-"RSA PUBLIC KEY" + file (ASN.1 type 'RSAPublicKey') or a PEM-"PUBLIC KEY" file + ('SubjectPublicKeyInfo' ASN.1 type).

-

The second element of the PEM-entry will be the ASN.1 DER encoded - key data.

+

The second element of the PEM-entry is the ASN.1 DER encoded + key data:

1> PemEntry = public_key:pem_entry_encode('RSAPublicKey', RSAPubKey). {'RSAPublicKey', <<48,72,...>>, not_encrypted} @@ -348,7 +348,7 @@ 3> file:write_file("rsa_pub_key.pem", PemBin). ok -

or

+

or:

1> PemEntry = public_key:pem_entry_encode('SubjectPublicKeyInfo', RSAPubKey). {'SubjectPublicKeyInfo', <<48,92...>>, not_encrypted} @@ -363,96 +363,106 @@ ok
- RSA public key cryptography -

Suppose you have PrivateKey = #'RSAPrivateKey{}' and the - plaintext Msg = binary() and the corresponding public key - PublicKey = #'RSAPublicKey'{} then you can do the following. - Note that you normally will only do one of the encrypt or - decrypt operations and the peer will do the other. -

- -

Encrypt with the private key

+ RSA Public-Key Cryptography +

Suppose you have the followwing private key and a corresponding public key:

+ + PrivateKey = #'RSAPrivateKey{}' and + the plaintext Msg = binary() + PublicKey = #'RSAPublicKey'{} + + +

Then you can proceed as follows:

+ +

Encrypt with the private key:

RsaEncrypted = public_key:encrypt_private(Msg, PrivateKey), Msg = public_key:decrypt_public(RsaEncrypted, PublicKey), -

Encrypt with the public key

+

Encrypt with the public key:

RsaEncrypted = public_key:encrypt_public(Msg, PublicKey), Msg = public_key:decrypt_private(RsaEncrypted, PrivateKey), + +

You normally do only one of the encrypt or decrypt operations, + and the peer does the other.

 +
- Digital signatures + Digital Signatures -

Suppose you have PrivateKey = #'RSAPrivateKey{}'or - #'DSAPrivateKey'{} and the plaintext Msg = binary() and the - corresponding public key PublicKey = #'RSAPublicKey'{} or - {integer(), #'DssParams'{}} then you can do the following. Note - that you normally will only do one of the sign or verify operations - and the peer will do the other.

+

Suppose you have the following private key and a corresponding public key:

+ + + PrivateKey = #'RSAPrivateKey{}' or + #'DSAPrivateKey'{} and the plaintext Msg = binary() + PublicKey = #'RSAPublicKey'{} or + {integer(), #'DssParams'{}} + +

Then you can proceed as follows:

Signature = public_key:sign(Msg, sha, PrivateKey), true = public_key:verify(Msg, sha, Signature, PublicKey), -

It might be appropriate to calculate the message digest before - calling sign or verify and then you can use the none as second - argument.

+

You normally do only one of the sign or verify operations, + and the peer does the other.

 + +

It can be appropriate to calculate the message digest before + calling sign or verify, and then use none as + second argument:

Digest = crypto:sha(Msg), Signature = public_key:sign(Digest, none, PrivateKey), -true = public_key:verify(Digest, none, Signature, PublicKey), - +true = public_key:verify(Digest, none, Signature, PublicKey),
- SSH files + SSH Files

SSH typically uses PEM files for private keys but has its - own file format for storing public keys. The erlang public_key - application can be used to parse the content of SSH public key files.

+ own file format for storing public keys. The public_key + application can be used to parse the content of SSH public-key files.

- RFC 4716 SSH public key files + RFC 4716 SSH Public-Key Files

RFC 4716 SSH files looks confusingly like PEM files, - but there are some differences.

+ but there are some differences:

1> {ok, SshBin} = file:read_file("ssh2_rsa_pub"). {ok, <<"---- BEGIN SSH2 PUBLIC KEY ----\nAAAA"...>>} -

This is equivalent to calling public_key:ssh_decode(SshBin, rfc4716_public_key). +

This is equivalent to calling public_key:ssh_decode(SshBin, rfc4716_public_key):

2> public_key:ssh_decode(SshBin, public_key). [{#'RSAPublicKey'{modulus = 794430685...91663, - publicExponent = 35}, []}] - + publicExponent = 35}, []}]
- Openssh public key format + OpenSSH Public-Key Format +

OpenSSH public-key format looks as follows:

1> {ok, SshBin} = file:read_file("openssh_dsa_pub"). {ok,<<"ssh-dss AAAAB3Nza"...>>} -

This is equivalent to calling public_key:ssh_decode(SshBin, openssh_public_key). +

This is equivalent to calling public_key:ssh_decode(SshBin, openssh_public_key):

2> public_key:ssh_decode(SshBin, public_key). [{{15642692...694280725, #'Dss-Parms'{p = 17291273936...696123221, q = 1255626590179665817295475654204371833735706001853, g = 10454211196...480338645}}, - [{comment,"dhopson@VMUbuntu-DSH"}]}] - + [{comment,"dhopson@VMUbuntu-DSH"}]}]
- Known hosts - openssh format - + Known Hosts - OpenSSH Format +

Known hosts - OpenSSH format looks as follows:

1> {ok, SshBin} = file:read_file("known_hosts"). {ok,<<"hostname.domain.com,192.168.0.1 ssh-rsa AAAAB...>>} -

Returns a list of public keys and their related attributes - each pair of key and attributes corresponds to one entry in - the known hosts file.

+

Returns a list of public keys and their related attributes. + Each pair of key and attribute corresponds to one entry in + the known hosts file:

2> public_key:ssh_decode(SshBin, known_hosts). [{#'RSAPublicKey'{modulus = 1498979460408...72721699, @@ -461,19 +471,19 @@ true = public_key:verify(Digest, none, Signature, PublicKey), {#'RSAPublicKey'{modulus = 14989794604088...2721699, publicExponent = 35}, [{comment,"foo@bar.com"}, - {hostnames,["|1|BWO5qDxk/cFH0wa05JLdHn+j6xQ=|rXQvIxh5cDD3C43k5DPDamawVNA="]}]}] - + {hostnames,["|1|BWO5qDxk/cFH0wa05JLdHn+j6xQ=|rXQvIxh5cDD3C43k5DPDamawVNA="]}]}]
- Authorized keys - openssh format + Authorized Keys - OpenSSH Format +

Authorized keys - OpenSSH format looks as follows:

1> {ok, SshBin} = file:read_file("auth_keys"). {ok, <<"command=\"dump /home\",no-pty,no-port-forwarding ssh-rsa AAA...>>} -

Returns a list of public keys and their related attributes - each pair of key and attributes corresponds to one entry in - the authorized key file.

+

Returns a list of public keys and their related attributes. + Each pair of key and attribute corresponds to one entry in + the authorized key file:

2> public_key:ssh_decode(SshBin, auth_keys). [{#'RSAPublicKey'{modulus = 794430685...691663, @@ -485,16 +495,15 @@ true = public_key:verify(Digest, none, Signature, PublicKey), #'Dss-Parms'{p = 17291273936185...763696123221, q = 1255626590179665817295475654204371833735706001853, g = 10454211195705...60511039590076780999046480338645}}, - [{comment,"dhopson@VMUbuntu-DSH"}]}] - + [{comment,"dhopson@VMUbuntu-DSH"}]}]
- Creating an SSH file from public key data + Creating an SSH File from Public-Key Data

If you got a public key PubKey and a related list of attributes Attributes as returned - by ssh_decode/2 you can create a new ssh file for example

+ by ssh_decode/2, you can create a new SSH file, for example:

N> SshBin = public_key:ssh_encode([{PubKey, Attributes}], openssh_public_key), <<"ssh-rsa "...>> N+1> file:write_file("id_rsa.pub", SshBin). -- cgit v1.2.3 From 25575183ca581a080478ad499e308a76e44e4def Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 24 Apr 2015 17:42:54 +0200 Subject: public_key: Change structure to what editor intended --- lib/public_key/doc/src/Makefile | 3 +- lib/public_key/doc/src/cert_records.xml | 743 ----------------------- lib/public_key/doc/src/public_key.xml | 3 +- lib/public_key/doc/src/public_key_records.xml | 155 ----- lib/public_key/doc/src/records.xml | 821 +++++++++++++++++++++++++- 5 files changed, 804 insertions(+), 921 deletions(-) delete mode 100644 lib/public_key/doc/src/cert_records.xml delete mode 100644 lib/public_key/doc/src/public_key_records.xml diff --git a/lib/public_key/doc/src/Makefile b/lib/public_key/doc/src/Makefile index 17fb67e95c..2adc13a5cf 100644 --- a/lib/public_key/doc/src/Makefile +++ b/lib/public_key/doc/src/Makefile @@ -42,8 +42,7 @@ XML_REF6_FILES = XML_PART_FILES = part.xml part_notes.xml XML_CHAPTER_FILES = \ introduction.xml \ - public_key_records.xml \ - cert_records.xml \ + records.xml \ using_public_key.xml \ notes.xml diff --git a/lib/public_key/doc/src/cert_records.xml b/lib/public_key/doc/src/cert_records.xml deleted file mode 100644 index 4d4533fe21..0000000000 --- a/lib/public_key/doc/src/cert_records.xml +++ /dev/null @@ -1,743 +0,0 @@ - - - - -
- - 2008 - 2014 - 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. - - The Initial Developer of the Original Code is Ericsson AB. - - - Certificate Records - Ingela Anderton Andin - - - - - 2008-02-06 - A - cert_records.xml -
- -

This section briefly describes Erlang records derived from ASN.1 - specifications used to handle X509 certificates and CertificationRequest. - The scope is to describe the data types of each component, - not the semantics. For information on the semantics, refer 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 ASN.1 specifications are available in the asn1 subdirectory - of the public_key application.

- -
- Common Data Types - -

Common non-standard Erlang - data types used to describe the record fields in the - following sections are defined in the 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, binary()}

-

| {bmpString, string()}

- - - dist_reason() - =

unused

-

| keyCompromise

-

| cACompromise

-

| affiliationChanged

-

| superseded

-

| cessationOfOperation

-

| certificateHold

-

| privilegeWithdrawn

-

| aACompromise

- - - -
- -
- PKIX Certificates -

Erlang representation of PKIX certificates derived from ASN.1 - specifications and RFC 5280 are as follows:

- -#'Certificate'{ - tbsCertificate, % #'TBSCertificate'{} - signatureAlgorithm, % #'AlgorithmIdentifier'{} - signature % 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 % 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'{} - }. - -

Here, id_signature_algorithm() = ?OID name, for available OID names, for example -?id-dsa-with-sha1. That is, by prepending "?" to the OID name, represented as an Erlang atom.

-

The available OID names are as follows:

- - - OID Name - - - id-dsa-with-sha1 - - - id-dsaWithSHA1 (ISO or OID to above) - - - md2WithRSAEncryption - - - md5WithRSAEncryption - - - sha1WithRSAEncryption - - - sha-1WithRSAEncryption (ISO or OID to above) - - - sha224WithRSAEncryption - - - sha256WithRSAEncryption - - - sha512WithRSAEncryption - - - ecdsa-with-SHA1 - - Signature Algorithm OIDs -
- -

The data type 'AttributeTypeAndValue', is represented as - the following erlang record:

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

The attribute OID name atoms and their corresponding value types -are as follows:

- - - 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() - - Attribute OIDs -
- -

The data types 'Validity', 'SubjectPublicKeyInfo', and -'SubjectPublicKeyInfoAlgorithm' are represented as the following Erlang records:

- - -#'Validity'{ - notBefore, % time() - notAfter % time() - }. - -#'SubjectPublicKeyInfo'{ - algorithm, % #AlgorithmIdentifier{} - subjectPublicKey % binary() - }. - -#'SubjectPublicKeyInfoAlgorithm'{ - algorithm, % id_public_key_algorithm() - parameters % public_key_params() - }. - -

The public-key algorithm OID name atoms are as follows:

- - - OID Name - - - rsaEncryption - - - id-dsa - - - dhpublicnumber - - - id-keyExchangeAlgorithm - - - id-ecPublicKey - - 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. -

- -
- -
- - Standard Certificate Extensions - -

The standard certificate extensions OID name atoms and their - corresponding value types are as follows:

- - - - 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'{}] - - - - Standard Certificate Extensions -
- -

Here:

- - key_usage() - =

digitalSignature

-

| nonRepudiation

-

| keyEncipherment

-

| dataEncipherment

-

| keyAgreement

-

| keyCertSign

-

| cRLSign

-

| encipherOnly

-

| decipherOnly

- - - -

And for id_key_purpose():

- - - - OID Name - - - id-kp-serverAuth - - - id-kp-clientAuth - - - id-kp-codeSigning - - - id-kp-emailProtection - - - id-kp-timeStamping - - - id-kp-OCSPSigning - - 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()] - }). - -
- -
- - Private Internet Extensions - -

The private internet extensions OID name atoms and their corresponding value - types are as follows:

- - - - OID Name - Value Type - - - id-pe-authorityInfoAccess - [#'AccessDescription'{}] - - - id-pe-subjectInfoAccess - [#'AccessDescription'{}] - - Private Internet Extensions -
- - -#'AccessDescription'{ - accessMethod, % oid() - accessLocation % general_name() - }). - -
- -
- CRL and CRL Extensions Profile - -

Erlang representation of CRL and CRL extensions profile - derived from ASN.1 specifications and RFC 5280 are as follows:

- - -#'CertificateList'{ - tbsCertList, % #'TBSCertList{} - signatureAlgorithm, % #'AlgorithmIdentifier'{} - signature % 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 - -

The CRL extensions OID name atoms and their corresponding value types are as follows:

- - - - - 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'{}] - - - CRL Extensions -
- -

Here, the data type 'IssuingDistributionPoint' is represented as - the following Erlang record:

- - -#'IssuingDistributionPoint'{ - distributionPoint, % {fullName, [general_name()]} | {nameRelativeToCRLIssuer, - [#AttributeTypeAndValue'{}]} - onlyContainsUserCerts, % boolean() - onlyContainsCACerts, % boolean() - onlySomeReasons, % [dist_reason()] - indirectCRL, % boolean() - onlyContainsAttributeCerts % boolean() - }). -
- -
- - CRL Entry Extensions - -

The CRL entry extensions OID name atoms and their corresponding value types are as follows:

- - - - OID Name - Value Type - - - id-ce-cRLReason - crl_reason() - - - id-ce-holdInstructionCode - oid() - - - id-ce-invalidityDate - general_time() - - - id-ce-certificateIssuer - general_name() - - CRL Entry Extensions -
- - -

Here:

- - crl_reason() - =

unspecifiedc>

-

| keyCompromise

-

| cACompromise

-

| affiliationChanged

-

| superseded

-

| cessationOfOperation

-

| certificateHold

-

| removeFromCRL

-

| privilegeWithdrawn

-

| aACompromise

- - - -
- -
- - PKCS#10 Certification Request -

Erlang representation of a PKCS#10 certification request - derived from ASN.1 specifications and RFC 5280 are as follows:

- -#'CertificationRequest'{ - certificationRequestInfo #'CertificationRequestInfo'{}, - signatureAlgorithm #'CertificationRequest_signatureAlgorithm'{}}. - signature bitstring() - } - -#'CertificationRequestInfo'{ - version atom(), - subject {rdnSequence, [#AttributeTypeAndValue'{}]} , - subjectPKInfo #'CertificationRequestInfo_subjectPKInfo'{}, - attributes [#'AttributePKCS-10' {}] - } - -#'CertificationRequestInfo_subjectPKInfo'{ - algorithm #'CertificationRequestInfo_subjectPKInfo_algorithm'{} - subjectPublicKey bitstring() - } - -#'CertificationRequestInfo_subjectPKInfo_algorithm'{ - algorithm = oid(), - parameters = der_encoded() -} - -#'CertificationRequest_signatureAlgorithm'{ - algorithm = oid(), - parameters = der_encoded() - } - -#'AttributePKCS-10'{ - type = oid(), - values = [der_encoded()] -} -
- -
- diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index ddaa8c2530..3d5c135075 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -73,8 +73,7 @@ are generated from ASN.1 specifications and are documented in the User's Guide. See Public-key Records and X.509 Certificate Records. + marker="public_key_records">Public-key Records.

Use the following include directive to get access to the diff --git a/lib/public_key/doc/src/public_key_records.xml b/lib/public_key/doc/src/public_key_records.xml deleted file mode 100644 index 24f5faf38e..0000000000 --- a/lib/public_key/doc/src/public_key_records.xml +++ /dev/null @@ -1,155 +0,0 @@ - - - - -

- - 2008 - 2014 - 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. - - The Initial Developer of the Original Code is Ericsson AB. - - - Public-Key Records - Ingela Anderton Andin - - - - - 2008-02-06 - A - public_key_records.xml -
- -

This section briefly describes Erlang records derived from ASN.1 - specifications used to handle public and private keys. - The scope is to describe the data types of each component, - not the semantics. For information on the - semantics, refer to the relevant standards and RFCs.

- -

Use the following include directive to get access to the - records and constant macros described in the following sections:

- - -include_lib("public_key/include/public_key.hrl"). - -
- Common Data Types - -

Common non-standard Erlang - data types used to describe the record fields in the - following sections are defined in the public_key Reference Manual.

-
- -
- The RSA According to PKCS-1 and RFC 3447 -

RSA as defined by the PKCS-1 standard and - RFC 3447 follows:

- - -#'RSAPublicKey'{ - modulus, % integer() - publicExponent % integer() - }. - -#'RSAPrivateKey'{ - version, % two-prime | multi - modulus, % integer() - publicExponent, % integer() - privateExponent, % integer() - prime1, % integer() - prime2, % integer() - exponent1, % integer() - exponent2, % integer() - coefficient, % integer() - otherPrimeInfos % [#OtherPrimeInfo{}] | asn1_NOVALUE - }. - -#'OtherPrimeInfo'{ - prime, % integer() - exponent, % integer() - coefficient % integer() - }. - -
- -
- DSA According to DSS -

The DSA as defined by the - - Digital Signature Standard (DSS), NIST FIPS PUB 186-2 follows:

- - -#'DSAPrivateKey',{ - version, % integer() - p, % integer() - q, % integer() - g, % integer() - y, % integer() - x % integer() - }. - -#'Dss-Parms',{ - p, % integer() - q, % integer() - g % integer() - }. -
- -
- ECC According to RFC 5480 -

The Elliptic Curve (ECC) as defined by - RFC 5480 follows:

- - -#'ECPrivateKey'{ - version, % integer() - privateKey, % binary() - parameters, % der_encoded() - {'EcpkParameters', #'ECParameters'{}} | - {'EcpkParameters', {namedCurve, oid()}} | - {'EcpkParameters', 'NULL'} % Inherited by CA - publicKey % bitstring() - }. - -#'ECParameters'{ - version, % integer() - fieldID, % #'FieldID'{} - curve, % #'Curve'{} - base, % binary() - order, % integer() - cofactor % integer() - }. - -#'Curve'{ - a, % binary() - b, % binary() - seed % bitstring() - optional - - }. - -#'FieldID'{ - fieldType, % oid() - parameters % Depending on fieldType - }. - -#'ECPoint'{ - point % binary() - the public key - }. - - -
- - diff --git a/lib/public_key/doc/src/records.xml b/lib/public_key/doc/src/records.xml index 75265791af..ac1ecd176c 100644 --- a/lib/public_key/doc/src/records.xml +++ b/lib/public_key/doc/src/records.xml @@ -1,7 +1,7 @@ - + - +
2008 @@ -23,25 +23,808 @@ The Initial Developer of the Original Code is Ericsson AB. - Records - Tommy Månevik + Public-Key Records + Ingela Anderton Andin + - 2015-04-01 - - records.xml + + + 2008-02-06 + A + public_key_records.xml
- -

This section describes Erlang records derived from ASN.1 specifications, - used to handle the following: -

- - Public and private keys - X509 certificates and CertificationRequest - - + +

This chapter briefly describes Erlang records derived from ASN.1 + specifications used to handle public key infrastructure. + The scope is to describe the data types of each component, + not the semantics. For information on the + semantics, refer to the relevant standards and RFCs linked in the sections below.

+ +

Use the following include directive to get access to the + records and constant macros described in the following sections:

+ + -include_lib("public_key/include/public_key.hrl"). + +
+ Data Types + +

Common non-standard Erlang + data types used to describe the record fields in the + following sections and which are not defined in the public_key Reference Manual + 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, binary()}

+

| {bmpString, string()}

+ + + dist_reason() + =

unused

+

| keyCompromise

+

| cACompromise

+

| affiliationChanged

+

| superseded

+

| cessationOfOperation

+

| certificateHold

+

| privilegeWithdrawn

+

| aACompromise

+ + + +
+ +
+ RSA +

Erlang representation of + Rivest-Shamir-Adleman cryptosystem (RSA) keys follows:

+ + +#'RSAPublicKey'{ + modulus, % integer() + publicExponent % integer() + }. + +#'RSAPrivateKey'{ + version, % two-prime | multi + modulus, % integer() + publicExponent, % integer() + privateExponent, % integer() + prime1, % integer() + prime2, % integer() + exponent1, % integer() + exponent2, % integer() + coefficient, % integer() + otherPrimeInfos % [#OtherPrimeInfo{}] | asn1_NOVALUE + }. + +#'OtherPrimeInfo'{ + prime, % integer() + exponent, % integer() + coefficient % integer() + }. + +
+ +
+ DSA +

Erlang representation of Digigital Signature Algorithm (DSA) keys

+ +#'DSAPrivateKey',{ + version, % integer() + p, % integer() + q, % integer() + g, % integer() + y, % integer() + x % integer() + }. + +#'Dss-Parms',{ + p, % integer() + q, % integer() + g % integer() + }. + +
+ +
+ ECDSA +

Erlang representation of Elliptic Curve Digital Signature Algorithm (ECDSA) keys follows:

+ + +#'ECPrivateKey'{ + version, % integer() + privateKey, % octet_string() + parameters, % der_encoded() - {'EcpkParameters', #'ECParameters'{}} | + {'EcpkParameters', {namedCurve, oid()}} | + {'EcpkParameters', 'NULL'} % Inherited by CA + publicKey % bitstring() + }. + +#'ECParameters'{ + version, % integer() + fieldID, % #'FieldID'{} + curve, % #'Curve'{} + base, % octet_string() + order, % integer() + cofactor % integer() + }. + +#'Curve'{ + a, % octet_string() + b, % octet_string() + seed % bitstring() - optional + + }. + +#'FieldID'{ + fieldType, % oid() + parameters % Depending on fieldType + }. + +#'ECPoint'{ + point % octet_string() - the public key + }. +
+ +
+ PKIX Certificates +

Erlang representation of PKIX certificates derived from ASN.1 + specifications see also X509 certificates (RFC 5280) are as follows:

+ +#'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'{} + }. + +

Here, id_signature_algorithm() = ?OID name, for available OID names, for example +?id-dsa-with-sha1. That is, by prepending "?" to the OID name, represented as an Erlang atom.

+

The available OID names are as follows:

+ + + OID Name + + + id-dsa-with-sha1 + + + id-dsaWithSHA1 (ISO or OID to above) + + + md2WithRSAEncryption + + + md5WithRSAEncryption + + + sha1WithRSAEncryption + + + sha-1WithRSAEncryption (ISO or OID to above) + + + sha224WithRSAEncryption + + + sha256WithRSAEncryption + + + sha512WithRSAEncryption + + + ecdsa-with-SHA1 + + Signature Algorithm OIDs +
+ +

The data type 'AttributeTypeAndValue', is represented as + the following erlang record:

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

The attribute OID name atoms and their corresponding value types +are as follows:

+ + + 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() + + Attribute OIDs +
+ +

The data types 'Validity', 'SubjectPublicKeyInfo', and +'SubjectPublicKeyInfoAlgorithm' are represented as the following Erlang records:

+ + +#'Validity'{ + notBefore, % time() + notAfter % time() + }. + +#'SubjectPublicKeyInfo'{ + algorithm, % #AlgorithmIdentifier{} + subjectPublicKey % binary() + }. + +#'SubjectPublicKeyInfoAlgorithm'{ + algorithm, % id_public_key_algorithm() + parameters % public_key_params() + }. + +

The public-key algorithm OID name atoms are as follows:

+ + + OID Name + + + rsaEncryption + + + id-dsa + + + dhpublicnumber + + + id-keyExchangeAlgorithm + + + id-ecPublicKey + + 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. +

+ +
+ +
+ + Standard Certificate Extensions + +

The standard certificate extensions OID name atoms and their + corresponding value types are as follows:

+ + + + 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'{}] + + + + Standard Certificate Extensions +
+ +

Here:

+ + key_usage() + =

digitalSignature

+

| nonRepudiation

+

| keyEncipherment

+

| dataEncipherment

+

| keyAgreement

+

| keyCertSign

+

| cRLSign

+

| encipherOnly

+

| decipherOnly

+ + + +

And for id_key_purpose():

+ + + + OID Name + + + id-kp-serverAuth + + + id-kp-clientAuth + + + id-kp-codeSigning + + + id-kp-emailProtection + + + id-kp-timeStamping + + + id-kp-OCSPSigning + + 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()] + }). + +
+ +
+ + Private Internet Extensions + +

The private internet extensions OID name atoms and their corresponding value + types are as follows:

+ + + + OID Name + Value Type + + + id-pe-authorityInfoAccess + [#'AccessDescription'{}] + + + id-pe-subjectInfoAccess + [#'AccessDescription'{}] + + Private Internet Extensions +
+ + +#'AccessDescription'{ + accessMethod, % oid() + accessLocation % general_name() + }). + +
- - +
+ CRL and CRL Extensions Profile + +

Erlang representation of CRL and CRL extensions profile + derived from ASN.1 specifications and RFC 5280 are as follows:

+ + +#'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 + +

The CRL extensions OID name atoms and their corresponding value types are as follows:

+ + + + + 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'{}] + + + CRL Extensions +
+ +

Here, the data type 'IssuingDistributionPoint' is represented as + the following Erlang record:

+ + +#'IssuingDistributionPoint'{ + distributionPoint, % {fullName, [general_name()]} | {nameRelativeToCRLIssuer, + [#AttributeTypeAndValue'{}]} + onlyContainsUserCerts, % boolean() + onlyContainsCACerts, % boolean() + onlySomeReasons, % [dist_reason()] + indirectCRL, % boolean() + onlyContainsAttributeCerts % boolean() + }). +
+ +
+ + CRL Entry Extensions + +

The CRL entry extensions OID name atoms and their corresponding value types are as follows:

+ + + + OID Name + Value Type + + + id-ce-cRLReason + crl_reason() + + + id-ce-holdInstructionCode + oid() + + + id-ce-invalidityDate + general_time() + + + id-ce-certificateIssuer + general_name() + + CRL Entry Extensions +
+ + +

Here:

+ + crl_reason() + =

unspecifiedc>

+

| keyCompromise

+

| cACompromise

+

| affiliationChanged

+

| superseded

+

| cessationOfOperation

+

| certificateHold

+

| removeFromCRL

+

| privilegeWithdrawn

+

| aACompromise

+ + + +
+ +
+ + PKCS#10 Certification Request +

Erlang representation of a PKCS#10 certification request + derived from ASN.1 specifications and RFC 5280 are as follows:

+ +#'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()] +} +
+
+ -- cgit v1.2.3 From d34eab98d034598f2e9ed96c8e3aa992cb633bc8 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Thu, 7 May 2015 13:29:16 +0200 Subject: public_key: Correct application names and typos --- lib/public_key/doc/src/introduction.xml | 10 +++++----- lib/public_key/doc/src/public_key.xml | 12 ++++++------ lib/public_key/doc/src/records.xml | 6 +++--- lib/public_key/doc/src/using_public_key.xml | 25 +++++++++++++------------ 4 files changed, 27 insertions(+), 26 deletions(-) diff --git a/lib/public_key/doc/src/introduction.xml b/lib/public_key/doc/src/introduction.xml index 17f4e5155a..6542c8c509 100644 --- a/lib/public_key/doc/src/introduction.xml +++ b/lib/public_key/doc/src/introduction.xml @@ -5,7 +5,7 @@
2008 - 2013 + 2015 Ericsson AB, All Rights Reserved @@ -36,7 +36,7 @@
Purpose -

The public_key application deals with public-key related file +

The Public Key application deals with public-key related file formats, digital signatures, and X-509 certificates. It is a library application that provides encode/decode, sign/verify, encrypt/decrypt, and similar @@ -54,9 +54,9 @@

Performance Tips -

The public_key decode- and encode-functions try to use the NIFs - in the ASN.1 compilers runtime modules, if they can be found. - Thus, to have the ASN.1 application in the +

The Public Key decode- and encode-functions try to use the NIFs + in the ASN.1 compilers runtime modules, if they can be found. + Thus, to have the ASN1 application in the path of your system gives the best performance.

diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index 3d5c135075..8a81593341 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -43,9 +43,9 @@ public_key - public_key requires the crypto and ASN.1 applications, - the latter as OTP R16 (hopefully the runtime dependency on ASN.1 will - be removed again in the future). + Public Key requires the Crypto and ASN1 applications, + the latter as OTP R16 (hopefully the runtime dependency on ASN1 will + be removed again in the future). Supports RFC 5280 - Internet X.509 Public-Key Infrastructure Certificate and Certificate Revocation List @@ -268,7 +268,7 @@ Decodes a public-key ASN.1 DER encoded entity. Asn1Type = atom() - ASN.1 type present in the public_key applications + ASN.1 type present in the Public Key applications ASN.1 specifications. Der = der_encoded() @@ -282,7 +282,7 @@ Encodes a public-key entity with ASN.1 DER encoding. Asn1Type = atom() - ASN.1 type present in the public_key applications + ASN.1 type present in the Public Key applications ASN.1 specifications. Entity = term() Erlang representation of Asn1Type @@ -626,7 +626,7 @@ fun(OtpCert :: #'OTPCertificate'{},

The fun uses the information in the distribution point to access the latest possible version of the CRL. If this fun is not specified, - public_key uses the default implementation: + Public Key uses the default implementation:

fun(_DP, CRL) -> CRL end diff --git a/lib/public_key/doc/src/records.xml b/lib/public_key/doc/src/records.xml index ac1ecd176c..0090278da8 100644 --- a/lib/public_key/doc/src/records.xml +++ b/lib/public_key/doc/src/records.xml @@ -5,7 +5,7 @@
2008 - 2014 + 2015 Ericsson AB, All Rights Reserved @@ -50,7 +50,7 @@

Common non-standard Erlang data types used to describe the record fields in the - following sections and which are not defined in the public_key Reference Manual follows here:

@@ -772,7 +772,7 @@ are as follows:

Here:

crl_reason() - =

unspecifiedc>

+ =

unspecified

| keyCompromise

| cACompromise

| affiliationChanged

diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml index 69b8c0dcb9..aaf802cd34 100644 --- a/lib/public_key/doc/src/using_public_key.xml +++ b/lib/public_key/doc/src/using_public_key.xml @@ -30,8 +30,8 @@

This section describes examples of how to use the - public_key API. Keys and certificates used in the following - sections are generated only for testing the public_key + Public Key API. Keys and certificates used in the following + sections are generated only for testing the Public Key application.

Some shell printouts in the following examples @@ -43,14 +43,15 @@

Public-key data (keys, certificates, and so on) can be stored in Privacy Enhanced Mail (PEM) format. The PEM files have the following structure:

- - <text> - -----BEGIN <SOMETHING>----- - <Attribute> : <Value> - <Base64 encoded DER data> - -----END <SOMETHING>----- - <text> - + + + <text> + -----BEGIN <SOMETHING>----- + <Attribute> : <Value> + <Base64 encoded DER data> + -----END <SOMETHING>----- + <text> +

A file can contain several BEGIN/END blocks. Text lines between blocks are ignored. Attributes, if present, are ignored except for Proc-Type and DEK-Info, which are used when DER @@ -59,7 +60,7 @@

DSA Private Key

A DSA private key can look as follows:

-

File handling is not done by the public_key application.

 +

File handling is not done by the Public Key application.

 1> {ok, PemBin} = file:read_file("dsa.pem"). {ok,<<"-----BEGIN DSA PRIVATE KEY-----\nMIIBuw"...>>} @@ -364,7 +365,7 @@ ok
RSA Public-Key Cryptography -

Suppose you have the followwing private key and a corresponding public key:

+

Suppose you have the following private key and a corresponding public key:

PrivateKey = #'RSAPrivateKey{}' and the plaintext Msg = binary() -- cgit v1.2.3 From 9a6b0809ceae80bfb542ee8bab2e8fcd12087467 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Thu, 7 May 2015 13:37:16 +0200 Subject: public_key: Align to alphabetical order --- lib/public_key/doc/src/public_key.xml | 54 +++++++++++++++++------------------ 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index 8a81593341..6d220c9b69 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -292,6 +292,33 @@ + + encrypt_private(PlainText, Key) -> binary() + Public-key encryption using the private key. + + PlainText = binary() + Key = rsa_private_key() + + +

Public-key encryption using the private key. + See also crypto:private_encrypt/4.

+ + + + + encrypt_public(PlainText, Key) -> binary() + Public-key encryption using the public key. + + PlainText = binary() + Key = rsa_public_key() + + +

Public-key encryption using the public key. See also crypto:public_encrypt/4.

+ + + generate_key(Params) -> {Public::binary(), Private::binary()} | #'ECPrivateKey'{} Generates a new keypair. @@ -364,33 +391,6 @@

Creates a PEM entry that can be feed to pem_encode/1.

 - - - encrypt_private(PlainText, Key) -> binary() - Public-key encryption using the private key. - - PlainText = binary() - Key = rsa_private_key() - - -

Public-key encryption using the private key. - See also crypto:private_encrypt/4.

- - - - - encrypt_public(PlainText, Key) -> binary() - Public-key encryption using the public key. - - PlainText = binary() - Key = rsa_public_key() - - -

Public-key encryption using the public key. See also crypto:public_encrypt/4.

- - pkix_decode_cert(Cert, otp|plain) -> #'Certificate'{} | #'OTPCertificate'{} -- cgit v1.2.3 From fafd888770d16d2a3962210c04a0b341311a13c8 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Thu, 7 May 2015 13:59:44 +0200 Subject: public_key: Align types with removal of legacy ASN.1 flags --- lib/public_key/doc/src/records.xml | 20 ++++++++++---------- lib/public_key/doc/src/using_public_key.xml | 8 +++----- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/lib/public_key/doc/src/records.xml b/lib/public_key/doc/src/records.xml index 0090278da8..e9e9b231af 100644 --- a/lib/public_key/doc/src/records.xml +++ b/lib/public_key/doc/src/records.xml @@ -160,7 +160,7 @@ #'ECPrivateKey'{ version, % integer() - privateKey, % octet_string() + privateKey, % binary() parameters, % der_encoded() - {'EcpkParameters', #'ECParameters'{}} | {'EcpkParameters', {namedCurve, oid()}} | {'EcpkParameters', 'NULL'} % Inherited by CA @@ -171,14 +171,14 @@ version, % integer() fieldID, % #'FieldID'{} curve, % #'Curve'{} - base, % octet_string() + base, % binary() order, % integer() cofactor % integer() }. #'Curve'{ - a, % octet_string() - b, % octet_string() + a, % binary() + b, % binary() seed % bitstring() - optional }. @@ -189,7 +189,7 @@ }. #'ECPoint'{ - point % octet_string() - the public key + point % binary() - the public key }.
@@ -201,7 +201,7 @@ #'Certificate'{ tbsCertificate, % #'TBSCertificate'{} signatureAlgorithm, % #'AlgorithmIdentifier'{} - signature % {0, binary()} - ASN1 compact bitstring + signature % bitstring() }. #'TBSCertificate'{ @@ -226,7 +226,7 @@ #'OTPCertificate'{ tbsCertificate, % #'OTPTBSCertificate'{} signatureAlgorithm, % #'SignatureAlgorithm' - signature % {0, binary()} - ASN1 compact bitstring + signature % bitstring() }. #'OTPTBSCertificate'{ @@ -664,7 +664,7 @@ are as follows:

#'CertificateList'{ tbsCertList, % #'TBSCertList{} signatureAlgorithm, % #'AlgorithmIdentifier'{} - signature % {0, binary()} - ASN1 compact bitstring + signature % bitstring() }). #'TBSCertList'{ @@ -796,7 +796,7 @@ are as follows:

#'CertificationRequest'{ certificationRequestInfo #'CertificationRequestInfo'{}, signatureAlgorithm #'CertificationRequest_signatureAlgorithm'{}}. - signature {0, binary()} - ASN1 compact bitstring + signature bitstring() } #'CertificationRequestInfo'{ @@ -808,7 +808,7 @@ are as follows:

#'CertificationRequestInfo_subjectPKInfo'{ algorithm #'CertificationRequestInfo_subjectPKInfo_algorithm'{} - subjectPublicKey {0, binary()} - ASN1 compact bitstring + subjectPublicKey bitstring() } #'CertificationRequestInfo_subjectPKInfo_algorithm'{ diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml index aaf802cd34..41a81b6dea 100644 --- a/lib/public_key/doc/src/using_public_key.xml +++ b/lib/public_key/doc/src/using_public_key.xml @@ -212,9 +212,8 @@ algorithm = {1,2,840,113549,1,1,5}, parameters = <<5,0>>}, signature = - {0, - <<163,186,7,163,216,152,63,47,154,234,139,73,154,96,120, - 165,2,52,196,195,109,167,192,...>>}} + <<163,186,7,163,216,152,63,47,154,234,139,73,154,96,120, + 165,2,52,196,195,109,167,192,...>>}

Parts of certificates can be decoded with public_key:der_decode/2, using the ASN.1 type of that part. @@ -317,9 +316,8 @@ algorithm = {1,2,840,113549,1,1,5}, parameters = 'NULL'}, signature = - {0, <<163,186,7,163,216,152,63,47,154,234,139,73,154,96,120, - 165,2,52,196,195,109,167,192,...>>}} + 165,2,52,196,195,109,167,192,...>>}

This call is equivalent to public_key:pem_entry_decode(CertEntry1):

5> public_key:pkix_decode_cert(DerCert, plain). -- cgit v1.2.3 From 631489eb5f989f06de993004ae6db58f07465ccb Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Thu, 7 May 2015 14:09:35 +0200 Subject: public_key: Add clarifications --- lib/public_key/doc/src/records.xml | 17 ++++++++++++++--- lib/public_key/doc/src/using_public_key.xml | 4 +++- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/lib/public_key/doc/src/records.xml b/lib/public_key/doc/src/records.xml index e9e9b231af..9536167839 100644 --- a/lib/public_key/doc/src/records.xml +++ b/lib/public_key/doc/src/records.xml @@ -96,6 +96,15 @@

| privilegeWithdrawn

| aACompromise

+ + OID_macro() + =

?OID_name()

+ + + OID_name() + =

atom()

+ +
@@ -196,7 +205,7 @@
PKIX Certificates

Erlang representation of PKIX certificates derived from ASN.1 - specifications see also X509 certificates (RFC 5280) are as follows:

+ specifications see also X509 certificates (RFC 5280), also referred to as plain type, are as follows:

#'Certificate'{ tbsCertificate, % #'TBSCertificate'{} @@ -222,6 +231,8 @@ parameters % der_encoded() }. +

Erlang alternate representation of PKIX certificate, also referred to as otp type

+ #'OTPCertificate'{ tbsCertificate, % #'OTPTBSCertificate'{} @@ -247,8 +258,8 @@ parameters % asn1_novalue | #'Dss-Parms'{} }. -

Here, id_signature_algorithm() = ?OID name, for available OID names, for example -?id-dsa-with-sha1. That is, by prepending "?" to the OID name, represented as an Erlang atom.

+

id_signature_algorithm() = OID_macro()

+

The available OID names are as follows:

diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml index 41a81b6dea..03e4bedf3d 100644 --- a/lib/public_key/doc/src/using_public_key.xml +++ b/lib/public_key/doc/src/using_public_key.xml @@ -381,7 +381,9 @@ Msg = public_key:decrypt_public(RsaEncrypted, PublicKey), Msg = public_key:decrypt_private(RsaEncrypted, PrivateKey),

You normally do only one of the encrypt or decrypt operations, - and the peer does the other.

 + and the peer does the other. This normaly used in legacy applications + as a primitive digital signature. +

-- cgit v1.2.3