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       key_oid_name() =
31           rsaEncryption | 'id-RSASSA-PSS' | 'id-ecPublicKey' |
32           'id-Ed25519' | 'id-Ed448' | 'id-dsa'
33
34              Macro names for key object identifiers used by prefixing with ?
35
36       der_encoded() = binary()
37
38       pki_asn1_type() =
39           'Certificate' | 'RSAPrivateKey' | 'RSAPublicKey' |
40           'SubjectPublicKeyInfo' | 'DSAPrivateKey' | 'DHParameter' |
41           'PrivateKeyInfo' | 'CertificationRequest' | 'ContentInfo' |
42           'CertificateList' | 'ECPrivateKey' | 'OneAsymmetricKey' |
43           'EcpkParameters'
44
45       asn1_type() = atom()
46
47              ASN.1 type present in the Public Key applications ASN.1 specifi‐
48              cations.
49
50       pem_entry() =
51           {pki_asn1_type(),
52            der_or_encrypted_der(),
53            not_encrypted | cipher_info()}
54
55       der_or_encrypted_der() = binary()
56
57       cipher_info() = {cipher(), cipher_info_params()}
58
59       cipher() = string()
60
61       salt() = binary()
62
63       cipher_info_params() =
64           salt() |
65           {#'PBEParameter'{}, digest_type()} |
66           #'PBES2-params'{}
67
68              Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC"
69
70              Salt could be generated with crypto:strong_rand_bytes(8).
71
72       public_key() =
73           rsa_public_key() |
74           rsa_pss_public_key() |
75           dsa_public_key() |
76           ec_public_key() |
77           ed_public_key()
78
79       rsa_public_key() = #'RSAPublicKey'{}
80
81       dss_public_key() = integer()
82
83       rsa_pss_public_key() =
84           {rsa_pss_public_key(), #'RSASSA-PSS-params'{}}
85
86       dsa_public_key() = {dss_public_key(), #'Dss-Parms'{}}
87
88       ec_public_key() = {#'ECPoint'{}, ecpk_parameters_api()}
89
90       public_key_params() =
91           'NULL' |
92           #'RSASSA-PSS-params'{} |
93           {namedCurve, oid()} |
94           #'ECParameters'{} |
95           #'Dss-Parms'{}
96
97       ecpk_parameters() =
98           {ecParameters, #'ECParameters'{}} |
99           {namedCurve, Oid :: tuple()}
100
101       ecpk_parameters_api() =
102           ecpk_parameters() |
103           #'ECParameters'{} |
104           {namedCurve, Name :: crypto:ec_named_curve()}
105
106       public_key_info() =
107           {key_oid_name(),
108            rsa_public_key() | #'ECPoint'{} | dss_public_key(),
109            public_key_params()}
110
111       ed_public_key() = {#'ECPoint'{}, ed_params()}
112
113       ed_params() = {namedCurve, ed_oid_name()}
114
115       private_key() =
116           rsa_private_key() |
117           rsa_pss_private_key() |
118           dsa_private_key() |
119           ec_private_key() |
120           ed_private_key()
121
122       rsa_private_key() = #'RSAPrivateKey'{}
123
124       rsa_pss_private_key() =
125           {#'RSAPrivateKey'{}, #'RSASSA-PSS-params'{}}
126
127       dsa_private_key() = #'DSAPrivateKey'{}
128
129       ec_private_key() = #'ECPrivateKey'{}
130
131       ed_private_key() = #'ECPrivateKey'{parameters = ed_params()}
132
133       ed_oid_name() = 'id-Ed25519' | 'id-Ed448'
134
135              Macro names for object identifiers for EDDSA curves used by pre‐
136              fixing with ?
137
138       key_params() =
139           #'DHParameter'{} |
140           {namedCurve, oid()} |
141           #'ECParameters'{} |
142           {rsa, Size :: integer(), PubExp :: integer()}
143
144       digest_type() =
145           none | sha1 |
146           crypto:rsa_digest_type() |
147           crypto:dss_digest_type() |
148           crypto:ecdsa_digest_type()
149
150       issuer_name() = {rdnSequence, [[#'AttributeTypeAndValue'{}]]}
151
152       referenceIDs() = [referenceID()]
153
154       referenceID() =
155           {uri_id | dns_id | ip | srv_id | atom() | oid(), string()} |
156           {ip, inet:ip_address() | string()}
157
158       cert_id() = {SerialNr :: integer(), issuer_name()}
159
160       cert() = der_cert() | otp_cert()
161
162       otp_cert() = #'OTPCertificate'{}
163
164       der_cert() = der_encoded()
165
166       combined_cert() =
167           #cert{der = public_key:der_encoded(),
168                 otp = #'OTPCertificate'{}}
169
170       bad_cert_reason() =
171           cert_expired | invalid_issuer | invalid_signature |
172           name_not_permitted | missing_basic_constraint |
173           invalid_key_usage |
174           {revoked, crl_reason()} |
175           atom()
176
177       crl_reason() =
178           unspecified | keyCompromise | cACompromise |
179           affiliationChanged | superseded | cessationOfOperation |
180           certificateHold | privilegeWithdrawn | aACompromise
181
182       chain_opts() =
183           #{chain_end() := [cert_opt()],
184             intermediates => [[cert_opt()]]}
185
186       chain_end() = root | peer
187
188       cert_opt() =
189           {digest, public_key:digest_type()} |
190           {key, public_key:key_params() | public_key:private_key()} |
191           {validity,
192            {From :: erlang:timestamp(), To :: erlang:timestamp()}} |
193           {extensions, [#'Extension'{}]}
194
195       test_root_cert() =
196           #{cert := der_encoded(), key := public_key:private_key()}
197
198       test_config() =
199           #{server_config := [conf_opt()],
200             client_config := [conf_opt()]}
201
202       conf_opt() =
203           {cert, public_key:der_encoded()} |
204           {key, public_key:private_key()} |
205           {cacerts, [public_key:der_encoded()]}
206

EXPORTS

208       cacerts_clear() -> boolean()
209
210              Clears any loaded CA  certificates,  returns  true  if  any  was
211              loaded.
212
213       cacerts_get() -> [combined_cert()]
214
215              Returns the trusted CA certificates if any are loaded, otherwise
216              uses cacerts_load/0 to load them. The function fails if no  cac‐
217              erts could be loaded.
218
219       cacerts_load() -> ok | {error, Reason :: term()}
220
221              Loads the OS supplied trusted CA certificates.
222
223       cacerts_load(File :: file:filename_all()) ->
224                       ok | {error, Reason :: term()}
225
226              Loads the trusted CA certificates from a file.
227
228       compute_key(OthersECDHkey, MyECDHkey) -> SharedSecret
229
230              Types:
231
232                 OthersECDHkey = #'ECPoint'{}
233                 MyECDHkey = #'ECPrivateKey'{}
234                 SharedSecret = binary()
235
236              Computes shared secret.
237
238       compute_key(OthersDHkey, MyDHkey, DHparms) -> SharedSecret
239
240              Types:
241
242                 OthersDHkey = crypto:dh_public()
243                 MyDHkey = crypto:dh_private()
244                 DHparms = #'DHParameter'{}
245                 SharedSecret = binary()
246
247              Computes shared secret.
248
249       decrypt_private(CipherText, Key) -> PlainText
250
251       decrypt_private(CipherText, Key, Options) -> PlainText
252
253              Types:
254
255                 CipherText = binary()
256                 Key = rsa_private_key()
257                 Options = crypto:pk_encrypt_decrypt_opts()
258                 PlainText = binary()
259
260              Public-key   decryption   using   the   private  key.  See  also
261              crypto:private_decrypt/4
262
263       decrypt_public(CipherText, Key) -> PlainText
264
265       decrypt_public(CipherText, Key, Options) -> PlainText
266
267              Types:
268
269                 CipherText = binary()
270                 Key = rsa_public_key()
271                 Options = crypto:pk_encrypt_decrypt_opts()
272                 PlainText = binary()
273
274              Public-key decryption using the public key. See also crypto:pub‐
275              lic_decrypt/4
276
277       der_decode(Asn1Type, Der) -> Entity
278
279              Types:
280
281                 Asn1Type = asn1_type()
282                 Der = der_encoded()
283                 Entity = term()
284
285              Decodes a public-key ASN.1 DER encoded entity.
286
287       der_encode(Asn1Type, Entity) -> Der
288
289              Types:
290
291                 Asn1Type = asn1_type()
292                 Entity = term()
293                 Der = binary()
294
295              Encodes a public-key entity with ASN.1 DER encoding.
296
297       dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) ->
298                       {ok, {Size, Group}} | {error, term()}
299
300              Types:
301
302                 MinSize = SuggestedSize = MaxSize = integer() >= 1
303                 Groups = undefined | [{Size, [Group]}]
304                 Size = integer() >= 1
305                 Group = {G, P}
306                 G = P = integer() >= 1
307
308              Selects  a  group  for  Diffie-Hellman key exchange with the key
309              size in the range MinSize...MaxSize and as close  to  Suggested‐
310              Size  as  possible. If Groups == undefined a default set will be
311              used, otherwise the group is selected from Groups.
312
313              First a size, as close as  possible  to  SuggestedSize,  is  se‐
314              lected.  Then  one group with that key size is randomly selected
315              from the specified set of groups. If no size within  the  limits
316              of  MinSize  and MaxSize is available, {error,no_group_found} is
317              returned.
318
319              The default set of groups is listed in  lib/public_key/priv/mod‐
320              uli. This file may be regenerated like this:
321
322                   $> cd $ERL_TOP/lib/public_key/priv/
323                   $> generate
324                       ---- wait until all background jobs has finished. It may take several days !
325                   $> cat moduli-* > moduli
326                   $> cd ..; make
327
328
329       encrypt_private(PlainText, Key) -> CipherText
330
331       encrypt_private(PlainText, Key, Options) -> CipherText
332
333              Types:
334
335                 PlainText = binary()
336                 Key = rsa_private_key()
337                 Options = crypto:pk_encrypt_decrypt_opts()
338                 CipherText = binary()
339
340              Public-key   encryption   using   the   private  key.  See  also
341              crypto:private_encrypt/4.
342
343       encrypt_public(PlainText, Key) -> CipherText
344
345       encrypt_public(PlainText, Key, Options) -> CipherText
346
347              Types:
348
349                 PlainText = binary()
350                 Key = rsa_public_key()
351                 Options = crypto:pk_encrypt_decrypt_opts()
352                 CipherText = binary()
353
354              Public-key encryption using the public key. See also crypto:pub‐
355              lic_encrypt/4.
356
357       generate_key(Params :: DHparams | ECparams | RSAparams) ->
358                       DHkeys | ECkey | RSAkey
359
360              Types:
361
362                 DHparams = #'DHParameter'{}
363                 DHkeys = {PublicDH :: binary(), PrivateDH :: binary()}
364                 ECparams = ecpk_parameters_api()
365                 ECkey = #'ECPrivateKey'{}
366                 RSAparams = {rsa, Size, PubExp}
367                 Size = PubExp = integer() >= 1
368                 RSAkey = #'RSAPrivateKey'{}
369
370              Generates  a  new  key pair. Note that except for Diffie-Hellman
371              the public key is included in the  private  key  structure.  See
372              also crypto:generate_key/2
373
374       pem_decode(PemBin :: binary()) -> [pem_entry()]
375
376              Decodes PEM binary data and returns entries as ASN.1 DER encoded
377              entities.
378
379              Example {ok, PemBin} = file:read_file("cert.pem"). PemEntries  =
380              public_key:pem_decode(PemBin).
381
382       pem_encode(PemEntries :: [pem_entry()]) -> binary()
383
384              Creates a PEM binary.
385
386       pem_entry_decode(PemEntry) -> term()
387
388       pem_entry_decode(PemEntry, Password) -> term()
389
390              Types:
391
392                 PemEntry = pem_entry()
393                 Password = iodata() | fun(() -> iodata())
394
395              Decodes a PEM entry. pem_decode/1 returns a list of PEM entries.
396              Notice that if the PEM entry is of type  'SubjectPublickeyInfo',
397              it  is  further  decoded  to  an  rsa_public_key()  or  dsa_pub‐
398              lic_key().
399
400              Password can be either an octet string or function which returns
401              same type.
402
403       pem_entry_encode(Asn1Type, Entity) -> pem_entry()
404
405       pem_entry_encode(Asn1Type, Entity, InfoPwd) -> pem_entry()
406
407              Types:
408
409                 Asn1Type = pki_asn1_type()
410                 Entity = term()
411                 InfoPwd = {CipherInfo, Password}
412                 CipherInfo = cipher_info()
413                 Password = iodata()
414
415              Creates a PEM entry that can be feed to pem_encode/1.
416
417              If  Asn1Type is 'SubjectPublicKeyInfo', Entity must be either an
418              rsa_public_key(), dsa_public_key()  or  an  ec_public_key()  and
419              this function creates the appropriate 'SubjectPublicKeyInfo' en‐
420              try.
421
422       pkix_decode_cert(Cert, Type) -> #'Certificate'{} | otp_cert()
423
424              Types:
425
426                 Cert = der_cert()
427                 Type = plain | otp
428
429              Decodes an ASN.1 DER-encoded PKIX certificate. Option  otp  uses
430              the  customized  ASN.1  specification OTP-PKIX.asn1 for decoding
431              and also recursively decode most of the standard parts.
432
433       pkix_encode(Asn1Type, Entity, Type) -> Der
434
435              Types:
436
437                 Asn1Type = asn1_type()
438                 Entity = term()
439                 Type = otp | plain
440                 Der = der_encoded()
441
442              DER encodes a PKIX x509 certificate or part of such  a  certifi‐
443              cate.  This  function  must be used for encoding certificates or
444              parts of certificates that are decoded/created in the  otp  for‐
445              mat,  whereas  for the plain format this function directly calls
446              der_encode/2.
447
448          Note:
449              Subtle ASN-1 encoding  errors  in  certificates  may  be  worked
450              around when decoding, this may have the affect that the encoding
451              a certificate back to DER may generate different bytes then  the
452              supplied original.
453
454
455       pkix_is_issuer(CertorCRL, IssuerCert) -> boolean()
456
457              Types:
458
459                 CertorCRL = cert() | #'CertificateList'{}
460                 IssuerCert = cert()
461
462              Checks if IssuerCert issued Cert.
463
464       pkix_is_fixed_dh_cert(Cert) -> boolean()
465
466              Types:
467
468                 Cert = cert()
469
470              Checks if a certificate is a fixed Diffie-Hellman certificate.
471
472       pkix_is_self_signed(Cert) -> boolean()
473
474              Types:
475
476                 Cert = cert()
477
478              Checks if a certificate is self-signed.
479
480       pkix_issuer_id(Cert, IssuedBy) ->
481                         {ok, ID :: cert_id()} | {error, Reason}
482
483              Types:
484
485                 Cert = cert()
486                 IssuedBy = self | other
487                 Reason = term()
488
489              Returns the x509 certificate issuer id, if it can be determined.
490
491       pkix_normalize_name(Issuer) -> Normalized
492
493              Types:
494
495                 Issuer = issuer_name() | der_encoded()
496                 Normalized = issuer_name()
497
498              Normalizes  an  issuer name so that it can be easily compared to
499              another issuer name.
500
501       pkix_path_validation(Cert, CertChain, Options) ->
502                               {ok, {PublicKeyInfo, PolicyTree}} |
503                               {error,
504                                {bad_cert, Reason :: bad_cert_reason()}}
505
506              Types:
507
508                 Cert = cert() | atom()
509                 CertChain = [cert() | combined_cert()]
510                 Options =
511                     [{max_path_length, integer()} |
512                      {verify_fun, {function(), term()}}]
513                 PublicKeyInfo = public_key_info()
514                 PolicyTree = list()
515
516              Performs a basic path validation according to RFC 5280. However,
517              CRL  validation  is done separately by pkix_crls_validate/3  and
518              is to be called from the supplied verify_fun. The optional  pol‐
519              icy  tree  check is currently not implemented but an empty place
520              holder list is returned instead.
521
522              Available options:
523
524                {verify_fun, {fun(), InitialUserState::term()}:
525                  The fun must be defined as:
526
527                fun(OtpCert :: #'OTPCertificate'{},
528                    Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
529                             {extension, #'Extension'{}},
530                    InitialUserState :: term()) ->
531                     {valid, UserState :: term()} |
532                     {valid_peer, UserState :: term()} |
533                     {fail, Reason :: term()} |
534                     {unknown, UserState :: term()}.
535
536
537                  If the verify callback fun returns {fail, Reason}, the veri‐
538                  fication process is immediately stopped. If the verify call‐
539                  back  fun  returns  {valid,  UserState},  the   verification
540                  process  is  continued.  This can be used to accept specific
541                  path validation errors, such as selfsigned_peer, as well  as
542                  verifying application-specific extensions. If called with an
543                  extension unknown to the user application, the return  value
544                  {unknown, UserState} is to be used.
545
546            Warning:
547                Note  that  user  defined custom verify_fun may alter original
548                path validation error (e.g selfsigned_peer). Use with caution.
549
550
551                {max_path_length, integer()}:
552                   The max_path_length is the maximum number  of  non-self-is‐
553                  sued intermediate certificates that can follow the peer cer‐
554                  tificate   in   a   valid   certification   path.   So,   if
555                  max_path_length is 0, the PEER must be signed by the trusted
556                  ROOT-CA directly, if it is 1, the  path  can  be  PEER,  CA,
557                  ROOT-CA,  if it is 2, the path can be PEER, CA, CA, ROOT-CA,
558                  and so on.
559
560              Explanations of reasons for a bad certificate:
561
562                cert_expired:
563                  Certificate is no longer valid as its  expiration  date  has
564                  passed.
565
566                invalid_issuer:
567                  Certificate  issuer  name does not match the name of the is‐
568                  suer certificate in the chain.
569
570                invalid_signature:
571                  Certificate was not signed by its issuer certificate in  the
572                  chain.
573
574                name_not_permitted:
575                  Invalid Subject Alternative Name extension.
576
577                missing_basic_constraint:
578                  Certificate,  required  to have the basic constraints exten‐
579                  sion, does not have a basic constraints extension.
580
581                invalid_key_usage:
582                  Certificate key is used in an invalid way according  to  the
583                  key-usage extension.
584
585                {revoked, crl_reason()}:
586                  Certificate has been revoked.
587
588                atom():
589                  Application-specific  error  reason that is to be checked by
590                  the verify_fun.
591
592       pkix_crl_issuer(CRL) -> Issuer
593
594              Types:
595
596                 CRL = der_encoded() | #'CertificateList'{}
597                 Issuer = issuer_name()
598
599              Returns the issuer of the CRL.
600
601       pkix_crls_validate(OTPcertificate, DPandCRLs, Options) ->
602                             CRLstatus
603
604              Types:
605
606                 OTPcertificate = #'OTPCertificate'{}
607                 DPandCRLs = [DPandCRL]
608                 DPandCRL = {DP, {DerCRL, CRL}}
609                 DP = #'DistributionPoint'{}
610                 DerCRL = der_encoded()
611                 CRL = #'CertificateList'{}
612                 Options = [{atom(), term()}]
613                 CRLstatus = valid | {bad_cert, BadCertReason}
614                 BadCertReason =
615                     revocation_status_undetermined |
616                     {revocation_status_undetermined, Reason :: term()} |
617                     {revoked, crl_reason()}
618
619              Performs CRL validation. It is intended to be  called  from  the
620              verify fun of  pkix_path_validation/3 .
621
622              Available options:
623
624                {update_crl, fun()}:
625                  The fun has the following type specification:
626
627                 fun(#'DistributionPoint'{}, #'CertificateList'{}) ->
628                        #'CertificateList'{}
629
630                  The  fun  uses  the information in the distribution point to
631                  access the latest possible version of the CRL. If  this  fun
632                  is  not  specified,  Public Key uses the default implementa‐
633                  tion:
634
635                 fun(_DP, CRL) -> CRL end
636
637                {issuer_fun, fun()}:
638                  The fun has the following type specification:
639
640                fun(#'DistributionPoint'{}, #'CertificateList'{},
641                    {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) ->
642                     {ok, #'OTPCertificate'{}, [der_encoded]}
643
644                  The fun returns the root certificate and  certificate  chain
645                  that has signed the CRL.
646
647                 fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}
648
649                {undetermined_details, boolean()}:
650                  Defaults  to  false. When revocation status cannot be deter‐
651                  mined, and this option is set to true,  details  of  why  no
652                  CRLs where accepted are included in the return value.
653
654       pkix_crl_verify(CRL, Cert) -> boolean()
655
656              Types:
657
658                 CRL = der_encoded() | #'CertificateList'{}
659                 Cert = cert()
660
661              Verify that Cert is the CRL signer.
662
663       pkix_dist_point(Cert) -> DistPoint
664
665              Types:
666
667                 Cert = cert()
668                 DistPoint = #'DistributionPoint'{}
669
670              Creates  a distribution point for CRLs issued by the same issuer
671              as Cert. Can be used as input to pkix_crls_validate/3
672
673       pkix_dist_points(Cert) -> DistPoints
674
675              Types:
676
677                 Cert = cert()
678                 DistPoints = [#'DistributionPoint'{}]
679
680              Extracts distribution points from the certificates extensions.
681
682       pkix_hash_type(HashOid :: oid()) ->
683                         DigestType ::
684                             md5 | crypto:sha1() | crypto:sha2()
685
686              Translates OID to Erlang digest type
687
688       pkix_match_dist_point(CRL, DistPoint) -> boolean()
689
690              Types:
691
692                 CRL = der_encoded() | #'CertificateList'{}
693                 DistPoint = #'DistributionPoint'{}
694
695              Checks whether the given distribution point matches the  Issuing
696              Distribution  Point of the CRL, as described in RFC 5280. If the
697              CRL doesn't have an Issuing Distribution  Point  extension,  the
698              distribution point always matches.
699
700       pkix_sign(Cert, Key) -> Der
701
702              Types:
703
704                 Cert = #'OTPTBSCertificate'{}
705                 Key = private_key()
706                 Der = der_encoded()
707
708              Signs  an 'OTPTBSCertificate'. Returns the corresponding DER-en‐
709              coded certificate.
710
711       pkix_sign_types(AlgorithmId) -> {DigestType, SignatureType}
712
713              Types:
714
715                 AlgorithmId = oid()
716                 DigestType = crypto:rsa_digest_type() | none
717                 SignatureType = rsa | dsa | ecdsa | eddsa
718
719              Translates signature algorithm OID to Erlang digest  and  signa‐
720              ture types.
721
722              The  AlgorithmId  is  the  signature OID from a certificate or a
723              certificate revocation list.
724
725       pkix_test_data(ChainConf) -> TestConf
726
727              Types:
728
729                 ChainConf =
730                     #{server_chain   :=   chain_opts(),    client_chain    :=
731                 chain_opts()} |
732                     chain_opts()
733                 TestConf = test_config() | [conf_opt()]
734
735              Creates  certificate  configuration(s) consisting of certificate
736              and its private key plus CA certificate bundle, for a client and
737              a  server,  intended to facilitate automated testing of applica‐
738              tions using X509-certificates, often through SSL/TLS.  The  test
739              data  can be used when you have control over both the client and
740              the server in a test scenario.
741
742              When this function is called with a map  containing  client  and
743              server  chain  specifications;  it generates both a client and a
744              server certificate chain where  the  cacerts  returned  for  the
745              server  contains  the  root cert the server should trust and the
746              intermediate certificates the server should present to  connect‐
747              ing  clients.  The  root cert the server should trust is the one
748              used as root of the client certificate chain. Vice versa applies
749              to the cacerts returned for the client. The root cert(s) can ei‐
750              ther be pre-generated with  pkix_test_root_cert/2 ,  or  if  op‐
751              tions are specified; it is (they are) generated.
752
753              When this function is called with a list of certificate options;
754              it generates a configuration  with  just  one  node  certificate
755              where  cacerts contains the root cert and the intermediate certs
756              that should be presented to a peer. In this case the  same  root
757              cert  must  be used for all peers. This is useful in for example
758              an Erlang distributed cluster where any  node,  towards  another
759              node,  acts  either  as a server or as a client depending on who
760              connects to whom. The generated certificate contains  a  subject
761              altname,  which is not needed in a client certificate, but makes
762              the certificate useful for both roles.
763
764              Explanation of the options used to customize certificates in the
765              generated chains:
766
767                 {digest, digest_type()}:
768                  Hash  algorithm  to  be used for signing the certificate to‐
769                  gether with the key option. Defaults to sha that is sha1.
770
771                 {key, key_params() | private_key()}:
772                  Parameters to be used to call public_key:generate_key/1,  to
773                  generate  a  key, or an existing key. Defaults to generating
774                  an ECDSA key. Note this could fail if Erlang/OTP is compiled
775                  with a very old cryptolib.
776
777                 {validity,     {From::erlang:timestamp(),    To::erlang:time‐
778                stamp()}} :
779                  The validity period of the certificate.
780
781                 {extensions, [#'Extension'{}]}:
782                  Extensions to include in the certificate.
783
784                  Default extensions included in CA certificates if not other‐
785                  wise specified are:
786
787                [#'Extension'{extnID = ?'id-ce-keyUsage',
788                              extnValue = [keyCertSign, cRLSign],
789                              critical = false},
790                #'Extension'{extnID = ?'id-ce-basicConstraints',
791                             extnValue = #'BasicConstraints'{cA = true},
792                             critical = true}]
793
794
795                  Default  extensions  included in the server peer cert if not
796                  otherwise specified are:
797
798                [#'Extension'{extnID = ?'id-ce-keyUsage',
799                              extnValue = [digitalSignature, keyAgreement],
800                              critical = false},
801                #'Extension'{extnID = ?'id-ce-subjectAltName',
802                             extnValue = [{dNSName, Hostname}],
803                             critical = false}]
804
805
806                  Hostname is the result of calling net_adm:localhost() in the
807                  Erlang node where this function is called.
808
809          Note:
810              Note that the generated certificates and keys does not provide a
811              formally correct PKIX-trust-chain and they  cannot  be  used  to
812              achieve  real  security.  This  function is provided for testing
813              purposes only.
814
815
816       pkix_test_root_cert(Name, Options) -> RootCert
817
818              Types:
819
820                 Name = string()
821                 Options = [cert_opt()]
822                 RootCert = test_root_cert()
823
824              Generates a root certificate that can be used in multiple  calls
825              to  pkix_test_data/1 when you want the same root certificate for
826              several generated certificates.
827
828       pkix_subject_id(Cert) -> ID
829
830              Types:
831
832                 Cert = cert()
833                 ID = cert_id()
834
835              Returns the X509 certificate subject id.
836
837       pkix_verify(Cert, Key) -> boolean()
838
839              Types:
840
841                 Cert = der_cert()
842                 Key = public_key()
843
844              Verifies PKIX x.509 certificate signature.
845
846       pkix_verify_hostname(Cert, ReferenceIDs) -> boolean()
847
848       pkix_verify_hostname(Cert, ReferenceIDs, Options) -> boolean()
849
850              Types:
851
852                 Cert = cert()
853                 ReferenceIDs = referenceIDs()
854                 Options =  [{match_fun  |  fail_callback  |  fqdn_fun,  func‐
855                 tion()}]
856
857              This  function  checks that the Presented Identifier  (e.g host‐
858              name) in a peer certificate is in agreement with at least one of
859              the  Reference  Identifier   that  the client expects to be con‐
860              nected to. The function is intended to  be  added  as  an  extra
861              client  check  of  the  peer  certificate  when  performing pub‐
862              lic_key:pkix_path_validation/3
863
864              See RFC 6125 for detailed information about  hostname  verifica‐
865              tion. The User's Guide and code examples describes this function
866              more detailed.
867
868              The option funs are described here:
869
870                match_fun:
871
872
873                fun(ReferenceId::ReferenceId() | FQDN::string(),
874                    PresentedId::{dNSName,string()} | {uniformResourceIdentifier,string() |
875                                 {iPAddress,list(byte())} | {OtherId::atom()|oid(),term()}})
876
877                fun(....) -> true;   % My special case
878                   (_, _) -> default % all others falls back to the inherit tests
879                end
880
881                See pkix_verify_hostname_match_fun/1 for a function that takes
882                a  protocol  name as argument and returns a fun/2 suitable for
883                this option and Re-defining the match operation in the  User's
884                Guide for an example.
885
886            Note:
887                Reference  Id  values  given  as binaries will be converted to
888                strings, and ip references may be given in string format  that
889                is  "10.0.1.1"  or  "1234::5678:9012" as well as on the format
890                inet:ip_address()
891
892
893                fail_callback:
894                  If a matching fails, there could be circumstances  when  the
895                  certificate  should be accepted anyway. Think for example of
896                  a web browser where you choose to accept  an  outdated  cer‐
897                  tificate.  This option enables implementation of such an ex‐
898                  ception but for hostnames. This fun/1 is called when no Ref‐
899                  erenceID  matches. The return value of the fun (a boolean())
900                  decides the outcome. If true the the certificate is accepted
901                  otherwise it is rejected. See "Pinning" a Certificate in the
902                  User's Guide.
903
904                fqdn_fun:
905                  This option augments the host name extraction from URIs  and
906                  other  Reference IDs. It could for example be a very special
907                  URI that is not standardised. The fun takes a  Reference  ID
908                  as argument and returns one of:
909
910                  * the hostname
911
912                  * the  atom  default: the default host name extract function
913                    will be used
914
915                  * the atom undefined: a host name could  not  be  extracted.
916                    The pkix_verify_hostname/3 will return false.
917
918                For an example, see Hostname extraction in the User's Guide.
919
920       pkix_verify_hostname_match_fun(Protocol) -> Result
921
922              Types:
923
924                 Protocol = https
925                 Result = function()
926
927              The return value of calling this function is intended to be used
928              in the match_fun option in pkix_verify_hostname/3.
929
930              The returned fun augments the verify hostname matching according
931              to the specific rules for the protocol in the argument.
932
933          Note:
934              Currently  supported  https  fun will allow wildcard certificate
935              matching as specified by the HTTP standard. Note  that  for  in‐
936              stance  LDAP have a different set of wildcard matching rules. If
937              you do not want to allow wildcard certificates (recommended from
938              a  security  perspective)  or  otherwise  customize the hostname
939              match the default match function used by ssl application will be
940              sufficient.
941
942
943       sign(Msg, DigestType, Key) -> Signature
944
945       sign(Msg, DigestType, Key, Options) -> Signature
946
947              Types:
948
949                 Msg = binary() | {digest, binary()}
950                 DigestType = digest_type()
951                 Key = private_key()
952                 Options = crypto:pk_sign_verify_opts()
953                 Signature = binary()
954
955              Creates a digital signature.
956
957              The  Msg  is either the binary "plain text" data to be signed or
958              it is the hashed value of "plain text", that is, the digest.
959
960       verify(Msg, DigestType, Signature, Key) -> boolean()
961
962       verify(Msg, DigestType, Signature, Key, Options) -> boolean()
963
964              Types:
965
966                 Msg = binary() | {digest, binary()}
967                 DigestType = digest_type()
968                 Signature = binary()
969                 Key = public_key()
970                 Options = crypto:pk_sign_verify_opts()
971
972              Verifies a digital signature.
973
974              The Msg is either the binary "plain text"  data  or  it  is  the
975              hashed value of "plain text", that is, the digest.
976
977       short_name_hash(Name) -> string()
978
979              Types:
980
981                 Name = issuer_name()
982
983              Generates  a  short hash of an issuer name. The hash is returned
984              as a string containing eight hexadecimal digits.
985
986              The return value of this function is the same as the  result  of
987              the  commands  openssl  crl -hash and openssl x509 -issuer_hash,
988              when passed the issuer name of a CRL or a  certificate,  respec‐
989              tively. This hash is used by the c_rehash tool to maintain a di‐
990              rectory of symlinks to CRL files, in order to facilitate looking
991              up a CRL by its issuer name.
992
993
994
995Ericsson AB                   public_key 1.13.3.1                public_key(3)
Impressum