1public_key(3)              Erlang Module Definition              public_key(3)
2
3
4

NAME

6       public_key - API module for public-key infrastructure.
7

DESCRIPTION

9       Provides functions to handle public-key infrastructure, for details see
10       public_key(6).
11

COMMON RECORDS AND ASN.1 TYPES

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
18
19       Use the following include directive to get access to  the  records  and
20       constant macros described here and in the User's Guide:
21
22        -include_lib("public_key/include/public_key.hrl").
23

DATA TYPES

25       oid() = tuple()
26
27              Object identifier, a tuple of integers as generated by the ASN.1
28              compiler.
29
30       der_encoded() = binary()
31
32       pki_asn1_type() =
33           'Certificate' | 'RSAPrivateKey' | 'RSAPublicKey' |
34           'DSAPrivateKey' | 'DSAPublicKey' | 'DHParameter' |
35           'SubjectPublicKeyInfo' | 'PrivateKeyInfo' |
36           'CertificationRequest' | 'CertificateList' | 'ECPrivateKey' |
37           'EcpkParameters'
38
39       asn1_type() = atom()
40
41              ASN.1 type present in the Public Key applications ASN.1 specifi‐
42              cations.
43
44       pem_entry() =
45           {pki_asn1_type(),
46            der_or_encrypted_der(),
47            not_encrypted | cipher_info()}
48
49       der_or_encrypted_der() = binary()
50
51       cipher_info() = {cipher(), cipher_info_params()}
52
53       cipher() = string()
54
55       salt() = binary()
56
57       cipher_info_params() =
58           salt() |
59           {#'PBEParameter'{}, digest_type()} |
60           #'PBES2-params'{}
61
62              Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC"
63
64              Salt could be generated with crypto:strong_rand_bytes(8).
65
66       public_key() =
67           rsa_public_key() |
68           rsa_pss_public_key() |
69           dsa_public_key() |
70           ec_public_key() |
71           ed_public_key()
72
73       rsa_public_key() = #'RSAPublicKey'{}
74
75       rsa_pss_public_key() =
76           {#'RSAPublicKey'{}, #'RSASSA-PSS-params'{}}
77
78       dsa_public_key() = {integer(), #'Dss-Parms'{}}
79
80       ec_public_key() = {#'ECPoint'{}, ecpk_parameters_api()}
81
82       ecpk_parameters() =
83           {ecParameters, #'ECParameters'{}} |
84           {namedCurve, Oid :: tuple()}
85
86       ecpk_parameters_api() =
87           ecpk_parameters() |
88           #'ECParameters'{} |
89           {namedCurve, Name :: crypto:ec_named_curve()}
90
91       ed_public_key() = {ed_pub, ed25519 | ed448, Key :: binary()}
92
93          Warning:
94              This  format  of  the  EdDSA  curves is temporary and may change
95              without prior notice!
96
97
98       private_key() =
99           rsa_private_key() |
100           rsa_pss_private_key() |
101           dsa_private_key() |
102           ec_private_key() |
103           ed_private_key()
104
105       rsa_private_key() = #'RSAPrivateKey'{}
106
107       rsa_pss_private_key() =
108           {#'RSAPrivateKey'{}, #'RSASSA-PSS-params'{}}
109
110       dsa_private_key() = #'DSAPrivateKey'{}
111
112       ec_private_key() = #'ECPrivateKey'{}
113
114       ed_private_key() =
115           {ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()}
116
117          Warning:
118              This format of the EdDSA curves  is  temporary  and  may  change
119              without prior notice!
120
121
122       key_params() =
123           #'DHParameter'{} |
124           {namedCurve, oid()} |
125           #'ECParameters'{} |
126           {rsa, Size :: integer(), PubExp :: integer()}
127
128       digest_type() =
129           none | sha1 |
130           crypto:rsa_digest_type() |
131           crypto:dss_digest_type() |
132           crypto:ecdsa_digest_type()
133
134       crl_reason() =
135           unspecified | keyCompromise | cACompromise |
136           affiliationChanged | superseded | cessationOfOperation |
137           certificateHold | privilegeWithdrawn | aACompromise
138
139       cert_id() = {SerialNr :: integer(), issuer_name()}
140
141       issuer_name() = {rdnSequence, [#'AttributeTypeAndValue'{}]}
142
143       ssh_file() =
144           openssh_public_key | rfc4716_public_key | known_hosts |
145           auth_keys
146

EXPORTS

148       compute_key(OthersECDHkey, MyECDHkey) -> SharedSecret
149
150              Types:
151
152                 OthersECDHkey = #'ECPoint'{}
153                 MyECDHkey = #'ECPrivateKey'{}
154                 SharedSecret = binary()
155
156              Computes shared secret.
157
158       compute_key(OthersDHkey, MyDHkey, DHparms) -> SharedSecret
159
160              Types:
161
162                 OthersDHkey = crypto:dh_public()
163                 MyDHkey = crypto:dh_private()
164                 DHparms = #'DHParameter'{}
165                 SharedSecret = binary()
166
167              Computes shared secret.
168
169       decrypt_private(CipherText, Key) -> PlainText
170
171       decrypt_private(CipherText, Key, Options) -> PlainText
172
173              Types:
174
175                 CipherText = binary()
176                 Key = rsa_private_key()
177                 Options = crypto:pk_encrypt_decrypt_opts()
178                 PlainText = binary()
179
180              Public-key   decryption   using   the   private  key.  See  also
181              crypto:private_decrypt/4
182
183       decrypt_public(CipherText, Key) -> PlainText
184
185       decrypt_public(CipherText, Key, Options) -> PlainText
186
187              Types:
188
189                 CipherText = binary()
190                 Key = rsa_public_key()
191                 Options = crypto:pk_encrypt_decrypt_opts()
192                 PlainText = binary()
193
194              Public-key decryption using the public key. See also crypto:pub‐
195              lic_decrypt/4
196
197       der_decode(Asn1Type, Der) -> Entity
198
199              Types:
200
201                 Asn1Type = asn1_type()
202                 Der = binary()
203                 Entity = term()
204
205              Decodes a public-key ASN.1 DER encoded entity.
206
207       der_encode(Asn1Type, Entity) -> Der
208
209              Types:
210
211                 Asn1Type = asn1_type()
212                 Entity = term()
213                 Der = binary()
214
215              Encodes a public-key entity with ASN.1 DER encoding.
216
217       dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) ->
218                       {ok, {Size, Group}} | {error, term()}
219
220              Types:
221
222                 MinSize = SuggestedSize = MaxSize = integer() >= 1
223                 Groups = undefined | [{Size, [Group]}]
224                 Size = integer() >= 1
225                 Group = {G, P}
226                 G = P = integer() >= 1
227
228              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
233              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
239              The default set of groups is listed in  lib/public_key/priv/mod‐
240              uli. This file may be regenerated like this:
241
242                   $> 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
248
249       encrypt_private(PlainText, Key) -> CipherText
250
251       encrypt_private(PlainText, Key, Options) -> CipherText
252
253              Types:
254
255                 PlainText = binary()
256                 Key = rsa_private_key()
257                 Options = crypto:pk_encrypt_decrypt_opts()
258                 CipherText = binary()
259
260              Public-key   encryption   using   the   private  key.  See  also
261              crypto:private_encrypt/4.
262
263       encrypt_public(PlainText, Key) -> CipherText
264
265       encrypt_public(PlainText, Key, Options) -> CipherText
266
267              Types:
268
269                 PlainText = binary()
270                 Key = rsa_public_key()
271                 Options = crypto:pk_encrypt_decrypt_opts()
272                 CipherText = binary()
273
274              Public-key encryption using the public key. See also crypto:pub‐
275              lic_encrypt/4.
276
277       generate_key(Params :: DHparams | ECparams | RSAparams) ->
278                       DHkeys | ECkey | RSAkey
279
280              Types:
281
282                 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
290              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
294       pem_decode(PemBin :: binary()) -> [pem_entry()]
295
296              Decodes PEM binary data and returns entries as ASN.1 DER encoded
297              entities.
298
299              Example {ok, PemBin} = file:read_file("cert.pem"). PemEntries  =
300              public_key:pem_decode(PemBin).
301
302       pem_encode(PemEntries :: [pem_entry()]) -> binary()
303
304              Creates a PEM binary.
305
306       pem_entry_decode(PemEntry) -> term()
307
308       pem_entry_decode(PemEntry, Password) -> term()
309
310              Types:
311
312                 PemEntry = pem_entry()
313                 Password = string()
314
315              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
320       pem_entry_encode(Asn1Type, Entity) -> pem_entry()
321
322       pem_entry_encode(Asn1Type, Entity, InfoPwd) -> pem_entry()
323
324              Types:
325
326                 Asn1Type = pki_asn1_type()
327                 Entity = term()
328                 InfoPwd = {CipherInfo, Password}
329                 CipherInfo = cipher_info()
330                 Password = string()
331
332              Creates a PEM entry that can be feed to pem_encode/1.
333
334              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
339       pkix_decode_cert(Cert, Type) ->
340                           #'Certificate'{} | #'OTPCertificate'{}
341
342              Types:
343
344                 Cert = der_encoded()
345                 Type = plain | otp
346
347              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
351       pkix_encode(Asn1Type, Entity, Type) -> Der
352
353              Types:
354
355                 Asn1Type = asn1_type()
356                 Entity = term()
357                 Type = otp | plain
358                 Der = der_encoded()
359
360              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
366       pkix_is_issuer(Cert, IssuerCert) -> boolean()
367
368              Types:
369
370                 Cert =
371                     der_encoded()    |   #'OTPCertificate'{}   |   #'Certifi‐
372                 cateList'{}
373                 IssuerCert = der_encoded() | #'OTPCertificate'{}
374
375              Checks if IssuerCert issued Cert.
376
377       pkix_is_fixed_dh_cert(Cert) -> boolean()
378
379              Types:
380
381                 Cert = der_encoded() | #'OTPCertificate'{}
382
383              Checks if a certificate is a fixed Diffie-Hellman certificate.
384
385       pkix_is_self_signed(Cert) -> boolean()
386
387              Types:
388
389                 Cert = der_encoded() | #'OTPCertificate'{}
390
391              Checks if a certificate is self-signed.
392
393       pkix_issuer_id(Cert, IssuedBy) ->
394                         {ok, ID :: cert_id()} | {error, Reason}
395
396              Types:
397
398                 Cert = der_encoded() | #'OTPCertificate'{}
399                 IssuedBy = self | other
400                 Reason = term()
401
402              Returns the x509 certificater issuer id, if  it  can  be  deter‐
403              mined.
404
405       pkix_normalize_name(Issuer) -> Normalized
406
407              Types:
408
409                 Issuer = Normalized = issuer_name()
410
411              Normalizes  an  issuer name so that it can be easily compared to
412              another issuer name.
413
414       pkix_path_validation(TrustedCert, CertChain, Options) -> {ok, {PublicK‐
415       eyInfo, PolicyTree}} | {error, {bad_cert, Reason}}
416
417              Types:
418
419                 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
439              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
443              Available options:
444
445                {verify_fun, {fun(), InitialUserState::term()}:
446                  The fun must be defined as:
447
448                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
457
458                  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
467            Warning:
468                Note that user defined custom verify_fun  may  alter  original
469                path validation error (e.g selfsigned_peer). Use with caution.
470
471
472                {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
481              Possible reasons for a bad certificate:
482
483                cert_expired:
484                  Certificate  is  no  longer valid as its expiration date has
485                  passed.
486
487                invalid_issuer:
488                  Certificate issuer name does  not  match  the  name  of  the
489                  issuer certificate in the chain.
490
491                invalid_signature:
492                  Certificate  was not signed by its issuer certificate in the
493                  chain.
494
495                name_not_permitted:
496                  Invalid Subject Alternative Name extension.
497
498                missing_basic_constraint:
499                  Certificate, required to have the basic  constraints  exten‐
500                  sion, does not have a basic constraints extension.
501
502                invalid_key_usage:
503                  Certificate  key  is used in an invalid way according to the
504                  key-usage extension.
505
506                {revoked, crl_reason()}:
507                  Certificate has been revoked.
508
509                atom():
510                  Application-specific error reason that is to be  checked  by
511                  the verify_fun.
512
513       pkix_crl_issuer(CRL :: CRL | #'CertificateList'{}) -> Issuer
514
515              Types:
516
517                 CRL = der_encoded()
518                 Issuer = issuer_name()
519
520              Returns the issuer of the CRL.
521
522       pkix_crls_validate(OTPcertificate, DPandCRLs, Options) ->
523                             CRLstatus
524
525              Types:
526
527                 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
540              Performs  CRL  validation.  It is intended to be called from the
541              verify fun of  pkix_path_validation/3 .
542
543              Available options:
544
545                {update_crl, fun()}:
546                  The fun has the following type specification:
547
548                 fun(#'DistributionPoint'{}, #'CertificateList'{}) ->
549                        #'CertificateList'{}
550
551                  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
556                 fun(_DP, CRL) -> CRL end
557
558                {issuer_fun, fun()}:
559                  The fun has the following type specification:
560
561                fun(#'DistributionPoint'{}, #'CertificateList'{},
562                    {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
563                     {ok, #'OTPCertificate'{}, [der_encoded]}
564
565                  The  fun  returns the root certificate and certificate chain
566                  that has signed the CRL.
567
568                 fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}
569
570                {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
575       pkix_crl_verify(CRL, Cert) -> boolean()
576
577              Types:
578
579                 CRL = der_encoded() | #'CertificateList'{}
580                 Cert = der_encoded() | #'OTPCertificate'{}
581
582              Verify that Cert is the CRL signer.
583
584       pkix_dist_point(Cert) -> DistPoint
585
586              Types:
587
588                 Cert = der_encoded() | #'OTPCertificate'{}
589                 DistPoint = #'DistributionPoint'{}
590
591              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
594       pkix_dist_points(Cert) -> DistPoints
595
596              Types:
597
598                 Cert = der_encoded() | #'OTPCertificate'{}
599                 DistPoints = [#'DistributionPoint'{}]
600
601              Extracts distribution points from the certificates extensions.
602
603       pkix_hash_type(HashOid :: oid()) ->
604                         DigestType ::
605                             md5 | crypto:sha1() | crypto:sha2()
606
607              Translates OID to Erlang digest type
608
609       pkix_match_dist_point(CRL, DistPoint) -> boolean()
610
611              Types:
612
613                 CRL = der_encoded() | #'CertificateList'{}
614                 DistPoint = #'DistributionPoint'{}
615
616              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
621       pkix_sign(Cert, Key) -> Der
622
623              Types:
624
625                 Cert = #'OTPTBSCertificate'{}
626                 Key = private_key()
627                 Der = der_encoded()
628
629              Signs an 'OTPTBSCertificate'.  Returns  the  corresponding  DER-
630              encoded certificate.
631
632       pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}
633
634              Types:
635
636                 AlgorithmId = oid()
637                 DigestType = crypto:rsa_digest_type()
638                 SignatureType = rsa | dsa | ecdsa
639
640              Translates  signature  algorithm OID to Erlang digest and signa‐
641              ture types.
642
643              The AlgorithmId is the signature OID from  a  certificate  or  a
644              certificate revocation list.
645
646       pkix_test_data(Options) -> Config
647       pkix_test_data([chain_opts()]) -> [conf_opt()]
648
649              Types:
650
651                 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
671              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
678              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
689              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
700              The cert_opt() type consists of the following options:
701
702                 {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
706                 {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
712                 {validity,     {From::erlang:timestamp(),    To::erlang:time‐
713                stamp()}} :
714                  The validity period of the certificate.
715
716                 {extensions, [#'Extension'{}]}:
717                  Extensions to include in the certificate.
718
719                  Default extensions included in CA certificates if not other‐
720                  wise specified are:
721
722                [#'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
729
730                  Default  extensions  included in the server peer cert if not
731                  otherwise specified are:
732
733                [#'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
740
741                  Hostname is the result of calling net_adm:localhost() in the
742                  Erlang node where this funcion is called.
743
744          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
750
751       pkix_test_root_cert(Name, Options) -> RootCert
752
753              Types:
754
755                 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
764              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
768       pkix_subject_id(Cert) -> ID
769
770              Types:
771
772                 Cert = der_encoded() | #'OTPCertificate'{}
773                 ID = cert_id()
774
775              Returns the X509 certificate subject id.
776
777       pkix_verify(Cert, Key) -> boolean()
778
779              Types:
780
781                 Cert = der_encoded()
782                 Key = public_key()
783
784              Verifies PKIX x.509 certificate signature.
785
786       pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()
787       pkix_verify_hostname(Cert, ReferenceIDs, Opts) -> boolean()
788
789              Types:
790
791                 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
810              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
817              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
821              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
825              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
829              The options are:
830
831                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
839                fun(....) -> true;   % My special case
840                   (_, _) -> default % all others falls back to the inherit tests
841                end
842
843                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
848                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
858                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
864                  * the hostname
865
866                  * the atom default: the default host name  extract  function
867                    will be used
868
869                  * the  atom  undefined:  a host name could not be extracted.
870                    The pkix_verify_hostname/3 will return false.
871
872                For an example, see Hostname extraction in the User's Guide.
873
874       pkix_verify_hostname_match_fun(Protcol) -> fun(RefId |  FQDN::string(),
875       PresentedID) -> boolean() | default
876
877              Types:
878
879                 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
889              The return value of calling this function is intended to be used
890              in the match_fun option in pkix_verify_hostname/3.
891
892              The returned fun augments the verify hostname matching according
893              to the specific rules for the protocol in the argument.
894
895       sign(Msg, DigestType, Key) -> Signature
896
897       sign(Msg, DigestType, Key, Options) -> Signature
898
899              Types:
900
901                 Msg = binary() | {digest, binary()}
902                 DigestType = digest_type()
903                 Key = private_key()
904                 Options = crypto:pk_sign_verify_opts()
905                 Signature = binary()
906
907              Creates a digital signature.
908
909              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
912       ssh_decode(SshBin, Type) -> Decoded
913
914              Types:
915
916                 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
925              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
931              If the Type is ssh2_pubkey, the result will be Decoded_ssh2_pub‐
932              key. Otherwise it will be Decoded_OtherType.
933
934                RFC4716 attributes - see RFC 4716.:
935                  {headers, [{string(), utf8_string()}]}
936
937                auth_key attributes - see manual page for sshd.:
938                  {comment, string()}{options, [string()]}{bits, integer()}  -
939                  In SSH version 1 files.
940
941                known_host attributes - see manual page for sshd.:
942                  {hostnames,  [string()]}{comment, string()}{bits, integer()}
943                  - In SSH version 1 files.
944
945              Example: {ok, SshBin} = file:read_file("known_hosts").
946
947              If Type is public_key the binary can be either an RFC4716 public
948              key or an OpenSSH public key.
949
950       ssh_encode(InData, Type) -> binary()
951
952              Types:
953
954                 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
962              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
966              If the Type is ssh2_pubkey, the InData shall be InData_ssh2_pub‐
967              key. Otherwise it shall be OtherInData.
968
969       ssh_hostkey_fingerprint(HostKey) -> string()
970       ssh_hostkey_fingerprint(DigestType, HostKey) -> string()
971       ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]
972
973              Types:
974
975                 HostKey = public_key()
976                 DigestType = digest_type()
977
978              Calculates a ssh fingerprint from a public host key  as  openssh
979              does.
980
981              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
986              Examples:
987
988               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
991               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
994               4> public_key:ssh_hostkey_fingerprint(sha,Key).
995               "SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY"
996
997               5> public_key:ssh_hostkey_fingerprint(sha256,Key).
998               "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"
999
1000               6> public_key:ssh_hostkey_fingerprint([sha,sha256],Key).
1001               ["SHA1:bSLY/C4QXLDL/Iwmhyg0PGW9UbY",
1002                "SHA256:aZGXhabfbf4oxglxltItWeHU7ub3Dc31NcNw2cMJePQ"]
1003
1004
1005       verify(Msg, DigestType, Signature, Key) -> boolean()
1006
1007       verify(Msg, DigestType, Signature, Key, Options) -> boolean()
1008
1009              Types:
1010
1011                 Msg = binary() | {digest, binary()}
1012                 DigestType = digest_type()
1013                 Signature = binary()
1014                 Key = public_key()
1015                 Options = crypto:pk_sign_verify_opts()
1016
1017              Verifies a digital signature.
1018
1019              The Msg is either the binary "plain text"  data  or  it  is  the
1020              hashed value of "plain text", that is, the digest.
1021
1022       short_name_hash(Name) -> string()
1023
1024              Types:
1025
1026                 Name = issuer_name()
1027
1028              Generates  a  short hash of an issuer name. The hash is returned
1029              as a string containing eight hexadecimal digits.
1030
1031              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.
1037
1038
1039
1040Ericsson AB                     public_key 1.10                  public_key(3)
Impressum