1public_key(3) Erlang Module Definition public_key(3)
2
6 public_key - API module for public-key infrastructure.
7
9 Provides functions to handle public-key infrastructure, for details see
10 public_key(6).
11
13 Note:
14 All records used in this Reference Manual are generated from ASN.1
15 specifications and are documented in the User's Guide. See Public-key
16 Records.
17 Use the following include directive to get access to the records and
20 constant macros described here and in the User's Guide:
21 -include_lib("public_key/include/public_key.hrl").
23
25 oid() = tuple()
26 Object identifier, a tuple of integers as generated by the ASN.1
28 compiler.
29 der_encoded() = binary()
31 pki_asn1_type() =
33 'Certificate' | 'RSAPrivateKey' | 'RSAPublicKey' |
34 'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' |
35 'SubjectPublicKeyInfo' | 'PrivateKeyInfo' |
36 'CertificationRequest' | 'CertificateList' | 'ECPrivateKey' |
37 'EcpkParameters'
38 asn1_type() = atom()
40 ASN.1 type present in the Public Key applications ASN.1 specifi‐
42 cations.
43 pem_entry() =
45 {pki_asn1_type(),
46 der_or_encrypted_der(),
47 not_encrypted | cipher_info()}
48 der_or_encrypted_der() = binary()
50 cipher_info() = {cipher(), cipher_info_params()}
52 cipher() = string()
54 salt() = binary()
56 cipher_info_params() =
58 salt() |
59 {#'PBEParameter'{}, digest_type()} |
60 #'PBES2-params'{}
61 Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC"
63 Salt could be generated with crypto:strong_rand_bytes(8).
65 public_key() =
67 rsa_public_key() |
68 dsa_public_key() |
69 ec_public_key() |
70 ed_public_key()
71 rsa_public_key() = #'RSAPublicKey'{}
73 dsa_public_key() = {integer(), #'Dss-Parms'{}}
75 ec_public_key() = {#'ECPoint'{}, ecpk_parameters_api()}
77 ecpk_parameters() =
79 {ecParameters, #'ECParameters'{}} |
80 {namedCurve, Oid :: tuple()}
81 ecpk_parameters_api() =
83 ecpk_parameters() |
84 #'ECParameters'{} |
85 {namedCurve, Name :: crypto:ec_named_curve()}
86 ed_public_key() = {ed_pub, ed25519 | ed448, Key :: binary()}
88 Warning:
90 This format of the EdDSA curves is temporary and may change
91 without prior notice!
92 private_key() =
95 rsa_private_key() |
96 dsa_private_key() |
97 ec_private_key() |
98 ed_private_key()
99 rsa_private_key() = #'RSAPrivateKey'{}
101 dsa_private_key() = #'DSAPrivateKey'{}
103 ec_private_key() = #'ECPrivateKey'{}
105 ed_private_key() =
107 {ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()}
108 Warning:
110 This format of the EdDSA curves is temporary and may change
111 without prior notice!
112 key_params() =
115 #'DHParameter'{} |
116 {namedCurve, oid()} |
117 #'ECParameters'{} |
118 {rsa, Size :: integer(), PubExp :: integer()}
119 digest_type() =
121 none | sha1 |
122 crypto:rsa_digest_type() |
123 crypto:dss_digest_type() |
124 crypto:ecdsa_digest_type()
125 crl_reason() =
127 unspecified | keyCompromise | cACompromise |
128 affiliationChanged | superseded | cessationOfOperation |
129 certificateHold | privilegeWithdrawn | aACompromise
130 issuer_id() = {SerialNr :: integer(), issuer_name()}
132 issuer_name() = {rdnSequence, [#'AttributeTypeAndValue'{}]}
134 ssh_file() =
136 openssh_public_key | rfc4716_public_key | known_hosts |
137 auth_keys
138
140 compute_key(OthersECDHkey, MyECDHkey) -> SharedSecret
141 Types:
143 OthersECDHkey = #'ECPoint'{}
145 MyECDHkey = #'ECPrivateKey'{}
146 SharedSecret = binary()
147 Computes shared secret.
149 compute_key(OthersDHkey, MyDHkey, DHparms) -> SharedSecret
151 Types:
153 OthersDHkey = crypto:dh_public()
155 MyDHkey = crypto:dh_private()
156 DHparms = #'DHParameter'{}
157 SharedSecret = binary()
158 Computes shared secret.
160 decrypt_private(CipherText, Key) -> PlainText
162 decrypt_private(CipherText, Key, Options) -> PlainText
164 Types:
166 CipherText = binary()
168 Key = rsa_private_key()
169 Options = crypto:pk_encrypt_decrypt_opts()
170 PlainText = binary()
171 Public-key decryption using the private key. See also
173 crypto:private_decrypt/4
174 decrypt_public(CipherText, Key) -> PlainText
176 decrypt_public(CipherText, Key, Options) -> PlainText
178 Types:
180 CipherText = binary()
182 Key = rsa_public_key()
183 Options = crypto:pk_encrypt_decrypt_opts()
184 PlainText = binary()
185 Public-key decryption using the public key. See also crypto:pub‐
187 lic_decrypt/4
188 der_decode(Asn1Type, Der) -> Entity
190 Types:
192 Asn1Type = asn1_type()
194 Der = binary()
195 Entity = term()
196 Decodes a public-key ASN.1 DER encoded entity.
198 der_encode(Asn1Type, Entity) -> Der
200 Types:
202 Asn1Type = asn1_type()
204 Entity = term()
205 Der = binary()
206 Encodes a public-key entity with ASN.1 DER encoding.
208 dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) ->
210 {ok, {Size, Group}} | {error, term()}
211 Types:
213 MinSize = SuggestedSize = MaxSize = integer() >= 1
215 Groups = undefined | [{Size, [Group]}]
216 Size = integer() >= 1
217 Group = {G, P}
218 G = P = integer() >= 1
219 Selects a group for Diffie-Hellman key exchange with the key
221 size in the range MinSize...MaxSize and as close to Suggested‐
222 Size as possible. If Groups == undefined a default set will be
223 used, otherwise the group is selected from Groups.
224 First a size, as close as possible to SuggestedSize, is
226 selected. Then one group with that key size is randomly selected
227 from the specified set of groups. If no size within the limits
228 of MinSize and MaxSize is available, {error,no_group_found} is
229 returned.
230 The default set of groups is listed in lib/public_key/priv/mod‐
232 uli. This file may be regenerated like this:
233 $> cd $ERL_TOP/lib/public_key/priv/
235 $> generate
236 ---- wait until all background jobs has finished. It may take several days !
237 $> cat moduli-* > moduli
238 $> cd ..; make
239 encrypt_private(PlainText, Key) -> CipherText
242 encrypt_private(PlainText, Key, Options) -> CipherText
244 Types:
246 PlainText = binary()
248 Key = rsa_private_key()
249 Options = crypto:pk_encrypt_decrypt_opts()
250 CipherText = binary()
251 Public-key encryption using the private key. See also
253 crypto:private_encrypt/4.
254 encrypt_public(PlainText, Key) -> CipherText
256 encrypt_public(PlainText, Key, Options) -> CipherText
258 Types:
260 PlainText = binary()
262 Key = rsa_public_key()
263 Options = crypto:pk_encrypt_decrypt_opts()
264 CipherText = binary()
265 Public-key encryption using the public key. See also crypto:pub‐
267 lic_encrypt/4.
268 generate_key(Params :: DHparams | ECparams | RSAparams) ->
270 DHkeys | ECkey | RSAkey
271 Types:
273 DHparams = #'DHParameter'{}
275 DHkeys = {PublicDH :: binary(), PrivateDH :: binary()}
276 ECparams = ecpk_parameters_api()
277 ECkey = #'ECPrivateKey'{}
278 RSAparams = {rsa, Size, PubExp}
279 Size = PubExp = integer() >= 1
280 RSAkey = #'RSAPrivateKey'{}
281 Generates a new keypair. Note that except for Diffie-Hellman the
283 public key is included in the private key structure. See also
284 crypto:generate_key/2
285 pem_decode(PemBin :: binary()) -> [pem_entry()]
287 Decodes PEM binary data and returns entries as ASN.1 DER encoded
289 entities.
290 Example {ok, PemBin} = file:read_file("cert.pem"). PemEntries =
292 public_key:pem_decode(PemBin).
293 pem_encode(PemEntries :: [pem_entry()]) -> binary()
295 Creates a PEM binary.
297 pem_entry_decode(PemEntry) -> term()
299 pem_entry_decode(PemEntry, Password) -> term()
301 Types:
303 PemEntry = pem_entry()
305 Password = string()
306 Decodes a PEM entry. pem_decode/1 returns a list of PEM entries.
308 Notice that if the PEM entry is of type 'SubjectPublickeyInfo',
309 it is further decoded to an rsa_public_key() or dsa_pub‐
310 lic_key().
311 pem_entry_encode(Asn1Type, Entity) -> pem_entry()
313 pem_entry_encode(Asn1Type, Entity, InfoPwd) -> pem_entry()
315 Types:
317 Asn1Type = pki_asn1_type()
319 Entity = term()
320 InfoPwd = {CipherInfo, Password}
321 CipherInfo = cipher_info()
322 Password = string()
323 Creates a PEM entry that can be feed to pem_encode/1.
325 If Asn1Type is 'SubjectPublicKeyInfo', Entity must be either an
327 rsa_public_key(), dsa_public_key() or an ec_public_key() and
328 this function creates the appropriate 'SubjectPublicKeyInfo'
329 entry.
330 pkix_decode_cert(Cert, Type) ->
332 #'Certificate'{} | #'OTPCertificate'{}
333 Types:
335 Cert = der_encoded()
337 Type = plain | otp
338 Decodes an ASN.1 DER-encoded PKIX certificate. Option otp uses
340 the customized ASN.1 specification OTP-PKIX.asn1 for decoding
341 and also recursively decode most of the standard parts.
342 pkix_encode(Asn1Type, Entity, Type) -> Der
344 Types:
346 Asn1Type = asn1_type()
348 Entity = term()
349 Type = otp | plain
350 Der = der_encoded()
351 DER encodes a PKIX x509 certificate or part of such a certifi‐
353 cate. This function must be used for encoding certificates or
354 parts of certificates that are decoded/created in the otp for‐
355 mat, whereas for the plain format this function directly calls
356 der_encode/2.
357 pkix_is_issuer(Cert, IssuerCert) -> boolean()
359 Types:
361 Cert =
363 der_encoded() | #'OTPCertificate'{} | #'Certifi‐
364 cateList'{}
365 IssuerCert = der_encoded() | #'OTPCertificate'{}
366 Checks if IssuerCert issued Cert.
368 pkix_is_fixed_dh_cert(Cert) -> boolean()
370 Types:
372 Cert = der_encoded() | #'OTPCertificate'{}
374 Checks if a certificate is a fixed Diffie-Hellman certificate.
376 pkix_is_self_signed(Cert) -> boolean()
378 Types:
380 Cert = der_encoded() | #'OTPCertificate'{}
382 Checks if a certificate is self-signed.
384 pkix_issuer_id(Cert, IssuedBy) ->
386 {ok, issuer_id()} | {error, Reason}
387 Types:
389 Cert = der_encoded() | #'OTPCertificate'{}
391 IssuedBy = self | other
392 Reason = term()
393 Returns the issuer id.
395 pkix_normalize_name(Issuer) -> Normalized
397 Types:
399 Issuer = Normalized = issuer_name()
401 Normalizes an issuer name so that it can be easily compared to
403 another issuer name.
404 pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicK‐
406 eyInfo, PolicyTree}} | {error, {bad_cert, Reason}}
407 Types:
409 TrustedCert = #'OTPCertificate'{} | der_encoded() | atom()
411 Normally a trusted certificate, but it can also be a path-
412 validation error that can be discovered while constructing
413 the input to this function and that is to be run through
414 the verify_fun. Examples are unknown_ca and self‐
415 signed_peer.
416 CertChain = [der_encoded()]
417 A list of DER-encoded certificates in trust order ending
418 with the peer certificate.
419 Options = proplists:proplist()
420 PublicKeyInfo = {?'rsaEncryption' | ?'id-dsa', rsa_pub‐
421 lic_key() | integer(), 'NULL' | 'Dss-Parms'{}}
422 PolicyTree = term()
423 At the moment this is always an empty list as policies are
424 not currently supported.
425 Reason = cert_expired | invalid_issuer | invalid_signature |
426 name_not_permitted | missing_basic_constraint |
427 invalid_key_usage | {revoked, crl_reason()} | atom()
428 Performs a basic path validation according to RFC 5280. However,
430 CRL validation is done separately by pkix_crls_validate/3 and
431 is to be called from the supplied verify_fun.
432 Available options:
434 {verify_fun, {fun(), InitialUserState::term()}:
436 The fun must be defined as:
437 fun(OtpCert :: #'OTPCertificate'{},
439 Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
440 {extension, #'Extension'{}},
441 InitialUserState :: term()) ->
442 {valid, UserState :: term()} |
443 {valid_peer, UserState :: term()} |
444 {fail, Reason :: term()} |
445 {unknown, UserState :: term()}.
446 If the verify callback fun returns {fail, Reason}, the veri‐
449 fication process is immediately stopped. If the verify call‐
450 back fun returns {valid, UserState}, the verification
451 process is continued. This can be used to accept specific
452 path validation errors, such as selfsigned_peer, as well as
453 verifying application-specific extensions. If called with an
454 extension unknown to the user application, the return value
455 {unknown, UserState} is to be used.
456 {max_path_length, integer()}:
458 The max_path_length is the maximum number of non-self-
459 issued intermediate certificates that can follow the peer
460 certificate in a valid certification path. So, if
461 max_path_length is 0, the PEER must be signed by the trusted
462 ROOT-CA directly, if it is 1, the path can be PEER, CA,
463 ROOT-CA, if it is 2, the path can be PEER, CA, CA, ROOT-CA,
464 and so on.
465 Possible reasons for a bad certificate:
467 cert_expired:
469 Certificate is no longer valid as its expiration date has
470 passed.
471 invalid_issuer:
473 Certificate issuer name does not match the name of the
474 issuer certificate in the chain.
475 invalid_signature:
477 Certificate was not signed by its issuer certificate in the
478 chain.
479 name_not_permitted:
481 Invalid Subject Alternative Name extension.
482 missing_basic_constraint:
484 Certificate, required to have the basic constraints exten‐
485 sion, does not have a basic constraints extension.
486 invalid_key_usage:
488 Certificate key is used in an invalid way according to the
489 key-usage extension.
490 {revoked, crl_reason()}:
492 Certificate has been revoked.
493 atom():
495 Application-specific error reason that is to be checked by
496 the verify_fun.
497 pkix_crl_issuer(CRL :: CRL | #'CertificateList'{}) -> Issuer
499 Types:
501 CRL = der_encoded()
503 Issuer = issuer_name()
504 Returns the issuer of the CRL.
506 pkix_crls_validate(OTPcertificate, DPandCRLs, Options) ->
508 CRLstatus
509 Types:
511 OTPcertificate = #'OTPCertificate'{}
513 DPandCRLs = [DPandCRL]
514 DPandCRL = {DP, {DerCRL, CRL}}
515 DP = #'DistributionPoint'{}
516 DerCRL = der_encoded()
517 CRL = #'CertificateList'{}
518 Options = [{atom(), term()}]
519 CRLstatus = valid | {bad_cert, BadCertReason}
520 BadCertReason =
521 revocation_status_undetermined |
522 {revocation_status_undetermined, Reason :: term()} |
523 {revoked, crl_reason()}
524 Performs CRL validation. It is intended to be called from the
526 verify fun of pkix_path_validation/3 .
527 Available options:
529 {update_crl, fun()}:
531 The fun has the following type specification:
532 fun(#'DistributionPoint'{}, #'CertificateList'{}) ->
534 #'CertificateList'{}
535 The fun uses the information in the distribution point to
537 access the latest possible version of the CRL. If this fun
538 is not specified, Public Key uses the default implementa‐
539 tion:
540 fun(_DP, CRL) -> CRL end
542 {issuer_fun, fun()}:
544 The fun has the following type specification:
545 fun(#'DistributionPoint'{}, #'CertificateList'{},
547 {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
548 {ok, #'OTPCertificate'{}, [der_encoded]}
549 The fun returns the root certificate and certificate chain
551 that has signed the CRL.
552 fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}
554 {undetermined_details, boolean()}:
556 Defaults to false. When revocation status cannot be deter‐
557 mined, and this option is set to true, details of why no
558 CRLs where accepted are included in the return value.
559 pkix_crl_verify(CRL, Cert) -> boolean()
561 Types:
563 CRL = der_encoded() | #'CertificateList'{}
565 Cert = der_encoded() | #'OTPCertificate'{}
566 Verify that Cert is the CRL signer.
568 pkix_dist_point(Cert) -> DistPoint
570 Types:
572 Cert = der_encoded() | #'OTPCertificate'{}
574 DistPoint = #'DistributionPoint'{}
575 Creates a distribution point for CRLs issued by the same issuer
577 as Cert. Can be used as input to pkix_crls_validate/3
578 pkix_dist_points(Cert) -> DistPoints
580 Types:
582 Cert = der_encoded() | #'OTPCertificate'{}
584 DistPoints = [#'DistributionPoint'{}]
585 Extracts distribution points from the certificates extensions.
587 pkix_match_dist_point(CRL, DistPoint) -> boolean()
589 Types:
591 CRL = der_encoded() | #'CertificateList'{}
593 DistPoint = #'DistributionPoint'{}
594 Checks whether the given distribution point matches the Issuing
596 Distribution Point of the CRL, as described in RFC 5280. If the
597 CRL doesn't have an Issuing Distribution Point extension, the
598 distribution point always matches.
599 pkix_sign(Cert, Key) -> Der
601 Types:
603 Cert = #'OTPTBSCertificate'{}
605 Key = private_key()
606 Der = der_encoded()
607 Signs an 'OTPTBSCertificate'. Returns the corresponding DER-
609 encoded certificate.
610 pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}
612 Types:
614 AlgorithmId = oid()
616 DigestType = crypto:rsa_digest_type()
617 SignatureType = rsa | dsa | ecdsa
618 Translates signature algorithm OID to Erlang digest and signa‐
620 ture types.
621 The AlgorithmId is the signature OID from a certificate or a
623 certificate revocation list.
624 pkix_test_data(Options) -> Config
626 pkix_test_data([chain_opts()]) -> [conf_opt()]
627 Types:
629 Options = #{chain_type() := chain_opts()}
631 Options for ROOT, Intermediate and Peer certs
632 chain_type() = server_chain | client_chain
633 chain_opts() = #{root := [cert_opt()] | root_cert(), peer :=
634 [cert_opt()], intermediates => [[cert_opt()]]}
635 A valid chain must have at least a ROOT and a peer cert.
636 The root cert can be given either as a cert pre-generated
637 by pkix_test_root_cert/2 , or as root cert generation
638 options.
639 root_cert() = #{cert := der_encoded(), key := Key}
640 A root certificate generated by pkix_test_root_cert/2 .
641 cert_opt() = {Key, Value}
642 For available options see cert_opt() below.
643 Config = #{server_config := [conf_opt()], client_config :=
644 [conf_opt()]}
645 conf_opt() = {cert, der_encoded()} | {key, PrivateKey} |{cac‐
646 erts, [der_encoded()]}
647 This is a subset of the type ssl:tls_option(). PrivateKey
648 is what generate_key/1 returns.
649 Creates certificate configuration(s) consisting of certificate
651 and its private key plus CA certificate bundle, for a client and
652 a server, intended to facilitate automated testing of applica‐
653 tions using X509-certificates, often through SSL/TLS. The test
654 data can be used when you have control over both the client and
655 the server in a test scenario.
656 When this function is called with a map containing client and
658 server chain specifications; it generates both a client and a
659 server certificate chain where the cacerts returned for the
660 server contains the root cert the server should trust and the
661 intermediate certificates the server should present to connect‐
662 ing clients. The root cert the server should trust is the one
663 used as root of the client certificate chain. Vice versa applies
664 to the cacerts returned for the client. The root cert(s) can
665 either be pre-generated with pkix_test_root_cert/2 , or if
666 options are specified; it is (they are) generated.
667 When this function is called with a list of certificate options;
669 it generates a configuration with just one node certificate
670 where cacerts contains the root cert and the intermediate certs
671 that should be presented to a peer. In this case the same root
672 cert must be used for all peers. This is useful in for example
673 an Erlang distributed cluster where any node, towards another
674 node, acts either as a server or as a client depending on who
675 connects to whom. The generated certificate contains a subject
676 altname, which is not needed in a client certificate, but makes
677 the certificate useful for both roles.
678 The cert_opt() type consists of the following options:
680 {digest, digest_type()}:
682 Hash algorithm to be used for signing the certificate
683 together with the key option. Defaults to sha that is sha1.
684 {key, key_params() | private_key()}:
686 Parameters to be used to call public_key:generate_key/1, to
687 generate a key, or an existing key. Defaults to generating
688 an ECDSA key. Note this could fail if Erlang/OTP is compiled
689 with a very old cryptolib.
690 {validity, {From::erlang:timestamp(), To::erlang:time‐
692 stamp()}} :
693 The validity period of the certificate.
694 {extensions, [#'Extension'{}]}:
696 Extensions to include in the certificate.
697 Default extensions included in CA certificates if not other‐
699 wise specified are:
700 [#'Extension'{extnID = ?'id-ce-keyUsage',
702 extnValue = [keyCertSign, cRLSign],
703 critical = false},
704 #'Extension'{extnID = ?'id-ce-basicConstraints',
705 extnValue = #'BasicConstraints'{cA = true},
706 critical = true}]
707 Default extensions included in the server peer cert if not
710 otherwise specified are:
711 [#'Extension'{extnID = ?'id-ce-keyUsage',
713 extnValue = [digitalSignature, keyAgreement],
714 critical = false},
715 #'Extension'{extnID = ?'id-ce-subjectAltName',
716 extnValue = [{dNSName, Hostname}],
717 critical = false}]
718 Hostname is the result of calling net_adm:localhost() in the
721 Erlang node where this funcion is called.
722 Note:
724 Note that the generated certificates and keys does not provide a
725 formally correct PKIX-trust-chain and they cannot be used to
726 achieve real security. This function is provided for testing
727 purposes only.
728 pkix_test_root_cert(Name, Options) -> RootCert
731 Types:
733 Name = string()
735 The root certificate name.
736 Options = [cert_opt()]
737 For available options see cert_opt() under
738 pkix_test_data/1.
739 RootCert = #{cert := der_encoded(), key := Key}
740 A root certificate and key. The Key is generated by gener‐
741 ate_key/1.
742 Generates a root certificate that can be used in multiple calls
744 to pkix_test_data/1 when you want the same root certificate for
745 several generated certificates.
746 pkix_verify(Cert, Key) -> boolean()
748 Types:
750 Cert = der_encoded()
752 Key = public_key()
753 Verifies PKIX x.509 certificate signature.
755 pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()
757 pkix_verify_hostname(Cert, ReferenceIDs, Opts) -> boolean()
758 Types:
760 Cert = der_encoded() | #'OTPCertificate'{}
762 ReferenceIDs = [ RefID ]
763 RefID = {dns_id,string()} | {srv_id,string()} |
764 {uri_id,string()} | {ip,inet:ip_address()|string()} | {Other‐
765 RefID,term()}}
766 OtherRefID = atom()
767 Opts = [ PvhOpt() ]
768 PvhOpt = [MatchOpt | FailCallBackOpt | FqdnExtractOpt]
769 MatchOpt = {match_fun, fun(RefId | FQDN::string(), Presente‐
770 dID) -> boolean() | default}
771 PresentedID = {dNSName,string()} | {uniformResourceIdenti‐
772 fier,string() | {iPAddress,list(byte())} | {Other‐
773 PresId,term()}}
774 OtherPresID = atom()
775 FailCallBackOpt = {fail_callback, fun(#'OTPCertificate'{}) ->
776 boolean()}
777 FqdnExtractOpt = {fqdn_fun, fun(RefID) -> FQDN::string() |
778 default | undefined}
779 This function checks that the Presented Identifier (e.g host‐
781 name) in a peer certificate is in agreement with at least one of
782 the Reference Identifier that the client expects to be con‐
783 nected to. The function is intended to be added as an extra
784 client check of the peer certificate when performing pub‐
785 lic_key:pkix_path_validation/3
786 See RFC 6125 for detailed information about hostname verifica‐
788 tion. The User's Guide and code examples describes this function
789 more detailed.
790 The {OtherRefId,term()} is defined by the user and is passed to
792 the match_fun, if defined. If the term in OtherRefId is a
793 binary, it will be converted to a string.
794 The ip Reference ID takes an inet:ip_address() or an ip address
796 in string format (E.g "10.0.1.1" or "1234::5678:9012") as second
797 element.
798 The options are:
800 match_fun:
802 The fun/2 in this option replaces the default host name
803 matching rules. The fun should return a boolean to tell if
804 the Reference ID and Presented ID matches or not. The fun
805 can also return a third value, the atom default, if the
806 default matching rules shall apply. This makes it possible
807 to augment the tests with a special case:
808 fun(....) -> true; % My special case
810 (_, _) -> default % all others falls back to the inherit tests
811 end
812 See pkix_verify_hostname_match_fun/1 for a function that takes
814 a protocol name as argument and returns a fun/2 suitable for
815 this option and Re-defining the match operation in the User's
816 Guide for an example.
817 fail_callback:
819 If a matching fails, there could be circumstances when the
820 certificate should be accepted anyway. Think for example of
821 a web browser where you choose to accept an outdated cer‐
822 tificate. This option enables implementation of such a func‐
823 tion. This fun/1 is called when no ReferenceID matches. The
824 return value of the fun (a boolean()) decides the outcome.
825 If true the the certificate is accepted otherwise it is
826 rejected. See "Pinning" a Certificate in the User's Guide.
827 fqdn_fun:
829 This option augments the host name extraction from URIs and
830 other Reference IDs. It could for example be a very special
831 URI that is not standardised. The fun takes a Reference ID
832 as argument and returns one of:
833 * the hostname
835 * the atom default: the default host name extract function
837 will be used
838 * the atom undefined: a host name could not be extracted.
840 The pkix_verify_hostname/3 will return false.
841 For an example, see Hostname extraction in the User's Guide.
843 pkix_verify_hostname_match_fun(Protcol) -> fun(RefId | FQDN::string(),
845 PresentedID) -> boolean() | default
846 Types:
848 Protocol = https
850 The algorithm for wich the fun should implement the special
851 matching rules
852 RefId
853 See pkix_verify_hostname/3.
854 FQDN
855 See pkix_verify_hostname/3.
856 PresentedID
857 See pkix_verify_hostname/3.
858 The return value of calling this function is intended to be used
860 in the match_fun option in pkix_verify_hostname/3.
861 The returned fun augments the verify hostname matching according
863 to the specific rules for the protocol in the argument.
864 sign(Msg, DigestType, Key) -> Signature
866 sign(Msg, DigestType, Key, Options) -> Signature
868 Types:
870 Msg = binary() | {digest, binary()}
872 DigestType = digest_type()
873 Key = private_key()
874 Options = crypto:pk_sign_verify_opts()
875 Signature = binary()
876 Creates a digital signature.
878 The Msg is either the binary "plain text" data to be signed or
880 it is the hashed value of "plain text", that is, the digest.
881 ssh_decode(SshBin, Type) -> Decoded
883 Types:
885 SshBin = binary()
887 Type = ssh2_pubkey | OtherType | InternalType
888 OtherType = public_key | ssh_file()
889 InternalType = new_openssh
890 Decoded = Decoded_ssh2_pubkey | Decoded_OtherType
891 Decoded_ssh2_pubkey = public_key()
892 Decoded_OtherType = [{public_key(), Attributes}]
893 Attributes = [{atom(), term()}]
894 Decodes an SSH file-binary. In the case of known_hosts or
896 auth_keys, the binary can include one or more lines of the file.
897 Returns a list of public keys and their attributes, possible
898 attribute values depends on the file type represented by the
899 binary.
900 If the Type is ssh2_pubkey, the result will be Decoded_ssh2_pub‐
902 key. Otherwise it will be Decoded_OtherType.
903 RFC4716 attributes - see RFC 4716.:
905 {headers, [{string(), utf8_string()}]}
906 auth_key attributes - see manual page for sshd.:
908 {comment, string()}{options, [string()]}{bits, integer()} -
909 In SSH version 1 files.
910 known_host attributes - see manual page for sshd.:
912 {hostnames, [string()]}{comment, string()}{bits, integer()}
913 - In SSH version 1 files.
914 Example: {ok, SshBin} = file:read_file("known_hosts").
916 If Type is public_key the binary can be either an RFC4716 public
918 key or an OpenSSH public key.
919 ssh_encode(InData, Type) -> binary()
921 Types:
923 Type = ssh2_pubkey | OtherType
925 OtherType = public_key | ssh_file()
926 InData = InData_ssh2_pubkey | OtherInData
927 InData_ssh2_pubkey = public_key()
928 OtherInData = [{Key, Attributes}]
929 Key = public_key()
930 Attributes = [{atom(), term()}]
931 Encodes a list of SSH file entries (public keys and attributes)
933 to a binary. Possible attributes depend on the file type, see
934 ssh_decode/2 .
935 If the Type is ssh2_pubkey, the InData shall be InData_ssh2_pub‐
937 key. Otherwise it shall be OtherInData.
938 ssh_hostkey_fingerprint(HostKey) -> string()
940 ssh_hostkey_fingerprint(DigestType, HostKey) -> string()
941 ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]
942 Types:
944 HostKey = public_key()
946 DigestType = digest_type()
947 Calculates a ssh fingerprint from a public host key as openssh
949 does.
950 The algorithm in ssh_hostkey_fingerprint/1 is md5 to be compati‐
952 ble with older ssh-keygen commands. The string from the second
953 variant is prepended by the algorithm name in uppercase as in
954 newer ssh-keygen commands.
955 Examples:
957 2> public_key:ssh_hostkey_fingerprint(Key).
959 "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
960 3> public_key:ssh_hostkey_fingerprint(md5,Key).
962 "MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
963 4> public_key:ssh_hostkey_fingerprint(sha,Key).
965 "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
966 5> public_key:ssh_hostkey_fingerprint(sha256,Key).
968 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
969 6> public_key:ssh_hostkey_fingerprint([sha,sha256],Key).
971 ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
972 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
973 verify(Msg, DigestType, Signature, Key) -> boolean()
976 verify(Msg, DigestType, Signature, Key, Options) -> boolean()
978 Types:
980 Msg = binary() | {digest, binary()}
982 DigestType = digest_type()
983 Signature = binary()
984 Key = public_key()
985 Options = crypto:pk_sign_verify_opts()
986 Verifies a digital signature.
988 The Msg is either the binary "plain text" data or it is the
990 hashed value of "plain text", that is, the digest.
991 short_name_hash(Name) -> string()
993 Types:
995 Name = issuer_name()
997 Generates a short hash of an issuer name. The hash is returned
999 as a string containing eight hexadecimal digits.
1000 The return value of this function is the same as the result of
1002 the commands openssl crl -hash and openssl x509 -issuer_hash,
1003 when passed the issuer name of a CRL or a certificate, respec‐
1004 tively. This hash is used by the c_rehash tool to maintain a
1005 directory of symlinks to CRL files, in order to facilitate look‐
1006 ing up a CRL by its issuer name.
1007Ericsson AB public_key 1.7 public_key(3)