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           dsa_public_key() |
69           ec_public_key() |
70           ed_public_key()
71
72       rsa_public_key() = #'RSAPublicKey'{}
73
74       dsa_public_key() = {integer(), #'Dss-Parms'{}}
75
76       ec_public_key() = {#'ECPoint'{}, ecpk_parameters_api()}
77
78       ecpk_parameters() =
79           {ecParameters, #'ECParameters'{}} |
80           {namedCurve, Oid :: tuple()}
81
82       ecpk_parameters_api() =
83           ecpk_parameters() |
84           #'ECParameters'{} |
85           {namedCurve, Name :: crypto:ec_named_curve()}
86
87       ed_public_key() = {ed_pub, ed25519 | ed448, Key :: binary()}
88
89          Warning:
90              This  format  of  the  EdDSA  curves is temporary and may change
91              without prior notice!
92
93
94       private_key() =
95           rsa_private_key() |
96           dsa_private_key() |
97           ec_private_key() |
98           ed_private_key()
99
100       rsa_private_key() = #'RSAPrivateKey'{}
101
102       dsa_private_key() = #'DSAPrivateKey'{}
103
104       ec_private_key() = #'ECPrivateKey'{}
105
106       ed_private_key() =
107           {ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()}
108
109          Warning:
110              This format of the EdDSA curves  is  temporary  and  may  change
111              without prior notice!
112
113
114       key_params() =
115           #'DHParameter'{} |
116           {namedCurve, oid()} |
117           #'ECParameters'{} |
118           {rsa, Size :: integer(), PubExp :: integer()}
119
120       digest_type() =
121           none | sha1 |
122           crypto:rsa_digest_type() |
123           crypto:dss_digest_type() |
124           crypto:ecdsa_digest_type()
125
126       crl_reason() =
127           unspecified | keyCompromise | cACompromise |
128           affiliationChanged | superseded | cessationOfOperation |
129           certificateHold | privilegeWithdrawn | aACompromise
130
131       issuer_id() = {SerialNr :: integer(), issuer_name()}
132
133       issuer_name() = {rdnSequence, [#'AttributeTypeAndValue'{}]}
134
135       ssh_file() =
136           openssh_public_key | rfc4716_public_key | known_hosts |
137           auth_keys
138

EXPORTS

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