1crypto(3) Erlang Module Definition crypto(3)
2
6 crypto - Crypto Functions
7
9 This module provides a set of cryptographic functions.
10 Hash functions:
12 SHA1, SHA2:
15 Secure Hash Standard [FIPS PUB 180-4]
16 SHA3:
18 SHA-3 Standard: Permutation-Based Hash and Extendable-Output
19 Functions [FIPS PUB 202]
20 BLAKE2:
22 BLAKE2 — fast secure hashing
23 MD5:
25 The MD5 Message Digest Algorithm [RFC 1321]
26 MD4:
28 The MD4 Message Digest Algorithm [RFC 1320]
29 MACs - Message Authentication Codes:
31 Hmac functions:
34 Keyed-Hashing for Message Authentication [RFC 2104]
35 Cmac functions:
37 The AES-CMAC Algorithm [RFC 4493]
38 POLY1305:
40 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
41 Symmetric Ciphers:
43 DES, 3DES and AES:
46 Block Cipher Techniques [NIST]
47 Blowfish:
49 Fast Software Encryption, Cambridge Security Workshop Proceed‐
50 ings (December 1993), Springer-Verlag, 1994, pp. 191-204.
51 Chacha20:
53 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
54 Chacha20_poly1305:
56 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
57 Modes:
59 ECB, CBC, CFB, OFB and CTR:
62 Recommendation for Block Cipher Modes of Operation: Methods and
63 Techniques [NIST SP 800-38A]
64 GCM:
66 Recommendation for Block Cipher Modes of Operation: Ga‐
67 lois/Counter Mode (GCM) and GMAC [NIST SP 800-38D]
68 CCM:
70 Recommendation for Block Cipher Modes of Operation: The CCM Mode
71 for Authentication and Confidentiality [NIST SP 800-38C]
72 Asymmetric Ciphers - Public Key Techniques:
74 RSA:
77 PKCS #1: RSA Cryptography Specifications [RFC 3447]
78 DSS:
80 Digital Signature Standard (DSS) [FIPS 186-4]
81 ECDSA:
83 Elliptic Curve Digital Signature Algorithm [ECDSA]
84 SRP:
86 The SRP Authentication and Key Exchange System [RFC 2945]
87 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 Enabling FIPS mode will also disable algorithms and features.
94 Note:
97 Compiling, linking and running with OpenSSL 3.0 works although the
98 crypto app calls deprecated functions. We do not recommend it for other
99 than experimental purposes or alpha testing, since it is not exten‐
100 sively tested yet.
101 The CRYPTO User's Guide has more information on FIPS, Engines and Algo‐
104 rithm Details like key lengths.
105
107 Ciphers
108 cipher() = cipher_no_iv() | cipher_iv() | cipher_aead()
109 cipher_no_iv() =
111 aes_128_ecb | aes_192_ecb | aes_256_ecb | aes_ecb |
112 blowfish_ecb | des_ecb | rc4
113 cipher_iv() =
115 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
116 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
117 aes_cfb128 | aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 |
118 aes_cfb8 | aes_128_ctr | aes_192_ctr | aes_256_ctr | aes_ctr |
119 blowfish_cbc | blowfish_cfb64 | blowfish_ofb64 | chacha20 |
120 des_ede3_cbc | des_ede3_cfb | des_cbc | des_cfb | rc2_cbc
121 cipher_aead() =
123 aes_128_ccm | aes_192_ccm | aes_256_ccm | aes_ccm |
124 aes_128_gcm | aes_192_gcm | aes_256_gcm | aes_gcm |
125 chacha20_poly1305
126 Ciphers known by the CRYPTO application.
128 Note that this list might be reduced if the underlying libcrypto
130 does not support all of them.
131 crypto_opts() = boolean() | [crypto_opt()]
133 crypto_opt() = {encrypt, boolean()} | {padding, padding()}
135 Selects encryption ({encrypt,true}) or decryption ({en‐
137 crypt,false}).
138 padding() = cryptolib_padding() | otp_padding()
140 This option handles padding in the last block. If not set, no
142 padding is done and any bytes in the last unfilled block is
143 silently discarded.
144 cryptolib_padding() = none | pkcs_padding
146 The cryptolib_padding are paddings that may be present in the
148 underlying cryptolib linked to the Erlang/OTP crypto app.
149 For OpenSSL, see the OpenSSL documentation. and find EVP_CI‐
151 PHER_CTX_set_padding() in cryptolib for your linked version.
152 otp_padding() = zero | random
154 Erlang/OTP adds a either padding of zeroes or padding with ran‐
156 dom bytes.
157 Digests and hash
159 hash_algorithm() =
160 sha1() |
161 sha2() |
162 sha3() |
163 blake2() |
164 ripemd160 |
165 compatibility_only_hash()
166 hmac_hash_algorithm() =
168 sha1() | sha2() | sha3() | compatibility_only_hash()
169 cmac_cipher_algorithm() =
171 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
172 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
173 aes_cfb128 | aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 |
174 aes_cfb8 | blowfish_cbc | des_cbc | des_ede3_cbc | rc2_cbc
175 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
177 dss_digest_type() = sha1() | sha2()
179 ecdsa_digest_type() = sha1() | sha2()
181 sha1() = sha
183 sha2() = sha224 | sha256 | sha384 | sha512
185 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
187 blake2() = blake2b | blake2s
189 compatibility_only_hash() = md5 | md4
191 The compatibility_only_hash() algorithms are recommended only
193 for compatibility with existing applications.
194 Elliptic Curves
196 ec_named_curve() =
197 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
198 brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
199 brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
200 brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
201 brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
202 c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
203 c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
204 c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
205 c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
206 prime192v2 | prime192v3 | prime239v1 | prime239v2 |
207 prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
208 secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
209 secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
210 secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
211 sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
212 sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
213 sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
214 wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
215 wtls6 | wtls7 | wtls8 | wtls9
216 edwards_curve_dh() = x25519 | x448
218 edwards_curve_ed() = ed25519 | ed448
220 Note that some curves are disabled if FIPS is enabled.
222 ec_explicit_curve() =
224 {Field :: ec_field(),
225 Curve :: ec_curve(),
226 BasePoint :: binary(),
227 Order :: binary(),
228 CoFactor :: none | binary()}
229 ec_field() = ec_prime_field() | ec_characteristic_two_field()
231 ec_curve() =
233 {A :: binary(), B :: binary(), Seed :: none | binary()}
234 Parametric curve definition.
236 ec_prime_field() = {prime_field, Prime :: integer()}
238 ec_characteristic_two_field() =
240 {characteristic_two_field,
241 M :: integer(),
242 Basis :: ec_basis()}
243 ec_basis() =
245 {tpbasis, K :: integer() >= 0} |
246 {ppbasis,
247 K1 :: integer() >= 0,
248 K2 :: integer() >= 0,
249 K3 :: integer() >= 0} |
250 onbasis
251 Curve definition details.
253 Keys
255 key_integer() = integer() | binary()
256 Always binary() when used as return value
258 Public/Private Keys
260 rsa_public() = [key_integer()]
261 rsa_private() = [key_integer()]
263 rsa_params() =
265 {ModulusSizeInBits :: integer(),
266 PublicExponent :: key_integer()}
267 rsa_public() = [E, N]
269 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
271 Where E is the public exponent, N is public modulus and D is the
273 private exponent. The longer key format contains redundant in‐
274 formation that will make the calculation faster. P1 and P2 are
275 first and second prime factors. E1 and E2 are first and second
276 exponents. C is the CRT coefficient. The terminology is taken
277 from RFC 3447.
278 dss_public() = [key_integer()]
280 dss_private() = [key_integer()]
282 dss_public() = [P, Q, G, Y]
284 Where P, Q and G are the dss parameters and Y is the public key.
286 dss_private() = [P, Q, G, X]
288 Where P, Q and G are the dss parameters and X is the private
290 key.
291 ecdsa_public() = key_integer()
293 ecdsa_private() = key_integer()
295 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
297 eddsa_public() = key_integer()
299 eddsa_private() = key_integer()
301 eddsa_params() = edwards_curve_ed()
303 srp_public() = key_integer()
305 srp_private() = key_integer()
307 srp_public() = key_integer()
309 Where is A or B from SRP design
311 srp_private() = key_integer()
313 Where is a or b from SRP design
315 srp_gen_params() =
317 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
318 srp_comp_params() =
320 {user, srp_user_comp_params()} |
321 {host, srp_host_comp_params()}
322 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
324 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
326 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
328 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
330 Where Verifier is v, Generator is g and Prime is N, DerivedKey
332 is X, and Scrambler is u (optional will be generated if not pro‐
333 vided) from SRP design Version = '3' | '6' | '6a'
334 Public Key Ciphers
336 pk_encrypt_decrypt_algs() = rsa
337 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
339 ported.
340 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
342 rsa_opt() =
344 {rsa_padding, rsa_padding()} |
345 {signature_md, atom()} |
346 {rsa_mgf1_md, sha} |
347 {rsa_oaep_label, binary()} |
348 {rsa_oaep_md, sha}
349 rsa_padding() =
351 rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
352 rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
353 Options for public key encrypt/decrypt. Only RSA is supported.
355 Warning:
357 The RSA options are experimental.
359 The exact set of options and there syntax may be changed without
361 prior notice.
362 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
365 Those option forms are kept only for compatibility and should
367 not be used in new code.
368 Public Key Sign and Verify
370 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
371 Algorithms for sign and verify.
373 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
375 rsa_sign_verify_opt() =
377 {rsa_padding, rsa_sign_verify_padding()} |
378 {rsa_pss_saltlen, integer()} |
379 {rsa_mgf1_md, sha2()}
380 rsa_sign_verify_padding() =
382 rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
383 rsa_no_padding
384 Options for sign and verify.
386 Warning:
388 The RSA options are experimental.
390 The exact set of options and there syntax may be changed without
392 prior notice.
393 Diffie-Hellman Keys and parameters
396 dh_public() = key_integer()
397 dh_private() = key_integer()
399 dh_params() = [key_integer()]
401 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
403 ecdh_public() = key_integer()
405 ecdh_private() = key_integer()
407 ecdh_params() =
409 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
410 Types for Engines
412 engine_key_ref() =
413 #{engine := engine_ref(),
414 key_id := key_id(),
415 password => password(),
416 term() => term()}
417 engine_ref() = term()
419 The result of a call to engine_load/3.
421 key_id() = string() | binary()
423 Identifies the key to be used. The format depends on the loaded
425 engine. It is passed to the ENGINE_load_(private|public)_key
426 functions in libcrypto.
427 password() = string() | binary()
429 The password of the key stored in an engine.
431 engine_method_type() =
433 engine_method_rsa | engine_method_dsa | engine_method_dh |
434 engine_method_rand | engine_method_ecdh |
435 engine_method_ecdsa | engine_method_ciphers |
436 engine_method_digests | engine_method_store |
437 engine_method_pkey_meths | engine_method_pkey_asn1_meths |
438 engine_method_ec
439 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
441 Pre and Post commands for engine_load/3 and /4.
443 Internal data types
445 crypto_state()
446 hash_state()
448 mac_state()
450 Contexts with an internal state that should not be manipulated
452 but passed between function calls.
453 Error types
455 run_time_error() = any()
456 The exception error:badarg signifies that one or more arguments
458 are of wrong data type, or are otherwise badly formed.
459 The exception error:notsup signifies that the algorithm is known
461 but is not supported by current underlying libcrypto or explic‐
462 itly disabled when building that.
463 For a list of supported algorithms, see supports(ciphers).
465 descriptive_error() = any()
467 This is a more developed variant of the older run_time_error().
469 The exception is:
471 {Tag, {C_FileName,LineNumber}, Description}
473 Tag = badarg | notsup | error
475 C_FileName = string()
476 LineNumber = integer()
477 Description = string()
478 It is like the older type an exception of the error class. In
481 addition they contain a descriptive text in English. That text
482 is targeted to a developer. Examples are "Bad key size" or "Ci‐
483 pher id is not an atom".
484 The exception tags are:
486 badarg:
488 Signifies that one or more arguments are of wrong data type
489 or are otherwise badly formed.
490 notsup:
492 Signifies that the algorithm is known but is not supported
493 by current underlying libcrypto or explicitly disabled when
494 building that one.
495 error:
497 An error condition that should not occur, for example a mem‐
498 ory allocation failed or the underlying cryptolib returned
499 an error code, for example "Can't initialize context, step
500 1". Those text usually needs searching the C-code to be un‐
501 derstood.
502 To catch the exception, use for example:
504 try crypto:crypto_init(Ciph, Key, IV, true)
506 catch
507 error:{Tag, {C_FileName,LineNumber}, Description} ->
508 do_something(......)
509 .....
510 end
511
514 crypto_init(Cipher, Key, FlagOrOptions) ->
515 State | descriptive_error()
516 Types:
518 Cipher = cipher_no_iv()
520 Key = iodata()
521 FlagOrOptions = crypto_opts() | boolean()
522 State = crypto_state()
523 Equivalent to the call crypto_init(Cipher, Key, <<>>, FlagOrOp‐
525 tions). It is intended for ciphers without an IV (nounce).
526 crypto_init(Cipher, Key, IV, FlagOrOptions) ->
528 State | descriptive_error()
529 Types:
531 Cipher = cipher_iv()
533 Key = IV = iodata()
534 FlagOrOptions = crypto_opts()
535 State = crypto_state()
536 Initializes a series of encryptions or decryptions and creates
538 an internal state with a reference that is returned.
539 If IV = <<>>, no IV is used. This is intended for ciphers with‐
541 out an IV (nounce). See crypto_init/3.
542 If IV = undefined, the IV must be added by calls to
544 crypto_dyn_iv_update/3. This is intended for cases where the IV
545 (nounce) need to be changed for each encryption and decryption.
546 See crypto_dyn_iv_init/3.
547 The actual encryption or decryption is done by crypto_update/2
549 (or crypto_dyn_iv_update/3 ).
550 For encryption, set the FlagOrOptions to true or [{en‐
552 crypt,true}]. For decryption, set it to false or [{en‐
553 crypt,false}].
554 Padding could be enabled with the option {padding,Padding}. The
556 cryptolib_padding enables pkcs_padding or no padding (none). The
557 paddings zero or random fills the last part of the last block
558 with zeroes or random bytes. If the last block is already full,
559 nothing is added.
560 In decryption, the cryptolib_padding removes such padding, if
562 present. The otp_padding is not removed - it has to be done
563 elsewhere.
564 If padding is {padding,none} or not specified and the total data
566 from all subsequent crypto_updates does not fill the last block
567 fully, that last data is lost. In case of {padding,none} there
568 will be an error in this case. If padding is not specified, the
569 bytes of the unfilled block is silently discarded.
570 The actual padding is performed by crypto_final/1.
572 For blocksizes call cipher_info/1.
574 See examples in the User's Guide.
576 crypto_update(State, Data) -> Result | descriptive_error()
578 Types:
580 State = crypto_state()
582 Data = iodata()
583 Result = binary()
584 It does an actual crypto operation on a part of the full text.
586 If the part is less than a number of full blocks, only the full
587 blocks (possibly none) are encrypted or decrypted and the re‐
588 maining bytes are saved to the next crypto_update operation. The
589 State should be created with crypto_init/3 or crypto_init/4.
590 See examples in the User's Guide.
592 crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) ->
594 State | descriptive_error()
595 Types:
597 Cipher = cipher_iv()
599 Key = iodata()
600 FlagOrOptions = crypto_opts() | boolean()
601 State = crypto_state()
602 Initializes a series of encryptions or decryptions where the IV
604 is provided later. The actual encryption or decryption is done
605 by crypto_dyn_iv_update/3.
606 The function is equivalent to crypto_init(Cipher, Key, unde‐
608 fined, FlagOrOptions).
609 crypto_final(State) -> FinalResult | descriptive_error()
611 Types:
613 State = crypto_state()
615 FinalResult = binary()
616 Finalizes a series of encryptions or decryptions and delivers
618 the final bytes of the final block. The data returned from this
619 function may be empty if no padding was enabled in
620 crypto_init/3,4 or crypto_dyn_iv_init/3.
621 crypto_get_data(State) -> Result
623 Types:
625 State = crypto_state()
627 Result = map()
628 Returns information about the State in the argument. The infor‐
630 mation is the form of a map, which currently contains at least:
631 size:
633 The number of bytes encrypted or decrypted so far.
634 padding_size:
636 After a call to crypto_final/1 it contains the number of
637 bytes padded. Otherwise 0.
638 padding_type:
640 The type of the padding as provided in the call to
641 crypto_init/3,4.
642 encrypt:
644 Is true if encryption is performed. It is false otherwise.
645 crypto_dyn_iv_update(State, Data, IV) ->
647 Result | descriptive_error()
648 Types:
650 State = crypto_state()
652 Data = IV = iodata()
653 Result = binary()
654 Do an actual crypto operation on a part of the full text and the
656 IV is supplied for each part. The State should be created with
657 crypto_dyn_iv_init/3.
658 crypto_one_time(Cipher, Key, Data, FlagOrOptions) ->
660 Result | descriptive_error()
661 Types:
663 Cipher = cipher_no_iv()
665 Key = Data = iodata()
666 FlagOrOptions = crypto_opts() | boolean()
667 Result = binary()
668 As crypto_one_time/5 but for ciphers without IVs.
670 crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) ->
672 Result | descriptive_error()
673 Types:
675 Cipher = cipher_iv()
677 Key = IV = Data = iodata()
678 FlagOrOptions = crypto_opts() | boolean()
679 Result = binary()
680 Do a complete encrypt or decrypt of the full text in the argu‐
682 ment Data.
683 For encryption, set the FlagOrOptions to true. For decryption,
685 set it to false. For setting other options, see crypto_init/4.
686 See examples in the User's Guide.
688 crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
690 EncFlag :: true) ->
691 Result | descriptive_error()
692 crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
694 EncFlag) ->
695 Result | descriptive_error()
696 Types:
698 Cipher = cipher_aead()
700 Key = IV = InText = AAD = iodata()
701 TagOrTagLength = EncryptTagLength | DecryptTag
702 EncryptTagLength = integer() >= 0
703 DecryptTag = iodata()
704 EncFlag = boolean()
705 Result = EncryptResult | DecryptResult
706 EncryptResult = {OutCryptoText, OutTag}
707 DecryptResult = OutPlainText | error
708 OutCryptoText = OutTag = OutPlainText = binary()
709 Do a complete encrypt or decrypt with an AEAD cipher of the full
711 text.
712 For encryption, set the EncryptFlag to true and set the TagOrTa‐
714 gLength to the wanted size (in bytes) of the tag, that is, the
715 tag length. If the default length is wanted, the crypto_aead/6
716 form may be used.
717 For decryption, set the EncryptFlag to false and put the tag to
719 be checked in the argument TagOrTagLength.
720 See examples in the User's Guide.
722 supports(Type) -> Support
724 Types:
726 Type = hashs | ciphers | public_keys | macs | curves |
728 rsa_opts
729 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
730 Hashs =
731 [sha1() |
732 sha2() |
733 sha3() |
734 blake2() |
735 ripemd160 |
736 compatibility_only_hash()]
737 Ciphers = [cipher()]
738 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
739 Macs = [hmac | cmac | poly1305]
740 Curves =
741 [ec_named_curve() | edwards_curve_dh() | ed‐
742 wards_curve_ed()]
743 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
744 Can be used to determine which crypto algorithms that are sup‐
746 ported by the underlying libcrypto library
747 See hash_info/1 and cipher_info/1 for information about the hash
749 and cipher algorithms.
750 mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()
752 Types:
754 Key = Data = iodata()
756 Mac = binary()
757 Short for mac(Type, undefined, Key, Data).
759 mac(Type, SubType, Key, Data) -> Mac | descriptive_error()
761 Types:
763 Type = hmac | cmac | poly1305
765 SubType =
766 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
767 fined
768 Key = Data = iodata()
769 Mac = binary()
770 Computes a MAC (Message Authentication Code) of type Type from
772 Data.
773 SubType depends on the MAC Type:
775 * For hmac it is a hash algorithm, see Algorithm Details in
777 the User's Guide.
778 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
780 tails in the User's Guide.
781 * For poly1305 it should be set to undefined or the mac/2
783 function could be used instead, see Algorithm Details in the
784 User's Guide.
785 Key is the authentication key with a length according to the
787 Type and SubType. The key length could be found with the
788 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
789 poly1305 the key length is 32 bytes. Note that the cryptographic
790 quality of the key is not checked.
791 The Mac result will have a default length depending on the Type
793 and SubType. To set a shorter length, use macN/4 or macN/5 in‐
794 stead. The default length is documented in Algorithm Details in
795 the User's Guide.
796 macN(Type :: poly1305, Key, Data, MacLength) ->
798 Mac | descriptive_error()
799 Types:
801 Key = Data = iodata()
803 Mac = binary()
804 MacLength = integer() >= 1
805 Short for macN(Type, undefined, Key, Data, MacLength).
807 macN(Type, SubType, Key, Data, MacLength) ->
809 Mac | descriptive_error()
810 Types:
812 Type = hmac | cmac | poly1305
814 SubType =
815 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
816 fined
817 Key = Data = iodata()
818 Mac = binary()
819 MacLength = integer() >= 1
820 Computes a MAC (Message Authentication Code) as mac/3 and mac/4
822 but MacLength will limit the size of the resultant Mac to at
823 most MacLength bytes. Note that if MacLength is greater than the
824 actual number of bytes returned from the underlying hash, the
825 returned hash will have that shorter length instead.
826 The max MacLength is documented in Algorithm Details in the
828 User's Guide.
829 mac_init(Type :: poly1305, Key) -> State | descriptive_error()
831 Types:
833 Key = iodata()
835 State = mac_state()
836 Short for mac_init(Type, undefined, Key).
838 mac_init(Type, SubType, Key) -> State | descriptive_error()
840 Types:
842 Type = hmac | cmac | poly1305
844 SubType =
845 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
846 fined
847 Key = iodata()
848 State = mac_state()
849 Initializes the context for streaming MAC operations.
851 Type determines which mac algorithm to use in the MAC operation.
853 SubType depends on the MAC Type:
855 * For hmac it is a hash algorithm, see Algorithm Details in
857 the User's Guide.
858 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
860 tails in the User's Guide.
861 * For poly1305 it should be set to undefined or the mac/2
863 function could be used instead, see Algorithm Details in the
864 User's Guide.
865 Key is the authentication key with a length according to the
867 Type and SubType. The key length could be found with the
868 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
869 poly1305 the key length is 32 bytes. Note that the cryptographic
870 quality of the key is not checked.
871 The returned State should be used in one or more subsequent
873 calls to mac_update/2. The MAC value is finally returned by
874 calling mac_final/1 or mac_finalN/2.
875 See examples in the User's Guide.
877 mac_update(State0, Data) -> State | descriptive_error()
879 Types:
881 Data = iodata()
883 State0 = State = mac_state()
884 Updates the MAC represented by State0 using the given Data which
886 could be of any length.
887 The State0 is the State value originally from a MAC init func‐
889 tion, that is mac_init/2, mac_init/3 or a previous call of
890 mac_update/2. The value State0 is returned unchanged by the
891 function as State.
892 mac_final(State) -> Mac | descriptive_error()
894 Types:
896 State = mac_state()
898 Mac = binary()
899 Finalizes the MAC operation referenced by State. The Mac result
901 will have a default length depending on the Type and SubType in
902 the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
903 instead. The default length is documented in Algorithm Details
904 in the User's Guide.
905 mac_finalN(State, MacLength) -> Mac | descriptive_error()
907 Types:
909 State = mac_state()
911 MacLength = integer() >= 1
912 Mac = binary()
913 Finalizes the MAC operation referenced by State.
915 Mac will be a binary with at most MacLength bytes. Note that if
917 MacLength is greater than the actual number of bytes returned
918 from the underlying hash, the returned hash will have that
919 shorter length instead.
920 The max MacLength is documented in Algorithm Details in the
922 User's Guide.
923 bytes_to_integer(Bin :: binary()) -> integer()
925 Convert binary representation, of an integer, to an Erlang inte‐
927 ger.
928 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
930 SharedSecret
931 Types:
933 Type = dh | ecdh | eddh | srp
935 SharedSecret = binary()
936 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
937 MyPrivateKey =
938 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
939 vate()}
940 Params = dh_params() | ecdh_params() | srp_comp_params()
941 Computes the shared secret from the private key and the other
943 party's public key. See also public_key:compute_key/2
944 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
946 Performs bit-wise XOR (exclusive or) on the data supplied.
948 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
950 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
952 Types:
954 Type = dh | ecdh | eddh | eddsa | rsa | srp
956 PublicKey =
957 dh_public() | ecdh_public() | rsa_public() | srp_public()
958 PrivKeyIn =
959 undefined |
960 dh_private() |
961 ecdh_private() |
962 rsa_private() |
963 {srp_public(), srp_private()}
964 PrivKeyOut =
965 dh_private() |
966 ecdh_private() |
967 rsa_private() |
968 {srp_public(), srp_private()}
969 Params =
970 dh_params() |
971 ecdh_params() |
972 eddsa_params() |
973 rsa_params() |
974 srp_comp_params()
975 Generates a public key of type Type. See also public_key:gener‐
977 ate_key/1. May raise exception:
978 * error:badarg: an argument is of wrong type or has an illegal
980 value,
981 * error:low_entropy: the random generator failed due to lack
983 of secure "randomness",
984 * error:computation_failed: the computation fails of another
986 reason than low_entropy.
987 Note:
989 RSA key generation is only available if the runtime was built
990 with dirty scheduler support. Otherwise, attempting to generate
991 an RSA key will raise exception error:notsup.
992 hash(Type, Data) -> Digest
995 Types:
997 Type = hash_algorithm()
999 Data = iodata()
1000 Digest = binary()
1001 Computes a message digest of type Type from Data.
1003 May raise exception error:notsup in case the chosen Type is not
1005 supported by the underlying libcrypto implementation.
1006 hash_init(Type) -> State
1008 Types:
1010 Type = hash_algorithm()
1012 State = hash_state()
1013 Initializes the context for streaming hash operations. Type de‐
1015 termines which digest to use. The returned context should be
1016 used as argument to hash_update.
1017 May raise exception error:notsup in case the chosen Type is not
1019 supported by the underlying libcrypto implementation.
1020 hash_update(State, Data) -> NewState
1022 Types:
1024 State = NewState = hash_state()
1026 Data = iodata()
1027 Updates the digest represented by Context using the given Data.
1029 Context must have been generated using hash_init or a previous
1030 call to this function. Data can be any length. NewContext must
1031 be passed into the next call to hash_update or hash_final.
1032 hash_final(State) -> Digest
1034 Types:
1036 State = hash_state()
1038 Digest = binary()
1039 Finalizes the hash operation referenced by Context returned from
1041 a previous call to hash_update. The size of Digest is determined
1042 by the type of hash function used to generate it.
1043 info_fips() -> not_supported | not_enabled | enabled
1045 Provides information about the FIPS operating status of crypto
1047 and the underlying libcrypto library. If crypto was built with
1048 FIPS support this can be either enabled (when running in FIPS
1049 mode) or not_enabled. For other builds this value is always
1050 not_supported.
1051 See enable_fips_mode/1 about how to enable FIPS mode.
1053 Warning:
1055 In FIPS mode all non-FIPS compliant algorithms are disabled and
1056 raise exception error:notsup. Check supports(ciphers) that in
1057 FIPS mode returns the restricted list of available algorithms.
1058 enable_fips_mode(Enable) -> Result
1061 Types:
1063 Enable = Result = boolean()
1065 Enables (Enable = true) or disables (Enable = false) FIPS mode.
1067 Returns true if the operation was successful or false otherwise.
1068 Note that to enable FIPS mode successfully, OTP must be built
1070 with the configure option --enable-fips, and the underlying
1071 libcrypto must also support FIPS.
1072 See also info_fips/0.
1074 info() ->
1076 #{compile_type := normal | debug | valgrind | asan,
1077 cryptolib_version_compiled => string() | undefined,
1078 cryptolib_version_linked := string(),
1079 link_type := dynamic | static,
1080 otp_crypto_version := string()}
1081 Provides a map with information about the compilation and link‐
1083 ing of crypto.
1084 Example:
1086 1> crypto:info().
1088 #{compile_type => normal,
1089 cryptolib_version_compiled => "OpenSSL 3.0.0 7 sep 2021",
1090 cryptolib_version_linked => "OpenSSL 3.0.0 7 sep 2021",
1091 link_type => dynamic,
1092 otp_crypto_version => "5.0.2"}
1093 2>
1094 More association types than documented may be present in the
1097 map.
1098 info_lib() -> [{Name, VerNum, VerStr}]
1100 Types:
1102 Name = binary()
1104 VerNum = integer()
1105 VerStr = binary()
1106 Provides the name and version of the libraries used by crypto.
1108 Name is the name of the library. VerNum is the numeric version
1110 according to the library's own versioning scheme. VerStr con‐
1111 tains a text variant of the version.
1112 > info_lib().
1114 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
1115 Note:
1118 From OTP R16 the numeric version represents the version of the
1119 OpenSSL header files (openssl/opensslv.h) used when crypto was
1120 compiled. The text variant represents the libcrypto library used
1121 at runtime. In earlier OTP versions both numeric and text was
1122 taken from the library.
1123 hash_info(Type) -> Result | run_time_error()
1126 Types:
1128 Type = hash_algorithm()
1130 Result =
1131 #{size := integer(),
1132 block_size := integer(),
1133 type := integer()}
1134 Provides a map with information about block_size, size and pos‐
1136 sibly other properties of the hash algorithm in question.
1137 For a list of supported hash algorithms, see supports(hashs).
1139 cipher_info(Type) -> Result | run_time_error()
1141 Types:
1143 Type = cipher()
1145 Result =
1146 #{key_length := integer(),
1147 iv_length := integer(),
1148 block_size := integer(),
1149 mode := CipherModes,
1150 type := undefined | integer(),
1151 prop_aead := boolean()}
1152 CipherModes =
1153 undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1154 ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1155 wrap_mode | xts_mode
1156 Provides a map with information about block_size, key_length,
1158 iv_length, aead support and possibly other properties of the ci‐
1159 pher algorithm in question.
1160 Note:
1162 The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb,
1163 aes_gcm and aes_ccm has no keylength in the Type as opposed to
1164 for example aes_128_ctr. They adapt to the length of the key
1165 provided in the encrypt and decrypt function. Therefore it is
1166 impossible to return a valid keylength in the map.
1167 Always use a Type with an explicit key length,
1169 For a list of supported cipher algorithms, see supports(ci‐
1172 phers).
1173 mod_pow(N, P, M) -> Result
1175 Types:
1177 N = P = M = binary() | integer()
1179 Result = binary() | error
1180 Computes the function N^P mod M.
1182 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1184 PlainText
1185 Types:
1187 Algorithm = pk_encrypt_decrypt_algs()
1189 CipherText = binary()
1190 PrivateKey = rsa_private() | engine_key_ref()
1191 Options = pk_encrypt_decrypt_opts()
1192 PlainText = binary()
1193 Decrypts the CipherText, encrypted with public_encrypt/4 (or
1195 equivalent function) using the PrivateKey, and returns the
1196 plaintext (message digest). This is a low level signature veri‐
1197 fication operation used for instance by older versions of the
1198 SSL protocol. See also public_key:decrypt_private/[2,3]
1199 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1201 CipherText
1202 Types:
1204 Algorithm = pk_encrypt_decrypt_algs()
1206 PlainText = binary()
1207 PrivateKey = rsa_private() | engine_key_ref()
1208 Options = pk_encrypt_decrypt_opts()
1209 CipherText = binary()
1210 Encrypts the PlainText using the PrivateKey and returns the ci‐
1212 phertext. This is a low level signature operation used for in‐
1213 stance by older versions of the SSL protocol. See also pub‐
1214 lic_key:encrypt_private/[2,3]
1215 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1217 PlainText
1218 Types:
1220 Algorithm = pk_encrypt_decrypt_algs()
1222 CipherText = binary()
1223 PublicKey = rsa_public() | engine_key_ref()
1224 Options = pk_encrypt_decrypt_opts()
1225 PlainText = binary()
1226 Decrypts the CipherText, encrypted with private_encrypt/4(or
1228 equivalent function) using the PrivateKey, and returns the
1229 plaintext (message digest). This is a low level signature veri‐
1230 fication operation used for instance by older versions of the
1231 SSL protocol. See also public_key:decrypt_public/[2,3]
1232 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1234 CipherText
1235 Types:
1237 Algorithm = pk_encrypt_decrypt_algs()
1239 PlainText = binary()
1240 PublicKey = rsa_public() | engine_key_ref()
1241 Options = pk_encrypt_decrypt_opts()
1242 CipherText = binary()
1243 Encrypts the PlainText (message digest) using the PublicKey and
1245 returns the CipherText. This is a low level signature operation
1246 used for instance by older versions of the SSL protocol. See
1247 also public_key:encrypt_public/[2,3]
1248 rand_seed(Seed :: binary()) -> ok
1250 Set the seed for PRNG to the given binary. This calls the
1252 RAND_seed function from openssl. Only use this if the system you
1253 are running on does not have enough "randomness" built in. Nor‐
1254 mally this is when strong_rand_bytes/1 raises error:low_entropy
1255 rand_uniform(Lo, Hi) -> N
1257 Types:
1259 Lo, Hi, N = integer()
1261 Generate a random number N, Lo =< N < Hi. Uses the crypto li‐
1263 brary pseudo-random number generator. Hi must be larger than Lo.
1264 start() -> ok | {error, Reason :: term()}
1266 Equivalent to application:start(crypto).
1268 stop() -> ok | {error, Reason :: term()}
1270 Equivalent to application:stop(crypto).
1272 strong_rand_bytes(N :: integer() >= 0) -> binary()
1274 Generates N bytes randomly uniform 0..255, and returns the re‐
1276 sult in a binary. Uses a cryptographically secure prng seeded
1277 and periodically mixed with operating system provided entropy.
1278 By default this is the RAND_bytes method from OpenSSL.
1279 May raise exception error:low_entropy in case the random genera‐
1281 tor failed due to lack of secure "randomness".
1282 rand_seed() -> rand:state()
1284 Creates state object for random number generation, in order to
1286 generate cryptographically strong random numbers (based on
1287 OpenSSL's BN_rand_range), and saves it in the process dictionary
1288 before returning it as well. See also rand:seed/1 and
1289 rand_seed_s/0.
1290 When using the state object from this function the rand func‐
1292 tions using it may raise exception error:low_entropy in case the
1293 random generator failed due to lack of secure "randomness".
1294 Example
1296 _ = crypto:rand_seed(),
1298 _IntegerValue = rand:uniform(42), % [1; 42]
1299 _FloatValue = rand:uniform(). % [0.0; 1.0[
1300 rand_seed_s() -> rand:state()
1302 Creates state object for random number generation, in order to
1304 generate cryptographically strongly random numbers (based on
1305 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1306 When using the state object from this function the rand func‐
1308 tions using it may raise exception error:low_entropy in case the
1309 random generator failed due to lack of secure "randomness".
1310 Note:
1312 The state returned from this function cannot be used to get a
1313 reproducible random sequence as from the other rand functions,
1314 since reproducibility does not match cryptographically safe.
1315 The only supported usage is to generate one distinct random se‐
1317 quence from this start state.
1318 rand_seed_alg(Alg) -> rand:state()
1321 Types:
1323 Alg = crypto | crypto_cache
1325 Creates state object for random number generation, in order to
1327 generate cryptographically strong random numbers, and saves it
1328 in the process dictionary before returning it as well. See also
1329 rand:seed/1 and rand_seed_alg_s/1.
1330 When using the state object from this function the rand func‐
1332 tions using it may raise exception error:low_entropy in case the
1333 random generator failed due to lack of secure "randomness".
1334 Example
1336 _ = crypto:rand_seed_alg(crypto_cache),
1338 _IntegerValue = rand:uniform(42), % [1; 42]
1339 _FloatValue = rand:uniform(). % [0.0; 1.0[
1340 rand_seed_alg(Alg, Seed) -> rand:state()
1342 Types:
1344 Alg = crypto_aes
1346 Creates a state object for random number generation, in order to
1348 generate cryptographically unpredictable random numbers, and
1349 saves it in the process dictionary before returning it as well.
1350 See also rand_seed_alg_s/2.
1351 Example
1353 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1355 IntegerValue = rand:uniform(42), % [1; 42]
1356 FloatValue = rand:uniform(), % [0.0; 1.0[
1357 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1358 IntegerValue = rand:uniform(42), % Same values
1359 FloatValue = rand:uniform(). % again
1360 rand_seed_alg_s(Alg) -> rand:state()
1363 Types:
1365 Alg = crypto | crypto_cache
1367 Creates state object for random number generation, in order to
1369 generate cryptographically strongly random numbers. See also
1370 rand:seed_s/1.
1371 If Alg is crypto this function behaves exactly like
1373 rand_seed_s/0.
1374 If Alg is crypto_cache this function fetches random data with
1376 OpenSSL's RAND_bytes and caches it for speed using an internal
1377 word size of 56 bits that makes calculations fast on 64 bit ma‐
1378 chines.
1379 When using the state object from this function the rand func‐
1381 tions using it may raise exception error:low_entropy in case the
1382 random generator failed due to lack of secure "randomness".
1383 The cache size can be changed from its default value using the
1385 crypto app's configuration parameter rand_cache_size.
1386 When using the state object from this function the rand func‐
1388 tions using it may throw exception low_entropy in case the ran‐
1389 dom generator failed due to lack of secure "randomness".
1390 Note:
1392 The state returned from this function cannot be used to get a
1393 reproducible random sequence as from the other rand functions,
1394 since reproducibility does not match cryptographically safe.
1395 In fact since random data is cached some numbers may get repro‐
1397 duced if you try, but this is unpredictable.
1398 The only supported usage is to generate one distinct random se‐
1400 quence from this start state.
1401 rand_seed_alg_s(Alg, Seed) -> rand:state()
1404 Types:
1406 Alg = crypto_aes
1408 Creates a state object for random number generation, in order to
1410 generate cryptographically unpredictable random numbers. See
1411 also rand_seed_alg/1.
1412 To get a long period the Xoroshiro928 generator from the rand
1414 module is used as a counter (with period 2^928 - 1) and the gen‐
1415 erator states are scrambled through AES to create 58-bit pseudo
1416 random values.
1417 The result should be statistically completely unpredictable ran‐
1419 dom values, since the scrambling is cryptographically strong and
1420 the period is ridiculously long. But the generated numbers are
1421 not to be regarded as cryptographically strong since there is no
1422 re-keying schedule.
1423 * If you need cryptographically strong random numbers use
1425 rand_seed_alg_s/1 with Alg =:= crypto or Alg =:=
1426 crypto_cache.
1427 * If you need to be able to repeat the sequence use this func‐
1429 tion.
1430 * If you do not need the statistical quality of this function,
1432 there are faster algorithms in the rand module.
1433 Thanks to the used generator the state object supports the
1435 rand:jump/0,1 function with distance 2^512.
1436 Numbers are generated in batches and cached for speed reasons.
1438 The cache size can be changed from its default value using the
1439 crypto app's configuration parameter rand_cache_size.
1440 ec_curves() -> [EllipticCurve]
1442 Types:
1444 EllipticCurve =
1446 ec_named_curve() | edwards_curve_dh() | ed‐
1447 wards_curve_ed()
1448 Can be used to determine which named elliptic curves are sup‐
1450 ported.
1451 ec_curve(CurveName) -> ExplicitCurve
1453 Types:
1455 CurveName = ec_named_curve()
1457 ExplicitCurve = ec_explicit_curve()
1458 Return the defining parameters of a elliptic curve.
1460 sign(Algorithm, DigestType, Msg, Key) -> Signature
1462 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1464 Types:
1466 Algorithm = pk_sign_verify_algs()
1468 DigestType =
1469 rsa_digest_type() |
1470 dss_digest_type() |
1471 ecdsa_digest_type() |
1472 none
1473 Msg = iodata() | {digest, iodata()}
1474 Key =
1475 rsa_private() |
1476 dss_private() |
1477 [ecdsa_private() | ecdsa_params()] |
1478 [eddsa_private() | eddsa_params()] |
1479 engine_key_ref()
1480 Options = pk_sign_verify_opts()
1481 Signature = binary()
1482 Creates a digital signature.
1484 The msg is either the binary "cleartext" data to be signed or it
1486 is the hashed value of "cleartext" i.e. the digest (plaintext).
1487 Algorithm dss can only be used together with digest type sha.
1489 See also public_key:sign/3.
1491 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1493 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1495 Result
1496 Types:
1498 Algorithm = pk_sign_verify_algs()
1500 DigestType =
1501 rsa_digest_type() |
1502 dss_digest_type() |
1503 ecdsa_digest_type() |
1504 none
1505 Msg = iodata() | {digest, iodata()}
1506 Signature = binary()
1507 Key =
1508 rsa_public() |
1509 dss_public() |
1510 [ecdsa_public() | ecdsa_params()] |
1511 [eddsa_public() | eddsa_params()] |
1512 engine_key_ref()
1513 Options = pk_sign_verify_opts()
1514 Result = boolean()
1515 Verifies a digital signature
1517 The msg is either the binary "cleartext" data to be signed or it
1519 is the hashed value of "cleartext" i.e. the digest (plaintext).
1520 Algorithm dss can only be used together with digest type sha.
1522 See also public_key:verify/4.
1524
1527 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1528 Types:
1530 Type = rsa | dss
1532 EnginePrivateKeyRef = engine_key_ref()
1533 PublicKey = rsa_public() | dss_public()
1534 Fetches the corresponding public key from a private key stored
1536 in an Engine. The key must be of the type indicated by the Type
1537 parameter.
1538 engine_get_all_methods() -> Result
1540 Types:
1542 Result = [engine_method_type()]
1544 Returns a list of all possible engine methods.
1546 May raise exception error:notsup in case there is no engine sup‐
1548 port in the underlying OpenSSL implementation.
1549 See also the chapter Engine Load in the User's Guide.
1551 engine_load(EngineId, PreCmds, PostCmds) -> Result
1553 Types:
1555 EngineId = unicode:chardata()
1557 PreCmds = PostCmds = [engine_cmnd()]
1558 Result =
1559 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1560 Loads the OpenSSL engine given by EngineId if it is available
1562 and then returns ok and an engine handle. This function is the
1563 same as calling engine_load/4 with EngineMethods set to a list
1564 of all the possible methods. An error tuple is returned if the
1565 engine can't be loaded.
1566 The function raises a error:badarg if the parameters are in
1568 wrong format. It may also raise the exception error:notsup in
1569 case there is no engine support in the underlying OpenSSL imple‐
1570 mentation.
1571 See also the chapter Engine Load in the User's Guide.
1573 engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
1575 Types:
1577 EngineId = unicode:chardata()
1579 PreCmds = PostCmds = [engine_cmnd()]
1580 EngineMethods = [engine_method_type()]
1581 Result =
1582 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1583 Loads the OpenSSL engine given by EngineId if it is available
1585 and then returns ok and an engine handle. An error tuple is re‐
1586 turned if the engine can't be loaded.
1587 The function raises a error:badarg if the parameters are in
1589 wrong format. It may also raise the exception error:notsup in
1590 case there is no engine support in the underlying OpenSSL imple‐
1591 mentation.
1592 See also the chapter Engine Load in the User's Guide.
1594 engine_unload(Engine) -> Result
1596 Types:
1598 Engine = engine_ref()
1600 Result = ok | {error, Reason :: term()}
1601 Unloads the OpenSSL engine given by Engine. An error tuple is
1603 returned if the engine can't be unloaded.
1604 The function raises a error:badarg if the parameter is in wrong
1606 format. It may also raise the exception error:notsup in case
1607 there is no engine support in the underlying OpenSSL implementa‐
1608 tion.
1609 See also the chapter Engine Load in the User's Guide.
1611 engine_by_id(EngineId) -> Result
1613 Types:
1615 EngineId = unicode:chardata()
1617 Result =
1618 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1619 Get a reference to an already loaded engine with EngineId. An
1621 error tuple is returned if the engine can't be unloaded.
1622 The function raises a error:badarg if the parameter is in wrong
1624 format. It may also raise the exception error:notsup in case
1625 there is no engine support in the underlying OpenSSL implementa‐
1626 tion.
1627 See also the chapter Engine Load in the User's Guide.
1629 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1631 Types:
1633 Engine = term()
1635 CmdName = CmdArg = unicode:chardata()
1636 Result = ok | {error, Reason :: term()}
1637 Sends ctrl commands to the OpenSSL engine given by Engine. This
1639 function is the same as calling engine_ctrl_cmd_string/4 with
1640 Optional set to false.
1641 The function raises a error:badarg if the parameters are in
1643 wrong format. It may also raise the exception error:notsup in
1644 case there is no engine support in the underlying OpenSSL imple‐
1645 mentation.
1646 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1648 Result
1649 Types:
1651 Engine = term()
1653 CmdName = CmdArg = unicode:chardata()
1654 Optional = boolean()
1655 Result = ok | {error, Reason :: term()}
1656 Sends ctrl commands to the OpenSSL engine given by Engine. Op‐
1658 tional is a boolean argument that can relax the semantics of the
1659 function. If set to true it will only return failure if the EN‐
1660 GINE supported the given command name but failed while executing
1661 it, if the ENGINE doesn't support the command name it will sim‐
1662 ply return success without doing anything. In this case we as‐
1663 sume the user is only supplying commands specific to the given
1664 ENGINE so we set this to false.
1665 The function raises a error:badarg if the parameters are in
1667 wrong format. It may also raise the exception error:notsup in
1668 case there is no engine support in the underlying OpenSSL imple‐
1669 mentation.
1670 engine_add(Engine) -> Result
1672 Types:
1674 Engine = engine_ref()
1676 Result = ok | {error, Reason :: term()}
1677 Add the engine to OpenSSL's internal list.
1679 The function raises a error:badarg if the parameters are in
1681 wrong format. It may also raise the exception error:notsup in
1682 case there is no engine support in the underlying OpenSSL imple‐
1683 mentation.
1684 engine_remove(Engine) -> Result
1686 Types:
1688 Engine = engine_ref()
1690 Result = ok | {error, Reason :: term()}
1691 Remove the engine from OpenSSL's internal list.
1693 The function raises a error:badarg if the parameters are in
1695 wrong format. It may also raise the exception error:notsup in
1696 case there is no engine support in the underlying OpenSSL imple‐
1697 mentation.
1698 engine_get_id(Engine) -> EngineId
1700 Types:
1702 Engine = engine_ref()
1704 EngineId = unicode:chardata()
1705 Return the ID for the engine, or an empty binary if there is no
1707 id set.
1708 The function raises a error:badarg if the parameters are in
1710 wrong format. It may also raise the exception error:notsup in
1711 case there is no engine support in the underlying OpenSSL imple‐
1712 mentation.
1713 engine_get_name(Engine) -> EngineName
1715 Types:
1717 Engine = engine_ref()
1719 EngineName = unicode:chardata()
1720 Return the name (eg a description) for the engine, or an empty
1722 binary if there is no name set.
1723 The function raises a error:badarg if the parameters are in
1725 wrong format. It may also raise the exception error:notsup in
1726 case there is no engine support in the underlying OpenSSL imple‐
1727 mentation.
1728 engine_list() -> Result
1730 Types:
1732 Result = [EngineId :: unicode:chardata()]
1734 List the id's of all engines in OpenSSL's internal list.
1736 It may also raise the exception error:notsup in case there is no
1738 engine support in the underlying OpenSSL implementation.
1739 See also the chapter Engine Load in the User's Guide.
1741 May raise exception error:notsup in case engine functionality is
1743 not supported by the underlying OpenSSL implementation.
1744 ensure_engine_loaded(EngineId, LibPath) -> Result
1746 ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
1748 Types:
1750 EngineId = LibPath = unicode:chardata()
1752 EngineMethods = [engine_method_type()]
1753 Result =
1754 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1755 Loads an engine given by EngineId and the path to the dynamic
1757 library implementing the engine. If the function with arity
1758 three is used, one can specify which engine methods it should
1759 handle. An error tuple is returned if the engine can't be
1760 loaded.
1761 This function differs from the normal engine_load in the sense
1763 that it also add the engine id to OpenSSL's internal engine
1764 list. The reference from the first call holds a functional ref‐
1765 erence to the engine. Then in the following calls to the func‐
1766 tion just fetch a structural reference by looking up the En‐
1767 gineId in OpenSSL's internal engine list. Therefor there is a
1768 difference when unloading the references, see ensure_engine_un‐
1769 loaded.
1770 The function raises a error:badarg if the parameters are in
1772 wrong format. It may also raise the exception error:notsup in
1773 case there is no engine support in the underlying OpenSSL imple‐
1774 mentation.
1775 See also the chapter Engine Load in the User's Guide.
1777 ensure_engine_unloaded(Engine) -> Result
1779 ensure_engine_unloaded(Engine, EngineMethods) -> Result
1781 Types:
1783 Engine = engine_ref()
1785 EngineMethods = [engine_method_type()]
1786 Result = ok | {error, Reason :: term()}
1787 Unloads an engine loaded with the ensure_engine_loaded func‐
1789 tions. The variant with arity two is used when the engine was
1790 loaded with ensure_engine_loaded/3 and the second parameter is
1791 the method list (same as when loaded).
1792 Exactly what happens differ a bit on the reference, if it's the
1794 first reference got by ensure_engine_loaded it both removes the
1795 label from OpenSSL's internal engine list and unloads the en‐
1796 gine. If it's not the reference from the first call it just re‐
1797 moves that refence.
1798 The function raises a error:badarg if the parameters are in
1800 wrong format. It may also raise the exception error:notsup in
1801 case there is no engine support in the underlying OpenSSL imple‐
1802 mentation.
1803 See also the chapter Engine Load in the User's Guide.
1805 pbkdf2_hmac(Digest, Pass, Salt, Iter, KeyLen) -> Result
1807 Types:
1809 Digest = sha | sha224 | sha256 | sha384 | sha512
1811 Pass = Salt = binary()
1812 Iter = KeyLen = integer() >= 1
1813 Result = binary()
1814 PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in
1816 combination with HMAC.
1817 The function raises a error:badarg if the parameters are in
1819 wrong format.
1820Ericsson AB crypto 5.0.6.1 crypto(3)