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 The CRYPTO User's Guide has more information on FIPS, Engines and Algo‐
97 rithm Details like key lengths.
98
100 Ciphers
101 cipher() = cipher_no_iv() | cipher_iv() | cipher_aead()
102 cipher_no_iv() =
104 aes_128_ecb | aes_192_ecb | aes_256_ecb | aes_ecb |
105 blowfish_ecb | des_ecb | rc4
106 cipher_iv() =
108 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
109 aes_128_ofb | aes_192_ofb | aes_256_ofb | aes_128_cfb128 |
110 aes_192_cfb128 | aes_256_cfb128 | aes_cfb128 | aes_128_cfb8 |
111 aes_192_cfb8 | aes_256_cfb8 | aes_cfb8 | aes_128_ctr |
112 aes_192_ctr | aes_256_ctr | aes_ctr | blowfish_cbc |
113 blowfish_cfb64 | blowfish_ofb64 | chacha20 | des_ede3_cbc |
114 des_ede3_cfb | des_cbc | des_cfb | rc2_cbc
115 cipher_aead() =
117 aes_128_ccm | aes_192_ccm | aes_256_ccm | aes_ccm |
118 aes_128_gcm | aes_192_gcm | aes_256_gcm | aes_gcm |
119 chacha20_poly1305
120 Ciphers known by the CRYPTO application.
122 Note that this list might be reduced if the underlying libcrypto
124 does not support all of them.
125 crypto_opts() = boolean() | [crypto_opt()]
127 crypto_opt() = {encrypt, boolean()} | {padding, padding()}
129 Selects encryption ({encrypt,true}) or decryption ({en‐
131 crypt,false}).
132 padding() = cryptolib_padding() | otp_padding()
134 This option handles padding in the last block. If not set, no
136 padding is done and any bytes in the last unfilled block is
137 silently discarded.
138 cryptolib_padding() = none | pkcs_padding
140 The cryptolib_padding are paddings that may be present in the
142 underlying cryptolib linked to the Erlang/OTP crypto app.
143 For OpenSSL, see the OpenSSL documentation. and find EVP_CI‐
145 PHER_CTX_set_padding() in cryptolib for your linked version.
146 otp_padding() = zero | random
148 Erlang/OTP adds a either padding of zeroes or padding with ran‐
150 dom bytes.
151 Digests and hash
153 hash_algorithm() =
154 sha1() |
155 sha2() |
156 sha3() |
157 blake2() |
158 ripemd160 |
159 compatibility_only_hash()
160 hmac_hash_algorithm() =
162 sha1() | sha2() | sha3() | compatibility_only_hash()
163 cmac_cipher_algorithm() =
165 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
166 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
167 aes_cfb128 | aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 |
168 aes_cfb8 | blowfish_cbc | des_cbc | des_ede3_cbc | rc2_cbc
169 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
171 dss_digest_type() = sha1() | sha2()
173 ecdsa_digest_type() = sha1() | sha2()
175 sha1() = sha
177 sha2() = sha224 | sha256 | sha384 | sha512
179 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
181 blake2() = blake2b | blake2s
183 compatibility_only_hash() = md5 | md4
185 The compatibility_only_hash() algorithms are recommended only
187 for compatibility with existing applications.
188 Elliptic Curves
190 ec_named_curve() =
191 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
192 brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
193 brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
194 brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
195 brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
196 c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
197 c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
198 c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
199 c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
200 prime192v2 | prime192v3 | prime239v1 | prime239v2 |
201 prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
202 secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
203 secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
204 secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
205 sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
206 sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
207 sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
208 wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
209 wtls6 | wtls7 | wtls8 | wtls9
210 edwards_curve_dh() = x25519 | x448
212 edwards_curve_ed() = ed25519 | ed448
214 Note that some curves are disabled if FIPS is enabled.
216 ec_explicit_curve() =
218 {Field :: ec_field(),
219 Curve :: ec_curve(),
220 BasePoint :: binary(),
221 Order :: binary(),
222 CoFactor :: none | binary()}
223 ec_field() = ec_prime_field() | ec_characteristic_two_field()
225 ec_curve() =
227 {A :: binary(), B :: binary(), Seed :: none | binary()}
228 Parametric curve definition.
230 ec_prime_field() = {prime_field, Prime :: integer()}
232 ec_characteristic_two_field() =
234 {characteristic_two_field,
235 M :: integer(),
236 Basis :: ec_basis()}
237 ec_basis() =
239 {tpbasis, K :: integer() >= 0} |
240 {ppbasis,
241 K1 :: integer() >= 0,
242 K2 :: integer() >= 0,
243 K3 :: integer() >= 0} |
244 onbasis
245 Curve definition details.
247 Keys
249 key_integer() = integer() | binary()
250 Always binary() when used as return value
252 Public/Private Keys
254 rsa_public() = [key_integer()]
255 rsa_private() = [key_integer()]
257 rsa_params() =
259 {ModulusSizeInBits :: integer(),
260 PublicExponent :: key_integer()}
261 rsa_public() = [E, N]
263 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
265 Where E is the public exponent, N is public modulus and D is the
267 private exponent. The longer key format contains redundant in‐
268 formation that will make the calculation faster. P1 and P2 are
269 first and second prime factors. E1 and E2 are first and second
270 exponents. C is the CRT coefficient. The terminology is taken
271 from RFC 3447.
272 dss_public() = [key_integer()]
274 dss_private() = [key_integer()]
276 dss_public() = [P, Q, G, Y]
278 Where P, Q and G are the dss parameters and Y is the public key.
280 dss_private() = [P, Q, G, X]
282 Where P, Q and G are the dss parameters and X is the private
284 key.
285 ecdsa_public() = key_integer()
287 ecdsa_private() = key_integer()
289 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
291 eddsa_public() = key_integer()
293 eddsa_private() = key_integer()
295 eddsa_params() = edwards_curve_ed()
297 srp_public() = key_integer()
299 srp_private() = key_integer()
301 srp_public() = key_integer()
303 Where is A or B from SRP design
305 srp_private() = key_integer()
307 Where is a or b from SRP design
309 srp_gen_params() =
311 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
312 srp_comp_params() =
314 {user, srp_user_comp_params()} |
315 {host, srp_host_comp_params()}
316 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
318 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
320 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
322 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
324 Where Verifier is v, Generator is g and Prime is N, DerivedKey
326 is X, and Scrambler is u (optional will be generated if not pro‐
327 vided) from SRP design Version = '3' | '6' | '6a'
328 Public Key Ciphers
330 pk_encrypt_decrypt_algs() = rsa
331 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
333 ported.
334 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
336 rsa_opt() =
338 {rsa_padding, rsa_padding()} |
339 {signature_md, atom()} |
340 {rsa_mgf1_md, sha} |
341 {rsa_oaep_label, binary()} |
342 {rsa_oaep_md, sha}
343 rsa_padding() =
345 rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
346 rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
347 Options for public key encrypt/decrypt. Only RSA is supported.
349 Warning:
351 The RSA options are experimental.
353 The exact set of options and there syntax may be changed without
355 prior notice.
356 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
359 Those option forms are kept only for compatibility and should
361 not be used in new code.
362 Public Key Sign and Verify
364 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
365 Algorithms for sign and verify.
367 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
369 rsa_sign_verify_opt() =
371 {rsa_padding, rsa_sign_verify_padding()} |
372 {rsa_pss_saltlen, integer()} |
373 {rsa_mgf1_md, sha2()}
374 rsa_sign_verify_padding() =
376 rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
377 rsa_no_padding
378 Options for sign and verify.
380 Warning:
382 The RSA options are experimental.
384 The exact set of options and there syntax may be changed without
386 prior notice.
387 Diffie-Hellman Keys and parameters
390 dh_public() = key_integer()
391 dh_private() = key_integer()
393 dh_params() = [key_integer()]
395 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
397 ecdh_public() = key_integer()
399 ecdh_private() = key_integer()
401 ecdh_params() =
403 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
404 Types for Engines
406 engine_key_ref() =
407 #{engine := engine_ref(),
408 key_id := key_id(),
409 password => password(),
410 term() => term()}
411 engine_ref() = term()
413 The result of a call to engine_load/3.
415 key_id() = string() | binary()
417 Identifies the key to be used. The format depends on the loaded
419 engine. It is passed to the ENGINE_load_(private|public)_key
420 functions in libcrypto.
421 password() = string() | binary()
423 The password of the key stored in an engine.
425 engine_method_type() =
427 engine_method_rsa | engine_method_dsa | engine_method_dh |
428 engine_method_rand | engine_method_ecdh |
429 engine_method_ecdsa | engine_method_ciphers |
430 engine_method_digests | engine_method_store |
431 engine_method_pkey_meths | engine_method_pkey_asn1_meths |
432 engine_method_ec
433 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
435 Pre and Post commands for engine_load/3 and /4.
437 Internal data types
439 crypto_state()
440 hash_state()
442 mac_state()
444 Contexts with an internal state that should not be manipulated
446 but passed between function calls.
447
449 Atoms - the older style
450 The exception error:badarg signifies that one or more arguments are of
451 wrong data type, or are otherwise badly formed.
452 The exception error:notsup signifies that the algorithm is known but is
454 not supported by current underlying libcrypto or explicitly disabled
455 when building that.
456 For a list of supported algorithms, see supports(ciphers).
458 3-tuples - the new style
460 The exception is:
461 error:{Tag, C_FileInfo, Description}
463 Tag = badarg | notsup | error
465 C_FileInfo = term() % Usually only useful for the OTP maintainer
466 Description = string() % Clear text, sometimes only useful for the OTP maintainer
467 The exception tags are:
470 badarg:
472 Signifies that one or more arguments are of wrong data type or are
473 otherwise badly formed.
474 notsup:
476 Signifies that the algorithm is known but is not supported by cur‐
477 rent underlying libcrypto or explicitly disabled when building that
478 one.
479 error:
481 An error condition that should not occur, for example a memory al‐
482 location failed or the underlying cryptolib returned an error code,
483 for example "Can't initialize context, step 1". Those text usually
484 needs searching the C-code to be understood.
485 Usually there are more information in the call stack about which argu‐
487 ment caused the exception and what the values where.
488 To catch the exception, use for example:
490 try crypto:crypto_init(Ciph, Key, IV, true)
492 catch
493 error:{Tag, _C_FileInfo, Description} ->
494 do_something(......)
495 .....
496 end
497
500 crypto_init(Cipher, Key, FlagOrOptions) -> State
501 Types:
503 Cipher = cipher_no_iv()
505 Key = iodata()
506 FlagOrOptions = crypto_opts() | boolean()
507 State = crypto_state()
508 Uses the 3-tuple style for error handling.
510 Equivalent to the call crypto_init(Cipher, Key, <<>>, FlagOrOp‐
512 tions). It is intended for ciphers without an IV (nounce).
513 crypto_init(Cipher, Key, IV, FlagOrOptions) -> State
515 Types:
517 Cipher = cipher_iv()
519 Key = IV = iodata()
520 FlagOrOptions = crypto_opts()
521 State = crypto_state()
522 Uses the 3-tuple style for error handling.
524 Initializes a series of encryptions or decryptions and creates
526 an internal state with a reference that is returned.
527 If IV = <<>>, no IV is used. This is intended for ciphers with‐
529 out an IV (nounce). See crypto_init/3.
530 If IV = undefined, the IV must be added by calls to
532 crypto_dyn_iv_update/3. This is intended for cases where the IV
533 (nounce) need to be changed for each encryption and decryption.
534 See crypto_dyn_iv_init/3.
535 The actual encryption or decryption is done by crypto_update/2
537 (or crypto_dyn_iv_update/3 ).
538 For encryption, set the FlagOrOptions to true or [{en‐
540 crypt,true}]. For decryption, set it to false or [{en‐
541 crypt,false}].
542 Padding could be enabled with the option {padding,Padding}. The
544 cryptolib_padding enables pkcs_padding or no padding (none). The
545 paddings zero or random fills the last part of the last block
546 with zeroes or random bytes. If the last block is already full,
547 nothing is added.
548 In decryption, the cryptolib_padding removes such padding, if
550 present. The otp_padding is not removed - it has to be done
551 elsewhere.
552 If padding is {padding,none} or not specified and the total data
554 from all subsequent crypto_updates does not fill the last block
555 fully, that last data is lost. In case of {padding,none} there
556 will be an error in this case. If padding is not specified, the
557 bytes of the unfilled block is silently discarded.
558 The actual padding is performed by crypto_final/1.
560 For blocksizes call cipher_info/1.
562 See examples in the User's Guide.
564 crypto_update(State, Data) -> Result
566 Types:
568 State = crypto_state()
570 Data = iodata()
571 Result = binary()
572 Uses the 3-tuple style for error handling.
574 It does an actual crypto operation on a part of the full text.
576 If the part is less than a number of full blocks, only the full
577 blocks (possibly none) are encrypted or decrypted and the re‐
578 maining bytes are saved to the next crypto_update operation. The
579 State should be created with crypto_init/3 or crypto_init/4.
580 See examples in the User's Guide.
582 crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) -> State
584 Types:
586 Cipher = cipher_iv()
588 Key = iodata()
589 FlagOrOptions = crypto_opts() | boolean()
590 State = crypto_state()
591 Uses the 3-tuple style for error handling.
593 Initializes a series of encryptions or decryptions where the IV
595 is provided later. The actual encryption or decryption is done
596 by crypto_dyn_iv_update/3.
597 The function is equivalent to crypto_init(Cipher, Key, unde‐
599 fined, FlagOrOptions).
600 crypto_final(State) -> FinalResult
602 Types:
604 State = crypto_state()
606 FinalResult = binary()
607 Uses the 3-tuple style for error handling.
609 Finalizes a series of encryptions or decryptions and delivers
611 the final bytes of the final block. The data returned from this
612 function may be empty if no padding was enabled in
613 crypto_init/3,4 or crypto_dyn_iv_init/3.
614 crypto_get_data(State) -> Result
616 Types:
618 State = crypto_state()
620 Result = map()
621 Uses the 3-tuple style for error handling.
623 Returns information about the State in the argument. The infor‐
625 mation is the form of a map, which currently contains at least:
626 size:
628 The number of bytes encrypted or decrypted so far.
629 padding_size:
631 After a call to crypto_final/1 it contains the number of
632 bytes padded. Otherwise 0.
633 padding_type:
635 The type of the padding as provided in the call to
636 crypto_init/3,4.
637 encrypt:
639 Is true if encryption is performed. It is false otherwise.
640 crypto_dyn_iv_update(State, Data, IV) -> Result
642 Types:
644 State = crypto_state()
646 Data = IV = iodata()
647 Result = binary()
648 Uses the 3-tuple style for error handling.
650 Do an actual crypto operation on a part of the full text and the
652 IV is supplied for each part. The State should be created with
653 crypto_dyn_iv_init/3.
654 crypto_one_time(Cipher, Key, Data, FlagOrOptions) -> Result
656 Types:
658 Cipher = cipher_no_iv()
660 Key = Data = iodata()
661 FlagOrOptions = crypto_opts() | boolean()
662 Result = binary()
663 Uses the 3-tuple style for error handling.
665 As crypto_one_time/5 but for ciphers without IVs.
667 crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) -> Result
669 Types:
671 Cipher = cipher_iv()
673 Key = IV = Data = iodata()
674 FlagOrOptions = crypto_opts() | boolean()
675 Result = binary()
676 Uses the 3-tuple style for error handling.
678 Do a complete encrypt or decrypt of the full text in the argu‐
680 ment Data.
681 For encryption, set the FlagOrOptions to true. For decryption,
683 set it to false. For setting other options, see crypto_init/4.
684 See examples in the User's Guide.
686 crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
688 EncFlag :: true) ->
689 Result
690 crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
692 EncFlag) ->
693 Result
694 Types:
696 Cipher = cipher_aead()
698 Key = IV = InText = AAD = iodata()
699 TagOrTagLength = EncryptTagLength | DecryptTag
700 EncryptTagLength = integer() >= 0
701 DecryptTag = iodata()
702 EncFlag = boolean()
703 Result = EncryptResult | DecryptResult
704 EncryptResult = {OutCryptoText, OutTag}
705 DecryptResult = OutPlainText | error
706 OutCryptoText = OutTag = OutPlainText = binary()
707 Uses the 3-tuple style for error handling.
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
752 Types:
754 Key = Data = iodata()
756 Mac = binary()
757 Uses the 3-tuple style for error handling.
759 Short for mac(Type, undefined, Key, Data).
761 mac(Type, SubType, Key, Data) -> Mac
763 Types:
765 Type = hmac | cmac | poly1305
767 SubType =
768 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
769 fined
770 Key = Data = iodata()
771 Mac = binary()
772 Uses the 3-tuple style for error handling.
774 Computes a MAC (Message Authentication Code) of type Type from
776 Data.
777 SubType depends on the MAC Type:
779 * For hmac it is a hash algorithm, see Algorithm Details in
781 the User's Guide.
782 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
784 tails in the User's Guide.
785 * For poly1305 it should be set to undefined or the mac/2
787 function could be used instead, see Algorithm Details in the
788 User's Guide.
789 Key is the authentication key with a length according to the
791 Type and SubType. The key length could be found with the
792 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
793 poly1305 the key length is 32 bytes. Note that the cryptographic
794 quality of the key is not checked.
795 The Mac result will have a default length depending on the Type
797 and SubType. To set a shorter length, use macN/4 or macN/5 in‐
798 stead. The default length is documented in Algorithm Details in
799 the User's Guide.
800 macN(Type :: poly1305, Key, Data, MacLength) -> Mac
802 Types:
804 Key = Data = iodata()
806 Mac = binary()
807 MacLength = integer() >= 1
808 Uses the 3-tuple style for error handling.
810 Short for macN(Type, undefined, Key, Data, MacLength).
812 macN(Type, SubType, Key, Data, MacLength) -> Mac
814 Types:
816 Type = hmac | cmac | poly1305
818 SubType =
819 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
820 fined
821 Key = Data = iodata()
822 Mac = binary()
823 MacLength = integer() >= 1
824 Computes a MAC (Message Authentication Code) as mac/3 and mac/4
826 but MacLength will limit the size of the resultant Mac to at
827 most MacLength bytes. Note that if MacLength is greater than the
828 actual number of bytes returned from the underlying hash, the
829 returned hash will have that shorter length instead.
830 The max MacLength is documented in Algorithm Details in the
832 User's Guide.
833 mac_init(Type :: poly1305, Key) -> State
835 Types:
837 Key = iodata()
839 State = mac_state()
840 Uses the 3-tuple style for error handling.
842 Short for mac_init(Type, undefined, Key).
844 mac_init(Type, SubType, Key) -> State
846 Types:
848 Type = hmac | cmac | poly1305
850 SubType =
851 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
852 fined
853 Key = iodata()
854 State = mac_state()
855 Uses the 3-tuple style for error handling.
857 Initializes the context for streaming MAC operations.
859 Type determines which mac algorithm to use in the MAC operation.
861 SubType depends on the MAC Type:
863 * For hmac it is a hash algorithm, see Algorithm Details in
865 the User's Guide.
866 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
868 tails in the User's Guide.
869 * For poly1305 it should be set to undefined or the mac/2
871 function could be used instead, see Algorithm Details in the
872 User's Guide.
873 Key is the authentication key with a length according to the
875 Type and SubType. The key length could be found with the
876 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
877 poly1305 the key length is 32 bytes. Note that the cryptographic
878 quality of the key is not checked.
879 The returned State should be used in one or more subsequent
881 calls to mac_update/2. The MAC value is finally returned by
882 calling mac_final/1 or mac_finalN/2.
883 See examples in the User's Guide.
885 mac_update(State0, Data) -> State
887 Types:
889 Data = iodata()
891 State0 = State = mac_state()
892 Uses the 3-tuple style for error handling.
894 Updates the MAC represented by State0 using the given Data which
896 could be of any length.
897 The State0 is the State value originally from a MAC init func‐
899 tion, that is mac_init/2, mac_init/3 or a previous call of
900 mac_update/2. The value State0 is returned unchanged by the
901 function as State.
902 mac_final(State) -> Mac
904 Types:
906 State = mac_state()
908 Mac = binary()
909 Uses the 3-tuple style for error handling.
911 Finalizes the MAC operation referenced by State. The Mac result
913 will have a default length depending on the Type and SubType in
914 the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
915 instead. The default length is documented in Algorithm Details
916 in the User's Guide.
917 mac_finalN(State, MacLength) -> Mac
919 Types:
921 State = mac_state()
923 MacLength = integer() >= 1
924 Mac = binary()
925 Uses the 3-tuple style for error handling.
927 Finalizes the MAC operation referenced by State.
929 Mac will be a binary with at most MacLength bytes. Note that if
931 MacLength is greater than the actual number of bytes returned
932 from the underlying hash, the returned hash will have that
933 shorter length instead.
934 The max MacLength is documented in Algorithm Details in the
936 User's Guide.
937 bytes_to_integer(Bin :: binary()) -> integer()
939 Convert binary representation, of an integer, to an Erlang inte‐
941 ger.
942 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
944 SharedSecret
945 Types:
947 Type = dh | ecdh | eddh | srp
949 SharedSecret = binary()
950 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
951 MyPrivateKey =
952 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
953 vate()}
954 Params = dh_params() | ecdh_params() | srp_comp_params()
955 Uses the 3-tuple style for error handling.
957 Computes the shared secret from the private key and the other
959 party's public key. See also public_key:compute_key/2
960 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
962 Performs bit-wise XOR (exclusive or) on the data supplied.
964 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
966 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
968 Types:
970 Type = dh | ecdh | eddh | eddsa | rsa | srp
972 PublicKey =
973 dh_public() | ecdh_public() | rsa_public() | srp_public()
974 PrivKeyIn =
975 undefined |
976 dh_private() |
977 ecdh_private() |
978 rsa_private() |
979 {srp_public(), srp_private()}
980 PrivKeyOut =
981 dh_private() |
982 ecdh_private() |
983 rsa_private() |
984 {srp_public(), srp_private()}
985 Params =
986 dh_params() |
987 ecdh_params() |
988 eddsa_params() |
989 rsa_params() |
990 srp_comp_params()
991 Uses the 3-tuple style for error handling.
993 Generates a public key of type Type. See also public_key:gener‐
995 ate_key/1.
996 Note:
998 If the linked version of cryptolib is OpenSSL 3.0
999 * and the Type is dh (diffie-hellman)
1001 * and the parameter P (in dh_params()) is one of the MODP
1003 groups (see RFC 3526)
1004 * and the optional PrivateKeyBitLength parameter (in
1006 dh_params()) is present,
1007 then the optional key length parameter must be at least 224,
1009 256, 302, 352 and 400 for group sizes of 2048, 3072, 4096, 6144
1010 and 8192, respectively.
1011 Note:
1014 RSA key generation is only available if the runtime was built
1015 with dirty scheduler support. Otherwise, attempting to generate
1016 an RSA key will raise the exception error:notsup.
1017 hash(Type, Data) -> Digest
1020 Types:
1022 Type = hash_algorithm()
1024 Data = iodata()
1025 Digest = binary()
1026 Uses the 3-tuple style for error handling.
1028 Computes a message digest of type Type from Data.
1030 hash_init(Type) -> State
1032 Types:
1034 Type = hash_algorithm()
1036 State = hash_state()
1037 Uses the 3-tuple style for error handling.
1039 Initializes the context for streaming hash operations. Type de‐
1041 termines which digest to use. The returned context should be
1042 used as argument to hash_update.
1043 hash_update(State, Data) -> NewState
1045 Types:
1047 State = NewState = hash_state()
1049 Data = iodata()
1050 Uses the 3-tuple style for error handling.
1052 Updates the digest represented by Context using the given Data.
1054 Context must have been generated using hash_init or a previous
1055 call to this function. Data can be any length. NewContext must
1056 be passed into the next call to hash_update or hash_final.
1057 hash_final(State) -> Digest
1059 Types:
1061 State = hash_state()
1063 Digest = binary()
1064 Uses the 3-tuple style for error handling.
1066 Finalizes the hash operation referenced by Context returned from
1068 a previous call to hash_update. The size of Digest is determined
1069 by the type of hash function used to generate it.
1070 info_fips() -> not_supported | not_enabled | enabled
1072 Provides information about the FIPS operating status of crypto
1074 and the underlying libcrypto library. If crypto was built with
1075 FIPS support this can be either enabled (when running in FIPS
1076 mode) or not_enabled. For other builds this value is always
1077 not_supported.
1078 See enable_fips_mode/1 about how to enable FIPS mode.
1080 Warning:
1082 In FIPS mode all non-FIPS compliant algorithms are disabled and
1083 raise exception error:notsup. Check supports(ciphers) that in
1084 FIPS mode returns the restricted list of available algorithms.
1085 enable_fips_mode(Enable) -> Result
1088 Types:
1090 Enable = Result = boolean()
1092 Enables (Enable = true) or disables (Enable = false) FIPS mode.
1094 Returns true if the operation was successful or false otherwise.
1095 Note that to enable FIPS mode successfully, OTP must be built
1097 with the configure option --enable-fips, and the underlying
1098 libcrypto must also support FIPS.
1099 See also info_fips/0.
1101 info() ->
1103 #{compile_type := normal | debug | valgrind | asan,
1104 cryptolib_version_compiled => string() | undefined,
1105 cryptolib_version_linked := string(),
1106 link_type := dynamic | static,
1107 otp_crypto_version := string()}
1108 Provides a map with information about the compilation and link‐
1110 ing of crypto.
1111 Example:
1113 1> crypto:info().
1115 #{compile_type => normal,
1116 cryptolib_version_compiled => "OpenSSL 3.0.0 7 sep 2021",
1117 cryptolib_version_linked => "OpenSSL 3.0.0 7 sep 2021",
1118 link_type => dynamic,
1119 otp_crypto_version => "5.0.2"}
1120 2>
1121 More association types than documented may be present in the
1124 map.
1125 info_lib() -> [{Name, VerNum, VerStr}]
1127 Types:
1129 Name = binary()
1131 VerNum = integer()
1132 VerStr = binary()
1133 Provides the name and version of the libraries used by crypto.
1135 Name is the name of the library. VerNum is the numeric version
1137 according to the library's own versioning scheme. VerStr con‐
1138 tains a text variant of the version.
1139 > info_lib().
1141 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
1142 Note:
1145 From OTP R16 the numeric version represents the version of the
1146 OpenSSL header files (openssl/opensslv.h) used when crypto was
1147 compiled. The text variant represents the libcrypto library used
1148 at runtime. In earlier OTP versions both numeric and text was
1149 taken from the library.
1150 hash_info(Type) -> Result
1153 Types:
1155 Type = hash_algorithm()
1157 Result =
1158 #{size := integer(),
1159 block_size := integer(),
1160 type := integer()}
1161 Provides a map with information about block_size, size and pos‐
1163 sibly other properties of the hash algorithm in question.
1164 For a list of supported hash algorithms, see supports(hashs).
1166 cipher_info(Type) -> Result
1168 Types:
1170 Type = cipher()
1172 Result =
1173 #{key_length := integer(),
1174 iv_length := integer(),
1175 block_size := integer(),
1176 mode := CipherModes,
1177 type := undefined | integer(),
1178 prop_aead := boolean()}
1179 CipherModes =
1180 undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1181 ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1182 wrap_mode | xts_mode
1183 Provides a map with information about block_size, key_length,
1185 iv_length, aead support and possibly other properties of the ci‐
1186 pher algorithm in question.
1187 Note:
1189 The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb,
1190 aes_gcm and aes_ccm has no keylength in the Type as opposed to
1191 for example aes_128_ctr. They adapt to the length of the key
1192 provided in the encrypt and decrypt function. Therefore it is
1193 impossible to return a valid keylength in the map.
1194 Always use a Type with an explicit key length,
1196 For a list of supported cipher algorithms, see supports(ci‐
1199 phers).
1200 mod_pow(N, P, M) -> Result
1202 Types:
1204 N = P = M = binary() | integer()
1206 Result = binary() | error
1207 Computes the function N^P mod M.
1209 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1211 PlainText
1212 Types:
1214 Algorithm = pk_encrypt_decrypt_algs()
1216 CipherText = binary()
1217 PrivateKey = rsa_private() | engine_key_ref()
1218 Options = pk_encrypt_decrypt_opts()
1219 PlainText = binary()
1220 Uses the 3-tuple style for error handling.
1222 Decrypts the CipherText, encrypted with public_encrypt/4 (or
1224 equivalent function) using the PrivateKey, and returns the
1225 plaintext (message digest). This is a low level signature veri‐
1226 fication operation used for instance by older versions of the
1227 SSL protocol. See also public_key:decrypt_private/[2,3]
1228 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1230 CipherText
1231 Types:
1233 Algorithm = pk_encrypt_decrypt_algs()
1235 PlainText = binary()
1236 PrivateKey = rsa_private() | engine_key_ref()
1237 Options = pk_encrypt_decrypt_opts()
1238 CipherText = binary()
1239 Uses the 3-tuple style for error handling.
1241 Encrypts the PlainText using the PrivateKey and returns the ci‐
1243 phertext. This is a low level signature operation used for in‐
1244 stance by older versions of the SSL protocol. See also pub‐
1245 lic_key:encrypt_private/[2,3]
1246 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1248 PlainText
1249 Types:
1251 Algorithm = pk_encrypt_decrypt_algs()
1253 CipherText = binary()
1254 PublicKey = rsa_public() | engine_key_ref()
1255 Options = pk_encrypt_decrypt_opts()
1256 PlainText = binary()
1257 Uses the 3-tuple style for error handling.
1259 Decrypts the CipherText, encrypted with private_encrypt/4(or
1261 equivalent function) using the PrivateKey, and returns the
1262 plaintext (message digest). This is a low level signature veri‐
1263 fication operation used for instance by older versions of the
1264 SSL protocol. See also public_key:decrypt_public/[2,3]
1265 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1267 CipherText
1268 Types:
1270 Algorithm = pk_encrypt_decrypt_algs()
1272 PlainText = binary()
1273 PublicKey = rsa_public() | engine_key_ref()
1274 Options = pk_encrypt_decrypt_opts()
1275 CipherText = binary()
1276 Uses the 3-tuple style for error handling.
1278 Encrypts the PlainText (message digest) using the PublicKey and
1280 returns the CipherText. This is a low level signature operation
1281 used for instance by older versions of the SSL protocol. See
1282 also public_key:encrypt_public/[2,3]
1283 rand_seed(Seed :: binary()) -> ok
1285 Set the seed for PRNG to the given binary. This calls the
1287 RAND_seed function from openssl. Only use this if the system you
1288 are running on does not have enough "randomness" built in. Nor‐
1289 mally this is when strong_rand_bytes/1 raises error:low_entropy
1290 rand_uniform(Lo, Hi) -> N
1292 Types:
1294 Lo, Hi, N = integer()
1296 Generate a random number N, Lo =< N < Hi. Uses the crypto li‐
1298 brary pseudo-random number generator. Hi must be larger than Lo.
1299 start() -> ok | {error, Reason :: term()}
1301 Equivalent to application:start(crypto).
1303 stop() -> ok | {error, Reason :: term()}
1305 Equivalent to application:stop(crypto).
1307 strong_rand_bytes(N :: integer() >= 0) -> binary()
1309 Generates N bytes randomly uniform 0..255, and returns the re‐
1311 sult in a binary. Uses a cryptographically secure prng seeded
1312 and periodically mixed with operating system provided entropy.
1313 By default this is the RAND_bytes method from OpenSSL.
1314 May raise exception error:low_entropy in case the random genera‐
1316 tor failed due to lack of secure "randomness".
1317 rand_seed() -> rand:state()
1319 Creates state object for random number generation, in order to
1321 generate cryptographically strong random numbers (based on
1322 OpenSSL's BN_rand_range), and saves it in the process dictionary
1323 before returning it as well. See also rand:seed/1 and
1324 rand_seed_s/0.
1325 When using the state object from this function the rand func‐
1327 tions using it may raise exception error:low_entropy in case the
1328 random generator failed due to lack of secure "randomness".
1329 Example
1331 _ = crypto:rand_seed(),
1333 _IntegerValue = rand:uniform(42), % [1; 42]
1334 _FloatValue = rand:uniform(). % [0.0; 1.0[
1335 rand_seed_s() -> rand:state()
1337 Creates state object for random number generation, in order to
1339 generate cryptographically strongly random numbers (based on
1340 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1341 When using the state object from this function the rand func‐
1343 tions using it may raise exception error:low_entropy in case the
1344 random generator failed due to lack of secure "randomness".
1345 Note:
1347 The state returned from this function cannot be used to get a
1348 reproducible random sequence as from the other rand functions,
1349 since reproducibility does not match cryptographically safe.
1350 The only supported usage is to generate one distinct random se‐
1352 quence from this start state.
1353 rand_seed_alg(Alg) -> rand:state()
1356 Types:
1358 Alg = crypto | crypto_cache
1360 Creates state object for random number generation, in order to
1362 generate cryptographically strong random numbers, and saves it
1363 in the process dictionary before returning it as well. See also
1364 rand:seed/1 and rand_seed_alg_s/1.
1365 When using the state object from this function the rand func‐
1367 tions using it may raise exception error:low_entropy in case the
1368 random generator failed due to lack of secure "randomness".
1369 Example
1371 _ = crypto:rand_seed_alg(crypto_cache),
1373 _IntegerValue = rand:uniform(42), % [1; 42]
1374 _FloatValue = rand:uniform(). % [0.0; 1.0[
1375 rand_seed_alg(Alg, Seed) -> rand:state()
1377 Types:
1379 Alg = crypto_aes
1381 Creates a state object for random number generation, in order to
1383 generate cryptographically unpredictable random numbers, and
1384 saves it in the process dictionary before returning it as well.
1385 See also rand_seed_alg_s/2.
1386 Example
1388 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1390 IntegerValue = rand:uniform(42), % [1; 42]
1391 FloatValue = rand:uniform(), % [0.0; 1.0[
1392 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1393 IntegerValue = rand:uniform(42), % Same values
1394 FloatValue = rand:uniform(). % again
1395 rand_seed_alg_s(Alg) -> rand:state()
1398 Types:
1400 Alg = crypto | crypto_cache
1402 Creates state object for random number generation, in order to
1404 generate cryptographically strongly random numbers. See also
1405 rand:seed_s/1.
1406 If Alg is crypto this function behaves exactly like
1408 rand_seed_s/0.
1409 If Alg is crypto_cache this function fetches random data with
1411 OpenSSL's RAND_bytes and caches it for speed using an internal
1412 word size of 56 bits that makes calculations fast on 64 bit ma‐
1413 chines.
1414 When using the state object from this function the rand func‐
1416 tions using it may raise exception error:low_entropy in case the
1417 random generator failed due to lack of secure "randomness".
1418 The cache size can be changed from its default value using the
1420 crypto app's configuration parameter rand_cache_size.
1421 When using the state object from this function the rand func‐
1423 tions using it may throw exception low_entropy in case the ran‐
1424 dom generator failed due to lack of secure "randomness".
1425 Note:
1427 The state returned from this function cannot be used to get a
1428 reproducible random sequence as from the other rand functions,
1429 since reproducibility does not match cryptographically safe.
1430 In fact since random data is cached some numbers may get repro‐
1432 duced if you try, but this is unpredictable.
1433 The only supported usage is to generate one distinct random se‐
1435 quence from this start state.
1436 rand_seed_alg_s(Alg, Seed) -> rand:state()
1439 Types:
1441 Alg = crypto_aes
1443 Creates a state object for random number generation, in order to
1445 generate cryptographically unpredictable random numbers. See
1446 also rand_seed_alg/1.
1447 To get a long period the Xoroshiro928 generator from the rand
1449 module is used as a counter (with period 2^928 - 1) and the gen‐
1450 erator states are scrambled through AES to create 58-bit pseudo
1451 random values.
1452 The result should be statistically completely unpredictable ran‐
1454 dom values, since the scrambling is cryptographically strong and
1455 the period is ridiculously long. But the generated numbers are
1456 not to be regarded as cryptographically strong since there is no
1457 re-keying schedule.
1458 * If you need cryptographically strong random numbers use
1460 rand_seed_alg_s/1 with Alg =:= crypto or Alg =:=
1461 crypto_cache.
1462 * If you need to be able to repeat the sequence use this func‐
1464 tion.
1465 * If you do not need the statistical quality of this function,
1467 there are faster algorithms in the rand module.
1468 Thanks to the used generator the state object supports the
1470 rand:jump/0,1 function with distance 2^512.
1471 Numbers are generated in batches and cached for speed reasons.
1473 The cache size can be changed from its default value using the
1474 crypto app's configuration parameter rand_cache_size.
1475 ec_curves() -> [EllipticCurve]
1477 Types:
1479 EllipticCurve =
1481 ec_named_curve() | edwards_curve_dh() | ed‐
1482 wards_curve_ed()
1483 Can be used to determine which named elliptic curves are sup‐
1485 ported.
1486 ec_curve(CurveName) -> ExplicitCurve
1488 Types:
1490 CurveName = ec_named_curve()
1492 ExplicitCurve = ec_explicit_curve()
1493 Return the defining parameters of a elliptic curve.
1495 sign(Algorithm, DigestType, Msg, Key) -> Signature
1497 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1499 Types:
1501 Algorithm = pk_sign_verify_algs()
1503 DigestType =
1504 rsa_digest_type() |
1505 dss_digest_type() |
1506 ecdsa_digest_type() |
1507 none
1508 Msg = iodata() | {digest, iodata()}
1509 Key =
1510 rsa_private() |
1511 dss_private() |
1512 [ecdsa_private() | ecdsa_params()] |
1513 [eddsa_private() | eddsa_params()] |
1514 engine_key_ref()
1515 Options = pk_sign_verify_opts()
1516 Signature = binary()
1517 Uses the 3-tuple style for error handling.
1519 Creates a digital signature.
1521 The msg is either the binary "cleartext" data to be signed or it
1523 is the hashed value of "cleartext" i.e. the digest (plaintext).
1524 Algorithm dss can only be used together with digest type sha.
1526 See also public_key:sign/3.
1528 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1530 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1532 Result
1533 Types:
1535 Algorithm = pk_sign_verify_algs()
1537 DigestType =
1538 rsa_digest_type() |
1539 dss_digest_type() |
1540 ecdsa_digest_type() |
1541 none
1542 Msg = iodata() | {digest, iodata()}
1543 Signature = binary()
1544 Key =
1545 rsa_public() |
1546 dss_public() |
1547 [ecdsa_public() | ecdsa_params()] |
1548 [eddsa_public() | eddsa_params()] |
1549 engine_key_ref()
1550 Options = pk_sign_verify_opts()
1551 Result = boolean()
1552 Uses the 3-tuple style for error handling.
1554 Verifies a digital signature
1556 The msg is either the binary "cleartext" data to be signed or it
1558 is the hashed value of "cleartext" i.e. the digest (plaintext).
1559 Algorithm dss can only be used together with digest type sha.
1561 See also public_key:verify/4.
1563
1566 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1567 Types:
1569 Type = rsa | dss
1571 EnginePrivateKeyRef = engine_key_ref()
1572 PublicKey = rsa_public() | dss_public()
1573 Fetches the corresponding public key from a private key stored
1575 in an Engine. The key must be of the type indicated by the Type
1576 parameter.
1577 engine_get_all_methods() -> Result
1579 Types:
1581 Result = [engine_method_type()]
1583 Returns a list of all possible engine methods.
1585 May raise exception error:notsup in case there is no engine sup‐
1587 port in the underlying OpenSSL implementation.
1588 See also the chapter Engine Load in the User's Guide.
1590 engine_load(EngineId, PreCmds, PostCmds) -> Result
1592 Types:
1594 EngineId = unicode:chardata()
1596 PreCmds = PostCmds = [engine_cmnd()]
1597 Result =
1598 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1599 Loads the OpenSSL engine given by EngineId if it is available
1601 and intialize it. Returns ok and an engine handle, if the engine
1602 can't be loaded an error tuple is returned.
1603 The function raises a error:badarg if the parameters are in
1605 wrong format. It may also raise the exception error:notsup in
1606 case there is no engine support in the underlying OpenSSL imple‐
1607 mentation.
1608 See also the chapter Engine Load in the User's Guide.
1610 engine_unload(Engine) -> Result
1612 Types:
1614 Engine = engine_ref()
1616 Result = ok | {error, Reason :: term()}
1617 Unloads the OpenSSL engine given by Engine. An error tuple is
1619 returned if the engine can't be unloaded.
1620 The function raises a error:badarg if the parameter is in wrong
1622 format. It may also raise the exception error:notsup in case
1623 there is no engine support in the underlying OpenSSL implementa‐
1624 tion.
1625 See also the chapter Engine Load in the User's Guide.
1627 engine_by_id(EngineId) -> Result
1629 Types:
1631 EngineId = unicode:chardata()
1633 Result =
1634 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1635 Get a reference to an already loaded engine with EngineId. An
1637 error tuple is returned if the engine can't be unloaded.
1638 The function raises a error:badarg if the parameter is in wrong
1640 format. It may also raise the exception error:notsup in case
1641 there is no engine support in the underlying OpenSSL implementa‐
1642 tion.
1643 See also the chapter Engine Load in the User's Guide.
1645 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1647 Types:
1649 Engine = term()
1651 CmdName = CmdArg = unicode:chardata()
1652 Result = ok | {error, Reason :: term()}
1653 Sends ctrl commands to the OpenSSL engine given by Engine. This
1655 function is the same as calling engine_ctrl_cmd_string/4 with
1656 Optional set to false.
1657 The function raises a error:badarg if the parameters are in
1659 wrong format. It may also raise the exception error:notsup in
1660 case there is no engine support in the underlying OpenSSL imple‐
1661 mentation.
1662 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1664 Result
1665 Types:
1667 Engine = term()
1669 CmdName = CmdArg = unicode:chardata()
1670 Optional = boolean()
1671 Result = ok | {error, Reason :: term()}
1672 Sends ctrl commands to the OpenSSL engine given by Engine. Op‐
1674 tional is a boolean argument that can relax the semantics of the
1675 function. If set to true it will only return failure if the EN‐
1676 GINE supported the given command name but failed while executing
1677 it, if the ENGINE doesn't support the command name it will sim‐
1678 ply return success without doing anything. In this case we as‐
1679 sume the user is only supplying commands specific to the given
1680 ENGINE so we set this to false.
1681 The function raises a error:badarg if the parameters are in
1683 wrong format. It may also raise the exception error:notsup in
1684 case there is no engine support in the underlying OpenSSL imple‐
1685 mentation.
1686 engine_add(Engine) -> Result
1688 Types:
1690 Engine = engine_ref()
1692 Result = ok | {error, Reason :: term()}
1693 Add the engine to OpenSSL's internal list.
1695 The function raises a error:badarg if the parameters are in
1697 wrong format. It may also raise the exception error:notsup in
1698 case there is no engine support in the underlying OpenSSL imple‐
1699 mentation.
1700 engine_remove(Engine) -> Result
1702 Types:
1704 Engine = engine_ref()
1706 Result = ok | {error, Reason :: term()}
1707 Remove the engine from OpenSSL's internal list.
1709 The function raises a error:badarg if the parameters are in
1711 wrong format. It may also raise the exception error:notsup in
1712 case there is no engine support in the underlying OpenSSL imple‐
1713 mentation.
1714 engine_register(Engine, EngineMethods) -> Result
1716 Types:
1718 Engine = engine_ref()
1720 EngineMethods = [engine_method_type()]
1721 Result = ok | {error, Reason :: term()}
1722 Register engine to handle some type of methods, for example en‐
1724 gine_method_digests.
1725 The function raises a error:badarg if the parameters are in
1727 wrong format. It may also raise the exception error:notsup in
1728 case there is no engine support in the underlying OpenSSL imple‐
1729 mentation.
1730 engine_unregister(Engine, EngineMethods) -> Result
1732 Types:
1734 Engine = engine_ref()
1736 EngineMethods = [engine_method_type()]
1737 Result = ok | {error, Reason :: term()}
1738 Unregister engine so it don't handle some type of methods.
1740 The function raises a error:badarg if the parameters are in
1742 wrong format. It may also raise the exception error:notsup in
1743 case there is no engine support in the underlying OpenSSL imple‐
1744 mentation.
1745 engine_get_id(Engine) -> EngineId
1747 Types:
1749 Engine = engine_ref()
1751 EngineId = unicode:chardata()
1752 Return the ID for the engine, or an empty binary if there is no
1754 id set.
1755 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 engine_get_name(Engine) -> EngineName
1762 Types:
1764 Engine = engine_ref()
1766 EngineName = unicode:chardata()
1767 Return the name (eg a description) for the engine, or an empty
1769 binary if there is no name set.
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 engine_list() -> Result
1777 Types:
1779 Result = [EngineId :: unicode:chardata()]
1781 List the id's of all engines in OpenSSL's internal list.
1783 It may also raise the exception error:notsup in case there is no
1785 engine support in the underlying OpenSSL implementation.
1786 See also the chapter Engine Load in the User's Guide.
1788 May raise exception error:notsup in case engine functionality is
1790 not supported by the underlying OpenSSL implementation.
1791 ensure_engine_loaded(EngineId, LibPath) -> Result
1793 Types:
1795 EngineId = LibPath = unicode:chardata()
1797 Result =
1798 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1799 Loads an engine given by EngineId and the path to the dynamic
1801 library implementing the engine. An error tuple is returned if
1802 the engine can't be loaded.
1803 This function differs from the normal engine_load in the sense
1805 that it also add the engine id to OpenSSL's internal engine
1806 list. The difference between the first call and the following is
1807 that the first loads the engine with the dynamical engine and
1808 the following calls fetch it from the OpenSSL's engine list. All
1809 references that is returned are equal.
1810 Use engine_unload/1 function to remove the references. But re‐
1812 member that engine_unload/1 just removes the references to the
1813 engine and not the tag in OpenSSL's engine list. That has to be
1814 done with the engine_remove/1 function when needed (just called
1815 once, from any of the references you got).
1816 The function raises a error:badarg if the parameters are in
1818 wrong format. It may also raise the exception error:notsup in
1819 case there is no engine support in the underlying OpenSSL imple‐
1820 mentation.
1821 See also the chapter Engine Load in the User's Guide.
1823 hash_equals(BinA, BinB) -> Result
1825 Types:
1827 BinA = BinB = binary()
1829 Result = boolean()
1830 Constant time memory comparison for fixed length binaries, such
1832 as results of HMAC computations.
1833 Returns true if the binaries are identical, false if they are of
1835 the same length but not identical. The function raises an er‐
1836 ror:badarg exception if the binaries are of different size.
1837 pbkdf2_hmac(Digest, Pass, Salt, Iter, KeyLen) -> Result
1839 Types:
1841 Digest = sha | sha224 | sha256 | sha384 | sha512
1843 Pass = Salt = binary()
1844 Iter = KeyLen = integer() >= 1
1845 Result = binary()
1846 Uses the 3-tuple style for error handling.
1848 PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in
1850 combination with HMAC.
1851Ericsson AB crypto 5.1.4.1 crypto(3)