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 key_oid_name() =
31 rsaEncryption | 'id-RSASSA-PSS' | 'id-ecPublicKey' |
32 'id-Ed25519' | 'id-Ed448' | 'id-dsa'
33 Macro names for key object identifiers used by prefixing with ?
35 der_encoded() = binary()
37 pki_asn1_type() =
39 'Certificate' | 'RSAPrivateKey' | 'RSAPublicKey' |
40 'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' |
41 'SubjectPublicKeyInfo' | 'PrivateKeyInfo' |
42 'CertificationRequest' | 'CertificateList' | 'ECPrivateKey' |
43 'EcpkParameters'
44 asn1_type() = atom()
46 ASN.1 type present in the Public Key applications ASN.1 specifi‐
48 cations.
49 pem_entry() =
51 {pki_asn1_type(),
52 der_or_encrypted_der(),
53 not_encrypted | cipher_info()}
54 der_or_encrypted_der() = binary()
56 cipher_info() = {cipher(), cipher_info_params()}
58 cipher() = string()
60 salt() = binary()
62 cipher_info_params() =
64 salt() |
65 {#'PBEParameter'{}, digest_type()} |
66 #'PBES2-params'{}
67 Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC"
69 Salt could be generated with crypto:strong_rand_bytes(8).
71 public_key() =
73 rsa_public_key() |
74 rsa_pss_public_key() |
75 dsa_public_key() |
76 ec_public_key() |
77 ed_public_key()
78 rsa_public_key() = #'RSAPublicKey'{}
80 dss_public_key() = integer()
82 rsa_pss_public_key() =
84 {rsa_pss_public_key(), #'RSASSA-PSS-params'{}}
85 dsa_public_key() = {dss_public_key(), #'Dss-Parms'{}}
87 ec_public_key() = {#'ECPoint'{}, ecpk_parameters_api()}
89 public_key_params() =
91 'NULL' |
92 #'RSASSA-PSS-params'{} |
93 {namedCurve, oid()} |
94 #'ECParameters'{} |
95 #'Dss-Parms'{}
96 ecpk_parameters() =
98 {ecParameters, #'ECParameters'{}} |
99 {namedCurve, Oid :: tuple()}
100 ecpk_parameters_api() =
102 ecpk_parameters() |
103 #'ECParameters'{} |
104 {namedCurve, Name :: crypto:ec_named_curve()}
105 public_key_info() =
107 {key_oid_name(),
108 rsa_public_key() | #'ECPoint'{} | dss_public_key(),
109 public_key_params()}
110 ed_public_key() = {#'ECPoint'{}, ed_params()}
112 ed_legacy_pubkey() = {ed_pub, ed25519 | ed448, Key :: binary()}
114 Warning:
116 The tagged ed_pub format will not be returned from any pub‐
117 lic_key functions but can be used as input, should be considered
118 deprecated.
119 ed_params() = {namedCurve, ed_oid_name()}
122 private_key() =
124 rsa_private_key() |
125 rsa_pss_private_key() |
126 dsa_private_key() |
127 ec_private_key() |
128 ed_private_key()
129 rsa_private_key() = #'RSAPrivateKey'{}
131 rsa_pss_private_key() =
133 {#'RSAPrivateKey'{}, #'RSASSA-PSS-params'{}}
134 dsa_private_key() = #'DSAPrivateKey'{}
136 ec_private_key() = #'ECPrivateKey'{}
138 ed_private_key() = #'ECPrivateKey'{parameters = ed_params()}
140 ed_legacy_privkey() =
142 {ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()}
143 Warning:
145 The tagged ed_pri format will not be returned from any pub‐
146 lic_key functions but can be used as input, should be considered
147 deprecated.
148 ed_oid_name() = 'id-Ed25519' | 'id-Ed448'
151 Macro names for object identifiers for EDDSA curves used by pre‐
153 fixing with ?
154 key_params() =
156 #'DHParameter'{} |
157 {namedCurve, oid()} |
158 #'ECParameters'{} |
159 {rsa, Size :: integer(), PubExp :: integer()}
160 digest_type() =
162 none | sha1 |
163 crypto:rsa_digest_type() |
164 crypto:dss_digest_type() |
165 crypto:ecdsa_digest_type()
166 issuer_name() = {rdnSequence, [[#'AttributeTypeAndValue'{}]]}
168 referenceIDs() = [referenceID()]
170 referenceID() =
172 {uri_id | dns_id | ip | srv_id | atom() | oid(), string()} |
173 {ip, inet:ip_address() | string()}
174 cert_id() = {SerialNr :: integer(), issuer_name()}
176 cert() = der_cert() | otp_cert()
178 otp_cert() = #'OTPCertificate'{}
180 der_cert() = der_encoded()
182 combined_cert() =
184 #cert{der = public_key:der_encoded(),
185 otp = #'OTPCertificate'{}}
186 bad_cert_reason() =
188 cert_expired | invalid_issuer | invalid_signature |
189 name_not_permitted | missing_basic_constraint |
190 invalid_key_usage |
191 {revoked, crl_reason()} |
192 atom()
193 crl_reason() =
195 unspecified | keyCompromise | cACompromise |
196 affiliationChanged | superseded | cessationOfOperation |
197 certificateHold | privilegeWithdrawn | aACompromise
198 chain_opts() =
200 #{chain_end() := [cert_opt()],
201 intermediates => [[cert_opt()]]}
202 chain_end() = root | peer
204 cert_opt() =
206 {digest, public_key:digest_type()} |
207 {key, public_key:key_params() | public_key:private_key()} |
208 {validity,
209 {From :: erlang:timestamp(), To :: erlang:timestamp()}} |
210 {extensions, [#'Extension'{}]}
211 test_root_cert() =
213 #{cert := der_encoded(), key := public_key:private_key()}
214 test_config() =
216 #{server_config := [conf_opt()],
217 client_config := [conf_opt()]}
218 conf_opt() =
220 {cert, public_key:der_encoded()} |
221 {key, public_key:private_key()} |
222 {cacerts, [public_key:der_encoded()]}
223 ssh_file() =
225 openssh_public_key | rfc4716_public_key | known_hosts |
226 auth_keys
227
229 compute_key(OthersECDHkey, MyECDHkey) -> SharedSecret
230 Types:
232 OthersECDHkey = #'ECPoint'{}
234 MyECDHkey = #'ECPrivateKey'{}
235 SharedSecret = binary()
236 Computes shared secret.
238 compute_key(OthersDHkey, MyDHkey, DHparms) -> SharedSecret
240 Types:
242 OthersDHkey = crypto:dh_public()
244 MyDHkey = crypto:dh_private()
245 DHparms = #'DHParameter'{}
246 SharedSecret = binary()
247 Computes shared secret.
249 decrypt_private(CipherText, Key) -> PlainText
251 decrypt_private(CipherText, Key, Options) -> PlainText
253 Types:
255 CipherText = binary()
257 Key = rsa_private_key()
258 Options = crypto:pk_encrypt_decrypt_opts()
259 PlainText = binary()
260 Public-key decryption using the private key. See also
262 crypto:private_decrypt/4
263 decrypt_public(CipherText, Key) -> PlainText
265 decrypt_public(CipherText, Key, Options) -> PlainText
267 Types:
269 CipherText = binary()
271 Key = rsa_public_key()
272 Options = crypto:pk_encrypt_decrypt_opts()
273 PlainText = binary()
274 Public-key decryption using the public key. See also crypto:pub‐
276 lic_decrypt/4
277 der_decode(Asn1Type, Der) -> Entity
279 Types:
281 Asn1Type = asn1_type()
283 Der = der_encoded()
284 Entity = term()
285 Decodes a public-key ASN.1 DER encoded entity.
287 der_encode(Asn1Type, Entity) -> Der
289 Types:
291 Asn1Type = asn1_type()
293 Entity = term()
294 Der = binary()
295 Encodes a public-key entity with ASN.1 DER encoding.
297 dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) ->
299 {ok, {Size, Group}} | {error, term()}
300 Types:
302 MinSize = SuggestedSize = MaxSize = integer() >= 1
304 Groups = undefined | [{Size, [Group]}]
305 Size = integer() >= 1
306 Group = {G, P}
307 G = P = integer() >= 1
308 Selects a group for Diffie-Hellman key exchange with the key
310 size in the range MinSize...MaxSize and as close to Suggested‐
311 Size as possible. If Groups == undefined a default set will be
312 used, otherwise the group is selected from Groups.
313 First a size, as close as possible to SuggestedSize, is se‐
315 lected. Then one group with that key size is randomly selected
316 from the specified set of groups. If no size within the limits
317 of MinSize and MaxSize is available, {error,no_group_found} is
318 returned.
319 The default set of groups is listed in lib/public_key/priv/mod‐
321 uli. This file may be regenerated like this:
322 $> cd $ERL_TOP/lib/public_key/priv/
324 $> generate
325 ---- wait until all background jobs has finished. It may take several days !
326 $> cat moduli-* > moduli
327 $> cd ..; make
328 encrypt_private(PlainText, Key) -> CipherText
331 encrypt_private(PlainText, Key, Options) -> CipherText
333 Types:
335 PlainText = binary()
337 Key = rsa_private_key()
338 Options = crypto:pk_encrypt_decrypt_opts()
339 CipherText = binary()
340 Public-key encryption using the private key. See also
342 crypto:private_encrypt/4.
343 encrypt_public(PlainText, Key) -> CipherText
345 encrypt_public(PlainText, Key, Options) -> CipherText
347 Types:
349 PlainText = binary()
351 Key = rsa_public_key()
352 Options = crypto:pk_encrypt_decrypt_opts()
353 CipherText = binary()
354 Public-key encryption using the public key. See also crypto:pub‐
356 lic_encrypt/4.
357 generate_key(Params :: DHparams | ECparams | RSAparams) ->
359 DHkeys | ECkey | RSAkey
360 Types:
362 DHparams = #'DHParameter'{}
364 DHkeys = {PublicDH :: binary(), PrivateDH :: binary()}
365 ECparams = ecpk_parameters_api()
366 ECkey = #'ECPrivateKey'{}
367 RSAparams = {rsa, Size, PubExp}
368 Size = PubExp = integer() >= 1
369 RSAkey = #'RSAPrivateKey'{}
370 Generates a new key pair. Note that except for Diffie-Hellman
372 the public key is included in the private key structure. See
373 also crypto:generate_key/2
374 pem_decode(PemBin :: binary()) -> [pem_entry()]
376 Decodes PEM binary data and returns entries as ASN.1 DER encoded
378 entities.
379 Example {ok, PemBin} = file:read_file("cert.pem"). PemEntries =
381 public_key:pem_decode(PemBin).
382 pem_encode(PemEntries :: [pem_entry()]) -> binary()
384 Creates a PEM binary.
386 pem_entry_decode(PemEntry) -> term()
388 pem_entry_decode(PemEntry, Password) -> term()
390 Types:
392 PemEntry = pem_entry()
394 Password = string() | fun(() -> string())
395 Decodes a PEM entry. pem_decode/1 returns a list of PEM entries.
397 Notice that if the PEM entry is of type 'SubjectPublickeyInfo',
398 it is further decoded to an rsa_public_key() or dsa_pub‐
399 lic_key().
400 Password can be either an octet string or function which returns
402 same type.
403 pem_entry_encode(Asn1Type, Entity) -> pem_entry()
405 pem_entry_encode(Asn1Type, Entity, InfoPwd) -> pem_entry()
407 Types:
409 Asn1Type = pki_asn1_type()
411 Entity = term()
412 InfoPwd = {CipherInfo, Password}
413 CipherInfo = cipher_info()
414 Password = string()
415 Creates a PEM entry that can be feed to pem_encode/1.
417 If Asn1Type is 'SubjectPublicKeyInfo', Entity must be either an
419 rsa_public_key(), dsa_public_key() or an ec_public_key() and
420 this function creates the appropriate 'SubjectPublicKeyInfo' en‐
421 try.
422 pkix_decode_cert(Cert, Type) -> #'Certificate'{} | otp_cert()
424 Types:
426 Cert = der_cert()
428 Type = plain | otp
429 Decodes an ASN.1 DER-encoded PKIX certificate. Option otp uses
431 the customized ASN.1 specification OTP-PKIX.asn1 for decoding
432 and also recursively decode most of the standard parts.
433 pkix_encode(Asn1Type, Entity, Type) -> Der
435 Types:
437 Asn1Type = asn1_type()
439 Entity = term()
440 Type = otp | plain
441 Der = der_encoded()
442 DER encodes a PKIX x509 certificate or part of such a certifi‐
444 cate. This function must be used for encoding certificates or
445 parts of certificates that are decoded/created in the otp for‐
446 mat, whereas for the plain format this function directly calls
447 der_encode/2.
448 Note:
450 Subtle ASN-1 encoding errors in certificates may be worked
451 around when decoding, this may have the affect that the encoding
452 a certificate back to DER may generate different bytes then the
453 supplied original.
454 pkix_is_issuer(CertorCRL, IssuerCert) -> boolean()
457 Types:
459 CertorCRL = cert() | #'CertificateList'{}
461 IssuerCert = cert()
462 Checks if IssuerCert issued Cert.
464 pkix_is_fixed_dh_cert(Cert) -> boolean()
466 Types:
468 Cert = cert()
470 Checks if a certificate is a fixed Diffie-Hellman certificate.
472 pkix_is_self_signed(Cert) -> boolean()
474 Types:
476 Cert = cert()
478 Checks if a certificate is self-signed.
480 pkix_issuer_id(Cert, IssuedBy) ->
482 {ok, ID :: cert_id()} | {error, Reason}
483 Types:
485 Cert = cert()
487 IssuedBy = self | other
488 Reason = term()
489 Returns the x509 certificate issuer id, if it can be determined.
491 pkix_normalize_name(Issuer) -> Normalized
493 Types:
495 Issuer = issuer_name() | der_encoded()
497 Normalized = issuer_name()
498 Normalizes an issuer name so that it can be easily compared to
500 another issuer name.
501 pkix_path_validation(Cert, CertChain, Options) ->
503 {ok, {PublicKeyInfo, PolicyTree}} |
504 {error,
505 {bad_cert, Reason :: bad_cert_reason()}}
506 Types:
508 Cert = cert() | atom()
510 CertChain = [cert() | combined_cert()]
511 Options =
512 [{max_path_length, integer()} |
513 {verify_fun, {function(), term()}}]
514 PublicKeyInfo = public_key_info()
515 PolicyTree = list()
516 Performs a basic path validation according to RFC 5280. However,
518 CRL validation is done separately by pkix_crls_validate/3 and
519 is to be called from the supplied verify_fun. The optional pol‐
520 icy tree check is currently not implemented but an empty place
521 holder list is returned instead.
522 Available options:
524 {verify_fun, {fun(), InitialUserState::term()}:
526 The fun must be defined as:
527 fun(OtpCert :: #'OTPCertificate'{},
529 Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
530 {extension, #'Extension'{}},
531 InitialUserState :: term()) ->
532 {valid, UserState :: term()} |
533 {valid_peer, UserState :: term()} |
534 {fail, Reason :: term()} |
535 {unknown, UserState :: term()}.
536 If the verify callback fun returns {fail, Reason}, the veri‐
539 fication process is immediately stopped. If the verify call‐
540 back fun returns {valid, UserState}, the verification
541 process is continued. This can be used to accept specific
542 path validation errors, such as selfsigned_peer, as well as
543 verifying application-specific extensions. If called with an
544 extension unknown to the user application, the return value
545 {unknown, UserState} is to be used.
546 Warning:
548 Note that user defined custom verify_fun may alter original
549 path validation error (e.g selfsigned_peer). Use with caution.
550 {max_path_length, integer()}:
553 The max_path_length is the maximum number of non-self-is‐
554 sued intermediate certificates that can follow the peer cer‐
555 tificate in a valid certification path. So, if
556 max_path_length is 0, the PEER must be signed by the trusted
557 ROOT-CA directly, if it is 1, the path can be PEER, CA,
558 ROOT-CA, if it is 2, the path can be PEER, CA, CA, ROOT-CA,
559 and so on.
560 Explanations of reasons for a bad certificate:
562 cert_expired:
564 Certificate is no longer valid as its expiration date has
565 passed.
566 invalid_issuer:
568 Certificate issuer name does not match the name of the is‐
569 suer certificate in the chain.
570 invalid_signature:
572 Certificate was not signed by its issuer certificate in the
573 chain.
574 name_not_permitted:
576 Invalid Subject Alternative Name extension.
577 missing_basic_constraint:
579 Certificate, required to have the basic constraints exten‐
580 sion, does not have a basic constraints extension.
581 invalid_key_usage:
583 Certificate key is used in an invalid way according to the
584 key-usage extension.
585 {revoked, crl_reason()}:
587 Certificate has been revoked.
588 atom():
590 Application-specific error reason that is to be checked by
591 the verify_fun.
592 pkix_crl_issuer(CRL) -> Issuer
594 Types:
596 CRL = der_encoded() | #'CertificateList'{}
598 Issuer = issuer_name()
599 Returns the issuer of the CRL.
601 pkix_crls_validate(OTPcertificate, DPandCRLs, Options) ->
603 CRLstatus
604 Types:
606 OTPcertificate = #'OTPCertificate'{}
608 DPandCRLs = [DPandCRL]
609 DPandCRL = {DP, {DerCRL, CRL}}
610 DP = #'DistributionPoint'{}
611 DerCRL = der_encoded()
612 CRL = #'CertificateList'{}
613 Options = [{atom(), term()}]
614 CRLstatus = valid | {bad_cert, BadCertReason}
615 BadCertReason =
616 revocation_status_undetermined |
617 {revocation_status_undetermined, Reason :: term()} |
618 {revoked, crl_reason()}
619 Performs CRL validation. It is intended to be called from the
621 verify fun of pkix_path_validation/3 .
622 Available options:
624 {update_crl, fun()}:
626 The fun has the following type specification:
627 fun(#'DistributionPoint'{}, #'CertificateList'{}) ->
629 #'CertificateList'{}
630 The fun uses the information in the distribution point to
632 access the latest possible version of the CRL. If this fun
633 is not specified, Public Key uses the default implementa‐
634 tion:
635 fun(_DP, CRL) -> CRL end
637 {issuer_fun, fun()}:
639 The fun has the following type specification:
640 fun(#'DistributionPoint'{}, #'CertificateList'{},
642 {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
643 {ok, #'OTPCertificate'{}, [der_encoded]}
644 The fun returns the root certificate and certificate chain
646 that has signed the CRL.
647 fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}
649 {undetermined_details, boolean()}:
651 Defaults to false. When revocation status cannot be deter‐
652 mined, and this option is set to true, details of why no
653 CRLs where accepted are included in the return value.
654 pkix_crl_verify(CRL, Cert) -> boolean()
656 Types:
658 CRL = der_encoded() | #'CertificateList'{}
660 Cert = cert()
661 Verify that Cert is the CRL signer.
663 pkix_dist_point(Cert) -> DistPoint
665 Types:
667 Cert = cert()
669 DistPoint = #'DistributionPoint'{}
670 Creates a distribution point for CRLs issued by the same issuer
672 as Cert. Can be used as input to pkix_crls_validate/3
673 pkix_dist_points(Cert) -> DistPoints
675 Types:
677 Cert = cert()
679 DistPoints = [#'DistributionPoint'{}]
680 Extracts distribution points from the certificates extensions.
682 pkix_hash_type(HashOid :: oid()) ->
684 DigestType ::
685 md5 | crypto:sha1() | crypto:sha2()
686 Translates OID to Erlang digest type
688 pkix_match_dist_point(CRL, DistPoint) -> boolean()
690 Types:
692 CRL = der_encoded() | #'CertificateList'{}
694 DistPoint = #'DistributionPoint'{}
695 Checks whether the given distribution point matches the Issuing
697 Distribution Point of the CRL, as described in RFC 5280. If the
698 CRL doesn't have an Issuing Distribution Point extension, the
699 distribution point always matches.
700 pkix_sign(Cert, Key) -> Der
702 Types:
704 Cert = #'OTPTBSCertificate'{}
706 Key = private_key()
707 Der = der_encoded()
708 Signs an 'OTPTBSCertificate'. Returns the corresponding DER-en‐
710 coded certificate.
711 pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}
713 Types:
715 AlgorithmId = oid()
717 DigestType = crypto:rsa_digest_type() | none
718 SignatureType = rsa | dsa | ecdsa | eddsa
719 Translates signature algorithm OID to Erlang digest and signa‐
721 ture types.
722 The AlgorithmId is the signature OID from a certificate or a
724 certificate revocation list.
725 pkix_test_data(ChainConf) -> TestConf
727 Types:
729 ChainConf =
731 #{server_chain := chain_opts(), client_chain :=
732 chain_opts()} |
733 chain_opts()
734 TestConf = test_config() | [conf_opt()]
735 Creates certificate configuration(s) consisting of certificate
737 and its private key plus CA certificate bundle, for a client and
738 a server, intended to facilitate automated testing of applica‐
739 tions using X509-certificates, often through SSL/TLS. The test
740 data can be used when you have control over both the client and
741 the server in a test scenario.
742 When this function is called with a map containing client and
744 server chain specifications; it generates both a client and a
745 server certificate chain where the cacerts returned for the
746 server contains the root cert the server should trust and the
747 intermediate certificates the server should present to connect‐
748 ing clients. The root cert the server should trust is the one
749 used as root of the client certificate chain. Vice versa applies
750 to the cacerts returned for the client. The root cert(s) can ei‐
751 ther be pre-generated with pkix_test_root_cert/2 , or if op‐
752 tions are specified; it is (they are) generated.
753 When this function is called with a list of certificate options;
755 it generates a configuration with just one node certificate
756 where cacerts contains the root cert and the intermediate certs
757 that should be presented to a peer. In this case the same root
758 cert must be used for all peers. This is useful in for example
759 an Erlang distributed cluster where any node, towards another
760 node, acts either as a server or as a client depending on who
761 connects to whom. The generated certificate contains a subject
762 altname, which is not needed in a client certificate, but makes
763 the certificate useful for both roles.
764 Explanation of the options used to customize certificates in the
766 generated chains:
767 {digest, digest_type()}:
769 Hash algorithm to be used for signing the certificate to‐
770 gether with the key option. Defaults to sha that is sha1.
771 {key, key_params() | private_key()}:
773 Parameters to be used to call public_key:generate_key/1, to
774 generate a key, or an existing key. Defaults to generating
775 an ECDSA key. Note this could fail if Erlang/OTP is compiled
776 with a very old cryptolib.
777 {validity, {From::erlang:timestamp(), To::erlang:time‐
779 stamp()}} :
780 The validity period of the certificate.
781 {extensions, [#'Extension'{}]}:
783 Extensions to include in the certificate.
784 Default extensions included in CA certificates if not other‐
786 wise specified are:
787 [#'Extension'{extnID = ?'id-ce-keyUsage',
789 extnValue = [keyCertSign, cRLSign],
790 critical = false},
791 #'Extension'{extnID = ?'id-ce-basicConstraints',
792 extnValue = #'BasicConstraints'{cA = true},
793 critical = true}]
794 Default extensions included in the server peer cert if not
797 otherwise specified are:
798 [#'Extension'{extnID = ?'id-ce-keyUsage',
800 extnValue = [digitalSignature, keyAgreement],
801 critical = false},
802 #'Extension'{extnID = ?'id-ce-subjectAltName',
803 extnValue = [{dNSName, Hostname}],
804 critical = false}]
805 Hostname is the result of calling net_adm:localhost() in the
808 Erlang node where this funcion is called.
809 Note:
811 Note that the generated certificates and keys does not provide a
812 formally correct PKIX-trust-chain and they cannot be used to
813 achieve real security. This function is provided for testing
814 purposes only.
815 pkix_test_root_cert(Name, Options) -> RootCert
818 Types:
820 Name = string()
822 Options = [cert_opt()]
823 RootCert = test_root_cert()
824 Generates a root certificate that can be used in multiple calls
826 to pkix_test_data/1 when you want the same root certificate for
827 several generated certificates.
828 pkix_subject_id(Cert) -> ID
830 Types:
832 Cert = cert()
834 ID = cert_id()
835 Returns the X509 certificate subject id.
837 pkix_verify(Cert, Key) -> boolean()
839 Types:
841 Cert = der_cert()
843 Key = public_key()
844 Verifies PKIX x.509 certificate signature.
846 pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()
848 pkix_verify_hostname(Cert, ReferenceIDs, Options) -> boolean()
850 Types:
852 Cert = cert()
854 ReferenceIDs = referenceIDs()
855 Options = [{match_fun | fail_callback | fqdn_fun, func‐
856 tion()}]
857 This function checks that the Presented Identifier (e.g host‐
859 name) in a peer certificate is in agreement with at least one of
860 the Reference Identifier that the client expects to be con‐
861 nected to. The function is intended to be added as an extra
862 client check of the peer certificate when performing pub‐
863 lic_key:pkix_path_validation/3
864 See RFC 6125 for detailed information about hostname verifica‐
866 tion. The User's Guide and code examples describes this function
867 more detailed.
868 The option funs are described here:
870 match_fun:
872 fun(ReferenceId::ReferenceId() | FQDN::string(),
875 PresentedId::{dNSName,string()} | {uniformResourceIdentifier,string() |
876 {iPAddress,list(byte())} | {OtherId::atom()|oid(),term()}})
877 fun(....) -> true; % My special case
879 (_, _) -> default % all others falls back to the inherit tests
880 end
881 See pkix_verify_hostname_match_fun/1 for a function that takes
883 a protocol name as argument and returns a fun/2 suitable for
884 this option and Re-defining the match operation in the User's
885 Guide for an example.
886 Note:
888 Reference Id values given as binaries will be converted to
889 strings, and ip references may be given in string format that
890 is "10.0.1.1" or "1234::5678:9012" as well as on the format
891 inet:ip_address()
892 fail_callback:
895 If a matching fails, there could be circumstances when the
896 certificate should be accepted anyway. Think for example of
897 a web browser where you choose to accept an outdated cer‐
898 tificate. This option enables implementation of such an ex‐
899 ception but for hostnames. This fun/1 is called when no Ref‐
900 erenceID matches. The return value of the fun (a boolean())
901 decides the outcome. If true the the certificate is accepted
902 otherwise it is rejected. See "Pinning" a Certificate in the
903 User's Guide.
904 fqdn_fun:
906 This option augments the host name extraction from URIs and
907 other Reference IDs. It could for example be a very special
908 URI that is not standardised. The fun takes a Reference ID
909 as argument and returns one of:
910 * the hostname
912 * the atom default: the default host name extract function
914 will be used
915 * the atom undefined: a host name could not be extracted.
917 The pkix_verify_hostname/3 will return false.
918 For an example, see Hostname extraction in the User's Guide.
920 pkix_verify_hostname_match_fun(Protocol) -> Result
922 Types:
924 Protocol = https
926 Result = function()
927 The return value of calling this function is intended to be used
929 in the match_fun option in pkix_verify_hostname/3.
930 The returned fun augments the verify hostname matching according
932 to the specific rules for the protocol in the argument.
933 Note:
935 Currently supported https fun will allow wildcard certificate
936 matching as specified by the HTTP standard. Note that for in‐
937 stance LDAP have a different set of wildcard matching rules. If
938 you do not want to allow wildcard certificates (recommended from
939 a security perspective) or otherwise customize the hostname
940 match the default match function used by ssl application will be
941 sufficient.
942 sign(Msg, DigestType, Key) -> Signature
945 sign(Msg, DigestType, Key, Options) -> Signature
947 Types:
949 Msg = binary() | {digest, binary()}
951 DigestType = digest_type()
952 Key = private_key() | ed_legacy_privkey()
953 Options = crypto:pk_sign_verify_opts()
954 Signature = binary()
955 Creates a digital signature.
957 The Msg is either the binary "plain text" data to be signed or
959 it is the hashed value of "plain text", that is, the digest.
960 ssh_decode(SshBin, Type) -> Decoded
962 Types:
964 SshBin = binary()
966 Type = ssh2_pubkey | OtherType | InternalType
967 OtherType = public_key | ssh_file()
968 InternalType = new_openssh
969 Decoded = Decoded_ssh2_pubkey | Decoded_OtherType
970 Decoded_ssh2_pubkey = public_key() | ed_legacy_pubkey()
971 Decoded_OtherType =
972 [{public_key() | ed_legacy_pubkey(), Attributes}]
973 Attributes = [{atom(), term()}]
974 Note:
976 This function is deprecated and should not be used in new pro‐
977 grams. Use ssh_file:decode/2 instead.
978 Decodes an SSH file-binary. In the case of known_hosts or
981 auth_keys, the binary can include one or more lines of the file.
982 Returns a list of public keys and their attributes, possible at‐
983 tribute values depends on the file type represented by the bi‐
984 nary.
985 If the Type is ssh2_pubkey, the result will be Decoded_ssh2_pub‐
987 key. Otherwise it will be Decoded_OtherType.
988 RFC4716 attributes - see RFC 4716.:
990 {headers, [{string(), utf8_string()}]}
991 auth_key attributes - see manual page for sshd.:
993 {comment, string()}{options, [string()]}{bits, integer()} -
994 In SSH version 1 files.
995 known_host attributes - see manual page for sshd.:
997 {hostnames, [string()]}{comment, string()}{bits, integer()}
998 - In SSH version 1 files.
999 Example: {ok, SshBin} = file:read_file("known_hosts").
1001 If Type is public_key the binary can be either an RFC4716 public
1003 key or an OpenSSH public key.
1004 ssh_encode(InData, Type) -> binary()
1006 Types:
1008 Type = ssh2_pubkey | OtherType
1010 OtherType = public_key | ssh_file()
1011 InData = InData_ssh2_pubkey | OtherInData
1012 InData_ssh2_pubkey = public_key() | ed_legacy_pubkey()
1013 OtherInData = [{Key, Attributes}]
1014 Key = public_key() | ed_legacy_pubkey()
1015 Attributes = [{atom(), term()}]
1016 Note:
1018 This function is deprecated and should not be used in new pro‐
1019 grams. Use ssh_file:encode/2 instead.
1020 Encodes a list of SSH file entries (public keys and attributes)
1023 to a binary. Possible attributes depend on the file type, see
1024 ssh_decode/2 .
1025 If the Type is ssh2_pubkey, the InData shall be InData_ssh2_pub‐
1027 key. Otherwise it shall be OtherInData.
1028 ssh_hostkey_fingerprint(HostKey) -> string()
1030 ssh_hostkey_fingerprint(DigestType, HostKey) -> string()
1031 ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]
1032 Types:
1034 HostKey = public_key()
1036 DigestType = digest_type()
1037 Calculates a ssh fingerprint from a public host key as openssh
1039 does.
1040 Note:
1042 This function is deprecated and should not be used in new pro‐
1043 grams. Use ssh:hostkey_fingerprint/1 or ssh:hostkey_finger‐
1044 print/2 instead.
1045 The algorithm in ssh_hostkey_fingerprint/1 is md5 to be compati‐
1048 ble with older ssh-keygen commands. The string from the second
1049 variant is prepended by the algorithm name in uppercase as in
1050 newer ssh-keygen commands.
1051 Examples:
1053 2> public_key:ssh_hostkey_fingerprint(Key).
1055 "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
1056 3> public_key:ssh_hostkey_fingerprint(md5,Key).
1058 "MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
1059 4> public_key:ssh_hostkey_fingerprint(sha,Key).
1061 "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
1062 5> public_key:ssh_hostkey_fingerprint(sha256,Key).
1064 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
1065 6> public_key:ssh_hostkey_fingerprint([sha,sha256],Key).
1067 ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
1068 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
1069 verify(Msg, DigestType, Signature, Key) -> boolean()
1072 verify(Msg, DigestType, Signature, Key, Options) -> boolean()
1074 Types:
1076 Msg = binary() | {digest, binary()}
1078 DigestType = digest_type()
1079 Signature = binary()
1080 Key = public_key() | ed_legacy_pubkey()
1081 Options = crypto:pk_sign_verify_opts()
1082 Verifies a digital signature.
1084 The Msg is either the binary "plain text" data or it is the
1086 hashed value of "plain text", that is, the digest.
1087 short_name_hash(Name) -> string()
1089 Types:
1091 Name = issuer_name()
1093 Generates a short hash of an issuer name. The hash is returned
1095 as a string containing eight hexadecimal digits.
1096 The return value of this function is the same as the result of
1098 the commands openssl crl -hash and openssl x509 -issuer_hash,
1099 when passed the issuer name of a CRL or a certificate, respec‐
1100 tively. This hash is used by the c_rehash tool to maintain a di‐
1101 rectory of symlinks to CRL files, in order to facilitate looking
1102 up a CRL by its issuer name.
1103Ericsson AB public_key 1.12 public_key(3)