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

NAME

6       crypto - Crypto Functions
7

DESCRIPTION

9       This module provides a set of cryptographic functions.
10
11         Hash functions:
12
13
14           SHA1, SHA2:
15              Secure Hash Standard [FIPS PUB 180-4]
16
17           SHA3:
18              SHA-3  Standard:  Permutation-Based  Hash  and Extendable-Output
19             Functions [FIPS PUB 202]
20
21           BLAKE2:
22             BLAKE2 — fast secure hashing
23
24           MD5:
25             The MD5 Message Digest Algorithm [RFC 1321]
26
27           MD4:
28             The MD4 Message Digest Algorithm [RFC 1320]
29
30         MACs - Message Authentication Codes:
31
32
33           Hmac functions:
34              Keyed-Hashing for Message Authentication [RFC 2104]
35
36           Cmac functions:
37              The AES-CMAC Algorithm [RFC 4493]
38
39           POLY1305:
40              ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
41
42         Symmetric Ciphers:
43
44
45           DES, 3DES and AES:
46             Block Cipher Techniques [NIST]
47
48           Blowfish:
49              Fast Software Encryption, Cambridge Security  Workshop  Proceed‐
50             ings (December 1993), Springer-Verlag, 1994, pp. 191-204.
51
52           Chacha20:
53              ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
54
55           Chacha20_poly1305:
56              ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
57
58         Modes:
59
60
61           ECB, CBC, CFB, OFB and CTR:
62              Recommendation  for Block Cipher Modes of Operation: Methods and
63             Techniques [NIST SP 800-38A]
64
65           GCM:
66              Recommendation   for   Block   Cipher   Modes   of    Operation:
67             Galois/Counter Mode (GCM) and GMAC [NIST SP 800-38D]
68
69           CCM:
70              Recommendation for Block Cipher Modes of Operation: The CCM Mode
71             for Authentication and Confidentiality [NIST SP 800-38C]
72
73         Asymetric Ciphers - Public Key Techniques:
74
75
76           RSA:
77              PKCS #1: RSA Cryptography Specifications [RFC 3447]
78
79           DSS:
80              Digital Signature Standard (DSS) [FIPS 186-4]
81
82           ECDSA:
83              Elliptic Curve Digital Signature Algorithm [ECDSA]
84
85           SRP:
86              The SRP Authentication and Key Exchange System [RFC 2945]
87
88   Note:
89       The actual supported algorithms and features depends  on  their  avail‐
90       ability in the actual libcrypto used. See the crypto (App) about depen‐
91       dencies.
92
93       Enabling FIPS mode will also disable algorithms and features.
94
95
96       The CRYPTO User's Guide has more information on FIPS, Engines and Algo‐
97       rithm Details like key lengths.
98

DATA TYPES

