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
101 cipher() = cipher_no_iv() | cipher_iv() | cipher_aead()
102 cipher_no_iv() =
104 aes_128_ecb | aes_192_ecb | aes_256_ecb | aes_ecb |
105 blowfish_ecb | des_ecb | rc4
106 cipher_iv() =
108 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
109 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
110 aes_cfb128 | aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 |
111 aes_cfb8 | aes_128_ctr | aes_192_ctr | aes_256_ctr | aes_ctr |
112 blowfish_cbc | blowfish_cfb64 | blowfish_ofb64 | chacha20 |
113 des_ede3_cbc | des_ede3_cfb | des_cbc | des_cfb | rc2_cbc
114 cipher_aead() =
116 aes_128_ccm | aes_192_ccm | aes_256_ccm | aes_ccm |
117 aes_128_gcm | aes_192_gcm | aes_256_gcm | aes_gcm |
118 chacha20_poly1305
119 Ciphers known by the CRYPTO application.
121 Note that this list might be reduced if the underlying libcrypto
123 does not support all of them.
124 crypto_opts() = boolean() | [crypto_opt()]
126 crypto_opt() = {encrypt, boolean()} | {padding, padding()}
128 Selects encryption ({encrypt,true}) or decryption ({en‐
130 crypt,false}).
131 padding() = cryptolib_padding() | otp_padding()
133 This option handles padding in the last block. If not set, no
135 padding is done and any bytes in the last unfilled block is
136 silently discarded.
137 cryptolib_padding() = none | pkcs_padding
139 The cryptolib_padding are paddings that may be present in the
141 underlying cryptolib linked to the Erlang/OTP crypto app.
142 For OpenSSL, see the OpenSSL documentation. and find EVP_CI‐
144 PHER_CTX_set_padding() in cryptolib for your linked version.
145 otp_padding() = zero | random
147 Erlang/OTP adds a either padding of zeroes or padding with ran‐
149 dom bytes.
150 Digests and hash
152 hash_algorithm() =
153 sha1() |
154 sha2() |
155 sha3() |
156 blake2() |
157 ripemd160 |
158 compatibility_only_hash()
159 hmac_hash_algorithm() =
161 sha1() | sha2() | sha3() | compatibility_only_hash()
162 cmac_cipher_algorithm() =
164 aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
165 aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
166 aes_cfb128 | aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 |
167 aes_cfb8 | blowfish_cbc | des_cbc | des_ede3_cbc | rc2_cbc
168 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
170 dss_digest_type() = sha1() | sha2()
172 ecdsa_digest_type() = sha1() | sha2()
174 sha1() = sha
176 sha2() = sha224 | sha256 | sha384 | sha512
178 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
180 blake2() = blake2b | blake2s
182 compatibility_only_hash() = md5 | md4
184 The compatibility_only_hash() algorithms are recommended only
186 for compatibility with existing applications.
187 Elliptic Curves
189 ec_named_curve() =
190 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
191 brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
192 brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
193 brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
194 brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
195 c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
196 c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
197 c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
198 c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
199 prime192v2 | prime192v3 | prime239v1 | prime239v2 |
200 prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
201 secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
202 secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
203 secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
204 sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
205 sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
206 sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
207 wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
208 wtls6 | wtls7 | wtls8 | wtls9
209 edwards_curve_dh() = x25519 | x448
211 edwards_curve_ed() = ed25519 | ed448
213 Note that some curves are disabled if FIPS is enabled.
215 ec_explicit_curve() =
217 {Field :: ec_field(),
218 Curve :: ec_curve(),
219 BasePoint :: binary(),
220 Order :: binary(),
221 CoFactor :: none | binary()}
222 ec_field() = ec_prime_field() | ec_characteristic_two_field()
224 ec_curve() =
226 {A :: binary(), B :: binary(), Seed :: none | binary()}
227 Parametric curve definition.
229 ec_prime_field() = {prime_field, Prime :: integer()}
231 ec_characteristic_two_field() =
233 {characteristic_two_field,
234 M :: integer(),
235 Basis :: ec_basis()}
236 ec_basis() =
238 {tpbasis, K :: integer() >= 0} |
239 {ppbasis,
240 K1 :: integer() >= 0,
241 K2 :: integer() >= 0,
242 K3 :: integer() >= 0} |
243 onbasis
244 Curve definition details.
246 Keys
248 key_integer() = integer() | binary()
249 Always binary() when used as return value
251 Public/Private Keys
253 rsa_public() = [key_integer()]
254 rsa_private() = [key_integer()]
256 rsa_params() =
258 {ModulusSizeInBits :: integer(),
259 PublicExponent :: key_integer()}
260 rsa_public() = [E, N]
262 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
264 Where E is the public exponent, N is public modulus and D is the
266 private exponent. The longer key format contains redundant in‐
267 formation that will make the calculation faster. P1 and P2 are
268 first and second prime factors. E1 and E2 are first and second
269 exponents. C is the CRT coefficient. The terminology is taken
270 from RFC 3447.
271 dss_public() = [key_integer()]
273 dss_private() = [key_integer()]
275 dss_public() = [P, Q, G, Y]
277 Where P, Q and G are the dss parameters and Y is the public key.
279 dss_private() = [P, Q, G, X]
281 Where P, Q and G are the dss parameters and X is the private
283 key.
284 ecdsa_public() = key_integer()
286 ecdsa_private() = key_integer()
288 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
290 eddsa_public() = key_integer()
292 eddsa_private() = key_integer()
294 eddsa_params() = edwards_curve_ed()
296 srp_public() = key_integer()
298 srp_private() = key_integer()
300 srp_public() = key_integer()
302 Where is A or B from SRP design
304 srp_private() = key_integer()
306 Where is a or b from SRP design
308 srp_gen_params() =
310 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
311 srp_comp_params() =
313 {user, srp_user_comp_params()} |
314 {host, srp_host_comp_params()}
315 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
317 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
319 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
321 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
323 Where Verifier is v, Generator is g and Prime is N, DerivedKey
325 is X, and Scrambler is u (optional will be generated if not pro‐
326 vided) from SRP design Version = '3' | '6' | '6a'
327 Public Key Ciphers
329 pk_encrypt_decrypt_algs() = rsa
330 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
332 ported.
333 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
335 rsa_opt() =
337 {rsa_padding, rsa_padding()} |
338 {signature_md, atom()} |
339 {rsa_mgf1_md, sha} |
340 {rsa_oaep_label, binary()} |
341 {rsa_oaep_md, sha}
342 rsa_padding() =
344 rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
345 rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding
346 Options for public key encrypt/decrypt. Only RSA is supported.
348 Warning:
350 The RSA options are experimental.
352 The exact set of options and there syntax may be changed without
354 prior notice.
355 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
358 Those option forms are kept only for compatibility and should
360 not be used in new code.
361 Public Key Sign and Verify
363 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
364 Algorithms for sign and verify.
366 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
368 rsa_sign_verify_opt() =
370 {rsa_padding, rsa_sign_verify_padding()} |
371 {rsa_pss_saltlen, integer()} |
372 {rsa_mgf1_md, sha2()}
373 rsa_sign_verify_padding() =
375 rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
376 rsa_no_padding
377 Options for sign and verify.
379 Warning:
381 The RSA options are experimental.
383 The exact set of options and there syntax may be changed without
385 prior notice.
386 Diffie-Hellman Keys and parameters
389 dh_public() = key_integer()
390 dh_private() = key_integer()
392 dh_params() = [key_integer()]
394 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
396 ecdh_public() = key_integer()
398 ecdh_private() = key_integer()
400 ecdh_params() =
402 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
403 Types for Engines
405 engine_key_ref() =
406 #{engine := engine_ref(),
407 key_id := key_id(),
408 password => password(),
409 term() => term()}
410 engine_ref() = term()
412 The result of a call to engine_load/3.
414 key_id() = string() | binary()
416 Identifies the key to be used. The format depends on the loaded
418 engine. It is passed to the ENGINE_load_(private|public)_key
419 functions in libcrypto.
420 password() = string() | binary()
422 The password of the key stored in an engine.
424 engine_method_type() =
426 engine_method_rsa | engine_method_dsa | engine_method_dh |
427 engine_method_rand | engine_method_ecdh |
428 engine_method_ecdsa | engine_method_ciphers |
429 engine_method_digests | engine_method_store |
430 engine_method_pkey_meths | engine_method_pkey_asn1_meths |
431 engine_method_ec
432 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
434 Pre and Post commands for engine_load/3 and /4.
436 Internal data types
438 crypto_state()
439 hash_state()
441 mac_state()
443 Contexts with an internal state that should not be manipulated
445 but passed between function calls.
446 Error types
448 run_time_error() = any()
449 The exception error:badarg signifies that one or more arguments
451 are of wrong data type, or are otherwise badly formed.
452 The exception error:notsup signifies that the algorithm is known
454 but is not supported by current underlying libcrypto or explic‐
455 itly disabled when building that.
456 For a list of supported algorithms, see supports(ciphers).
458 descriptive_error() = any()
460 This is a more developed variant of the older run_time_error().
462 The exception is:
464 {Tag, {C_FileName,LineNumber}, Description}
466 Tag = badarg | notsup | error
468 C_FileName = string()
469 LineNumber = integer()
470 Description = string()
471 It is like the older type an exception of the error class. In
474 addition they contain a descriptive text in English. That text
475 is targeted to a developer. Examples are "Bad key size" or "Ci‐
476 pher id is not an atom".
477 The exception tags are:
479 badarg:
481 Signifies that one or more arguments are of wrong data type
482 or are otherwise badly formed.
483 notsup:
485 Signifies that the algorithm is known but is not supported
486 by current underlying libcrypto or explicitly disabled when
487 building that one.
488 error:
490 An error condition that should not occur, for example a mem‐
491 ory allocation failed or the underlying cryptolib returned
492 an error code, for example "Can't initialize context, step
493 1". Those text usually needs searching the C-code to be un‐
494 derstood.
495 To catch the exception, use for example:
497 try crypto:crypto_init(Ciph, Key, IV, true)
499 catch
500 error:{Tag, {C_FileName,LineNumber}, Description} ->
501 do_something(......)
502 .....
503 end
504
507 crypto_init(Cipher, Key, FlagOrOptions) ->
508 State | descriptive_error()
509 Types:
511 Cipher = cipher_no_iv()
513 Key = iodata()
514 FlagOrOptions = crypto_opts() | boolean()
515 State = crypto_state()
516 Equivalent to the call crypto_init(Cipher, Key, <<>>, FlagOrOp‐
518 tions). It is intended for ciphers without an IV (nounce).
519 crypto_init(Cipher, Key, IV, FlagOrOptions) ->
521 State | descriptive_error()
522 Types:
524 Cipher = cipher_iv()
526 Key = IV = iodata()
527 FlagOrOptions = crypto_opts()
528 State = crypto_state()
529 Initializes a series of encryptions or decryptions and creates
531 an internal state with a reference that is returned.
532 If IV = <<>>, no IV is used. This is intended for ciphers with‐
534 out an IV (nounce). See crypto_init/3.
535 If IV = undefined, the IV must be added by calls to
537 crypto_dyn_iv_update/3. This is intended for cases where the IV
538 (nounce) need to be changed for each encryption and decryption.
539 See crypto_dyn_iv_init/3.
540 The actual encryption or decryption is done by crypto_update/2
542 (or crypto_dyn_iv_update/3 ).
543 For encryption, set the FlagOrOptions to true or [{en‐
545 crypt,true}]. For decryption, set it to false or [{en‐
546 crypt,false}].
547 Padding could be enabled with the option {padding,Padding}. The
549 cryptolib_padding enables pkcs_padding or no padding (none). The
550 paddings zero or random fills the last part of the last block
551 with zeroes or random bytes. If the last block is already full,
552 nothing is added.
553 In decryption, the cryptolib_padding removes such padding, if
555 present. The otp_padding is not removed - it has to be done
556 elsewhere.
557 If padding is {padding,none} or not specifed and the total data
559 from all subsequent crypto_updates does not fill the last block
560 fully, that last data is lost. In case of {padding,none} there
561 will be an error in this case. If padding is not specified, the
562 bytes of the unfilled block is silently discarded.
563 The actual padding is performed by crypto_final/1.
565 For blocksizes call cipher_info/1.
567 See examples in the User's Guide.
569 crypto_update(State, Data) -> Result | descriptive_error()
571 Types:
573 State = crypto_state()
575 Data = iodata()
576 Result = binary()
577 It does an actual crypto operation on a part of the full text.
579 If the part is less than a number of full blocks, only the full
580 blocks (possibly none) are encrypted or decrypted and the re‐
581 maining bytes are saved to the next crypto_update operation. The
582 State should be created with crypto_init/3 or crypto_init/4.
583 See examples in the User's Guide.
585 crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) ->
587 State | descriptive_error()
588 Types:
590 Cipher = cipher_iv()
592 Key = iodata()
593 FlagOrOptions = crypto_opts() | boolean()
594 State = crypto_state()
595 Initializes a series of encryptions or decryptions where the IV
597 is provided later. The actual encryption or decryption is done
598 by crypto_dyn_iv_update/3.
599 The function is equivalent to crypto_init(Cipher, Key, unde‐
601 fined, FlagOrOptions).
602 crypto_final(State) -> FinalResult | descriptive_error()
604 Types:
606 State = crypto_state()
608 FinalResult = binary()
609 Finalizes a series of encryptions or decryptions and delivers
611 the final bytes of the final block. The data returned from this
612 function may be empty if no padding was enabled in
613 crypto_init/3,4 or crypto_dyn_iv_init/3.
614 crypto_get_data(State) -> Result
616 Types:
618 State = crypto_state()
620 Result = map()
621 Returns information about the State in the argument. The infor‐
623 mation is the form of a map, which currently contains at least:
624 size:
626 The number of bytes encrypted or decrypted so far.
627 padding_size:
629 After a call to crypto_final/1 it contains the number of
630 bytes padded. Otherwise 0.
631 padding_type:
633 The type of the padding as provided in the call ot
634 crypto_init/3,4.
635 encrypt:
637 Is true if encryption is performed. It is false otherwise.
638 crypto_dyn_iv_update(State, Data, IV) ->
640 Result | descriptive_error()
641 Types:
643 State = crypto_state()
645 Data = IV = iodata()
646 Result = binary()
647 Do an actual crypto operation on a part of the full text and the
649 IV is supplied for each part. The State should be created with
650 crypto_dyn_iv_init/3.
651 crypto_one_time(Cipher, Key, Data, FlagOrOptions) ->
653 Result | descriptive_error()
654 Types:
656 Cipher = cipher_no_iv()
658 Key = Data = iodata()
659 FlagOrOptions = crypto_opts() | boolean()
660 Result = binary()
661 As crypto_one_time/5 but for ciphers without IVs.
663 crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) ->
665 Result | descriptive_error()
666 Types:
668 Cipher = cipher_iv()
670 Key = IV = Data = iodata()
671 FlagOrOptions = crypto_opts() | boolean()
672 Result = binary()
673 Do a complete encrypt or decrypt of the full text in the argu‐
675 ment Data.
676 For encryption, set the FlagOrOptions to true. For decryption,
678 set it to false. For setting other options, see crypto_init/4.
679 See examples in the User's Guide.
681 crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
683 EncFlag :: true) ->
684 Result | descriptive_error()
685 crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
687 EncFlag) ->
688 Result | descriptive_error()
689 Types:
691 Cipher = cipher_aead()
693 Key = IV = InText = AAD = iodata()
694 TagOrTagLength = EncryptTagLength | DecryptTag
695 EncryptTagLength = integer() >= 0
696 DecryptTag = iodata()
697 EncFlag = boolean()
698 Result = EncryptResult | DecryptResult
699 EncryptResult = {OutCryptoText, OutTag}
700 DecryptResult = OutPlainText | error
701 OutCryptoText = OutTag = OutPlainText = binary()
702 Do a complete encrypt or decrypt with an AEAD cipher of the full
704 text.
705 For encryption, set the EncryptFlag to true and set the TagOrTa‐
707 gLength to the wanted size (in bytes) of the tag, that is, the
708 tag length. If the default length is wanted, the crypto_aead/6
709 form may be used.
710 For decryption, set the EncryptFlag to false and put the tag to
712 be checked in the argument TagOrTagLength.
713 See examples in the User's Guide.
715 supports(Type) -> Support
717 Types:
719 Type = hashs | ciphers | public_keys | macs | curves |
721 rsa_opts
722 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
723 Hashs =
724 [sha1() |
725 sha2() |
726 sha3() |
727 blake2() |
728 ripemd160 |
729 compatibility_only_hash()]
730 Ciphers = [cipher()]
731 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
732 Macs = [hmac | cmac | poly1305]
733 Curves =
734 [ec_named_curve() | edwards_curve_dh() | ed‐
735 wards_curve_ed()]
736 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
737 Can be used to determine which crypto algorithms that are sup‐
739 ported by the underlying libcrypto library
740 See hash_info/1 and cipher_info/1 for information about the hash
742 and cipher algorithms.
743 mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()
745 Types:
747 Key = Data = iodata()
749 Mac = binary()
750 Short for mac(Type, undefined, Key, Data).
752 mac(Type, SubType, Key, Data) -> Mac | descriptive_error()
754 Types:
756 Type = hmac | cmac | poly1305
758 SubType =
759 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
760 fined
761 Key = Data = iodata()
762 Mac = binary()
763 Computes a MAC (Message Authentication Code) of type Type from
765 Data.
766 SubType depends on the MAC Type:
768 * For hmac it is a hash algorithm, see Algorithm Details in
770 the User's Guide.
771 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
773 tails in the User's Guide.
774 * For poly1305 it should be set to undefined or the mac/2
776 function could be used instead, see Algorithm Details in the
777 User's Guide.
778 Key is the authentication key with a length according to the
780 Type and SubType. The key length could be found with the
781 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
782 poly1305 the key length is 32 bytes. Note that the cryptographic
783 quality of the key is not checked.
784 The Mac result will have a default length depending on the Type
786 and SubType. To set a shorter length, use macN/4 or macN/5 in‐
787 stead. The default length is documented in Algorithm Details in
788 the User's Guide.
789 macN(Type :: poly1305, Key, Data, MacLength) ->
791 Mac | descriptive_error()
792 Types:
794 Key = Data = iodata()
796 Mac = binary()
797 MacLength = integer() >= 1
798 Short for macN(Type, undefined, Key, Data, MacLength).
800 macN(Type, SubType, Key, Data, MacLength) ->
802 Mac | descriptive_error()
803 Types:
805 Type = hmac | cmac | poly1305
807 SubType =
808 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
809 fined
810 Key = Data = iodata()
811 Mac = binary()
812 MacLength = integer() >= 1
813 Computes a MAC (Message Authentication Code) as mac/3 and mac/4
815 but MacLength will limit the size of the resultant Mac to at
816 most MacLength bytes. Note that if MacLength is greater than the
817 actual number of bytes returned from the underlying hash, the
818 returned hash will have that shorter length instead.
819 The max MacLength is documented in Algorithm Details in the
821 User's Guide.
822 mac_init(Type :: poly1305, Key) -> State | descriptive_error()
824 Types:
826 Key = iodata()
828 State = mac_state()
829 Short for mac_init(Type, undefined, Key).
831 mac_init(Type, SubType, Key) -> State | descriptive_error()
833 Types:
835 Type = hmac | cmac | poly1305
837 SubType =
838 hmac_hash_algorithm() | cmac_cipher_algorithm() | unde‐
839 fined
840 Key = iodata()
841 State = mac_state()
842 Initializes the context for streaming MAC operations.
844 Type determines which mac algorithm to use in the MAC operation.
846 SubType depends on the MAC Type:
848 * For hmac it is a hash algorithm, see Algorithm Details in
850 the User's Guide.
851 * For cmac it is a cipher suitable for cmac, see Algorithm De‐
853 tails in the User's Guide.
854 * For poly1305 it should be set to undefined or the mac/2
856 function could be used instead, see Algorithm Details in the
857 User's Guide.
858 Key is the authentication key with a length according to the
860 Type and SubType. The key length could be found with the
861 hash_info/1 (hmac) for and cipher_info/1 (cmac) functions. For
862 poly1305 the key length is 32 bytes. Note that the cryptographic
863 quality of the key is not checked.
864 The returned State should be used in one or more subsequent
866 calls to mac_update/2. The MAC value is finally returned by
867 calling mac_final/1 or mac_finalN/2.
868 See examples in the User's Guide.
870 mac_update(State0, Data) -> State | descriptive_error()
872 Types:
874 Data = iodata()
876 State0 = State = mac_state()
877 Updates the MAC represented by State0 using the given Data which
879 could be of any length.
880 The State0 is the State value originally from a MAC init func‐
882 tion, that is mac_init/2, mac_init/3 or a previous call of
883 mac_update/2. The value State0 is returned unchanged by the
884 function as State.
885 mac_final(State) -> Mac | descriptive_error()
887 Types:
889 State = mac_state()
891 Mac = binary()
892 Finalizes the MAC operation referenced by State. The Mac result
894 will have a default length depending on the Type and SubType in
895 the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
896 instead. The default length is documented in Algorithm Details
897 in the User's Guide.
898 mac_finalN(State, MacLength) -> Mac | descriptive_error()
900 Types:
902 State = mac_state()
904 MacLength = integer() >= 1
905 Mac = binary()
906 Finalizes the MAC operation referenced by State.
908 Mac will be a binary with at most MacLength bytes. Note that if
910 MacLength is greater than the actual number of bytes returned
911 from the underlying hash, the returned hash will have that
912 shorter length instead.
913 The max MacLength is documented in Algorithm Details in the
915 User's Guide.
916 bytes_to_integer(Bin :: binary()) -> integer()
918 Convert binary representation, of an integer, to an Erlang inte‐
920 ger.
921 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
923 SharedSecret
924 Types:
926 Type = dh | ecdh | eddh | srp
928 SharedSecret = binary()
929 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
930 MyPrivateKey =
931 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
932 vate()}
933 Params = dh_params() | ecdh_params() | srp_comp_params()
934 Computes the shared secret from the private key and the other
936 party's public key. See also public_key:compute_key/2
937 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
939 Performs bit-wise XOR (exclusive or) on the data supplied.
941 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
943 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
945 Types:
947 Type = dh | ecdh | eddh | eddsa | rsa | srp
949 PublicKey =
950 dh_public() | ecdh_public() | rsa_public() | srp_public()
951 PrivKeyIn =
952 undefined |
953 dh_private() |
954 ecdh_private() |
955 rsa_private() |
956 {srp_public(), srp_private()}
957 PrivKeyOut =
958 dh_private() |
959 ecdh_private() |
960 rsa_private() |
961 {srp_public(), srp_private()}
962 Params =
963 dh_params() |
964 ecdh_params() |
965 eddsa_params() |
966 rsa_params() |
967 srp_comp_params()
968 Generates a public key of type Type. See also public_key:gener‐
970 ate_key/1. May raise exception:
971 * error:badarg: an argument is of wrong type or has an illegal
973 value,
974 * error:low_entropy: the random generator failed due to lack
976 of secure "randomness",
977 * error:computation_failed: the computation fails of another
979 reason than low_entropy.
980 Note:
982 RSA key generation is only available if the runtime was built
983 with dirty scheduler support. Otherwise, attempting to generate
984 an RSA key will raise exception error:notsup.
985 hash(Type, Data) -> Digest
988 Types:
990 Type = hash_algorithm()
992 Data = iodata()
993 Digest = binary()
994 Computes a message digest of type Type from Data.
996 May raise exception error:notsup in case the chosen Type is not
998 supported by the underlying libcrypto implementation.
999 hash_init(Type) -> State
1001 Types:
1003 Type = hash_algorithm()
1005 State = hash_state()
1006 Initializes the context for streaming hash operations. Type de‐
1008 termines which digest to use. The returned context should be
1009 used as argument to hash_update.
1010 May raise exception error:notsup in case the chosen Type is not
1012 supported by the underlying libcrypto implementation.
1013 hash_update(State, Data) -> NewState
1015 Types:
1017 State = NewState = hash_state()
1019 Data = iodata()
1020 Updates the digest represented by Context using the given Data.
1022 Context must have been generated using hash_init or a previous
1023 call to this function. Data can be any length. NewContext must
1024 be passed into the next call to hash_update or hash_final.
1025 hash_final(State) -> Digest
1027 Types:
1029 State = hash_state()
1031 Digest = binary()
1032 Finalizes the hash operation referenced by Context returned from
1034 a previous call to hash_update. The size of Digest is determined
1035 by the type of hash function used to generate it.
1036 info_fips() -> not_supported | not_enabled | enabled
1038 Provides information about the FIPS operating status of crypto
1040 and the underlying libcrypto library. If crypto was built with
1041 FIPS support this can be either enabled (when running in FIPS
1042 mode) or not_enabled. For other builds this value is always
1043 not_supported.
1044 See enable_fips_mode/1 about how to enable FIPS mode.
1046 Warning:
1048 In FIPS mode all non-FIPS compliant algorithms are disabled and
1049 raise exception error:notsup. Check supports(ciphers) that in
1050 FIPS mode returns the restricted list of available algorithms.
1051 enable_fips_mode(Enable) -> Result
1054 Types:
1056 Enable = Result = boolean()
1058 Enables (Enable = true) or disables (Enable = false) FIPS mode.
1060 Returns true if the operation was successful or false otherwise.
1061 Note that to enable FIPS mode succesfully, OTP must be built
1063 with the configure option --enable-fips, and the underlying
1064 libcrypto must also support FIPS.
1065 See also info_fips/0.
1067 info_lib() -> [{Name, VerNum, VerStr}]
1069 Types:
1071 Name = binary()
1073 VerNum = integer()
1074 VerStr = binary()
1075 Provides the name and version of the libraries used by crypto.
1077 Name is the name of the library. VerNum is the numeric version
1079 according to the library's own versioning scheme. VerStr con‐
1080 tains a text variant of the version.
1081 > info_lib().
1083 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
1084 Note:
1087 From OTP R16 the numeric version represents the version of the
1088 OpenSSL header files (openssl/opensslv.h) used when crypto was
1089 compiled. The text variant represents the libcrypto library used
1090 at runtime. In earlier OTP versions both numeric and text was
1091 taken from the library.
1092 hash_info(Type) -> Result | run_time_error()
1095 Types:
1097 Type = hash_algorithm()
1099 Result =
1100 #{size := integer(),
1101 block_size := integer(),
1102 type := integer()}
1103 Provides a map with information about block_size, size and pos‐
1105 sibly other properties of the hash algorithm in question.
1106 For a list of supported hash algorithms, see supports(hashs).
1108 cipher_info(Type) -> Result | run_time_error()
1110 Types:
1112 Type = cipher()
1114 Result =
1115 #{key_length := integer(),
1116 iv_length := integer(),
1117 block_size := integer(),
1118 mode := CipherModes,
1119 type := undefined | integer(),
1120 prop_aead := boolean()}
1121 CipherModes =
1122 undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
1123 ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
1124 wrap_mode | xts_mode
1125 Provides a map with information about block_size, key_length,
1127 iv_length, aead support and possibly other properties of the ci‐
1128 pher algorithm in question.
1129 Note:
1131 The ciphers aes_cbc, aes_cfb8, aes_cfb128, aes_ctr, aes_ecb,
1132 aes_gcm and aes_ccm has no keylength in the Type as opposed to
1133 for example aes_128_ctr. They adapt to the length of the key
1134 provided in the encrypt and decrypt function. Therefor it is im‐
1135 possible to return a valid keylength in the map.
1136 Always use a Type with an explicit key length,
1138 For a list of supported cipher algorithms, see supports(ci‐
1141 phers).
1142 mod_pow(N, P, M) -> Result
1144 Types:
1146 N = P = M = binary() | integer()
1148 Result = binary() | error
1149 Computes the function N^P mod M.
1151 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
1153 PlainText
1154 Types:
1156 Algorithm = pk_encrypt_decrypt_algs()
1158 CipherText = binary()
1159 PrivateKey = rsa_private() | engine_key_ref()
1160 Options = pk_encrypt_decrypt_opts()
1161 PlainText = binary()
1162 Decrypts the CipherText, encrypted with public_encrypt/4 (or
1164 equivalent function) using the PrivateKey, and returns the
1165 plaintext (message digest). This is a low level signature veri‐
1166 fication operation used for instance by older versions of the
1167 SSL protocol. See also public_key:decrypt_private/[2,3]
1168 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
1170 CipherText
1171 Types:
1173 Algorithm = pk_encrypt_decrypt_algs()
1175 PlainText = binary()
1176 PrivateKey = rsa_private() | engine_key_ref()
1177 Options = pk_encrypt_decrypt_opts()
1178 CipherText = binary()
1179 Encrypts the PlainText using the PrivateKey and returns the ci‐
1181 phertext. This is a low level signature operation used for in‐
1182 stance by older versions of the SSL protocol. See also pub‐
1183 lic_key:encrypt_private/[2,3]
1184 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
1186 PlainText
1187 Types:
1189 Algorithm = pk_encrypt_decrypt_algs()
1191 CipherText = binary()
1192 PublicKey = rsa_public() | engine_key_ref()
1193 Options = pk_encrypt_decrypt_opts()
1194 PlainText = binary()
1195 Decrypts the CipherText, encrypted with private_encrypt/4(or
1197 equivalent function) using the PrivateKey, and returns the
1198 plaintext (message digest). This is a low level signature veri‐
1199 fication operation used for instance by older versions of the
1200 SSL protocol. See also public_key:decrypt_public/[2,3]
1201 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
1203 CipherText
1204 Types:
1206 Algorithm = pk_encrypt_decrypt_algs()
1208 PlainText = binary()
1209 PublicKey = rsa_public() | engine_key_ref()
1210 Options = pk_encrypt_decrypt_opts()
1211 CipherText = binary()
1212 Encrypts the PlainText (message digest) using the PublicKey and
1214 returns the CipherText. This is a low level signature operation
1215 used for instance by older versions of the SSL protocol. See
1216 also public_key:encrypt_public/[2,3]
1217 rand_seed(Seed :: binary()) -> ok
1219 Set the seed for PRNG to the given binary. This calls the
1221 RAND_seed function from openssl. Only use this if the system you
1222 are running on does not have enough "randomness" built in. Nor‐
1223 mally this is when strong_rand_bytes/1 raises error:low_entropy
1224 rand_uniform(Lo, Hi) -> N
1226 Types:
1228 Lo, Hi, N = integer()
1230 Generate a random number N, Lo =< N < Hi. Uses the crypto li‐
1232 brary pseudo-random number generator. Hi must be larger than Lo.
1233 start() -> ok | {error, Reason :: term()}
1235 Equivalent to application:start(crypto).
1237 stop() -> ok | {error, Reason :: term()}
1239 Equivalent to application:stop(crypto).
1241 strong_rand_bytes(N :: integer() >= 0) -> binary()
1243 Generates N bytes randomly uniform 0..255, and returns the re‐
1245 sult in a binary. Uses a cryptographically secure prng seeded
1246 and periodically mixed with operating system provided entropy.
1247 By default this is the RAND_bytes method from OpenSSL.
1248 May raise exception error:low_entropy in case the random genera‐
1250 tor failed due to lack of secure "randomness".
1251 rand_seed() -> rand:state()
1253 Creates state object for random number generation, in order to
1255 generate cryptographically strong random numbers (based on
1256 OpenSSL's BN_rand_range), and saves it in the process dictionary
1257 before returning it as well. See also rand:seed/1 and
1258 rand_seed_s/0.
1259 When using the state object from this function the rand func‐
1261 tions using it may raise exception error:low_entropy in case the
1262 random generator failed due to lack of secure "randomness".
1263 Example
1265 _ = crypto:rand_seed(),
1267 _IntegerValue = rand:uniform(42), % [1; 42]
1268 _FloatValue = rand:uniform(). % [0.0; 1.0[
1269 rand_seed_s() -> rand:state()
1271 Creates state object for random number generation, in order to
1273 generate cryptographically strongly random numbers (based on
1274 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1275 When using the state object from this function the rand func‐
1277 tions using it may raise exception error:low_entropy in case the
1278 random generator failed due to lack of secure "randomness".
1279 Note:
1281 The state returned from this function cannot be used to get a
1282 reproducable random sequence as from the other rand functions,
1283 since reproducability does not match cryptographically safe.
1284 The only supported usage is to generate one distinct random se‐
1286 quence from this start state.
1287 rand_seed_alg(Alg) -> rand:state()
1290 Types:
1292 Alg = crypto | crypto_cache
1294 Creates state object for random number generation, in order to
1296 generate cryptographically strong random numbers, and saves it
1297 in the process dictionary before returning it as well. See also
1298 rand:seed/1 and rand_seed_alg_s/1.
1299 When using the state object from this function the rand func‐
1301 tions using it may raise exception error:low_entropy in case the
1302 random generator failed due to lack of secure "randomness".
1303 Example
1305 _ = crypto:rand_seed_alg(crypto_cache),
1307 _IntegerValue = rand:uniform(42), % [1; 42]
1308 _FloatValue = rand:uniform(). % [0.0; 1.0[
1309 rand_seed_alg(Alg, Seed) -> rand:state()
1311 Types:
1313 Alg = crypto_aes
1315 Creates a state object for random number generation, in order to
1317 generate cryptographically unpredictable random numbers, and
1318 saves it in the process dictionary before returning it as well.
1319 See also rand_seed_alg_s/2.
1320 Example
1322 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1324 IntegerValue = rand:uniform(42), % [1; 42]
1325 FloatValue = rand:uniform(), % [0.0; 1.0[
1326 _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
1327 IntegerValue = rand:uniform(42), % Same values
1328 FloatValue = rand:uniform(). % again
1329 rand_seed_alg_s(Alg) -> rand:state()
1332 Types:
1334 Alg = crypto | crypto_cache
1336 Creates state object for random number generation, in order to
1338 generate cryptographically strongly random numbers. See also
1339 rand:seed_s/1.
1340 If Alg is crypto this function behaves exactly like
1342 rand_seed_s/0.
1343 If Alg is crypto_cache this function fetches random data with
1345 OpenSSL's RAND_bytes and caches it for speed using an internal
1346 word size of 56 bits that makes calculations fast on 64 bit ma‐
1347 chines.
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 The cache size can be changed from its default value using the
1354 crypto app's configuration parameter rand_cache_size.
1355 When using the state object from this function the rand func‐
1357 tions using it may throw exception low_entropy in case the ran‐
1358 dom generator failed due to lack of secure "randomness".
1359 Note:
1361 The state returned from this function cannot be used to get a
1362 reproducable random sequence as from the other rand functions,
1363 since reproducability does not match cryptographically safe.
1364 In fact since random data is cached some numbers may get repro‐
1366 duced if you try, but this is unpredictable.
1367 The only supported usage is to generate one distinct random se‐
1369 quence from this start state.
1370 rand_seed_alg_s(Alg, Seed) -> rand:state()
1373 Types:
1375 Alg = crypto_aes
1377 Creates a state object for random number generation, in order to
1379 generate cryptographically unpredictable random numbers. See
1380 also rand_seed_alg/1.
1381 To get a long period the Xoroshiro928 generator from the rand
1383 module is used as a counter (with period 2^928 - 1) and the gen‐
1384 erator states are scrambled through AES to create 58-bit pseudo
1385 random values.
1386 The result should be statistically completely unpredictable ran‐
1388 dom values, since the scrambling is cryptographically strong and
1389 the period is ridiculously long. But the generated numbers are
1390 not to be regarded as cryptographically strong since there is no
1391 re-keying schedule.
1392 * If you need cryptographically strong random numbers use
1394 rand_seed_alg_s/1 with Alg =:= crypto or Alg =:=
1395 crypto_cache.
1396 * If you need to be able to repeat the sequence use this func‐
1398 tion.
1399 * If you do not need the statistical quality of this function,
1401 there are faster algorithms in the rand module.
1402 Thanks to the used generator the state object supports the
1404 rand:jump/0,1 function with distance 2^512.
1405 Numbers are generated in batches and cached for speed reasons.
1407 The cache size can be changed from its default value using the
1408 crypto app's configuration parameter rand_cache_size.
1409 ec_curves() -> [EllipticCurve]
1411 Types:
1413 EllipticCurve =
1415 ec_named_curve() | edwards_curve_dh() | ed‐
1416 wards_curve_ed()
1417 Can be used to determine which named elliptic curves are sup‐
1419 ported.
1420 ec_curve(CurveName) -> ExplicitCurve
1422 Types:
1424 CurveName = ec_named_curve()
1426 ExplicitCurve = ec_explicit_curve()
1427 Return the defining parameters of a elliptic curve.
1429 sign(Algorithm, DigestType, Msg, Key) -> Signature
1431 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1433 Types:
1435 Algorithm = pk_sign_verify_algs()
1437 DigestType =
1438 rsa_digest_type() |
1439 dss_digest_type() |
1440 ecdsa_digest_type() |
1441 none
1442 Msg = iodata() | {digest, iodata()}
1443 Key =
1444 rsa_private() |
1445 dss_private() |
1446 [ecdsa_private() | ecdsa_params()] |
1447 [eddsa_private() | eddsa_params()] |
1448 engine_key_ref()
1449 Options = pk_sign_verify_opts()
1450 Signature = binary()
1451 Creates a digital signature.
1453 The msg is either the binary "cleartext" data to be signed or it
1455 is the hashed value of "cleartext" i.e. the digest (plaintext).
1456 Algorithm dss can only be used together with digest type sha.
1458 See also public_key:sign/3.
1460 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1462 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1464 Result
1465 Types:
1467 Algorithm = pk_sign_verify_algs()
1469 DigestType =
1470 rsa_digest_type() |
1471 dss_digest_type() |
1472 ecdsa_digest_type() |
1473 none
1474 Msg = iodata() | {digest, iodata()}
1475 Signature = binary()
1476 Key =
1477 rsa_public() |
1478 dss_public() |
1479 [ecdsa_public() | ecdsa_params()] |
1480 [eddsa_public() | eddsa_params()] |
1481 engine_key_ref()
1482 Options = pk_sign_verify_opts()
1483 Result = boolean()
1484 Verifies a digital signature
1486 The msg is either the binary "cleartext" data to be signed or it
1488 is the hashed value of "cleartext" i.e. the digest (plaintext).
1489 Algorithm dss can only be used together with digest type sha.
1491 See also public_key:verify/4.
1493
1496 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1497 Types:
1499 Type = rsa | dss
1501 EnginePrivateKeyRef = engine_key_ref()
1502 PublicKey = rsa_public() | dss_public()
1503 Fetches the corresponding public key from a private key stored
1505 in an Engine. The key must be of the type indicated by the Type
1506 parameter.
1507 engine_get_all_methods() -> Result
1509 Types:
1511 Result = [engine_method_type()]
1513 Returns a list of all possible engine methods.
1515 May raise exception error:notsup in case there is no engine sup‐
1517 port in the underlying OpenSSL implementation.
1518 See also the chapter Engine Load in the User's Guide.
1520 engine_load(EngineId, PreCmds, PostCmds) -> Result
1522 Types:
1524 EngineId = unicode:chardata()
1526 PreCmds = PostCmds = [engine_cmnd()]
1527 Result =
1528 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1529 Loads the OpenSSL engine given by EngineId if it is available
1531 and then returns ok and an engine handle. This function is the
1532 same as calling engine_load/4 with EngineMethods set to a list
1533 of all the possible methods. An error tuple is returned if the
1534 engine can't be loaded.
1535 The function raises a error:badarg if the parameters are in
1537 wrong format. It may also raise the exception error:notsup in
1538 case there is no engine support in the underlying OpenSSL imple‐
1539 mentation.
1540 See also the chapter Engine Load in the User's Guide.
1542 engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
1544 Types:
1546 EngineId = unicode:chardata()
1548 PreCmds = PostCmds = [engine_cmnd()]
1549 EngineMethods = [engine_method_type()]
1550 Result =
1551 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1552 Loads the OpenSSL engine given by EngineId if it is available
1554 and then returns ok and an engine handle. An error tuple is re‐
1555 turned if the engine can't be loaded.
1556 The function raises a error:badarg if the parameters are in
1558 wrong format. It may also raise the exception error:notsup in
1559 case there is no engine support in the underlying OpenSSL imple‐
1560 mentation.
1561 See also the chapter Engine Load in the User's Guide.
1563 engine_unload(Engine) -> Result
1565 Types:
1567 Engine = engine_ref()
1569 Result = ok | {error, Reason :: term()}
1570 Unloads the OpenSSL engine given by Engine. An error tuple is
1572 returned if the engine can't be unloaded.
1573 The function raises a error:badarg if the parameter is in wrong
1575 format. It may also raise the exception error:notsup in case
1576 there is no engine support in the underlying OpenSSL implementa‐
1577 tion.
1578 See also the chapter Engine Load in the User's Guide.
1580 engine_by_id(EngineId) -> Result
1582 Types:
1584 EngineId = unicode:chardata()
1586 Result =
1587 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1588 Get a reference to an already loaded engine with EngineId. An
1590 error tuple is returned if the engine can't be unloaded.
1591 The function raises a error:badarg if the parameter is in wrong
1593 format. It may also raise the exception error:notsup in case
1594 there is no engine support in the underlying OpenSSL implementa‐
1595 tion.
1596 See also the chapter Engine Load in the User's Guide.
1598 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1600 Types:
1602 Engine = term()
1604 CmdName = CmdArg = unicode:chardata()
1605 Result = ok | {error, Reason :: term()}
1606 Sends ctrl commands to the OpenSSL engine given by Engine. This
1608 function is the same as calling engine_ctrl_cmd_string/4 with
1609 Optional set to false.
1610 The function raises a error:badarg if the parameters are in
1612 wrong format. It may also raise the exception error:notsup in
1613 case there is no engine support in the underlying OpenSSL imple‐
1614 mentation.
1615 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1617 Result
1618 Types:
1620 Engine = term()
1622 CmdName = CmdArg = unicode:chardata()
1623 Optional = boolean()
1624 Result = ok | {error, Reason :: term()}
1625 Sends ctrl commands to the OpenSSL engine given by Engine. Op‐
1627 tional is a boolean argument that can relax the semantics of the
1628 function. If set to true it will only return failure if the EN‐
1629 GINE supported the given command name but failed while executing
1630 it, if the ENGINE doesn't support the command name it will sim‐
1631 ply return success without doing anything. In this case we as‐
1632 sume the user is only supplying commands specific to the given
1633 ENGINE so we set this to false.
1634 The function raises a error:badarg if the parameters are in
1636 wrong format. It may also raise the exception error:notsup in
1637 case there is no engine support in the underlying OpenSSL imple‐
1638 mentation.
1639 engine_add(Engine) -> Result
1641 Types:
1643 Engine = engine_ref()
1645 Result = ok | {error, Reason :: term()}
1646 Add the engine to OpenSSL's internal list.
1648 The function raises a error:badarg if the parameters are in
1650 wrong format. It may also raise the exception error:notsup in
1651 case there is no engine support in the underlying OpenSSL imple‐
1652 mentation.
1653 engine_remove(Engine) -> Result
1655 Types:
1657 Engine = engine_ref()
1659 Result = ok | {error, Reason :: term()}
1660 Remove the engine from OpenSSL's internal list.
1662 The function raises a error:badarg if the parameters are in
1664 wrong format. It may also raise the exception error:notsup in
1665 case there is no engine support in the underlying OpenSSL imple‐
1666 mentation.
1667 engine_get_id(Engine) -> EngineId
1669 Types:
1671 Engine = engine_ref()
1673 EngineId = unicode:chardata()
1674 Return the ID for the engine, or an empty binary if there is no
1676 id set.
1677 The function raises a error:badarg if the parameters are in
1679 wrong format. It may also raise the exception error:notsup in
1680 case there is no engine support in the underlying OpenSSL imple‐
1681 mentation.
1682 engine_get_name(Engine) -> EngineName
1684 Types:
1686 Engine = engine_ref()
1688 EngineName = unicode:chardata()
1689 Return the name (eg a description) for the engine, or an empty
1691 binary if there is no name set.
1692 The function raises a error:badarg if the parameters are in
1694 wrong format. It may also raise the exception error:notsup in
1695 case there is no engine support in the underlying OpenSSL imple‐
1696 mentation.
1697 engine_list() -> Result
1699 Types:
1701 Result = [EngineId :: unicode:chardata()]
1703 List the id's of all engines in OpenSSL's internal list.
1705 It may also raise the exception error:notsup in case there is no
1707 engine support in the underlying OpenSSL implementation.
1708 See also the chapter Engine Load in the User's Guide.
1710 May raise exception error:notsup in case engine functionality is
1712 not supported by the underlying OpenSSL implementation.
1713 ensure_engine_loaded(EngineId, LibPath) -> Result
1715 Types:
1717 EngineId = LibPath = unicode:chardata()
1719 Result =
1720 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1721 Loads the OpenSSL engine given by EngineId and the path to the
1723 dynamic library implementing the engine. This function is the
1724 same as calling ensure_engine_loaded/3 with EngineMethods set to
1725 a list of all the possible methods. An error tuple is returned
1726 if the engine can't be loaded.
1727 The function raises a error:badarg if the parameters are in
1729 wrong format. It may also raise the exception error:notsup in
1730 case there is no engine support in the underlying OpenSSL imple‐
1731 mentation.
1732 See also the chapter Engine Load in the User's Guide.
1734 ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
1736 Types:
1738 EngineId = LibPath = unicode:chardata()
1740 EngineMethods = [engine_method_type()]
1741 Result =
1742 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1743 Loads the OpenSSL engine given by EngineId and the path to the
1745 dynamic library implementing the engine. This function differs
1746 from the normal engine_load in that sense it also add the engine
1747 id to the internal list in OpenSSL. Then in the following calls
1748 to the function it just fetch the reference to the engine in‐
1749 stead of loading it again. An error tuple is returned if the en‐
1750 gine can't be loaded.
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 See also the chapter Engine Load in the User's Guide.
1758 ensure_engine_unloaded(Engine) -> Result
1760 Types:
1762 Engine = engine_ref()
1764 Result = ok | {error, Reason :: term()}
1765 Unloads an engine loaded with the ensure_engine_loaded function.
1767 It both removes the label from the OpenSSL internal engine list
1768 and unloads the engine. This function is the same as calling en‐
1769 sure_engine_unloaded/2 with EngineMethods set to a list of all
1770 the possible methods. An error tuple is returned if the engine
1771 can't be unloaded.
1772 The function raises a error:badarg if the parameters are in
1774 wrong format. It may also raise the exception error:notsup in
1775 case there is no engine support in the underlying OpenSSL imple‐
1776 mentation.
1777 See also the chapter Engine Load in the User's Guide.
1779 ensure_engine_unloaded(Engine, EngineMethods) -> Result
1781 Types:
1783 Engine = engine_ref()
1785 EngineMethods = [engine_method_type()]
1786 Result = ok | {error, Reason :: term()}
1787 Unloads an engine loaded with the ensure_engine_loaded function.
1789 It both removes the label from the OpenSSL internal engine list
1790 and unloads the engine. An error tuple is returned if the engine
1791 can't be unloaded.
1792 The function raises a error:badarg if the parameters are in
1794 wrong format. It may also raise the exception error:notsup in
1795 case there is no engine support in the underlying OpenSSL imple‐
1796 mentation.
1797 See also the chapter Engine Load in the User's Guide.
1799Ericsson AB crypto 5.0.4 crypto(3)