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 sha3_xof() |
158 blake2() |
159 ripemd160 |
160 compatibility_only_hash()
161 hash_xof_algorithm() = sha3_xof()
163 hmac_hash_algorithm() =
165 sha1() | sha2() | sha3() | compatibility_only_hash()
166 cmac_cipher_algorithm() =
168 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
169 blowfish_cbc | des_cbc | des_ede3_cbc | rc2_cbc
170 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
172 dss_digest_type() = sha1() | sha2()
174 ecdsa_digest_type() = sha1() | sha2()
176 sha1() = sha
178 sha2() = sha224 | sha256 | sha384 | sha512
180 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
182 sha3_xof() = shake128 | shake256
184 blake2() = blake2b | blake2s
186 compatibility_only_hash() = md5 | md4
188 The compatibility_only_hash() algorithms are recommended only
190 for compatibility with existing applications.
191 Elliptic Curves
193 ec_named_curve() =
194 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
195 brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
196 brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
197 brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
198 brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
199 c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
200 c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
201 c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
202 c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
203 prime192v2 | prime192v3 | prime239v1 | prime239v2 |
204 prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
205 secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
206 secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
207 secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
208 sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
209 sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
210 sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
211 wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
212 wtls6 | wtls7 | wtls8 | wtls9
213 edwards_curve_dh() = x25519 | x448
215 edwards_curve_ed() = ed25519 | ed448
217 Note that some curves are disabled if FIPS is enabled.
219 ec_explicit_curve() =
221 {Field :: ec_field(),
222 Curve :: ec_curve(),
223 BasePoint :: binary(),
224 Order :: binary(),
225 CoFactor :: none | binary()}
226 ec_field() = ec_prime_field() | ec_characteristic_two_field()
228 ec_curve() =
230 {A :: binary(), B :: binary(), Seed :: none | binary()}
231 Parametric curve definition.
233 ec_prime_field() = {prime_field, Prime :: integer()}
235 ec_characteristic_two_field() =
237 {characteristic_two_field,
238 M :: integer(),
239 Basis :: ec_basis()}
240 ec_basis() =
242 {tpbasis, K :: integer() >= 0} |
243 {ppbasis,
244 K1 :: integer() >= 0,
245 K2 :: integer() >= 0,
246 K3 :: integer() >= 0} |
247 onbasis
248 Curve definition details.
250 Keys
252 key_integer() = integer() | binary()
253 Always binary() when used as return value
255 Public/Private Keys
257 rsa_public() = [key_integer()]
258 rsa_private() = [key_integer()]
260 rsa_params() =
262 {ModulusSizeInBits :: integer(),
263 PublicExponent :: key_integer()}
264 rsa_public() = [E, N]
266 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
268 Where E is the public exponent, N is public modulus and D is the
270 private exponent. The longer key format contains redundant in‐
271 formation that will make the calculation faster. P1 and P2 are
272 first and second prime factors. E1 and E2 are first and second
273 exponents. C is the CRT coefficient. The terminology is taken
274 from RFC 3447.
275 dss_public() = [key_integer()]
277 dss_private() = [key_integer()]
279 dss_public() = [P, Q, G, Y]
281 Where P, Q and G are the dss parameters and Y is the public key.
283 dss_private() = [P, Q, G, X]
285 Where P, Q and G are the dss parameters and X is the private
287 key.
288 ecdsa_public() = key_integer()
290 ecdsa_private() = key_integer()
292 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
294 eddsa_public() = key_integer()
296 eddsa_private() = key_integer()
298 eddsa_params() = edwards_curve_ed()
300 srp_public() = key_integer()
302 srp_private() = key_integer()
304 srp_public() = key_integer()
306 Where is A or B from SRP design
308 srp_private() = key_integer()
310 Where is a or b from SRP design
312 srp_gen_params() =
314 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
315 srp_comp_params() =
317 {user, srp_user_comp_params()} |
318 {host, srp_host_comp_params()}
319 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
321 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
323 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
325 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
327 Where Verifier is v, Generator is g and Prime is N, DerivedKey
329 is X, and Scrambler is u (optional will be generated if not pro‐
330 vided) from SRP design Version = '3' | '6' | '6a'
331 Public Key Ciphers
333 pk_encrypt_decrypt_algs() = rsa
334 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
336 ported.
337 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
339 rsa_opt() =
341 {rsa_padding, rsa_padding()} |
342 {signature_md, atom()} |
343 {rsa_mgf1_md, sha} |
344 {rsa_oaep_label, binary()} |
345 {rsa_oaep_md, sha}
346 rsa_padding() =
348 rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
349 rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
350 Options for public key encrypt/decrypt. Only RSA is supported.
352 Warning:
354 The RSA options are experimental.
356 The exact set of options and there syntax may be changed without
358 prior notice.
359 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
362 Those option forms are kept only for compatibility and should
364 not be used in new code.
365 Public Key Sign and Verify
367 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
368 Algorithms for sign and verify.
370 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
372 rsa_sign_verify_opt() =
374 {rsa_padding, rsa_sign_verify_padding()} |
375 {rsa_pss_saltlen, integer()} |
376 {rsa_mgf1_md, sha2()}
377 rsa_sign_verify_padding() =
379 rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
380 rsa_no_padding
381 Options for sign and verify.
383 Warning:
385 The RSA options are experimental.
387 The exact set of options and there syntax may be changed without
389 prior notice.
390 Diffie-Hellman Keys and parameters
393 dh_public() = key_integer()
394 dh_private() = key_integer()
396 dh_params() = [key_integer()]
398 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
400 ecdh_public() = key_integer()
402 ecdh_private() = key_integer()
404 ecdh_params() =
406 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
407 Types for Engines
409 engine_key_ref() =
410 #{engine := engine_ref(),
411 key_id := key_id(),
412 password => password(),
413 term() => term()}
414 engine_ref() = term()
416 The result of a call to engine_load/3.
418 key_id() = string() | binary()
420 Identifies the key to be used. The format depends on the loaded
422 engine. It is passed to the ENGINE_load_(private|public)_key
423 functions in libcrypto.
424 password() = string() | binary()
426 The password of the key stored in an engine.
428 engine_method_type() =
430 engine_method_rsa | engine_method_dsa | engine_method_dh |
431 engine_method_rand | engine_method_ecdh |
432 engine_method_ecdsa | engine_method_ciphers |
433 engine_method_digests | engine_method_store |
434 engine_method_pkey_meths | engine_method_pkey_asn1_meths |
435 engine_method_ec
436 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
438 Pre and Post commands for engine_load/3 and /4.
440 Internal data types
442 crypto_state()
443 hash_state()
445 mac_state()
447 Contexts with an internal state that should not be manipulated
449 but passed between function calls.
450
452 Atoms - the older style
453 The exception error:badarg signifies that one or more arguments are of
454 wrong data type, or are otherwise badly formed.
455 The exception error:notsup signifies that the algorithm is known but is
457 not supported by current underlying libcrypto or explicitly disabled
458 when building that.
459 For a list of supported algorithms, see supports(ciphers).
461 3-tuples - the new style
463 The exception is:
464 error:{Tag, C_FileInfo, Description}
466 Tag = badarg | notsup | error
468 C_FileInfo = term() % Usually only useful for the OTP maintainer
469 Description = string() % Clear text, sometimes only useful for the OTP maintainer
470 The exception tags are:
473 badarg:
475 Signifies that one or more arguments are of wrong data type or are
476 otherwise badly formed.
477 notsup:
479 Signifies that the algorithm is known but is not supported by cur‐
480 rent underlying libcrypto or explicitly disabled when building that
481 one.
482 error:
484 An error condition that should not occur, for example a memory al‐
485 location failed or the underlying cryptolib returned an error code,
486 for example "Can't initialize context, step 1". Those text usually
487 needs searching the C-code to be understood.
488 Usually there are more information in the call stack about which argu‐
490 ment caused the exception and what the values where.
491 To catch the exception, use for example:
493 try crypto:crypto_init(Ciph, Key, IV, true)
495 catch
496 error:{Tag, _C_FileInfo, Description} ->
497 do_something(......)
498 .....
499 end
500
503 crypto_init(Cipher, Key, FlagOrOptions) -> State
504 Types:
506 Cipher = cipher_no_iv()
508 Key = iodata()
509 FlagOrOptions = crypto_opts() | boolean()
510 State = crypto_state()
511 Uses the 3-tuple style for error handling.
513 Equivalent to the call crypto_init(Cipher, Key, <<>>, FlagOrOp‐
515 tions). It is intended for ciphers without an IV (nounce).
516 crypto_init(Cipher, Key, IV, FlagOrOptions) -> State
518 Types:
520 Cipher = cipher_iv()
522 Key = IV = iodata()
523 FlagOrOptions = crypto_opts()
524 State = crypto_state()
525 Uses the 3-tuple style for error handling.
527 Initializes a series of encryptions or decryptions and creates
529 an internal state with a reference that is returned.
530 If IV = <<>>, no IV is used. This is intended for ciphers with‐
532 out an IV (nounce). See crypto_init/3.
533 If IV = undefined, the IV must be added by calls to
535 crypto_dyn_iv_update/3. This is intended for cases where the IV
536 (nounce) need to be changed for each encryption and decryption.
537 See crypto_dyn_iv_init/3.
538 The actual encryption or decryption is done by crypto_update/2
540 (or crypto_dyn_iv_update/3 ).
541 For encryption, set the FlagOrOptions to true or [{en‐
543 crypt,true}]. For decryption, set it to false or [{en‐
544 crypt,false}].
545 Padding could be enabled with the option {padding,Padding}. The
547 cryptolib_padding enables pkcs_padding or no padding (none). The
548 paddings zero or random fills the last part of the last block
549 with zeroes or random bytes. If the last block is already full,
550 nothing is added.
551 In decryption, the cryptolib_padding removes such padding, if
553 present. The otp_padding is not removed - it has to be done
554 elsewhere.
555 If padding is {padding,none} or not specified and the total data
557 from all subsequent crypto_updates does not fill the last block
558 fully, that last data is lost. In case of {padding,none} there
559 will be an error in this case. If padding is not specified, the
560 bytes of the unfilled block is silently discarded.
561 The actual padding is performed by crypto_final/1.
563 For blocksizes call cipher_info/1.
565 See examples in the User's Guide.
567 crypto_update(State, Data) -> Result
569 Types:
571 State = crypto_state()
573 Data = iodata()
574 Result = binary()
575 Uses the 3-tuple style for error handling.
577 It does an actual crypto operation on a part of the full text.
579 If the part is less than a number of full blocks, only the full
580 blocks (possibly none) are encrypted or decrypted and the re‐
581 maining bytes are saved to the next crypto_update operation. The
582 State should be created with crypto_init/3 or crypto_init/4.
583 See examples in the User's Guide.
585 crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) -> State
587 Types:
589 Cipher = cipher_iv()
591 Key = iodata()
592 FlagOrOptions = crypto_opts() | boolean()
593 State = crypto_state()
594 Uses the 3-tuple style for error handling.
596 Initializes a series of encryptions or decryptions where the IV
598 is provided later. The actual encryption or decryption is done
599 by crypto_dyn_iv_update/3.
600 The function is equivalent to crypto_init(Cipher, Key, unde‐
602 fined, FlagOrOptions).
603 crypto_final(State) -> FinalResult
605 Types:
607 State = crypto_state()
609 FinalResult = binary()
610 Uses the 3-tuple style for error handling.
612 Finalizes a series of encryptions or decryptions and delivers
614 the final bytes of the final block. The data returned from this
615 function may be empty if no padding was enabled in
616 crypto_init/3,4 or crypto_dyn_iv_init/3.
617 crypto_get_data(State) -> Result
619 Types:
621 State = crypto_state()
623 Result = map()
624 Uses the 3-tuple style for error handling.
626 Returns information about the State in the argument. The infor‐
628 mation is the form of a map, which currently contains at least:
629 size:
631 The number of bytes encrypted or decrypted so far.
632 padding_size:
634 After a call to crypto_final/1 it contains the number of
635 bytes padded. Otherwise 0.
636 padding_type:
638 The type of the padding as provided in the call to
639 crypto_init/3,4.
640 encrypt:
642 Is true if encryption is performed. It is false otherwise.
643 crypto_dyn_iv_update(State, Data, IV) -> Result
645 Types:
647 State = crypto_state()
649 Data = IV = iodata()
650 Result = binary()
651 Uses the 3-tuple style for error handling.
653 Do an actual crypto operation on a part of the full text and the
655 IV is supplied for each part. The State should be created with
656 crypto_dyn_iv_init/3.
657 crypto_one_time(Cipher, Key, Data, FlagOrOptions) -> Result
659 Types:
661 Cipher = cipher_no_iv()
663 Key = Data = iodata()
664 FlagOrOptions = crypto_opts() | boolean()
665 Result = binary()
666 Uses the 3-tuple style for error handling.
668 As crypto_one_time/5 but for ciphers without IVs.
670 crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) -> Result
672 Types:
674 Cipher = cipher_iv()
676 Key = IV = Data = iodata()
677 FlagOrOptions = crypto_opts() | boolean()
678 Result = binary()
679 Uses the 3-tuple style for error handling.
681 Do a complete encrypt or decrypt of the full text in the argu‐
683 ment Data.
684 For encryption, set the FlagOrOptions to true. For decryption,
686 set it to false. For setting other options, see crypto_init/4.
687 See examples in the User's Guide.
689 crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
691 EncFlag :: true) ->
692 Result
693 crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
695 EncFlag) ->
696 Result
697 Types:
699 Cipher = cipher_aead()
701 Key = IV = InText = AAD = iodata()
702 TagOrTagLength = EncryptTagLength | DecryptTag
703 EncryptTagLength = integer() >= 0
704 DecryptTag = iodata()
705 EncFlag = boolean()
706 Result = EncryptResult | DecryptResult
707 EncryptResult = {OutCryptoText, OutTag}
708 DecryptResult = OutPlainText | error
709 OutCryptoText = OutTag = OutPlainText = binary()
710 Uses the 3-tuple style for error handling.
712 Do a complete encrypt or decrypt with an AEAD cipher of the full
714 text.
715 For encryption, set the EncryptFlag to true and set the TagOrTa‐
717 gLength to the wanted size (in bytes) of the tag, that is, the
718 tag length. If the default length is wanted, the crypto_aead/6
719 form may be used.
720 For decryption, set the EncryptFlag to false and put the tag to
722 be checked in the argument TagOrTagLength.
723 See examples in the User's Guide.
725 supports(Type) -> Support
727 Types:
729 Type = hashs | ciphers | public_keys | macs | curves |
731 rsa_opts
732 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
733 Hashs =
734 [sha1() |
735 sha2() |
736 sha3() |
737 sha3_xof() |
738 blake2() |
739 ripemd160 |
740 compatibility_only_hash()]
741 Ciphers = [cipher()]
742 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
743 Macs = [hmac | cmac | poly1305]
744 Curves =
745 [ec_named_curve() | edwards_curve_dh() | ed‐
746 wards_curve_ed()]
747 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
748 Can be used to determine which crypto algorithms that are sup‐
750 ported by the underlying libcrypto library
751 See hash_info/1 and cipher_info/1 for information about the hash
753 and cipher algorithms.
754 mac(Type :: poly1305, Key, Data) -> Mac
756 Types:
758 Key = Data = iodata()
760 Mac = binary()
761 Uses the 3-tuple style for error handling.
763 Short for mac(Type, undefined, Key, Data).
765 mac(Type, SubType, Key, Data) -> Mac
767 Types:
769 Type = hmac | cmac | poly1305
771 SubType =
772 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
773 fined
774 Key = Data = iodata()
775 Mac = binary()
776 Uses the 3-tuple style for error handling.
778 Computes a MAC (Message Authentication Code) of type Type from
780 Data.
781 SubType depends on the MAC Type:
783 * For hmac it is a hash algorithm, see Algorithm Details in
785 the User's Guide.
786 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
788 tails in the User's Guide.
789 * For poly1305 it should be set to undefined or the mac/2
791 function could be used instead, see Algorithm Details in the
792 User's Guide.
793 Key is the authentication key with a length according to the
795 Type and SubType. The key length could be found with the
796 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
797 poly1305 the key length is 32 bytes. Note that the cryptographic
798 quality of the key is not checked.
799 The Mac result will have a default length depending on the Type
801 and SubType. To set a shorter length, use macN/4 or macN/5 in‐
802 stead. The default length is documented in Algorithm Details in
803 the User's Guide.
804 macN(Type :: poly1305, Key, Data, MacLength) -> Mac
806 Types:
808 Key = Data = iodata()
810 Mac = binary()
811 MacLength = integer() >= 1
812 Uses the 3-tuple style for error handling.
814 Short for macN(Type, undefined, Key, Data, MacLength).
816 macN(Type, SubType, Key, Data, MacLength) -> Mac
818 Types:
820 Type = hmac | cmac | poly1305
822 SubType =
823 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
824 fined
825 Key = Data = iodata()
826 Mac = binary()
827 MacLength = integer() >= 1
828 Computes a MAC (Message Authentication Code) as mac/3 and mac/4
830 but MacLength will limit the size of the resultant Mac to at
831 most MacLength bytes. Note that if MacLength is greater than the
832 actual number of bytes returned from the underlying hash, the
833 returned hash will have that shorter length instead.
834 The max MacLength is documented in Algorithm Details in the
836 User's Guide.
837 mac_init(Type :: poly1305, Key) -> State
839 Types:
841 Key = iodata()
843 State = mac_state()
844 Uses the 3-tuple style for error handling.
846 Short for mac_init(Type, undefined, Key).
848 mac_init(Type, SubType, Key) -> State
850 Types:
852 Type = hmac | cmac | poly1305
854 SubType =
855 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
856 fined
857 Key = iodata()
858 State = mac_state()
859 Uses the 3-tuple style for error handling.
861 Initializes the context for streaming MAC operations.
863 Type determines which mac algorithm to use in the MAC operation.
865 SubType depends on the MAC Type:
867 * For hmac it is a hash algorithm, see Algorithm Details in
869 the User's Guide.
870 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
872 tails in the User's Guide.
873 * For poly1305 it should be set to undefined or the mac/2
875 function could be used instead, see Algorithm Details in the
876 User's Guide.
877 Key is the authentication key with a length according to the
879 Type and SubType. The key length could be found with the
880 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
881 poly1305 the key length is 32 bytes. Note that the cryptographic
882 quality of the key is not checked.
883 The returned State should be used in one or more subsequent
885 calls to mac_update/2. The MAC value is finally returned by
886 calling mac_final/1 or mac_finalN/2.
887 See examples in the User's Guide.
889 mac_update(State0, Data) -> State
891 Types:
893 Data = iodata()
895 State0 = State = mac_state()
896 Uses the 3-tuple style for error handling.
898 Updates the MAC represented by State0 using the given Data which
900 could be of any length.
901 The State0 is the State value originally from a MAC init func‐
903 tion, that is mac_init/2, mac_init/3 or a previous call of
904 mac_update/2. The value State0 is returned unchanged by the
905 function as State.
906 mac_final(State) -> Mac
908 Types:
910 State = mac_state()
912 Mac = binary()
913 Uses the 3-tuple style for error handling.
915 Finalizes the MAC operation referenced by State. The Mac result
917 will have a default length depending on the Type and SubType in
918 the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
919 instead. The default length is documented in Algorithm Details
920 in the User's Guide.
921 mac_finalN(State, MacLength) -> Mac
923 Types:
925 State = mac_state()
927 MacLength = integer() >= 1
928 Mac = binary()
929 Uses the 3-tuple style for error handling.
931 Finalizes the MAC operation referenced by State.
933 Mac will be a binary with at most MacLength bytes. Note that if
935 MacLength is greater than the actual number of bytes returned
936 from the underlying hash, the returned hash will have that
937 shorter length instead.
938 The max MacLength is documented in Algorithm Details in the
940 User's Guide.
941 bytes_to_integer(Bin :: binary()) -> integer()
943 Convert binary representation, of an integer, to an Erlang inte‐
945 ger.
946 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
948 SharedSecret
949 Types:
951 Type = dh | ecdh | eddh | srp
953 SharedSecret = binary()
954 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
955 MyPrivateKey =
956 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
957 vate()}
958 Params = dh_params() | ecdh_params() | srp_comp_params()
959 Uses the 3-tuple style for error handling.
961 Computes the shared secret from the private key and the other
963 party's public key. See also public_key:compute_key/2
964 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
966 Performs bit-wise XOR (exclusive or) on the data supplied.
968 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
970 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
972 Types:
974 Type = dh | ecdh | eddh | eddsa | rsa | srp
976 PublicKey =
977 dh_public() | ecdh_public() | rsa_public() | srp_public()
978 PrivKeyIn =
979 undefined |
980 dh_private() |
981 ecdh_private() |
982 rsa_private() |
983 {srp_public(), srp_private()}
984 PrivKeyOut =
985 dh_private() |
986 ecdh_private() |
987 rsa_private() |
988 {srp_public(), srp_private()}
989 Params =
990 dh_params() |
991 ecdh_params() |
992 eddsa_params() |
993 rsa_params() |
994 srp_comp_params()
995 Uses the 3-tuple style for error handling.
997 Generates a public key of type Type. See also public_key:gener‐
999 ate_key/1.
1000 Note:
1002 If the linked version of cryptolib is OpenSSL 3.0
1003 * and the Type is dh (diffie-hellman)
1005 * and the parameter P (in dh_params()) is one of the MODP
1007 groups (see RFC 3526)
1008 * and the optional PrivateKeyBitLength parameter (in
1010 dh_params()) is present,
1011 then the optional key length parameter must be at least 224,
1013 256, 302, 352 and 400 for group sizes of 2048, 3072, 4096, 6144
1014 and 8192, respectively.
1015 Note:
1018 RSA key generation is only available if the runtime was built
1019 with dirty scheduler support. Otherwise, attempting to generate
1020 an RSA key will raise the exception error:notsup.
1021 hash(Type, Data) -> Digest
1024 Types:
1026 Type = hash_algorithm()
1028 Data = iodata()
1029 Digest = binary()
1030 Uses the 3-tuple style for error handling.
1032 Computes a message digest of type Type from Data.
1034 hash_xof(Type, Data, Length) -> Digest
1036 Types:
1038 Type = hash_xof_algorithm()
1040 Data = iodata()
1041 Length = integer() >= 0
1042 Digest = binary()
1043 Uses the 3-tuple style for error handling.
1045 Computes a message digest of type Type from Data of Length for
1047 the chosen xof_algorithm.
1048 May raise exception error:notsup in case the chosen Type is not
1050 supported by the underlying libcrypto implementation.
1051 hash_init(Type) -> State
1053 Types:
1055 Type = hash_algorithm()
1057 State = hash_state()
1058 Uses the 3-tuple style for error handling.
1060 Initializes the context for streaming hash operations. Type de‐
1062 termines which digest to use. The returned context should be
1063 used as argument to hash_update.
1064 hash_update(State, Data) -> NewState
1066 Types:
1068 State = NewState = hash_state()
1070 Data = iodata()
1071 Uses the 3-tuple style for error handling.
1073 Updates the digest represented by Context using the given Data.
1075 Context must have been generated using hash_init or a previous
1076 call to this function. Data can be any length. NewContext must
1077 be passed into the next call to hash_update or hash_final.
1078 hash_final(State) -> Digest
1080 Types:
1082 State = hash_state()
1084 Digest = binary()
1085 Uses the 3-tuple style for error handling.
1087 Finalizes the hash operation referenced by Context returned from
1089 a previous call to hash_update. The size of Digest is determined
1090 by the type of hash function used to generate it.
1091 info_fips() -> not_supported | not_enabled | enabled
1093 Provides information about the FIPS operating status of crypto
1095 and the underlying libcrypto library. If crypto was built with
1096 FIPS support this can be either enabled (when running in FIPS
1097 mode) or not_enabled. For other builds this value is always
1098 not_supported.
1099 See enable_fips_mode/1 about how to enable FIPS mode.
1101 Warning:
1103 In FIPS mode all non-FIPS compliant algorithms are disabled and
1104 raise exception error:notsup. Check supports(ciphers) that in
1105 FIPS mode returns the restricted list of available algorithms.
1106 enable_fips_mode(Enable) -> Result
1109 Types:
1111 Enable = Result = boolean()
1113 Enables (Enable = true) or disables (Enable = false) FIPS mode.
1115 Returns true if the operation was successful or false otherwise.
1116 Note that to enable FIPS mode successfully, OTP must be built
1118 with the configure option --enable-fips, and the underlying
1119 libcrypto must also support FIPS.
1120 See also info_fips/0.
1122 info() ->
1124 #{compile_type := normal | debug | valgrind | asan,
1125 cryptolib_version_compiled => string() | undefined,
1126 cryptolib_version_linked := string(),
1127 link_type := dynamic | static,
1128 otp_crypto_version := string()}
1129 Provides a map with information about the compilation and link‐
1131 ing of crypto.
1132 Example:
1134 1> crypto:info().
1136 #{compile_type => normal,
1137 cryptolib_version_compiled => "OpenSSL 3.0.0 7 sep 2021",
1138 cryptolib_version_linked => "OpenSSL 3.0.0 7 sep 2021",
1139 link_type => dynamic,
1140 otp_crypto_version => "5.0.2"}
1141 2>
1142 More association types than documented may be present in the
1145 map.
1146 info_lib() -> [{Name, VerNum, VerStr}]
1148 Types:
1150 Name = binary()
1152 VerNum = integer()
1153 VerStr = binary()
1154 Provides the name and version of the libraries used by crypto.
1156 Name is the name of the library. VerNum is the numeric version
1158 according to the library's own versioning scheme. VerStr con‐
1159 tains a text variant of the version.
1160 > info_lib().
1162 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
1163 Note:
1166 From OTP R16 the numeric version represents the version of the
1167 OpenSSL header files (openssl/opensslv.h) used when crypto was
1168 compiled. The text variant represents the libcrypto library used
1169 at runtime. In earlier OTP versions both numeric and text was
1170 taken from the library.
1171 hash_info(Type) -> Result
1174 Types:
1176 Type = hash_algorithm()
1178 Result =
1179 #{size := integer(),
1180 block_size := integer(),
1181 type := integer()}
1182 Provides a map with information about block_size, size and pos‐
1184 sibly other properties of the hash algorithm in question.
1185 For a list of supported hash algorithms, see supports(hashs).
1187 cipher_info(Type) -> Result
1189 Types:
1191 Type = cipher()
1193 Result =
1194 #{key_length := integer(),
1195 iv_length := integer(),
1196 block_size := integer(),
1197 mode := CipherModes,
1198 type := undefined | integer(),
1199 prop_aead := boolean()}
1200 CipherModes =
1201 undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1202 ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1203 wrap_mode | xts_mode
1204 Provides a map with information about block_size, key_length,
1206 iv_length, aead support and possibly other properties of the ci‐
1207 pher algorithm in question.
1208 Note:
1210 The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb,
1211 aes_gcm and aes_ccm has no keylength in the Type as opposed to
1212 for example aes_128_ctr. They adapt to the length of the key
1213 provided in the encrypt and decrypt function. Therefore it is
1214 impossible to return a valid keylength in the map.
1215 Always use a Type with an explicit key length,
1217 For a list of supported cipher algorithms, see supports(ci‐
1220 phers).
1221 mod_pow(N, P, M) -> Result
1223 Types:
1225 N = P = M = binary() | integer()
1227 Result = binary() | error
1228 Computes the function N^P mod M.
1230 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1232 PlainText
1233 Types:
1235 Algorithm = pk_encrypt_decrypt_algs()
1237 CipherText = binary()
1238 PrivateKey = rsa_private() | engine_key_ref()
1239 Options = pk_encrypt_decrypt_opts()
1240 PlainText = binary()
1241 Uses the 3-tuple style for error handling.
1243 Decrypts the CipherText, encrypted with public_encrypt/4 (or
1245 equivalent function) using the PrivateKey, and returns the
1246 plaintext (message digest). This is a low level signature veri‐
1247 fication operation used for instance by older versions of the
1248 SSL protocol. See also public_key:decrypt_private/[2,3]
1249 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1251 CipherText
1252 Types:
1254 Algorithm = pk_encrypt_decrypt_algs()
1256 PlainText = binary()
1257 PrivateKey = rsa_private() | engine_key_ref()
1258 Options = pk_encrypt_decrypt_opts()
1259 CipherText = binary()
1260 Uses the 3-tuple style for error handling.
1262 Encrypts the PlainText using the PrivateKey and returns the ci‐
1264 phertext. This is a low level signature operation used for in‐
1265 stance by older versions of the SSL protocol. See also pub‐
1266 lic_key:encrypt_private/[2,3]
1267 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1269 PlainText
1270 Types:
1272 Algorithm = pk_encrypt_decrypt_algs()
1274 CipherText = binary()
1275 PublicKey = rsa_public() | engine_key_ref()
1276 Options = pk_encrypt_decrypt_opts()
1277 PlainText = binary()
1278 Uses the 3-tuple style for error handling.
1280 Decrypts the CipherText, encrypted with private_encrypt/4(or
1282 equivalent function) using the PrivateKey, and returns the
1283 plaintext (message digest). This is a low level signature veri‐
1284 fication operation used for instance by older versions of the
1285 SSL protocol. See also public_key:decrypt_public/[2,3]
1286 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1288 CipherText
1289 Types:
1291 Algorithm = pk_encrypt_decrypt_algs()
1293 PlainText = binary()
1294 PublicKey = rsa_public() | engine_key_ref()
1295 Options = pk_encrypt_decrypt_opts()
1296 CipherText = binary()
1297 Uses the 3-tuple style for error handling.
1299 Encrypts the PlainText (message digest) using the PublicKey and
1301 returns the CipherText. This is a low level signature operation
1302 used for instance by older versions of the SSL protocol. See
1303 also public_key:encrypt_public/[2,3]
1304 rand_seed(Seed :: binary()) -> ok
1306 Set the seed for PRNG to the given binary. This calls the
1308 RAND_seed function from openssl. Only use this if the system you
1309 are running on does not have enough "randomness" built in. Nor‐
1310 mally this is when strong_rand_bytes/1 raises error:low_entropy
1311 rand_uniform(Lo, Hi) -> N
1313 Types:
1315 Lo, Hi, N = integer()
1317 Generate a random number N, Lo =< N < Hi. Uses the crypto li‐
1319 brary pseudo-random number generator. Hi must be larger than Lo.
1320 start() -> ok | {error, Reason :: term()}
1322 Equivalent to application:start(crypto).
1324 stop() -> ok | {error, Reason :: term()}
1326 Equivalent to application:stop(crypto).
1328 strong_rand_bytes(N :: integer() >= 0) -> binary()
1330 Generates N bytes randomly uniform 0..255, and returns the re‐
1332 sult in a binary. Uses a cryptographically secure prng seeded
1333 and periodically mixed with operating system provided entropy.
1334 By default this is the RAND_bytes method from OpenSSL.
1335 May raise exception error:low_entropy in case the random genera‐
1337 tor failed due to lack of secure "randomness".
1338 rand_seed() -> rand:state()
1340 Creates state object for random number generation, in order to
1342 generate cryptographically strong random numbers (based on
1343 OpenSSL's BN_rand_range), and saves it in the process dictionary
1344 before returning it as well. See also rand:seed/1 and
1345 rand_seed_s/0.
1346 When using the state object from this function the rand func‐
1348 tions using it may raise exception error:low_entropy in case the
1349 random generator failed due to lack of secure "randomness".
1350 Example
1352 _ = crypto:rand_seed(),
1354 _IntegerValue = rand:uniform(42), % [1; 42]
1355 _FloatValue = rand:uniform(). % [0.0; 1.0[
1356 rand_seed_s() -> rand:state()
1358 Creates state object for random number generation, in order to
1360 generate cryptographically strongly random numbers (based on
1361 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1362 When using the state object from this function the rand func‐
1364 tions using it may raise exception error:low_entropy in case the
1365 random generator failed due to lack of secure "randomness".
1366 Note:
1368 The state returned from this function cannot be used to get a
1369 reproducible random sequence as from the other rand functions,
1370 since reproducibility does not match cryptographically safe.
1371 The only supported usage is to generate one distinct random se‐
1373 quence from this start state.
1374 rand_seed_alg(Alg) -> rand:state()
1377 Types:
1379 Alg = crypto | crypto_cache
1381 Creates state object for random number generation, in order to
1383 generate cryptographically strong random numbers, and saves it
1384 in the process dictionary before returning it as well. See also
1385 rand:seed/1 and rand_seed_alg_s/1.
1386 When using the state object from this function the rand func‐
1388 tions using it may raise exception error:low_entropy in case the
1389 random generator failed due to lack of secure "randomness".
1390 Example
1392 _ = crypto:rand_seed_alg(crypto_cache),
1394 _IntegerValue = rand:uniform(42), % [1; 42]
1395 _FloatValue = rand:uniform(). % [0.0; 1.0[
1396 rand_seed_alg(Alg, Seed) -> rand:state()
1398 Types:
1400 Alg = crypto_aes
1402 Creates a state object for random number generation, in order to
1404 generate cryptographically unpredictable random numbers, and
1405 saves it in the process dictionary before returning it as well.
1406 See also rand_seed_alg_s/2.
1407 Example
1409 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1411 IntegerValue = rand:uniform(42), % [1; 42]
1412 FloatValue = rand:uniform(), % [0.0; 1.0[
1413 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1414 IntegerValue = rand:uniform(42), % Same values
1415 FloatValue = rand:uniform(). % again
1416 rand_seed_alg_s(Alg) -> rand:state()
1419 Types:
1421 Alg = crypto | crypto_cache
1423 Creates state object for random number generation, in order to
1425 generate cryptographically strongly random numbers. See also
1426 rand:seed_s/1.
1427 If Alg is crypto this function behaves exactly like
1429 rand_seed_s/0.
1430 If Alg is crypto_cache this function fetches random data with
1432 OpenSSL's RAND_bytes and caches it for speed using an internal
1433 word size of 56 bits that makes calculations fast on 64 bit ma‐
1434 chines.
1435 When using the state object from this function the rand func‐
1437 tions using it may raise exception error:low_entropy in case the
1438 random generator failed due to lack of secure "randomness".
1439 The cache size can be changed from its default value using the
1441 crypto app's configuration parameter rand_cache_size.
1442 When using the state object from this function the rand func‐
1444 tions using it may throw exception low_entropy in case the ran‐
1445 dom generator failed due to lack of secure "randomness".
1446 Note:
1448 The state returned from this function cannot be used to get a
1449 reproducible random sequence as from the other rand functions,
1450 since reproducibility does not match cryptographically safe.
1451 In fact since random data is cached some numbers may get repro‐
1453 duced if you try, but this is unpredictable.
1454 The only supported usage is to generate one distinct random se‐
1456 quence from this start state.
1457 rand_seed_alg_s(Alg, Seed) -> rand:state()
1460 Types:
1462 Alg = crypto_aes
1464 Creates a state object for random number generation, in order to
1466 generate cryptographically unpredictable random numbers. See
1467 also rand_seed_alg/1.
1468 To get a long period the Xoroshiro928 generator from the rand
1470 module is used as a counter (with period 2^928 - 1) and the gen‐
1471 erator states are scrambled through AES to create 58-bit pseudo
1472 random values.
1473 The result should be statistically completely unpredictable ran‐
1475 dom values, since the scrambling is cryptographically strong and
1476 the period is ridiculously long. But the generated numbers are
1477 not to be regarded as cryptographically strong since there is no
1478 re-keying schedule.
1479 * If you need cryptographically strong random numbers use
1481 rand_seed_alg_s/1 with Alg =:= crypto or Alg =:=
1482 crypto_cache.
1483 * If you need to be able to repeat the sequence use this func‐
1485 tion.
1486 * If you do not need the statistical quality of this function,
1488 there are faster algorithms in the rand module.
1489 Thanks to the used generator the state object supports the
1491 rand:jump/0,1 function with distance 2^512.
1492 Numbers are generated in batches and cached for speed reasons.
1494 The cache size can be changed from its default value using the
1495 crypto app's configuration parameter rand_cache_size.
1496 ec_curves() -> [EllipticCurve]
1498 Types:
1500 EllipticCurve =
1502 ec_named_curve() | edwards_curve_dh() | ed‐
1503 wards_curve_ed()
1504 Can be used to determine which named elliptic curves are sup‐
1506 ported.
1507 ec_curve(CurveName) -> ExplicitCurve
1509 Types:
1511 CurveName = ec_named_curve()
1513 ExplicitCurve = ec_explicit_curve()
1514 Return the defining parameters of a elliptic curve.
1516 sign(Algorithm, DigestType, Msg, Key) -> Signature
1518 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1520 Types:
1522 Algorithm = pk_sign_verify_algs()
1524 DigestType =
1525 rsa_digest_type() |
1526 dss_digest_type() |
1527 ecdsa_digest_type() |
1528 none
1529 Msg = iodata() | {digest, iodata()}
1530 Key =
1531 rsa_private() |
1532 dss_private() |
1533 [ecdsa_private() | ecdsa_params()] |
1534 [eddsa_private() | eddsa_params()] |
1535 engine_key_ref()
1536 Options = pk_sign_verify_opts()
1537 Signature = binary()
1538 Uses the 3-tuple style for error handling.
1540 Creates a digital signature.
1542 The msg is either the binary "cleartext" data to be signed or it
1544 is the hashed value of "cleartext" i.e. the digest (plaintext).
1545 Algorithm dss can only be used together with digest type sha.
1547 See also public_key:sign/3.
1549 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1551 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1553 Result
1554 Types:
1556 Algorithm = pk_sign_verify_algs()
1558 DigestType =
1559 rsa_digest_type() |
1560 dss_digest_type() |
1561 ecdsa_digest_type() |
1562 none
1563 Msg = iodata() | {digest, iodata()}
1564 Signature = binary()
1565 Key =
1566 rsa_public() |
1567 dss_public() |
1568 [ecdsa_public() | ecdsa_params()] |
1569 [eddsa_public() | eddsa_params()] |
1570 engine_key_ref()
1571 Options = pk_sign_verify_opts()
1572 Result = boolean()
1573 Uses the 3-tuple style for error handling.
1575 Verifies a digital signature
1577 The msg is either the binary "cleartext" data to be signed or it
1579 is the hashed value of "cleartext" i.e. the digest (plaintext).
1580 Algorithm dss can only be used together with digest type sha.
1582 See also public_key:verify/4.
1584
1587 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1588 Types:
1590 Type = rsa | dss
1592 EnginePrivateKeyRef = engine_key_ref()
1593 PublicKey = rsa_public() | dss_public()
1594 Fetches the corresponding public key from a private key stored
1596 in an Engine. The key must be of the type indicated by the Type
1597 parameter.
1598 engine_get_all_methods() -> Result
1600 Types:
1602 Result = [engine_method_type()]
1604 Returns a list of all possible engine methods.
1606 May raise exception error:notsup in case there is no engine sup‐
1608 port in the underlying OpenSSL implementation.
1609 See also the chapter Engine Load in the User's Guide.
1611 engine_load(EngineId, PreCmds, PostCmds) -> Result
1613 Types:
1615 EngineId = unicode:chardata()
1617 PreCmds = PostCmds = [engine_cmnd()]
1618 Result =
1619 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1620 Loads the OpenSSL engine given by EngineId if it is available
1622 and intialize it. Returns ok and an engine handle, if the engine
1623 can't be loaded an error tuple is returned.
1624 The function raises a error:badarg if the parameters are in
1626 wrong format. It may also raise the exception error:notsup in
1627 case there is no engine support in the underlying OpenSSL imple‐
1628 mentation.
1629 See also the chapter Engine Load in the User's Guide.
1631 engine_unload(Engine) -> Result
1633 Types:
1635 Engine = engine_ref()
1637 Result = ok | {error, Reason :: term()}
1638 Unloads the OpenSSL engine given by Engine. An error tuple is
1640 returned if the engine can't be unloaded.
1641 The function raises a error:badarg if the parameter is in wrong
1643 format. It may also raise the exception error:notsup in case
1644 there is no engine support in the underlying OpenSSL implementa‐
1645 tion.
1646 See also the chapter Engine Load in the User's Guide.
1648 engine_by_id(EngineId) -> Result
1650 Types:
1652 EngineId = unicode:chardata()
1654 Result =
1655 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1656 Get a reference to an already loaded engine with EngineId. An
1658 error tuple is returned if the engine can't be unloaded.
1659 The function raises a error:badarg if the parameter is in wrong
1661 format. It may also raise the exception error:notsup in case
1662 there is no engine support in the underlying OpenSSL implementa‐
1663 tion.
1664 See also the chapter Engine Load in the User's Guide.
1666 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1668 Types:
1670 Engine = term()
1672 CmdName = CmdArg = unicode:chardata()
1673 Result = ok | {error, Reason :: term()}
1674 Sends ctrl commands to the OpenSSL engine given by Engine. This
1676 function is the same as calling engine_ctrl_cmd_string/4 with
1677 Optional set to false.
1678 The function raises a error:badarg if the parameters are in
1680 wrong format. It may also raise the exception error:notsup in
1681 case there is no engine support in the underlying OpenSSL imple‐
1682 mentation.
1683 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1685 Result
1686 Types:
1688 Engine = term()
1690 CmdName = CmdArg = unicode:chardata()
1691 Optional = boolean()
1692 Result = ok | {error, Reason :: term()}
1693 Sends ctrl commands to the OpenSSL engine given by Engine. Op‐
1695 tional is a boolean argument that can relax the semantics of the
1696 function. If set to true it will only return failure if the EN‐
1697 GINE supported the given command name but failed while executing
1698 it, if the ENGINE doesn't support the command name it will sim‐
1699 ply return success without doing anything. In this case we as‐
1700 sume the user is only supplying commands specific to the given
1701 ENGINE so we set this to false.
1702 The function raises a error:badarg if the parameters are in
1704 wrong format. It may also raise the exception error:notsup in
1705 case there is no engine support in the underlying OpenSSL imple‐
1706 mentation.
1707 engine_add(Engine) -> Result
1709 Types:
1711 Engine = engine_ref()
1713 Result = ok | {error, Reason :: term()}
1714 Add the engine to OpenSSL's internal list.
1716 The function raises a error:badarg if the parameters are in
1718 wrong format. It may also raise the exception error:notsup in
1719 case there is no engine support in the underlying OpenSSL imple‐
1720 mentation.
1721 engine_remove(Engine) -> Result
1723 Types:
1725 Engine = engine_ref()
1727 Result = ok | {error, Reason :: term()}
1728 Remove the engine from OpenSSL's internal list.
1730 The function raises a error:badarg if the parameters are in
1732 wrong format. It may also raise the exception error:notsup in
1733 case there is no engine support in the underlying OpenSSL imple‐
1734 mentation.
1735 engine_register(Engine, EngineMethods) -> Result
1737 Types:
1739 Engine = engine_ref()
1741 EngineMethods = [engine_method_type()]
1742 Result = ok | {error, Reason :: term()}
1743 Register engine to handle some type of methods, for example en‐
1745 gine_method_digests.
1746 The function raises a error:badarg if the parameters are in
1748 wrong format. It may also raise the exception error:notsup in
1749 case there is no engine support in the underlying OpenSSL imple‐
1750 mentation.
1751 engine_unregister(Engine, EngineMethods) -> Result
1753 Types:
1755 Engine = engine_ref()
1757 EngineMethods = [engine_method_type()]
1758 Result = ok | {error, Reason :: term()}
1759 Unregister engine so it don't handle some type of methods.
1761 The function raises a error:badarg if the parameters are in
1763 wrong format. It may also raise the exception error:notsup in
1764 case there is no engine support in the underlying OpenSSL imple‐
1765 mentation.
1766 engine_get_id(Engine) -> EngineId
1768 Types:
1770 Engine = engine_ref()
1772 EngineId = unicode:chardata()
1773 Return the ID for the engine, or an empty binary if there is no
1775 id set.
1776 The function raises a error:badarg if the parameters are in
1778 wrong format. It may also raise the exception error:notsup in
1779 case there is no engine support in the underlying OpenSSL imple‐
1780 mentation.
1781 engine_get_name(Engine) -> EngineName
1783 Types:
1785 Engine = engine_ref()
1787 EngineName = unicode:chardata()
1788 Return the name (eg a description) for the engine, or an empty
1790 binary if there is no name set.
1791 The function raises a error:badarg if the parameters are in
1793 wrong format. It may also raise the exception error:notsup in
1794 case there is no engine support in the underlying OpenSSL imple‐
1795 mentation.
1796 engine_list() -> Result
1798 Types:
1800 Result = [EngineId :: unicode:chardata()]
1802 List the id's of all engines in OpenSSL's internal list.
1804 It may also raise the exception error:notsup in case there is no
1806 engine support in the underlying OpenSSL implementation.
1807 See also the chapter Engine Load in the User's Guide.
1809 May raise exception error:notsup in case engine functionality is
1811 not supported by the underlying OpenSSL implementation.
1812 ensure_engine_loaded(EngineId, LibPath) -> Result
1814 Types:
1816 EngineId = LibPath = unicode:chardata()
1818 Result =
1819 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1820 Loads an engine given by EngineId and the path to the dynamic
1822 library implementing the engine. An error tuple is returned if
1823 the engine can't be loaded.
1824 This function differs from the normal engine_load in the sense
1826 that it also add the engine id to OpenSSL's internal engine
1827 list. The difference between the first call and the following is
1828 that the first loads the engine with the dynamical engine and
1829 the following calls fetch it from the OpenSSL's engine list. All
1830 references that is returned are equal.
1831 Use engine_unload/1 function to remove the references. But re‐
1833 member that engine_unload/1 just removes the references to the
1834 engine and not the tag in OpenSSL's engine list. That has to be
1835 done with the engine_remove/1 function when needed (just called
1836 once, from any of the references you got).
1837 The function raises a error:badarg if the parameters are in
1839 wrong format. It may also raise the exception error:notsup in
1840 case there is no engine support in the underlying OpenSSL imple‐
1841 mentation.
1842 See also the chapter Engine Load in the User's Guide.
1844 hash_equals(BinA, BinB) -> Result
1846 Types:
1848 BinA = BinB = binary()
1850 Result = boolean()
1851 Constant time memory comparison for fixed length binaries, such
1853 as results of HMAC computations.
1854 Returns true if the binaries are identical, false if they are of
1856 the same length but not identical. The function raises an er‐
1857 ror:badarg exception if the binaries are of different size.
1858 pbkdf2_hmac(Digest, Pass, Salt, Iter, KeyLen) -> Result
1860 Types:
1862 Digest = sha | sha224 | sha256 | sha384 | sha512
1864 Pass = Salt = binary()
1865 Iter = KeyLen = integer() >= 1
1866 Result = binary()
1867 Uses the 3-tuple style for error handling.
1869 PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in
1871 combination with HMAC.
1872Ericsson AB crypto 5.3 crypto(3)