100   Ciphers, new API
101       cipher() = cipher_no_iv() | cipher_iv() | cipher_aead()
102
103       cipher_no_iv() =
104           aes_128_ecb | aes_192_ecb | aes_256_ecb | blowfish_ecb |
105           des_ecb | rc4
106
107       cipher_iv() =
108           aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_128_cfb128 |
109           aes_192_cfb128 | aes_256_cfb128 | aes_128_cfb8 |
110           aes_192_cfb8 | aes_256_cfb8 | aes_128_ctr | aes_192_ctr |
111           aes_256_ctr | aes_ige256 | blowfish_cbc | blowfish_cfb64 |
112           blowfish_ofb64 | chacha20 | des_ede3_cbc | des_ede3_cfb |
113           des_cbc | des_cfb | rc2_cbc
114
115       cipher_aead() =
116           aes_128_ccm | aes_192_ccm | aes_256_ccm | aes_128_gcm |
117           aes_192_gcm | aes_256_gcm | chacha20_poly1305
118
119              Ciphers known by the CRYPTO application when using the new API.
120
121              Note that this list might be reduced if the underlying libcrypto
122              does not support all of them.
123
124   Ciphers, old API
125       block_cipher_with_iv() =
126           cbc_cipher() | cfb_cipher() | blowfish_ofb64 | aes_ige256
127
128       block_cipher_without_iv() = ecb_cipher()
129
130       stream_cipher() = ctr_cipher() | chacha20 | rc4
131
132       aead_cipher() = aes_gcm | aes_ccm | chacha20_poly1305
133
134       cbc_cipher() =
135           aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
136           des_cbc | des_ede3_cbc | rc2_cbc |
137           retired_cbc_cipher_aliases()
138
139       cfb_cipher() =
140           aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
141           aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 | blowfish_cfb64 |
142           des_cfb | des_ede3_cfb |
143           retired_cfb_cipher_aliases()
144
145       ctr_cipher() =
146           aes_128_ctr | aes_192_ctr | aes_256_ctr |
147           retired_ctr_cipher_aliases()
148
149       ecb_cipher() =
150           aes_128_ecb | aes_192_ecb | aes_256_ecb | blowfish_ecb |
151           retired_ecb_cipher_aliases()
152
153              Ciphers known by the CRYPTO application when using the old API.
154
155              Note that this list might be reduced if the underlying libcrypto
156              does not support all of them.
157
158       retired_cbc_cipher_aliases() =
159           aes_cbc | aes_cbc128 | aes_cbc256 | des3_cbc | des_ede3
160
161       retired_cfb_cipher_aliases() =
162           aes_cfb8 | aes_cfb128 | des3_cbf | des3_cfb | des_ede3_cbf
163
164       retired_ctr_cipher_aliases() = aes_ctr
165
166       retired_ecb_cipher_aliases() = aes_ecb
167
168              Alternative,  old  names of ciphers known by the CRYPTO applica‐
169              tion when using the old API. See Retired cipher names for  names
170              to  use instead to be prepared for an easy convertion to the new
171              API.
172
173              Note that this list might be reduced if the underlying libcrypto
174              does not support all of them.
175
176   Digests and hash
177       hash_algorithm() =
178           sha1() |
179           sha2() |
180           sha3() |
181           blake2() |
182           ripemd160 |
183           compatibility_only_hash()
184
185       hmac_hash_algorithm() =
186           sha1() | sha2() | sha3() | compatibility_only_hash()
187
188       cmac_cipher_algorithm() =
189           aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
190           des_cbc | des_ede3_cbc | rc2_cbc | aes_128_cfb128 |
191           aes_192_cfb128 | aes_256_cfb128 | aes_128_cfb8 |
192           aes_192_cfb8 | aes_256_cfb8
193
194       rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
195
196       dss_digest_type() = sha1() | sha2()
197
198       ecdsa_digest_type() = sha1() | sha2()
199
200       sha1() = sha
201
202       sha2() = sha224 | sha256 | sha384 | sha512
203
204       sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
205
206       blake2() = blake2b | blake2s
207
208       compatibility_only_hash() = md5 | md4
209
210              The  compatibility_only_hash()  algorithms  are recommended only
211              for compatibility with existing applications.
212
213   Elliptic Curves
214       ec_named_curve() =
215           brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
216           brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
217           brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
218           brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
219           brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
220           c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
221           c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
222           c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
223           c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
224           prime192v2 | prime192v3 | prime239v1 | prime239v2 |
225           prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
226           secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
227           secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
228           secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
229           sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
230           sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
231           sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
232           wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
233           wtls6 | wtls7 | wtls8 | wtls9
234
235       edwards_curve_dh() = x25519 | x448
236
237       edwards_curve_ed() = ed25519 | ed448
238
239              Note that some curves are disabled if FIPS is enabled.
240
241       ec_explicit_curve() =
242           {Field :: ec_field(),
243            Curve :: ec_curve(),
244            BasePoint :: binary(),
245            Order :: binary(),
246            CoFactor :: none | binary()}
247
248       ec_field() = ec_prime_field() | ec_characteristic_two_field()
249
250       ec_curve() =
251           {A :: binary(), B :: binary(), Seed :: none | binary()}
252
253              Parametric curve definition.
254
255       ec_prime_field() = {prime_field, Prime :: integer()}
256
257       ec_characteristic_two_field() =
258           {characteristic_two_field,
259            M :: integer(),
260            Basis :: ec_basis()}
261
262       ec_basis() =
263           {tpbasis, K :: integer() >= 0} |
264           {ppbasis,
265            K1 :: integer() >= 0,
266            K2 :: integer() >= 0,
267            K3 :: integer() >= 0} |
268           onbasis
269
270              Curve definition details.
271
272   Keys
273       key() = iodata()
274
275       des3_key() = [key()]
276
277              For keylengths, iv-sizes and blocksizes see the User's Guide.
278
279              A key for des3 is a list of three iolists
280
281       key_integer() = integer() | binary()
282
283              Always binary() when used as return value
284
285   Public/Private Keys
286       rsa_public() = [key_integer()]
287
288       rsa_private() = [key_integer()]
289
290       rsa_params() =
291           {ModulusSizeInBits :: integer(),
292            PublicExponent :: key_integer()}
293
294              rsa_public() = [E, N]
295
296              rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
297
298              Where E is the public exponent, N is public modulus and D is the
299              private  exponent.  The  longer  key  format  contains redundant
300              information that will make the  calculation  faster.  P1,P2  are
301              first and second prime factors. E1,E2 are first and second expo‐
302              nents. C is the CRT coefficient. Terminology is taken from   RFC
303              3447.
304
305       dss_public() = [key_integer()]
306
307       dss_private() = [key_integer()]
308
309              dss_public() = [P, Q, G, Y]
310
311              Where P, Q and G are the dss parameters and Y is the public key.
312
313              dss_private() = [P, Q, G, X]
314
315              Where  P,  Q  and  G are the dss parameters and X is the private
316              key.
317
318       ecdsa_public() = key_integer()
319
320       ecdsa_private() = key_integer()
321
322       ecdsa_params() = ec_named_curve() | ec_explicit_curve()
323
324       eddsa_public() = key_integer()
325
326       eddsa_private() = key_integer()
327
328       eddsa_params() = edwards_curve_ed()
329
330       srp_public() = key_integer()
331
332       srp_private() = key_integer()
333
334              srp_public() = key_integer()
335
336              Where is A or B from SRP design
337
338              srp_private() = key_integer()
339
340              Where is a or b from SRP design
341
342       srp_gen_params() =
343           {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
344
345       srp_comp_params() =
346           {user, srp_user_comp_params()} |
347           {host, srp_host_comp_params()}
348
349              srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
350
351              srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
352
353              srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
354
355              srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
356
357              Where Verifier is v, Generator is g and Prime is  N,  DerivedKey
358              is X, and Scrambler is u (optional will be generated if not pro‐
359              vided) from SRP design Version = '3' | '6' | '6a'
360
361   Public Key Ciphers
362       pk_encrypt_decrypt_algs() = rsa
363
364              Algorithms for public key  encrypt/decrypt.  Only  RSA  is  sup‐
365              ported.
366
367       pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
368
369       rsa_opt() =
370           {rsa_padding, rsa_padding()} |
371           {signature_md, atom()} |
372           {rsa_mgf1_md, sha} |
373           {rsa_oaep_label, binary()} |
374           {rsa_oaep_md, sha}
375
376       rsa_padding() =
377           rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
378           rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
379
380              Options for public key encrypt/decrypt. Only RSA is supported.
381
382          Warning:
383
384              The RSA options are experimental.
385
386              The exact set of options and there syntax may be changed without
387              prior notice.
388
389
390       rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
391
392              Those option forms are kept only for  compatibility  and  should
393              not be used in new code.
394
395   Public Key Sign and Verify
396       pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
397
398              Algorithms for sign and verify.
399
400       pk_sign_verify_opts() = [rsa_sign_verify_opt()]
401
402       rsa_sign_verify_opt() =
403           {rsa_padding, rsa_sign_verify_padding()} |
404           {rsa_pss_saltlen, integer()} |
405           {rsa_mgf1_md, sha2()}
406
407       rsa_sign_verify_padding() =
408           rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
409           rsa_no_padding
410
411              Options for sign and verify.
412
413          Warning:
414
415              The RSA options are experimental.
416
417              The exact set of options and there syntax may be changed without
418              prior notice.
419
420
421   Diffie-Hellman Keys and parameters
422       dh_public() = key_integer()
423
424       dh_private() = key_integer()
425
426       dh_params() = [key_integer()]
427
428              dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
429
430       ecdh_public() = key_integer()
431
432       ecdh_private() = key_integer()
433
434       ecdh_params() =
435           ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
436
437   Types for Engines
438       engine_key_ref() =
439           #{engine := engine_ref(),
440             key_id := key_id(),
441             password => password(),
442             term() => term()}
443
444       engine_ref() = term()
445
446              The result of a call to engine_load/3.
447
448       key_id() = string() | binary()
449
450              Identifies the key to be used. The format depends on the  loaded
451              engine.  It  is  passed  to the ENGINE_load_(private|public)_key
452              functions in libcrypto.
453
454       password() = string() | binary()
455
456              The password of the key stored in an engine.
457
458       engine_method_type() =
459           engine_method_rsa | engine_method_dsa | engine_method_dh |
460           engine_method_rand | engine_method_ecdh |
461           engine_method_ecdsa | engine_method_ciphers |
462           engine_method_digests | engine_method_store |
463           engine_method_pkey_meths | engine_method_pkey_asn1_meths |
464           engine_method_ec
465
466       engine_cmnd() = {unicode:chardata(), unicode:chardata()}
467
468              Pre and Post commands for engine_load/3 and /4.
469
470   Internal data types
471       crypto_state()
472
473       hash_state()
474
475       hmac_state()
476
477       mac_state()
478
479       stream_state()
480
481              Contexts with an internal state that should not  be  manipulated
482              but passed between function calls.
483
484   Error types
485       run_time_error() = no_return()
486
487              The  exception error:badarg signifies that one or more arguments
488              are of wrong data type, or are otherwise badly formed.
489
490              The exception error:notsup signifies that the algorithm is known
491              but  is not supported by current underlying libcrypto or explic‐
492              itly disabled when building that.
493
494              For a list of supported algorithms, see supports/0.
495
496       descriptive_error() = no_return()
497
498              This is a more developed variant of the older run_time_error().
499
500              The exception is:
501
502                     {Tag, {C_FileName,LineNumber}, Description}
503
504                      Tag = badarg | notsup | error
505                      C_FileName = string()
506                      LineNumber = integer()
507                      Description = string()
508
509
510              It is like the older type an exception of the  error  class.  In
511              addition  they  contain a descriptive text in English. That text
512              is targeted to a developer.  Examples  are  "Bad  key  size"  or
513              "Cipher id is not an atom".
514
515              The exception tags are:
516
517                badarg:
518                  Signifies  that one or more arguments are of wrong data type
519                  or are otherwise badly formed.
520
521                notsup:
522                  Signifies that the algorithm is known but is  not  supported
523                  by  current underlying libcrypto or explicitly disabled when
524                  building that one.
525
526                error:
527                  An error condition that should not occur, for example a mem‐
528                  ory  allocation  failed or the underlying cryptolib returned
529                  an error code, for example "Can't initialize  context,  step
530                  1".  Thoose  text  usually  needs searching the C-code to be
531                  understood.
532
533              To catch the exception, use for example:
534
535                     try crypto:crypto_init(Ciph, Key, IV, true)
536                     catch
537                         error:{Tag, {C_FileName,LineNumber}, Description} ->
538                                 do_something(......)
539                         .....
540                     end
541
542

NEW API

EXPORTS

