From 0cdaea5199c49c1511700db3b4b0ff59f4c7396d Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 3 Sep 2018 15:15:47 +0200 Subject: public_key: Generate refman from types and specs --- lib/public_key/doc/src/public_key.xml | 684 ++++++++++++---------------------- 1 file changed, 240 insertions(+), 444 deletions(-) diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index c0a67c25b8..a4d7e4a734 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -41,7 +41,7 @@
- DATA TYPES + Common Records and ASN.1 Types

All records used in this Reference Manual @@ -54,193 +54,132 @@ records and constant macros described here and in the User's Guide:

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

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

+ + + + + + + + + + + + + + + + + + +

ASN.1 type present in the Public Key applications ASN.1 specifications.

+ + + + + + + + + + + + Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC" +

Salt could be generated with + crypto:strong_rand_bytes(8).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -

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

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

-

| 'CertificateList'

-

| '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:strong_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'{}, #'ECParameters'{} | {namedCurve, oid()}}

 - - ec_private_key() = -

#'ECPrivateKey'{}

 - - key_params() = -

#'DHParameter'{} | {namedCurve, oid()} | #'ECParameters'{} - | {rsa, Size::integer(), PubExp::integer()}

- - public_crypt_options() = -

[{rsa_pad, rsa_padding()}]

 - - rsa_padding() = - -

'rsa_pkcs1_padding'

-

| 'rsa_pkcs1_oaep_padding'

-

| 'rsa_no_padding'

- - - public_sign_options() = -

[{rsa_pad, rsa_sign_padding()} | {rsa_pss_saltlen, integer()}]

 - - rsa_sign_padding() = - -

'rsa_pkcs1_padding'

-

| 'rsa_pkcs1_pss_padding'

- - - digest_type() = -

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

 - - rsa_digest_type() = -

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

 - - dss_digest_type() = -

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

-

Note that the actual supported dss_digest_type depends on the underlying crypto library. - In OpenSSL version >= 1.0.1 the listed digest are supported, while in 1.0.0 only - sha, sha224 and sha256 are supported. In version 0.9.8 only sha is supported.

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - compute_key(OthersKey, MyKey)-> - compute_key(OthersKey, MyKey, Params)-> + + Computes shared secret. + +

Computes shared secret.

+ + + + + Computes shared secret. - - OthersKey = #'ECPoint'{} | binary(), MyKey = #'ECPrivateKey'{} | binary() - Params = #'DHParameter'{} -

Computes shared secret.

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

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

@@ -248,14 +187,9 @@ - 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 crypto:public_decrypt/4

@@ -263,47 +197,24 @@ - der_decode(Asn1type, Der) -> term() + Decodes a public-key ASN.1 DER encoded entity. - - Asn1Type = atom() - ASN.1 type present in the Public Key applications - ASN.1 specifications. - Der = der_encoded() - - +

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

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

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

 - dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) -> {ok, {Size,Group}} | {error,Error} + Selects a group for Diffie-Hellman key exchange - - MinSize = positive_integer() - SuggestedSize = positive_integer() - MaxSize = positive_integer() - Groups = undefined | [{Size,[{G,P}]}] - Size = positive_integer() - Group = {G,P} - G = positive_integer() - P = positive_integer() -

Selects a group for Diffie-Hellman key exchange with the key size in the range MinSize...MaxSize and as close to SuggestedSize as possible. If Groups == undefined a default set will be @@ -322,13 +233,10 @@ - - 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 - 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.

@@ -350,11 +255,8 @@ - generate_key(Params) -> {Public::binary(), Private::binary()} | #'ECPrivateKey'{} | #'RSAPrivateKey'{} + Generates a new keypair. - - Params = key_params() -

Generates a new keypair. Note that except for Diffie-Hellman the public key is included in the private key structure. See also @@ -364,38 +266,27 @@ - pem_decode(PemBin) -> [pem_entry()] + Decodes PEM binary data and returns entries as ASN.1 DER encoded entities. - - PemBin = binary() - Example {ok, PemBin} = file:read_file("cert.pem"). - -

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

+

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

+

Example {ok, PemBin} = file:read_file("cert.pem").

 - - pem_encode(PemEntries) -> 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. - - PemEntry = pem_entry() - Password = string() -

Decodes a PEM entry. pem_decode/1 returns a list of PEM entries. Notice that if the PEM entry is of type @@ -404,51 +295,36 @@ - - 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. - - Asn1Type = pki_asn1_type() - Entity = term() - Erlang representation of - Asn1Type. If Asn1Type is 'SubjectPublicKeyInfo', + +

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

+

If Asn1Type is 'SubjectPublicKeyInfo', Entity must be either an rsa_public_key(), dsa_public_key() or an ec_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.

- + 'SubjectPublicKeyInfo' entry. +

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

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.

- + +

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.

+ - pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded() + DER encodes a PKIX x509 certificate or part of such a certificate. - - Asn1Type = atom() - 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 @@ -458,69 +334,47 @@ - pkix_is_issuer(Cert, IssuerCert) -> boolean() - Checks if IssuerCert issued Cert. - - Cert = der_encoded() | #'OTPCertificate'{} | #'CertificateList'{} - IssuerCert = der_encoded() | #'OTPCertificate'{} - - -

Checks if IssuerCert issued Cert.

- - + + 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 certificate. - - Cert = der_encoded() | #'OTPCertificate'{} - - -

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

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

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

+ + - - pkix_is_self_signed(Cert) -> boolean() - 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. + +

