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 MD5:
22 The MD5 Message Digest Algorithm [RFC 1321]
23 MD4:
25 The MD4 Message Digest Algorithm [RFC 1320]
26 MACs - Message Authentication Codes:
28 Hmac functions:
31 Keyed-Hashing for Message Authentication [RFC 2104]
32 Cmac functions:
34 The AES-CMAC Algorithm [RFC 4493]
35 POLY1305:
37 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
38 Symmetric Ciphers:
40 DES, 3DES and AES:
43 Block Cipher Techniques [NIST]
44 Blowfish:
46 Fast Software Encryption, Cambridge Security Workshop Proceed‐
47 ings (December 1993), Springer-Verlag, 1994, pp. 191-204.
48 Chacha20:
50 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
51 Chacha20_poly1305:
53 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]
54 Modes:
56 ECB, CBC, CFB, OFB and CTR:
59 Recommendation for Block Cipher Modes of Operation: Methods and
60 Techniques [NIST SP 800-38A]
61 GCM:
63 Recommendation for Block Cipher Modes of Operation:
64 Galois/Counter Mode (GCM) and GMAC [NIST SP 800-38D]
65 CCM:
67 Recommendation for Block Cipher Modes of Operation: The CCM Mode
68 for Authentication and Confidentiality [NIST SP 800-38C]
69 Asymetric Ciphers - Public Key Techniques:
71 RSA:
74 PKCS #1: RSA Cryptography Specifications [RFC 3447]
75 DSS:
77 Digital Signature Standard (DSS) [FIPS 186-4]
78 ECDSA:
80 Elliptic Curve Digital Signature Algorithm [ECDSA]
81 SRP:
83 The SRP Authentication and Key Exchange System [RFC 2945]
84 Note:
86 The actual supported algorithms and features depends on their avail‐
87 ability in the actual libcrypto used. See the crypto (App) about depen‐
88 dencies.
89 Enabling FIPS mode will also disable algorithms and features.
91 The CRYPTO User's Guide has more information on FIPS, Engines and Algo‐
94 rithm Details like key lengths.
95
97 Ciphers
98 stream_cipher() = rc4 | aes_ctr | chacha20
99 Stream ciphers for stream_encrypt/2 and stream_decrypt/2 .
101 block_cipher_with_iv() =
103 cbc_cipher() |
104 cfb_cipher() |
105 aes_cbc128 |
106 aes_cbc256 |
107 aes_ige256 |
108 blowfish_ofb64 |
109 des3_cbf |
110 des_ede3 |
111 rc2_cbc
112 cbc_cipher() = des_cbc | des3_cbc | aes_cbc | blowfish_cbc
114 cfb_cipher() =
116 aes_cfb128 | aes_cfb8 | blowfish_cfb64 | des3_cfb | des_cfb
117 Block ciphers with initialization vector for block_encrypt/4 and
119 block_decrypt/4 .
120 block_cipher_without_iv() = ecb_cipher()
122 ecb_cipher() = des_ecb | blowfish_ecb | aes_ecb
124 Block ciphers without initialization vector for block_encrypt/3
126 and block_decrypt/3 .
127 aead_cipher() = aes_gcm | aes_ccm | chacha20_poly1305
129 Ciphers with simultaneous MAC-calculation or MAC-checking.
131 block_encrypt/4 and block_decrypt/4 .
132 Digests
134 sha1() = sha
135 sha2() = sha224 | sha256 | sha384 | sha512
137 sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512
139 compatibility_only_hash() = md5 | md4
141 The compatibility_only_hash() algorithms are recommended only
143 for compatibility with existing applications.
144 rsa_digest_type() = sha1() | sha2() | md5 | ripemd160
146 dss_digest_type() = sha1() | sha2()
148 ecdsa_digest_type() = sha1() | sha2()
150 Elliptic Curves
152 ec_named_curve() =
153 brainpoolP160r1 |
154 brainpoolP160t1 |
155 brainpoolP192r1 |
156 brainpoolP192t1 |
157 brainpoolP224r1 |
158 brainpoolP224t1 |
159 brainpoolP256r1 |
160 brainpoolP256t1 |
161 brainpoolP320r1 |
162 brainpoolP320t1 |
163 brainpoolP384r1 |
164 brainpoolP384t1 |
165 brainpoolP512r1 |
166 brainpoolP512t1 |
167 c2pnb163v1 |
168 c2pnb163v2 |
169 c2pnb163v3 |
170 c2pnb176v1 |
171 c2pnb208w1 |
172 c2pnb272w1 |
173 c2pnb304w1 |
174 c2pnb368w1 |
175 c2tnb191v1 |
176 c2tnb191v2 |
177 c2tnb191v3 |
178 c2tnb239v1 |
179 c2tnb239v2 |
180 c2tnb239v3 |
181 c2tnb359v1 |
182 c2tnb431r1 |
183 ipsec3 |
184 ipsec4 |
185 prime192v1 |
186 prime192v2 |
187 prime192v3 |
188 prime239v1 |
189 prime239v2 |
190 prime239v3 |
191 prime256v1 |
192 secp112r1 |
193 secp112r2 |
194 secp128r1 |
195 secp128r2 |
196 secp160k1 |
197 secp160r1 |
198 secp160r2 |
199 secp192k1 |
200 secp192r1 |
201 secp224k1 |
202 secp224r1 |
203 secp256k1 |
204 secp256r1 |
205 secp384r1 |
206 secp521r1 |
207 sect113r1 |
208 sect113r2 |
209 sect131r1 |
210 sect131r2 |
211 sect163k1 |
212 sect163r1 |
213 sect163r2 |
214 sect193r1 |
215 sect193r2 |
216 sect233k1 |
217 sect233r1 |
218 sect239k1 |
219 sect283k1 |
220 sect283r1 |
221 sect409k1 |
222 sect409r1 |
223 sect571k1 |
224 sect571r1 |
225 wtls1 |
226 wtls10 |
227 wtls11 |
228 wtls12 |
229 wtls3 |
230 wtls4 |
231 wtls5 |
232 wtls6 |
233 wtls7 |
234 wtls8 |
235 wtls9
236 edwards_curve_dh() = x25519 | x448
238 edwards_curve_ed() = ed25519 | ed448
240 Note that some curves are disabled if FIPS is enabled.
242 ec_explicit_curve() =
244 {Field :: ec_field(),
245 Curve :: ec_curve(),
246 BasePoint :: binary(),
247 Order :: binary(),
248 CoFactor :: none | binary()}
249 ec_field() = ec_prime_field() | ec_characteristic_two_field()
251 ec_curve() =
253 {A :: binary(), B :: binary(), Seed :: none | binary()}
254 Parametric curve definition.
256 ec_prime_field() = {prime_field, Prime :: integer()}
258 ec_characteristic_two_field() =
260 {characteristic_two_field,
261 M :: integer(),
262 Basis :: ec_basis()}
263 ec_basis() =
265 {tpbasis, K :: integer() >= 0} |
266 {ppbasis,
267 K1 :: integer() >= 0,
268 K2 :: integer() >= 0,
269 K3 :: integer() >= 0} |
270 onbasis
271 Curve definition details.
273 Keys
275 key() = iodata()
276 des3_key() = [key()]
278 For keylengths, iv-sizes and blocksizes see the User's Guide.
280 A key for des3 is a list of three iolists
282 key_integer() = integer() | binary()
284 Always binary() when used as return value
286 Public/Private Keys
288 rsa_public() = [key_integer()]
289 rsa_private() = [key_integer()]
291 rsa_params() =
293 {ModulusSizeInBits :: integer(),
294 PublicExponent :: key_integer()}
295 rsa_public() = [E, N]
297 rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
299 Where E is the public exponent, N is public modulus and D is the
301 private exponent. The longer key format contains redundant
302 information that will make the calculation faster. P1,P2 are
303 first and second prime factors. E1,E2 are first and second expo‐
304 nents. C is the CRT coefficient. Terminology is taken from RFC
305 3447.
306 dss_public() = [key_integer()]
308 dss_private() = [key_integer()]
310 dss_public() = [P, Q, G, Y]
312 Where P, Q and G are the dss parameters and Y is the public key.
314 dss_private() = [P, Q, G, X]
316 Where P, Q and G are the dss parameters and X is the private
318 key.
319 ecdsa_public() = key_integer()
321 ecdsa_private() = key_integer()
323 ecdsa_params() = ec_named_curve() | ec_explicit_curve()
325 eddsa_public() = key_integer()
327 eddsa_private() = key_integer()
329 eddsa_params() = edwards_curve_ed()
331 srp_public() = key_integer()
333 srp_private() = key_integer()
335 srp_public() = key_integer()
337 Where is A or B from SRP design
339 srp_private() = key_integer()
341 Where is a or b from SRP design
343 srp_gen_params() =
345 {user, srp_user_gen_params()} | {host, srp_host_gen_params()}
346 srp_comp_params() =
348 {user, srp_user_comp_params()} |
349 {host, srp_host_comp_params()}
350 srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
352 srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
354 srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
356 srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
358 Where Verifier is v, Generator is g and Prime is N, DerivedKey
360 is X, and Scrambler is u (optional will be generated if not pro‐
361 vided) from SRP design Version = '3' | '6' | '6a'
362 Public Key Ciphers
364 pk_encrypt_decrypt_algs() = rsa
365 Algorithms for public key encrypt/decrypt. Only RSA is sup‐
367 ported.
368 pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()
370 rsa_opt() =
372 {rsa_padding, rsa_padding()} |
373 {signature_md, atom()} |
374 {rsa_mgf1_md, sha} |
375 {rsa_oaep_label, binary()} |
376 {rsa_oaep_md, sha}
377 rsa_padding() =
379 rsa_pkcs1_padding |
380 rsa_pkcs1_oaep_padding |
381 rsa_sslv23_padding |
382 rsa_x931_padding |
383 rsa_no_padding
384 Options for public key encrypt/decrypt. Only RSA is supported.
386 Warning:
388 The RSA options are experimental.
390 The exact set of options and there syntax may be changed without
392 prior notice.
393 rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()
396 Those option forms are kept only for compatibility and should
398 not be used in new code.
399 Public Key Sign and Verify
401 pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa
402 Algorithms for sign and verify.
404 pk_sign_verify_opts() = [rsa_sign_verify_opt()]
406 rsa_sign_verify_opt() =
408 {rsa_padding, rsa_sign_verify_padding()} |
409 {rsa_pss_saltlen, integer()}
410 rsa_sign_verify_padding() =
412 rsa_pkcs1_padding |
413 rsa_pkcs1_pss_padding |
414 rsa_x931_padding |
415 rsa_no_padding
416 Options for sign and verify.
418 Warning:
420 The RSA options are experimental.
422 The exact set of options and there syntax may be changed without
424 prior notice.
425 Diffie-Hellman Keys and parameters
428 dh_public() = key_integer()
429 dh_private() = key_integer()
431 dh_params() = [key_integer()]
433 dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
435 ecdh_public() = key_integer()
437 ecdh_private() = key_integer()
439 ecdh_params() =
441 ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()
442 Types for Engines
444 engine_key_ref() =
445 #{engine := engine_ref(),
446 key_id := key_id(),
447 password => password(),
448 term() => term()}
449 engine_ref() = term()
451 The result of a call to engine_load/3.
453 key_id() = string() | binary()
455 Identifies the key to be used. The format depends on the loaded
457 engine. It is passed to the ENGINE_load_(private|public)_key
458 functions in libcrypto.
459 password() = string() | binary()
461 The password of the key stored in an engine.
463 engine_method_type() =
465 engine_method_rsa |
466 engine_method_dsa |
467 engine_method_dh |
468 engine_method_rand |
469 engine_method_ecdh |
470 engine_method_ecdsa |
471 engine_method_ciphers |
472 engine_method_digests |
473 engine_method_store |
474 engine_method_pkey_meths |
475 engine_method_pkey_asn1_meths |
476 engine_method_ec
477 engine_cmnd() = {unicode:chardata(), unicode:chardata()}
479 Pre and Post commands for engine_load/3 and /4.
481 Internal data types
483 stream_state()
484 hmac_state()
486 hash_state()
488 Contexts with an internal state that should not be manipulated
490 but passed between function calls.
491
493 block_encrypt(Type :: block_cipher_without_iv(),
494 Key :: key(),
495 PlainText :: iodata()) ->
496 binary()
497 Encrypt PlainText according to Type block cipher.
499 May raise exception error:notsup in case the chosen Type is not
501 supported by the underlying libcrypto implementation.
502 For keylengths and blocksizes see the User's Guide.
504 block_decrypt(Type :: block_cipher_without_iv(),
506 Key :: key(),
507 Data :: iodata()) ->
508 binary()
509 Decrypt CipherText according to Type block cipher.
511 May raise exception error:notsup in case the chosen Type is not
513 supported by the underlying libcrypto implementation.
514 For keylengths and blocksizes see the User's Guide.
516 block_encrypt(Type, Key, Ivec, PlainText) -> CipherText
518 block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText,
519 CipherTag}
520 block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText,
521 TagLength}) -> {CipherText, CipherTag}
522 Types:
524 Type = block_cipher_with_iv()
526 AeadType = aead_cipher()
527 Key = key() | des3_key()
528 PlainText = iodata()
529 AAD = IVec = CipherText = CipherTag = binary()
530 TagLength = 1..16
531 Encrypt PlainText according to Type block cipher. IVec is an
533 arbitrary initializing vector.
534 In AEAD (Authenticated Encryption with Associated Data) mode,
536 encrypt PlainTextaccording to Type block cipher and calculate
537 CipherTag that also authenticates the AAD (Associated Authenti‐
538 cated Data).
539 May raise exception error:notsup in case the chosen Type is not
541 supported by the underlying libcrypto implementation.
542 For keylengths, iv-sizes and blocksizes see the User's Guide.
544 block_decrypt(Type, Key, Ivec, CipherText) -> PlainText
546 block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) ->
547 PlainText | error
548 Types:
550 Type = block_cipher_with_iv()
552 AeadType = aead_cipher()
553 Key = key() | des3_key()
554 PlainText = iodata()
555 AAD = IVec = CipherText = CipherTag = binary()
556 Decrypt CipherText according to Type block cipher. IVec is an
558 arbitrary initializing vector.
559 In AEAD (Authenticated Encryption with Associated Data) mode,
561 decrypt CipherTextaccording to Type block cipher and check the
562 authenticity the PlainText and AAD (Associated Authenticated
563 Data) using the CipherTag. May return error if the decryption or
564 validation fail's
565 May raise exception error:notsup in case the chosen Type is not
567 supported by the underlying libcrypto implementation.
568 For keylengths, iv-sizes and blocksizes see the User's Guide.
570 bytes_to_integer(Bin :: binary()) -> integer()
572 Convert binary representation, of an integer, to an Erlang inte‐
574 ger.
575 compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
577 SharedSecret
578 Types:
580 Type = dh | ecdh | srp
582 SharedSecret = binary()
583 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
584 MyPrivateKey =
585 dh_private() | ecdh_private() | {srp_public(), srp_pri‐
586 vate()}
587 Params = dh_params() | ecdh_params() | srp_comp_params()
588 Computes the shared secret from the private key and the other
590 party's public key. See also public_key:compute_key/2
591 exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
593 Performs bit-wise XOR (exclusive or) on the data supplied.
595 generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
597 generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
599 Types:
601 Type = dh | ecdh | rsa | srp
603 PublicKey =
604 dh_public() | ecdh_public() | rsa_public() | srp_public()
605 PrivKeyIn =
606 undefined |
607 dh_private() |
608 ecdh_private() |
609 rsa_private() |
610 {srp_public(), srp_private()}
611 PrivKeyOut =
612 dh_private() |
613 ecdh_private() |
614 rsa_private() |
615 {srp_public(), srp_private()}
616 Params =
617 dh_params() | ecdh_params() | rsa_params() |
618 srp_comp_params()
619 Generates a public key of type Type. See also public_key:gener‐
621 ate_key/1. May raise exception:
622 * error:badarg: an argument is of wrong type or has an illegal
624 value,
625 * error:low_entropy: the random generator failed due to lack
627 of secure "randomness",
628 * error:computation_failed: the computation fails of another
630 reason than low_entropy.
631 Note:
633 RSA key generation is only available if the runtime was built
634 with dirty scheduler support. Otherwise, attempting to generate
635 an RSA key will raise exception error:notsup.
636 hash(Type, Data) -> Digest
639 Types:
641 Type =
643 sha1() |
644 sha2() |
645 sha3() |
646 ripemd160 |
647 compatibility_only_hash()
648 Data = iodata()
649 Digest = binary()
650 Computes a message digest of type Type from Data.
652 May raise exception error:notsup in case the chosen Type is not
654 supported by the underlying libcrypto implementation.
655 hash_init(Type) -> State
657 Types:
659 Type =
661 sha1() |
662 sha2() |
663 sha3() |
664 ripemd160 |
665 compatibility_only_hash()
666 State = hash_state()
667 Initializes the context for streaming hash operations. Type
669 determines which digest to use. The returned context should be
670 used as argument to hash_update.
671 May raise exception error:notsup in case the chosen Type is not
673 supported by the underlying libcrypto implementation.
674 hash_update(State, Data) -> NewState
676 Types:
678 State = NewState = hash_state()
680 Data = iodata()
681 Updates the digest represented by Context using the given Data.
683 Context must have been generated using hash_init or a previous
684 call to this function. Data can be any length. NewContext must
685 be passed into the next call to hash_update or hash_final.
686 hash_final(State) -> Digest
688 Types:
690 State = hash_state()
692 Digest = binary()
693 Finalizes the hash operation referenced by Context returned from
695 a previous call to hash_update. The size of Digest is determined
696 by the type of hash function used to generate it.
697 hmac(Type, Key, Data) -> Mac
699 hmac(Type, Key, Data, MacLength) -> Mac
701 Types:
703 Type = sha1() | sha2() | sha3() | compatibility_only_hash()
705 Key = Data = iodata()
706 MacLength = integer()
707 Mac = binary()
708 Computes a HMAC of type Type from Data using Key as the authen‐
710 tication key.
711 MacLength will limit the size of the resultant Mac.
713 hmac_init(Type, Key) -> State
715 Types:
717 Type = sha1() | sha2() | sha3() | compatibility_only_hash()
719 Key = iodata()
720 State = hmac_state()
721 Initializes the context for streaming HMAC operations. Type
723 determines which hash function to use in the HMAC operation. Key
724 is the authentication key. The key can be any length.
725 hmac_update(State, Data) -> NewState
727 Types:
729 Data = iodata()
731 State = NewState = hmac_state()
732 Updates the HMAC represented by Context using the given Data.
734 Context must have been generated using an HMAC init function
735 (such as hmac_init). Data can be any length. NewContext must be
736 passed into the next call to hmac_update or to one of the func‐
737 tions hmac_final and hmac_final_n
738 Warning:
740 Do not use a Context as argument in more than one call to
741 hmac_update or hmac_final. The semantics of reusing old contexts
742 in any way is undefined and could even crash the VM in earlier
743 releases. The reason for this limitation is a lack of support in
744 the underlying libcrypto API.
745 hmac_final(State) -> Mac
748 Types:
750 State = hmac_state()
752 Mac = binary()
753 Finalizes the HMAC operation referenced by Context. The size of
755 the resultant MAC is determined by the type of hash function
756 used to generate it.
757 hmac_final_n(State, HashLen) -> Mac
759 Types:
761 State = hmac_state()
763 HashLen = integer()
764 Mac = binary()
765 Finalizes the HMAC operation referenced by Context. HashLen must
767 be greater than zero. Mac will be a binary with at most HashLen
768 bytes. Note that if HashLen is greater than the actual number of
769 bytes returned from the underlying hash, the returned hash will
770 have fewer than HashLen bytes.
771 cmac(Type, Key, Data) -> Mac
773 cmac(Type, Key, Data, MacLength) -> Mac
775 Types:
777 Type =
779 cbc_cipher() |
780 cfb_cipher() |
781 blowfish_cbc |
782 des_ede3 |
783 rc2_cbc
784 Key = Data = iodata()
785 MacLength = integer()
786 Mac = binary()
787 Computes a CMAC of type Type from Data using Key as the authen‐
789 tication key.
790 MacLength will limit the size of the resultant Mac.
792 info_fips() -> not_supported | not_enabled | enabled
794 Provides information about the FIPS operating status of crypto
796 and the underlying libcrypto library. If crypto was built with
797 FIPS support this can be either enabled (when running in FIPS
798 mode) or not_enabled. For other builds this value is always
799 not_supported.
800 See enable_fips_mode/1 about how to enable FIPS mode.
802 Warning:
804 In FIPS mode all non-FIPS compliant algorithms are disabled and
805 raise exception error:notsup. Check supports that in FIPS mode
806 returns the restricted list of available algorithms.
807 enable_fips_mode(Enable) -> Result
810 Types:
812 Enable = Result = boolean()
814 Enables (Enable = true) or disables (Enable = false) FIPS mode.
816 Returns true if the operation was successful or false otherwise.
817 Note that to enable FIPS mode succesfully, OTP must be built
819 with the configure option --enable-fips, and the underlying
820 libcrypto must also support FIPS.
821 See also info_fips/0.
823 info_lib() -> [{Name, VerNum, VerStr}]
825 Types:
827 Name = binary()
829 VerNum = integer()
830 VerStr = binary()
831 Provides the name and version of the libraries used by crypto.
833 Name is the name of the library. VerNum is the numeric version
835 according to the library's own versioning scheme. VerStr con‐
836 tains a text variant of the version.
837 > info_lib().
839 [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c 10 Nov 2016"">>}]
840 Note:
843 From OTP R16 the numeric version represents the version of the
844 OpenSSL header files (openssl/opensslv.h) used when crypto was
845 compiled. The text variant represents the libcrypto library used
846 at runtime. In earlier OTP versions both numeric and text was
847 taken from the library.
848 mod_pow(N, P, M) -> Result
851 Types:
853 N = P = M = binary() | integer()
855 Result = binary() | error
856 Computes the function N^P mod M.
858 next_iv(Type :: cbc_cipher(), Data) -> NextIVec
860 next_iv(Type :: des_cfb, Data, IVec) -> NextIVec
862 Types:
864 Data = iodata()
866 IVec = NextIVec = binary()
867 Returns the initialization vector to be used in the next itera‐
869 tion of encrypt/decrypt of type Type. Data is the encrypted data
870 from the previous iteration step. The IVec argument is only
871 needed for des_cfb as the vector used in the previous iteration
872 step.
873 poly1305(Key :: iodata(), Data :: iodata()) -> Mac
875 Types:
877 Mac = binary()
879 Computes a POLY1305 message authentication code (Mac) from Data
881 using Key as the authentication key.
882 private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
884 PlainText
885 Types:
887 Algorithm = pk_encrypt_decrypt_algs()
889 CipherText = binary()
890 PrivateKey = rsa_private() | engine_key_ref()
891 Options = pk_encrypt_decrypt_opts()
892 PlainText = binary()
893 Decrypts the CipherText, encrypted with public_encrypt/4 (or
895 equivalent function) using the PrivateKey, and returns the
896 plaintext (message digest). This is a low level signature veri‐
897 fication operation used for instance by older versions of the
898 SSL protocol. See also public_key:decrypt_private/[2,3]
899 private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
901 CipherText
902 Types:
904 Algorithm = pk_encrypt_decrypt_algs()
906 PlainText = binary()
907 PrivateKey = rsa_private() | engine_key_ref()
908 Options = pk_encrypt_decrypt_opts()
909 CipherText = binary()
910 Encrypts the PlainText using the PrivateKey and returns the
912 ciphertext. This is a low level signature operation used for
913 instance by older versions of the SSL protocol. See also pub‐
914 lic_key:encrypt_private/[2,3]
915 public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
917 PlainText
918 Types:
920 Algorithm = pk_encrypt_decrypt_algs()
922 CipherText = binary()
923 PublicKey = rsa_public() | engine_key_ref()
924 Options = pk_encrypt_decrypt_opts()
925 PlainText = binary()
926 Decrypts the CipherText, encrypted with private_encrypt/4(or
928 equivalent function) using the PrivateKey, and returns the
929 plaintext (message digest). This is a low level signature veri‐
930 fication operation used for instance by older versions of the
931 SSL protocol. See also public_key:decrypt_public/[2,3]
932 public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
934 CipherText
935 Types:
937 Algorithm = pk_encrypt_decrypt_algs()
939 PlainText = binary()
940 PublicKey = rsa_public() | engine_key_ref()
941 Options = pk_encrypt_decrypt_opts()
942 CipherText = binary()
943 Encrypts the PlainText (message digest) using the PublicKey and
945 returns the CipherText. This is a low level signature operation
946 used for instance by older versions of the SSL protocol. See
947 also public_key:encrypt_public/[2,3]
948 rand_seed(Seed :: binary()) -> ok
950 Set the seed for PRNG to the given binary. This calls the
952 RAND_seed function from openssl. Only use this if the system you
953 are running on does not have enough "randomness" built in. Nor‐
954 mally this is when strong_rand_bytes/1 raises error:low_entropy
955 rand_uniform(Lo, Hi) -> N
957 Types:
959 Lo, Hi, N = integer()
961 Generate a random number N, Lo =< N < Hi. Uses the crypto
963 library pseudo-random number generator. Hi must be larger than
964 Lo.
965 start() -> ok | {error, Reason :: term()}
967 Equivalent to application:start(crypto).
969 stop() -> ok | {error, Reason :: term()}
971 Equivalent to application:stop(crypto).
973 strong_rand_bytes(N :: integer() >= 0) -> binary()
975 Generates N bytes randomly uniform 0..255, and returns the
977 result in a binary. Uses a cryptographically secure prng seeded
978 and periodically mixed with operating system provided entropy.
979 By default this is the RAND_bytes method from OpenSSL.
980 May raise exception error:low_entropy in case the random genera‐
982 tor failed due to lack of secure "randomness".
983 rand_seed() -> rand:state()
985 Creates state object for random number generation, in order to
987 generate cryptographically strong random numbers (based on
988 OpenSSL's BN_rand_range), and saves it in the process dictionary
989 before returning it as well. See also rand:seed/1 and
990 rand_seed_s/0.
991 When using the state object from this function the rand func‐
993 tions using it may raise exception error:low_entropy in case the
994 random generator failed due to lack of secure "randomness".
995 Example
997 _ = crypto:rand_seed(),
999 _IntegerValue = rand:uniform(42), % [1; 42]
1000 _FloatValue = rand:uniform(). % [0.0; 1.0[
1001 rand_seed_s() -> rand:state()
1003 Creates state object for random number generation, in order to
1005 generate cryptographically strongly random numbers (based on
1006 OpenSSL's BN_rand_range). See also rand:seed_s/1.
1007 When using the state object from this function the rand func‐
1009 tions using it may raise exception error:low_entropy in case the
1010 random generator failed due to lack of secure "randomness".
1011 Note:
1013 The state returned from this function can not be used to get a
1014 reproducable random sequence as from the other rand functions,
1015 since reproducability does not match cryptographically safe.
1016 The only supported usage is to generate one distinct random
1018 sequence from this start state.
1019 rand_seed_alg(Alg) -> rand:state()
1022 Types:
1024 Alg = crypto | crypto_cache
1026 Creates state object for random number generation, in order to
1028 generate cryptographically strong random numbers. See also
1029 rand:seed/1 and rand_seed_alg_s/1.
1030 When using the state object from this function the rand func‐
1032 tions using it may raise exception error:low_entropy in case the
1033 random generator failed due to lack of secure "randomness".
1034 The cache size can be changed from its default value using the
1036 crypto app's configuration parameter rand_cache_size.
1037 Example
1039 _ = crypto:rand_seed_alg(crypto_cache),
1041 _IntegerValue = rand:uniform(42), % [1; 42]
1042 _FloatValue = rand:uniform(). % [0.0; 1.0[
1043 rand_seed_alg_s(Alg) -> rand:state()
1045 Types:
1047 Alg = crypto | crypto_cache
1049 Creates state object for random number generation, in order to
1051 generate cryptographically strongly random numbers. See also
1052 rand:seed_s/1.
1053 If Alg is crypto this function behaves exactly like
1055 rand_seed_s/0.
1056 If Alg is crypto_cache this function fetches random data with
1058 OpenSSL's RAND_bytes and caches it for speed using an internal
1059 word size of 56 bits that makes calculations fast on 64 bit
1060 machines.
1061 When using the state object from this function the rand func‐
1063 tions using it may raise exception error:low_entropy in case the
1064 random generator failed due to lack of secure "randomness".
1065 The cache size can be changed from its default value using the
1067 crypto app's configuration parameter rand_cache_size.
1068 Note:
1070 The state returned from this function can not be used to get a
1071 reproducable random sequence as from the other rand functions,
1072 since reproducability does not match cryptographically safe.
1073 In fact since random data is cached some numbers may get repro‐
1075 duced if you try, but this is unpredictable.
1076 The only supported usage is to generate one distinct random
1078 sequence from this start state.
1079 stream_init(Type, Key) -> State
1082 Types:
1084 Type = rc4
1086 Key = iodata()
1087 State = stream_state()
1088 Initializes the state for use in RC4 stream encryption
1090 stream_encrypt and stream_decrypt
1091 For keylengths see the User's Guide.
1093 stream_init(Type, Key, IVec) -> State
1095 Types:
1097 Type = aes_ctr | chacha20
1099 Key = iodata()
1100 IVec = binary()
1101 State = stream_state()
1102 Initializes the state for use in streaming AES encryption using
1104 Counter mode (CTR). Key is the AES key and must be either 128,
1105 192, or 256 bits long. IVec is an arbitrary initializing vector
1106 of 128 bits (16 bytes). This state is for use with
1107 stream_encrypt and stream_decrypt.
1108 For keylengths and iv-sizes see the User's Guide.
1110 stream_encrypt(State, PlainText) -> {NewState, CipherText}
1112 Types:
1114 State = stream_state()
1116 PlainText = iodata()
1117 NewState = stream_state()
1118 CipherText = iodata()
1119 Encrypts PlainText according to the stream cipher Type specified
1121 in stream_init/3. Text can be any number of bytes. The initial
1122 State is created using stream_init. NewState must be passed into
1123 the next call to stream_encrypt.
1124 stream_decrypt(State, CipherText) -> {NewState, PlainText}
1126 Types:
1128 State = stream_state()
1130 CipherText = iodata()
1131 NewState = stream_state()
1132 PlainText = iodata()
1133 Decrypts CipherText according to the stream cipher Type speci‐
1135 fied in stream_init/3. PlainText can be any number of bytes. The
1136 initial State is created using stream_init. NewState must be
1137 passed into the next call to stream_decrypt.
1138 supports() -> [Support]
1140 Types:
1142 Support =
1144 {hashs, Hashs} |
1145 {ciphers, Ciphers} |
1146 {public_keys, PKs} |
1147 {macs, Macs} |
1148 {curves, Curves} |
1149 {rsa_opts, RSAopts}
1150 Hashs =
1151 [sha1() |
1152 sha2() |
1153 sha3() |
1154 ripemd160 |
1155 compatibility_only_hash()]
1156 Ciphers =
1157 [stream_cipher() |
1158 block_cipher_with_iv() |
1159 block_cipher_without_iv() |
1160 aead_cipher()]
1161 PKs = [rsa | dss | ecdsa | dh | ecdh | ec_gf2m]
1162 Macs = [hmac | cmac | poly1305]
1163 Curves =
1164 [ec_named_curve() | edwards_curve_dh() |
1165 edwards_curve_ed()]
1166 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]
1167 Can be used to determine which crypto algorithms that are sup‐
1169 ported by the underlying libcrypto library
1170 Note: the rsa_opts entry is in an experimental state and may
1172 change or be removed without notice. No guarantee for the
1173 accuarcy of the rsa option's value list should be assumed.
1174 ec_curves() -> [EllipticCurve]
1176 Types:
1178 EllipticCurve =
1180 ec_named_curve() | edwards_curve_dh() |
1181 edwards_curve_ed()
1182 Can be used to determine which named elliptic curves are sup‐
1184 ported.
1185 ec_curve(CurveName) -> ExplicitCurve
1187 Types:
1189 CurveName = ec_named_curve()
1191 ExplicitCurve = ec_explicit_curve()
1192 Return the defining parameters of a elliptic curve.
1194 sign(Algorithm, DigestType, Msg, Key) -> Signature
1196 sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
1198 Types:
1200 Algorithm = pk_sign_verify_algs()
1202 DigestType =
1203 rsa_digest_type() |
1204 dss_digest_type() |
1205 ecdsa_digest_type() |
1206 none
1207 Msg = binary() | {digest, binary()}
1208 Key =
1209 rsa_private() |
1210 dss_private() |
1211 [ecdsa_private() | ecdsa_params()] |
1212 [eddsa_private() | eddsa_params()] |
1213 engine_key_ref()
1214 Options = pk_sign_verify_opts()
1215 Signature = binary()
1216 Creates a digital signature.
1218 The msg is either the binary "cleartext" data to be signed or it
1220 is the hashed value of "cleartext" i.e. the digest (plaintext).
1221 Algorithm dss can only be used together with digest type sha.
1223 See also public_key:sign/3.
1225 verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
1227 verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
1229 Result
1230 Types:
1232 Algorithm = pk_sign_verify_algs()
1234 DigestType =
1235 rsa_digest_type() | dss_digest_type() |
1236 ecdsa_digest_type()
1237 Msg = binary() | {digest, binary()}
1238 Signature = binary()
1239 Key =
1240 rsa_public() |
1241 dss_public() |
1242 [ecdsa_public() | ecdsa_params()] |
1243 [eddsa_public() | eddsa_params()] |
1244 engine_key_ref()
1245 Options = pk_sign_verify_opts()
1246 Result = boolean()
1247 Verifies a digital signature
1249 The msg is either the binary "cleartext" data to be signed or it
1251 is the hashed value of "cleartext" i.e. the digest (plaintext).
1252 Algorithm dss can only be used together with digest type sha.
1254 See also public_key:verify/4.
1256 privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
1258 Types:
1260 Type = rsa | dss
1262 EnginePrivateKeyRef = engine_key_ref()
1263 PublicKey = rsa_public() | dss_public()
1264 Fetches the corresponding public key from a private key stored
1266 in an Engine. The key must be of the type indicated by the Type
1267 parameter.
1268 engine_get_all_methods() -> Result
1270 Types:
1272 Result = [engine_method_type()]
1274 Returns a list of all possible engine methods.
1276 May raise exception error:notsup in case there is no engine sup‐
1278 port in the underlying OpenSSL implementation.
1279 See also the chapter Engine Load in the User's Guide.
1281 engine_load(EngineId, PreCmds, PostCmds) -> Result
1283 Types:
1285 EngineId = unicode:chardata()
1287 PreCmds = PostCmds = [engine_cmnd()]
1288 Result =
1289 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1290 Loads the OpenSSL engine given by EngineId if it is available
1292 and then returns ok and an engine handle. This function is the
1293 same as calling engine_load/4 with EngineMethods set to a list
1294 of all the possible methods. An error tuple is returned if the
1295 engine can't be loaded.
1296 The function raises a error:badarg if the parameters are in
1298 wrong format. It may also raise the exception error:notsup in
1299 case there is no engine support in the underlying OpenSSL imple‐
1300 mentation.
1301 See also the chapter Engine Load in the User's Guide.
1303 engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
1305 Types:
1307 EngineId = unicode:chardata()
1309 PreCmds = PostCmds = [engine_cmnd()]
1310 EngineMethods = [engine_method_type()]
1311 Result =
1312 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1313 Loads the OpenSSL engine given by EngineId if it is available
1315 and then returns ok and an engine handle. An error tuple is
1316 returned if the engine can't be loaded.
1317 The function raises a error:badarg if the parameters are in
1319 wrong format. It may also raise the exception error:notsup in
1320 case there is no engine support in the underlying OpenSSL imple‐
1321 mentation.
1322 See also the chapter Engine Load in the User's Guide.
1324 engine_unload(Engine) -> Result
1326 Types:
1328 Engine = engine_ref()
1330 Result = ok | {error, Reason :: term()}
1331 Unloads the OpenSSL engine given by Engine. An error tuple is
1333 returned if the engine can't be unloaded.
1334 The function raises a error:badarg if the parameter is in wrong
1336 format. It may also raise the exception error:notsup in case
1337 there is no engine support in the underlying OpenSSL implementa‐
1338 tion.
1339 See also the chapter Engine Load in the User's Guide.
1341 engine_by_id(EngineId) -> Result
1343 Types:
1345 EngineId = unicode:chardata()
1347 Result =
1348 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1349 Get a reference to an already loaded engine with EngineId. An
1351 error tuple is returned if the engine can't be unloaded.
1352 The function raises a error:badarg if the parameter is in wrong
1354 format. It may also raise the exception error:notsup in case
1355 there is no engine support in the underlying OpenSSL implementa‐
1356 tion.
1357 See also the chapter Engine Load in the User's Guide.
1359 engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
1361 Types:
1363 Engine = term()
1365 CmdName = CmdArg = unicode:chardata()
1366 Result = ok | {error, Reason :: term()}
1367 Sends ctrl commands to the OpenSSL engine given by Engine. This
1369 function is the same as calling engine_ctrl_cmd_string/4 with
1370 Optional set to false.
1371 The function raises a error:badarg if the parameters are in
1373 wrong format. It may also raise the exception error:notsup in
1374 case there is no engine support in the underlying OpenSSL imple‐
1375 mentation.
1376 engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
1378 Result
1379 Types:
1381 Engine = term()
1383 CmdName = CmdArg = unicode:chardata()
1384 Optional = boolean()
1385 Result = ok | {error, Reason :: term()}
1386 Sends ctrl commands to the OpenSSL engine given by Engine.
1388 Optional is a boolean argument that can relax the semantics of
1389 the function. If set to true it will only return failure if the
1390 ENGINE supported the given command name but failed while execut‐
1391 ing it, if the ENGINE doesn't support the command name it will
1392 simply return success without doing anything. In this case we
1393 assume the user is only supplying commands specific to the given
1394 ENGINE so we set this to false.
1395 The function raises a error:badarg if the parameters are in
1397 wrong format. It may also raise the exception error:notsup in
1398 case there is no engine support in the underlying OpenSSL imple‐
1399 mentation.
1400 engine_add(Engine) -> Result
1402 Types:
1404 Engine = engine_ref()
1406 Result = ok | {error, Reason :: term()}
1407 Add the engine to OpenSSL's internal list.
1409 The function raises a error:badarg if the parameters are in
1411 wrong format. It may also raise the exception error:notsup in
1412 case there is no engine support in the underlying OpenSSL imple‐
1413 mentation.
1414 engine_remove(Engine) -> Result
1416 Types:
1418 Engine = engine_ref()
1420 Result = ok | {error, Reason :: term()}
1421 Remove the engine from OpenSSL's internal list.
1423 The function raises a error:badarg if the parameters are in
1425 wrong format. It may also raise the exception error:notsup in
1426 case there is no engine support in the underlying OpenSSL imple‐
1427 mentation.
1428 engine_get_id(Engine) -> EngineId
1430 Types:
1432 Engine = engine_ref()
1434 EngineId = unicode:chardata()
1435 Return the ID for the engine, or an empty binary if there is no
1437 id set.
1438 The function raises a error:badarg if the parameters are in
1440 wrong format. It may also raise the exception error:notsup in
1441 case there is no engine support in the underlying OpenSSL imple‐
1442 mentation.
1443 engine_get_name(Engine) -> EngineName
1445 Types:
1447 Engine = engine_ref()
1449 EngineName = unicode:chardata()
1450 Return the name (eg a description) for the engine, or an empty
1452 binary if there is no name set.
1453 The function raises a error:badarg if the parameters are in
1455 wrong format. It may also raise the exception error:notsup in
1456 case there is no engine support in the underlying OpenSSL imple‐
1457 mentation.
1458 engine_list() -> Result
1460 Types:
1462 Result = [EngineId :: unicode:chardata()]
1464 List the id's of all engines in OpenSSL's internal list.
1466 It may also raise the exception error:notsup in case there is no
1468 engine support in the underlying OpenSSL implementation.
1469 See also the chapter Engine Load in the User's Guide.
1471 May raise exception error:notsup in case engine functionality is
1473 not supported by the underlying OpenSSL implementation.
1474 ensure_engine_loaded(EngineId, LibPath) -> Result
1476 Types:
1478 EngineId = LibPath = unicode:chardata()
1480 Result =
1481 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1482 Loads the OpenSSL engine given by EngineId and the path to the
1484 dynamic library implementing the engine. This function is the
1485 same as calling ensure_engine_loaded/3 with EngineMethods set to
1486 a list of all the possible methods. An error tuple is returned
1487 if the engine can't be loaded.
1488 The function raises a error:badarg if the parameters are in
1490 wrong format. It may also raise the exception error:notsup in
1491 case there is no engine support in the underlying OpenSSL imple‐
1492 mentation.
1493 See also the chapter Engine Load in the User's Guide.
1495 ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
1497 Types:
1499 EngineId = LibPath = unicode:chardata()
1501 EngineMethods = [engine_method_type()]
1502 Result =
1503 {ok, Engine :: engine_ref()} | {error, Reason :: term()}
1504 Loads the OpenSSL engine given by EngineId and the path to the
1506 dynamic library implementing the engine. This function differs
1507 from the normal engine_load in that sense it also add the engine
1508 id to the internal list in OpenSSL. Then in the following calls
1509 to the function it just fetch the reference to the engine
1510 instead of loading it again. An error tuple is returned if the
1511 engine can't be loaded.
1512 The function raises a error:badarg if the parameters are in
1514 wrong format. It may also raise the exception error:notsup in
1515 case there is no engine support in the underlying OpenSSL imple‐
1516 mentation.
1517 See also the chapter Engine Load in the User's Guide.
1519 ensure_engine_unloaded(Engine) -> Result
1521 Types:
1523 Engine = engine_ref()
1525 Result = ok | {error, Reason :: term()}
1526 Unloads an engine loaded with the ensure_engine_loaded function.
1528 It both removes the label from the OpenSSL internal engine list
1529 and unloads the engine. This function is the same as calling
1530 ensure_engine_unloaded/2 with EngineMethods set to a list of all
1531 the possible methods. An error tuple is returned if the engine
1532 can't be unloaded.
1533 The function raises a error:badarg if the parameters are in
1535 wrong format. It may also raise the exception error:notsup in
1536 case there is no engine support in the underlying OpenSSL imple‐
1537 mentation.
1538 See also the chapter Engine Load in the User's Guide.
1540 ensure_engine_unloaded(Engine, EngineMethods) -> Result
1542 Types:
1544 Engine = engine_ref()
1546 EngineMethods = [engine_method_type()]
1547 Result = ok | {error, Reason :: term()}
1548 Unloads an engine loaded with the ensure_engine_loaded function.
1550 It both removes the label from the OpenSSL internal engine list
1551 and unloads the engine. An error tuple is returned if the engine
1552 can't be unloaded.
1553 The function raises a error:badarg if the parameters are in
1555 wrong format. It may also raise the exception error:notsup in
1556 case there is no engine support in the underlying OpenSSL imple‐
1557 mentation.
1558 See also the chapter Engine Load in the User's Guide.
1560Ericsson AB crypto 4.4.2 crypto(3)