public_key

PUBLIC_KEY

模块

PUBLIC_KEY

模块摘要

公共密钥基础设施的API模块。

描述

提供处理公钥基础设施的功能，详情请参阅public_key(6)。

数据类型

注

本参考手册中使用的所有记录均根据ASN.1规范生成，并记录在用户指南中。看Public-key Records。

使用以下include指令可以访问这里和用户指南中描述的记录和常量宏：

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

以下数据类型用于以下功能public_key：

oid()

对象标识符(由ASN.1编译器。

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

联合rsa_digest_type()，，，dss_digest_type()，和ecdsa_digest_type()...

rsa_digest_type() =

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

dss_digest_type() =

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

请注意，实际支持的dss_digest_type取决于底层的加密库。在OpenSSL版本> = 1.0.1中，支持列出的摘要，而在1.0.0中仅支持sha，sha224和sha256。在版本0.9.8中，只有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

输出

compute_key(OthersKey, MyKey)->compute_key(OthersKey, MyKey, Params)->

类型

计算共享密钥。

decrypt_private(CipherText, Key) -> binary()decrypt_private(CipherText, Key, Options) -> binary()

类型

使用私钥进行公钥解密。另见crypto:private_decrypt/4

decrypt_public(CipherText, Key) - > binary()decrypt_public(CipherText, Key, Options) - > binary()

类型

使用公钥解密。另见crypto:public_decrypt/4

der_decode(Asn1type, Der) -> term()

类型

ASN.1公开密钥应用程序中的ASN.1类型。

解码公开密钥ASN.1 der编码的实体。

der_encode(Asn1Type, Entity) -> der_encoded()

类型

ASN.1公开密钥应用程序中的ASN.1类型。

Erlang表示Asn1Type

用ASN.1 der编码对公钥实体进行编码。

dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) -> {ok, {Size,Group}} | {error,Error}

类型

选择Diffie-Hellman密钥交换组，密钥大小范围为MinSize ... MaxSize，尽可能接近SuggestedSize。 如果组==未定义，将使用默认集合，否则从组中选择组。

首先选择一个尽可能接近SuggestedSize的尺寸。 然后从指定的一组组中随机选择一个具有该密钥大小的组。 如果MinSize和MaxSize范围内没有大小可用，则返回{error，no_group_found}。

默认组集列在lib/public_key/priv/moduli.此文件可按以下方式重新生成：

$> cd $ERL_TOP/lib/public_key/priv/
$> generate
         ---- wait until all background jobs has finished. It may take several days !
$> cat moduli-* > moduli
$> cd ..; make 
      

encrypt_private(PlainText, Key) -> binary()

类型

使用私钥进行公钥加密。另见crypto:private_encrypt/4...

encrypt_public(PlainText, Key) -> binary()

类型

使用公钥进行公钥加密。另见crypto:public_encrypt/4...

generate_key(Params) -> {Public::binary(), Private::binary()} | #'ECPrivateKey'{} | #'RSAPrivateKey'{}

类型

生成一个新的键盘。注意，除了Diffie-Hellman之外，私钥结构中还包括公钥。另见crypto:generate_key/2

pem_decode(PemBin) -> [pem_entry()]

类型

示例{ok，PemBin} = file：read_file（“cert.pem”）。

解码PEM二进制数据并将条目作为ASN.1 der编码实体返回。

pem_encode(PemEntries) -> binary()

类型

创建一个PEM二进制文件。

pem_entry_decode(PemEntry) -> term()pem_entry_decode(PemEntry, Password) -> term()

类型

解码PEM条目。pem_decode/1返回一个PEM条目列表。请注意，如果PEM条目的类型为“SubjectPublickeyInfo”，则会进一步解码为rsa_public_key()or dsa_public_key()。

pem_entry_encode(Asn1Type, Entity) -> pem_entry()pem_entry_encode(Asn1Type, Entity, {CipherInfo, Password}) -> pem_entry()

类型

Erlang表示Asn1Type。如果Asn1Type是“SubjectPublicKeyInfo进行”，Entity必须是一个rsa_public_key()，dsa_public_key()或ec_public_key()与此函数创建相应的“SubjectPublicKeyInfo进行”条目。

创建一个PEM条目，该条目可以被馈送到pem_encode/1...

pkix_decode_cert(Cert, otp|plain) -> #'Certificate'{} | #'OTPCertificate'{}

类型

解码ASN.1 DER编码的PKIX证书。Option otp使用定制的ASN.1规范OTP-PKIX.asn1进行解码，并对大多数标准部件进行递归解码。

pkix_encode(Asn1Type, Entity, otp | plain) -> der_encoded()

类型

ASN.1类型可以是“证书”，“OTPCertificate”或任何一个的子类型。

DER编码一个PKIX x509证书或这种证书的一部分。此功能必须用于编码证书或部分以该otp格式解码/创建的证书，而对于纯文本格式，则直接调用此函数der_encode/2。

pkix_is_issuer(Cert, IssuerCert) -> boolean()

