1crypto(3) Erlang Module Definition crypto(3)
2
6 crypto - Crypto Functions
7
9 This module provides a set of cryptographic functions.
10 Hash functions:
12 SHA1, SHA2:
15 Secure Hash Standard [FIPS PUB 180-4]
16 SHA3:
18 SHA-3 Standard: Permutation-Based Hash and Extendable-Output
19 Functions [FIPS PUB 202]
20 BLAKE2:
22 BLAKE2 — fast secure hashing
23 MD5:
25 The MD5 Message Digest Algorithm [RFC 1321]
26 MD4:
28 The MD4 Message Digest Algorithm [RFC 1320]
29 MACs - Message Authentication Codes:
31 Hmac functions:
34 Keyed-Hashing for Message Authentication [RFC 2104]
35 Cmac functions:
37 The AES-CMAC Algorithm [RFC 4493]
38 POLY1305:
40 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
41 Symmetric Ciphers:
43 DES, 3DES and AES:
46 Block Cipher Techniques [NIST]
47 Blowfish:
49 Fast Software Encryption, Cambridge Security Workshop Proceed‐
50 ings (December 1993), Springer-Verlag, 1994, pp. 191-204.
51 Chacha20:
53 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
54 Chacha20_poly1305:
56 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
57 Modes:
59 ECB, CBC, CFB, OFB and CTR:
62 Recommendation for Block Cipher Modes of Operation: Methods and
63 Techniques [NIST SP 800-38A]
64 GCM:
66 Recommendation for Block Cipher Modes of Operation: Ga‐
67 lois/Counter Mode (GCM) and GMAC [NIST SP 800-38D]
68 CCM:
70 Recommendation for Block Cipher Modes of Operation: The CCM Mode
71 for Authentication and Confidentiality [NIST SP 800-38C]
72 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 ({en‐
129 crypt,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 EVP_CI‐
143 PHER_CTX_set_padding() in cryptolib for your linked version.
144 otp_padding() = zero | random
146 Erlang/OTP adds a either padding of zeroes or padding with ran‐
148 dom bytes.
149 Ciphers, old API
151 block_cipher_with_iv() =
152 cbc_cipher() | cfb_cipher() | blowfish_ofb64 | aes_ige256
153 block_cipher_without_iv() = ecb_cipher()
155 stream_cipher() = ctr_cipher() | chacha20 | rc4
157 aead_cipher() = aes_gcm | aes_ccm | chacha20_poly1305
159 cbc_cipher() =
161 aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
162 des_cbc | des_ede3_cbc | rc2_cbc |
163 retired_cbc_cipher_aliases()
164 cfb_cipher() =
166 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
167 aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 | blowfish_cfb64 |
168 des_cfb | des_ede3_cfb |
169 retired_cfb_cipher_aliases()
170 ctr_cipher() =
172 aes_128_ctr | aes_192_ctr | aes_256_ctr |
173 retired_ctr_cipher_aliases()
174 ecb_cipher() =
176 aes_128_ecb | aes_192_ecb | aes_256_ecb | blowfish_ecb |
177 retired_ecb_cipher_aliases()
178 Ciphers known by the CRYPTO application when using the old API.
180 Note that this list might be reduced if the underlying libcrypto
182 does not support all of them.
183 retired_cbc_cipher_aliases() =
185 aes_cbc | aes_cbc128 | aes_cbc256 | des3_cbc | des_ede3
186 retired_cfb_cipher_aliases() =
188 aes_cfb8 | aes_cfb128 | des3_cbf | des3_cfb | des_ede3_cbf
189 retired_ctr_cipher_aliases() = aes_ctr
191 retired_ecb_cipher_aliases() = aes_ecb
193 Alternative, old names of ciphers known by the CRYPTO applica‐
195 tion when using the old API. See Retired cipher names for names
196 to use instead to be prepared for an easy convertion to the new
197 API.
198 Note that this list might be reduced if the underlying libcrypto
200 does not support all of them.
201 Digests and hash
203 hash_algorithm() =
204 sha1() |
205 sha2() |
206 sha3() |
207 blake2() |
208 ripemd160 |
209 compatibility_only_hash()
210 hmac_hash_algorithm() =
212 sha1() | sha2() | sha3() | compatibility_only_hash()
213 cmac_cipher_algorithm() =
215 aes_128_cbc | aes_192_cbc | aes_256_cbc | blowfish_cbc |
216 des_cbc | des_ede3_cbc | rc2_cbc | aes_128_cfb128 |
217 aes_192_cfb128 | aes_256_cfb128 | aes_128_cfb8 |
218 aes_192_cfb8 | aes_256_cfb8
219 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
221 dss_digest_type() = sha1() | sha2()
223 ecdsa_digest_type() = sha1() | sha2()
225 sha1() = sha
227 sha2() = sha224 | sha256 | sha384 | sha512
229 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
231 blake2() = blake2b | blake2s
233 compatibility_only_hash() = md5 | md4
235 The compatibility_only_hash() algorithms are recommended only
237 for compatibility with existing applications.
238 Elliptic Curves
240 ec_named_curve() =
241 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
242 brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
243 brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
244 brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
245 brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
246 c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
247 c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
248 c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
249 c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
250 prime192v2 | prime192v3 | prime239v1 | prime239v2 |
251 prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
252 secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
253 secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
254 secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
255 sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
256 sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
257 sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
258 wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
259 wtls6 | wtls7 | wtls8 | wtls9
260 edwards_curve_dh() = x25519 | x448
262 edwards_curve_ed() = ed25519 | ed448
264 Note that some curves are disabled if FIPS is enabled.
266 ec_explicit_curve() =
268 {Field :: ec_field(),
269 Curve :: ec_curve(),
270 BasePoint :: binary(),
271 Order :: binary(),
272 CoFactor :: none | binary()}
273 ec_field() = ec_prime_field() | ec_characteristic_two_field()
275 ec_curve() =
277 {A :: binary(), B :: binary(), Seed :: none | binary()}
278 Parametric curve definition.
280 ec_prime_field() = {prime_field, Prime :: integer()}
282 ec_characteristic_two_field() =
284 {characteristic_two_field,
285 M :: integer(),
286 Basis :: ec_basis()}
287 ec_basis() =
289 {tpbasis, K :: integer() >= 0} |
290 {ppbasis,
291 K1 :: integer() >= 0,
292 K2 :: integer() >= 0,
293 K3 :: integer() >= 0} |
294 onbasis
295 Curve definition details.
297 Keys
299 key() = iodata()
300 des3_key() = [key()]
302 For keylengths, iv-sizes and blocksizes see the User's Guide.
304 A key for des3 is a list of three iolists
306 key_integer() = integer() | binary()
308 Always binary() when used as return value
310 Public/Private Keys
312 rsa_public() = [key_integer()]
313 rsa_private() = [key_integer()]
315 rsa_params() =
317 {ModulusSizeInBits :: integer(),
318 PublicExponent :: key_integer()}
319 rsa_public() = [E, N]
321 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
323 Where E is the public exponent, N is public modulus and D is the
325 private exponent. The longer key format contains redundant in‐
326 formation that will make the calculation faster. P1 and P2 are
327 first and second prime factors. E1 and E2 are first and second
328 exponents. C is the CRT coefficient. The terminology is taken
329 from RFC 3447.
330 dss_public() = [key_integer()]
332 dss_private() = [key_integer()]
334 dss_public() = [P, Q, G, Y]
336 Where P, Q and G are the dss parameters and Y is the public key.
338 dss_private() = [P, Q, G, X]
340 Where P, Q and G are the dss parameters and X is the private
342 key.
343 ecdsa_public() = key_integer()
345 ecdsa_private() = key_integer()
347 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
349 eddsa_public() = key_integer()
351 eddsa_private() = key_integer()
353 eddsa_params() = edwards_curve_ed()
355 srp_public() = key_integer()
357 srp_private() = key_integer()
359 srp_public() = key_integer()
361 Where is A or B from SRP design
363 srp_private() = key_integer()
365 Where is a or b from SRP design
367 srp_gen_params() =
369 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
370 srp_comp_params() =
372 {user, srp_user_comp_params()} |
373 {host, srp_host_comp_params()}
374 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
376 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
378 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
380 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
382 Where Verifier is v, Generator is g and Prime is N, DerivedKey
384 is X, and Scrambler is u (optional will be generated if not pro‐
385 vided) from SRP design Version = '3' | '6' | '6a'
386 Public Key Ciphers
388 pk_encrypt_decrypt_algs() = rsa
389 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
391 ported.
392 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
394 rsa_opt() =
396 {rsa_padding, rsa_padding()} |
397 {signature_md, atom()} |
398 {rsa_mgf1_md, sha} |
399 {rsa_oaep_label, binary()} |
400 {rsa_oaep_md, sha}
401 rsa_padding() =
403 rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
404 rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
405 Options for public key encrypt/decrypt. Only RSA is supported.
407 Warning:
409 The RSA options are experimental.
411 The exact set of options and there syntax may be changed without
413 prior notice.
414 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
417 Those option forms are kept only for compatibility and should
419 not be used in new code.
420 Public Key Sign and Verify
422 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
423 Algorithms for sign and verify.
425 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
427 rsa_sign_verify_opt() =
429 {rsa_padding, rsa_sign_verify_padding()} |
430 {rsa_pss_saltlen, integer()} |
431 {rsa_mgf1_md, sha2()}
432 rsa_sign_verify_padding() =
434 rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
435 rsa_no_padding
436 Options for sign and verify.
438 Warning:
440 The RSA options are experimental.
442 The exact set of options and there syntax may be changed without
444 prior notice.
445 Diffie-Hellman Keys and parameters
448 dh_public() = key_integer()
449 dh_private() = key_integer()
451 dh_params() = [key_integer()]
453 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
455 ecdh_public() = key_integer()
457 ecdh_private() = key_integer()
459 ecdh_params() =
461 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
462 Types for Engines
464 engine_key_ref() =
465 #{engine := engine_ref(),
466 key_id := key_id(),
467 password => password(),
468 term() => term()}
469 engine_ref() = term()
471 The result of a call to engine_load/3.
473 key_id() = string() | binary()
475 Identifies the key to be used. The format depends on the loaded
477 engine. It is passed to the ENGINE_load_(private|public)_key
478 functions in libcrypto.
479 password() = string() | binary()
481 The password of the key stored in an engine.
483 engine_method_type() =
485 engine_method_rsa | engine_method_dsa | engine_method_dh |
486 engine_method_rand | engine_method_ecdh |
487 engine_method_ecdsa | engine_method_ciphers |
488 engine_method_digests | engine_method_store |
489 engine_method_pkey_meths | engine_method_pkey_asn1_meths |
490 engine_method_ec
491 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
493 Pre and Post commands for engine_load/3 and /4.
495 Internal data types
497 crypto_state()
498 hash_state()
500 hmac_state()
502 mac_state()
504 stream_state()
506 Contexts with an internal state that should not be manipulated
508 but passed between function calls.
509 Error types
511 run_time_error() = any()
512 The exception error:badarg signifies that one or more arguments
514 are of wrong data type, or are otherwise badly formed.
515 The exception error:notsup signifies that the algorithm is known
517 but is not supported by current underlying libcrypto or explic‐
518 itly disabled when building that.
519 For a list of supported algorithms, see supports/0.
521 descriptive_error() = any()
523 This is a more developed variant of the older run_time_error().
525 The exception is:
527 {Tag, {C_FileName,LineNumber}, Description}
529 Tag = badarg | notsup | error
531 C_FileName = string()
532 LineNumber = integer()
533 Description = string()
534 It is like the older type an exception of the error class. In
537 addition they contain a descriptive text in English. That text
538 is targeted to a developer. Examples are "Bad key size" or "Ci‐
539 pher id is not an atom".
540 The exception tags are:
542 badarg:
544 Signifies that one or more arguments are of wrong data type
545 or are otherwise badly formed.
546 notsup:
548 Signifies that the algorithm is known but is not supported
549 by current underlying libcrypto or explicitly disabled when
550 building that one.
551 error:
553 An error condition that should not occur, for example a mem‐
554 ory allocation failed or the underlying cryptolib returned
555 an error code, for example "Can't initialize context, step
556 1". Those text usually needs searching the C-code to be un‐
557 derstood.
558 To catch the exception, use for example:
560 try crypto:crypto_init(Ciph, Key, IV, true)
562 catch
563 error:{Tag, {C_FileName,LineNumber}, Description} ->
564 do_something(......)
565 .....
566 end
567
571 crypto_init(Cipher, Key, FlagOrOptions) ->
572 State | descriptive_error()
573 Types:
575 Cipher = cipher_no_iv()
577 Key = iodata()
578 FlagOrOptions = crypto_opts() | boolean()
579 State = crypto_state()
580 Part of the new API.
582 Equivalent to the call crypto_init(Cipher, Key, <<>>, FlagOrOp‐
584 tions). It is intended for ciphers without an IV (nounce).
585 crypto_init(Cipher, Key, IV, FlagOrOptions) ->
587 State | descriptive_error()
588 Types:
590 Cipher = cipher_iv()
592 Key = IV = iodata()
593 FlagOrOptions = crypto_opts()
594 State = crypto_state()
595 Part of the new API. Initializes a series of encryptions or de‐
597 cryptions and creates an internal state with a reference that is
598 returned.
599 If IV = <<>>, no IV is used. This is intended for ciphers with‐
601 out an IV (nounce). See crypto_init/3.
602 If IV = undefined, the IV must be added by calls to
604 crypto_dyn_iv_update/3. This is intended for cases where the IV
605 (nounce) need to be changed for each encryption and decryption.
606 See crypto_dyn_iv_init/3.
607 The actual encryption or decryption is done by crypto_update/2
609 (or crypto_dyn_iv_update/3 ).
610 For encryption, set the FlagOrOptions to true or [{en‐
612 crypt,true}]. For decryption, set it to false or [{en‐
613 crypt,false}].
614 Padding could be enabled with the option {padding,Padding}. The
616 cryptolib_padding enables pkcs_padding or no padding (none). The
617 paddings zero or random fills the last part of the last block
618 with zeroes or random bytes. If the last block is already full,
619 nothing is added.
620 In decryption, the cryptolib_padding removes such padding, if
622 present. The otp_padding is not removed - it has to be done
623 elsewhere.
624 If padding is {padding,none} or not specifed and the total data
626 from all subsequent crypto_updates does not fill the last block
627 fully, that last data is lost. In case of {padding,none} there
628 will be an error in this case. If padding is not specified, the
629 bytes of the unfilled block is silently discarded.
630 The actual padding is performed by crypto_final/1.
632 For blocksizes call cipher_info/1.
634 See examples in the User's Guide.
636 crypto_update(State, Data) -> Result | descriptive_error()
638 Types:
640 State = crypto_state()
642 Data = iodata()
643 Result = binary()
644 Part of the new API. It does an actual crypto operation on a
646 part of the full text. If the part is less than a number of full
647 blocks, only the full blocks (possibly none) are encrypted or
648 decrypted and the remaining bytes are saved to the next
649 crypto_update operation. The State should be created with
650 crypto_init/3 or crypto_init/4.
651 See examples in the User's Guide.
653 crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) ->
655 State | descriptive_error()
656 Types:
658 Cipher = cipher_iv()
660 Key = iodata()
661 FlagOrOptions = crypto_opts() | boolean()
662 State = crypto_state()
663 Part of the new API.
665 Initializes a series of encryptions or decryptions where the IV
667 is provided later. The actual encryption or decryption is done
668 by crypto_dyn_iv_update/3.
669 The function is equivalent to crypto_init(Cipher, Key, unde‐
671 fined, FlagOrOptions).
672 crypto_final(State) -> FinalResult | descriptive_error()
674 Types:
676 State = crypto_state()
678 FinalResult = binary()
679 Part of the new API.
681 Finalizes a series of encryptions or decryptions and delivers
683 the final bytes of the final block. The data returned from this
684 function may be empty if no padding was enabled in
685 crypto_init/3,4 or crypto_dyn_iv_init/3.
686 crypto_get_data(State) -> Result
688 Types:
690 State = crypto_state()
692 Result = map()
693 Part of the new API.
695 Returns information about the State in the argument. The infor‐
697 mation is the form of a map, which currently contains at least:
698 size:
700 The number of bytes encrypted or decrypted so far.
701 padding_size:
703 After a call to crypto_final/1 it contains the number of
704 bytes padded. Otherwise 0.
705 padding_type:
707 The type of the padding as provided in the call ot
708 crypto_init/3,4.
709 encrypt:
711 Is true if encryption is performed. It is false otherwise.
712 crypto_dyn_iv_update(State, Data, IV) ->
714 Result | descriptive_error()
715 Types:
717 State = crypto_state()
719 Data = IV = iodata()
720 Result = binary()
721 Part of the new API. Do an actual crypto operation on a part of
723 the full text and the IV is supplied for each part. The State
724 should be created with crypto_dyn_iv_init/3.
725 crypto_one_time(Cipher, Key, Data, FlagOrOptions) ->
727 Result | descriptive_error()
728 Types:
730 Cipher = cipher_no_iv()
732 Key = Data = iodata()
733 FlagOrOptions = crypto_opts() | boolean()
734 Result = binary()
735 As crypto_one_time/5 but for ciphers without IVs.
737 crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) ->
739 Result | descriptive_error()
740 Types:
742 Cipher = cipher_iv()
744 Key = IV = Data = iodata()
745 FlagOrOptions = crypto_opts() | boolean()
746 Result = binary()
747 Part of the new API. Do a complete encrypt or decrypt of the
749 full text in the argument Data.
750 For encryption, set the FlagOrOptions to true. For decryption,
752 set it to false. For setting other options, see crypto_init/4.
753 See examples in the User's Guide.
755 crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
757 EncFlag :: true) ->
758 Result | descriptive_error()
759 crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
761 EncFlag) ->
762 Result | descriptive_error()
763 Types:
765 Cipher = cipher_aead()
767 Key = IV = InText = AAD = iodata()
768 TagOrTagLength = EncryptTagLength | DecryptTag
769 EncryptTagLength = integer() >= 0
770 DecryptTag = iodata()
771 EncFlag = boolean()
772 Result = EncryptResult | DecryptResult
773 EncryptResult = {OutCryptoText, OutTag}
774 DecryptResult = OutPlainText | error
775 OutCryptoText = OutTag = OutPlainText = binary()
776 Part of the new API. Do a complete encrypt or decrypt with an
778 AEAD cipher of the full text.
779 For encryption, set the EncryptFlag to true and set the TagOrTa‐
781 gLength to the wanted size (in bytes) of the tag, that is, the
782 tag length. If the default length is wanted, the crypto_aead/6
783 form may be used.
784 For decryption, set the EncryptFlag to false and put the tag to
786 be checked in the argument TagOrTagLength.
787 See examples in the User's Guide.
789 supports(Type) -> Support
791 Types:
793 Type = hashs | ciphers | public_keys | macs | curves |
795 rsa_opts
796 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
797 Hashs =
798 [sha1() |
799 sha2() |
800 sha3() |
801 blake2() |
802 ripemd160 |
803 compatibility_only_hash()]
804 Ciphers = [cipher()]
805 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
806 Macs = [hmac | cmac | poly1305]
807 Curves =
808 [ec_named_curve() | edwards_curve_dh() | ed‐
809 wards_curve_ed()]
810 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
811 Can be used to determine which crypto algorithms that are sup‐
813 ported by the underlying libcrypto library
814 See hash_info/1 and cipher_info/1 for information about the hash
816 and cipher algorithms.
817 mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()
819 Types:
821 Key = Data = iodata()
823 Mac = binary()
824 Short for mac(Type, undefined, Key, Data).
826 mac(Type, SubType, Key, Data) -> Mac | descriptive_error()
828 Types:
830 Type = hmac | cmac | poly1305
832 SubType =
833 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
834 fined
835 Key = Data = iodata()
836 Mac = binary()
837 Computes a MAC (Message Authentication Code) of type Type from
839 Data.
840 SubType depends on the MAC Type:
842 * For hmac it is a hash algorithm, see Algorithm Details in
844 the User's Guide.
845 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
847 tails in the User's Guide.
848 * For poly1305 it should be set to undefined or the mac/2
850 function could be used instead, see Algorithm Details in the
851 User's Guide.
852 Key is the authentication key with a length according to the
854 Type and SubType. The key length could be found with the
855 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
856 poly1305 the key length is 32 bytes. Note that the cryptographic
857 quality of the key is not checked.
858 The Mac result will have a default length depending on the Type
860 and SubType. To set a shorter length, use macN/4 or macN/5 in‐
861 stead. The default length is documented in Algorithm Details in
862 the User's Guide.
863 macN(Type :: poly1305, Key, Data, MacLength) ->
865 Mac | descriptive_error()
866 Types:
868 Key = Data = iodata()
870 Mac = binary()
871 MacLength = integer() >= 1
872 Short for macN(Type, undefined, Key, Data, MacLength).
874 macN(Type, SubType, Key, Data, MacLength) ->
876 Mac | descriptive_error()
877 Types:
879 Type = hmac | cmac | poly1305
881 SubType =
882 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
883 fined
884 Key = Data = iodata()
885 Mac = binary()
886 MacLength = integer() >= 1
887 Computes a MAC (Message Authentication Code) as mac/3 and mac/4
889 but MacLength will limit the size of the resultant Mac to at
890 most MacLength bytes. Note that if MacLength is greater than the
891 actual number of bytes returned from the underlying hash, the
892 returned hash will have that shorter length instead.
893 The max MacLength is documented in Algorithm Details in the
895 User's Guide.
896 mac_init(Type :: poly1305, Key) -> State | descriptive_error()
898 Types:
900 Key = iodata()
902 State = mac_state()
903 Short for mac_init(Type, undefined, Key).
905 mac_init(Type, SubType, Key) -> State | descriptive_error()
907 Types:
909 Type = hmac | cmac | poly1305
911 SubType =
912 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
913 fined
914 Key = iodata()
915 State = mac_state()
916 Initializes the context for streaming MAC operations.
918 Type determines which mac algorithm to use in the MAC operation.
920 SubType depends on the MAC Type:
922 * For hmac it is a hash algorithm, see Algorithm Details in
924 the User's Guide.
925 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
927 tails in the User's Guide.
928 * For poly1305 it should be set to undefined or the mac/2
930 function could be used instead, see Algorithm Details in the
931 User's Guide.
932 Key is the authentication key with a length according to the
934 Type and SubType. The key length could be found with the
935 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
936 poly1305 the key length is 32 bytes. Note that the cryptographic
937 quality of the key is not checked.
938 The returned State should be used in one or more subsequent
940 calls to mac_update/2. The MAC value is finally returned by
941 calling mac_final/1 or mac_finalN/2.
942 See examples in the User's Guide.
944 mac_update(State0, Data) -> State | descriptive_error()
946 Types:
948 Data = iodata()
950 State0 = State = mac_state()
951 Updates the MAC represented by State0 using the given Data which
953 could be of any length.
954 The State0 is the State value originally from a MAC init func‐
956 tion, that is mac_init/2, mac_init/3 or a previous call of
957 mac_update/2. The value State0 is returned unchanged by the
958 function as State.
959 mac_final(State) -> Mac | descriptive_error()
961 Types:
963 State = mac_state()
965 Mac = binary()
966 Finalizes the MAC operation referenced by State. The Mac result
968 will have a default length depending on the Type and SubType in
969 the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
970 instead. The default length is documented in Algorithm Details
971 in the User's Guide.
972 mac_finalN(State, MacLength) -> Mac | descriptive_error()
974 Types:
976 State = mac_state()
978 MacLength = integer() >= 1
979 Mac = binary()
980 Finalizes the MAC operation referenced by State.
982 Mac will be a binary with at most MacLength bytes. Note that if
984 MacLength is greater than the actual number of bytes returned
985 from the underlying hash, the returned hash will have that
986 shorter length instead.
987 The max MacLength is documented in Algorithm Details in the
989 User's Guide.
990
993 bytes_to_integer(Bin :: binary()) -> integer()
994 Convert binary representation, of an integer, to an Erlang inte‐
996 ger.
997 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
999 SharedSecret
1000 Types:
1002 Type = dh | ecdh | eddh | srp
1004 SharedSecret = binary()
1005 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
1006 MyPrivateKey =
1007 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
1008 vate()}
1009 Params = dh_params() | ecdh_params() | srp_comp_params()
1010 Computes the shared secret from the private key and the other
1012 party's public key. See also public_key:compute_key/2
1013 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
1015 Performs bit-wise XOR (exclusive or) on the data supplied.
1017 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
1019 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
1021 Types:
1023 Type = dh | ecdh | eddh | eddsa | rsa | srp
1025 PublicKey =
1026 dh_public() | ecdh_public() | rsa_public() | srp_public()
1027 PrivKeyIn =
1028 undefined |
1029 dh_private() |
1030 ecdh_private() |
1031 rsa_private() |
1032 {srp_public(), srp_private()}
1033 PrivKeyOut =
1034 dh_private() |
1035 ecdh_private() |
1036 rsa_private() |
1037 {srp_public(), srp_private()}
1038 Params =
1039 dh_params() |
1040 ecdh_params() |
1041 eddsa_params() |
1042 rsa_params() |
1043 srp_comp_params()
1044 Generates a public key of type Type. See also public_key:gener‐
1046 ate_key/1. May raise exception:
1047 * error:badarg: an argument is of wrong type or has an illegal
1049 value,
1050 * error:low_entropy: the random generator failed due to lack
1052 of secure "randomness",
1053 * error:computation_failed: the computation fails of another
1055 reason than low_entropy.
1056 Note:
1058 RSA key generation is only available if the runtime was built
1059 with dirty scheduler support. Otherwise, attempting to generate
1060 an RSA key will raise exception error:notsup.
1061 hash(Type, Data) -> Digest
1064 Types:
1066 Type = hash_algorithm()
1068 Data = iodata()
1069 Digest = binary()
1070 Computes a message digest of type Type from Data.
1072 May raise exception error:notsup in case the chosen Type is not
1074 supported by the underlying libcrypto implementation.
1075 hash_init(Type) -> State
1077 Types:
1079 Type = hash_algorithm()
1081 State = hash_state()
1082 Initializes the context for streaming hash operations. Type de‐
1084 termines which digest to use. The returned context should be
1085 used as argument to hash_update.
1086 May raise exception error:notsup in case the chosen Type is not
1088 supported by the underlying libcrypto implementation.
1089 hash_update(State, Data) -> NewState
1091 Types:
1093 State = NewState = hash_state()
1095 Data = iodata()
1096 Updates the digest represented by Context using the given Data.
1098 Context must have been generated using hash_init or a previous
1099 call to this function. Data can be any length. NewContext must
1100 be passed into the next call to hash_update or hash_final.
1101 hash_final(State) -> Digest
1103 Types:
1105 State = hash_state()
1107 Digest = binary()
1108 Finalizes the hash operation referenced by Context returned from
1110 a previous call to hash_update. The size of Digest is determined
1111 by the type of hash function used to generate it.
1112 info_fips() -> not_supported | not_enabled | enabled
1114 Provides information about the FIPS operating status of crypto
1116 and the underlying libcrypto library. If crypto was built with
1117 FIPS support this can be either enabled (when running in FIPS
1118 mode) or not_enabled. For other builds this value is always
1119 not_supported.
1120 See enable_fips_mode/1 about how to enable FIPS mode.
1122 Warning:
1124 In FIPS mode all non-FIPS compliant algorithms are disabled and
1125 raise exception error:notsup. Check supports that in FIPS mode
1126 returns the restricted list of available algorithms.
1127 enable_fips_mode(Enable) -> Result
1130 Types:
1132 Enable = Result = boolean()
1134 Enables (Enable = true) or disables (Enable = false) FIPS mode.
1136 Returns true if the operation was successful or false otherwise.
1137 Note that to enable FIPS mode succesfully, OTP must be built
1139 with the configure option --enable-fips, and the underlying
1140 libcrypto must also support FIPS.
1141 See also info_fips/0.
1143 info_lib() -> [{Name, VerNum, VerStr}]
1145 Types:
1147 Name = binary()
1149 VerNum = integer()
1150 VerStr = binary()
1151 Provides the name and version of the libraries used by crypto.
1153 Name is the name of the library. VerNum is the numeric version
1155 according to the library's own versioning scheme. VerStr con‐
1156 tains a text variant of the version.
1157 > info_lib().
1159 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
1160 Note:
1163 From OTP R16 the numeric version represents the version of the
1164 OpenSSL header files (openssl/opensslv.h) used when crypto was
1165 compiled. The text variant represents the libcrypto library used
1166 at runtime. In earlier OTP versions both numeric and text was
1167 taken from the library.
1168 hash_info(Type) -> Result | run_time_error()
1171 Types:
1173 Type = hash_algorithm()
1175 Result =
1176 #{size := integer(),
1177 block_size := integer(),
1178 type := integer()}
1179 Provides a map with information about block_size, size and pos‐
1181 sibly other properties of the hash algorithm in question.
1182 For a list of supported hash algorithms, see supports/0.
1184 cipher_info(Type) -> Result | run_time_error()
1186 Types:
1188 Type = cipher()
1190 Result =
1191 #{key_length := integer(),
1192 iv_length := integer(),
1193 block_size := integer(),
1194 mode := CipherModes,
1195 type := undefined | integer()}
1196 CipherModes =
1197 undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1198 ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1199 wrap_mode | xts_mode
1200 Provides a map with information about block_size, key_length,
1202 iv_length and possibly other properties of the cipher algorithm
1203 in question.
1204 Note:
1206 The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb,
1207 aes_gcm and aes_ccm has no keylength in the Type as opposed to
1208 for example aes_128_ctr. They adapt to the length of the key
1209 provided in the encrypt and decrypt function. Therefor it is im‐
1210 possible to return a valid keylength in the map.
1211 Always use a Type with an explicit key length,
1213 For a list of supported cipher algorithms, see supports/0.
1216 mod_pow(N, P, M) -> Result
1218 Types:
1220 N = P = M = binary() | integer()
1222 Result = binary() | error
1223 Computes the function N^P mod M.
1225 next_iv(Type :: cbc_cipher(), Data) -> NextIVec
1227 next_iv(Type :: des_cfb, Data, IVec) -> NextIVec
1229 Types:
1231 Data = iodata()
1233 IVec = NextIVec = binary()
1234 Returns the initialization vector to be used in the next itera‐
1236 tion of encrypt/decrypt of type Type. Data is the encrypted data
1237 from the previous iteration step. The IVec argument is only
1238 needed for des_cfb as the vector used in the previous iteration
1239 step.
1240 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1242 PlainText
1243 Types:
1245 Algorithm = pk_encrypt_decrypt_algs()
1247 CipherText = binary()
1248 PrivateKey = rsa_private() | engine_key_ref()
1249 Options = pk_encrypt_decrypt_opts()
1250 PlainText = binary()
1251 Decrypts the CipherText, encrypted with public_encrypt/4 (or
1253 equivalent function) using the PrivateKey, and returns the
1254 plaintext (message digest). This is a low level signature veri‐
1255 fication operation used for instance by older versions of the
1256 SSL protocol. See also public_key:decrypt_private/[2,3]
1257 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1259 CipherText
1260 Types:
1262 Algorithm = pk_encrypt_decrypt_algs()
1264 PlainText = binary()
1265 PrivateKey = rsa_private() | engine_key_ref()
1266 Options = pk_encrypt_decrypt_opts()
1267 CipherText = binary()
1268 Encrypts the PlainText using the PrivateKey and returns the ci‐
1270 phertext. This is a low level signature operation used for in‐
1271 stance by older versions of the SSL protocol. See also pub‐
1272 lic_key:encrypt_private/[2,3]
1273 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1275 PlainText
1276 Types:
1278 Algorithm = pk_encrypt_decrypt_algs()
1280 CipherText = binary()
1281 PublicKey = rsa_public() | engine_key_ref()
1282 Options = pk_encrypt_decrypt_opts()
1283 PlainText = binary()
1284 Decrypts the CipherText, encrypted with private_encrypt/4(or
1286 equivalent function) using the PrivateKey, and returns the
1287 plaintext (message digest). This is a low level signature veri‐
1288 fication operation used for instance by older versions of the
1289 SSL protocol. See also public_key:decrypt_public/[2,3]
1290 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1292 CipherText
1293 Types:
1295 Algorithm = pk_encrypt_decrypt_algs()
1297 PlainText = binary()
1298 PublicKey = rsa_public() | engine_key_ref()
1299 Options = pk_encrypt_decrypt_opts()
1300 CipherText = binary()
1301 Encrypts the PlainText (message digest) using the PublicKey and
1303 returns the CipherText. This is a low level signature operation
1304 used for instance by older versions of the SSL protocol. See
1305 also public_key:encrypt_public/[2,3]
1306 rand_seed(Seed :: binary()) -> ok
1308 Set the seed for PRNG to the given binary. This calls the
1310 RAND_seed function from openssl. Only use this if the system you
1311 are running on does not have enough "randomness" built in. Nor‐
1312 mally this is when strong_rand_bytes/1 raises error:low_entropy
1313 rand_uniform(Lo, Hi) -> N
1315 Types:
1317 Lo, Hi, N = integer()
1319 Generate a random number N, Lo =< N < Hi. Uses the crypto li‐
1321 brary pseudo-random number generator. Hi must be larger than Lo.
1322 start() -> ok | {error, Reason :: term()}
1324 Equivalent to application:start(crypto).
1326 stop() -> ok | {error, Reason :: term()}
1328 Equivalent to application:stop(crypto).
1330 strong_rand_bytes(N :: integer() >= 0) -> binary()
1332 Generates N bytes randomly uniform 0..255, and returns the re‐
1334 sult in a binary. Uses a cryptographically secure prng seeded
1335 and periodically mixed with operating system provided entropy.
1336 By default this is the RAND_bytes method from OpenSSL.
1337 May raise exception error:low_entropy in case the random genera‐
1339 tor failed due to lack of secure "randomness".
1340 rand_seed() -> rand:state()
1342 Creates state object for random number generation, in order to
1344 generate cryptographically strong random numbers (based on
1345 OpenSSL's BN_rand_range), and saves it in the process dictionary
1346 before returning it as well. See also rand:seed/1 and
1347 rand_seed_s/0.
1348 When using the state object from this function the rand func‐
1350 tions using it may raise exception error:low_entropy in case the
1351 random generator failed due to lack of secure "randomness".
1352 Example
1354 _ = crypto:rand_seed(),
1356 _IntegerValue = rand:uniform(42), % [1; 42]
1357 _FloatValue = rand:uniform(). % [0.0; 1.0[
1358 rand_seed_s() -> rand:state()
1360 Creates state object for random number generation, in order to
1362 generate cryptographically strongly random numbers (based on
1363 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1364 When using the state object from this function the rand func‐
1366 tions using it may raise exception error:low_entropy in case the
1367 random generator failed due to lack of secure "randomness".
1368 Note:
1370 The state returned from this function cannot be used to get a
1371 reproducable random sequence as from the other rand functions,
1372 since reproducability does not match cryptographically safe.
1373 The only supported usage is to generate one distinct random se‐
1375 quence from this start state.
1376 rand_seed_alg(Alg) -> rand:state()
1379 Types:
1381 Alg = crypto | crypto_cache
1383 Creates state object for random number generation, in order to
1385 generate cryptographically strong random numbers, and saves it
1386 in the process dictionary before returning it as well. See also
1387 rand:seed/1 and rand_seed_alg_s/1.
1388 When using the state object from this function the rand func‐
1390 tions using it may raise exception error:low_entropy in case the
1391 random generator failed due to lack of secure "randomness".
1392 Example
1394 _ = crypto:rand_seed_alg(crypto_cache),
1396 _IntegerValue = rand:uniform(42), % [1; 42]
1397 _FloatValue = rand:uniform(). % [0.0; 1.0[
1398 rand_seed_alg(Alg, Seed) -> rand:state()
1400 Types:
1402 Alg = crypto_aes
1404 Creates a state object for random number generation, in order to
1406 generate cryptographically unpredictable random numbers, and
1407 saves it in the process dictionary before returning it as well.
1408 See also rand_seed_alg_s/2.
1409 Example
1411 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1413 IntegerValue = rand:uniform(42), % [1; 42]
1414 FloatValue = rand:uniform(), % [0.0; 1.0[
1415 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1416 IntegerValue = rand:uniform(42), % Same values
1417 FloatValue = rand:uniform(). % again
1418 rand_seed_alg_s(Alg) -> rand:state()
1421 Types:
1423 Alg = crypto | crypto_cache
1425 Creates state object for random number generation, in order to
1427 generate cryptographically strongly random numbers. See also
1428 rand:seed_s/1.
1429 If Alg is crypto this function behaves exactly like
1431 rand_seed_s/0.
1432 If Alg is crypto_cache this function fetches random data with
1434 OpenSSL's RAND_bytes and caches it for speed using an internal
1435 word size of 56 bits that makes calculations fast on 64 bit ma‐
1436 chines.
1437 When using the state object from this function the rand func‐
1439 tions using it may raise exception error:low_entropy in case the
1440 random generator failed due to lack of secure "randomness".
1441 The cache size can be changed from its default value using the
1443 crypto app's configuration parameter rand_cache_size.
1444 When using the state object from this function the rand func‐
1446 tions using it may throw exception low_entropy in case the ran‐
1447 dom generator failed due to lack of secure "randomness".
1448 Note:
1450 The state returned from this function cannot be used to get a
1451 reproducable random sequence as from the other rand functions,
1452 since reproducability does not match cryptographically safe.
1453 In fact since random data is cached some numbers may get repro‐
1455 duced if you try, but this is unpredictable.
1456 The only supported usage is to generate one distinct random se‐
1458 quence from this start state.
1459 rand_seed_alg_s(Alg, Seed) -> rand:state()
1462 Types:
1464 Alg = crypto_aes
1466 Creates a state object for random number generation, in order to
1468 generate cryptographically unpredictable random numbers. See
1469 also rand_seed_alg/1.
1470 To get a long period the Xoroshiro928 generator from the rand
1472 module is used as a counter (with period 2^928 - 1) and the gen‐
1473 erator states are scrambled through AES to create 58-bit pseudo
1474 random values.
1475 The result should be statistically completely unpredictable ran‐
1477 dom values, since the scrambling is cryptographically strong and
1478 the period is ridiculously long. But the generated numbers are
1479 not to be regarded as cryptographically strong since there is no
1480 re-keying schedule.
1481 * If you need cryptographically strong random numbers use
1483 rand_seed_alg_s/1 with Alg =:= crypto or Alg =:=
1484 crypto_cache.
1485 * If you need to be able to repeat the sequence use this func‐
1487 tion.
1488 * If you do not need the statistical quality of this function,
1490 there are faster algorithms in the rand module.
1491 Thanks to the used generator the state object supports the
1493 rand:jump/0,1 function with distance 2^512.
1494 Numbers are generated in batches and cached for speed reasons.
1496 The cache size can be changed from its default value using the
1497 crypto app's configuration parameter rand_cache_size.
1498 ec_curves() -> [EllipticCurve]
1500 Types:
1502 EllipticCurve =
1504 ec_named_curve() | edwards_curve_dh() | ed‐
1505 wards_curve_ed()
1506 Can be used to determine which named elliptic curves are sup‐
1508 ported.
1509 ec_curve(CurveName) -> ExplicitCurve
1511 Types:
1513 CurveName = ec_named_curve()
1515 ExplicitCurve = ec_explicit_curve()
1516 Return the defining parameters of a elliptic curve.
1518 sign(Algorithm, DigestType, Msg, Key) -> Signature
1520 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1522 Types:
1524 Algorithm = pk_sign_verify_algs()
1526 DigestType =
1527 rsa_digest_type() |
1528 dss_digest_type() |
1529 ecdsa_digest_type() |
1530 none
1531 Msg = iodata() | {digest, iodata()}
1532 Key =
1533 rsa_private() |
1534 dss_private() |
1535 [ecdsa_private() | ecdsa_params()] |
1536 [eddsa_private() | eddsa_params()] |
1537 engine_key_ref()
1538 Options = pk_sign_verify_opts()
1539 Signature = binary()
1540 Creates a digital signature.
1542 The msg is either the binary "cleartext" data to be signed or it
1544 is the hashed value of "cleartext" i.e. the digest (plaintext).
1545 Algorithm dss can only be used together with digest type sha.
1547 See also public_key:sign/3.
1549 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1551 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1553 Result
1554 Types:
1556 Algorithm = pk_sign_verify_algs()
1558 DigestType =
1559 rsa_digest_type() | dss_digest_type() | ecdsa_di‐
1560 gest_type()
1561 Msg = iodata() | {digest, iodata()}
1562 Signature = binary()
1563 Key =
1564 rsa_public() |
1565 dss_public() |
1566 [ecdsa_public() | ecdsa_params()] |
1567 [eddsa_public() | eddsa_params()] |
1568 engine_key_ref()
1569 Options = pk_sign_verify_opts()
1570 Result = boolean()
1571 Verifies a digital signature
1573 The msg is either the binary "cleartext" data to be signed or it
1575 is the hashed value of "cleartext" i.e. the digest (plaintext).
1576 Algorithm dss can only be used together with digest type sha.
1578 See also public_key:verify/4.
1580
1583 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1584 Types:
1586 Type = rsa | dss
1588 EnginePrivateKeyRef = engine_key_ref()
1589 PublicKey = rsa_public() | dss_public()
1590 Fetches the corresponding public key from a private key stored
1592 in an Engine. The key must be of the type indicated by the Type
1593 parameter.
1594 engine_get_all_methods() -> Result
1596 Types:
1598 Result = [engine_method_type()]
1600 Returns a list of all possible engine methods.
1602 May raise exception error:notsup in case there is no engine sup‐
1604 port in the underlying OpenSSL implementation.
1605 See also the chapter Engine Load in the User's Guide.
1607 engine_load(EngineId, PreCmds, PostCmds) -> Result
1609 Types:
1611 EngineId = unicode:chardata()
1613 PreCmds = PostCmds = [engine_cmnd()]
1614 Result =
1615 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1616 Loads the OpenSSL engine given by EngineId if it is available
1618 and then returns ok and an engine handle. This function is the
1619 same as calling engine_load/4 with EngineMethods set to a list
1620 of all the possible methods. An error tuple is returned if the
1621 engine can't be loaded.
1622 The function raises a error:badarg if the parameters are in
1624 wrong format. It may also raise the exception error:notsup in
1625 case there is no engine support in the underlying OpenSSL imple‐
1626 mentation.
1627 See also the chapter Engine Load in the User's Guide.
1629 engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
1631 Types:
1633 EngineId = unicode:chardata()
1635 PreCmds = PostCmds = [engine_cmnd()]
1636 EngineMethods = [engine_method_type()]
1637 Result =
1638 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1639 Loads the OpenSSL engine given by EngineId if it is available
1641 and then returns ok and an engine handle. An error tuple is re‐
1642 turned if the engine can't be loaded.
1643 The function raises a error:badarg if the parameters are in
1645 wrong format. It may also raise the exception error:notsup in
1646 case there is no engine support in the underlying OpenSSL imple‐
1647 mentation.
1648 See also the chapter Engine Load in the User's Guide.
1650 engine_unload(Engine) -> Result
1652 Types:
1654 Engine = engine_ref()
1656 Result = ok | {error, Reason :: term()}
1657 Unloads the OpenSSL engine given by Engine. An error tuple is
1659 returned if the engine can't be unloaded.
1660 The function raises a error:badarg if the parameter is in wrong
1662 format. It may also raise the exception error:notsup in case
1663 there is no engine support in the underlying OpenSSL implementa‐
1664 tion.
1665 See also the chapter Engine Load in the User's Guide.
1667 engine_by_id(EngineId) -> Result
1669 Types:
1671 EngineId = unicode:chardata()
1673 Result =
1674 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1675 Get a reference to an already loaded engine with EngineId. An
1677 error tuple is returned if the engine can't be unloaded.
1678 The function raises a error:badarg if the parameter is in wrong
1680 format. It may also raise the exception error:notsup in case
1681 there is no engine support in the underlying OpenSSL implementa‐
1682 tion.
1683 See also the chapter Engine Load in the User's Guide.
1685 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1687 Types:
1689 Engine = term()
1691 CmdName = CmdArg = unicode:chardata()
1692 Result = ok | {error, Reason :: term()}
1693 Sends ctrl commands to the OpenSSL engine given by Engine. This
1695 function is the same as calling engine_ctrl_cmd_string/4 with
1696 Optional set to false.
1697 The function raises a error:badarg if the parameters are in
1699 wrong format. It may also raise the exception error:notsup in
1700 case there is no engine support in the underlying OpenSSL imple‐
1701 mentation.
1702 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1704 Result
1705 Types:
1707 Engine = term()
1709 CmdName = CmdArg = unicode:chardata()
1710 Optional = boolean()
1711 Result = ok | {error, Reason :: term()}
1712 Sends ctrl commands to the OpenSSL engine given by Engine. Op‐
1714 tional is a boolean argument that can relax the semantics of the
1715 function. If set to true it will only return failure if the EN‐
1716 GINE supported the given command name but failed while executing
1717 it, if the ENGINE doesn't support the command name it will sim‐
1718 ply return success without doing anything. In this case we as‐
1719 sume the user is only supplying commands specific to the given
1720 ENGINE so we set this to false.
1721 The function raises a error:badarg if the parameters are in
1723 wrong format. It may also raise the exception error:notsup in
1724 case there is no engine support in the underlying OpenSSL imple‐
1725 mentation.
1726 engine_add(Engine) -> Result
1728 Types:
1730 Engine = engine_ref()
1732 Result = ok | {error, Reason :: term()}
1733 Add the engine to OpenSSL's internal list.
1735 The function raises a error:badarg if the parameters are in
1737 wrong format. It may also raise the exception error:notsup in
1738 case there is no engine support in the underlying OpenSSL imple‐
1739 mentation.
1740 engine_remove(Engine) -> Result
1742 Types:
1744 Engine = engine_ref()
1746 Result = ok | {error, Reason :: term()}
1747 Remove the engine from OpenSSL's internal list.
1749 The function raises a error:badarg if the parameters are in
1751 wrong format. It may also raise the exception error:notsup in
1752 case there is no engine support in the underlying OpenSSL imple‐
1753 mentation.
1754 engine_get_id(Engine) -> EngineId
1756 Types:
1758 Engine = engine_ref()
1760 EngineId = unicode:chardata()
1761 Return the ID for the engine, or an empty binary if there is no
1763 id set.
1764 The function raises a error:badarg if the parameters are in
1766 wrong format. It may also raise the exception error:notsup in
1767 case there is no engine support in the underlying OpenSSL imple‐
1768 mentation.
1769 engine_get_name(Engine) -> EngineName
1771 Types:
1773 Engine = engine_ref()
1775 EngineName = unicode:chardata()
1776 Return the name (eg a description) for the engine, or an empty
1778 binary if there is no name set.
1779 The function raises a error:badarg if the parameters are in
1781 wrong format. It may also raise the exception error:notsup in
1782 case there is no engine support in the underlying OpenSSL imple‐
1783 mentation.
1784 engine_list() -> Result
1786 Types:
1788 Result = [EngineId :: unicode:chardata()]
1790 List the id's of all engines in OpenSSL's internal list.
1792 It may also raise the exception error:notsup in case there is no
1794 engine support in the underlying OpenSSL implementation.
1795 See also the chapter Engine Load in the User's Guide.
1797 May raise exception error:notsup in case engine functionality is
1799 not supported by the underlying OpenSSL implementation.
1800 ensure_engine_loaded(EngineId, LibPath) -> Result
1802 Types:
1804 EngineId = LibPath = unicode:chardata()
1806 Result =
1807 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1808 Loads the OpenSSL engine given by EngineId and the path to the
1810 dynamic library implementing the engine. This function is the
1811 same as calling ensure_engine_loaded/3 with EngineMethods set to
1812 a list of all the possible methods. An error tuple is returned
1813 if the engine can't be loaded.
1814 The function raises a error:badarg if the parameters are in
1816 wrong format. It may also raise the exception error:notsup in
1817 case there is no engine support in the underlying OpenSSL imple‐
1818 mentation.
1819 See also the chapter Engine Load in the User's Guide.
1821 ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
1823 Types:
1825 EngineId = LibPath = unicode:chardata()
1827 EngineMethods = [engine_method_type()]
1828 Result =
1829 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1830 Loads the OpenSSL engine given by EngineId and the path to the
1832 dynamic library implementing the engine. This function differs
1833 from the normal engine_load in that sense it also add the engine
1834 id to the internal list in OpenSSL. Then in the following calls
1835 to the function it just fetch the reference to the engine in‐
1836 stead of loading it again. An error tuple is returned if the en‐
1837 gine can't be loaded.
1838 The function raises a error:badarg if the parameters are in
1840 wrong format. It may also raise the exception error:notsup in
1841 case there is no engine support in the underlying OpenSSL imple‐
1842 mentation.
1843 See also the chapter Engine Load in the User's Guide.
1845 ensure_engine_unloaded(Engine) -> Result
1847 Types:
1849 Engine = engine_ref()
1851 Result = ok | {error, Reason :: term()}
1852 Unloads an engine loaded with the ensure_engine_loaded function.
1854 It both removes the label from the OpenSSL internal engine list
1855 and unloads the engine. This function is the same as calling en‐
1856 sure_engine_unloaded/2 with EngineMethods set to a list of all
1857 the possible methods. An error tuple is returned if the engine
1858 can't be unloaded.
1859 The function raises a error:badarg if the parameters are in
1861 wrong format. It may also raise the exception error:notsup in
1862 case there is no engine support in the underlying OpenSSL imple‐
1863 mentation.
1864 See also the chapter Engine Load in the User's Guide.
1866 ensure_engine_unloaded(Engine, EngineMethods) -> Result
1868 Types:
1870 Engine = engine_ref()
1872 EngineMethods = [engine_method_type()]
1873 Result = ok | {error, Reason :: term()}
1874 Unloads an engine loaded with the ensure_engine_loaded function.
1876 It both removes the label from the OpenSSL internal engine list
1877 and unloads the engine. An error tuple is returned if the engine
1878 can't be unloaded.
1879 The function raises a error:badarg if the parameters are in
1881 wrong format. It may also raise the exception error:notsup in
1882 case there is no engine support in the underlying OpenSSL imple‐
1883 mentation.
1884 See also the chapter Engine Load in the User's Guide.
1886
1889 block_encrypt(Type :: block_cipher_without_iv(),
1890 Key :: key(),
1891 PlainText :: iodata()) ->
1892 binary() | run_time_error()
1893 Dont:
1895 Don't use this function for new programs! Use the-new-api.
1896 Encrypt PlainText according to Type block cipher.
1899 May raise exception error:notsup in case the chosen Type is not
1901 supported by the underlying libcrypto implementation.
1902 For keylengths and blocksizes see the User's Guide.
1904 block_decrypt(Type :: block_cipher_without_iv(),
1906 Key :: key(),
1907 Data :: iodata()) ->
1908 binary() | run_time_error()
1909 Dont:
1911 Don't use this function for new programs! Use the new api.
1912 Decrypt CipherText according to Type block cipher.
1915 May raise exception error:notsup in case the chosen Type is not
1917 supported by the underlying libcrypto implementation.
1918 For keylengths and blocksizes see the User's Guide.
1920 block_encrypt(Type, Key, Ivec, PlainText) -> CipherText | Error
1922 block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText,
1923 CipherTag} | Error
1924 block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText,
1925 TagLength}) -> {CipherText, CipherTag} | Error
1926 Types:
1928 Type = block_cipher_with_iv()
1930 AeadType = aead_cipher()
1931 Key = key() | des3_key()
1932 PlainText = iodata()
1933 AAD = IVec = CipherText = CipherTag = binary()
1934 TagLength = 1..16
1935 Error = run_time_error()
1936 Dont:
1938 Don't use this function for new programs! Use the new api.
1939 Encrypt PlainText according to Type block cipher. IVec is an ar‐
1942 bitrary initializing vector.
1943 In AEAD (Authenticated Encryption with Associated Data) mode,
1945 encrypt PlainTextaccording to Type block cipher and calculate
1946 CipherTag that also authenticates the AAD (Associated Authenti‐
1947 cated Data).
1948 May raise exception error:notsup in case the chosen Type is not
1950 supported by the underlying libcrypto implementation.
1951 For keylengths, iv-sizes and blocksizes see the User's Guide.
1953 block_decrypt(Type, Key, Ivec, CipherText) -> PlainText | Error
1955 block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) ->
1956 PlainText | Error
1957 Types:
1959 Type = block_cipher_with_iv()
1961 AeadType = aead_cipher()
1962 Key = key() | des3_key()
1963 PlainText = iodata()
1964 AAD = IVec = CipherText = CipherTag = binary()
1965 Error = BadTag | run_time_error()
1966 BadTag = error
1967 Dont:
1969 Don't use this function for new programs! Use the new api.
1970 Decrypt CipherText according to Type block cipher. IVec is an
1973 arbitrary initializing vector.
1974 In AEAD (Authenticated Encryption with Associated Data) mode,
1976 decrypt CipherTextaccording to Type block cipher and check the
1977 authenticity the PlainText and AAD (Associated Authenticated
1978 Data) using the CipherTag. May return error if the decryption or
1979 validation fail's
1980 May raise exception error:notsup in case the chosen Type is not
1982 supported by the underlying libcrypto implementation.
1983 For keylengths, iv-sizes and blocksizes see the User's Guide.
1985 stream_init(Type, Key) -> State | run_time_error()
1987 Types:
1989 Type = rc4
1991 Key = iodata()
1992 State = stream_state()
1993 Dont:
1995 Don't use this function for new programs! Use the new api.
1996 Initializes the state for use in RC4 stream encryption
1999 stream_encrypt and stream_decrypt
2000 For keylengths see the User's Guide.
2002 stream_init(Type, Key, IVec) -> State | run_time_error()
2004 Types:
2006 Type = stream_cipher()
2008 Key = iodata()
2009 IVec = binary()
2010 State = stream_state()
2011 Dont:
2013 Don't use this function for new programs! Use the new api.
2014 Initializes the state for use in streaming AES encryption using
2017 Counter mode (CTR). Key is the AES key and must be either 128,
2018 192, or 256 bits long. IVec is an arbitrary initializing vector
2019 of 128 bits (16 bytes). This state is for use with stream_en‐
2020 crypt and stream_decrypt.
2021 For keylengths and iv-sizes see the User's Guide.
2023 stream_encrypt(State, PlainText) ->
2025 {NewState, CipherText} | run_time_error()
2026 Types:
2028 State = stream_state()
2030 PlainText = iodata()
2031 NewState = stream_state()
2032 CipherText = iodata()
2033 Dont:
2035 Don't use this function for new programs! Use the new api.
2036 Encrypts PlainText according to the stream cipher Type specified
2039 in stream_init/3. Text can be any number of bytes. The initial
2040 State is created using stream_init. NewState must be passed into
2041 the next call to stream_encrypt.
2042 stream_decrypt(State, CipherText) ->
2044 {NewState, PlainText} | run_time_error()
2045 Types:
2047 State = stream_state()
2049 CipherText = iodata()
2050 NewState = stream_state()
2051 PlainText = iodata()
2052 Dont:
2054 Don't use this function for new programs! Use the new api.
2055 Decrypts CipherText according to the stream cipher Type speci‐
2058 fied in stream_init/3. PlainText can be any number of bytes. The
2059 initial State is created using stream_init. NewState must be
2060 passed into the next call to stream_decrypt.
2061 supports() -> [Support]
2063 Types:
2065 Support =
2067 {hashs, Hashs} |
2068 {ciphers, Ciphers} |
2069 {public_keys, PKs} |
2070 {macs, Macs} |
2071 {curves, Curves} |
2072 {rsa_opts, RSAopts}
2073 Hashs =
2074 [sha1() |
2075 sha2() |
2076 sha3() |
2077 blake2() |
2078 ripemd160 |
2079 compatibility_only_hash()]
2080 Ciphers = [cipher()]
2081 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
2082 Macs = [hmac | cmac | poly1305]
2083 Curves =
2084 [ec_named_curve() | edwards_curve_dh() | ed‐
2085 wards_curve_ed()]
2086 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
2087 Dont:
2089 Don't use this function for new programs! Use supports/1 in the
2090 new api.
2091 Can be used to determine which crypto algorithms that are sup‐
2094 ported by the underlying libcrypto library
2095 See hash_info/1 and cipher_info/1 for information about the hash
2097 and cipher algorithms.
2098 hmac(Type, Key, Data) -> Mac
2100 hmac(Type, Key, Data, MacLength) -> Mac
2102 Types:
2104 Type = hmac_hash_algorithm()
2106 Key = Data = iodata()
2107 MacLength = integer()
2108 Mac = binary()
2109 Dont:
2111 Don't use this function for new programs! Use mac/4 or macN/5 in
2112 the new api.
2113 Computes a HMAC of type Type from Data using Key as the authen‐
2116 tication key.
2117 MacLength will limit the size of the resultant Mac.
2119 hmac_init(Type, Key) -> State
2121 Types:
2123 Type = hmac_hash_algorithm()
2125 Key = iodata()
2126 State = hmac_state()
2127 Dont:
2129 Don't use this function for new programs! Use mac_init/3 in the
2130 new api.
2131 Initializes the context for streaming HMAC operations. Type de‐
2134 termines which hash function to use in the HMAC operation. Key
2135 is the authentication key. The key can be any length.
2136 hmac_update(State, Data) -> NewState
2138 Types:
2140 Data = iodata()
2142 State = NewState = hmac_state()
2143 Dont:
2145 Don't use this function for new programs! Use mac_update/2 in
2146 the new api.
2147 Updates the HMAC represented by Context using the given Data.
2150 Context must have been generated using an HMAC init function
2151 (such as hmac_init). Data can be any length. NewContext must be
2152 passed into the next call to hmac_update or to one of the func‐
2153 tions hmac_final and hmac_final_n
2154 Warning:
2156 Do not use a Context as argument in more than one call to
2157 hmac_update or hmac_final. The semantics of reusing old contexts
2158 in any way is undefined and could even crash the VM in earlier
2159 releases. The reason for this limitation is a lack of support in
2160 the underlying libcrypto API.
2161 hmac_final(State) -> Mac
2164 Types:
2166 State = hmac_state()
2168 Mac = binary()
2169 Dont:
2171 Don't use this function for new programs! Use mac_final/1 in the
2172 new api.
2173 Finalizes the HMAC operation referenced by Context. The size of
2176 the resultant MAC is determined by the type of hash function
2177 used to generate it.
2178 hmac_final_n(State, HashLen) -> Mac
2180 Types:
2182 State = hmac_state()
2184 HashLen = integer()
2185 Mac = binary()
2186 Dont:
2188 Don't use this function for new programs! Use mac_finalN/2 in
2189 the new api.
2190 Finalizes the HMAC operation referenced by Context. HashLen must
2193 be greater than zero. Mac will be a binary with at most HashLen
2194 bytes. Note that if HashLen is greater than the actual number of
2195 bytes returned from the underlying hash, the returned hash will
2196 have fewer than HashLen bytes.
2197 cmac(Type, Key, Data) -> Mac
2199 cmac(Type, Key, Data, MacLength) -> Mac
2201 Types:
2203 Type =
2205 cbc_cipher() |
2206 cfb_cipher() |
2207 blowfish_cbc | des_ede3 | rc2_cbc
2208 Key = Data = iodata()
2209 MacLength = integer()
2210 Mac = binary()
2211 Dont:
2213 Don't use this function for new programs! Use mac/4 or macN/5 in
2214 the new api.
2215 Computes a CMAC of type Type from Data using Key as the authen‐
2218 tication key.
2219 MacLength will limit the size of the resultant Mac.
2221 poly1305(Key :: iodata(), Data :: iodata()) -> Mac
2223 Types:
2225 Mac = binary()
2227 Dont:
2229 Don't use this function for new programs! Use mac/3 or macN/4 in
2230 the new api.
2231 Computes a POLY1305 message authentication code (Mac) from Data
2234 using Key as the authentication key.
2235Ericsson AB crypto 4.9.0.2 crypto(3)