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' |
34 'RSAPrivateKey' |
35 'RSAPublicKey' |
36 'DSAPrivateKey' |
37 'DSAPublicKey' |
38 'DHParameter' |
39 'SubjectPublicKeyInfo' |
40 'PrivateKeyInfo' |
41 'CertificationRequest' |
42 'CertificateList' |
43 'ECPrivateKey' |
44 'EcpkParameters'
45 asn1_type() = atom()
47 ASN.1 type present in the Public Key applications ASN.1 specifi‐
49 cations.
50 pem_entry() =
52 {pki_asn1_type(),
53 der_or_encrypted_der(),
54 not_encrypted | cipher_info()}
55 der_or_encrypted_der() = binary()
57 cipher_info() = {cipher(), cipher_info_params()}
59 cipher() = string()
61 salt() = binary()
63 cipher_info_params() =
65 salt() |
66 {#'PBEParameter'{}, digest_type()} |
67 #'PBES2-params'{}
68 Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC"
70 Salt could be generated with crypto:strong_rand_bytes(8).
72 public_key() =
74 rsa_public_key() |
75 dsa_public_key() |
76 ec_public_key() |
77 ed_public_key()
78 rsa_public_key() = #'RSAPublicKey'{}
80 dsa_public_key() = {integer(), #'Dss-Parms'{}}
82 ec_public_key() = {#'ECPoint'{}, ecpk_parameters_api()}
84 ecpk_parameters() =
86 {ecParameters, #'ECParameters'{}} |
87 {namedCurve, Oid :: tuple()}
88 ecpk_parameters_api() =
90 ecpk_parameters() |
91 #'ECParameters'{} |
92 {namedCurve, Name :: crypto:ec_named_curve()}
93 ed_public_key() = {ed_pub, ed25519 | ed448, Key :: binary()}
95 Warning:
97 This format of the EdDSA curves is temporary and may change
98 without prior notice!
99 private_key() =
102 rsa_private_key() |
103 dsa_private_key() |
104 ec_private_key() |
105 ed_private_key()
106 rsa_private_key() = #'RSAPrivateKey'{}
108 dsa_private_key() = #'DSAPrivateKey'{}
110 ec_private_key() = #'ECPrivateKey'{}
112 ed_private_key() =
114 {ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()}
115 Warning:
117 This format of the EdDSA curves is temporary and may change
118 without prior notice!
119 key_params() =
122 #'DHParameter'{} |
123 {namedCurve, oid()} |
124 #'ECParameters'{} |
125 {rsa, Size :: integer(), PubExp :: integer()}
126 digest_type() =
128 none |
129 sha1 |
130 crypto:rsa_digest_type() |
131 crypto:dss_digest_type() |
132 crypto:ecdsa_digest_type()
133 crl_reason() =
135 unspecified |
136 keyCompromise |
137 cACompromise |
138 affiliationChanged |
139 superseded |
140 cessationOfOperation |
141 certificateHold |
142 privilegeWithdrawn |
143 aACompromise
144 issuer_id() = {SerialNr :: integer(), issuer_name()}
146 issuer_name() = {rdnSequence, [#'AttributeTypeAndValue'{}]}
148 ssh_file() =
150 openssh_public_key |
151 rfc4716_public_key |
152 known_hosts |
153 auth_keys
154
156 compute_key(OthersECDHkey, MyECDHkey) -> SharedSecret
157 Types:
159 OthersECDHkey = #'ECPoint'{}
161 MyECDHkey = #'ECPrivateKey'{}
162 SharedSecret = binary()
163 Computes shared secret.
165 compute_key(OthersDHkey, MyDHkey, DHparms) -> SharedSecret
167 Types:
169 OthersDHkey = crypto:dh_public()
171 MyDHkey = crypto:dh_private()
172 DHparms = #'DHParameter'{}
173 SharedSecret = binary()
174 Computes shared secret.
176 decrypt_private(CipherText, Key) -> PlainText
178 decrypt_private(CipherText, Key, Options) -> PlainText
180 Types:
182 CipherText = binary()
184 Key = rsa_private_key()
185 Options = crypto:pk_encrypt_decrypt_opts()
186 PlainText = binary()
187 Public-key decryption using the private key. See also
189 crypto:private_decrypt/4
190 decrypt_public(CipherText, Key) -> PlainText
192 decrypt_public(CipherText, Key, Options) -> PlainText
194 Types:
196 CipherText = binary()
198 Key = rsa_public_key()
199 Options = crypto:pk_encrypt_decrypt_opts()
200 PlainText = binary()
201 Public-key decryption using the public key. See also crypto:pub‐
203 lic_decrypt/4
204 der_decode(Asn1Type, Der) -> Entity
206 Types:
208 Asn1Type = asn1_type()
210 Der = binary()
211 Entity = term()
212 Decodes a public-key ASN.1 DER encoded entity.
214 der_encode(Asn1Type, Entity) -> Der
216 Types:
218 Asn1Type = asn1_type()
220 Entity = term()
221 Der = binary()
222 Encodes a public-key entity with ASN.1 DER encoding.
224 dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) ->
226 {ok, {Size, Group}} | {error, term()}
227 Types:
229 MinSize = SuggestedSize = MaxSize = integer() >= 1
231 Groups = undefined | [{Size, [Group]}]
232 Size = integer() >= 1
233 Group = {G, P}
234 G = P = integer() >= 1
235 Selects a group for Diffie-Hellman key exchange with the key
237 size in the range MinSize...MaxSize and as close to Suggested‐
238 Size as possible. If Groups == undefined a default set will be
239 used, otherwise the group is selected from Groups.
240 First a size, as close as possible to SuggestedSize, is
242 selected. Then one group with that key size is randomly selected
243 from the specified set of groups. If no size within the limits
244 of MinSize and MaxSize is available, {error,no_group_found} is
245 returned.
246 The default set of groups is listed in lib/public_key/priv/mod‐
248 uli. This file may be regenerated like this:
249 $> cd $ERL_TOP/lib/public_key/priv/
251 $> generate
252 ---- wait until all background jobs has finished. It may take several days !
253 $> cat moduli-* > moduli
254 $> cd ..; make
255 encrypt_private(PlainText, Key) -> CipherText
258 encrypt_private(PlainText, Key, Options) -> CipherText
260 Types:
262 PlainText = binary()
264 Key = rsa_private_key()
265 Options = crypto:pk_encrypt_decrypt_opts()
266 CipherText = binary()
267 Public-key encryption using the private key. See also
269 crypto:private_encrypt/4.
270 encrypt_public(PlainText, Key) -> CipherText
272 encrypt_public(PlainText, Key, Options) -> CipherText
274 Types:
276 PlainText = binary()
278 Key = rsa_public_key()
279 Options = crypto:pk_encrypt_decrypt_opts()
280 CipherText = binary()
281 Public-key encryption using the public key. See also crypto:pub‐
283 lic_encrypt/4.
284 generate_key(Params :: DHparams | ECparams | RSAparams) ->
286 DHkeys | ECkey | RSAkey
287 Types:
289 DHparams = #'DHParameter'{}
291 DHkeys = {PublicDH :: binary(), PrivateDH :: binary()}
292 ECparams = ecpk_parameters_api()
293 ECkey = #'ECPrivateKey'{}
294 RSAparams = {rsa, Size, PubExp}
295 Size = PubExp = integer() >= 1
296 RSAkey = #'RSAPrivateKey'{}
297 Generates a new keypair. Note that except for Diffie-Hellman the
299 public key is included in the private key structure. See also
300 crypto:generate_key/2
301 pem_decode(PemBin :: binary()) -> [pem_entry()]
303 Decodes PEM binary data and returns entries as ASN.1 DER encoded
305 entities.
306 Example {ok, PemBin} = file:read_file("cert.pem").
308 pem_encode(PemEntries :: [pem_entry()]) -> binary()
310 Creates a PEM binary.
312 pem_entry_decode(PemEntry) -> term()
314 pem_entry_decode(PemEntry, Password) -> term()
316 Types:
318 PemEntry = pem_entry()
320 Password = string()
321 Decodes a PEM entry. pem_decode/1 returns a list of PEM entries.
323 Notice that if the PEM entry is of type 'SubjectPublickeyInfo',
324 it is further decoded to an rsa_public_key() or dsa_pub‐
325 lic_key().
326 pem_entry_encode(Asn1Type, Entity) -> pem_entry()
328 pem_entry_encode(Asn1Type, Entity, InfoPwd) -> pem_entry()
330 Types:
332 Asn1Type = pki_asn1_type()
334 Entity = term()
335 InfoPwd = {CipherInfo, Password}
336 CipherInfo = cipher_info()
337 Password = string()
338 Creates a PEM entry that can be feed to pem_encode/1.
340 If Asn1Type is 'SubjectPublicKeyInfo', Entity must be either an
342 rsa_public_key(), dsa_public_key() or an ec_public_key() and
343 this function creates the appropriate 'SubjectPublicKeyInfo'
344 entry.
345 pkix_decode_cert(Cert, Type) ->
347 #'Certificate'{} | #'OTPCertificate'{}
348 Types:
350 Cert = der_encoded()
352 Type = plain | otp
353 Decodes an ASN.1 DER-encoded PKIX certificate. Option otp uses
355 the customized ASN.1 specification OTP-PKIX.asn1 for decoding
356 and also recursively decode most of the standard parts.
357 pkix_encode(Asn1Type, Entity, Type) -> Der
359 Types:
361 Asn1Type = asn1_type()
363 Entity = term()
364 Type = otp | plain
365 Der = der_encoded()
366 DER encodes a PKIX x509 certificate or part of such a certifi‐
368 cate. This function must be used for encoding certificates or
369 parts of certificates that are decoded/created in the otp for‐
370 mat, whereas for the plain format this function directly calls
371 der_encode/2.
372 pkix_is_issuer(Cert, IssuerCert) -> boolean()
374 Types:
376 Cert =
378 der_encoded() | #'OTPCertificate'{} | #'Certifi‐
379 cateList'{}
380 IssuerCert = der_encoded() | #'OTPCertificate'{}
381 Checks if IssuerCert issued Cert.
383 pkix_is_fixed_dh_cert(Cert) -> boolean()
385 Types:
387 Cert = der_encoded() | #'OTPCertificate'{}
389 Checks if a certificate is a fixed Diffie-Hellman certificate.
391 pkix_is_self_signed(Cert) -> boolean()
393 Types:
395 Cert = der_encoded() | #'OTPCertificate'{}
397 Checks if a certificate is self-signed.
399 pkix_issuer_id(Cert, IssuedBy) ->
401 {ok, issuer_id()} | {error, Reason}
402 Types:
404 Cert = der_encoded() | #'OTPCertificate'{}
406 IssuedBy = self | other
407 Reason = term()
408 Returns the issuer id.
410 pkix_normalize_name(Issuer) -> Normalized
412 Types:
414 Issuer = Normalized = issuer_name()
416 Normalizes an issuer name so that it can be easily compared to
418 another issuer name.
419 pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicK‐
421 eyInfo, PolicyTree}} | {error, {bad_cert, Reason}}
422 Types:
424 TrustedCert = #'OTPCertificate'{} | der_encoded() | atom()
426 Normally a trusted certificate, but it can also be a path-
427 validation error that can be discovered while constructing
428 the input to this function and that is to be run through
429 the verify_fun. Examples are unknown_ca and self‐
430 signed_peer.
431 CertChain = [der_encoded()]
432 A list of DER-encoded certificates in trust order ending
433 with the peer certificate.
434 Options = proplists:proplist()
435 PublicKeyInfo = {?'rsaEncryption' | ?'id-dsa', rsa_pub‐
436 lic_key() | integer(), 'NULL' | 'Dss-Parms'{}}
437 PolicyTree = term()
438 At the moment this is always an empty list as policies are
439 not currently supported.
440 Reason = cert_expired | invalid_issuer | invalid_signature |
441 name_not_permitted | missing_basic_constraint |
442 invalid_key_usage | {revoked, crl_reason()} | atom()
443 Performs a basic path validation according to RFC 5280. However,
445 CRL validation is done separately by pkix_crls_validate/3 and
446 is to be called from the supplied verify_fun.
447 Available options:
449 {verify_fun, fun()}:
451 The fun must be defined as:
452 fun(OtpCert :: #'OTPCertificate'{},
454 Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
455 {extension, #'Extension'{}},
456 InitialUserState :: term()) ->
457 {valid, UserState :: term()} |
458 {valid_peer, UserState :: term()} |
459 {fail, Reason :: term()} |
460 {unknown, UserState :: term()}.
461 If the verify callback fun returns {fail, Reason}, the veri‐
464 fication process is immediately stopped. If the verify call‐
465 back fun returns {valid, UserState}, the verification
466 process is continued. This can be used to accept specific
467 path validation errors, such as selfsigned_peer, as well as
468 verifying application-specific extensions. If called with an
469 extension unknown to the user application, the return value
470 {unknown, UserState} is to be used.
471 {max_path_length, integer()}:
473 The max_path_length is the maximum number of non-self-
474 issued intermediate certificates that can follow the peer
475 certificate in a valid certification path. So, if
476 max_path_length is 0, the PEER must be signed by the trusted
477 ROOT-CA directly, if it is 1, the path can be PEER, CA,
478 ROOT-CA, if it is 2, the path can be PEER, CA, CA, ROOT-CA,
479 and so on.
480 Possible reasons for a bad certificate:
482 cert_expired:
484 Certificate is no longer valid as its expiration date has
485 passed.
486 invalid_issuer:
488 Certificate issuer name does not match the name of the
489 issuer certificate in the chain.
490 invalid_signature:
492 Certificate was not signed by its issuer certificate in the
493 chain.
494 name_not_permitted:
496 Invalid Subject Alternative Name extension.
497 missing_basic_constraint:
499 Certificate, required to have the basic constraints exten‐
500 sion, does not have a basic constraints extension.
501 invalid_key_usage:
503 Certificate key is used in an invalid way according to the
504 key-usage extension.
505 {revoked, crl_reason()}:
507 Certificate has been revoked.
508 atom():
510 Application-specific error reason that is to be checked by
511 the verify_fun.
512 pkix_crl_issuer(CRL :: CRL | #'CertificateList'{}) -> Issuer
514 Types:
516 CRL = der_encoded()
518 Issuer = issuer_name()
519 Returns the issuer of the CRL.
521 pkix_crls_validate(OTPcertificate, DPandCRLs, Options) ->
523 CRLstatus
524 Types:
526 OTPcertificate = #'OTPCertificate'{}
528 DPandCRLs = [DPandCRL]
529 DPandCRL = {DP, {DerCRL, CRL}}
530 DP = #'DistributionPoint'{}
531 DerCRL = der_encoded()
532 CRL = #'CertificateList'{}
533 Options = [{atom(), term()}]
534 CRLstatus = valid | {bad_cert, BadCertReason}
535 BadCertReason =
536 revocation_status_undetermined |
537 {revocation_status_undetermined, Reason :: term()} |
538 {revoked, crl_reason()}
539 Performs CRL validation. It is intended to be called from the
541 verify fun of pkix_path_validation/3 .
542 Available options:
544 {update_crl, fun()}:
546 The fun has the following type specification:
547 fun(#'DistributionPoint'{}, #'CertificateList'{}) ->
549 #'CertificateList'{}
550 The fun uses the information in the distribution point to
552 access the latest possible version of the CRL. If this fun
553 is not specified, Public Key uses the default implementa‐
554 tion:
555 fun(_DP, CRL) -> CRL end
557 {issuer_fun, fun()}:
559 The fun has the following type specification:
560 fun(#'DistributionPoint'{}, #'CertificateList'{},
562 {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
563 {ok, #'OTPCertificate'{}, [der_encoded]}
564 The fun returns the root certificate and certificate chain
566 that has signed the CRL.
567 fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}
569 {undetermined_details, boolean()}:
571 Defaults to false. When revocation status can not be deter‐
572 mined, and this option is set to true, details of why no
573 CRLs where accepted are included in the return value.
574 pkix_crl_verify(CRL, Cert) -> boolean()
576 Types:
578 CRL = der_encoded() | #'CertificateList'{}
580 Cert = der_encoded() | #'OTPCertificate'{}
581 Verify that Cert is the CRL signer.
583 pkix_dist_point(Cert) -> DistPoint
585 Types:
587 Cert = der_encoded() | #'OTPCertificate'{}
589 DistPoint = #'DistributionPoint'{}
590 Creates a distribution point for CRLs issued by the same issuer
592 as Cert. Can be used as input to pkix_crls_validate/3
593 pkix_dist_points(Cert) -> DistPoints
595 Types:
597 Cert = der_encoded() | #'OTPCertificate'{}
599 DistPoints = [#'DistributionPoint'{}]
600 Extracts distribution points from the certificates extensions.
602 pkix_match_dist_point(CRL, DistPoint) -> boolean()
604 Types:
606 CRL = der_encoded() | #'CertificateList'{}
608 DistPoint = #'DistributionPoint'{}
609 Checks whether the given distribution point matches the Issuing
611 Distribution Point of the CRL, as described in RFC 5280. If the
612 CRL doesn't have an Issuing Distribution Point extension, the
613 distribution point always matches.
614 pkix_sign(Cert, Key) -> Der
616 Types:
618 Cert = #'OTPTBSCertificate'{}
620 Key = private_key()
621 Der = der_encoded()
622 Signs an 'OTPTBSCertificate'. Returns the corresponding DER-
624 encoded certificate.
625 pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}
627 Types:
629 AlgorithmId = oid()
631 DigestType = crypto:rsa_digest_type()
632 SignatureType = rsa | dsa | ecdsa
633 Translates signature algorithm OID to Erlang digest and signa‐
635 ture types.
636 The AlgorithmId is the signature OID from a certificate or a
638 certificate revocation list.
639 pkix_test_data(Options) -> Config
641 pkix_test_data([chain_opts()]) -> [conf_opt()]
642 Types:
644 Options = #{chain_type() := chain_opts()}
646 Options for ROOT, Intermediate and Peer certs
647 chain_type() = server_chain | client_chain
648 chain_opts() = #{root := [cert_opt()] | root_cert(), peer :=
649 [cert_opt()], intermediates => [[cert_opt()]]}
650 A valid chain must have at least a ROOT and a peer cert.
651 The root cert can be given either as a cert pre-generated
652 by pkix_test_root_cert/2 , or as root cert generation
653 options.
654 root_cert() = #{cert := der_encoded(), key := Key}
655 A root certificate generated by pkix_test_root_cert/2 .
656 cert_opt() = {Key, Value}
657 For available options see cert_opt() below.
658 Config = #{server_config := [conf_opt()], client_config :=
659 [conf_opt()]}
660 conf_opt() = {cert, der_encoded()} | {key, PrivateKey} |{cac‐
661 erts, [der_encoded()]}
662 This is a subset of the type ssl:tls_option(). PrivateKey
663 is what generate_key/1 returns.
664 Creates certificate configuration(s) consisting of certificate
666 and its private key plus CA certificate bundle, for a client and
667 a server, intended to facilitate automated testing of applica‐
668 tions using X509-certificates, often through SSL/TLS. The test
669 data can be used when you have control over both the client and
670 the server in a test scenario.
671 When this function is called with a map containing client and
673 server chain specifications; it generates both a client and a
674 server certificate chain where the cacerts returned for the
675 server contains the root cert the server should trust and the
676 intermediate certificates the server should present to connect‐
677 ing clients. The root cert the server should trust is the one
678 used as root of the client certificate chain. Vice versa applies
679 to the cacerts returned for the client. The root cert(s) can
680 either be pre-generated with pkix_test_root_cert/2 , or if
681 options are specified; it is (they are) generated.
682 When this function is called with a list of certificate options;
684 it generates a configuration with just one node certificate
685 where cacerts contains the root cert and the intermediate certs
686 that should be presented to a peer. In this case the same root
687 cert must be used for all peers. This is useful in for example
688 an Erlang distributed cluster where any node, towards another
689 node, acts either as a server or as a client depending on who
690 connects to whom. The generated certificate contains a subject
691 altname, which is not needed in a client certificate, but makes
692 the certificate useful for both roles.
693 The cert_opt() type consists of the following options:
695 {digest, digest_type()}:
697 Hash algorithm to be used for signing the certificate
698 together with the key option. Defaults to sha that is sha1.
699 {key, key_params() | private_key()}:
701 Parameters to be used to call public_key:generate_key/1, to
702 generate a key, or an existing key. Defaults to generating
703 an ECDSA key. Note this could fail if Erlang/OTP is compiled
704 with a very old cryptolib.
705 {validity, {From::erlang:timestamp(), To::erlang:time‐
707 stamp()}} :
708 The validity period of the certificate.
709 {extensions, [#'Extension'{}]}:
711 Extensions to include in the certificate.
712 Default extensions included in CA certificates if not other‐
714 wise specified are:
715 [#'Extension'{extnID = ?'id-ce-keyUsage',
717 extnValue = [keyCertSign, cRLSign],
718 critical = false},
719 #'Extension'{extnID = ?'id-ce-basicConstraints',
720 extnValue = #'BasicConstraints'{cA = true},
721 critical = true}]
722 Default extensions included in the server peer cert if not
725 otherwise specified are:
726 [#'Extension'{extnID = ?'id-ce-keyUsage',
728 extnValue = [digitalSignature, keyAgreement],
729 critical = false},
730 #'Extension'{extnID = ?'id-ce-subjectAltName',
731 extnValue = [{dNSName, Hostname}],
732 critical = false}]
733 Hostname is the result of calling net_adm:localhost() in the
736 Erlang node where this funcion is called.
737 Note:
739 Note that the generated certificates and keys does not provide a
740 formally correct PKIX-trust-chain and they can not be used to
741 achieve real security. This function is provided for testing
742 purposes only.
743 pkix_test_root_cert(Name, Options) -> RootCert
746 Types:
748 Name = string()
750 The root certificate name.
751 Options = [cert_opt()]
752 For available options see cert_opt() under
753 pkix_test_data/1.
754 RootCert = #{cert := der_encoded(), key := Key}
755 A root certificate and key. The Key is generated by gener‐
756 ate_key/1.
757 Generates a root certificate that can be used in multiple calls
759 to pkix_test_data/1 when you want the same root certificate for
760 several generated certificates.
761 pkix_verify(Cert, Key) -> boolean()
763 Types:
765 Cert = der_encoded()
767 Key = public_key()
768 Verifies PKIX x.509 certificate signature.
770 pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()
772 pkix_verify_hostname(Cert, ReferenceIDs, Opts) -> boolean()
773 Types:
775 Cert = der_encoded() | #'OTPCertificate'{}
777 ReferenceIDs = [ RefID ]
778 RefID = {dns_id,string()} | {srv_id,string()} |
779 {uri_id,string()} | {ip,inet:ip_address()|string()} | {Other‐
780 RefID,term()}}
781 OtherRefID = atom()
782 Opts = [ PvhOpt() ]
783 PvhOpt = [MatchOpt | FailCallBackOpt | FqdnExtractOpt]
784 MatchOpt = {match_fun, fun(RefId | FQDN::string(), Presente‐
785 dID) -> boolean() | default}
786 PresentedID = {dNSName,string()} | {uniformResourceIdenti‐
787 fier,string() | {iPAddress,list(byte())} | {Other‐
788 PresId,term()}}
789 OtherPresID = atom()
790 FailCallBackOpt = {fail_callback, fun(#'OTPCertificate'{}) ->
791 boolean()}
792 FqdnExtractOpt = {fqdn_fun, fun(RefID) -> FQDN::string() |
793 default | undefined}
794 This function checks that the Presented Identifier (e.g host‐
796 name) in a peer certificate is in agreement with at least one of
797 the Reference Identifier that the client expects to be con‐
798 nected to. The function is intended to be added as an extra
799 client check of the peer certificate when performing pub‐
800 lic_key:pkix_path_validation/3
801 See RFC 6125 for detailed information about hostname verifica‐
803 tion. The User's Guide and code examples describes this function
804 more detailed.
805 The {OtherRefId,term()} is defined by the user and is passed to
807 the match_fun, if defined. If the term in OtherRefId is a
808 binary, it will be converted to a string.
809 The ip Reference ID takes an inet:ip_address() or an ip address
811 in string format (E.g "10.0.1.1" or "1234::5678:9012") as second
812 element.
813 The options are:
815 match_fun:
817 The fun/2 in this option replaces the default host name
818 matching rules. The fun should return a boolean to tell if
819 the Reference ID and Presented ID matches or not. The fun
820 can also return a third value, the atom default, if the
821 default matching rules shall apply. This makes it possible
822 to augment the tests with a special case:
823 fun(....) -> true; % My special case
825 (_, _) -> default % all others falls back to the inherit tests
826 end
827 See pkix_verify_hostname_match_fun/1 for a function that takes
829 a protocol name as argument and returns a fun/2 suitable for
830 this option and Re-defining the match operation in the User's
831 Guide for an example.
832 fail_callback:
834 If a matching fails, there could be circumstances when the
835 certificate should be accepted anyway. Think for example of
836 a web browser where you choose to accept an outdated cer‐
837 tificate. This option enables implementation of such a func‐
838 tion. This fun/1 is called when no ReferenceID matches. The
839 return value of the fun (a boolean()) decides the outcome.
840 If true the the certificate is accepted otherwise it is
841 rejected. See "Pinning" a Certificate in the User's Guide.
842 fqdn_fun:
844 This option augments the host name extraction from URIs and
845 other Reference IDs. It could for example be a very special
846 URI that is not standardised. The fun takes a Reference ID
847 as argument and returns one of:
848 * the hostname
850 * the atom default: the default host name extract function
852 will be used
853 * the atom undefined: a host name could not be extracted.
855 The pkix_verify_hostname/3 will return false.
856 For an example, see Hostname extraction in the User's Guide.
858 pkix_verify_hostname_match_fun(Protcol) -> fun(RefId | FQDN::string(),
860 PresentedID) -> boolean() | default
861 Types:
863 Protocol = https
865 The algorithm for wich the fun should implement the special
866 matching rules
867 RefId
868 See pkix_verify_hostname/3.
869 FQDN
870 See pkix_verify_hostname/3.
871 PresentedID
872 See pkix_verify_hostname/3.
873 The return value of calling this function is intended to be used
875 in the match_fun option in pkix_verify_hostname/3.
876 The returned fun augments the verify hostname matching according
878 to the specific rules for the protocol in the argument.
879 sign(Msg, DigestType, Key) -> Signature
881 sign(Msg, DigestType, Key, Options) -> Signature
883 Types:
885 Msg = binary() | {digest, binary()}
887 DigestType = digest_type()
888 Key = private_key()
889 Options = crypto:pk_sign_verify_opts()
890 Signature = binary()
891 Creates a digital signature.
893 The Msg is either the binary "plain text" data to be signed or
895 it is the hashed value of "plain text", that is, the digest.
896 ssh_decode(SshBin, Type) -> Decoded
898 Types:
900 SshBin = binary()
902 Type = ssh2_pubkey | OtherType | InternalType
903 OtherType = public_key | ssh_file()
904 InternalType = new_openssh
905 Decoded = Decoded_ssh2_pubkey | Decoded_OtherType
906 Decoded_ssh2_pubkey = public_key()
907 Decoded_OtherType = [{public_key(), Attributes}]
908 Attributes = [{atom(), term()}]
909 Decodes an SSH file-binary. In the case of known_hosts or
911 auth_keys, the binary can include one or more lines of the file.
912 Returns a list of public keys and their attributes, possible
913 attribute values depends on the file type represented by the
914 binary.
915 If the Type is ssh2_pubkey, the result will be Decoded_ssh2_pub‐
917 key. Otherwise it will be Decoded_OtherType.
918 RFC4716 attributes - see RFC 4716.:
920 {headers, [{string(), utf8_string()}]}
921 auth_key attributes - see manual page for sshd.:
923 {comment, string()}{options, [string()]}{bits, integer()} -
924 In SSH version 1 files.
925 known_host attributes - see manual page for sshd.:
927 {hostnames, [string()]}{comment, string()}{bits, integer()}
928 - In SSH version 1 files.
929 Example: {ok, SshBin} = file:read_file("known_hosts").
931 If Type is public_key the binary can be either an RFC4716 public
933 key or an OpenSSH public key.
934 ssh_encode(InData, Type) -> binary()
936 Types:
938 Type = ssh2_pubkey | OtherType
940 OtherType = public_key | ssh_file()
941 InData = InData_ssh2_pubkey | OtherInData
942 InData_ssh2_pubkey = public_key()
943 OtherInData = [{Key, Attributes}]
944 Key = public_key()
945 Attributes = [{atom(), term()}]
946 Encodes a list of SSH file entries (public keys and attributes)
948 to a binary. Possible attributes depend on the file type, see
949 ssh_decode/2 .
950 If the Type is ssh2_pubkey, the InData shall be InData_ssh2_pub‐
952 key. Otherwise it shall be OtherInData.
953 ssh_hostkey_fingerprint(HostKey) -> string()
955 ssh_hostkey_fingerprint(DigestType, HostKey) -> string()
956 ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]
957 Types:
959 HostKey = public_key()
961 DigestType = digest_type()
962 Calculates a ssh fingerprint from a public host key as openssh
964 does.
965 The algorithm in ssh_hostkey_fingerprint/1 is md5 to be compati‐
967 ble with older ssh-keygen commands. The string from the second
968 variant is prepended by the algorithm name in uppercase as in
969 newer ssh-keygen commands.
970 Examples:
972 2> public_key:ssh_hostkey_fingerprint(Key).
974 "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
975 3> public_key:ssh_hostkey_fingerprint(md5,Key).
977 "MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
978 4> public_key:ssh_hostkey_fingerprint(sha,Key).
980 "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
981 5> public_key:ssh_hostkey_fingerprint(sha256,Key).
983 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
984 6> public_key:ssh_hostkey_fingerprint([sha,sha256],Key).
986 ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
987 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
988 verify(Msg, DigestType, Signature, Key) -> boolean()
991 verify(Msg, DigestType, Signature, Key, Options) -> boolean()
993 Types:
995 Msg = binary() | {digest, binary()}
997 DigestType = digest_type()
998 Signature = binary()
999 Key = public_key()
1000 Options = crypto:pk_sign_verify_opts()
1001 Verifies a digital signature.
1003 The Msg is either the binary "plain text" data or it is the
1005 hashed value of "plain text", that is, the digest.
1006 short_name_hash(Name) -> string()
1008 Types:
1010 Name = issuer_name()
1012 Generates a short hash of an issuer name. The hash is returned
1014 as a string containing eight hexadecimal digits.
1015 The return value of this function is the same as the result of
1017 the commands openssl crl -hash and openssl x509 -issuer_hash,
1018 when passed the issuer name of a CRL or a certificate, respec‐
1019 tively. This hash is used by the c_rehash tool to maintain a
1020 directory of symlinks to CRL files, in order to facilitate look‐
1021 ing up a CRL by its issuer name.
1022Ericsson AB public_key 1.6.6 public_key(3)