545       crypto_init(Cipher, Key, EncryptFlag) ->
546                      State | descriptive_error()
547
548              Types:
549
550                 Cipher = cipher_no_iv()
551                 Key = iodata()
552                 EncryptFlag = boolean()
553                 State = crypto_state()
554
555              As crypto_init/4 but for ciphers without IVs.
556
557       crypto_init(Cipher, Key, IV, EncryptFlag) ->
558                      State | descriptive_error()
559
560              Types:
561
562                 Cipher = cipher_iv()
563                 Key = IV = iodata()
564                 EncryptFlag = boolean()
565                 State = crypto_state()
566
567              Part of the new API. Initializes  a  series  of  encryptions  or
568              decryptions  and creates an internal state with a reference that
569              is returned. The actual encryption  or  decryption  is  done  by
570              crypto_update/2.
571
572              For encryption, set the EncryptFlag to true. For decryption, set
573              it to false.
574
575              See  examples in the User's Guide.
576
577       crypto_update(State, Data) -> Result | descriptive_error()
578
579              Types:
580
581                 State = crypto_state()
582                 Data = iodata()
583                 Result = binary()
584
585              Part of the new API. It does an actual  crypto  operation  on  a
586              part of the full text. If the part is less than a number of full
587              blocks, only the full blocks (possibly none)  are  encrypted  or
588              decrypted  and  the  remaining  bytes  are  saved  to  the  next
589              crypto_update  operation.  The  State  should  be  created  with
590              crypto_init/3 or crypto_init/4.
591
592              See  examples in the User's Guide.
593
594       crypto_dyn_iv_init(Cipher, Key, EncryptFlag) ->
595                             State | descriptive_error()
596
597              Types:
598
599                 Cipher = cipher_iv()
600                 Key = iodata()
601                 EncryptFlag = boolean()
602                 State = crypto_state()
603
604              Part  of  the  new  API.  Initializes a series of encryptions or
605              decryptions where the IV is provided later. The  actual  encryp‐
606              tion or decryption is done by crypto_dyn_iv_update/3.
607
608              For encryption, set the EncryptFlag to true. For decryption, set
609              it to false.
610
611       crypto_dyn_iv_update(State, Data, IV) ->
612                               Result | descriptive_error()
613
614              Types:
615
616                 State = crypto_state()
617                 Data = IV = iodata()
618                 Result = binary()
619
620              Part of the new API. Do an actual crypto operation on a part  of
621              the  full  text  and the IV is supplied for each part. The State
622              should be created with crypto_dyn_iv_init/3.
623
624       crypto_one_time(Cipher, Key, Data, EncryptFlag) ->
625                          Result | descriptive_error()
626
627              Types:
628
629                 Cipher = cipher_no_iv()
630                 Key = Data = iodata()
631                 EncryptFlag = boolean()
632                 Result = binary()
633
634              As crypto_one_time/5 but for ciphers without IVs.
635
636       crypto_one_time(Cipher, Key, IV, Data, EncryptFlag) ->
637                          Result | descriptive_error()
638
639              Types:
640
641                 Cipher = cipher_iv()
642                 Key = IV = Data = iodata()
643                 EncryptFlag = boolean()
644                 Result = binary()
645
646              Part of the new API. Do a complete encrypt  or  decrypt  of  the
647              full text in the argument Data.
648
649              For encryption, set the EncryptFlag to true. For decryption, set
650              it to false.
651
652              See examples in the User's Guide.
653
654       crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
655                            EncFlag :: true) ->
656                               Result | descriptive_error()
657
658       crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
659                            EncFlag) ->
660                               Result | descriptive_error()
661
662              Types:
663
664                 Cipher = cipher_aead()
665                 Key = IV = InText = AAD = iodata()
666                 TagOrTagLength = EncryptTagLength | DecryptTag
667                 EncryptTagLength = integer() >= 0
668                 DecryptTag = iodata()
669                 EncFlag = boolean()
670                 Result = EncryptResult | DecryptResult
671                 EncryptResult = {OutCryptoText, OutTag}
672                 DecryptResult = OutPlainText | error
673                 OutCryptoText = OutTag = OutPlainText = binary()
674
675              Part of the new API. Do a complete encrypt or  decrypt  with  an
676              AEAD cipher of the full text.
677
678              For encryption, set the EncryptFlag to true and set the TagOrTa‐
679              gLength to the wanted size of the tag, that is, the tag  length.
680              If  the  default length is wanted, the crypto_aead/6 form may be
681              used.
682
683              For decryption, set the EncryptFlag to false and put the tag  to
684              be checked in the argument TagOrTagLength.
685
686              See examples in the User's Guide.
687
688       supports(Type) -> Support
689
690              Types:
691
692                 Type  =  hashs  |  ciphers  |  public_keys  | macs | curves |
693                 rsa_opts
694                 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
695                 Hashs =
696                     [sha1() |
697                      sha2() |
698                      sha3() |
699                      blake2() |
700                      ripemd160 |
701                      compatibility_only_hash()]
702                 Ciphers = [cipher()]
703                 PKs = [rsa | dss | ecdsa | dh | ecdh | ec_gf2m]
704                 Macs = [hmac | cmac | poly1305]
705                 Curves =
706                     [ec_named_curve()      |       edwards_curve_dh()       |
707                 edwards_curve_ed()]
708                 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
709
710              Can  be  used to determine which crypto algorithms that are sup‐
711              ported by the underlying libcrypto library
712
713              See hash_info/1 and cipher_info/1 for information about the hash
714              and cipher algorithms.
715
716       mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()
717
718              Types:
719
720                 Key = Data = iodata()
721                 Mac = binary()
722
723              Short for mac(Type, undefined, Key, Data).
724
725       mac(Type, SubType, Key, Data) -> Mac | descriptive_error()
726
727              Types:
728
729                 Type = hmac | cmac | poly1305
730                 SubType =
731                     hmac_hash_algorithm()  |  cmac_cipher_algorithm() | unde‐
732                 fined
733                 Key = Data = iodata()
734                 Mac = binary()
735
736              Computes a MAC (Message Authentication Code) of type  Type  from
737              Data.
738
739              SubType depends on the MAC Type:
740
741                * For  hmac  it  is a hash algorithm, see Algorithm Details in
742                  the User's Guide.
743
744                * For cmac it is a cipher suitable  for  cmac,  see  Algorithm
745                  Details in the User's Guide.
746
747                * For  poly1305  it  should  be  set to undefined or the mac/2
748                  function could be used instead, see Algorithm Details in the
749                  User's Guide.
750
751              Key  is  the  authentication  key with a length according to the
752              Type and SubType.  The  key  length  could  be  found  with  the
753              hash_info/1  (hmac)  for and cipher_info/1 (cmac) functions. For
754              poly1305 the key length is 32 bytes. Note that the cryptographic
755              quality of the key is not checked.
756
757              The  Mac result will have a default length depending on the Type
758              and SubType. To set a  shorter  length,  use  macN/4  or  macN/5
759              instead.  The  default length is documented in Algorithm Details
760              in the User's Guide.
761
762       macN(Type :: poly1305, Key, Data, MacLength) ->
763               Mac | descriptive_error()
764
765              Types:
766
767                 Key = Data = iodata()
768                 Mac = binary()
769                 MacLength = integer() >= 1
770
771              Short for macN(Type, undefined, Key, Data, MacLength).
772
773       macN(Type, SubType, Key, Data, MacLength) ->
774               Mac | descriptive_error()
775
776              Types:
777
778                 Type = hmac | cmac | poly1305
779                 SubType =
780                     hmac_hash_algorithm() | cmac_cipher_algorithm()  |  unde‐
781                 fined
782                 Key = Data = iodata()
783                 Mac = binary()
784                 MacLength = integer() >= 1
785
786              Computes  a MAC (Message Authentication Code) as mac/3 and mac/4
787              but MacLength will limit the size of the  resultant  Mac  to  at
788              most MacLength bytes. Note that if MacLength is greater than the
789              actual number of bytes returned from the  underlying  hash,  the
790              returned hash will have that shorter length instead.
791
792              The  max  MacLength  is  documented  in Algorithm Details in the
793              User's Guide.
794
795       mac_init(Type :: poly1305, Key) -> State | descriptive_error()
796
797              Types:
798
799                 Key = iodata()
800                 State = mac_state()
801
802              Short for mac_init(Type, undefined, Key).
803
804       mac_init(Type, SubType, Key) -> State | descriptive_error()
805
806              Types:
807
808                 Type = hmac | cmac | poly1305
809                 SubType =
810                     hmac_hash_algorithm() | cmac_cipher_algorithm()  |  unde‐
811                 fined
812                 Key = iodata()
813                 State = mac_state()
814
815              Initializes the context for streaming MAC operations.
816
817              Type determines which mac algorithm to use in the MAC operation.
818
819              SubType depends on the MAC Type:
820
821                * For  hmac  it  is a hash algorithm, see Algorithm Details in
822                  the User's Guide.
823
824                * For cmac it is a cipher suitable  for  cmac,  see  Algorithm
825                  Details in the User's Guide.
826
827                * For  poly1305  it  should  be  set to undefined or the mac/2
828                  function could be used instead, see Algorithm Details in the
829                  User's Guide.
830
831              Key  is  the  authentication  key with a length according to the
832              Type and SubType.  The  key  length  could  be  found  with  the
833              hash_info/1  (hmac)  for and cipher_info/1 (cmac) functions. For
834              poly1305 the key length is 32 bytes. Note that the cryptographic
835              quality of the key is not checked.
836
837              The  returned  State  should  be  used in one or more subsequent
838              calls to mac_update/2. The MAC  value  is  finally  returned  by
839              calling mac_final/1 or mac_finalN/2.
840
841              See  examples in the User's Guide.
842
843       mac_update(State0, Data) -> State | descriptive_error()
844
845              Types:
846
847                 Data = iodata()
848                 State0 = State = mac_state()
849
850              Updates the MAC represented by State0 using the given Data which
851              could be of any length.
852
853              The State0 is the State value originally from a MAC  init  func‐
854              tion,  that  is  mac_init/2,  mac_init/3  or  a previous call of
855              mac_update/2. The value State0  is  returned  unchanged  by  the
856              function as State.
857
858       mac_final(State) -> Mac | descriptive_error()
859
860              Types:
861
862                 State = mac_state()
863                 Mac = binary()
864
865              Finalizes  the MAC operation referenced by State. The Mac result
866              will have a default length depending on the Type and SubType  in
867              the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
868              instead. The default length is documented in  Algorithm  Details
869              in the User's Guide.
870
871       mac_finalN(State, MacLength) -> Mac | descriptive_error()
872
873              Types:
874
875                 State = mac_state()
876                 MacLength = integer() >= 1
877                 Mac = binary()
878
879              Finalizes the MAC operation referenced by State.
880
881              Mac  will be a binary with at most MacLength bytes. Note that if
882              MacLength is greater than the actual number  of  bytes  returned
883              from  the  underlying  hash,  the  returned  hash will have that
884              shorter length instead.
885
886              The max MacLength is documented  in  Algorithm  Details  in  the
887              User's Guide.
888