类型

检查是否IssuerCert发布Cert。

pkix_is_fixed_dh_cert(Cert) -> boolean()

类型

检查证书是否是固定的Diffie-Hellman证书。

pkix_is_self_signed(Cert) -> boolean()

类型

检查证书是否自签名。

pkix_issuer_id(Cert, IssuedBy) -> {ok, IssuerID} | {error, Reason}

类型

发行人ID由序列号和发行者名称组成。

返回发行人ID。

pkix_normalize_name(Issuer) -> Normalized

类型

规范发行者名称，以便将其与另一个发行者名称相比较。

pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicKeyInfo, PolicyTree}} | {error, {bad_cert, Reason}}

类型

通常是一个受信任的证书，但它也可以是一个路径验证错误，可以在构造此函数的输入时发现该错误，并且要通过verify_fun.例如：unknown_ca和selfsigned_peer.

以信任顺序以对等证书结尾的编码证书列表.

目前，这始终是一个空列表，因为当前不支持策略。

根据以下内容执行基本路径验证RFC 5280.然而，CRL验证是由提供的单独完成的，并且pkix_crls_validate/3将从提供的内容中调用verify_fun。

可供选择的办法：

{verify_fun，fun（）}

函数必须被定义为：

fun(OtpCert :: #'OTPCertificate'{},
    Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
             {extension, #'Extension'{}},
    InitialUserState :: term()) ->
	{valid, UserState :: term()} |
	{valid_peer, UserState :: term()} |
	{fail, Reason :: term()} |
	{unknown, UserState :: term()}.
	  

如果验证回调乐趣返回{fail, Reason}，验证过程立即停止。如果验证回调函数返回{valid, UserState}，核查进程将继续进行。这可用于接受特定的路径验证错误，如selfsigned_peer，以及验证特定于应用程序的扩展。如果使用用户应用程序未知的扩展名调用，则返回值{unknown, UserState}就是被利用。

{max_path_length，integer（）} 这max_path_length是可以在有效证书路径中跟随对等证书的非自发中间证书的最大数量。因此，如果max_path_length是0，PEER必须由可信ROOT-CA直接签名，如果它是1，路径可以是PEER，CA，ROOT-CA，如果它是2，路径可以是PEER，CA，CA ，ROOT-CA等等。

可能出现错误证书的原因：

cert_expired

证书已过期，因此不再有效。

invalid_issuer

证书颁发者名称与链中颁发者证书的名称不匹配。

invalid_signature

证书没有由链中的颁发者证书签名。

name_not_permitted

无效的主题替代名称扩展。

missing_basic_constraint

证书需要有基本约束扩展，但没有基本约束扩展。

invalid_key_usage

证书密钥根据密钥使用扩展以无效的方式使用.

{revoked，crl_reason（）}

证书已被撤销。

atom()

特定于应用程序的错误原因将由verify_fun检查。

pkix_crl_issuer(CRL) -> issuer_name()

类型

返回的发行者CRL。

pkix_crls_validate(OTPCertificate, DPAndCRLs, Options) -> CRLStatus()

类型

执行CRL验证。它的目的是从验证的函数中调用pkix_path_validation/3。

可供选择的办法：

{update_crl，fun（）}

函数有以下类型规格：

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

函数使用分发点中的信息访问最新版本的CRL。如果未指定此乐趣，则公钥使用默认实现：

fun(_DP, CRL) -> CRL end

{issuer_fun，fun（）}

函数有以下类型规范：

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

该程序返回已签署CRL的根证书和证书链。

fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}

{undetermined_details，boolean（）}

默认为false。当无法确定撤销状态并且此选项设置为true时，返回值中包含为什么不接受CRL的原因的详细信息。

pkix_crl_verify(CRL, Cert) -> boolean()

类型

核实Cert是CRL签字人。

pkix_dist_point(Cert) -> DistPoint

类型

为CRLS创建一个分发点，该分发点由与Cert可以用作pkix_crls_validate/3

pkix_dist_points(Cert) -> DistPoints

类型

从证书扩展中提取分发点。

pkix_match_dist_point(CRL, DistPoint) -> boolean()

类型

检查给定分发点是否与CRL的颁发分发点相匹配，如RFC 5280中所述。如果CRL没有颁发分发点扩展，则分发点始终匹配。

pkix_sign(#'OTPTBSCertificate'{}, Key) -> der_encoded()

类型

签署'OTPTBSCertificate'。返回相应的DER编码证书。

pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}

类型

签名证书或证书撤销列表中的OID。

将签名算法OID转换为Erlang摘要和签名类型。

pkix_test_data(Options) -> Config

类型

ROOT，Intermediate和Peer证书的选项

有效的链必须至少有根和对等证书。

有关可用选项，请参阅下面的cert_opt（）。 这是ssl类型的一个子集：ssl_option（）

创建证书测试数据，以便于使用X 509对应用程序进行自动化测试--证书通常通过SSL/TLS进行。当您在测试场景中控制客户端和服务器时，可以使用测试数据。

