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()
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 pem_entry_encode(Asn1Type, Entity) -> pem_entry()
402 pem_entry_encode(Asn1Type, Entity, InfoPwd) -> pem_entry()
404 Types:
406 Asn1Type = pki_asn1_type()
408 Entity = term()
409 InfoPwd = {CipherInfo, Password}
410 CipherInfo = cipher_info()
411 Password = string()
412 Creates a PEM entry that can be feed to pem_encode/1.
414 If Asn1Type is 'SubjectPublicKeyInfo', Entity must be either an
416 rsa_public_key(), dsa_public_key() or an ec_public_key() and
417 this function creates the appropriate 'SubjectPublicKeyInfo' en‐
418 try.
419 pkix_decode_cert(Cert, Type) -> #'Certificate'{} | otp_cert()
421 Types:
423 Cert = der_cert()
425 Type = plain | otp
426 Decodes an ASN.1 DER-encoded PKIX certificate. Option otp uses
428 the customized ASN.1 specification OTP-PKIX.asn1 for decoding
429 and also recursively decode most of the standard parts.
430 pkix_encode(Asn1Type, Entity, Type) -> Der
432 Types:
434 Asn1Type = asn1_type()
436 Entity = term()
437 Type = otp | plain
438 Der = der_encoded()
439 DER encodes a PKIX x509 certificate or part of such a certifi‐
441 cate. This function must be used for encoding certificates or
442 parts of certificates that are decoded/created in the otp for‐
443 mat, whereas for the plain format this function directly calls
444 der_encode/2.
445 Note:
447 Subtle ASN-1 encoding errors in certificates may be worked
448 around when decoding, this may have the affect that the encoding
449 a certificate back to DER may generate different bytes then the
450 supplied original.
451 pkix_is_issuer(CertorCRL, IssuerCert) -> boolean()
454 Types:
456 CertorCRL = cert() | #'CertificateList'{}
458 IssuerCert = cert()
459 Checks if IssuerCert issued Cert.
461 pkix_is_fixed_dh_cert(Cert) -> boolean()
463 Types:
465 Cert = cert()
467 Checks if a certificate is a fixed Diffie-Hellman certificate.
469 pkix_is_self_signed(Cert) -> boolean()
471 Types:
473 Cert = cert()
475 Checks if a certificate is self-signed.
477 pkix_issuer_id(Cert, IssuedBy) ->
479 {ok, ID :: cert_id()} | {error, Reason}
480 Types:
482 Cert = cert()
484 IssuedBy = self | other
485 Reason = term()
486 Returns the x509 certificate issuer id, if it can be determined.
488 pkix_normalize_name(Issuer) -> Normalized
490 Types:
492 Issuer = Normalized = issuer_name()
494 Normalizes an issuer name so that it can be easily compared to
496 another issuer name.
497 pkix_path_validation(Cert, CertChain, Options) ->
499 {ok, {PublicKeyInfo, PolicyTree}} |
500 {error,
501 {bad_cert, Reason :: bad_cert_reason()}}
502 Types:
504 Cert = cert() | atom()
506 CertChain = [cert() | combined_cert()]
507 Options =
508 [{max_path_length, integer()} |
509 {verify_fun, {function(), term()}}]
510 PublicKeyInfo = public_key_info()
511 PolicyTree = list()
512 Performs a basic path validation according to RFC 5280. However,
514 CRL validation is done separately by pkix_crls_validate/3 and
515 is to be called from the supplied verify_fun. The optional pol‐
516 icy tree check is currently not implemented but an empty place
517 holder list is returned instead.
518 Available options:
520 {verify_fun, {fun(), InitialUserState::term()}:
522 The fun must be defined as:
523 fun(OtpCert :: #'OTPCertificate'{},
525 Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
526 {extension, #'Extension'{}},
527 InitialUserState :: term()) ->
528 {valid, UserState :: term()} |
529 {valid_peer, UserState :: term()} |
530 {fail, Reason :: term()} |
531 {unknown, UserState :: term()}.
532 If the verify callback fun returns {fail, Reason}, the veri‐
535 fication process is immediately stopped. If the verify call‐
536 back fun returns {valid, UserState}, the verification
537 process is continued. This can be used to accept specific
538 path validation errors, such as selfsigned_peer, as well as
539 verifying application-specific extensions. If called with an
540 extension unknown to the user application, the return value
541 {unknown, UserState} is to be used.
542 Warning:
544 Note that user defined custom verify_fun may alter original
545 path validation error (e.g selfsigned_peer). Use with caution.
546 {max_path_length, integer()}:
549 The max_path_length is the maximum number of non-self-is‐
550 sued intermediate certificates that can follow the peer cer‐
551 tificate in a valid certification path. So, if
552 max_path_length is 0, the PEER must be signed by the trusted
553 ROOT-CA directly, if it is 1, the path can be PEER, CA,
554 ROOT-CA, if it is 2, the path can be PEER, CA, CA, ROOT-CA,
555 and so on.
556 Explanations of reasons for a bad certificate:
558 cert_expired:
560 Certificate is no longer valid as its expiration date has
561 passed.
562 invalid_issuer:
564 Certificate issuer name does not match the name of the is‐
565 suer certificate in the chain.
566 invalid_signature:
568 Certificate was not signed by its issuer certificate in the
569 chain.
570 name_not_permitted:
572 Invalid Subject Alternative Name extension.
573 missing_basic_constraint:
575 Certificate, required to have the basic constraints exten‐
576 sion, does not have a basic constraints extension.
577 invalid_key_usage:
579 Certificate key is used in an invalid way according to the
580 key-usage extension.
581 {revoked, crl_reason()}:
583 Certificate has been revoked.
584 atom():
586 Application-specific error reason that is to be checked by
587 the verify_fun.
588 pkix_crl_issuer(CRL) -> Issuer
590 Types:
592 CRL = der_encoded() | #'CertificateList'{}
594 Issuer = issuer_name()
595 Returns the issuer of the CRL.
597 pkix_crls_validate(OTPcertificate, DPandCRLs, Options) ->
599 CRLstatus
600 Types:
602 OTPcertificate = #'OTPCertificate'{}
604 DPandCRLs = [DPandCRL]
605 DPandCRL = {DP, {DerCRL, CRL}}
606 DP = #'DistributionPoint'{}
607 DerCRL = der_encoded()
608 CRL = #'CertificateList'{}
609 Options = [{atom(), term()}]
610 CRLstatus = valid | {bad_cert, BadCertReason}
611 BadCertReason =
612 revocation_status_undetermined |
613 {revocation_status_undetermined, Reason :: term()} |
614 {revoked, crl_reason()}
615 Performs CRL validation. It is intended to be called from the
617 verify fun of pkix_path_validation/3 .
618 Available options:
620 {update_crl, fun()}:
622 The fun has the following type specification:
623 fun(#'DistributionPoint'{}, #'CertificateList'{}) ->
625 #'CertificateList'{}
626 The fun uses the information in the distribution point to
628 access the latest possible version of the CRL. If this fun
629 is not specified, Public Key uses the default implementa‐
630 tion:
631 fun(_DP, CRL) -> CRL end
633 {issuer_fun, fun()}:
635 The fun has the following type specification:
636 fun(#'DistributionPoint'{}, #'CertificateList'{},
638 {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
639 {ok, #'OTPCertificate'{}, [der_encoded]}
640 The fun returns the root certificate and certificate chain
642 that has signed the CRL.
643 fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}
645 {undetermined_details, boolean()}:
647 Defaults to false. When revocation status cannot be deter‐
648 mined, and this option is set to true, details of why no
649 CRLs where accepted are included in the return value.
650 pkix_crl_verify(CRL, Cert) -> boolean()
652 Types:
654 CRL = der_encoded() | #'CertificateList'{}
656 Cert = cert()
657 Verify that Cert is the CRL signer.
659 pkix_dist_point(Cert) -> DistPoint
661 Types:
663 Cert = cert()
665 DistPoint = #'DistributionPoint'{}
666 Creates a distribution point for CRLs issued by the same issuer
668 as Cert. Can be used as input to pkix_crls_validate/3
669 pkix_dist_points(Cert) -> DistPoints
671 Types:
673 Cert = cert()
675 DistPoints = [#'DistributionPoint'{}]
676 Extracts distribution points from the certificates extensions.
678 pkix_hash_type(HashOid :: oid()) ->
680 DigestType ::
681 md5 | crypto:sha1() | crypto:sha2()
682 Translates OID to Erlang digest type
684 pkix_match_dist_point(CRL, DistPoint) -> boolean()
686 Types:
688 CRL = der_encoded() | #'CertificateList'{}
690 DistPoint = #'DistributionPoint'{}
691 Checks whether the given distribution point matches the Issuing
693 Distribution Point of the CRL, as described in RFC 5280. If the
694 CRL doesn't have an Issuing Distribution Point extension, the
695 distribution point always matches.
696 pkix_sign(Cert, Key) -> Der
698 Types:
700 Cert = #'OTPTBSCertificate'{}
702 Key = private_key()
703 Der = der_encoded()
704 Signs an 'OTPTBSCertificate'. Returns the corresponding DER-en‐
706 coded certificate.
707 pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}
709 Types:
711 AlgorithmId = oid()
713 DigestType = crypto:rsa_digest_type() | none
714 SignatureType = rsa | dsa | ecdsa
715 Translates signature algorithm OID to Erlang digest and signa‐
717 ture types.
718 The AlgorithmId is the signature OID from a certificate or a
720 certificate revocation list.
721 pkix_test_data(ChainConf) -> TestConf
723 Types:
725 ChainConf =
727 #{server_chain := chain_opts(), client_chain :=
728 chain_opts()} |
729 chain_opts()
730 TestConf = test_config() | [conf_opt()]
731 Creates certificate configuration(s) consisting of certificate
733 and its private key plus CA certificate bundle, for a client and
734 a server, intended to facilitate automated testing of applica‐
735 tions using X509-certificates, often through SSL/TLS. The test
736 data can be used when you have control over both the client and
737 the server in a test scenario.
738 When this function is called with a map containing client and
740 server chain specifications; it generates both a client and a
741 server certificate chain where the cacerts returned for the
742 server contains the root cert the server should trust and the
743 intermediate certificates the server should present to connect‐
744 ing clients. The root cert the server should trust is the one
745 used as root of the client certificate chain. Vice versa applies
746 to the cacerts returned for the client. The root cert(s) can ei‐
747 ther be pre-generated with pkix_test_root_cert/2 , or if op‐
748 tions are specified; it is (they are) generated.
749 When this function is called with a list of certificate options;
751 it generates a configuration with just one node certificate
752 where cacerts contains the root cert and the intermediate certs
753 that should be presented to a peer. In this case the same root
754 cert must be used for all peers. This is useful in for example
755 an Erlang distributed cluster where any node, towards another
756 node, acts either as a server or as a client depending on who
757 connects to whom. The generated certificate contains a subject
758 altname, which is not needed in a client certificate, but makes
759 the certificate useful for both roles.
760 Explanation of the options used to customize certificates in the
762 generated chains:
763 {digest, digest_type()}:
765 Hash algorithm to be used for signing the certificate to‐
766 gether with the key option. Defaults to sha that is sha1.
767 {key, key_params() | private_key()}:
769 Parameters to be used to call public_key:generate_key/1, to
770 generate a key, or an existing key. Defaults to generating
771 an ECDSA key. Note this could fail if Erlang/OTP is compiled
772 with a very old cryptolib.
773 {validity, {From::erlang:timestamp(), To::erlang:time‐
775 stamp()}} :
776 The validity period of the certificate.
777 {extensions, [#'Extension'{}]}:
779 Extensions to include in the certificate.
780 Default extensions included in CA certificates if not other‐
782 wise specified are:
783 [#'Extension'{extnID = ?'id-ce-keyUsage',
785 extnValue = [keyCertSign, cRLSign],
786 critical = false},
787 #'Extension'{extnID = ?'id-ce-basicConstraints',
788 extnValue = #'BasicConstraints'{cA = true},
789 critical = true}]
790 Default extensions included in the server peer cert if not
793 otherwise specified are:
794 [#'Extension'{extnID = ?'id-ce-keyUsage',
796 extnValue = [digitalSignature, keyAgreement],
797 critical = false},
798 #'Extension'{extnID = ?'id-ce-subjectAltName',
799 extnValue = [{dNSName, Hostname}],
800 critical = false}]
801 Hostname is the result of calling net_adm:localhost() in the
804 Erlang node where this funcion is called.
805 Note:
807 Note that the generated certificates and keys does not provide a
808 formally correct PKIX-trust-chain and they cannot be used to
809 achieve real security. This function is provided for testing
810 purposes only.
811 pkix_test_root_cert(Name, Options) -> RootCert
814 Types:
816 Name = string()
818 Options = [cert_opt()]
819 RootCert = test_root_cert()
820 Generates a root certificate that can be used in multiple calls
822 to pkix_test_data/1 when you want the same root certificate for
823 several generated certificates.
824 pkix_subject_id(Cert) -> ID
826 Types:
828 Cert = cert()
830 ID = cert_id()
831 Returns the X509 certificate subject id.
833 pkix_verify(Cert, Key) -> boolean()
835 Types:
837 Cert = der_cert()
839 Key = public_key()
840 Verifies PKIX x.509 certificate signature.
842 pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()
844 pkix_verify_hostname(Cert, ReferenceIDs, Options) -> boolean()
846 Types:
848 Cert = cert()
850 ReferenceIDs = referenceIDs()
851 Options = [{match_fun | fail_callback | fqdn_fun, func‐
852 tion()}]
853 This function checks that the Presented Identifier (e.g host‐
855 name) in a peer certificate is in agreement with at least one of
856 the Reference Identifier that the client expects to be con‐
857 nected to. The function is intended to be added as an extra
858 client check of the peer certificate when performing pub‐
859 lic_key:pkix_path_validation/3
860 See RFC 6125 for detailed information about hostname verifica‐
862 tion. The User's Guide and code examples describes this function
863 more detailed.
864 The option funs are described here:
866 match_fun:
868 fun(ReferenceId::ReferenceId() | FQDN::string(),
871 PresentedId::{dNSName,string()} | {uniformResourceIdentifier,string() |
872 {iPAddress,list(byte())} | {OtherId::atom()|oid(),term()}})
873 fun(....) -> true; % My special case
875 (_, _) -> default % all others falls back to the inherit tests
876 end
877 See pkix_verify_hostname_match_fun/1 for a function that takes
879 a protocol name as argument and returns a fun/2 suitable for
880 this option and Re-defining the match operation in the User's
881 Guide for an example.
882 Note:
884 Reference Id values given as binaries will be converted to
885 strings, and ip references may be given in string format that
886 is "10.0.1.1" or "1234::5678:9012" as well as on the format
887 inet:ip_address()
888 fail_callback:
891 If a matching fails, there could be circumstances when the
892 certificate should be accepted anyway. Think for example of
893 a web browser where you choose to accept an outdated cer‐
894 tificate. This option enables implementation of such an ex‐
895 ception but for hostnames. This fun/1 is called when no Ref‐
896 erenceID matches. The return value of the fun (a boolean())
897 decides the outcome. If true the the certificate is accepted
898 otherwise it is rejected. See "Pinning" a Certificate in the
899 User's Guide.
900 fqdn_fun:
902 This option augments the host name extraction from URIs and
903 other Reference IDs. It could for example be a very special
904 URI that is not standardised. The fun takes a Reference ID
905 as argument and returns one of:
906 * the hostname
908 * the atom default: the default host name extract function
910 will be used
911 * the atom undefined: a host name could not be extracted.
913 The pkix_verify_hostname/3 will return false.
914 For an example, see Hostname extraction in the User's Guide.
916 pkix_verify_hostname_match_fun(Protocol) -> Result
918 Types:
920 Protocol = https
922 Result = function()
923 The return value of calling this function is intended to be used
925 in the match_fun option in pkix_verify_hostname/3.
926 The returned fun augments the verify hostname matching according
928 to the specific rules for the protocol in the argument.
929 Note:
931 Currently supported https fun will allow wildcard certificate
932 matching as specified by the HTTP standard. Note that for in‐
933 stance LDAP have a different set of wildcard matching rules. If
934 you do not want to allow wildcard certificates (recommended from
935 a security perspective) or otherwise customize the hostname
936 match the default match function used by ssl application will be
937 sufficient.
938 sign(Msg, DigestType, Key) -> Signature
941 sign(Msg, DigestType, Key, Options) -> Signature
943 Types:
945 Msg = binary() | {digest, binary()}
947 DigestType = digest_type()
948 Key = private_key() | ed_legacy_privkey()
949 Options = crypto:pk_sign_verify_opts()
950 Signature = binary()
951 Creates a digital signature.
953 The Msg is either the binary "plain text" data to be signed or
955 it is the hashed value of "plain text", that is, the digest.
956 ssh_decode(SshBin, Type) -> Decoded
958 Types:
960 SshBin = binary()
962 Type = ssh2_pubkey | OtherType | InternalType
963 OtherType = public_key | ssh_file()
964 InternalType = new_openssh
965 Decoded = Decoded_ssh2_pubkey | Decoded_OtherType
966 Decoded_ssh2_pubkey = public_key() | ed_legacy_pubkey()
967 Decoded_OtherType =
968 [{public_key() | ed_legacy_pubkey(), Attributes}]
969 Attributes = [{atom(), term()}]
970 Note:
972 This function is deprecated and should not be used in new pro‐
973 grams. Use ssh_file:decode/2 instead.
974 Decodes an SSH file-binary. In the case of known_hosts or
977 auth_keys, the binary can include one or more lines of the file.
978 Returns a list of public keys and their attributes, possible at‐
979 tribute values depends on the file type represented by the bi‐
980 nary.
981 If the Type is ssh2_pubkey, the result will be Decoded_ssh2_pub‐
983 key. Otherwise it will be Decoded_OtherType.
984 RFC4716 attributes - see RFC 4716.:
986 {headers, [{string(), utf8_string()}]}
987 auth_key attributes - see manual page for sshd.:
989 {comment, string()}{options, [string()]}{bits, integer()} -
990 In SSH version 1 files.
991 known_host attributes - see manual page for sshd.:
993 {hostnames, [string()]}{comment, string()}{bits, integer()}
994 - In SSH version 1 files.
995 Example: {ok, SshBin} = file:read_file("known_hosts").
997 If Type is public_key the binary can be either an RFC4716 public
999 key or an OpenSSH public key.
1000 ssh_encode(InData, Type) -> binary()
1002 Types:
1004 Type = ssh2_pubkey | OtherType
1006 OtherType = public_key | ssh_file()
1007 InData = InData_ssh2_pubkey | OtherInData
1008 InData_ssh2_pubkey = public_key() | ed_legacy_pubkey()
1009 OtherInData = [{Key, Attributes}]
1010 Key = public_key() | ed_legacy_pubkey()
1011 Attributes = [{atom(), term()}]
1012 Note:
1014 This function is deprecated and should not be used in new pro‐
1015 grams. Use ssh_file:encode/2 instead.
1016 Encodes a list of SSH file entries (public keys and attributes)
1019 to a binary. Possible attributes depend on the file type, see
1020 ssh_decode/2 .
1021 If the Type is ssh2_pubkey, the InData shall be InData_ssh2_pub‐
1023 key. Otherwise it shall be OtherInData.
1024 ssh_hostkey_fingerprint(HostKey) -> string()
1026 ssh_hostkey_fingerprint(DigestType, HostKey) -> string()
1027 ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]
1028 Types:
1030 HostKey = public_key()
1032 DigestType = digest_type()
1033 Calculates a ssh fingerprint from a public host key as openssh
1035 does.
1036 Note:
1038 This function is deprecated and should not be used in new pro‐
1039 grams. Use ssh:hostkey_fingerprint/1 or ssh:hostkey_finger‐
1040 print/2 instead.
1041 The algorithm in ssh_hostkey_fingerprint/1 is md5 to be compati‐
1044 ble with older ssh-keygen commands. The string from the second
1045 variant is prepended by the algorithm name in uppercase as in
1046 newer ssh-keygen commands.
1047 Examples:
1049 2> public_key:ssh_hostkey_fingerprint(Key).
1051 "f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
1052 3> public_key:ssh_hostkey_fingerprint(md5,Key).
1054 "MD5:f5:64:a6:c1:5a:cb:9f:0a:10:46:a2:5c:3e:2f:57:84"
1055 4> public_key:ssh_hostkey_fingerprint(sha,Key).
1057 "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
1058 5> public_key:ssh_hostkey_fingerprint(sha256,Key).
1060 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
1061 6> public_key:ssh_hostkey_fingerprint([sha,sha256],Key).
1063 ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
1064 "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
1065 verify(Msg, DigestType, Signature, Key) -> boolean()
1068 verify(Msg, DigestType, Signature, Key, Options) -> boolean()
1070 Types:
1072 Msg = binary() | {digest, binary()}
1074 DigestType = digest_type()
1075 Signature = binary()
1076 Key = public_key() | ed_legacy_pubkey()
1077 Options = crypto:pk_sign_verify_opts()
1078 Verifies a digital signature.
1080 The Msg is either the binary "plain text" data or it is the
1082 hashed value of "plain text", that is, the digest.
1083 short_name_hash(Name) -> string()
1085 Types:
1087 Name = issuer_name()
1089 Generates a short hash of an issuer name. The hash is returned
1091 as a string containing eight hexadecimal digits.
1092 The return value of this function is the same as the result of
1094 the commands openssl crl -hash and openssl x509 -issuer_hash,
1095 when passed the issuer name of a CRL or a certificate, respec‐
1096 tively. This hash is used by the c_rehash tool to maintain a di‐
1097 rectory of symlinks to CRL files, in order to facilitate looking
1098 up a CRL by its issuer name.
1099Ericsson AB public_key 1.11.3 public_key(3)