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 crypto_opts() = boolean() | [crypto_opt()]
125 crypto_opt() = {encrypt, boolean()} | {padding, padding()}
127 Selects encryption ({encrypt,true}) or decryption
129 ({encrypt,false}) in the New API .
130 padding() = cryptolib_padding() | otp_padding()
132 This option handles padding in the last block. If not set, no
134 padding is done and any bytes in the last unfilled block is
135 silently discarded.
136 cryptolib_padding() = none | pkcs_padding
138 The cryptolib_padding are paddings that may be present in the
140 underlying cryptolib linked to the Erlang/OTP crypto app.
141 For OpenSSL, see the OpenSSL documentation. and find
143 EVP_CIPHER_CTX_set_padding() in cryptolib for your linked ver‐
144 sion.
145 otp_padding() = zero | random
147 Erlang/OTP adds a either padding of zeroes or padding with ran‐
149 dom bytes.
150 Ciphers, old API
152 block_cipher_with_iv() =
153 cbc_cipher() | cfb_cipher() | blowfish_ofb64 | aes_ige256
154 block_cipher_without_iv() = ecb_cipher()
156 stream_cipher() = ctr_cipher() | chacha20 | rc4
158 aead_cipher() = aes_gcm | aes_ccm | chacha20_poly1305
160 cbc_cipher() =
162 aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
163 des_cbc | des_ede3_cbc | rc2_cbc |
164 retired_cbc_cipher_aliases()
165 cfb_cipher() =
167 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
168 aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 | blowfish_cfb64 |
169 des_cfb | des_ede3_cfb |
170 retired_cfb_cipher_aliases()
171 ctr_cipher() =
173 aes_128_ctr | aes_192_ctr | aes_256_ctr |
174 retired_ctr_cipher_aliases()
175 ecb_cipher() =
177 aes_128_ecb | aes_192_ecb | aes_256_ecb | blowfish_ecb |
178 retired_ecb_cipher_aliases()
179 Ciphers known by the CRYPTO application when using the old API.
181 Note that this list might be reduced if the underlying libcrypto
183 does not support all of them.
184 retired_cbc_cipher_aliases() =
186 aes_cbc | aes_cbc128 | aes_cbc256 | des3_cbc | des_ede3
187 retired_cfb_cipher_aliases() =
189 aes_cfb8 | aes_cfb128 | des3_cbf | des3_cfb | des_ede3_cbf
190 retired_ctr_cipher_aliases() = aes_ctr
192 retired_ecb_cipher_aliases() = aes_ecb
194 Alternative, old names of ciphers known by the CRYPTO applica‐
196 tion when using the old API. See Retired cipher names for names
197 to use instead to be prepared for an easy convertion to the new
198 API.
199 Note that this list might be reduced if the underlying libcrypto
201 does not support all of them.
202 Digests and hash
204 hash_algorithm() =
205 sha1() |
206 sha2() |
207 sha3() |
208 blake2() |
209 ripemd160 |
210 compatibility_only_hash()
211 hmac_hash_algorithm() =
213 sha1() | sha2() | sha3() | compatibility_only_hash()
214 cmac_cipher_algorithm() =
216 aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
217 des_cbc | des_ede3_cbc | rc2_cbc | aes_128_cfb128 |
218 aes_192_cfb128 | aes_256_cfb128 | aes_128_cfb8 |
219 aes_192_cfb8 | aes_256_cfb8
220 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
222 dss_digest_type() = sha1() | sha2()
224 ecdsa_digest_type() = sha1() | sha2()
226 sha1() = sha
228 sha2() = sha224 | sha256 | sha384 | sha512
230 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
232 blake2() = blake2b | blake2s
234 compatibility_only_hash() = md5 | md4
236 The compatibility_only_hash() algorithms are recommended only
238 for compatibility with existing applications.
239 Elliptic Curves
241 ec_named_curve() =
242 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
243 brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
244 brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
245 brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
246 brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
247 c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
248 c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
249 c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
250 c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
251 prime192v2 | prime192v3 | prime239v1 | prime239v2 |
252 prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
253 secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
254 secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
255 secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
256 sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
257 sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
258 sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
259 wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
260 wtls6 | wtls7 | wtls8 | wtls9
261 edwards_curve_dh() = x25519 | x448
263 edwards_curve_ed() = ed25519 | ed448
265 Note that some curves are disabled if FIPS is enabled.
267 ec_explicit_curve() =
269 {Field :: ec_field(),
270 Curve :: ec_curve(),
271 BasePoint :: binary(),
272 Order :: binary(),
273 CoFactor :: none | binary()}
274 ec_field() = ec_prime_field() | ec_characteristic_two_field()
276 ec_curve() =
278 {A :: binary(), B :: binary(), Seed :: none | binary()}
279 Parametric curve definition.
281 ec_prime_field() = {prime_field, Prime :: integer()}
283 ec_characteristic_two_field() =
285 {characteristic_two_field,
286 M :: integer(),
287 Basis :: ec_basis()}
288 ec_basis() =
290 {tpbasis, K :: integer() >= 0} |
291 {ppbasis,
292 K1 :: integer() >= 0,
293 K2 :: integer() >= 0,
294 K3 :: integer() >= 0} |
295 onbasis
296 Curve definition details.
298 Keys
300 key() = iodata()
301 des3_key() = [key()]
303 For keylengths, iv-sizes and blocksizes see the User's Guide.
305 A key for des3 is a list of three iolists
307 key_integer() = integer() | binary()
309 Always binary() when used as return value
311 Public/Private Keys
313 rsa_public() = [key_integer()]
314 rsa_private() = [key_integer()]
316 rsa_params() =
318 {ModulusSizeInBits :: integer(),
319 PublicExponent :: key_integer()}
320 rsa_public() = [E, N]
322 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
324 Where E is the public exponent, N is public modulus and D is the
326 private exponent. The longer key format contains redundant
327 information that will make the calculation faster. P1 and P2 are
328 first and second prime factors. E1 and E2 are first and second
329 exponents. C is the CRT coefficient. The terminology is taken
330 from RFC 3447.
331 dss_public() = [key_integer()]
333 dss_private() = [key_integer()]
335 dss_public() = [P, Q, G, Y]
337 Where P, Q and G are the dss parameters and Y is the public key.
339 dss_private() = [P, Q, G, X]
341 Where P, Q and G are the dss parameters and X is the private
343 key.
344 ecdsa_public() = key_integer()
346 ecdsa_private() = key_integer()
348 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
350 eddsa_public() = key_integer()
352 eddsa_private() = key_integer()
354 eddsa_params() = edwards_curve_ed()
356 srp_public() = key_integer()
358 srp_private() = key_integer()
360 srp_public() = key_integer()
362 Where is A or B from SRP design
364 srp_private() = key_integer()
366 Where is a or b from SRP design
368 srp_gen_params() =
370 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
371 srp_comp_params() =
373 {user, srp_user_comp_params()} |
374 {host, srp_host_comp_params()}
375 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
377 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
379 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
381 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
383 Where Verifier is v, Generator is g and Prime is N, DerivedKey
385 is X, and Scrambler is u (optional will be generated if not pro‐
386 vided) from SRP design Version = '3' | '6' | '6a'
387 Public Key Ciphers
389 pk_encrypt_decrypt_algs() = rsa
390 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
392 ported.
393 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
395 rsa_opt() =
397 {rsa_padding, rsa_padding()} |
398 {signature_md, atom()} |
399 {rsa_mgf1_md, sha} |
400 {rsa_oaep_label, binary()} |
401 {rsa_oaep_md, sha}
402 rsa_padding() =
404 rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
405 rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
406 Options for public key encrypt/decrypt. Only RSA is supported.
408 Warning:
410 The RSA options are experimental.
412 The exact set of options and there syntax may be changed without
414 prior notice.
415 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
418 Those option forms are kept only for compatibility and should
420 not be used in new code.
421 Public Key Sign and Verify
423 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
424 Algorithms for sign and verify.
426 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
428 rsa_sign_verify_opt() =
430 {rsa_padding, rsa_sign_verify_padding()} |
431 {rsa_pss_saltlen, integer()} |
432 {rsa_mgf1_md, sha2()}
433 rsa_sign_verify_padding() =
435 rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
436 rsa_no_padding
437 Options for sign and verify.
439 Warning:
441 The RSA options are experimental.
443 The exact set of options and there syntax may be changed without
445 prior notice.
446 Diffie-Hellman Keys and parameters
449 dh_public() = key_integer()
450 dh_private() = key_integer()
452 dh_params() = [key_integer()]
454 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
456 ecdh_public() = key_integer()
458 ecdh_private() = key_integer()
460 ecdh_params() =
462 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
463 Types for Engines
465 engine_key_ref() =
466 #{engine := engine_ref(),
467 key_id := key_id(),
468 password => password(),
469 term() => term()}
470 engine_ref() = term()
472 The result of a call to engine_load/3.
474 key_id() = string() | binary()
476 Identifies the key to be used. The format depends on the loaded
478 engine. It is passed to the ENGINE_load_(private|public)_key
479 functions in libcrypto.
480 password() = string() | binary()
482 The password of the key stored in an engine.
484 engine_method_type() =
486 engine_method_rsa | engine_method_dsa | engine_method_dh |
487 engine_method_rand | engine_method_ecdh |
488 engine_method_ecdsa | engine_method_ciphers |
489 engine_method_digests | engine_method_store |
490 engine_method_pkey_meths | engine_method_pkey_asn1_meths |
491 engine_method_ec
492 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
494 Pre and Post commands for engine_load/3 and /4.
496 Internal data types
498 crypto_state()
499 hash_state()
501 hmac_state()
503 mac_state()
505 stream_state()
507 Contexts with an internal state that should not be manipulated
509 but passed between function calls.
510 Error types
512 run_time_error() = any()
513 The exception error:badarg signifies that one or more arguments
515 are of wrong data type, or are otherwise badly formed.
516 The exception error:notsup signifies that the algorithm is known
518 but is not supported by current underlying libcrypto or explic‐
519 itly disabled when building that.
520 For a list of supported algorithms, see supports/0.
522 descriptive_error() = any()
524 This is a more developed variant of the older run_time_error().
526 The exception is:
528 {Tag, {C_FileName,LineNumber}, Description}
530 Tag = badarg | notsup | error
532 C_FileName = string()
533 LineNumber = integer()
534 Description = string()
535 It is like the older type an exception of the error class. In
538 addition they contain a descriptive text in English. That text
539 is targeted to a developer. Examples are "Bad key size" or
540 "Cipher id is not an atom".
541 The exception tags are:
543 badarg:
545 Signifies that one or more arguments are of wrong data type
546 or are otherwise badly formed.
547 notsup:
549 Signifies that the algorithm is known but is not supported
550 by current underlying libcrypto or explicitly disabled when
551 building that one.
552 error:
554 An error condition that should not occur, for example a mem‐
555 ory allocation failed or the underlying cryptolib returned
556 an error code, for example "Can't initialize context, step
557 1". Those text usually needs searching the C-code to be
558 understood.
559 To catch the exception, use for example:
561 try crypto:crypto_init(Ciph, Key, IV, true)
563 catch
564 error:{Tag, {C_FileName,LineNumber}, Description} ->
565 do_something(......)
566 .....
567 end
568
572 crypto_init(Cipher, Key, FlagOrOptions) ->
573 State | descriptive_error()
574 Types:
576 Cipher = cipher_no_iv()
578 Key = iodata()
579 FlagOrOptions = crypto_opts() | boolean()
580 State = crypto_state()
581 Part of the new API.
583 Equivalent to the call crypto_init(Cipher, Key, <<>>, FlagOrOp‐
585 tions). It is intended for ciphers without an IV (nounce).
586 crypto_init(Cipher, Key, IV, FlagOrOptions) ->
588 State | descriptive_error()
589 Types:
591 Cipher = cipher_iv()
593 Key = IV = iodata()
594 FlagOrOptions = crypto_opts()
595 State = crypto_state()
596 Part of the new API. Initializes a series of encryptions or
598 decryptions and creates an internal state with a reference that
599 is returned.
600 If IV = <<>>, no IV is used. This is intended for ciphers with‐
602 out an IV (nounce). See crypto_init/3.
603 If IV = undefined, the IV must be added by calls to
605 crypto_dyn_iv_update/3. This is intended for cases where the IV
606 (nounce) need to be changed for each encryption and decryption.
607 See crypto_dyn_iv_init/3.
608 The actual encryption or decryption is done by crypto_update/2
610 (or crypto_dyn_iv_update/3 ).
611 For encryption, set the FlagOrOptions to true or
613 [{encrypt,true}]. For decryption, set it to false or
614 [{encrypt,false}].
615 Padding could be enabled with the option {padding,Padding}. The
617 cryptolib_padding enables pkcs_padding or no padding (none). The
618 paddings zero or random fills the last part of the last block
619 with zeroes or random bytes. If the last block is already full,
620 nothing is added.
621 In decryption, the cryptolib_padding removes such padding, if
623 present. The otp_padding is not removed - it has to be done
624 elsewhere.
625 If padding is {padding,none} or not specifed and the total data
627 from all subsequent crypto_updates does not fill the last block
628 fully, that last data is lost. In case of {padding,none} there
629 will be an error in this case. If padding is not specified, the
630 bytes of the unfilled block is silently discarded.
631 The actual padding is performed by crypto_final/1.
633 For blocksizes call cipher_info/1.
635 See examples in the User's Guide.
637 crypto_update(State, Data) -> Result | descriptive_error()
639 Types:
641 State = crypto_state()
643 Data = iodata()
644 Result = binary()
645 Part of the new API. It does an actual crypto operation on a
647 part of the full text. If the part is less than a number of full
648 blocks, only the full blocks (possibly none) are encrypted or
649 decrypted and the remaining bytes are saved to the next
650 crypto_update operation. The State should be created with
651 crypto_init/3 or crypto_init/4.
652 See examples in the User's Guide.
654 crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) ->
656 State | descriptive_error()
657 Types:
659 Cipher = cipher_iv()
661 Key = iodata()
662 FlagOrOptions = crypto_opts() | boolean()
663 State = crypto_state()
664 Part of the new API.
666 Initializes a series of encryptions or decryptions where the IV
668 is provided later. The actual encryption or decryption is done
669 by crypto_dyn_iv_update/3.
670 The function is equivalent to crypto_init(Cipher, Key, unde‐
672 fined, FlagOrOptions).
673 crypto_final(State) -> FinalResult | descriptive_error()
675 Types:
677 State = crypto_state()
679 FinalResult = binary()
680 Part of the new API.
682 Finalizes a series of encryptions or decryptions and delivers
684 the final bytes of the final block. The data returned from this
685 function may be empty if no padding was enabled in
686 crypto_init/3,4 or crypto_dyn_iv_init/3.
687 crypto_get_data(State) -> Result
689 Types:
691 State = crypto_state()
693 Result = map()
694 Part of the new API.
696 Returns information about the State in the argument. The infor‐
698 mation is the form of a map, which currently contains at least:
699 size:
701 The number of bytes encrypted or decrypted so far.
702 padding_size:
704 After a call to crypto_final/1 it contains the number of
705 bytes padded. Otherwise 0.
706 padding_type:
708 The type of the padding as provided in the call ot
709 crypto_init/3,4.
710 encrypt:
712 Is true if encryption is performed. It is false otherwise.
713 crypto_dyn_iv_update(State, Data, IV) ->
715 Result | descriptive_error()
716 Types:
718 State = crypto_state()
720 Data = IV = iodata()
721 Result = binary()
722 Part of the new API. Do an actual crypto operation on a part of
724 the full text and the IV is supplied for each part. The State
725 should be created with crypto_dyn_iv_init/3.
726 crypto_one_time(Cipher, Key, Data, FlagOrOptions) ->
728 Result | descriptive_error()
729 Types:
731 Cipher = cipher_no_iv()
733 Key = Data = iodata()
734 FlagOrOptions = crypto_opts() | boolean()
735 Result = binary()
736 As crypto_one_time/5 but for ciphers without IVs.
738 crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) ->
740 Result | descriptive_error()
741 Types:
743 Cipher = cipher_iv()
745 Key = IV = Data = iodata()
746 FlagOrOptions = crypto_opts() | boolean()
747 Result = binary()
748 Part of the new API. Do a complete encrypt or decrypt of the
750 full text in the argument Data.
751 For encryption, set the FlagOrOptions to true. For decryption,
753 set it to false. For setting other options, see crypto_init/4.
754 See examples in the User's Guide.
756 crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
758 EncFlag :: true) ->
759 Result | descriptive_error()
760 crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
762 EncFlag) ->
763 Result | descriptive_error()
764 Types:
766 Cipher = cipher_aead()
768 Key = IV = InText = AAD = iodata()
769 TagOrTagLength = EncryptTagLength | DecryptTag
770 EncryptTagLength = integer() >= 0
771 DecryptTag = iodata()
772 EncFlag = boolean()
773 Result = EncryptResult | DecryptResult
774 EncryptResult = {OutCryptoText, OutTag}
775 DecryptResult = OutPlainText | error
776 OutCryptoText = OutTag = OutPlainText = binary()
777 Part of the new API. Do a complete encrypt or decrypt with an
779 AEAD cipher of the full text.
780 For encryption, set the EncryptFlag to true and set the TagOrTa‐
782 gLength to the wanted size (in bytes) of the tag, that is, the
783 tag length. If the default length is wanted, the crypto_aead/6
784 form may be used.
785 For decryption, set the EncryptFlag to false and put the tag to
787 be checked in the argument TagOrTagLength.
788 See examples in the User's Guide.
790 supports(Type) -> Support
792 Types:
794 Type = hashs | ciphers | public_keys | macs | curves |
796 rsa_opts
797 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
798 Hashs =
799 [sha1() |
800 sha2() |
801 sha3() |
802 blake2() |
803 ripemd160 |
804 compatibility_only_hash()]
805 Ciphers = [cipher()]
806 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
807 Macs = [hmac | cmac | poly1305]
808 Curves =
809 [ec_named_curve() | edwards_curve_dh() |
810 edwards_curve_ed()]
811 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
812 Can be used to determine which crypto algorithms that are sup‐
814 ported by the underlying libcrypto library
815 See hash_info/1 and cipher_info/1 for information about the hash
817 and cipher algorithms.
818 mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()
820 Types:
822 Key = Data = iodata()
824 Mac = binary()
825 Short for mac(Type, undefined, Key, Data).
827 mac(Type, SubType, Key, Data) -> Mac | descriptive_error()
829 Types:
831 Type = hmac | cmac | poly1305
833 SubType =
834 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
835 fined
836 Key = Data = iodata()
837 Mac = binary()
838 Computes a MAC (Message Authentication Code) of type Type from
840 Data.
841 SubType depends on the MAC Type:
843 * For hmac it is a hash algorithm, see Algorithm Details in
845 the User's Guide.
846 * For cmac it is a cipher suitable for cmac, see Algorithm
848 Details in the User's Guide.
849 * For poly1305 it should be set to undefined or the mac/2
851 function could be used instead, see Algorithm Details in the
852 User's Guide.
853 Key is the authentication key with a length according to the
855 Type and SubType. The key length could be found with the
856 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
857 poly1305 the key length is 32 bytes. Note that the cryptographic
858 quality of the key is not checked.
859 The Mac result will have a default length depending on the Type
861 and SubType. To set a shorter length, use macN/4 or macN/5
862 instead. The default length is documented in Algorithm Details
863 in the User's Guide.
864 macN(Type :: poly1305, Key, Data, MacLength) ->
866 Mac | descriptive_error()
867 Types:
869 Key = Data = iodata()
871 Mac = binary()
872 MacLength = integer() >= 1
873 Short for macN(Type, undefined, Key, Data, MacLength).
875 macN(Type, SubType, Key, Data, MacLength) ->
877 Mac | descriptive_error()
878 Types:
880 Type = hmac | cmac | poly1305
882 SubType =
883 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
884 fined
885 Key = Data = iodata()
886 Mac = binary()
887 MacLength = integer() >= 1
888 Computes a MAC (Message Authentication Code) as mac/3 and mac/4
890 but MacLength will limit the size of the resultant Mac to at
891 most MacLength bytes. Note that if MacLength is greater than the
892 actual number of bytes returned from the underlying hash, the
893 returned hash will have that shorter length instead.
894 The max MacLength is documented in Algorithm Details in the
896 User's Guide.
897 mac_init(Type :: poly1305, Key) -> State | descriptive_error()
899 Types:
901 Key = iodata()
903 State = mac_state()
904 Short for mac_init(Type, undefined, Key).
906 mac_init(Type, SubType, Key) -> State | descriptive_error()
908 Types:
910 Type = hmac | cmac | poly1305
912 SubType =
913 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
914 fined
915 Key = iodata()
916 State = mac_state()
917 Initializes the context for streaming MAC operations.
919 Type determines which mac algorithm to use in the MAC operation.
921 SubType depends on the MAC Type:
923 * For hmac it is a hash algorithm, see Algorithm Details in
925 the User's Guide.
926 * For cmac it is a cipher suitable for cmac, see Algorithm
928 Details in the User's Guide.
929 * For poly1305 it should be set to undefined or the mac/2
931 function could be used instead, see Algorithm Details in the
932 User's Guide.
933 Key is the authentication key with a length according to the
935 Type and SubType. The key length could be found with the
936 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
937 poly1305 the key length is 32 bytes. Note that the cryptographic
938 quality of the key is not checked.
939 The returned State should be used in one or more subsequent
941 calls to mac_update/2. The MAC value is finally returned by
942 calling mac_final/1 or mac_finalN/2.
943 See examples in the User's Guide.
945 mac_update(State0, Data) -> State | descriptive_error()
947 Types:
949 Data = iodata()
951 State0 = State = mac_state()
952 Updates the MAC represented by State0 using the given Data which
954 could be of any length.
955 The State0 is the State value originally from a MAC init func‐
957 tion, that is mac_init/2, mac_init/3 or a previous call of
958 mac_update/2. The value State0 is returned unchanged by the
959 function as State.
960 mac_final(State) -> Mac | descriptive_error()
962 Types:
964 State = mac_state()
966 Mac = binary()
967 Finalizes the MAC operation referenced by State. The Mac result
969 will have a default length depending on the Type and SubType in
970 the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
971 instead. The default length is documented in Algorithm Details
972 in the User's Guide.
973 mac_finalN(State, MacLength) -> Mac | descriptive_error()
975 Types:
977 State = mac_state()
979 MacLength = integer() >= 1
980 Mac = binary()
981 Finalizes the MAC operation referenced by State.
983 Mac will be a binary with at most MacLength bytes. Note that if
985 MacLength is greater than the actual number of bytes returned
986 from the underlying hash, the returned hash will have that
987 shorter length instead.
988 The max MacLength is documented in Algorithm Details in the
990 User's Guide.
991
994 bytes_to_integer(Bin :: binary()) -> integer()
995 Convert binary representation, of an integer, to an Erlang inte‐
997 ger.
998 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
1000 SharedSecret
1001 Types:
1003 Type = dh | ecdh | eddh | srp
1005 SharedSecret = binary()
1006 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
1007 MyPrivateKey =
1008 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
1009 vate()}
1010 Params = dh_params() | ecdh_params() | srp_comp_params()
1011 Computes the shared secret from the private key and the other
1013 party's public key. See also public_key:compute_key/2
1014 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
1016 Performs bit-wise XOR (exclusive or) on the data supplied.
1018 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
1020 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
1022 Types:
1024 Type = dh | ecdh | eddh | eddsa | rsa | srp
1026 PublicKey =
1027 dh_public() | ecdh_public() | rsa_public() | srp_public()
1028 PrivKeyIn =
1029 undefined |
1030 dh_private() |
1031 ecdh_private() |
1032 rsa_private() |
1033 {srp_public(), srp_private()}
1034 PrivKeyOut =
1035 dh_private() |
1036 ecdh_private() |
1037 rsa_private() |
1038 {srp_public(), srp_private()}
1039 Params =
1040 dh_params() |
1041 ecdh_params() |
1042 eddsa_params() |
1043 rsa_params() |
1044 srp_comp_params()
1045 Generates a public key of type Type. See also public_key:gener‐
1047 ate_key/1. May raise exception:
1048 * error:badarg: an argument is of wrong type or has an illegal
1050 value,
1051 * error:low_entropy: the random generator failed due to lack
1053 of secure "randomness",
1054 * error:computation_failed: the computation fails of another
1056 reason than low_entropy.
1057 Note:
1059 RSA key generation is only available if the runtime was built
1060 with dirty scheduler support. Otherwise, attempting to generate
1061 an RSA key will raise exception error:notsup.
1062 hash(Type, Data) -> Digest
1065 Types:
1067 Type = hash_algorithm()
1069 Data = iodata()
1070 Digest = binary()
1071 Computes a message digest of type Type from Data.
1073 May raise exception error:notsup in case the chosen Type is not
1075 supported by the underlying libcrypto implementation.
1076 hash_init(Type) -> State
1078 Types:
1080 Type = hash_algorithm()
1082 State = hash_state()
1083 Initializes the context for streaming hash operations. Type
1085 determines which digest to use. The returned context should be
1086 used as argument to hash_update.
1087 May raise exception error:notsup in case the chosen Type is not
1089 supported by the underlying libcrypto implementation.
1090 hash_update(State, Data) -> NewState
1092 Types:
1094 State = NewState = hash_state()
1096 Data = iodata()
1097 Updates the digest represented by Context using the given Data.
1099 Context must have been generated using hash_init or a previous
1100 call to this function. Data can be any length. NewContext must
1101 be passed into the next call to hash_update or hash_final.
1102 hash_final(State) -> Digest
1104 Types:
1106 State = hash_state()
1108 Digest = binary()
1109 Finalizes the hash operation referenced by Context returned from
1111 a previous call to hash_update. The size of Digest is determined
1112 by the type of hash function used to generate it.
1113 info_fips() -> not_supported | not_enabled | enabled
1115 Provides information about the FIPS operating status of crypto
1117 and the underlying libcrypto library. If crypto was built with
1118 FIPS support this can be either enabled (when running in FIPS
1119 mode) or not_enabled. For other builds this value is always
1120 not_supported.
1121 See enable_fips_mode/1 about how to enable FIPS mode.
1123 Warning:
1125 In FIPS mode all non-FIPS compliant algorithms are disabled and
1126 raise exception error:notsup. Check supports that in FIPS mode
1127 returns the restricted list of available algorithms.
1128 enable_fips_mode(Enable) -> Result
1131 Types:
1133 Enable = Result = boolean()
1135 Enables (Enable = true) or disables (Enable = false) FIPS mode.
1137 Returns true if the operation was successful or false otherwise.
1138 Note that to enable FIPS mode succesfully, OTP must be built
1140 with the configure option --enable-fips, and the underlying
1141 libcrypto must also support FIPS.
1142 See also info_fips/0.
1144 info_lib() -> [{Name, VerNum, VerStr}]
1146 Types:
1148 Name = binary()
1150 VerNum = integer()
1151 VerStr = binary()
1152 Provides the name and version of the libraries used by crypto.
1154 Name is the name of the library. VerNum is the numeric version
1156 according to the library's own versioning scheme. VerStr con‐
1157 tains a text variant of the version.
1158 > info_lib().
1160 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
1161 Note:
1164 From OTP R16 the numeric version represents the version of the
1165 OpenSSL header files (openssl/opensslv.h) used when crypto was
1166 compiled. The text variant represents the libcrypto library used
1167 at runtime. In earlier OTP versions both numeric and text was
1168 taken from the library.
1169 hash_info(Type) -> Result | run_time_error()
1172 Types:
1174 Type = hash_algorithm()
1176 Result =
1177 #{size := integer(),
1178 block_size := integer(),
1179 type := integer()}
1180 Provides a map with information about block_size, size and pos‐
1182 sibly other properties of the hash algorithm in question.
1183 For a list of supported hash algorithms, see supports/0.
1185 cipher_info(Type) -> Result | run_time_error()
1187 Types:
1189 Type = cipher()
1191 Result =
1192 #{key_length := integer(),
1193 iv_length := integer(),
1194 block_size := integer(),
1195 mode := CipherModes,
1196 type := undefined | integer()}
1197 CipherModes =
1198 undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1199 ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1200 wrap_mode | xts_mode
1201 Provides a map with information about block_size, key_length,
1203 iv_length and possibly other properties of the cipher algorithm
1204 in question.
1205 Note:
1207 The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb,
1208 aes_gcm and aes_ccm has no keylength in the Type as opposed to
1209 for example aes_128_ctr. They adapt to the length of the key
1210 provided in the encrypt and decrypt function. Therefor it is
1211 impossible to return a valid keylength in the map.
1212 Always use a Type with an explicit key length,
1214 For a list of supported cipher algorithms, see supports/0.
1217 mod_pow(N, P, M) -> Result
1219 Types:
1221 N = P = M = binary() | integer()
1223 Result = binary() | error
1224 Computes the function N^P mod M.
1226 next_iv(Type :: cbc_cipher(), Data) -> NextIVec
1228 next_iv(Type :: des_cfb, Data, IVec) -> NextIVec
1230 Types:
1232 Data = iodata()
1234 IVec = NextIVec = binary()
1235 Returns the initialization vector to be used in the next itera‐
1237 tion of encrypt/decrypt of type Type. Data is the encrypted data
1238 from the previous iteration step. The IVec argument is only
1239 needed for des_cfb as the vector used in the previous iteration
1240 step.
1241 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1243 PlainText
1244 Types:
1246 Algorithm = pk_encrypt_decrypt_algs()
1248 CipherText = binary()
1249 PrivateKey = rsa_private() | engine_key_ref()
1250 Options = pk_encrypt_decrypt_opts()
1251 PlainText = binary()
1252 Decrypts the CipherText, encrypted with public_encrypt/4 (or
1254 equivalent function) using the PrivateKey, and returns the
1255 plaintext (message digest). This is a low level signature veri‐
1256 fication operation used for instance by older versions of the
1257 SSL protocol. See also public_key:decrypt_private/[2,3]
1258 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1260 CipherText
1261 Types:
1263 Algorithm = pk_encrypt_decrypt_algs()
1265 PlainText = binary()
1266 PrivateKey = rsa_private() | engine_key_ref()
1267 Options = pk_encrypt_decrypt_opts()
1268 CipherText = binary()
1269 Encrypts the PlainText using the PrivateKey and returns the
1271 ciphertext. This is a low level signature operation used for
1272 instance by older versions of the SSL protocol. See also pub‐
1273 lic_key:encrypt_private/[2,3]
1274 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1276 PlainText
1277 Types:
1279 Algorithm = pk_encrypt_decrypt_algs()
1281 CipherText = binary()
1282 PublicKey = rsa_public() | engine_key_ref()
1283 Options = pk_encrypt_decrypt_opts()
1284 PlainText = binary()
1285 Decrypts the CipherText, encrypted with private_encrypt/4(or
1287 equivalent function) using the PrivateKey, and returns the
1288 plaintext (message digest). This is a low level signature veri‐
1289 fication operation used for instance by older versions of the
1290 SSL protocol. See also public_key:decrypt_public/[2,3]
1291 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1293 CipherText
1294 Types:
1296 Algorithm = pk_encrypt_decrypt_algs()
1298 PlainText = binary()
1299 PublicKey = rsa_public() | engine_key_ref()
1300 Options = pk_encrypt_decrypt_opts()
1301 CipherText = binary()
1302 Encrypts the PlainText (message digest) using the PublicKey and
1304 returns the CipherText. This is a low level signature operation
1305 used for instance by older versions of the SSL protocol. See
1306 also public_key:encrypt_public/[2,3]
1307 rand_seed(Seed :: binary()) -> ok
1309 Set the seed for PRNG to the given binary. This calls the
1311 RAND_seed function from openssl. Only use this if the system you
1312 are running on does not have enough "randomness" built in. Nor‐
1313 mally this is when strong_rand_bytes/1 raises error:low_entropy
1314 rand_uniform(Lo, Hi) -> N
1316 Types:
1318 Lo, Hi, N = integer()
1320 Generate a random number N, Lo =< N < Hi. Uses the crypto
1322 library pseudo-random number generator. Hi must be larger than
1323 Lo.
1324 start() -> ok | {error, Reason :: term()}
1326 Equivalent to application:start(crypto).
1328 stop() -> ok | {error, Reason :: term()}
1330 Equivalent to application:stop(crypto).
1332 strong_rand_bytes(N :: integer() >= 0) -> binary()
1334 Generates N bytes randomly uniform 0..255, and returns the
1336 result in a binary. Uses a cryptographically secure prng seeded
1337 and periodically mixed with operating system provided entropy.
1338 By default this is the RAND_bytes method from OpenSSL.
1339 May raise exception error:low_entropy in case the random genera‐
1341 tor failed due to lack of secure "randomness".
1342 rand_seed() -> rand:state()
1344 Creates state object for random number generation, in order to
1346 generate cryptographically strong random numbers (based on
1347 OpenSSL's BN_rand_range), and saves it in the process dictionary
1348 before returning it as well. See also rand:seed/1 and
1349 rand_seed_s/0.
1350 When using the state object from this function the rand func‐
1352 tions using it may raise exception error:low_entropy in case the
1353 random generator failed due to lack of secure "randomness".
1354 Example
1356 _ = crypto:rand_seed(),
1358 _IntegerValue = rand:uniform(42), % [1; 42]
1359 _FloatValue = rand:uniform(). % [0.0; 1.0[
1360 rand_seed_s() -> rand:state()
1362 Creates state object for random number generation, in order to
1364 generate cryptographically strongly random numbers (based on
1365 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1366 When using the state object from this function the rand func‐
1368 tions using it may raise exception error:low_entropy in case the
1369 random generator failed due to lack of secure "randomness".
1370 Note:
1372 The state returned from this function cannot be used to get a
1373 reproducable random sequence as from the other rand functions,
1374 since reproducability does not match cryptographically safe.
1375 The only supported usage is to generate one distinct random
1377 sequence from this start state.
1378 rand_seed_alg(Alg) -> rand:state()
1381 Types:
1383 Alg = crypto | crypto_cache
1385 Creates state object for random number generation, in order to
1387 generate cryptographically strong random numbers, and saves it
1388 in the process dictionary before returning it as well. See also
1389 rand:seed/1 and rand_seed_alg_s/1.
1390 When using the state object from this function the rand func‐
1392 tions using it may raise exception error:low_entropy in case the
1393 random generator failed due to lack of secure "randomness".
1394 Example
1396 _ = crypto:rand_seed_alg(crypto_cache),
1398 _IntegerValue = rand:uniform(42), % [1; 42]
1399 _FloatValue = rand:uniform(). % [0.0; 1.0[
1400 rand_seed_alg(Alg, Seed) -> rand:state()
1402 Types:
1404 Alg = crypto_aes
1406 Creates a state object for random number generation, in order to
1408 generate cryptographically unpredictable random numbers, and
1409 saves it in the process dictionary before returning it as well.
1410 See also rand_seed_alg_s/2.
1411 Example
1413 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1415 IntegerValue = rand:uniform(42), % [1; 42]
1416 FloatValue = rand:uniform(), % [0.0; 1.0[
1417 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1418 IntegerValue = rand:uniform(42), % Same values
1419 FloatValue = rand:uniform(). % again
1420 rand_seed_alg_s(Alg) -> rand:state()
1423 Types:
1425 Alg = crypto | crypto_cache
1427 Creates state object for random number generation, in order to
1429 generate cryptographically strongly random numbers. See also
1430 rand:seed_s/1.
1431 If Alg is crypto this function behaves exactly like
1433 rand_seed_s/0.
1434 If Alg is crypto_cache this function fetches random data with
1436 OpenSSL's RAND_bytes and caches it for speed using an internal
1437 word size of 56 bits that makes calculations fast on 64 bit
1438 machines.
1439 When using the state object from this function the rand func‐
1441 tions using it may raise exception error:low_entropy in case the
1442 random generator failed due to lack of secure "randomness".
1443 The cache size can be changed from its default value using the
1445 crypto app's configuration parameter rand_cache_size.
1446 When using the state object from this function the rand func‐
1448 tions using it may throw exception low_entropy in case the ran‐
1449 dom generator failed due to lack of secure "randomness".
1450 Note:
1452 The state returned from this function cannot be used to get a
1453 reproducable random sequence as from the other rand functions,
1454 since reproducability does not match cryptographically safe.
1455 In fact since random data is cached some numbers may get repro‐
1457 duced if you try, but this is unpredictable.
1458 The only supported usage is to generate one distinct random
1460 sequence from this start state.
1461 rand_seed_alg_s(Alg, Seed) -> rand:state()
1464 Types:
1466 Alg = crypto_aes
1468 Creates a state object for random number generation, in order to
1470 generate cryptographically unpredictable random numbers. See
1471 also rand_seed_alg/1.
1472 To get a long period the Xoroshiro928 generator from the rand
1474 module is used as a counter (with period 2^928 - 1) and the gen‐
1475 erator states are scrambled through AES to create 58-bit pseudo
1476 random values.
1477 The result should be statistically completely unpredictable ran‐
1479 dom values, since the scrambling is cryptographically strong and
1480 the period is ridiculously long. But the generated numbers are
1481 not to be regarded as cryptographically strong since there is no
1482 re-keying schedule.
1483 * If you need cryptographically strong random numbers use
1485 rand_seed_alg_s/1 with Alg =:= crypto or Alg =:=
1486 crypto_cache.
1487 * If you need to be able to repeat the sequence use this func‐
1489 tion.
1490 * If you do not need the statistical quality of this function,
1492 there are faster algorithms in the rand module.
1493 Thanks to the used generator the state object supports the
1495 rand:jump/0,1 function with distance 2^512.
1496 Numbers are generated in batches and cached for speed reasons.
1498 The cache size can be changed from its default value using the
1499 crypto app's configuration parameter rand_cache_size.
1500 ec_curves() -> [EllipticCurve]
1502 Types:
1504 EllipticCurve =
1506 ec_named_curve() | edwards_curve_dh() |
1507 edwards_curve_ed()
1508 Can be used to determine which named elliptic curves are sup‐
1510 ported.
1511 ec_curve(CurveName) -> ExplicitCurve
1513 Types:
1515 CurveName = ec_named_curve()
1517 ExplicitCurve = ec_explicit_curve()
1518 Return the defining parameters of a elliptic curve.
1520 sign(Algorithm, DigestType, Msg, Key) -> Signature
1522 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1524 Types:
1526 Algorithm = pk_sign_verify_algs()
1528 DigestType =
1529 rsa_digest_type() |
1530 dss_digest_type() |
1531 ecdsa_digest_type() |
1532 none
1533 Msg = iodata() | {digest, iodata()}
1534 Key =
1535 rsa_private() |
1536 dss_private() |
1537 [ecdsa_private() | ecdsa_params()] |
1538 [eddsa_private() | eddsa_params()] |
1539 engine_key_ref()
1540 Options = pk_sign_verify_opts()
1541 Signature = binary()
1542 Creates a digital signature.
1544 The msg is either the binary "cleartext" data to be signed or it
1546 is the hashed value of "cleartext" i.e. the digest (plaintext).
1547 Algorithm dss can only be used together with digest type sha.
1549 See also public_key:sign/3.
1551 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1553 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1555 Result
1556 Types:
1558 Algorithm = pk_sign_verify_algs()
1560 DigestType =
1561 rsa_digest_type() | dss_digest_type() |
1562 ecdsa_digest_type()
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 Verifies a digital signature
1575 The msg is either the binary "cleartext" data to be signed or it
1577 is the hashed value of "cleartext" i.e. the digest (plaintext).
1578 Algorithm dss can only be used together with digest type sha.
1580 See also public_key:verify/4.
1582
1585 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1586 Types:
1588 Type = rsa | dss
1590 EnginePrivateKeyRef = engine_key_ref()
1591 PublicKey = rsa_public() | dss_public()
1592 Fetches the corresponding public key from a private key stored
1594 in an Engine. The key must be of the type indicated by the Type
1595 parameter.
1596 engine_get_all_methods() -> Result
1598 Types:
1600 Result = [engine_method_type()]
1602 Returns a list of all possible engine methods.
1604 May raise exception error:notsup in case there is no engine sup‐
1606 port in the underlying OpenSSL implementation.
1607 See also the chapter Engine Load in the User's Guide.
1609 engine_load(EngineId, PreCmds, PostCmds) -> Result
1611 Types:
1613 EngineId = unicode:chardata()
1615 PreCmds = PostCmds = [engine_cmnd()]
1616 Result =
1617 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1618 Loads the OpenSSL engine given by EngineId if it is available
1620 and then returns ok and an engine handle. This function is the
1621 same as calling engine_load/4 with EngineMethods set to a list
1622 of all the possible methods. An error tuple is returned if the
1623 engine can't be loaded.
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_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
1633 Types:
1635 EngineId = unicode:chardata()
1637 PreCmds = PostCmds = [engine_cmnd()]
1638 EngineMethods = [engine_method_type()]
1639 Result =
1640 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1641 Loads the OpenSSL engine given by EngineId if it is available
1643 and then returns ok and an engine handle. An error tuple is
1644 returned if the engine can't be loaded.
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 See also the chapter Engine Load in the User's Guide.
1652 engine_unload(Engine) -> Result
1654 Types:
1656 Engine = engine_ref()
1658 Result = ok | {error, Reason :: term()}
1659 Unloads the OpenSSL engine given by Engine. An error tuple is
1661 returned if the engine can't be unloaded.
1662 The function raises a error:badarg if the parameter is in wrong
1664 format. It may also raise the exception error:notsup in case
1665 there is no engine support in the underlying OpenSSL implementa‐
1666 tion.
1667 See also the chapter Engine Load in the User's Guide.
1669 engine_by_id(EngineId) -> Result
1671 Types:
1673 EngineId = unicode:chardata()
1675 Result =
1676 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1677 Get a reference to an already loaded engine with EngineId. An
1679 error tuple is returned if the engine can't be unloaded.
1680 The function raises a error:badarg if the parameter is in wrong
1682 format. It may also raise the exception error:notsup in case
1683 there is no engine support in the underlying OpenSSL implementa‐
1684 tion.
1685 See also the chapter Engine Load in the User's Guide.
1687 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1689 Types:
1691 Engine = term()
1693 CmdName = CmdArg = unicode:chardata()
1694 Result = ok | {error, Reason :: term()}
1695 Sends ctrl commands to the OpenSSL engine given by Engine. This
1697 function is the same as calling engine_ctrl_cmd_string/4 with
1698 Optional set to false.
1699 The function raises a error:badarg if the parameters are in
1701 wrong format. It may also raise the exception error:notsup in
1702 case there is no engine support in the underlying OpenSSL imple‐
1703 mentation.
1704 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1706 Result
1707 Types:
1709 Engine = term()
1711 CmdName = CmdArg = unicode:chardata()
1712 Optional = boolean()
1713 Result = ok | {error, Reason :: term()}
1714 Sends ctrl commands to the OpenSSL engine given by Engine.
1716 Optional is a boolean argument that can relax the semantics of
1717 the function. If set to true it will only return failure if the
1718 ENGINE supported the given command name but failed while execut‐
1719 ing it, if the ENGINE doesn't support the command name it will
1720 simply return success without doing anything. In this case we
1721 assume the user is only supplying commands specific to the given
1722 ENGINE so we set this to false.
1723 The function raises a error:badarg if the parameters are in
1725 wrong format. It may also raise the exception error:notsup in
1726 case there is no engine support in the underlying OpenSSL imple‐
1727 mentation.
1728 engine_add(Engine) -> Result
1730 Types:
1732 Engine = engine_ref()
1734 Result = ok | {error, Reason :: term()}
1735 Add the engine to OpenSSL's internal list.
1737 The function raises a error:badarg if the parameters are in
1739 wrong format. It may also raise the exception error:notsup in
1740 case there is no engine support in the underlying OpenSSL imple‐
1741 mentation.
1742 engine_remove(Engine) -> Result
1744 Types:
1746 Engine = engine_ref()
1748 Result = ok | {error, Reason :: term()}
1749 Remove the engine from OpenSSL's internal list.
1751 The function raises a error:badarg if the parameters are in
1753 wrong format. It may also raise the exception error:notsup in
1754 case there is no engine support in the underlying OpenSSL imple‐
1755 mentation.
1756 engine_get_id(Engine) -> EngineId
1758 Types:
1760 Engine = engine_ref()
1762 EngineId = unicode:chardata()
1763 Return the ID for the engine, or an empty binary if there is no
1765 id set.
1766 The function raises a error:badarg if the parameters are in
1768 wrong format. It may also raise the exception error:notsup in
1769 case there is no engine support in the underlying OpenSSL imple‐
1770 mentation.
1771 engine_get_name(Engine) -> EngineName
1773 Types:
1775 Engine = engine_ref()
1777 EngineName = unicode:chardata()
1778 Return the name (eg a description) for the engine, or an empty
1780 binary if there is no name set.
1781 The function raises a error:badarg if the parameters are in
1783 wrong format. It may also raise the exception error:notsup in
1784 case there is no engine support in the underlying OpenSSL imple‐
1785 mentation.
1786 engine_list() -> Result
1788 Types:
1790 Result = [EngineId :: unicode:chardata()]
1792 List the id's of all engines in OpenSSL's internal list.
1794 It may also raise the exception error:notsup in case there is no
1796 engine support in the underlying OpenSSL implementation.
1797 See also the chapter Engine Load in the User's Guide.
1799 May raise exception error:notsup in case engine functionality is
1801 not supported by the underlying OpenSSL implementation.
1802 ensure_engine_loaded(EngineId, LibPath) -> Result
1804 Types:
1806 EngineId = LibPath = unicode:chardata()
1808 Result =
1809 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1810 Loads the OpenSSL engine given by EngineId and the path to the
1812 dynamic library implementing the engine. This function is the
1813 same as calling ensure_engine_loaded/3 with EngineMethods set to
1814 a list of all the possible methods. An error tuple is returned
1815 if the engine can't be loaded.
1816 The function raises a error:badarg if the parameters are in
1818 wrong format. It may also raise the exception error:notsup in
1819 case there is no engine support in the underlying OpenSSL imple‐
1820 mentation.
1821 See also the chapter Engine Load in the User's Guide.
1823 ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
1825 Types:
1827 EngineId = LibPath = unicode:chardata()
1829 EngineMethods = [engine_method_type()]
1830 Result =
1831 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1832 Loads the OpenSSL engine given by EngineId and the path to the
1834 dynamic library implementing the engine. This function differs
1835 from the normal engine_load in that sense it also add the engine
1836 id to the internal list in OpenSSL. Then in the following calls
1837 to the function it just fetch the reference to the engine
1838 instead of loading it again. An error tuple is returned if the
1839 engine can't be loaded.
1840 The function raises a error:badarg if the parameters are in
1842 wrong format. It may also raise the exception error:notsup in
1843 case there is no engine support in the underlying OpenSSL imple‐
1844 mentation.
1845 See also the chapter Engine Load in the User's Guide.
1847 ensure_engine_unloaded(Engine) -> Result
1849 Types:
1851 Engine = engine_ref()
1853 Result = ok | {error, Reason :: term()}
1854 Unloads an engine loaded with the ensure_engine_loaded function.
1856 It both removes the label from the OpenSSL internal engine list
1857 and unloads the engine. This function is the same as calling
1858 ensure_engine_unloaded/2 with EngineMethods set to a list of all
1859 the possible methods. An error tuple is returned if the engine
1860 can't be unloaded.
1861 The function raises a error:badarg if the parameters are in
1863 wrong format. It may also raise the exception error:notsup in
1864 case there is no engine support in the underlying OpenSSL imple‐
1865 mentation.
1866 See also the chapter Engine Load in the User's Guide.
1868 ensure_engine_unloaded(Engine, EngineMethods) -> Result
1870 Types:
1872 Engine = engine_ref()
1874 EngineMethods = [engine_method_type()]
1875 Result = ok | {error, Reason :: term()}
1876 Unloads an engine loaded with the ensure_engine_loaded function.
1878 It both removes the label from the OpenSSL internal engine list
1879 and unloads the engine. An error tuple is returned if the engine
1880 can't be unloaded.
1881 The function raises a error:badarg if the parameters are in
1883 wrong format. It may also raise the exception error:notsup in
1884 case there is no engine support in the underlying OpenSSL imple‐
1885 mentation.
1886 See also the chapter Engine Load in the User's Guide.
1888
1891 block_encrypt(Type :: block_cipher_without_iv(),
1892 Key :: key(),
1893 PlainText :: iodata()) ->
1894 binary() | run_time_error()
1895 Dont:
1897 Don't use this function for new programs! Use the-new-api.
1898 Encrypt PlainText according to Type block cipher.
1901 May raise exception error:notsup in case the chosen Type is not
1903 supported by the underlying libcrypto implementation.
1904 For keylengths and blocksizes see the User's Guide.
1906 block_decrypt(Type :: block_cipher_without_iv(),
1908 Key :: key(),
1909 Data :: iodata()) ->
1910 binary() | run_time_error()
1911 Dont:
1913 Don't use this function for new programs! Use the new api.
1914 Decrypt CipherText according to Type block cipher.
1917 May raise exception error:notsup in case the chosen Type is not
1919 supported by the underlying libcrypto implementation.
1920 For keylengths and blocksizes see the User's Guide.
1922 block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error
1924 block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText,
1925 CipherTag} | Error
1926 block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText,
1927 TagLength}) -> {CipherText, CipherTag} | Error
1928 Types:
1930 Type = block_cipher_with_iv()
1932 AeadType = aead_cipher()
1933 Key = key() | des3_key()
1934 PlainText = iodata()
1935 AAD = IVec = CipherText = CipherTag = binary()
1936 TagLength = 1..16
1937 Error = run_time_error()
1938 Dont:
1940 Don't use this function for new programs! Use the new api.
1941 Encrypt PlainText according to Type block cipher. IVec is an
1944 arbitrary initializing vector.
1945 In AEAD (Authenticated Encryption with Associated Data) mode,
1947 encrypt PlainTextaccording to Type block cipher and calculate
1948 CipherTag that also authenticates the AAD (Associated Authenti‐
1949 cated Data).
1950 May raise exception error:notsup in case the chosen Type is not
1952 supported by the underlying libcrypto implementation.
1953 For keylengths, iv-sizes and blocksizes see the User's Guide.
1955 block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error
1957 block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) ->
1958 PlainText | Error
1959 Types:
1961 Type = block_cipher_with_iv()
1963 AeadType = aead_cipher()
1964 Key = key() | des3_key()
1965 PlainText = iodata()
1966 AAD = IVec = CipherText = CipherTag = binary()
1967 Error = BadTag | run_time_error()
1968 BadTag = error
1969 Dont:
1971 Don't use this function for new programs! Use the new api.
1972 Decrypt CipherText according to Type block cipher. IVec is an
1975 arbitrary initializing vector.
1976 In AEAD (Authenticated Encryption with Associated Data) mode,
1978 decrypt CipherTextaccording to Type block cipher and check the
1979 authenticity the PlainText and AAD (Associated Authenticated
1980 Data) using the CipherTag. May return error if the decryption or
1981 validation fail's
1982 May raise exception error:notsup in case the chosen Type is not
1984 supported by the underlying libcrypto implementation.
1985 For keylengths, iv-sizes and blocksizes see the User's Guide.
1987 stream_init(Type, Key) -> State | run_time_error()
1989 Types:
1991 Type = rc4
1993 Key = iodata()
1994 State = stream_state()
1995 Dont:
1997 Don't use this function for new programs! Use the new api.
1998 Initializes the state for use in RC4 stream encryption
2001 stream_encrypt and stream_decrypt
2002 For keylengths see the User's Guide.
2004 stream_init(Type, Key, IVec) -> State | run_time_error()
2006 Types:
2008 Type = stream_cipher()
2010 Key = iodata()
2011 IVec = binary()
2012 State = stream_state()
2013 Dont:
2015 Don't use this function for new programs! Use the new api.
2016 Initializes the state for use in streaming AES encryption using
2019 Counter mode (CTR). Key is the AES key and must be either 128,
2020 192, or 256 bits long. IVec is an arbitrary initializing vector
2021 of 128 bits (16 bytes). This state is for use with
2022 stream_encrypt and stream_decrypt.
2023 For keylengths and iv-sizes see the User's Guide.
2025 stream_encrypt(State, PlainText) ->
2027 {NewState, CipherText} | run_time_error()
2028 Types:
2030 State = stream_state()
2032 PlainText = iodata()
2033 NewState = stream_state()
2034 CipherText = iodata()
2035 Dont:
2037 Don't use this function for new programs! Use the new api.
2038 Encrypts PlainText according to the stream cipher Type specified
2041 in stream_init/3. Text can be any number of bytes. The initial
2042 State is created using stream_init. NewState must be passed into
2043 the next call to stream_encrypt.
2044 stream_decrypt(State, CipherText) ->
2046 {NewState, PlainText} | run_time_error()
2047 Types:
2049 State = stream_state()
2051 CipherText = iodata()
2052 NewState = stream_state()
2053 PlainText = iodata()
2054 Dont:
2056 Don't use this function for new programs! Use the new api.
2057 Decrypts CipherText according to the stream cipher Type speci‐
2060 fied in stream_init/3. PlainText can be any number of bytes. The
2061 initial State is created using stream_init. NewState must be
2062 passed into the next call to stream_decrypt.
2063 supports() -> [Support]
2065 Types:
2067 Support =
2069 {hashs, Hashs} |
2070 {ciphers, Ciphers} |
2071 {public_keys, PKs} |
2072 {macs, Macs} |
2073 {curves, Curves} |
2074 {rsa_opts, RSAopts}
2075 Hashs =
2076 [sha1() |
2077 sha2() |
2078 sha3() |
2079 blake2() |
2080 ripemd160 |
2081 compatibility_only_hash()]
2082 Ciphers = [cipher()]
2083 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
2084 Macs = [hmac | cmac | poly1305]
2085 Curves =
2086 [ec_named_curve() | edwards_curve_dh() |
2087 edwards_curve_ed()]
2088 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
2089 Dont:
2091 Don't use this function for new programs! Use supports/1 in the
2092 new api.
2093 Can be used to determine which crypto algorithms that are sup‐
2096 ported by the underlying libcrypto library
2097 See hash_info/1 and cipher_info/1 for information about the hash
2099 and cipher algorithms.
2100 hmac(Type, Key, Data) -> Mac
2102 hmac(Type, Key, Data, MacLength) -> Mac
2104 Types:
2106 Type = hmac_hash_algorithm()
2108 Key = Data = iodata()
2109 MacLength = integer()
2110 Mac = binary()
2111 Dont:
2113 Don't use this function for new programs! Use mac/4 or macN/5 in
2114 the new api.
2115 Computes a HMAC of type Type from Data using Key as the authen‐
2118 tication key.
2119 MacLength will limit the size of the resultant Mac.
2121 hmac_init(Type, Key) -> State
2123 Types:
2125 Type = hmac_hash_algorithm()
2127 Key = iodata()
2128 State = hmac_state()
2129 Dont:
2131 Don't use this function for new programs! Use mac_init/3 in the
2132 new api.
2133 Initializes the context for streaming HMAC operations. Type
2136 determines which hash function to use in the HMAC operation. Key
2137 is the authentication key. The key can be any length.
2138 hmac_update(State, Data) -> NewState
2140 Types:
2142 Data = iodata()
2144 State = NewState = hmac_state()
2145 Dont:
2147 Don't use this function for new programs! Use mac_update/2 in
2148 the new api.
2149 Updates the HMAC represented by Context using the given Data.
2152 Context must have been generated using an HMAC init function
2153 (such as hmac_init). Data can be any length. NewContext must be
2154 passed into the next call to hmac_update or to one of the func‐
2155 tions hmac_final and hmac_final_n
2156 Warning:
2158 Do not use a Context as argument in more than one call to
2159 hmac_update or hmac_final. The semantics of reusing old contexts
2160 in any way is undefined and could even crash the VM in earlier
2161 releases. The reason for this limitation is a lack of support in
2162 the underlying libcrypto API.
2163 hmac_final(State) -> Mac
2166 Types:
2168 State = hmac_state()
2170 Mac = binary()
2171 Dont:
2173 Don't use this function for new programs! Use mac_final/1 in the
2174 new api.
2175 Finalizes the HMAC operation referenced by Context. The size of
2178 the resultant MAC is determined by the type of hash function
2179 used to generate it.
2180 hmac_final_n(State, HashLen) -> Mac
2182 Types:
2184 State = hmac_state()
2186 HashLen = integer()
2187 Mac = binary()
2188 Dont:
2190 Don't use this function for new programs! Use mac_finalN/2 in
2191 the new api.
2192 Finalizes the HMAC operation referenced by Context. HashLen must
2195 be greater than zero. Mac will be a binary with at most HashLen
2196 bytes. Note that if HashLen is greater than the actual number of
2197 bytes returned from the underlying hash, the returned hash will
2198 have fewer than HashLen bytes.
2199 cmac(Type, Key, Data) -> Mac
2201 cmac(Type, Key, Data, MacLength) -> Mac
2203 Types:
2205 Type =
2207 cbc_cipher() |
2208 cfb_cipher() |
2209 blowfish_cbc | des_ede3 | rc2_cbc
2210 Key = Data = iodata()
2211 MacLength = integer()
2212 Mac = binary()
2213 Dont:
2215 Don't use this function for new programs! Use mac/4 or macN/5 in
2216 the new api.
2217 Computes a CMAC of type Type from Data using Key as the authen‐
2220 tication key.
2221 MacLength will limit the size of the resultant Mac.
2223 poly1305(Key :: iodata(), Data :: iodata()) -> Mac
2225 Types:
2227 Mac = binary()
2229 Dont:
2231 Don't use this function for new programs! Use mac/3 or macN/4 in
2232 the new api.
2233 Computes a POLY1305 message authentication code (Mac) from Data
2236 using Key as the authentication key.
2237Ericsson AB crypto 4.9 crypto(3)