Checks if a certificate is self-signed.

+ + - - pkix_issuer_id(Cert, IssuedBy) -> {ok, IssuerID} | {error, Reason} - Returns the issuer id. - - Cert = der_encoded() | #'OTPCertificate'{} - IssuedBy = self | other - IssuerID = {integer(), issuer_name()} - The issuer id consists of the serial number and the issuers name. - Reason = term() - - -

Returns the issuer id.

- - - + + + Returns the issuer id. + +

Returns the issuer id.

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

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

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. @@ -622,26 +476,16 @@ fun(OtpCert :: #'OTPCertificate'{}, - pkix_crl_issuer(CRL) -> issuer_name() + Returns the issuer of the CRL. - - CRL = der_encoded() | #'CertificateList'{} -

Returns the issuer of the CRL.

 - pkix_crls_validate(OTPCertificate, DPAndCRLs, Options) -> CRLStatus() + Performs CRL validation. - - OTPCertificate = #'OTPCertificate'{} - DPAndCRLs = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] - Options = proplists:proplist() - CRLStatus() = valid | {bad_cert, revocation_status_undetermined} | {bad_cert, {revocation_status_undetermined, - {bad_crls, Details::term()}}} | {bad_cert, {revoked, crl_reason()}} -

Performs CRL validation. It is intended to be called from the verify fun of pkix_path_validation/3 @@ -692,24 +536,16 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, - pkix_crl_verify(CRL, Cert) -> boolean() + Verify that Cert is the CRL signer. - - CRL = der_encoded() | #'CertificateList'{} - Cert = der_encoded() | #'OTPCertificate'{} -

Verify that Cert is the CRL signer.

 - pkix_dist_point(Cert) -> DistPoint + Creates a distribution point for CRLs issued by the same issuer as Cert. - - Cert = der_encoded() | #'OTPCertificate'{} - DistPoint = #'DistributionPoint'{} -

Creates a distribution point for CRLs issued by the same issuer as Cert. Can be used as input to - pkix_dist_points(Cert) -> DistPoints + Extracts distribution points from the certificates extensions. - - Cert = der_encoded() | #'OTPCertificate'{} - DistPoints = [#'DistributionPoint'{}] -

Extracts distribution points from the certificates extensions.

 - pkix_match_dist_point(CRL, DistPoint) -> boolean() + Checks whether the given distribution point matches the Issuing Distribution Point of the CRL. - - - CRL = der_encoded() | #'CertificateList'{} - DistPoint = #'DistributionPoint'{} -

Checks whether the given distribution point matches the Issuing Distribution Point of the CRL, as described in RFC 5280. @@ -748,11 +575,8 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, - pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encoded() + Signs certificate. - - Key = rsa_private_key() | dsa_private_key() -

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

@@ -760,17 +584,12 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, - pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType} + 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() - SignatureType = rsa | dsa | ecdsa -

Translates signature algorithm OID to Erlang digest and signature types.

+

The AlgorithmId is the signature OID from a certificate or a certificate revocation list.

 @@ -938,12 +757,8 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, - pkix_verify(Cert, Key) -> boolean() + Verifies PKIX x.509 certificate signature. - - Cert = der_encoded() - Key = rsa_public_key() | dsa_public_key() | ec_public_key() -

Verifies PKIX x.509 certificate signature.

 @@ -1059,41 +874,30 @@ end - sign(Msg, DigestType, Key) -> binary() - sign(Msg, DigestType, Key, Options) -> binary() + + 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", that is, the - digest. - DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type() - Key = rsa_private_key() | dsa_private_key() | ec_private_key() - Options = public_sign_options() -

Creates a digital signature.

+

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.

 - ssh_decode(SshBin, Type) -> [{public_key(), Attributes::list()}] + 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 can be either - an RFC4716 public key or an OpenSSH public key. - - -

Decodes an SSH file-binary. In the case of known_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. -

- + +

Decodes an SSH file-binary. In the case of known_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. +

+

If the Type is ssh2_pubkey, the result will be + Decoded_ssh2_pubkey. Otherwise it will be Decoded_OtherType. +

RFC4716 attributes - see RFC 4716.

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

 @@ -1106,23 +910,25 @@ end {comment, string()}

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

 - +

Example: {ok, SshBin} = file:read_file("known_hosts"). +

+

If Type is public_key the binary can be either + an RFC4716 public key or an OpenSSH public key.

 - ssh_encode([{Key, Attributes}], Type) -> 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 depend 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 . +

+

If the Type is ssh2_pubkey, the InData shall be + InData_ssh2_pubkey. Otherwise it shall be OtherInData. +

+ @@ -1131,8 +937,8 @@ end ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()] Calculates a ssh fingerprint for a hostkey. - Key = public_key() - DigestType = digest_type() + HostKey = public_key() + DigestType = digest_type()

Calculates a ssh fingerprint from a public host key as openssh does.

@@ -1161,29 +967,19 @@ end - verify(Msg, DigestType, Signature, Key) -> boolean() - verify(Msg, DigestType, Signature, Key, Options) -> boolean() + + 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", 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() - Options = public_sign_options() -

Verifies a digital signature.

+

The Msg is either the binary "plain text" data + or it is the hashed value of "plain text", that is, the digest.

 - short_name_hash(Name) -> string() + Generates a short hash of an issuer name. - - Name = issuer_name() -

Generates a short hash of an issuer name. The hash is returned as a string containing eight hexadecimal digits.

-- cgit v1.2.3