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:
67 Galois/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 Asymetric 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, new API
101 cipher() = cipher_no_iv() | cipher_iv() | cipher_aead()
102 cipher_no_iv() =
104 aes_128_ecb | aes_192_ecb | aes_256_ecb | blowfish_ecb |
105 des_ecb | rc4
106 cipher_iv() =
108 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_128_cfb128 |
109 aes_192_cfb128 | aes_256_cfb128 | aes_128_cfb8 |
110 aes_192_cfb8 | aes_256_cfb8 | aes_128_ctr | aes_192_ctr |
111 aes_256_ctr | aes_ige256 | blowfish_cbc | blowfish_cfb64 |
112 blowfish_ofb64 | chacha20 | des_ede3_cbc | des_ede3_cfb |
113 des_cbc | des_cfb | rc2_cbc
114 cipher_aead() =
116 aes_128_ccm | aes_192_ccm | aes_256_ccm | aes_128_gcm |
117 aes_192_gcm | aes_256_gcm | chacha20_poly1305
118 Ciphers known by the CRYPTO application when using the new API.
120 Note that this list might be reduced if the underlying libcrypto
122 does not support all of them.
123 Ciphers, old API
125 block_cipher_with_iv() =
126 cbc_cipher() | cfb_cipher() | blowfish_ofb64 | aes_ige256
127 block_cipher_without_iv() = ecb_cipher()
129 stream_cipher() = ctr_cipher() | chacha20 | rc4
131 aead_cipher() = aes_gcm | aes_ccm | chacha20_poly1305
133 cbc_cipher() =
135 aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
136 des_cbc | des_ede3_cbc | rc2_cbc |
137 retired_cbc_cipher_aliases()
138 cfb_cipher() =
140 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
141 aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 | blowfish_cfb64 |
142 des_cfb | des_ede3_cfb |
143 retired_cfb_cipher_aliases()
144 ctr_cipher() =
146 aes_128_ctr | aes_192_ctr | aes_256_ctr |
147 retired_ctr_cipher_aliases()
148 ecb_cipher() =
150 aes_128_ecb | aes_192_ecb | aes_256_ecb | blowfish_ecb |
151 retired_ecb_cipher_aliases()
152 Ciphers known by the CRYPTO application when using the old API.
154 Note that this list might be reduced if the underlying libcrypto
156 does not support all of them.
157 retired_cbc_cipher_aliases() =
159 aes_cbc | aes_cbc128 | aes_cbc256 | des3_cbc | des_ede3
160 retired_cfb_cipher_aliases() =
162 aes_cfb8 | aes_cfb128 | des3_cbf | des3_cfb | des_ede3_cbf
163 retired_ctr_cipher_aliases() = aes_ctr
165 retired_ecb_cipher_aliases() = aes_ecb
167 Alternative, old names of ciphers known by the CRYPTO applica‐
169 tion when using the old API. See Retired cipher names for names
170 to use instead to be prepared for an easy convertion to the new
171 API.
172 Note that this list might be reduced if the underlying libcrypto
174 does not support all of them.
175 Digests and hash
177 hash_algorithm() =
178 sha1() |
179 sha2() |
180 sha3() |
181 blake2() |
182 ripemd160 |
183 compatibility_only_hash()
184 hmac_hash_algorithm() =
186 sha1() | sha2() | sha3() | compatibility_only_hash()
187 cmac_cipher_algorithm() =
189 aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
190 des_cbc | des_ede3_cbc | rc2_cbc | aes_128_cfb128 |
191 aes_192_cfb128 | aes_256_cfb128 | aes_128_cfb8 |
192 aes_192_cfb8 | aes_256_cfb8
193 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
195 dss_digest_type() = sha1() | sha2()
197 ecdsa_digest_type() = sha1() | sha2()
199 sha1() = sha
201 sha2() = sha224 | sha256 | sha384 | sha512
203 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
205 blake2() = blake2b | blake2s
207 compatibility_only_hash() = md5 | md4
209 The compatibility_only_hash() algorithms are recommended only
211 for compatibility with existing applications.
212 Elliptic Curves
214 ec_named_curve() =
215 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
216 brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
217 brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
218 brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
219 brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
220 c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
221 c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
222 c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
223 c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
224 prime192v2 | prime192v3 | prime239v1 | prime239v2 |
225 prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
226 secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
227 secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
228 secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
229 sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
230 sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
231 sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
232 wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
233 wtls6 | wtls7 | wtls8 | wtls9
234 edwards_curve_dh() = x25519 | x448
236 edwards_curve_ed() = ed25519 | ed448
238 Note that some curves are disabled if FIPS is enabled.
240 ec_explicit_curve() =
242 {Field :: ec_field(),
243 Curve :: ec_curve(),
244 BasePoint :: binary(),
245 Order :: binary(),
246 CoFactor :: none | binary()}
247 ec_field() = ec_prime_field() | ec_characteristic_two_field()
249 ec_curve() =
251 {A :: binary(), B :: binary(), Seed :: none | binary()}
252 Parametric curve definition.
254 ec_prime_field() = {prime_field, Prime :: integer()}
256 ec_characteristic_two_field() =
258 {characteristic_two_field,
259 M :: integer(),
260 Basis :: ec_basis()}
261 ec_basis() =
263 {tpbasis, K :: integer() >= 0} |
264 {ppbasis,
265 K1 :: integer() >= 0,
266 K2 :: integer() >= 0,
267 K3 :: integer() >= 0} |
268 onbasis
269 Curve definition details.
271 Keys
273 key() = iodata()
274 des3_key() = [key()]
276 For keylengths, iv-sizes and blocksizes see the User's Guide.
278 A key for des3 is a list of three iolists
280 key_integer() = integer() | binary()
282 Always binary() when used as return value
284 Public/Private Keys
286 rsa_public() = [key_integer()]
287 rsa_private() = [key_integer()]
289 rsa_params() =
291 {ModulusSizeInBits :: integer(),
292 PublicExponent :: key_integer()}
293 rsa_public() = [E, N]
295 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
297 Where E is the public exponent, N is public modulus and D is the
299 private exponent. The longer key format contains redundant
300 information that will make the calculation faster. P1,P2 are
301 first and second prime factors. E1,E2 are first and second expo‐
302 nents. C is the CRT coefficient. Terminology is taken from RFC
303 3447.
304 dss_public() = [key_integer()]
306 dss_private() = [key_integer()]
308 dss_public() = [P, Q, G, Y]
310 Where P, Q and G are the dss parameters and Y is the public key.
312 dss_private() = [P, Q, G, X]
314 Where P, Q and G are the dss parameters and X is the private
316 key.
317 ecdsa_public() = key_integer()
319 ecdsa_private() = key_integer()
321 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
323 eddsa_public() = key_integer()
325 eddsa_private() = key_integer()
327 eddsa_params() = edwards_curve_ed()
329 srp_public() = key_integer()
331 srp_private() = key_integer()
333 srp_public() = key_integer()
335 Where is A or B from SRP design
337 srp_private() = key_integer()
339 Where is a or b from SRP design
341 srp_gen_params() =
343 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
344 srp_comp_params() =
346 {user, srp_user_comp_params()} |
347 {host, srp_host_comp_params()}
348 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
350 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
352 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
354 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
356 Where Verifier is v, Generator is g and Prime is N, DerivedKey
358 is X, and Scrambler is u (optional will be generated if not pro‐
359 vided) from SRP design Version = '3' | '6' | '6a'
360 Public Key Ciphers
362 pk_encrypt_decrypt_algs() = rsa
363 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
365 ported.
366 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
368 rsa_opt() =
370 {rsa_padding, rsa_padding()} |
371 {signature_md, atom()} |
372 {rsa_mgf1_md, sha} |
373 {rsa_oaep_label, binary()} |
374 {rsa_oaep_md, sha}
375 rsa_padding() =
377 rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
378 rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
379 Options for public key encrypt/decrypt. Only RSA is supported.
381 Warning:
383 The RSA options are experimental.
385 The exact set of options and there syntax may be changed without
387 prior notice.
388 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
391 Those option forms are kept only for compatibility and should
393 not be used in new code.
394 Public Key Sign and Verify
396 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
397 Algorithms for sign and verify.
399 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
401 rsa_sign_verify_opt() =
403 {rsa_padding, rsa_sign_verify_padding()} |
404 {rsa_pss_saltlen, integer()} |
405 {rsa_mgf1_md, sha2()}
406 rsa_sign_verify_padding() =
408 rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
409 rsa_no_padding
410 Options for sign and verify.
412 Warning:
414 The RSA options are experimental.
416 The exact set of options and there syntax may be changed without
418 prior notice.
419 Diffie-Hellman Keys and parameters
422 dh_public() = key_integer()
423 dh_private() = key_integer()
425 dh_params() = [key_integer()]
427 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
429 ecdh_public() = key_integer()
431 ecdh_private() = key_integer()
433 ecdh_params() =
435 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
436 Types for Engines
438 engine_key_ref() =
439 #{engine := engine_ref(),
440 key_id := key_id(),
441 password => password(),
442 term() => term()}
443 engine_ref() = term()
445 The result of a call to engine_load/3.
447 key_id() = string() | binary()
449 Identifies the key to be used. The format depends on the loaded
451 engine. It is passed to the ENGINE_load_(private|public)_key
452 functions in libcrypto.
453 password() = string() | binary()
455 The password of the key stored in an engine.
457 engine_method_type() =
459 engine_method_rsa | engine_method_dsa | engine_method_dh |
460 engine_method_rand | engine_method_ecdh |
461 engine_method_ecdsa | engine_method_ciphers |
462 engine_method_digests | engine_method_store |
463 engine_method_pkey_meths | engine_method_pkey_asn1_meths |
464 engine_method_ec
465 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
467 Pre and Post commands for engine_load/3 and /4.
469 Internal data types
471 crypto_state()
472 hash_state()
474 hmac_state()
476 mac_state()
478 stream_state()
480 Contexts with an internal state that should not be manipulated
482 but passed between function calls.
483 Error types
485 run_time_error() = no_return()
486 The exception error:badarg signifies that one or more arguments
488 are of wrong data type, or are otherwise badly formed.
489 The exception error:notsup signifies that the algorithm is known
491 but is not supported by current underlying libcrypto or explic‐
492 itly disabled when building that.
493 For a list of supported algorithms, see supports/0.
495 descriptive_error() = no_return()
497 This is a more developed variant of the older run_time_error().
499 The exception is:
501 {Tag, {C_FileName,LineNumber}, Description}
503 Tag = badarg | notsup | error
505 C_FileName = string()
506 LineNumber = integer()
507 Description = string()
508 It is like the older type an exception of the error class. In
511 addition they contain a descriptive text in English. That text
512 is targeted to a developer. Examples are "Bad key size" or
513 "Cipher id is not an atom".
514 The exception tags are:
516 badarg:
518 Signifies that one or more arguments are of wrong data type
519 or are otherwise badly formed.
520 notsup:
522 Signifies that the algorithm is known but is not supported
523 by current underlying libcrypto or explicitly disabled when
524 building that one.
525 error:
527 An error condition that should not occur, for example a mem‐
528 ory allocation failed or the underlying cryptolib returned
529 an error code, for example "Can't initialize context, step
530 1". Thoose text usually needs searching the C-code to be
531 understood.
532 To catch the exception, use for example:
534 try crypto:crypto_init(Ciph, Key, IV, true)
536 catch
537 error:{Tag, {C_FileName,LineNumber}, Description} ->
538 do_something(......)
539 .....
540 end
541
545 crypto_init(Cipher, Key, EncryptFlag) ->
546 State | descriptive_error()
547 Types:
549 Cipher = cipher_no_iv()
551 Key = iodata()
552 EncryptFlag = boolean()
553 State = crypto_state()
554 As crypto_init/4 but for ciphers without IVs.
556 crypto_init(Cipher, Key, IV, EncryptFlag) ->
558 State | descriptive_error()
559 Types:
561 Cipher = cipher_iv()
563 Key = IV = iodata()
564 EncryptFlag = boolean()
565 State = crypto_state()
566 Part of the new API. Initializes a series of encryptions or
568 decryptions and creates an internal state with a reference that
569 is returned. The actual encryption or decryption is done by
570 crypto_update/2.
571 For encryption, set the EncryptFlag to true. For decryption, set
573 it to false.
574 See examples in the User's Guide.
576 crypto_update(State, Data) -> Result | descriptive_error()
578 Types:
580 State = crypto_state()
582 Data = iodata()
583 Result = binary()
584 Part of the new API. It does an actual crypto operation on a
586 part of the full text. If the part is less than a number of full
587 blocks, only the full blocks (possibly none) are encrypted or
588 decrypted and the remaining bytes are saved to the next
589 crypto_update operation. The State should be created with
590 crypto_init/3 or crypto_init/4.
591 See examples in the User's Guide.
593 crypto_dyn_iv_init(Cipher, Key, EncryptFlag) ->
595 State | descriptive_error()
596 Types:
598 Cipher = cipher_iv()
600 Key = iodata()
601 EncryptFlag = boolean()
602 State = crypto_state()
603 Part of the new API. Initializes a series of encryptions or
605 decryptions where the IV is provided later. The actual encryp‐
606 tion or decryption is done by crypto_dyn_iv_update/3.
607 For encryption, set the EncryptFlag to true. For decryption, set
609 it to false.
610 crypto_dyn_iv_update(State, Data, IV) ->
612 Result | descriptive_error()
613 Types:
615 State = crypto_state()
617 Data = IV = iodata()
618 Result = binary()
619 Part of the new API. Do an actual crypto operation on a part of
621 the full text and the IV is supplied for each part. The State
622 should be created with crypto_dyn_iv_init/3.
623 crypto_one_time(Cipher, Key, Data, EncryptFlag) ->
625 Result | descriptive_error()
626 Types:
628 Cipher = cipher_no_iv()
630 Key = Data = iodata()
631 EncryptFlag = boolean()
632 Result = binary()
633 As crypto_one_time/5 but for ciphers without IVs.
635 crypto_one_time(Cipher, Key, IV, Data, EncryptFlag) ->
637 Result | descriptive_error()
638 Types:
640 Cipher = cipher_iv()
642 Key = IV = Data = iodata()
643 EncryptFlag = boolean()
644 Result = binary()
645 Part of the new API. Do a complete encrypt or decrypt of the
647 full text in the argument Data.
648 For encryption, set the EncryptFlag to true. For decryption, set
650 it to false.
651 See examples in the User's Guide.
653 crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
655 EncFlag :: true) ->
656 Result | descriptive_error()
657 crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
659 EncFlag) ->
660 Result | descriptive_error()
661 Types:
663 Cipher = cipher_aead()
665 Key = IV = InText = AAD = iodata()
666 TagOrTagLength = EncryptTagLength | DecryptTag
667 EncryptTagLength = integer() >= 0
668 DecryptTag = iodata()
669 EncFlag = boolean()
670 Result = EncryptResult | DecryptResult
671 EncryptResult = {OutCryptoText, OutTag}
672 DecryptResult = OutPlainText | error
673 OutCryptoText = OutTag = OutPlainText = binary()
674 Part of the new API. Do a complete encrypt or decrypt with an
676 AEAD cipher of the full text.
677 For encryption, set the EncryptFlag to true and set the TagOrTa‐
679 gLength to the wanted size of the tag, that is, the tag length.
680 If the default length is wanted, the crypto_aead/6 form may be
681 used.
682 For decryption, set the EncryptFlag to false and put the tag to
684 be checked in the argument TagOrTagLength.
685 See examples in the User's Guide.
687 supports(Type) -> Support
689 Types:
691 Type = hashs | ciphers | public_keys | macs | curves |
693 rsa_opts
694 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
695 Hashs =
696 [sha1() |
697 sha2() |
698 sha3() |
699 blake2() |
700 ripemd160 |
701 compatibility_only_hash()]
702 Ciphers = [cipher()]
703 PKs = [rsa | dss | ecdsa | dh | ecdh | ec_gf2m]
704 Macs = [hmac | cmac | poly1305]
705 Curves =
706 [ec_named_curve() | edwards_curve_dh() |
707 edwards_curve_ed()]
708 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
709 Can be used to determine which crypto algorithms that are sup‐
711 ported by the underlying libcrypto library
712 See hash_info/1 and cipher_info/1 for information about the hash
714 and cipher algorithms.
715 mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()
717 Types:
719 Key = Data = iodata()
721 Mac = binary()
722 Short for mac(Type, undefined, Key, Data).
724 mac(Type, SubType, Key, Data) -> Mac | descriptive_error()
726 Types:
728 Type = hmac | cmac | poly1305
730 SubType =
731 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
732 fined
733 Key = Data = iodata()
734 Mac = binary()
735 Computes a MAC (Message Authentication Code) of type Type from
737 Data.
738 SubType depends on the MAC Type:
740 * For hmac it is a hash algorithm, see Algorithm Details in
742 the User's Guide.
743 * For cmac it is a cipher suitable for cmac, see Algorithm
745 Details in the User's Guide.
746 * For poly1305 it should be set to undefined or the mac/2
748 function could be used instead, see Algorithm Details in the
749 User's Guide.
750 Key is the authentication key with a length according to the
752 Type and SubType. The key length could be found with the
753 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
754 poly1305 the key length is 32 bytes. Note that the cryptographic
755 quality of the key is not checked.
756 The Mac result will have a default length depending on the Type
758 and SubType. To set a shorter length, use macN/4 or macN/5
759 instead. The default length is documented in Algorithm Details
760 in the User's Guide.
761 macN(Type :: poly1305, Key, Data, MacLength) ->
763 Mac | descriptive_error()
764 Types:
766 Key = Data = iodata()
768 Mac = binary()
769 MacLength = integer() >= 1
770 Short for macN(Type, undefined, Key, Data, MacLength).
772 macN(Type, SubType, Key, Data, MacLength) ->
774 Mac | descriptive_error()
775 Types:
777 Type = hmac | cmac | poly1305
779 SubType =
780 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
781 fined
782 Key = Data = iodata()
783 Mac = binary()
784 MacLength = integer() >= 1
785 Computes a MAC (Message Authentication Code) as mac/3 and mac/4
787 but MacLength will limit the size of the resultant Mac to at
788 most MacLength bytes. Note that if MacLength is greater than the
789 actual number of bytes returned from the underlying hash, the
790 returned hash will have that shorter length instead.
791 The max MacLength is documented in Algorithm Details in the
793 User's Guide.
794 mac_init(Type :: poly1305, Key) -> State | descriptive_error()
796 Types:
798 Key = iodata()
800 State = mac_state()
801 Short for mac_init(Type, undefined, Key).
803 mac_init(Type, SubType, Key) -> State | descriptive_error()
805 Types:
807 Type = hmac | cmac | poly1305
809 SubType =
810 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
811 fined
812 Key = iodata()
813 State = mac_state()
814 Initializes the context for streaming MAC operations.
816 Type determines which mac algorithm to use in the MAC operation.
818 SubType depends on the MAC Type:
820 * For hmac it is a hash algorithm, see Algorithm Details in
822 the User's Guide.
823 * For cmac it is a cipher suitable for cmac, see Algorithm
825 Details in the User's Guide.
826 * For poly1305 it should be set to undefined or the mac/2
828 function could be used instead, see Algorithm Details in the
829 User's Guide.
830 Key is the authentication key with a length according to the
832 Type and SubType. The key length could be found with the
833 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
834 poly1305 the key length is 32 bytes. Note that the cryptographic
835 quality of the key is not checked.
836 The returned State should be used in one or more subsequent
838 calls to mac_update/2. The MAC value is finally returned by
839 calling mac_final/1 or mac_finalN/2.
840 See examples in the User's Guide.
842 mac_update(State0, Data) -> State | descriptive_error()
844 Types:
846 Data = iodata()
848 State0 = State = mac_state()
849 Updates the MAC represented by State0 using the given Data which
851 could be of any length.
852 The State0 is the State value originally from a MAC init func‐
854 tion, that is mac_init/2, mac_init/3 or a previous call of
855 mac_update/2. The value State0 is returned unchanged by the
856 function as State.
857 mac_final(State) -> Mac | descriptive_error()
859 Types:
861 State = mac_state()
863 Mac = binary()
864 Finalizes the MAC operation referenced by State. The Mac result
866 will have a default length depending on the Type and SubType in
867 the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
868 instead. The default length is documented in Algorithm Details
869 in the User's Guide.
870 mac_finalN(State, MacLength) -> Mac | descriptive_error()
872 Types:
874 State = mac_state()
876 MacLength = integer() >= 1
877 Mac = binary()
878 Finalizes the MAC operation referenced by State.
880 Mac will be a binary with at most MacLength bytes. Note that if
882 MacLength is greater than the actual number of bytes returned
883 from the underlying hash, the returned hash will have that
884 shorter length instead.
885 The max MacLength is documented in Algorithm Details in the
887 User's Guide.
888
891 bytes_to_integer(Bin :: binary()) -> integer()
892 Convert binary representation, of an integer, to an Erlang inte‐
894 ger.
895 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
897 SharedSecret
898 Types:
900 Type = dh | ecdh | srp
902 SharedSecret = binary()
903 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
904 MyPrivateKey =
905 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
906 vate()}
907 Params = dh_params() | ecdh_params() | srp_comp_params()
908 Computes the shared secret from the private key and the other
910 party's public key. See also public_key:compute_key/2
911 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
913 Performs bit-wise XOR (exclusive or) on the data supplied.
915 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
917 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
919 Types:
921 Type = dh | ecdh | rsa | srp
923 PublicKey =
924 dh_public() | ecdh_public() | rsa_public() | srp_public()
925 PrivKeyIn =
926 undefined |
927 dh_private() |
928 ecdh_private() |
929 rsa_private() |
930 {srp_public(), srp_private()}
931 PrivKeyOut =
932 dh_private() |
933 ecdh_private() |
934 rsa_private() |
935 {srp_public(), srp_private()}
936 Params =
937 dh_params() | ecdh_params() | rsa_params() |
938 srp_comp_params()
939 Generates a public key of type Type. See also public_key:gener‐
941 ate_key/1. May raise exception:
942 * error:badarg: an argument is of wrong type or has an illegal
944 value,
945 * error:low_entropy: the random generator failed due to lack
947 of secure "randomness",
948 * error:computation_failed: the computation fails of another
950 reason than low_entropy.
951 Note:
953 RSA key generation is only available if the runtime was built
954 with dirty scheduler support. Otherwise, attempting to generate
955 an RSA key will raise exception error:notsup.
956 hash(Type, Data) -> Digest
959 Types:
961 Type = hash_algorithm()
963 Data = iodata()
964 Digest = binary()
965 Computes a message digest of type Type from Data.
967 May raise exception error:notsup in case the chosen Type is not
969 supported by the underlying libcrypto implementation.
970 hash_init(Type) -> State
972 Types:
974 Type = hash_algorithm()
976 State = hash_state()
977 Initializes the context for streaming hash operations. Type
979 determines which digest to use. The returned context should be
980 used as argument to hash_update.
981 May raise exception error:notsup in case the chosen Type is not
983 supported by the underlying libcrypto implementation.
984 hash_update(State, Data) -> NewState
986 Types:
988 State = NewState = hash_state()
990 Data = iodata()
991 Updates the digest represented by Context using the given Data.
993 Context must have been generated using hash_init or a previous
994 call to this function. Data can be any length. NewContext must
995 be passed into the next call to hash_update or hash_final.
996 hash_final(State) -> Digest
998 Types:
1000 State = hash_state()
1002 Digest = binary()
1003 Finalizes the hash operation referenced by Context returned from
1005 a previous call to hash_update. The size of Digest is determined
1006 by the type of hash function used to generate it.
1007 info_fips() -> not_supported | not_enabled | enabled
1009 Provides information about the FIPS operating status of crypto
1011 and the underlying libcrypto library. If crypto was built with
1012 FIPS support this can be either enabled (when running in FIPS
1013 mode) or not_enabled. For other builds this value is always
1014 not_supported.
1015 See enable_fips_mode/1 about how to enable FIPS mode.
1017 Warning:
1019 In FIPS mode all non-FIPS compliant algorithms are disabled and
1020 raise exception error:notsup. Check supports that in FIPS mode
1021 returns the restricted list of available algorithms.
1022 enable_fips_mode(Enable) -> Result
1025 Types:
1027 Enable = Result = boolean()
1029 Enables (Enable = true) or disables (Enable = false) FIPS mode.
1031 Returns true if the operation was successful or false otherwise.
1032 Note that to enable FIPS mode succesfully, OTP must be built
1034 with the configure option --enable-fips, and the underlying
1035 libcrypto must also support FIPS.
1036 See also info_fips/0.
1038 info_lib() -> [{Name, VerNum, VerStr}]
1040 Types:
1042 Name = binary()
1044 VerNum = integer()
1045 VerStr = binary()
1046 Provides the name and version of the libraries used by crypto.
1048 Name is the name of the library. VerNum is the numeric version
1050 according to the library's own versioning scheme. VerStr con‐
1051 tains a text variant of the version.
1052 > info_lib().
1054 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
1055 Note:
1058 From OTP R16 the numeric version represents the version of the
1059 OpenSSL header files (openssl/opensslv.h) used when crypto was
1060 compiled. The text variant represents the libcrypto library used
1061 at runtime. In earlier OTP versions both numeric and text was
1062 taken from the library.
1063 hash_info(Type) -> Result | run_time_error()
1066 Types:
1068 Type = hash_algorithm()
1070 Result =
1071 #{size := integer(),
1072 block_size := integer(),
1073 type := integer()}
1074 Provides a map with information about block_size, size and pos‐
1076 sibly other properties of the hash algorithm in question.
1077 For a list of supported hash algorithms, see supports/0.
1079 cipher_info(Type) -> Result | run_time_error()
1081 Types:
1083 Type = cipher()
1085 Result =
1086 #{key_length := integer(),
1087 iv_length := integer(),
1088 block_size := integer(),
1089 mode := CipherModes,
1090 type := undefined | integer()}
1091 CipherModes =
1092 undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1093 ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1094 wrap_mode | xts_mode
1095 Provides a map with information about block_size, key_length,
1097 iv_length and possibly other properties of the cipher algorithm
1098 in question.
1099 Note:
1101 The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb,
1102 aes_gcm and aes_ccm has no keylength in the Type as opposed to
1103 for example aes_128_ctr. They adapt to the length of the key
1104 provided in the encrypt and decrypt function. Therefor it is
1105 impossible to return a valid keylength in the map.
1106 Always use a Type with an explicit key length,
1108 For a list of supported cipher algorithms, see supports/0.
1111 mod_pow(N, P, M) -> Result
1113 Types:
1115 N = P = M = binary() | integer()
1117 Result = binary() | error
1118 Computes the function N^P mod M.
1120 next_iv(Type :: cbc_cipher(), Data) -> NextIVec
1122 next_iv(Type :: des_cfb, Data, IVec) -> NextIVec
1124 Types:
1126 Data = iodata()
1128 IVec = NextIVec = binary()
1129 Returns the initialization vector to be used in the next itera‐
1131 tion of encrypt/decrypt of type Type. Data is the encrypted data
1132 from the previous iteration step. The IVec argument is only
1133 needed for des_cfb as the vector used in the previous iteration
1134 step.
1135 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1137 PlainText
1138 Types:
1140 Algorithm = pk_encrypt_decrypt_algs()
1142 CipherText = binary()
1143 PrivateKey = rsa_private() | engine_key_ref()
1144 Options = pk_encrypt_decrypt_opts()
1145 PlainText = binary()
1146 Decrypts the CipherText, encrypted with public_encrypt/4 (or
1148 equivalent function) using the PrivateKey, and returns the
1149 plaintext (message digest). This is a low level signature veri‐
1150 fication operation used for instance by older versions of the
1151 SSL protocol. See also public_key:decrypt_private/[2,3]
1152 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1154 CipherText
1155 Types:
1157 Algorithm = pk_encrypt_decrypt_algs()
1159 PlainText = binary()
1160 PrivateKey = rsa_private() | engine_key_ref()
1161 Options = pk_encrypt_decrypt_opts()
1162 CipherText = binary()
1163 Encrypts the PlainText using the PrivateKey and returns the
1165 ciphertext. This is a low level signature operation used for
1166 instance by older versions of the SSL protocol. See also pub‐
1167 lic_key:encrypt_private/[2,3]
1168 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1170 PlainText
1171 Types:
1173 Algorithm = pk_encrypt_decrypt_algs()
1175 CipherText = binary()
1176 PublicKey = rsa_public() | engine_key_ref()
1177 Options = pk_encrypt_decrypt_opts()
1178 PlainText = binary()
1179 Decrypts the CipherText, encrypted with private_encrypt/4(or
1181 equivalent function) using the PrivateKey, and returns the
1182 plaintext (message digest). This is a low level signature veri‐
1183 fication operation used for instance by older versions of the
1184 SSL protocol. See also public_key:decrypt_public/[2,3]
1185 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1187 CipherText
1188 Types:
1190 Algorithm = pk_encrypt_decrypt_algs()
1192 PlainText = binary()
1193 PublicKey = rsa_public() | engine_key_ref()
1194 Options = pk_encrypt_decrypt_opts()
1195 CipherText = binary()
1196 Encrypts the PlainText (message digest) using the PublicKey and
1198 returns the CipherText. This is a low level signature operation
1199 used for instance by older versions of the SSL protocol. See
1200 also public_key:encrypt_public/[2,3]
1201 rand_seed(Seed :: binary()) -> ok
1203 Set the seed for PRNG to the given binary. This calls the
1205 RAND_seed function from openssl. Only use this if the system you
1206 are running on does not have enough "randomness" built in. Nor‐
1207 mally this is when strong_rand_bytes/1 raises error:low_entropy
1208 rand_uniform(Lo, Hi) -> N
1210 Types:
1212 Lo, Hi, N = integer()
1214 Generate a random number N, Lo =< N < Hi. Uses the crypto
1216 library pseudo-random number generator. Hi must be larger than
1217 Lo.
1218 start() -> ok | {error, Reason :: term()}
1220 Equivalent to application:start(crypto).
1222 stop() -> ok | {error, Reason :: term()}
1224 Equivalent to application:stop(crypto).
1226 strong_rand_bytes(N :: integer() >= 0) -> binary()
1228 Generates N bytes randomly uniform 0..255, and returns the
1230 result in a binary. Uses a cryptographically secure prng seeded
1231 and periodically mixed with operating system provided entropy.
1232 By default this is the RAND_bytes method from OpenSSL.
1233 May raise exception error:low_entropy in case the random genera‐
1235 tor failed due to lack of secure "randomness".
1236 rand_seed() -> rand:state()
1238 Creates state object for random number generation, in order to
1240 generate cryptographically strong random numbers (based on
1241 OpenSSL's BN_rand_range), and saves it in the process dictionary
1242 before returning it as well. See also rand:seed/1 and
1243 rand_seed_s/0.
1244 When using the state object from this function the rand func‐
1246 tions using it may raise exception error:low_entropy in case the
1247 random generator failed due to lack of secure "randomness".
1248 Example
1250 _ = crypto:rand_seed(),
1252 _IntegerValue = rand:uniform(42), % [1; 42]
1253 _FloatValue = rand:uniform(). % [0.0; 1.0[
1254 rand_seed_s() -> rand:state()
1256 Creates state object for random number generation, in order to
1258 generate cryptographically strongly random numbers (based on
1259 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1260 When using the state object from this function the rand func‐
1262 tions using it may raise exception error:low_entropy in case the
1263 random generator failed due to lack of secure "randomness".
1264 Note:
1266 The state returned from this function cannot be used to get a
1267 reproducable random sequence as from the other rand functions,
1268 since reproducability does not match cryptographically safe.
1269 The only supported usage is to generate one distinct random
1271 sequence from this start state.
1272 rand_seed_alg(Alg) -> rand:state()
1275 Types:
1277 Alg = crypto | crypto_cache
1279 Creates state object for random number generation, in order to
1281 generate cryptographically strong random numbers, and saves it
1282 in the process dictionary before returning it as well. See also
1283 rand:seed/1 and rand_seed_alg_s/1.
1284 When using the state object from this function the rand func‐
1286 tions using it may raise exception error:low_entropy in case the
1287 random generator failed due to lack of secure "randomness".
1288 Example
1290 _ = crypto:rand_seed_alg(crypto_cache),
1292 _IntegerValue = rand:uniform(42), % [1; 42]
1293 _FloatValue = rand:uniform(). % [0.0; 1.0[
1294 rand_seed_alg(Alg, Seed) -> rand:state()
1296 Types:
1298 Alg = crypto_aes
1300 Creates a state object for random number generation, in order to
1302 generate cryptographically unpredictable random numbers, and
1303 saves it in the process dictionary before returning it as well.
1304 See also rand_seed_alg_s/2.
1305 Example
1307 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1309 IntegerValue = rand:uniform(42), % [1; 42]
1310 FloatValue = rand:uniform(), % [0.0; 1.0[
1311 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1312 IntegerValue = rand:uniform(42), % Same values
1313 FloatValue = rand:uniform(). % again
1314 rand_seed_alg_s(Alg) -> rand:state()
1317 Types:
1319 Alg = crypto | crypto_cache
1321 Creates state object for random number generation, in order to
1323 generate cryptographically strongly random numbers. See also
1324 rand:seed_s/1.
1325 If Alg is crypto this function behaves exactly like
1327 rand_seed_s/0.
1328 If Alg is crypto_cache this function fetches random data with
1330 OpenSSL's RAND_bytes and caches it for speed using an internal
1331 word size of 56 bits that makes calculations fast on 64 bit
1332 machines.
1333 When using the state object from this function the rand func‐
1335 tions using it may raise exception error:low_entropy in case the
1336 random generator failed due to lack of secure "randomness".
1337 The cache size can be changed from its default value using the
1339 crypto app's configuration parameter rand_cache_size.
1340 When using the state object from this function the rand func‐
1342 tions using it may throw exception low_entropy in case the ran‐
1343 dom generator failed due to lack of secure "randomness".
1344 Note:
1346 The state returned from this function cannot be used to get a
1347 reproducable random sequence as from the other rand functions,
1348 since reproducability does not match cryptographically safe.
1349 In fact since random data is cached some numbers may get repro‐
1351 duced if you try, but this is unpredictable.
1352 The only supported usage is to generate one distinct random
1354 sequence from this start state.
1355 rand_seed_alg_s(Alg, Seed) -> rand:state()
1358 Types:
1360 Alg = crypto_aes
1362 Creates a state object for random number generation, in order to
1364 generate cryptographically unpredictable random numbers. See
1365 also rand_seed_alg/1.
1366 To get a long period the Xoroshiro928 generator from the rand
1368 module is used as a counter (with period 2^928 - 1) and the gen‐
1369 erator states are scrambled through AES to create 58-bit pseudo
1370 random values.
1371 The result should be statistically completely unpredictable ran‐
1373 dom values, since the scrambling is cryptographically strong and
1374 the period is ridiculously long. But the generated numbers are
1375 not to be regarded as cryptographically strong since there is no
1376 re-keying schedule.
1377 * If you need cryptographically strong random numbers use
1379 rand_seed_alg_s/1 with Alg =:= crypto or Alg =:=
1380 crypto_cache.
1381 * If you need to be able to repeat the sequence use this func‐
1383 tion.
1384 * If you do not need the statistical quality of this function,
1386 there are faster algorithms in the rand module.
1387 Thanks to the used generator the state object supports the
1389 rand:jump/0,1 function with distance 2^512.
1390 Numbers are generated in batches and cached for speed reasons.
1392 The cache size can be changed from its default value using the
1393 crypto app's configuration parameter rand_cache_size.
1394 ec_curves() -> [EllipticCurve]
1396 Types:
1398 EllipticCurve =
1400 ec_named_curve() | edwards_curve_dh() |
1401 edwards_curve_ed()
1402 Can be used to determine which named elliptic curves are sup‐
1404 ported.
1405 ec_curve(CurveName) -> ExplicitCurve
1407 Types:
1409 CurveName = ec_named_curve()
1411 ExplicitCurve = ec_explicit_curve()
1412 Return the defining parameters of a elliptic curve.
1414 sign(Algorithm, DigestType, Msg, Key) -> Signature
1416 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1418 Types:
1420 Algorithm = pk_sign_verify_algs()
1422 DigestType =
1423 rsa_digest_type() |
1424 dss_digest_type() |
1425 ecdsa_digest_type() |
1426 none
1427 Msg = iodata() | {digest, iodata()}
1428 Key =
1429 rsa_private() |
1430 dss_private() |
1431 [ecdsa_private() | ecdsa_params()] |
1432 [eddsa_private() | eddsa_params()] |
1433 engine_key_ref()
1434 Options = pk_sign_verify_opts()
1435 Signature = binary()
1436 Creates a digital signature.
1438 The msg is either the binary "cleartext" data to be signed or it
1440 is the hashed value of "cleartext" i.e. the digest (plaintext).
1441 Algorithm dss can only be used together with digest type sha.
1443 See also public_key:sign/3.
1445 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1447 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1449 Result
1450 Types:
1452 Algorithm = pk_sign_verify_algs()
1454 DigestType =
1455 rsa_digest_type() | dss_digest_type() |
1456 ecdsa_digest_type()
1457 Msg = iodata() | {digest, iodata()}
1458 Signature = binary()
1459 Key =
1460 rsa_public() |
1461 dss_public() |
1462 [ecdsa_public() | ecdsa_params()] |
1463 [eddsa_public() | eddsa_params()] |
1464 engine_key_ref()
1465 Options = pk_sign_verify_opts()
1466 Result = boolean()
1467 Verifies a digital signature
1469 The msg is either the binary "cleartext" data to be signed or it
1471 is the hashed value of "cleartext" i.e. the digest (plaintext).
1472 Algorithm dss can only be used together with digest type sha.
1474 See also public_key:verify/4.
1476
1479 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1480 Types:
1482 Type = rsa | dss
1484 EnginePrivateKeyRef = engine_key_ref()
1485 PublicKey = rsa_public() | dss_public()
1486 Fetches the corresponding public key from a private key stored
1488 in an Engine. The key must be of the type indicated by the Type
1489 parameter.
1490 engine_get_all_methods() -> Result
1492 Types:
1494 Result = [engine_method_type()]
1496 Returns a list of all possible engine methods.
1498 May raise exception error:notsup in case there is no engine sup‐
1500 port in the underlying OpenSSL implementation.
1501 See also the chapter Engine Load in the User's Guide.
1503 engine_load(EngineId, PreCmds, PostCmds) -> Result
1505 Types:
1507 EngineId = unicode:chardata()
1509 PreCmds = PostCmds = [engine_cmnd()]
1510 Result =
1511 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1512 Loads the OpenSSL engine given by EngineId if it is available
1514 and then returns ok and an engine handle. This function is the
1515 same as calling engine_load/4 with EngineMethods set to a list
1516 of all the possible methods. An error tuple is returned if the
1517 engine can't be loaded.
1518 The function raises a error:badarg if the parameters are in
1520 wrong format. It may also raise the exception error:notsup in
1521 case there is no engine support in the underlying OpenSSL imple‐
1522 mentation.
1523 See also the chapter Engine Load in the User's Guide.
1525 engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
1527 Types:
1529 EngineId = unicode:chardata()
1531 PreCmds = PostCmds = [engine_cmnd()]
1532 EngineMethods = [engine_method_type()]
1533 Result =
1534 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1535 Loads the OpenSSL engine given by EngineId if it is available
1537 and then returns ok and an engine handle. An error tuple is
1538 returned if the engine can't be loaded.
1539 The function raises a error:badarg if the parameters are in
1541 wrong format. It may also raise the exception error:notsup in
1542 case there is no engine support in the underlying OpenSSL imple‐
1543 mentation.
1544 See also the chapter Engine Load in the User's Guide.
1546 engine_unload(Engine) -> Result
1548 Types:
1550 Engine = engine_ref()
1552 Result = ok | {error, Reason :: term()}
1553 Unloads the OpenSSL engine given by Engine. An error tuple is
1555 returned if the engine can't be unloaded.
1556 The function raises a error:badarg if the parameter is in wrong
1558 format. It may also raise the exception error:notsup in case
1559 there is no engine support in the underlying OpenSSL implementa‐
1560 tion.
1561 See also the chapter Engine Load in the User's Guide.
1563 engine_by_id(EngineId) -> Result
1565 Types:
1567 EngineId = unicode:chardata()
1569 Result =
1570 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1571 Get a reference to an already loaded engine with EngineId. An
1573 error tuple is returned if the engine can't be unloaded.
1574 The function raises a error:badarg if the parameter is in wrong
1576 format. It may also raise the exception error:notsup in case
1577 there is no engine support in the underlying OpenSSL implementa‐
1578 tion.
1579 See also the chapter Engine Load in the User's Guide.
1581 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1583 Types:
1585 Engine = term()
1587 CmdName = CmdArg = unicode:chardata()
1588 Result = ok | {error, Reason :: term()}
1589 Sends ctrl commands to the OpenSSL engine given by Engine. This
1591 function is the same as calling engine_ctrl_cmd_string/4 with
1592 Optional set to false.
1593 The function raises a error:badarg if the parameters are in
1595 wrong format. It may also raise the exception error:notsup in
1596 case there is no engine support in the underlying OpenSSL imple‐
1597 mentation.
1598 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1600 Result
1601 Types:
1603 Engine = term()
1605 CmdName = CmdArg = unicode:chardata()
1606 Optional = boolean()
1607 Result = ok | {error, Reason :: term()}
1608 Sends ctrl commands to the OpenSSL engine given by Engine.
1610 Optional is a boolean argument that can relax the semantics of
1611 the function. If set to true it will only return failure if the
1612 ENGINE supported the given command name but failed while execut‐
1613 ing it, if the ENGINE doesn't support the command name it will
1614 simply return success without doing anything. In this case we
1615 assume the user is only supplying commands specific to the given
1616 ENGINE so we set this to false.
1617 The function raises a error:badarg if the parameters are in
1619 wrong format. It may also raise the exception error:notsup in
1620 case there is no engine support in the underlying OpenSSL imple‐
1621 mentation.
1622 engine_add(Engine) -> Result
1624 Types:
1626 Engine = engine_ref()
1628 Result = ok | {error, Reason :: term()}
1629 Add the engine to OpenSSL's internal list.
1631 The function raises a error:badarg if the parameters are in
1633 wrong format. It may also raise the exception error:notsup in
1634 case there is no engine support in the underlying OpenSSL imple‐
1635 mentation.
1636 engine_remove(Engine) -> Result
1638 Types:
1640 Engine = engine_ref()
1642 Result = ok | {error, Reason :: term()}
1643 Remove the engine from OpenSSL's internal list.
1645 The function raises a error:badarg if the parameters are in
1647 wrong format. It may also raise the exception error:notsup in
1648 case there is no engine support in the underlying OpenSSL imple‐
1649 mentation.
1650 engine_get_id(Engine) -> EngineId
1652 Types:
1654 Engine = engine_ref()
1656 EngineId = unicode:chardata()
1657 Return the ID for the engine, or an empty binary if there is no
1659 id set.
1660 The function raises a error:badarg if the parameters are in
1662 wrong format. It may also raise the exception error:notsup in
1663 case there is no engine support in the underlying OpenSSL imple‐
1664 mentation.
1665 engine_get_name(Engine) -> EngineName
1667 Types:
1669 Engine = engine_ref()
1671 EngineName = unicode:chardata()
1672 Return the name (eg a description) for the engine, or an empty
1674 binary if there is no name set.
1675 The function raises a error:badarg if the parameters are in
1677 wrong format. It may also raise the exception error:notsup in
1678 case there is no engine support in the underlying OpenSSL imple‐
1679 mentation.
1680 engine_list() -> Result
1682 Types:
1684 Result = [EngineId :: unicode:chardata()]
1686 List the id's of all engines in OpenSSL's internal list.
1688 It may also raise the exception error:notsup in case there is no
1690 engine support in the underlying OpenSSL implementation.
1691 See also the chapter Engine Load in the User's Guide.
1693 May raise exception error:notsup in case engine functionality is
1695 not supported by the underlying OpenSSL implementation.
1696 ensure_engine_loaded(EngineId, LibPath) -> Result
1698 Types:
1700 EngineId = LibPath = unicode:chardata()
1702 Result =
1703 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1704 Loads the OpenSSL engine given by EngineId and the path to the
1706 dynamic library implementing the engine. This function is the
1707 same as calling ensure_engine_loaded/3 with EngineMethods set to
1708 a list of all the possible methods. An error tuple is returned
1709 if the engine can't be loaded.
1710 The function raises a error:badarg if the parameters are in
1712 wrong format. It may also raise the exception error:notsup in
1713 case there is no engine support in the underlying OpenSSL imple‐
1714 mentation.
1715 See also the chapter Engine Load in the User's Guide.
1717 ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
1719 Types:
1721 EngineId = LibPath = unicode:chardata()
1723 EngineMethods = [engine_method_type()]
1724 Result =
1725 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1726 Loads the OpenSSL engine given by EngineId and the path to the
1728 dynamic library implementing the engine. This function differs
1729 from the normal engine_load in that sense it also add the engine
1730 id to the internal list in OpenSSL. Then in the following calls
1731 to the function it just fetch the reference to the engine
1732 instead of loading it again. An error tuple is returned if the
1733 engine can't be loaded.
1734 The function raises a error:badarg if the parameters are in
1736 wrong format. It may also raise the exception error:notsup in
1737 case there is no engine support in the underlying OpenSSL imple‐
1738 mentation.
1739 See also the chapter Engine Load in the User's Guide.
1741 ensure_engine_unloaded(Engine) -> Result
1743 Types:
1745 Engine = engine_ref()
1747 Result = ok | {error, Reason :: term()}
1748 Unloads an engine loaded with the ensure_engine_loaded function.
1750 It both removes the label from the OpenSSL internal engine list
1751 and unloads the engine. This function is the same as calling
1752 ensure_engine_unloaded/2 with EngineMethods set to a list of all
1753 the possible methods. An error tuple is returned if the engine
1754 can't be unloaded.
1755 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 See also the chapter Engine Load in the User's Guide.
1762 ensure_engine_unloaded(Engine, EngineMethods) -> Result
1764 Types:
1766 Engine = engine_ref()
1768 EngineMethods = [engine_method_type()]
1769 Result = ok | {error, Reason :: term()}
1770 Unloads an engine loaded with the ensure_engine_loaded function.
1772 It both removes the label from the OpenSSL internal engine list
1773 and unloads the engine. An error tuple is returned if the engine
1774 can't be unloaded.
1775 The function raises a error:badarg if the parameters are in
1777 wrong format. It may also raise the exception error:notsup in
1778 case there is no engine support in the underlying OpenSSL imple‐
1779 mentation.
1780 See also the chapter Engine Load in the User's Guide.
1782
1785 block_encrypt(Type :: block_cipher_without_iv(),
1786 Key :: key(),
1787 PlainText :: iodata()) ->
1788 binary() | run_time_error()
1789 Dont:
1791 Don't use this function for new programs! Use the-new-api.
1792 Encrypt PlainText according to Type block cipher.
1795 May raise exception error:notsup in case the chosen Type is not
1797 supported by the underlying libcrypto implementation.
1798 For keylengths and blocksizes see the User's Guide.
1800 block_decrypt(Type :: block_cipher_without_iv(),
1802 Key :: key(),
1803 Data :: iodata()) ->
1804 binary() | run_time_error()
1805 Dont:
1807 Don't use this function for new programs! Use the new api.
1808 Decrypt CipherText according to Type block cipher.
1811 May raise exception error:notsup in case the chosen Type is not
1813 supported by the underlying libcrypto implementation.
1814 For keylengths and blocksizes see the User's Guide.
1816 block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error
1818 block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText,
1819 CipherTag} | Error
1820 block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText,
1821 TagLength}) -> {CipherText, CipherTag} | Error
1822 Types:
1824 Type = block_cipher_with_iv()
1826 AeadType = aead_cipher()
1827 Key = key() | des3_key()
1828 PlainText = iodata()
1829 AAD = IVec = CipherText = CipherTag = binary()
1830 TagLength = 1..16
1831 Error = run_time_error()
1832 Dont:
1834 Don't use this function for new programs! Use the new api.
1835 Encrypt PlainText according to Type block cipher. IVec is an
1838 arbitrary initializing vector.
1839 In AEAD (Authenticated Encryption with Associated Data) mode,
1841 encrypt PlainTextaccording to Type block cipher and calculate
1842 CipherTag that also authenticates the AAD (Associated Authenti‐
1843 cated Data).
1844 May raise exception error:notsup in case the chosen Type is not
1846 supported by the underlying libcrypto implementation.
1847 For keylengths, iv-sizes and blocksizes see the User's Guide.
1849 block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error
1851 block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) ->
1852 PlainText | Error
1853 Types:
1855 Type = block_cipher_with_iv()
1857 AeadType = aead_cipher()
1858 Key = key() | des3_key()
1859 PlainText = iodata()
1860 AAD = IVec = CipherText = CipherTag = binary()
1861 Error = BadTag | run_time_error()
1862 BadTag = error
1863 Dont:
1865 Don't use this function for new programs! Use the new api.
1866 Decrypt CipherText according to Type block cipher. IVec is an
1869 arbitrary initializing vector.
1870 In AEAD (Authenticated Encryption with Associated Data) mode,
1872 decrypt CipherTextaccording to Type block cipher and check the
1873 authenticity the PlainText and AAD (Associated Authenticated
1874 Data) using the CipherTag. May return error if the decryption or
1875 validation fail's
1876 May raise exception error:notsup in case the chosen Type is not
1878 supported by the underlying libcrypto implementation.
1879 For keylengths, iv-sizes and blocksizes see the User's Guide.
1881 stream_init(Type, Key) -> State | run_time_error()
1883 Types:
1885 Type = rc4
1887 Key = iodata()
1888 State = stream_state()
1889 Dont:
1891 Don't use this function for new programs! Use the new api.
1892 Initializes the state for use in RC4 stream encryption
1895 stream_encrypt and stream_decrypt
1896 For keylengths see the User's Guide.
1898 stream_init(Type, Key, IVec) -> State | run_time_error()
1900 Types:
1902 Type = stream_cipher()
1904 Key = iodata()
1905 IVec = binary()
1906 State = stream_state()
1907 Dont:
1909 Don't use this function for new programs! Use the new api.
1910 Initializes the state for use in streaming AES encryption using
1913 Counter mode (CTR). Key is the AES key and must be either 128,
1914 192, or 256 bits long. IVec is an arbitrary initializing vector
1915 of 128 bits (16 bytes). This state is for use with
1916 stream_encrypt and stream_decrypt.
1917 For keylengths and iv-sizes see the User's Guide.
1919 stream_encrypt(State, PlainText) ->
1921 {NewState, CipherText} | run_time_error()
1922 Types:
1924 State = stream_state()
1926 PlainText = iodata()
1927 NewState = stream_state()
1928 CipherText = iodata()
1929 Dont:
1931 Don't use this function for new programs! Use the new api.
1932 Encrypts PlainText according to the stream cipher Type specified
1935 in stream_init/3. Text can be any number of bytes. The initial
1936 State is created using stream_init. NewState must be passed into
1937 the next call to stream_encrypt.
1938 stream_decrypt(State, CipherText) ->
1940 {NewState, PlainText} | run_time_error()
1941 Types:
1943 State = stream_state()
1945 CipherText = iodata()
1946 NewState = stream_state()
1947 PlainText = iodata()
1948 Dont:
1950 Don't use this function for new programs! Use the new api.
1951 Decrypts CipherText according to the stream cipher Type speci‐
1954 fied in stream_init/3. PlainText can be any number of bytes. The
1955 initial State is created using stream_init. NewState must be
1956 passed into the next call to stream_decrypt.
1957 supports() -> [Support]
1959 Types:
1961 Support =
1963 {hashs, Hashs} |
1964 {ciphers, Ciphers} |
1965 {public_keys, PKs} |
1966 {macs, Macs} |
1967 {curves, Curves} |
1968 {rsa_opts, RSAopts}
1969 Hashs =
1970 [sha1() |
1971 sha2() |
1972 sha3() |
1973 blake2() |
1974 ripemd160 |
1975 compatibility_only_hash()]
1976 Ciphers = [cipher()]
1977 PKs = [rsa | dss | ecdsa | dh | ecdh | ec_gf2m]
1978 Macs = [hmac | cmac | poly1305]
1979 Curves =
1980 [ec_named_curve() | edwards_curve_dh() |
1981 edwards_curve_ed()]
1982 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
1983 Dont:
1985 Don't use this function for new programs! Use supports/1 in the
1986 new api.
1987 Can be used to determine which crypto algorithms that are sup‐
1990 ported by the underlying libcrypto library
1991 See hash_info/1 and cipher_info/1 for information about the hash
1993 and cipher algorithms.
1994 hmac(Type, Key, Data) -> Mac
1996 hmac(Type, Key, Data, MacLength) -> Mac
1998 Types:
2000 Type = hmac_hash_algorithm()
2002 Key = Data = iodata()
2003 MacLength = integer()
2004 Mac = binary()
2005 Dont:
2007 Don't use this function for new programs! Use mac/4 or macN/5 in
2008 the new api.
2009 Computes a HMAC of type Type from Data using Key as the authen‐
2012 tication key.
2013 MacLength will limit the size of the resultant Mac.
2015 hmac_init(Type, Key) -> State
2017 Types:
2019 Type = hmac_hash_algorithm()
2021 Key = iodata()
2022 State = hmac_state()
2023 Dont:
2025 Don't use this function for new programs! Use mac_init/3 in the
2026 new api.
2027 Initializes the context for streaming HMAC operations. Type
2030 determines which hash function to use in the HMAC operation. Key
2031 is the authentication key. The key can be any length.
2032 hmac_update(State, Data) -> NewState
2034 Types:
2036 Data = iodata()
2038 State = NewState = hmac_state()
2039 Dont:
2041 Don't use this function for new programs! Use mac_update/2 in
2042 the new api.
2043 Updates the HMAC represented by Context using the given Data.
2046 Context must have been generated using an HMAC init function
2047 (such as hmac_init). Data can be any length. NewContext must be
2048 passed into the next call to hmac_update or to one of the func‐
2049 tions hmac_final and hmac_final_n
2050 Warning:
2052 Do not use a Context as argument in more than one call to
2053 hmac_update or hmac_final. The semantics of reusing old contexts
2054 in any way is undefined and could even crash the VM in earlier
2055 releases. The reason for this limitation is a lack of support in
2056 the underlying libcrypto API.
2057 hmac_final(State) -> Mac
2060 Types:
2062 State = hmac_state()
2064 Mac = binary()
2065 Dont:
2067 Don't use this function for new programs! Use mac_final/1 in the
2068 new api.
2069 Finalizes the HMAC operation referenced by Context. The size of
2072 the resultant MAC is determined by the type of hash function
2073 used to generate it.
2074 hmac_final_n(State, HashLen) -> Mac
2076 Types:
2078 State = hmac_state()
2080 HashLen = integer()
2081 Mac = binary()
2082 Dont:
2084 Don't use this function for new programs! Use mac_finalN/2 in
2085 the new api.
2086 Finalizes the HMAC operation referenced by Context. HashLen must
2089 be greater than zero. Mac will be a binary with at most HashLen
2090 bytes. Note that if HashLen is greater than the actual number of
2091 bytes returned from the underlying hash, the returned hash will
2092 have fewer than HashLen bytes.
2093 cmac(Type, Key, Data) -> Mac
2095 cmac(Type, Key, Data, MacLength) -> Mac
2097 Types:
2099 Type =
2101 cbc_cipher() |
2102 cfb_cipher() |
2103 blowfish_cbc | des_ede3 | rc2_cbc
2104 Key = Data = iodata()
2105 MacLength = integer()
2106 Mac = binary()
2107 Dont:
2109 Don't use this function for new programs! Use mac/4 or macN/5 in
2110 the new api.
2111 Computes a CMAC of type Type from Data using Key as the authen‐
2114 tication key.
2115 MacLength will limit the size of the resultant Mac.
2117 poly1305(Key :: iodata(), Data :: iodata()) -> Mac
2119 Types:
2121 Mac = binary()
2123 Dont:
2125 Don't use this function for new programs! Use mac/3 or macN/4 in
2126 the new api.
2127 Computes a POLY1305 message authentication code (Mac) from Data
2130 using Key as the authentication key.
2131Ericsson AB crypto 4.6.2 crypto(3)