API KEPT FROM PREVIOUS VERSIONS

EXPORTS

891       bytes_to_integer(Bin :: binary()) -> integer()
892
893              Convert binary representation, of an integer, to an Erlang inte‐
894              ger.
895
896       compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
897                      SharedSecret
898
899              Types:
900
901                 Type = dh | ecdh | srp
902                 SharedSecret = binary()
903                 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
904                 MyPrivateKey =
905                     dh_private() | ecdh_private() |  {srp_public(),  srp_pri‐
906                 vate()}
907                 Params = dh_params() | ecdh_params() | srp_comp_params()
908
909              Computes  the  shared  secret from the private key and the other
910              party's public key. See also public_key:compute_key/2
911
912       exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
913
914              Performs bit-wise XOR (exclusive or) on the data supplied.
915
916       generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
917
918       generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
919
920              Types:
921
922                 Type = dh | ecdh | rsa | srp
923                 PublicKey =
924                     dh_public() | ecdh_public() | rsa_public() | srp_public()
925                 PrivKeyIn =
926                     undefined |
927                     dh_private() |
928                     ecdh_private() |
929                     rsa_private() |
930                     {srp_public(), srp_private()}
931                 PrivKeyOut =
932                     dh_private() |
933                     ecdh_private() |
934                     rsa_private() |
935                     {srp_public(), srp_private()}
936                 Params =
937                     dh_params()   |   ecdh_params()    |    rsa_params()    |
938                 srp_comp_params()
939
940              Generates  a public key of type Type. See also public_key:gener‐
941              ate_key/1. May raise exception:
942
943                * error:badarg: an argument is of wrong type or has an illegal
944                  value,
945
946                * error:low_entropy:  the  random generator failed due to lack
947                  of secure "randomness",
948
949                * error:computation_failed: the computation fails  of  another
950                  reason than low_entropy.
951
952          Note:
953              RSA  key  generation  is only available if the runtime was built
954              with dirty scheduler support. Otherwise, attempting to  generate
955              an RSA key will raise exception error:notsup.
956
957
958       hash(Type, Data) -> Digest
959
960              Types:
961
962                 Type = hash_algorithm()
963                 Data = iodata()
964                 Digest = binary()
965
966              Computes a message digest of type Type from Data.
967
968              May  raise exception error:notsup in case the chosen Type is not
969              supported by the underlying libcrypto implementation.
970
971       hash_init(Type) -> State
972
973              Types:
974
975                 Type = hash_algorithm()
976                 State = hash_state()
977
978              Initializes the context  for  streaming  hash  operations.  Type
979              determines  which  digest to use. The returned context should be
980              used as argument to hash_update.
981
982              May raise exception error:notsup in case the chosen Type is  not
983              supported by the underlying libcrypto implementation.
984
985       hash_update(State, Data) -> NewState
986
987              Types:
988
989                 State = NewState = hash_state()
990                 Data = iodata()
991
992              Updates  the digest represented by Context using the given Data.
993              Context must have been generated using hash_init or  a  previous
994              call  to  this function. Data can be any length. NewContext must
995              be passed into the next call to hash_update or hash_final.
996
997       hash_final(State) -> Digest
998
999              Types:
1000
1001                 State = hash_state()
1002                 Digest = binary()
1003
1004              Finalizes the hash operation referenced by Context returned from
1005              a previous call to hash_update. The size of Digest is determined
1006              by the type of hash function used to generate it.
1007
1008       info_fips() -> not_supported | not_enabled | enabled
1009
1010              Provides information about the FIPS operating status  of  crypto
1011              and  the  underlying libcrypto library. If crypto was built with
1012              FIPS support this can be either enabled (when  running  in  FIPS
1013              mode)  or  not_enabled.  For  other  builds this value is always
1014              not_supported.
1015
1016              See enable_fips_mode/1 about how to enable FIPS mode.
1017
1018          Warning:
1019              In FIPS mode all non-FIPS compliant algorithms are disabled  and
1020              raise  exception  error:notsup. Check supports that in FIPS mode
1021              returns the restricted list of available algorithms.
1022
1023
1024       enable_fips_mode(Enable) -> Result
1025
1026              Types:
1027
1028                 Enable = Result = boolean()
1029
1030              Enables (Enable = true) or disables (Enable = false) FIPS  mode.
1031              Returns true if the operation was successful or false otherwise.
1032
1033              Note  that  to  enable  FIPS mode succesfully, OTP must be built
1034              with the configure  option  --enable-fips,  and  the  underlying
1035              libcrypto must also support FIPS.
1036
1037              See also info_fips/0.
1038
1039       info_lib() -> [{Name, VerNum, VerStr}]
1040
1041              Types:
1042
1043                 Name = binary()
1044                 VerNum = integer()
1045                 VerStr = binary()
1046
1047              Provides the name and version of the libraries used by crypto.
1048
1049              Name  is  the name of the library. VerNum is the numeric version
1050              according to the library's own versioning  scheme.  VerStr  con‐
1051              tains a text variant of the version.
1052
1053              > info_lib().
1054              [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c  10 Nov 2016"">>}]
1055
1056
1057          Note:
1058              From  OTP  R16 the numeric version represents the version of the
1059              OpenSSL header files (openssl/opensslv.h) used when  crypto  was
1060              compiled. The text variant represents the libcrypto library used
1061              at runtime. In earlier OTP versions both numeric  and  text  was
1062              taken from the library.
1063
1064
1065       hash_info(Type) -> Result | run_time_error()
1066
1067              Types:
1068
1069                 Type = hash_algorithm()
1070                 Result =
1071                     #{size := integer(),
1072                       block_size := integer(),
1073                       type := integer()}
1074
1075              Provides  a map with information about block_size, size and pos‐
1076              sibly other properties of the hash algorithm in question.
1077
1078              For a list of supported hash algorithms, see supports/0.
1079
1080       cipher_info(Type) -> Result | run_time_error()
1081
1082              Types:
1083
1084                 Type = cipher()
1085                 Result =
1086                     #{key_length := integer(),
1087                       iv_length := integer(),
1088                       block_size := integer(),
1089                       mode := CipherModes,
1090                       type := undefined | integer()}
1091                 CipherModes =
1092                     undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1093                     ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1094                     wrap_mode | xts_mode
1095
1096              Provides a map with information  about  block_size,  key_length,
1097              iv_length  and possibly other properties of the cipher algorithm
1098              in question.
1099
1100          Note:
1101              The ciphers aes_cbc,  aes_cfb8,  aes_cfb128,  aes_ctr,  aes_ecb,
1102              aes_gcm  and  aes_ccm has no keylength in the Type as opposed to
1103              for example aes_128_ctr. They adapt to the  length  of  the  key
1104              provided  in  the  encrypt  and decrypt function. Therefor it is
1105              impossible to return a valid keylength in the map.
1106
1107              Always use a Type with an explicit key length,
1108
1109
1110              For a list of supported cipher algorithms, see supports/0.
1111
1112       mod_pow(N, P, M) -> Result
1113
1114              Types:
1115
1116                 N = P = M = binary() | integer()
1117                 Result = binary() | error
1118
1119              Computes the function N^P mod M.
1120
1121       next_iv(Type :: cbc_cipher(), Data) -> NextIVec
1122
1123       next_iv(Type :: des_cfb, Data, IVec) -> NextIVec
1124
1125              Types:
1126
1127                 Data = iodata()
1128                 IVec = NextIVec = binary()
1129
1130              Returns the initialization vector to be used in the next  itera‐
1131              tion of encrypt/decrypt of type Type. Data is the encrypted data
1132              from the previous iteration step.  The  IVec  argument  is  only
1133              needed  for des_cfb as the vector used in the previous iteration
1134              step.
1135
1136       private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1137                          PlainText
1138
1139              Types:
1140
1141                 Algorithm = pk_encrypt_decrypt_algs()
1142                 CipherText = binary()
1143                 PrivateKey = rsa_private() | engine_key_ref()
1144                 Options = pk_encrypt_decrypt_opts()
1145                 PlainText = binary()
1146
1147              Decrypts the CipherText,  encrypted  with  public_encrypt/4  (or
1148              equivalent  function)  using  the  PrivateKey,  and  returns the
1149              plaintext (message digest). This is a low level signature  veri‐
1150              fication  operation  used  for instance by older versions of the
1151              SSL protocol. See also public_key:decrypt_private/[2,3]
1152
1153       private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1154                          CipherText
1155
1156              Types:
1157
1158                 Algorithm = pk_encrypt_decrypt_algs()
1159                 PlainText = binary()
1160                 PrivateKey = rsa_private() | engine_key_ref()
1161                 Options = pk_encrypt_decrypt_opts()
1162                 CipherText = binary()
1163
1164              Encrypts the PlainText using  the  PrivateKey  and  returns  the
1165              ciphertext.  This  is  a  low level signature operation used for
1166              instance by older versions of the SSL protocol.  See  also  pub‐
1167              lic_key:encrypt_private/[2,3]
1168
1169       public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1170                         PlainText
1171
1172              Types:
1173
1174                 Algorithm = pk_encrypt_decrypt_algs()
1175                 CipherText = binary()
1176                 PublicKey = rsa_public() | engine_key_ref()
1177                 Options = pk_encrypt_decrypt_opts()
1178                 PlainText = binary()
1179
1180              Decrypts  the  CipherText,  encrypted  with private_encrypt/4(or
1181              equivalent function)  using  the  PrivateKey,  and  returns  the
1182              plaintext  (message digest). This is a low level signature veri‐
1183              fication operation used for instance by older  versions  of  the
1184              SSL protocol. See also public_key:decrypt_public/[2,3]
1185
1186       public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1187                         CipherText
1188
1189              Types:
1190
1191                 Algorithm = pk_encrypt_decrypt_algs()
1192                 PlainText = binary()
1193                 PublicKey = rsa_public() | engine_key_ref()
1194                 Options = pk_encrypt_decrypt_opts()
1195                 CipherText = binary()
1196
1197              Encrypts  the PlainText (message digest) using the PublicKey and
1198              returns the CipherText. This is a low level signature  operation
1199              used  for  instance  by  older versions of the SSL protocol. See
1200              also public_key:encrypt_public/[2,3]
1201
1202       rand_seed(Seed :: binary()) -> ok
1203
1204              Set the seed for PRNG  to  the  given  binary.  This  calls  the
1205              RAND_seed function from openssl. Only use this if the system you
1206              are running on does not have enough "randomness" built in.  Nor‐
1207              mally this is when strong_rand_bytes/1 raises error:low_entropy
1208
1209       rand_uniform(Lo, Hi) -> N
1210
1211              Types:
1212
1213                 Lo, Hi, N = integer()
1214
1215              Generate  a  random  number  N,  Lo  =<  N < Hi. Uses the crypto
1216              library pseudo-random number generator. Hi must be  larger  than
1217              Lo.
1218
1219       start() -> ok | {error, Reason :: term()}
1220
1221              Equivalent to application:start(crypto).
1222
1223       stop() -> ok | {error, Reason :: term()}
1224
1225              Equivalent to application:stop(crypto).
1226
1227       strong_rand_bytes(N :: integer() >= 0) -> binary()
1228
1229              Generates  N  bytes  randomly  uniform  0..255,  and returns the
1230              result in a binary. Uses a cryptographically secure prng  seeded
1231              and  periodically  mixed with operating system provided entropy.
1232              By default this is the RAND_bytes method from OpenSSL.
1233
1234              May raise exception error:low_entropy in case the random genera‐
1235              tor failed due to lack of secure "randomness".
1236
1237       rand_seed() -> rand:state()
1238
1239              Creates  state  object for random number generation, in order to
1240              generate  cryptographically  strong  random  numbers  (based  on
1241              OpenSSL's BN_rand_range), and saves it in the process dictionary
1242              before  returning  it  as  well.  See   also   rand:seed/1   and
1243              rand_seed_s/0.
1244
1245              When  using  the  state object from this function the rand func‐
1246              tions using it may raise exception error:low_entropy in case the
1247              random generator failed due to lack of secure "randomness".
1248
1249              Example
1250
1251              _ = crypto:rand_seed(),
1252              _IntegerValue = rand:uniform(42), % [1; 42]
1253              _FloatValue = rand:uniform().     % [0.0; 1.0[
1254
1255       rand_seed_s() -> rand:state()
1256
1257              Creates  state  object for random number generation, in order to
1258              generate cryptographically strongly  random  numbers  (based  on
1259              OpenSSL's BN_rand_range). See also rand:seed_s/1.
1260
1261              When  using  the  state object from this function the rand func‐
1262              tions using it may raise exception error:low_entropy in case the
1263              random generator failed due to lack of secure "randomness".
1264
1265          Note:
1266              The  state  returned  from this function cannot be used to get a
1267              reproducable random sequence as from the other  rand  functions,
1268              since reproducability does not match cryptographically safe.
1269
1270              The  only  supported  usage  is  to generate one distinct random
1271              sequence from this start state.
1272
1273
1274       rand_seed_alg(Alg) -> rand:state()
1275
1276              Types:
1277
1278                 Alg = crypto | crypto_cache
1279
1280              Creates state object for random number generation, in  order  to
1281              generate  cryptographically  strong random numbers, and saves it
1282              in the process dictionary before returning it as well. See  also
1283              rand:seed/1 and rand_seed_alg_s/1.
1284
1285              When  using  the  state object from this function the rand func‐
1286              tions using it may raise exception error:low_entropy in case the
1287              random generator failed due to lack of secure "randomness".
1288
1289              Example
1290
1291              _ = crypto:rand_seed_alg(crypto_cache),
1292              _IntegerValue = rand:uniform(42), % [1; 42]
1293              _FloatValue = rand:uniform().     % [0.0; 1.0[
1294
1295       rand_seed_alg(Alg, Seed) -> rand:state()
1296
1297              Types:
1298
1299                 Alg = crypto_aes
1300
1301              Creates a state object for random number generation, in order to
1302              generate cryptographically  unpredictable  random  numbers,  and
1303              saves  it in the process dictionary before returning it as well.
1304              See also rand_seed_alg_s/2.
1305
1306              Example
1307
1308              _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1309              IntegerValue = rand:uniform(42), % [1; 42]
1310              FloatValue = rand:uniform(),     % [0.0; 1.0[
1311              _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1312              IntegerValue = rand:uniform(42), % Same values
1313              FloatValue = rand:uniform().     % again
1314
1315
1316       rand_seed_alg_s(Alg) -> rand:state()
1317
1318              Types:
1319
1320                 Alg = crypto | crypto_cache
1321
1322              Creates state object for random number generation, in  order  to
1323              generate  cryptographically  strongly  random  numbers. See also
1324              rand:seed_s/1.
1325
1326              If  Alg  is  crypto   this   function   behaves   exactly   like
1327              rand_seed_s/0.
1328
1329              If  Alg  is  crypto_cache this function fetches random data with
1330              OpenSSL's RAND_bytes and caches it for speed using  an  internal
1331              word  size  of  56  bits  that makes calculations fast on 64 bit
1332              machines.
1333
1334              When using the state object from this function  the  rand  func‐
1335              tions using it may raise exception error:low_entropy in case the
1336              random generator failed due to lack of secure "randomness".
1337
1338              The cache size can be changed from its default value  using  the
1339              crypto app's  configuration parameter rand_cache_size.
1340
1341              When  using  the  state object from this function the rand func‐
1342              tions using it may throw exception low_entropy in case the  ran‐
1343              dom generator failed due to lack of secure "randomness".
1344
1345          Note:
1346              The  state  returned  from this function cannot be used to get a
1347              reproducable random sequence as from the other  rand  functions,
1348              since reproducability does not match cryptographically safe.
1349
1350              In  fact since random data is cached some numbers may get repro‐
1351              duced if you try, but this is unpredictable.
1352
1353              The only supported usage is  to  generate  one  distinct  random
1354              sequence from this start state.
1355
1356
1357       rand_seed_alg_s(Alg, Seed) -> rand:state()
1358
1359              Types:
1360
1361                 Alg = crypto_aes
1362
1363              Creates a state object for random number generation, in order to
1364              generate cryptographically  unpredictable  random  numbers.  See
1365              also rand_seed_alg/1.
1366
1367              To  get  a  long period the Xoroshiro928 generator from the rand
1368              module is used as a counter (with period 2^928 - 1) and the gen‐
1369              erator  states are scrambled through AES to create 58-bit pseudo
1370              random values.
1371
1372              The result should be statistically completely unpredictable ran‐
1373              dom values, since the scrambling is cryptographically strong and
1374              the period is ridiculously long. But the generated  numbers  are
1375              not to be regarded as cryptographically strong since there is no
1376              re-keying schedule.
1377
1378                * If you need  cryptographically  strong  random  numbers  use
1379                  rand_seed_alg_s/1   with   Alg   =:=   crypto   or  Alg  =:=
1380                  crypto_cache.
1381
1382                * If you need to be able to repeat the sequence use this func‐
1383                  tion.
1384
1385                * If you do not need the statistical quality of this function,
1386                  there are faster algorithms in the rand module.
1387
1388              Thanks to the used  generator  the  state  object  supports  the
1389              rand:jump/0,1 function with distance 2^512.
1390
1391              Numbers  are  generated in batches and cached for speed reasons.
1392              The cache size can be changed from its default value  using  the
1393              crypto app's  configuration parameter rand_cache_size.
1394
1395       ec_curves() -> [EllipticCurve]
1396
1397              Types:
1398
1399                 EllipticCurve =
1400                     ec_named_curve()       |       edwards_curve_dh()       |
1401                 edwards_curve_ed()
1402
1403              Can be used to determine which named elliptic  curves  are  sup‐
1404              ported.
1405
1406       ec_curve(CurveName) -> ExplicitCurve
1407
1408              Types:
1409
1410                 CurveName = ec_named_curve()
1411                 ExplicitCurve = ec_explicit_curve()
1412
1413              Return the defining parameters of a elliptic curve.
1414
1415       sign(Algorithm, DigestType, Msg, Key) -> Signature
1416
1417       sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1418
1419              Types:
1420
1421                 Algorithm = pk_sign_verify_algs()
1422                 DigestType =
1423                     rsa_digest_type() |
1424                     dss_digest_type() |
1425                     ecdsa_digest_type() |
1426                     none
1427                 Msg = iodata() | {digest, iodata()}
1428                 Key =
1429                     rsa_private() |
1430                     dss_private() |
1431                     [ecdsa_private() | ecdsa_params()] |
1432                     [eddsa_private() | eddsa_params()] |
1433                     engine_key_ref()
1434                 Options = pk_sign_verify_opts()
1435                 Signature = binary()
1436
1437              Creates a digital signature.
1438
1439              The msg is either the binary "cleartext" data to be signed or it
1440              is the hashed value of "cleartext" i.e. the digest (plaintext).
1441
1442              Algorithm dss can only be used together with digest type sha.
1443
1444              See also public_key:sign/3.
1445
1446       verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1447
1448       verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1449                 Result
1450
1451              Types:
1452
1453                 Algorithm = pk_sign_verify_algs()
1454                 DigestType =
1455                     rsa_digest_type()       |       dss_digest_type()       |
1456                 ecdsa_digest_type()
1457                 Msg = iodata() | {digest, iodata()}
1458                 Signature = binary()
1459                 Key =
1460                     rsa_public() |
1461                     dss_public() |
1462                     [ecdsa_public() | ecdsa_params()] |
1463                     [eddsa_public() | eddsa_params()] |
1464                     engine_key_ref()
1465                 Options = pk_sign_verify_opts()
1466                 Result = boolean()
1467
1468              Verifies a digital signature
1469
1470              The msg is either the binary "cleartext" data to be signed or it
1471              is the hashed value of "cleartext" i.e. the digest (plaintext).
1472
1473              Algorithm dss can only be used together with digest type sha.
1474
1475              See also public_key:verify/4.
1476

ENGINE API

EXPORTS

1479       privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1480
1481              Types:
1482
1483                 Type = rsa | dss
1484                 EnginePrivateKeyRef = engine_key_ref()
1485                 PublicKey = rsa_public() | dss_public()
1486
1487              Fetches the corresponding public key from a private  key  stored
1488              in  an Engine. The key must be of the type indicated by the Type
1489              parameter.
1490
1491       engine_get_all_methods() -> Result
1492
1493              Types:
1494
1495                 Result = [engine_method_type()]
1496
1497              Returns a list of all possible engine methods.
1498
1499              May raise exception error:notsup in case there is no engine sup‐
1500              port in the underlying OpenSSL implementation.
1501
1502              See also the chapter Engine Load in the User's Guide.
1503
1504       engine_load(EngineId, PreCmds, PostCmds) -> Result
1505
1506              Types:
1507
1508                 EngineId = unicode:chardata()
1509                 PreCmds = PostCmds = [engine_cmnd()]
1510                 Result =
1511                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1512
1513              Loads  the  OpenSSL  engine given by EngineId if it is available
1514              and then returns ok and an engine handle. This function  is  the
1515              same  as  calling engine_load/4 with EngineMethods set to a list
1516              of all the possible methods. An error tuple is returned  if  the
1517              engine can't be loaded.
1518
1519              The  function  raises  a  error:badarg  if the parameters are in
1520              wrong format. It may also raise the  exception  error:notsup  in
1521              case there is no engine support in the underlying OpenSSL imple‐
1522              mentation.
1523
1524              See also the chapter Engine Load in the User's Guide.
1525
1526       engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
1527
1528              Types:
1529
1530                 EngineId = unicode:chardata()
1531                 PreCmds = PostCmds = [engine_cmnd()]
1532                 EngineMethods = [engine_method_type()]
1533                 Result =
1534                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1535
1536              Loads the OpenSSL engine given by EngineId if  it  is  available
1537              and  then  returns  ok  and  an engine handle. An error tuple is
1538              returned if the engine can't be loaded.
1539
1540              The function raises a error:badarg  if  the  parameters  are  in
1541              wrong  format.  It  may also raise the exception error:notsup in
1542              case there is no engine support in the underlying OpenSSL imple‐
1543              mentation.
1544
1545              See also the chapter Engine Load in the User's Guide.
1546
1547       engine_unload(Engine) -> Result
1548
1549              Types:
1550
1551                 Engine = engine_ref()
1552                 Result = ok | {error, Reason :: term()}
1553
1554              Unloads  the  OpenSSL  engine given by Engine. An error tuple is
1555              returned if the engine can't be unloaded.
1556
1557              The function raises a error:badarg if the parameter is in  wrong
1558              format.  It  may  also  raise the exception error:notsup in case
1559              there is no engine support in the underlying OpenSSL implementa‐
1560              tion.
1561
1562              See also the chapter Engine Load in the User's Guide.
1563
1564       engine_by_id(EngineId) -> Result
1565
1566              Types:
1567
1568                 EngineId = unicode:chardata()
1569                 Result =
1570                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1571
1572              Get  a  reference  to an already loaded engine with EngineId. An
1573              error tuple is returned if the engine can't be unloaded.
1574
1575              The function raises a error:badarg if the parameter is in  wrong
1576              format.  It  may  also  raise the exception error:notsup in case
1577              there is no engine support in the underlying OpenSSL implementa‐
1578              tion.
1579
1580              See also the chapter Engine Load in the User's Guide.
1581
1582       engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1583
1584              Types:
1585
1586                 Engine = term()
1587                 CmdName = CmdArg = unicode:chardata()
1588                 Result = ok | {error, Reason :: term()}
1589
1590              Sends  ctrl commands to the OpenSSL engine given by Engine. This
1591              function is the same as  calling  engine_ctrl_cmd_string/4  with
1592              Optional set to false.
1593
1594              The  function  raises  a  error:badarg  if the parameters are in
1595              wrong format. It may also raise the  exception  error:notsup  in
1596              case there is no engine support in the underlying OpenSSL imple‐
1597              mentation.
1598
1599       engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1600                                 Result
1601
1602              Types:
1603
1604                 Engine = term()
1605                 CmdName = CmdArg = unicode:chardata()
1606                 Optional = boolean()
1607                 Result = ok | {error, Reason :: term()}
1608
1609              Sends ctrl commands to  the  OpenSSL  engine  given  by  Engine.
1610              Optional  is  a boolean argument that can relax the semantics of
1611              the function. If set to true it will only return failure if  the
1612              ENGINE supported the given command name but failed while execut‐
1613              ing it, if the ENGINE doesn't support the command name  it  will
1614              simply  return  success  without doing anything. In this case we
1615              assume the user is only supplying commands specific to the given
1616              ENGINE so we set this to false.
1617
1618              The  function  raises  a  error:badarg  if the parameters are in
1619              wrong format. It may also raise the  exception  error:notsup  in
1620              case there is no engine support in the underlying OpenSSL imple‐
1621              mentation.
1622
1623       engine_add(Engine) -> Result
1624
1625              Types:
1626
1627                 Engine = engine_ref()
1628                 Result = ok | {error, Reason :: term()}
1629
1630              Add the engine to OpenSSL's internal list.
1631
1632              The function raises a error:badarg  if  the  parameters  are  in
1633              wrong  format.  It  may also raise the exception error:notsup in
1634              case there is no engine support in the underlying OpenSSL imple‐
1635              mentation.
1636
1637       engine_remove(Engine) -> Result
1638
1639              Types:
1640
1641                 Engine = engine_ref()
1642                 Result = ok | {error, Reason :: term()}
1643
1644              Remove the engine from OpenSSL's internal list.
1645
1646              The  function  raises  a  error:badarg  if the parameters are in
1647              wrong format. It may also raise the  exception  error:notsup  in
1648              case there is no engine support in the underlying OpenSSL imple‐
1649              mentation.
1650
1651       engine_get_id(Engine) -> EngineId
1652
1653              Types:
1654
1655                 Engine = engine_ref()
1656                 EngineId = unicode:chardata()
1657
1658              Return the ID for the engine, or an empty binary if there is  no
1659              id set.
1660
1661              The  function  raises  a  error:badarg  if the parameters are in
1662              wrong format. It may also raise the  exception  error:notsup  in
1663              case there is no engine support in the underlying OpenSSL imple‐
1664              mentation.
1665
1666       engine_get_name(Engine) -> EngineName
1667
1668              Types:
1669
1670                 Engine = engine_ref()
1671                 EngineName = unicode:chardata()
1672
1673              Return the name (eg a description) for the engine, or  an  empty
1674              binary if there is no name set.
1675
1676              The  function  raises  a  error:badarg  if the parameters are in
1677              wrong format. It may also raise the  exception  error:notsup  in
1678              case there is no engine support in the underlying OpenSSL imple‐
1679              mentation.
1680
1681       engine_list() -> Result
1682
1683              Types:
1684
1685                 Result = [EngineId :: unicode:chardata()]
1686
1687              List the id's of all engines in OpenSSL's internal list.
1688
1689              It may also raise the exception error:notsup in case there is no
1690              engine support in the underlying OpenSSL implementation.
1691
1692              See also the chapter Engine Load in the User's Guide.
1693
1694              May raise exception error:notsup in case engine functionality is
1695              not supported by the underlying OpenSSL implementation.
1696
1697       ensure_engine_loaded(EngineId, LibPath) -> Result
1698
1699              Types:
1700
1701                 EngineId = LibPath = unicode:chardata()
1702                 Result =
1703                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1704
1705              Loads the OpenSSL engine given by EngineId and the path  to  the
1706              dynamic  library  implementing  the engine. This function is the
1707              same as calling ensure_engine_loaded/3 with EngineMethods set to
1708              a  list  of all the possible methods. An error tuple is returned
1709              if the engine can't be loaded.
1710
1711              The function raises a error:badarg  if  the  parameters  are  in
1712              wrong  format.  It  may also raise the exception error:notsup in
1713              case there is no engine support in the underlying OpenSSL imple‐
1714              mentation.
1715
1716              See also the chapter Engine Load in the User's Guide.
1717
1718       ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
1719
1720              Types:
1721
1722                 EngineId = LibPath = unicode:chardata()
1723                 EngineMethods = [engine_method_type()]
1724                 Result =
1725                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1726
1727              Loads  the  OpenSSL engine given by EngineId and the path to the
1728              dynamic library implementing the engine. This  function  differs
1729              from the normal engine_load in that sense it also add the engine
1730              id to the internal list in OpenSSL. Then in the following  calls
1731              to  the  function  it  just  fetch  the  reference to the engine
1732              instead of loading it again. An error tuple is returned  if  the
1733              engine can't be loaded.
1734
1735              The  function  raises  a  error:badarg  if the parameters are in
1736              wrong format. It may also raise the  exception  error:notsup  in
1737              case there is no engine support in the underlying OpenSSL imple‐
1738              mentation.
1739
1740              See also the chapter Engine Load in the User's Guide.
1741
1742       ensure_engine_unloaded(Engine) -> Result
1743
1744              Types:
1745
1746                 Engine = engine_ref()
1747                 Result = ok | {error, Reason :: term()}
1748
1749              Unloads an engine loaded with the ensure_engine_loaded function.
1750              It  both removes the label from the OpenSSL internal engine list
1751              and unloads the engine. This function is  the  same  as  calling
1752              ensure_engine_unloaded/2 with EngineMethods set to a list of all
1753              the possible methods. An error tuple is returned if  the  engine
1754              can't be unloaded.
1755
1756              The  function  raises  a  error:badarg  if the parameters are in
1757              wrong format. It may also raise the  exception  error:notsup  in
1758              case there is no engine support in the underlying OpenSSL imple‐
1759              mentation.
1760
1761              See also the chapter Engine Load in the User's Guide.
1762
1763       ensure_engine_unloaded(Engine, EngineMethods) -> Result
1764
1765              Types:
1766
1767                 Engine = engine_ref()
1768                 EngineMethods = [engine_method_type()]
1769                 Result = ok | {error, Reason :: term()}
1770
1771              Unloads an engine loaded with the ensure_engine_loaded function.
1772              It  both removes the label from the OpenSSL internal engine list
1773              and unloads the engine. An error tuple is returned if the engine
1774              can't be unloaded.
1775
1776              The  function  raises  a  error:badarg  if the parameters are in
1777              wrong format. It may also raise the  exception  error:notsup  in
1778              case there is no engine support in the underlying OpenSSL imple‐
1779              mentation.
1780
1781              See also the chapter Engine Load in the User's Guide.
1782

OLD API

EXPORTS

1785       block_encrypt(Type :: block_cipher_without_iv(),
1786                     Key :: key(),
1787                     PlainText :: iodata()) ->
1788                        binary() | run_time_error()
1789
1790          Dont:
1791              Don't use this function for new programs! Use the-new-api.
1792
1793
1794              Encrypt PlainText according to Type block cipher.
1795
1796              May raise exception error:notsup in case the chosen Type is  not
1797              supported by the underlying libcrypto implementation.
1798
1799              For keylengths and blocksizes see the User's Guide.
1800
1801       block_decrypt(Type :: block_cipher_without_iv(),
1802                     Key :: key(),
1803                     Data :: iodata()) ->
1804                        binary() | run_time_error()
1805
1806          Dont:
1807              Don't use this function for new programs! Use the new api.
1808
1809
1810              Decrypt CipherText according to Type block cipher.
1811
1812              May  raise exception error:notsup in case the chosen Type is not
1813              supported by the underlying libcrypto implementation.
1814
1815              For keylengths and blocksizes see the User's Guide.
1816
1817       block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error
1818       block_encrypt(AeadType, Key, Ivec, {AAD,  PlainText})  ->  {CipherText,
1819       CipherTag} | Error
1820       block_encrypt(aes_gcm   |   aes_ccm,   Key,   Ivec,   {AAD,  PlainText,
1821       TagLength}) -> {CipherText, CipherTag} | Error
1822
1823              Types:
1824
1825                 Type = block_cipher_with_iv()
1826                 AeadType = aead_cipher()
1827                 Key = key() | des3_key()
1828                 PlainText = iodata()
1829                 AAD = IVec = CipherText = CipherTag = binary()
1830                 TagLength = 1..16
1831                 Error = run_time_error()
1832
1833          Dont:
1834              Don't use this function for new programs! Use the new api.
1835
1836
1837              Encrypt PlainText according to Type block  cipher.  IVec  is  an
1838              arbitrary initializing vector.
1839
1840              In  AEAD  (Authenticated  Encryption with Associated Data) mode,
1841              encrypt PlainTextaccording to Type block  cipher  and  calculate
1842              CipherTag  that also authenticates the AAD (Associated Authenti‐
1843              cated Data).
1844
1845              May raise exception error:notsup in case the chosen Type is  not
1846              supported by the underlying libcrypto implementation.
1847
1848              For keylengths, iv-sizes and blocksizes see the User's Guide.
1849
1850       block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error
1851       block_decrypt(AeadType,  Key,  Ivec,  {AAD,  CipherText, CipherTag}) ->
1852       PlainText | Error
1853
1854              Types:
1855
1856                 Type = block_cipher_with_iv()
1857                 AeadType = aead_cipher()
1858                 Key = key() | des3_key()
1859                 PlainText = iodata()
1860                 AAD = IVec = CipherText = CipherTag = binary()
1861                 Error = BadTag | run_time_error()
1862                 BadTag = error
1863
1864          Dont:
1865              Don't use this function for new programs! Use the new api.
1866
1867
1868              Decrypt CipherText according to Type block cipher.  IVec  is  an
1869              arbitrary initializing vector.
1870
1871              In  AEAD  (Authenticated  Encryption with Associated Data) mode,
1872              decrypt CipherTextaccording to Type block cipher and  check  the
1873              authenticity  the  PlainText  and  AAD (Associated Authenticated
1874              Data) using the CipherTag. May return error if the decryption or
1875              validation fail's
1876
1877              May  raise exception error:notsup in case the chosen Type is not
1878              supported by the underlying libcrypto implementation.
1879
1880              For keylengths, iv-sizes and blocksizes see the User's Guide.
1881
1882       stream_init(Type, Key) -> State | run_time_error()
1883
1884              Types:
1885
1886                 Type = rc4
1887                 Key = iodata()
1888                 State = stream_state()
1889
1890          Dont:
1891              Don't use this function for new programs! Use the new api.
1892
1893
1894              Initializes  the  state  for  use  in  RC4   stream   encryption
1895              stream_encrypt and stream_decrypt
1896
1897              For keylengths see the User's Guide.
1898
1899       stream_init(Type, Key, IVec) -> State | run_time_error()
1900
1901              Types:
1902
1903                 Type = stream_cipher()
1904                 Key = iodata()
1905                 IVec = binary()
1906                 State = stream_state()
1907
1908          Dont:
1909              Don't use this function for new programs! Use the new api.
1910
1911
1912              Initializes  the state for use in streaming AES encryption using
1913              Counter mode (CTR). Key is the AES key and must be  either  128,
1914              192,  or 256 bits long. IVec is an arbitrary initializing vector
1915              of  128  bits  (16  bytes).  This  state   is   for   use   with
1916              stream_encrypt and stream_decrypt.
1917
1918              For keylengths and iv-sizes see the User's Guide.
1919
1920       stream_encrypt(State, PlainText) ->
1921                         {NewState, CipherText} | run_time_error()
1922
1923              Types:
1924
1925                 State = stream_state()
1926                 PlainText = iodata()
1927                 NewState = stream_state()
1928                 CipherText = iodata()
1929
1930          Dont:
1931              Don't use this function for new programs! Use the new api.
1932
1933
1934              Encrypts PlainText according to the stream cipher Type specified
1935              in stream_init/3. Text can be any number of bytes.  The  initial
1936              State is created using stream_init. NewState must be passed into
1937              the next call to stream_encrypt.
1938
1939       stream_decrypt(State, CipherText) ->
1940                         {NewState, PlainText} | run_time_error()
1941
1942              Types:
1943
1944                 State = stream_state()
1945                 CipherText = iodata()
1946                 NewState = stream_state()
1947                 PlainText = iodata()
1948
1949          Dont:
1950              Don't use this function for new programs! Use the new api.
1951
1952
1953              Decrypts CipherText according to the stream cipher  Type  speci‐
1954              fied in stream_init/3. PlainText can be any number of bytes. The
1955              initial State is created using  stream_init.  NewState  must  be
1956              passed into the next call to stream_decrypt.
1957
1958       supports() -> [Support]
1959
1960              Types:
1961
1962                 Support =
1963                     {hashs, Hashs} |
1964                     {ciphers, Ciphers} |
1965                     {public_keys, PKs} |
1966                     {macs, Macs} |
1967                     {curves, Curves} |
1968                     {rsa_opts, RSAopts}
1969                 Hashs =
1970                     [sha1() |
1971                      sha2() |
1972                      sha3() |
1973                      blake2() |
1974                      ripemd160 |
1975                      compatibility_only_hash()]
1976                 Ciphers = [cipher()]
1977                 PKs = [rsa | dss | ecdsa | dh | ecdh | ec_gf2m]
1978                 Macs = [hmac | cmac | poly1305]
1979                 Curves =
1980                     [ec_named_curve()       |       edwards_curve_dh()      |
1981                 edwards_curve_ed()]
1982                 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
1983
1984          Dont:
1985              Don't use this function for new programs! Use supports/1 in  the
1986              new api.
1987
1988
1989              Can  be  used to determine which crypto algorithms that are sup‐
1990              ported by the underlying libcrypto library
1991
1992              See hash_info/1 and cipher_info/1 for information about the hash
1993              and cipher algorithms.
1994
1995       hmac(Type, Key, Data) -> Mac
1996
1997       hmac(Type, Key, Data, MacLength) -> Mac
1998
1999              Types:
2000
2001                 Type = hmac_hash_algorithm()
2002                 Key = Data = iodata()
2003                 MacLength = integer()
2004                 Mac = binary()
2005
2006          Dont:
2007              Don't use this function for new programs! Use mac/4 or macN/5 in
2008              the new api.
2009
2010
2011              Computes a HMAC of type Type from Data using Key as the  authen‐
2012              tication key.
2013
2014              MacLength will limit the size of the resultant Mac.
2015
2016       hmac_init(Type, Key) -> State
2017
2018              Types:
2019
2020                 Type = hmac_hash_algorithm()
2021                 Key = iodata()
2022                 State = hmac_state()
2023
2024          Dont:
2025              Don't  use this function for new programs! Use mac_init/3 in the
2026              new api.
2027
2028
2029              Initializes the context  for  streaming  HMAC  operations.  Type
2030              determines which hash function to use in the HMAC operation. Key
2031              is the authentication key. The key can be any length.
2032
2033       hmac_update(State, Data) -> NewState
2034
2035              Types:
2036
2037                 Data = iodata()
2038                 State = NewState = hmac_state()
2039
2040          Dont:
2041              Don't use this function for new programs!  Use  mac_update/2  in
2042              the new api.
2043
2044
2045              Updates  the  HMAC  represented by Context using the given Data.
2046              Context must have been generated using  an  HMAC  init  function
2047              (such  as hmac_init). Data can be any length. NewContext must be
2048              passed into the next call to hmac_update or to one of the  func‐
2049              tions hmac_final and hmac_final_n
2050
2051          Warning:
2052              Do  not  use  a  Context  as  argument  in more than one call to
2053              hmac_update or hmac_final. The semantics of reusing old contexts
2054              in  any  way is undefined and could even crash the VM in earlier
2055              releases. The reason for this limitation is a lack of support in
2056              the underlying libcrypto API.
2057
2058
2059       hmac_final(State) -> Mac
2060
2061              Types:
2062
2063                 State = hmac_state()
2064                 Mac = binary()
2065
2066          Dont:
2067              Don't use this function for new programs! Use mac_final/1 in the
2068              new api.
2069
2070
2071              Finalizes the HMAC operation referenced by Context. The size  of
2072              the  resultant  MAC  is  determined by the type of hash function
2073              used to generate it.
2074
2075       hmac_final_n(State, HashLen) -> Mac
2076
2077              Types:
2078
2079                 State = hmac_state()
2080                 HashLen = integer()
2081                 Mac = binary()
2082
2083          Dont:
2084              Don't use this function for new programs!  Use  mac_finalN/2  in
2085              the new api.
2086
2087
2088              Finalizes the HMAC operation referenced by Context. HashLen must
2089              be greater than zero. Mac will be a binary with at most  HashLen
2090              bytes. Note that if HashLen is greater than the actual number of
2091              bytes returned from the underlying hash, the returned hash  will
2092              have fewer than HashLen bytes.
2093
2094       cmac(Type, Key, Data) -> Mac
2095
2096       cmac(Type, Key, Data, MacLength) -> Mac
2097
2098              Types:
2099
2100                 Type =
2101                     cbc_cipher() |
2102                     cfb_cipher() |
2103                     blowfish_cbc | des_ede3 | rc2_cbc
2104                 Key = Data = iodata()
2105                 MacLength = integer()
2106                 Mac = binary()
2107
2108          Dont:
2109              Don't use this function for new programs! Use mac/4 or macN/5 in
2110              the new api.
2111
2112
2113              Computes a CMAC of type Type from Data using Key as the  authen‐
2114              tication key.
2115
2116              MacLength will limit the size of the resultant Mac.
2117
2118       poly1305(Key :: iodata(), Data :: iodata()) -> Mac
2119
2120              Types:
2121
2122                 Mac = binary()
2123
2124          Dont:
2125              Don't use this function for new programs! Use mac/3 or macN/4 in
2126              the new api.
2127
2128
2129              Computes a POLY1305 message authentication code (Mac) from  Data
2130              using Key as the authentication key.
2131
2132
2133
2134Ericsson AB                      crypto 4.6.2                        crypto(3)
Impressum