cert_opt（）类型由以下选项组成：

{digest, digest_type()}

与密钥选项一起用于签署证书的哈希算法。默认为sha，即sha1。

{key, key_params() | private_key()}

要用于调用public_key的参数：generate_key / 1，以生成密钥或现有密钥。默认为生成ECDSA密钥。注意，如果Erlang / OTP使用非常古老的cryptolib编译，这可能会失败。

{validity, {From::erlang:timestamp(), To::erlang:timestamp()}}

证书的有效期。

{extensions, #'Extension'{}}

扩展将包括在证书中。

如果未另行指定，CA证书中包含的默认扩展名是：

[#'Extension'{extnID = ?'id-ce-keyUsage',
              extnValue = [keyCertSign, cRLSign],
              critical = false},
#'Extension'{extnID = ?'id-ce-basicConstraints',
             extnValue = #'BasicConstraints'{cA = true},
             critical = true}]
	  

服务器对等证书中包含的默认扩展(如果没有另外指定)如下：

[#'Extension'{extnID = ?'id-ce-keyUsage',
              extnValue = [digitalSignature, keyAgreement],
              critical = false},
#'Extension'{extnID = ?'id-ce-subjectAltName',
             extnValue = [{dNSName, Hostname}],
             critical = false}]
	  

主机名称是调用该函数的Erlang节点中调用net_adm：localhost（）的结果。

注

请注意，生成的证书和密钥没有提供形式上正确的PKIX信任链，它们不能用于实现真正的安全性。此功能仅用于测试目的。

pkix_verify(Cert, Key) -> boolean()

类型

验证PKIX X.509证书签名。

pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()pkix_verify_hostname(Cert, ReferenceIDs, Opts) -> boolean()

类型

该功能检查对等证书中显示的标识符（例如主机名）是否符合客户端希望连接的预期标识符。此功能旨在在执行时作为额外的客户端检查添加到对等证书public_key:pkix_path_validation/3

请参阅RFC 6125有关主机名验证的详细信息。在User's Manual和code examples描述了此功能的更详细。

sign(Msg, DigestType, Key) -> binary()sign(Msg, DigestType, Key, Options) -> binary()

类型

Msg或者是二进制的“明文”的数据进行签名，或者它是“纯文本”的散列值，即，该摘要。

创建一个数字签名。

ssh_decode(SshBin, Type) -> [{public_key(), Attributes::list()}]

类型

例子{ok, SshBin} = file:read_file("known_hosts")。如果Type是public_key二进制可以是RFC4716的公共密钥或OpenSSH的公钥。

解码SSH文件二进制文件。在known_hostsor 的情况下auth_keys，二进制文件可以包含一行或多行文件。返回公钥和它们的属性列表，可能的属性值取决于二进制表示的文件类型。

RFC4716 attributes - see RFC 4716.

{headers，{string（），utf8_string（）}}

auth_key属性 - 请参阅sshd的手册页。{comment，string（）} {options，string（）}

{bits，integer（）} - 在SSH版本1文件中。

known_host属性 - 请参阅sshd的手册页。{主机名，字符串（）} {评论，字符串（）}

{bits，integer（）} - 在SSH版本1文件中。

ssh_encode([{Key, Attributes}], Type) -> binary()

类型

将SSH文件条目（公钥和属性）的列表编码为二进制文件。可能的属性取决于文件类型，请参阅ssh_decode/2。

ssh_hostkey_fingerprint(HostKey) -> string()ssh_hostkey_fingerprint(DigestType, HostKey) -> string()ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]

类型

像openssh那样从公共主机键计算ssh指纹。

ssh_hostkey_fingerprint/1md5中的算法与旧的ssh-keygen命令兼容。来自第二个变体的字符串在算法名称前面加上大写字母，就像在较新的ssh-keygen命令中一样。

例子：

2> public_key:ssh_hostkey_fingerprint(Key).    
"f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"

3> public_key:ssh_hostkey_fingerprint(md5,Key).
"MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"

4> public_key:ssh_hostkey_fingerprint(sha,Key).
"SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"

5> public_key:ssh_hostkey_fingerprint(sha256,Key).
"SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"

6> public_key:ssh_hostkey_fingerprint([sha,sha256],Key).
["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
   

verify(Msg, DigestType, Signature, Key) -> boolean()verify(Msg, DigestType, Signature, Key, Options) -> boolean()

类型

Msg可以是二进制“纯文本”数据，也可以是“纯文本”的散列值，即摘要。

验证数字签名。

short_name_hash(Name) -> string()

类型

生成签发者名称的短散列。哈希作为包含八个十六进制数字的字符串返回。

当分别传递CRL或证书的颁发者名称时，此函数的返回值与命令openssl crl -hash和openssl x509 -issuer_hash的结果相同。 该散列由c_rehash工具用来维护一个到CRL文件的符号链接目录，以便于通过发行者名称查找CRL。