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 rsa_pss_public_key() |
69 dsa_public_key() |
70 ec_public_key() |
71 ed_public_key()
72 rsa_public_key() = #'RSAPublicKey'{}
74 rsa_pss_public_key() =
76 {#'RSAPublicKey'{}, #'RSASSA-PSS-params'{}}
77 dsa_public_key() = {integer(), #'Dss-Parms'{}}
79 ec_public_key() = {#'ECPoint'{}, ecpk_parameters_api()}
81 ecpk_parameters() =
83 {ecParameters, #'ECParameters'{}} |
84 {namedCurve, Oid :: tuple()}
85 ecpk_parameters_api() =
87 ecpk_parameters() |
88 #'ECParameters'{} |
89 {namedCurve, Name :: crypto:ec_named_curve()}
90 ed_public_key() = {ed_pub, ed25519 | ed448, Key :: binary()}
92 Warning:
94 This format of the EdDSA curves is temporary and may change
95 without prior notice!
96 private_key() =
99 rsa_private_key() |
100 rsa_pss_private_key() |
101 dsa_private_key() |
102 ec_private_key() |
103 ed_private_key()
104 rsa_private_key() = #'RSAPrivateKey'{}
106 rsa_pss_private_key() =
108 {#'RSAPrivateKey'{}, #'RSASSA-PSS-params'{}}
109 dsa_private_key() = #'DSAPrivateKey'{}
111 ec_private_key() = #'ECPrivateKey'{}
113 ed_private_key() =
115 {ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()}
116 Warning:
118 This format of the EdDSA curves is temporary and may change
119 without prior notice!
120 key_params() =
123 #'DHParameter'{} |
124 {namedCurve, oid()} |
125 #'ECParameters'{} |
126 {rsa, Size :: integer(), PubExp :: integer()}
127 digest_type() =
129 none | sha1 |
130 crypto:rsa_digest_type() |
131 crypto:dss_digest_type() |
132 crypto:ecdsa_digest_type()
133 crl_reason() =
135 unspecified | keyCompromise | cACompromise |
136 affiliationChanged | superseded | cessationOfOperation |
137 certificateHold | privilegeWithdrawn | aACompromise
138 cert_id() = {SerialNr :: integer(), issuer_name()}
140 issuer_name() = {rdnSequence, [#'AttributeTypeAndValue'{}]}
142 ssh_file() =
144 openssh_public_key | rfc4716_public_key | known_hosts |
145 auth_keys
146
148 compute_key(OthersECDHkey, MyECDHkey) -> SharedSecret
149 Types:
151 OthersECDHkey = #'ECPoint'{}
153 MyECDHkey = #'ECPrivateKey'{}
154 SharedSecret = binary()
155 Computes shared secret.
157 compute_key(OthersDHkey, MyDHkey, DHparms) -> SharedSecret
159 Types:
161 OthersDHkey = crypto:dh_public()
163 MyDHkey = crypto:dh_private()
164 DHparms = #'DHParameter'{}
165 SharedSecret = binary()
166 Computes shared secret.
168 decrypt_private(CipherText, Key) -> PlainText
170 decrypt_private(CipherText, Key, Options) -> PlainText
172 Types:
174 CipherText = binary()
176 Key = rsa_private_key()
177 Options = crypto:pk_encrypt_decrypt_opts()
178 PlainText = binary()
179 Public-key decryption using the private key. See also
181 crypto:private_decrypt/4
182 decrypt_public(CipherText, Key) -> PlainText
184 decrypt_public(CipherText, Key, Options) -> PlainText
186 Types:
188 CipherText = binary()
190 Key = rsa_public_key()
191 Options = crypto:pk_encrypt_decrypt_opts()
192 PlainText = binary()
193 Public-key decryption using the public key. See also crypto:pub‐
195 lic_decrypt/4
196 der_decode(Asn1Type, Der) -> Entity
198 Types:
200 Asn1Type = asn1_type()
202 Der = binary()
203 Entity = term()
204 Decodes a public-key ASN.1 DER encoded entity.
206 der_encode(Asn1Type, Entity) -> Der
208 Types:
210 Asn1Type = asn1_type()
212 Entity = term()
213 Der = binary()
214 Encodes a public-key entity with ASN.1 DER encoding.
216 dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) ->
218 {ok, {Size, Group}} | {error, term()}
219 Types:
221 MinSize = SuggestedSize = MaxSize = integer() >= 1
223 Groups = undefined | [{Size, [Group]}]
224 Size = integer() >= 1
225 Group = {G, P}
226 G = P = integer() >= 1
227 Selects a group for Diffie-Hellman key exchange with the key
229 size in the range MinSize...MaxSize and as close to Suggested‐
230 Size as possible. If Groups == undefined a default set will be
231 used, otherwise the group is selected from Groups.
232 First a size, as close as possible to SuggestedSize, is
234 selected. Then one group with that key size is randomly selected
235 from the specified set of groups. If no size within the limits
236 of MinSize and MaxSize is available, {error,no_group_found} is
237 returned.
238 The default set of groups is listed in lib/public_key/priv/mod‐
240 uli. This file may be regenerated like this:
241 $> cd $ERL_TOP/lib/public_key/priv/
243 $> generate
244 ---- wait until all background jobs has finished. It may take several days !
245 $> cat moduli-* > moduli
246 $> cd ..; make
247 encrypt_private(PlainText, Key) -> CipherText
250 encrypt_private(PlainText, Key, Options) -> CipherText
252 Types:
254 PlainText = binary()
256 Key = rsa_private_key()
257 Options = crypto:pk_encrypt_decrypt_opts()
258 CipherText = binary()
259 Public-key encryption using the private key. See also
261 crypto:private_encrypt/4.
262 encrypt_public(PlainText, Key) -> CipherText
264 encrypt_public(PlainText, Key, Options) -> CipherText
266 Types:
268 PlainText = binary()
270 Key = rsa_public_key()
271 Options = crypto:pk_encrypt_decrypt_opts()
272 CipherText = binary()
273 Public-key encryption using the public key. See also crypto:pub‐
275 lic_encrypt/4.
276 generate_key(Params :: DHparams | ECparams | RSAparams) ->
278 DHkeys | ECkey | RSAkey
279 Types:
281 DHparams = #'DHParameter'{}
283 DHkeys = {PublicDH :: binary(), PrivateDH :: binary()}
284 ECparams = ecpk_parameters_api()
285 ECkey = #'ECPrivateKey'{}
286 RSAparams = {rsa, Size, PubExp}
287 Size = PubExp = integer() >= 1
288 RSAkey = #'RSAPrivateKey'{}
289 Generates a new keypair. Note that except for Diffie-Hellman the
291 public key is included in the private key structure. See also
292 crypto:generate_key/2
293 pem_decode(PemBin :: binary()) -> [pem_entry()]
295 Decodes PEM binary data and returns entries as ASN.1 DER encoded
297 entities.
298 Example {ok, PemBin} = file:read_file("cert.pem"). PemEntries =
300 public_key:pem_decode(PemBin).
301 pem_encode(PemEntries :: [pem_entry()]) -> binary()
303 Creates a PEM binary.
305 pem_entry_decode(PemEntry) -> term()
307 pem_entry_decode(PemEntry, Password) -> term()
309 Types:
311 PemEntry = pem_entry()
313 Password = string()
314 Decodes a PEM entry. pem_decode/1 returns a list of PEM entries.
316 Notice that if the PEM entry is of type 'SubjectPublickeyInfo',
317 it is further decoded to an rsa_public_key() or dsa_pub‐
318 lic_key().
319 pem_entry_encode(Asn1Type, Entity) -> pem_entry()
321 pem_entry_encode(Asn1Type, Entity, InfoPwd) -> pem_entry()
323 Types:
325 Asn1Type = pki_asn1_type()
327 Entity = term()
328 InfoPwd = {CipherInfo, Password}
329 CipherInfo = cipher_info()
330 Password = string()
331 Creates a PEM entry that can be feed to pem_encode/1.
333 If Asn1Type is 'SubjectPublicKeyInfo', Entity must be either an
335 rsa_public_key(), dsa_public_key() or an ec_public_key() and
336 this function creates the appropriate 'SubjectPublicKeyInfo'
337 entry.
338 pkix_decode_cert(Cert, Type) ->
340 #'Certificate'{} | #'OTPCertificate'{}
341 Types:
343 Cert = der_encoded()
345 Type = plain | otp
346 Decodes an ASN.1 DER-encoded PKIX certificate. Option otp uses
348 the customized ASN.1 specification OTP-PKIX.asn1 for decoding
349 and also recursively decode most of the standard parts.
350 pkix_encode(Asn1Type, Entity, Type) -> Der
352 Types:
354 Asn1Type = asn1_type()
356 Entity = term()
357 Type = otp | plain
358 Der = der_encoded()
359 DER encodes a PKIX x509 certificate or part of such a certifi‐
361 cate. This function must be used for encoding certificates or
362 parts of certificates that are decoded/created in the otp for‐
363 mat, whereas for the plain format this function directly calls
364 der_encode/2.
365 pkix_is_issuer(Cert, IssuerCert) -> boolean()
367 Types:
369 Cert =
371 der_encoded() | #'OTPCertificate'{} | #'Certifi‐
372 cateList'{}
373 IssuerCert = der_encoded() | #'OTPCertificate'{}
374 Checks if IssuerCert issued Cert.
376 pkix_is_fixed_dh_cert(Cert) -> boolean()
378 Types:
380 Cert = der_encoded() | #'OTPCertificate'{}
382 Checks if a certificate is a fixed Diffie-Hellman certificate.
384 pkix_is_self_signed(Cert) -> boolean()
386 Types:
388 Cert = der_encoded() | #'OTPCertificate'{}
390 Checks if a certificate is self-signed.
392 pkix_issuer_id(Cert, IssuedBy) ->
394 {ok, ID :: cert_id()} | {error, Reason}
395 Types:
397 Cert = der_encoded() | #'OTPCertificate'{}
399 IssuedBy = self | other
400 Reason = term()
401 Returns the x509 certificater issuer id, if it can be deter‐
403 mined.
404 pkix_normalize_name(Issuer) -> Normalized
406 Types:
408 Issuer = Normalized = issuer_name()
410 Normalizes an issuer name so that it can be easily compared to
412 another issuer name.
413 pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicK‐
415 eyInfo, PolicyTree}} | {error, {bad_cert, Reason}}
416 Types:
418 TrustedCert = #'OTPCertificate'{} | der_encoded() | atom()
420 Normally a trusted certificate, but it can also be a path-
421 validation error that can be discovered while constructing
422 the input to this function and that is to be run through
423 the verify_fun. Examples are unknown_ca and self‐
424 signed_peer.
425 CertChain = [der_encoded()]
426 A list of DER-encoded certificates in trust order ending
427 with the peer certificate.
428 Options = proplists:proplist()
429 PublicKeyInfo = {?'rsaEncryption' | ?'id-RSASSA-PSS'| ?'id-
430 dsa', rsa_public_key() | integer(), 'NULL' | 'RSASSA-PSS-
431 params'{} | 'Dss-Parms'{}}
432 PolicyTree = term()
433 At the moment this is always an empty list as policies are
434 not currently supported.
435 Reason = cert_expired | invalid_issuer | invalid_signature |
436 name_not_permitted | missing_basic_constraint |
437 invalid_key_usage | {revoked, crl_reason()} | atom()
438 Performs a basic path validation according to RFC 5280. However,
440 CRL validation is done separately by pkix_crls_validate/3 and
441 is to be called from the supplied verify_fun.
442 Available options:
444 {verify_fun, {fun(), InitialUserState::term()}:
446 The fun must be defined as:
447 fun(OtpCert :: #'OTPCertificate'{},
449 Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
450 {extension, #'Extension'{}},
451 InitialUserState :: term()) ->
452 {valid, UserState :: term()} |
453 {valid_peer, UserState :: term()} |
454 {fail, Reason :: term()} |
455 {unknown, UserState :: term()}.
456 If the verify callback fun returns {fail, Reason}, the veri‐
459 fication process is immediately stopped. If the verify call‐
460 back fun returns {valid, UserState}, the verification
461 process is continued. This can be used to accept specific
462 path validation errors, such as selfsigned_peer, as well as
463 verifying application-specific extensions. If called with an
464 extension unknown to the user application, the return value
465 {unknown, UserState} is to be used.
466 Warning:
468 Note that user defined custom verify_fun may alter original
469 path validation error (e.g selfsigned_peer). Use with caution.
470 {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 cannot 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_hash_type(HashOid :: oid()) ->
604 DigestType ::
605 md5 | crypto:sha1() | crypto:sha2()
606 Translates OID to Erlang digest type
608 pkix_match_dist_point(CRL, DistPoint) -> boolean()
610 Types:
612 CRL = der_encoded() | #'CertificateList'{}
614 DistPoint = #'DistributionPoint'{}
615 Checks whether the given distribution point matches the Issuing
617 Distribution Point of the CRL, as described in RFC 5280. If the
618 CRL doesn't have an Issuing Distribution Point extension, the
619 distribution point always matches.
620 pkix_sign(Cert, Key) -> Der
622 Types:
624 Cert = #'OTPTBSCertificate'{}
626 Key = private_key()
627 Der = der_encoded()
628 Signs an 'OTPTBSCertificate'. Returns the corresponding DER-
630 encoded certificate.
631 pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}
633 Types:
635 AlgorithmId = oid()
637 DigestType = crypto:rsa_digest_type()
638 SignatureType = rsa | dsa | ecdsa
639 Translates signature algorithm OID to Erlang digest and signa‐
641 ture types.
642 The AlgorithmId is the signature OID from a certificate or a
644 certificate revocation list.
645 pkix_test_data(Options) -> Config
647 pkix_test_data([chain_opts()]) -> [conf_opt()]
648 Types:
650 Options = #{chain_type() := chain_opts()}
652 Options for ROOT, Intermediate and Peer certs
653 chain_type() = server_chain | client_chain
654 chain_opts() = #{root := [cert_opt()] | root_cert(), peer :=
655 [cert_opt()], intermediates => [[cert_opt()]]}
656 A valid chain must have at least a ROOT and a peer cert.
657 The root cert can be given either as a cert pre-generated
658 by pkix_test_root_cert/2 , or as root cert generation
659 options.
660 root_cert() = #{cert := der_encoded(), key := Key}
661 A root certificate generated by pkix_test_root_cert/2 .
662 cert_opt() = {Key, Value}
663 For available options see cert_opt() below.
664 Config = #{server_config := [conf_opt()], client_config :=
665 [conf_opt()]}
666 conf_opt() = {cert, der_encoded()} | {key, PrivateKey} |{cac‐
667 erts, [der_encoded()]}
668 This is a subset of the type ssl:tls_option(). PrivateKey
669 is what generate_key/1 returns.
670 Creates certificate configuration(s) consisting of certificate
672 and its private key plus CA certificate bundle, for a client and
673 a server, intended to facilitate automated testing of applica‐
674 tions using X509-certificates, often through SSL/TLS. The test
675 data can be used when you have control over both the client and
676 the server in a test scenario.
677 When this function is called with a map containing client and
679 server chain specifications; it generates both a client and a
680 server certificate chain where the cacerts returned for the
681 server contains the root cert the server should trust and the
682 intermediate certificates the server should present to connect‐
683 ing clients. The root cert the server should trust is the one
684 used as root of the client certificate chain. Vice versa applies
685 to the cacerts returned for the client. The root cert(s) can
686 either be pre-generated with pkix_test_root_cert/2 , or if
687 options are specified; it is (they are) generated.
688 When this function is called with a list of certificate options;
690 it generates a configuration with just one node certificate
691 where cacerts contains the root cert and the intermediate certs
692 that should be presented to a peer. In this case the same root
693 cert must be used for all peers. This is useful in for example
694 an Erlang distributed cluster where any node, towards another
695 node, acts either as a server or as a client depending on who
696 connects to whom. The generated certificate contains a subject
697 altname, which is not needed in a client certificate, but makes
698 the certificate useful for both roles.
699 The cert_opt() type consists of the following options:
701 {digest, digest_type()}:
703 Hash algorithm to be used for signing the certificate
704 together with the key option. Defaults to sha that is sha1.
705 {key, key_params() | private_key()}:
707 Parameters to be used to call public_key:generate_key/1, to
708 generate a key, or an existing key. Defaults to generating
709 an ECDSA key. Note this could fail if Erlang/OTP is compiled
710 with a very old cryptolib.
711 {validity, {From::erlang:timestamp(), To::erlang:time‐
713 stamp()}} :
714 The validity period of the certificate.
715 {extensions, [#'Extension'{}]}:
717 Extensions to include in the certificate.
718 Default extensions included in CA certificates if not other‐
720 wise specified are:
721 [#'Extension'{extnID = ?'id-ce-keyUsage',
723 extnValue = [keyCertSign, cRLSign],
724 critical = false},
725 #'Extension'{extnID = ?'id-ce-basicConstraints',
726 extnValue = #'BasicConstraints'{cA = true},
727 critical = true}]
728 Default extensions included in the server peer cert if not
731 otherwise specified are:
732 [#'Extension'{extnID = ?'id-ce-keyUsage',
734 extnValue = [digitalSignature, keyAgreement],
735 critical = false},
736 #'Extension'{extnID = ?'id-ce-subjectAltName',
737 extnValue = [{dNSName, Hostname}],
738 critical = false}]
739 Hostname is the result of calling net_adm:localhost() in the
742 Erlang node where this funcion is called.
743 Note:
745 Note that the generated certificates and keys does not provide a
746 formally correct PKIX-trust-chain and they cannot be used to
747 achieve real security. This function is provided for testing
748 purposes only.
749 pkix_test_root_cert(Name, Options) -> RootCert
752 Types:
754 Name = string()
756 The root certificate name.
757 Options = [cert_opt()]
758 For available options see cert_opt() under
759 pkix_test_data/1.
760 RootCert = #{cert := der_encoded(), key := Key}
761 A root certificate and key. The Key is generated by gener‐
762 ate_key/1.
763 Generates a root certificate that can be used in multiple calls
765 to pkix_test_data/1 when you want the same root certificate for
766 several generated certificates.
767 pkix_subject_id(Cert) -> ID
769 Types:
771 Cert = der_encoded() | #'OTPCertificate'{}
773 ID = cert_id()
774 Returns the X509 certificate subject id.
776 pkix_verify(Cert, Key) -> boolean()
778 Types:
780 Cert = der_encoded()
782 Key = public_key()
783 Verifies PKIX x.509 certificate signature.
785 pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()
787 pkix_verify_hostname(Cert, ReferenceIDs, Opts) -> boolean()
788 Types:
790 Cert = der_encoded() | #'OTPCertificate'{}
792 ReferenceIDs = [ RefID ]
793 RefID = {dns_id,string()} | {srv_id,string()} |
794 {uri_id,string()} | {ip,inet:ip_address()|string()} | {Other‐
795 RefID,term()}}
796 OtherRefID = atom()
797 Opts = [ PvhOpt() ]
798 PvhOpt = [MatchOpt | FailCallBackOpt | FqdnExtractOpt]
799 MatchOpt = {match_fun, fun(RefId | FQDN::string(), Presente‐
800 dID) -> boolean() | default}
801 PresentedID = {dNSName,string()} | {uniformResourceIdenti‐
802 fier,string() | {iPAddress,list(byte())} | {Other‐
803 PresId,term()}}
804 OtherPresID = atom()
805 FailCallBackOpt = {fail_callback, fun(#'OTPCertificate'{}) ->
806 boolean()}
807 FqdnExtractOpt = {fqdn_fun, fun(RefID) -> FQDN::string() |
808 default | undefined}
809 This function checks that the Presented Identifier (e.g host‐
811 name) in a peer certificate is in agreement with at least one of
812 the Reference Identifier that the client expects to be con‐
813 nected to. The function is intended to be added as an extra
814 client check of the peer certificate when performing pub‐
815 lic_key:pkix_path_validation/3
816 See RFC 6125 for detailed information about hostname verifica‐
818 tion. The User's Guide and code examples describes this function
819 more detailed.
820 The {OtherRefId,term()} is defined by the user and is passed to
822 the match_fun, if defined. If the term in OtherRefId is a
823 binary, it will be converted to a string.
824 The ip Reference ID takes an inet:ip_address() or an ip address
826 in string format (E.g "10.0.1.1" or "1234::5678:9012") as second
827 element.
828 The options are:
830 match_fun:
832 The fun/2 in this option replaces the default host name
833 matching rules. The fun should return a boolean to tell if
834 the Reference ID and Presented ID matches or not. The fun
835 can also return a third value, the atom default, if the
836 default matching rules shall apply. This makes it possible
837 to augment the tests with a special case:
838 fun(....) -> true; % My special case
840 (_, _) -> default % all others falls back to the inherit tests
841 end
842 See pkix_verify_hostname_match_fun/1 for a function that takes
844 a protocol name as argument and returns a fun/2 suitable for
845 this option and Re-defining the match operation in the User's
846 Guide for an example.
847 fail_callback:
849 If a matching fails, there could be circumstances when the
850 certificate should be accepted anyway. Think for example of
851 a web browser where you choose to accept an outdated cer‐
852 tificate. This option enables implementation of such a func‐
853 tion. This fun/1 is called when no ReferenceID matches. The
854 return value of the fun (a boolean()) decides the outcome.
855 If true the the certificate is accepted otherwise it is
856 rejected. See "Pinning" a Certificate in the User's Guide.
857 fqdn_fun:
859 This option augments the host name extraction from URIs and
860 other Reference IDs. It could for example be a very special
861 URI that is not standardised. The fun takes a Reference ID
862 as argument and returns one of:
863 * the hostname
865 * the atom default: the default host name extract function
867 will be used
868 * the atom undefined: a host name could not be extracted.
870 The pkix_verify_hostname/3 will return false.
871 For an example, see Hostname extraction in the User's Guide.
873 pkix_verify_hostname_match_fun(Protcol) -> fun(RefId | FQDN::string(),
875 PresentedID) -> boolean() | default
876 Types:
878 Protocol = https
880 The algorithm for wich the fun should implement the special
881 matching rules
882 RefId
883 See pkix_verify_hostname/3.
884 FQDN
885 See pkix_verify_hostname/3.
886 PresentedID
887 See pkix_verify_hostname/3.
888 The return value of calling this function is intended to be used
890 in the match_fun option in pkix_verify_hostname/3.
891 The returned fun augments the verify hostname matching according
893 to the specific rules for the protocol in the argument.
894 sign(Msg, DigestType, Key) -> Signature
896 sign(Msg, DigestType, Key, Options) -> Signature
898 Types:
900 Msg = binary() | {digest, binary()}
902 DigestType = digest_type()
903 Key = private_key()
904 Options = crypto:pk_sign_verify_opts()
905 Signature = binary()
906 Creates a digital signature.
908 The Msg is either the binary "plain text" data to be signed or
910 it is the hashed value of "plain text", that is, the digest.
911 ssh_decode(SshBin, Type) -> Decoded
913 Types:
915 SshBin = binary()
917 Type = ssh2_pubkey | OtherType | InternalType
918 OtherType = public_key | ssh_file()
919 InternalType = new_openssh
920 Decoded = Decoded_ssh2_pubkey | Decoded_OtherType
921 Decoded_ssh2_pubkey = public_key()
922 Decoded_OtherType = [{public_key(), Attributes}]
923 Attributes = [{atom(), term()}]
924 Decodes an SSH file-binary. In the case of known_hosts or
926 auth_keys, the binary can include one or more lines of the file.
927 Returns a list of public keys and their attributes, possible
928 attribute values depends on the file type represented by the
929 binary.
930 If the Type is ssh2_pubkey, the result will be Decoded_ssh2_pub‐
932 key. Otherwise it will be Decoded_OtherType.
933 RFC4716 attributes - see RFC 4716.:
935 {headers, [{string(), utf8_string()}]}
936 auth_key attributes - see manual page for sshd.:
938 {comment, string()}{options, [string()]}{bits, integer()} -
939 In SSH version 1 files.
940 known_host attributes - see manual page for sshd.:
942 {hostnames, [string()]}{comment, string()}{bits, integer()}
943 - In SSH version 1 files.
944 Example: {ok, SshBin} = file:read_file("known_hosts").
946 If Type is public_key the binary can be either an RFC4716 public
948 key or an OpenSSH public key.
949 ssh_encode(InData, Type) -> binary()
951 Types:
953 Type = ssh2_pubkey | OtherType
955 OtherType = public_key | ssh_file()
956 InData = InData_ssh2_pubkey | OtherInData
957 InData_ssh2_pubkey = public_key()
958 OtherInData = [{Key, Attributes}]
959 Key = public_key()
960 Attributes = [{atom(), term()}]
961 Encodes a list of SSH file entries (public keys and attributes)
963 to a binary. Possible attributes depend on the file type, see
964 ssh_decode/2 .
965 If the Type is ssh2_pubkey, the InData shall be InData_ssh2_pub‐
967 key. Otherwise it shall be OtherInData.
968 ssh_hostkey_fingerprint(HostKey) -> string()
970 ssh_hostkey_fingerprint(DigestType, HostKey) -> string()
971 ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]
972 Types:
974 HostKey = public_key()
976 DigestType = digest_type()
977 Calculates a ssh fingerprint from a public host key as openssh
979 does.
980 The algorithm in ssh_hostkey_fingerprint/1 is md5 to be compati‐
982 ble with older ssh-keygen commands. The string from the second
983 variant is prepended by the algorithm name in uppercase as in
984 newer ssh-keygen commands.
985 Examples:
987 2> public_key:ssh_hostkey_fingerprint(Key).
989 "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
990 3> public_key:ssh_hostkey_fingerprint(md5,Key).
992 "MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
993 4> public_key:ssh_hostkey_fingerprint(sha,Key).
995 "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
996 5> public_key:ssh_hostkey_fingerprint(sha256,Key).
998 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
999 6> public_key:ssh_hostkey_fingerprint([sha,sha256],Key).
1001 ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
1002 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
1003 verify(Msg, DigestType, Signature, Key) -> boolean()
1006 verify(Msg, DigestType, Signature, Key, Options) -> boolean()
1008 Types:
1010 Msg = binary() | {digest, binary()}
1012 DigestType = digest_type()
1013 Signature = binary()
1014 Key = public_key()
1015 Options = crypto:pk_sign_verify_opts()
1016 Verifies a digital signature.
1018 The Msg is either the binary "plain text" data or it is the
1020 hashed value of "plain text", that is, the digest.
1021 short_name_hash(Name) -> string()
1023 Types:
1025 Name = issuer_name()
1027 Generates a short hash of an issuer name. The hash is returned
1029 as a string containing eight hexadecimal digits.
1030 The return value of this function is the same as the result of
1032 the commands openssl crl -hash and openssl x509 -issuer_hash,
1033 when passed the issuer name of a CRL or a certificate, respec‐
1034 tively. This hash is used by the c_rehash tool to maintain a
1035 directory of symlinks to CRL files, in order to facilitate look‐
1036 ing up a CRL by its issuer name.
1037Ericsson AB public_key 1.10 public_key(3)