.TH crypto 3erl "crypto 4.4" "Ericsson AB" "Erlang Module Definition"
.SH NAME
crypto \- Crypto Functions
.SH DESCRIPTION
.LP
This module provides a set of cryptographic functions\&.
.RS 2
.TP 2
.B
Hash functions:

.RS 2
.TP 2
.B
SHA1, SHA2:
 Secure Hash Standard [FIPS PUB 180-4] 
.TP 2
.B
SHA3:
 SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [FIPS PUB 202] 
.TP 2
.B
MD5:
The MD5 Message Digest Algorithm [RFC 1321]
.TP 2
.B
MD4:
The MD4 Message Digest Algorithm [RFC 1320]
.RE
.RS 2
.LP

.RE

.TP 2
.B
MACs - Message Authentication Codes:

.RS 2
.TP 2
.B
Hmac functions:
 Keyed-Hashing for Message Authentication [RFC 2104] 
.TP 2
.B
Cmac functions:
 The AES-CMAC Algorithm [RFC 4493] 
.TP 2
.B
POLY1305:
 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539] 
.RE
.RS 2
.LP

.RE

.TP 2
.B
Symmetric Ciphers:

.RS 2
.TP 2
.B
DES, 3DES and AES:
Block Cipher Techniques [NIST]
.TP 2
.B
Blowfish:
 Fast Software Encryption, Cambridge Security Workshop Proceedings (December 1993), Springer-Verlag, 1994, pp\&. 191-204\&. 
.TP 2
.B
Chacha20:
 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539] 
.TP 2
.B
Chacha20_poly1305:
 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539] 
.RE
.RS 2
.LP

.RE

.TP 2
.B
Modes:

.RS 2
.TP 2
.B
ECB, CBC, CFB, OFB and CTR:
 Recommendation for Block Cipher Modes of Operation: Methods and Techniques [NIST SP 800-38A] 
.TP 2
.B
GCM:
 Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC [NIST SP 800-38D] 
.TP 2
.B
CCM:
 Recommendation for Block Cipher Modes of Operation: The CCM Mode for Authentication and Confidentiality [NIST SP 800-38C] 
.RE
.RS 2
.LP

.RE

.TP 2
.B
Asymetric Ciphers - Public Key Techniques:

.RS 2
.TP 2
.B
RSA:
 PKCS #1: RSA Cryptography Specifications [RFC 3447] 
.TP 2
.B
DSS:
 Digital Signature Standard (DSS) [FIPS 186-4] 
.TP 2
.B
ECDSA:
 Elliptic Curve Digital Signature Algorithm [ECDSA] 
.TP 2
.B
SRP:
 The SRP Authentication and Key Exchange System [RFC 2945] 
.RE
.RS 2
.LP

.RE

.RE
.LP

.RS -4
.B
Note:
.RE
The actual supported algorithms and features depends on their availability in the actual libcrypto used\&. See the \fBcrypto (App)\fR\& about dependencies\&.
.LP
Enabling FIPS mode will also disable algorithms and features\&.

.LP
The \fBCRYPTO User\&'s Guide\fR\& has more information on FIPS, Engines and Algorithm Details like key lengths\&.
.SH DATA TYPES
.SS Ciphers
.nf

\fBstream_cipher()\fR\& = rc4 | aes_ctr | chacha20
.br
.fi
.RS
.LP
Stream ciphers for \fBstream_encrypt/2\fR\& and \fBstream_decrypt/2\fR\& \&.
.RE

.nf

\fBblock_cipher_with_iv()\fR\& = 
.br
    \fBcbc_cipher()\fR\& |
.br
    \fBcfb_cipher()\fR\& |
.br
    aes_cbc128 |
.br
    aes_cbc256 |
.br
    aes_ige256 |
.br
    blowfish_ofb64 |
.br
    des3_cbf |
.br
    des_ede3 |
.br
    rc2_cbc
.br
.fi
.nf

\fBcbc_cipher()\fR\& = des_cbc | des3_cbc | aes_cbc | blowfish_cbc
.br
.fi
.nf

\fBcfb_cipher()\fR\& = 
.br
    aes_cfb128 | aes_cfb8 | blowfish_cfb64 | des3_cfb | des_cfb
.br
.fi
.RS
.LP
Block ciphers with initialization vector for \fBblock_encrypt/4\fR\& and \fBblock_decrypt/4\fR\& \&.
.RE

.nf

\fBblock_cipher_without_iv()\fR\& = \fBecb_cipher()\fR\&
.br
.fi
.nf

\fBecb_cipher()\fR\& = des_ecb | blowfish_ecb | aes_ecb
.br
.fi
.RS
.LP
Block ciphers without initialization vector for \fBblock_encrypt/3\fR\& and \fBblock_decrypt/3\fR\& \&.
.RE

.nf

\fBaead_cipher()\fR\& = aes_gcm | aes_ccm | chacha20_poly1305
.br
.fi
.RS
.LP
Ciphers with simultaneous MAC-calculation or MAC-checking\&. \fBblock_encrypt/4\fR\& and \fBblock_decrypt/4\fR\& \&.
.RE

.SS Digests
.nf

\fBsha1()\fR\& = sha
.br
.fi
.nf

\fBsha2()\fR\& = sha224 | sha256 | sha384 | sha512
.br
.fi
.nf

\fBsha3()\fR\& = sha3_224 | sha3_256 | sha3_384 | sha3_512
.br
.fi
.RS
.RE

.nf

\fBcompatibility_only_hash()\fR\& = md5 | md4
.br
.fi
.RS
.LP
The \fIcompatibility_only_hash()\fR\& algorithms are recommended only for compatibility with existing applications\&.
.RE

.nf

\fBrsa_digest_type()\fR\& = \fBsha1()\fR\& | \fBsha2()\fR\& | md5 | ripemd160
.br
.fi
.RS
.RE

.nf

\fBdss_digest_type()\fR\& = \fBsha1()\fR\& | \fBsha2()\fR\&
.br
.fi
.RS
.RE

.nf

\fBecdsa_digest_type()\fR\& = \fBsha1()\fR\& | \fBsha2()\fR\&
.br
.fi
.RS
.RE

.SS Elliptic Curves
.nf

\fBec_named_curve()\fR\& = 
.br
    brainpoolP160r1 |
.br
    brainpoolP160t1 |
.br
    brainpoolP192r1 |
.br
    brainpoolP192t1 |
.br
    brainpoolP224r1 |
.br
    brainpoolP224t1 |
.br
    brainpoolP256r1 |
.br
    brainpoolP256t1 |
.br
    brainpoolP320r1 |
.br
    brainpoolP320t1 |
.br
    brainpoolP384r1 |
.br
    brainpoolP384t1 |
.br
    brainpoolP512r1 |
.br
    brainpoolP512t1 |
.br
    c2pnb163v1 |
.br
    c2pnb163v2 |
.br
    c2pnb163v3 |
.br
    c2pnb176v1 |
.br
    c2pnb208w1 |
.br
    c2pnb272w1 |
.br
    c2pnb304w1 |
.br
    c2pnb368w1 |
.br
    c2tnb191v1 |
.br
    c2tnb191v2 |
.br
    c2tnb191v3 |
.br
    c2tnb239v1 |
.br
    c2tnb239v2 |
.br
    c2tnb239v3 |
.br
    c2tnb359v1 |
.br
    c2tnb431r1 |
.br
    ipsec3 |
.br
    ipsec4 |
.br
    prime192v1 |
.br
    prime192v2 |
.br
    prime192v3 |
.br
    prime239v1 |
.br
    prime239v2 |
.br
    prime239v3 |
.br
    prime256v1 |
.br
    secp112r1 |
.br
    secp112r2 |
.br
    secp128r1 |
.br
    secp128r2 |
.br
    secp160k1 |
.br
    secp160r1 |
.br
    secp160r2 |
.br
    secp192k1 |
.br
    secp192r1 |
.br
    secp224k1 |
.br
    secp224r1 |
.br
    secp256k1 |
.br
    secp256r1 |
.br
    secp384r1 |
.br
    secp521r1 |
.br
    sect113r1 |
.br
    sect113r2 |
.br
    sect131r1 |
.br
    sect131r2 |
.br
    sect163k1 |
.br
    sect163r1 |
.br
    sect163r2 |
.br
    sect193r1 |
.br
    sect193r2 |
.br
    sect233k1 |
.br
    sect233r1 |
.br
    sect239k1 |
.br
    sect283k1 |
.br
    sect283r1 |
.br
    sect409k1 |
.br
    sect409r1 |
.br
    sect571k1 |
.br
    sect571r1 |
.br
    wtls1 |
.br
    wtls10 |
.br
    wtls11 |
.br
    wtls12 |
.br
    wtls3 |
.br
    wtls4 |
.br
    wtls5 |
.br
    wtls6 |
.br
    wtls7 |
.br
    wtls8 |
.br
    wtls9
.br
.fi
.nf

\fBedwards_curve_dh()\fR\& = x25519 | x448
.br
.fi
.nf

\fBedwards_curve_ed()\fR\& = ed25519 | ed448
.br
.fi
.RS
.LP
Note that some curves are disabled if FIPS is enabled\&.
.RE

.nf

\fBec_explicit_curve()\fR\& = 
.br
    {Field :: \fBec_field()\fR\&,
.br
     Curve :: \fBec_curve()\fR\&,
.br
     BasePoint :: binary(),
.br
     Order :: binary(),
.br
     CoFactor :: none | binary()}
.br
.fi
.nf

\fBec_field()\fR\& = \fBec_prime_field()\fR\& | \fBec_characteristic_two_field()\fR\&
.br
.fi
.nf

\fBec_curve()\fR\& = 
.br
    {A :: binary(), B :: binary(), Seed :: none | binary()}
.br
.fi
.RS
.LP
Parametric curve definition\&.
.RE

.nf

\fBec_prime_field()\fR\& = {prime_field, Prime :: integer()}
.br
.fi
.nf

\fBec_characteristic_two_field()\fR\& = 
.br
    {characteristic_two_field,
.br
     M :: integer(),
.br
     Basis :: \fBec_basis()\fR\&}
.br
.fi
.nf

\fBec_basis()\fR\& = 
.br
    {tpbasis, K :: integer() >= 0} |
.br
    {ppbasis,
.br
     K1 :: integer() >= 0,
.br
     K2 :: integer() >= 0,
.br
     K3 :: integer() >= 0} |
.br
    onbasis
.br
.fi
.RS
.LP
Curve definition details\&.
.RE

.SS Keys
.nf

\fBkey()\fR\& = iodata()
.br
.fi
.nf

\fBdes3_key()\fR\& = [\fBkey()\fR\&]
.br
.fi
.RS
.LP
For keylengths, iv-sizes and blocksizes see the \fBUser\&'s Guide\fR\&\&.
.LP
A key for des3 is a list of three iolists
.RE

.nf

\fBkey_integer()\fR\& = integer() | binary()
.br
.fi
.RS
.LP
Always \fIbinary()\fR\& when used as return value
.RE

.SS Public/Private Keys
.nf

\fBrsa_public()\fR\& = [\fBkey_integer()\fR\&]
.br
.fi
.nf

\fBrsa_private()\fR\& = [\fBkey_integer()\fR\&]
.br
.fi
.nf

\fBrsa_params()\fR\& = 
.br
    {ModulusSizeInBits :: integer(),
.br
     PublicExponent :: \fBkey_integer()\fR\&}
.br
.fi
.RS
.LP
.nf
rsa_public() = [E, N]
.fi
.LP
.nf
rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]
.fi
.LP
Where E is the public exponent, N is public modulus and D is the private exponent\&. The longer key format contains redundant information that will make the calculation faster\&. P1,P2 are first and second prime factors\&. E1,E2 are first and second exponents\&. C is the CRT coefficient\&. Terminology is taken from  RFC 3447\&.
.RE

.nf

\fBdss_public()\fR\& = [\fBkey_integer()\fR\&]
.br
.fi
.nf

\fBdss_private()\fR\& = [\fBkey_integer()\fR\&]
.br
.fi
.RS
.LP
.nf
dss_public() = [P, Q, G, Y] 
.fi
.LP
Where P, Q and G are the dss parameters and Y is the public key\&.
.LP
.nf
dss_private() = [P, Q, G, X] 
.fi
.LP
Where P, Q and G are the dss parameters and X is the private key\&.
.RE

.nf

\fBecdsa_public()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBecdsa_private()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBecdsa_params()\fR\& = \fBec_named_curve()\fR\& | \fBec_explicit_curve()\fR\&
.br
.fi
.RS
.RE

.nf

\fBeddsa_public()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBeddsa_private()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBeddsa_params()\fR\& = \fBedwards_curve_ed()\fR\&
.br
.fi
.RS
.RE

.nf

\fBsrp_public()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBsrp_private()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.RS
.LP
.nf
srp_public() = key_integer() 
.fi
.LP
Where is \fIA\fR\& or \fIB\fR\& from SRP design
.LP
.nf
srp_private() = key_integer() 
.fi
.LP
Where is \fIa\fR\& or \fIb\fR\& from SRP design
.RE

.nf

\fBsrp_gen_params()\fR\& = 
.br
    {user, \fBsrp_user_gen_params()\fR\&} | {host, \fBsrp_host_gen_params()\fR\&}
.br
.fi
.nf

\fBsrp_comp_params()\fR\& = 
.br
    {user, \fBsrp_user_comp_params()\fR\&} |
.br
    {host, \fBsrp_host_comp_params()\fR\&}
.br
.fi
.RS
.LP
.nf
srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]
.fi
.LP
.nf
srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]
.fi
.LP
.nf
srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]
.fi
.LP
.nf
srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]
.fi
.LP
Where Verifier is \fIv\fR\&, Generator is \fIg\fR\& and Prime is\fI N\fR\&, DerivedKey is \fIX\fR\&, and Scrambler is \fIu\fR\& (optional will be generated if not provided) from SRP design Version = \&'3\&' | \&'6\&' | \&'6a\&'
.RE

.SS Public Key Ciphers
.nf

\fBpk_encrypt_decrypt_algs()\fR\& = rsa
.br
.fi
.RS
.LP
Algorithms for public key encrypt/decrypt\&. Only RSA is supported\&.
.RE

.nf

\fBpk_encrypt_decrypt_opts()\fR\& = [\fBrsa_opt()\fR\&] | \fBrsa_compat_opts()\fR\&
.br
.fi
.nf

\fBrsa_opt()\fR\& = 
.br
    {rsa_padding, \fBrsa_padding()\fR\&} |
.br
    {signature_md, atom()} |
.br
    {rsa_mgf1_md, sha} |
.br
    {rsa_oaep_label, binary()} |
.br
    {rsa_oaep_md, sha}
.br
.fi
.nf

\fBrsa_padding()\fR\& = 
.br
    rsa_pkcs1_padding |
.br
    rsa_pkcs1_oaep_padding |
.br
    rsa_sslv23_padding |
.br
    rsa_x931_padding |
.br
    rsa_no_padding
.br
.fi
.RS
.LP
Options for public key encrypt/decrypt\&. Only RSA is supported\&.
.LP

.RS -4
.B
Warning:
.RE
.LP
The RSA options are experimental\&.
.LP
The exact set of options and there syntax \fImay\fR\& be changed without prior notice\&.

.RE

.nf

\fBrsa_compat_opts()\fR\& = [{rsa_pad, \fBrsa_padding()\fR\&}] | \fBrsa_padding()\fR\&
.br
.fi
.RS
.LP
Those option forms are kept only for compatibility and should not be used in new code\&.
.RE

.SS Public Key Sign and Verify
.nf

\fBpk_sign_verify_algs()\fR\& = rsa | dss | ecdsa | eddsa
.br
.fi
.RS
.LP
Algorithms for sign and verify\&.
.RE

.nf

\fBpk_sign_verify_opts()\fR\& = [\fBrsa_sign_verify_opt()\fR\&]
.br
.fi
.nf

\fBrsa_sign_verify_opt()\fR\& = 
.br
    {rsa_padding, \fBrsa_sign_verify_padding()\fR\&} |
.br
    {rsa_pss_saltlen, integer()}
.br
.fi
.nf

\fBrsa_sign_verify_padding()\fR\& = 
.br
    rsa_pkcs1_padding |
.br
    rsa_pkcs1_pss_padding |
.br
    rsa_x931_padding |
.br
    rsa_no_padding
.br
.fi
.RS
.LP
Options for sign and verify\&.
.LP

.RS -4
.B
Warning:
.RE
.LP
The RSA options are experimental\&.
.LP
The exact set of options and there syntax \fImay\fR\& be changed without prior notice\&.

.RE

.SS Diffie-Hellman Keys and parameters
.nf

\fBdh_public()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBdh_private()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.RS
.RE

.nf

\fBdh_params()\fR\& = [\fBkey_integer()\fR\&]
.br
.fi
.RS
.LP
.nf
dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
.fi
.RE

.nf

\fBecdh_public()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBecdh_private()\fR\& = \fBkey_integer()\fR\&
.br
.fi
.nf

\fBecdh_params()\fR\& = 
.br
    \fBec_named_curve()\fR\& | \fBedwards_curve_dh()\fR\& | \fBec_explicit_curve()\fR\&
.br
.fi
.RS
.RE

.SS Types for Engines
.nf

\fBengine_key_ref()\fR\& = 
.br
    #{engine := \fBengine_ref()\fR\&,
.br
      key_id := \fBkey_id()\fR\&,
.br
      password => \fBpassword()\fR\&,
.br
      term() => term()}
.br
.fi
.nf

\fBengine_ref()\fR\& = term()
.br
.fi
.RS
.LP
The result of a call to \fBengine_load/3\fR\&\&.
.RE

.nf

\fBkey_id()\fR\& = string() | binary()
.br
.fi
.RS
.LP
Identifies the key to be used\&. The format depends on the loaded engine\&. It is passed to the \fIENGINE_load_(private|public)_key\fR\& functions in libcrypto\&.
.RE

.nf

\fBpassword()\fR\& = string() | binary()
.br
.fi
.RS
.LP
The password of the key stored in an engine\&.
.RE

.nf

\fBengine_method_type()\fR\& = 
.br
    engine_method_rsa |
.br
    engine_method_dsa |
.br
    engine_method_dh |
.br
    engine_method_rand |
.br
    engine_method_ecdh |
.br
    engine_method_ecdsa |
.br
    engine_method_ciphers |
.br
    engine_method_digests |
.br
    engine_method_store |
.br
    engine_method_pkey_meths |
.br
    engine_method_pkey_asn1_meths |
.br
    engine_method_ec
.br
.fi
.nf

\fBengine_cmnd()\fR\& = {\fBunicode:chardata()\fR\&, \fBunicode:chardata()\fR\&}
.br
.fi
.RS
.LP
Pre and Post commands for \fBengine_load/3 and /4\fR\&\&.
.RE

.SS Internal data types
.nf

\fBstream_state()\fR\&
.br
.fi
.nf

\fBhmac_state()\fR\&
.br
.fi
.nf

\fBhash_state()\fR\&
.br
.fi
.RS
.LP
Contexts with an internal state that should not be manipulated but passed between function calls\&.
.RE

.SH EXPORTS
.LP
.nf

.B
block_encrypt(Type :: block_cipher_without_iv(),
.B
              Key :: key(),
.B
              PlainText :: iodata()) ->
.B
                 binary()
.br
.fi
.br
.RS
.LP
Encrypt \fIPlainText\fR\& according to \fIType\fR\& block cipher\&.
.LP
May raise exception \fIerror:notsup\fR\& in case the chosen \fIType\fR\& is not supported by the underlying libcrypto implementation\&.
.LP
For keylengths and blocksizes see the \fBUser\&'s Guide\fR\&\&.
.RE

.LP
.nf

.B
block_decrypt(Type :: block_cipher_without_iv(),
.B
              Key :: key(),
.B
              Data :: iodata()) ->
.B
                 binary()
.br
.fi
.br
.RS
.LP
Decrypt \fICipherText\fR\& according to \fIType\fR\& block cipher\&.
.LP
May raise exception \fIerror:notsup\fR\& in case the chosen \fIType\fR\& is not supported by the underlying libcrypto implementation\&.
.LP
For keylengths and blocksizes see the \fBUser\&'s Guide\fR\&\&.
.RE

.LP
.B
block_encrypt(Type, Key, Ivec, PlainText) -> CipherText
.br
.B
block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) -> {CipherText, CipherTag}
.br
.B
block_encrypt(aes_gcm | aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag}
.br
.RS
.LP
Types:

.RS 3
Type = \fBblock_cipher_with_iv()\fR\&
.br
AeadType = \fBaead_cipher()\fR\&
.br
Key = \fBkey()\fR\& | \fBdes3_key()\fR\&
.br
PlainText = iodata()
.br
AAD = IVec = CipherText = CipherTag = binary()
.br
TagLength = 1\&.\&.16
.br
.RE
.RE
.RS
.LP
Encrypt \fIPlainText\fR\& according to \fIType\fR\& block cipher\&. \fIIVec\fR\& is an arbitrary initializing vector\&.
.LP
In AEAD (Authenticated Encryption with Associated Data) mode, encrypt \fIPlainText\fR\&according to \fIType\fR\& block cipher and calculate \fICipherTag\fR\& that also authenticates the \fIAAD\fR\& (Associated Authenticated Data)\&.
.LP
May raise exception \fIerror:notsup\fR\& in case the chosen \fIType\fR\& is not supported by the underlying libcrypto implementation\&.
.LP
For keylengths, iv-sizes and blocksizes see the \fBUser\&'s Guide\fR\&\&.
.RE

.LP
.B
block_decrypt(Type, Key, Ivec, CipherText) -> PlainText
.br
.B
block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | error
.br
.RS
.LP
Types:

.RS 3
Type = \fBblock_cipher_with_iv()\fR\&
.br
AeadType = \fBaead_cipher()\fR\&
.br
Key = \fBkey()\fR\& | \fBdes3_key()\fR\&
.br
PlainText = iodata()
.br
AAD = IVec = CipherText = CipherTag = binary()
.br
.RE
.RE
.RS
.LP
Decrypt \fICipherText\fR\& according to \fIType\fR\& block cipher\&. \fIIVec\fR\& is an arbitrary initializing vector\&.
.LP
In AEAD (Authenticated Encryption with Associated Data) mode, decrypt \fICipherText\fR\&according to \fIType\fR\& block cipher and check the authenticity the \fIPlainText\fR\& and \fIAAD\fR\& (Associated Authenticated Data) using the \fICipherTag\fR\&\&. May return \fIerror\fR\& if the decryption or validation fail\&'s
.LP
May raise exception \fIerror:notsup\fR\& in case the chosen \fIType\fR\& is not supported by the underlying libcrypto implementation\&.
.LP
For keylengths, iv-sizes and blocksizes see the \fBUser\&'s Guide\fR\&\&.
.RE

.LP
.nf

.B
bytes_to_integer(Bin :: binary()) -> integer()
.br
.fi
.br
.RS
.LP
Convert binary representation, of an integer, to an Erlang integer\&.
.RE

.LP
.nf

.B
compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
.B
               SharedSecret
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = dh | ecdh | srp
.br
SharedSecret = binary()
.br
OthersPublicKey = \fBdh_public()\fR\& | \fBecdh_public()\fR\& | \fBsrp_public()\fR\&
.br
MyPrivateKey = 
.br
    \fBdh_private()\fR\& | \fBecdh_private()\fR\& | {\fBsrp_public()\fR\&, \fBsrp_private()\fR\&}
.br
Params = \fBdh_params()\fR\& | \fBecdh_params()\fR\& | \fBsrp_comp_params()\fR\&
.br
.RE
.RE
.RS
.LP
Computes the shared secret from the private key and the other party\&'s public key\&. See also \fBpublic_key:compute_key/2\fR\& 
.RE

.LP
.nf

.B
exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()
.br
.fi
.br
.RS
.LP
Performs bit-wise XOR (exclusive or) on the data supplied\&.
.RE

.LP
.nf

.B
generate_key(Type, Params) -> {PublicKey, PrivKeyOut}
.br
.fi
.br
.nf

.B
generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = dh | ecdh | rsa | srp
.br
PublicKey = 
.br
    \fBdh_public()\fR\& | \fBecdh_public()\fR\& | \fBrsa_public()\fR\& | \fBsrp_public()\fR\&
.br
PrivKeyIn = 
.br
    undefined |
.br
    \fBdh_private()\fR\& |
.br
    \fBecdh_private()\fR\& |
.br
    \fBrsa_private()\fR\& |
.br
    {\fBsrp_public()\fR\&, \fBsrp_private()\fR\&}
.br
PrivKeyOut = 
.br
    \fBdh_private()\fR\& |
.br
    \fBecdh_private()\fR\& |
.br
    \fBrsa_private()\fR\& |
.br
    {\fBsrp_public()\fR\&, \fBsrp_private()\fR\&}
.br
Params = 
.br
    \fBdh_params()\fR\& | \fBecdh_params()\fR\& | \fBrsa_params()\fR\& | \fBsrp_comp_params()\fR\&
.br
.RE
.RE
.RS
.LP
Generates a public key of type \fIType\fR\&\&. See also \fBpublic_key:generate_key/1\fR\&\&. May raise exception:
.RS 2
.TP 2
*
\fIerror:badarg\fR\&: an argument is of wrong type or has an illegal value,
.LP
.TP 2
*
\fIerror:low_entropy\fR\&: the random generator failed due to lack of secure "randomness",
.LP
.TP 2
*
\fIerror:computation_failed\fR\&: the computation fails of another reason than \fIlow_entropy\fR\&\&.
.LP
.RE

.LP

.RS -4
.B
Note:
.RE
RSA key generation is only available if the runtime was built with dirty scheduler support\&. Otherwise, attempting to generate an RSA key will raise exception \fIerror:notsup\fR\&\&.

.RE

.LP
.nf

.B
hash(Type, Data) -> Digest
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = 
.br
    \fBsha1()\fR\& |
.br
    \fBsha2()\fR\& |
.br
    \fBsha3()\fR\& |
.br
    ripemd160 |
.br
    \fBcompatibility_only_hash()\fR\&
.br
Data = iodata()
.br
Digest = binary()
.br
.RE
.RE
.RS
.LP
Computes a message digest of type \fIType\fR\& from \fIData\fR\&\&.
.LP
May raise exception \fIerror:notsup\fR\& in case the chosen \fIType\fR\& is not supported by the underlying libcrypto implementation\&.
.RE

.LP
.nf

.B
hash_init(Type) -> State
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = 
.br
    \fBsha1()\fR\& |
.br
    \fBsha2()\fR\& |
.br
    \fBsha3()\fR\& |
.br
    ripemd160 |
.br
    \fBcompatibility_only_hash()\fR\&
.br
State = \fBhash_state()\fR\&
.br
.RE
.RE
.RS
.LP
Initializes the context for streaming hash operations\&. \fIType\fR\& determines which digest to use\&. The returned context should be used as argument to \fBhash_update\fR\&\&.
.LP
May raise exception \fIerror:notsup\fR\& in case the chosen \fIType\fR\& is not supported by the underlying libcrypto implementation\&.
.RE

.LP
.nf

.B
hash_update(State, Data) -> NewState
.br
.fi
.br
.RS
.LP
Types:

.RS 3
State = NewState = \fBhash_state()\fR\&
.br
Data = iodata()
.br
.RE
.RE
.RS
.LP
Updates the digest represented by \fIContext\fR\& using the given \fIData\fR\&\&. \fIContext\fR\& must have been generated using \fBhash_init\fR\& or a previous call to this function\&. \fIData\fR\& can be any length\&. \fINewContext\fR\& must be passed into the next call to \fIhash_update\fR\& or \fBhash_final\fR\&\&.
.RE

.LP
.nf

.B
hash_final(State) -> Digest
.br
.fi
.br
.RS
.LP
Types:

.RS 3
State = \fBhash_state()\fR\&
.br
Digest = binary()
.br
.RE
.RE
.RS
.LP
Finalizes the hash operation referenced by \fIContext\fR\& returned from a previous call to \fBhash_update\fR\&\&. The size of \fIDigest\fR\& is determined by the type of hash function used to generate it\&.
.RE

.LP
.nf

.B
hmac(Type, Key, Data) -> Mac
.br
.fi
.br
.nf

.B
hmac(Type, Key, Data, MacLength) -> Mac
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = \fBsha1()\fR\& | \fBsha2()\fR\& | \fBsha3()\fR\& | \fBcompatibility_only_hash()\fR\&
.br
Key = Data = iodata()
.br
MacLength = integer()
.br
Mac = binary()
.br
.RE
.RE
.RS
.LP
Computes a HMAC of type \fIType\fR\& from \fIData\fR\& using \fIKey\fR\& as the authentication key\&.
.LP
\fIMacLength\fR\& will limit the size of the resultant \fIMac\fR\&\&.
.RE

.LP
.nf

.B
hmac_init(Type, Key) -> State
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = \fBsha1()\fR\& | \fBsha2()\fR\& | \fBsha3()\fR\& | \fBcompatibility_only_hash()\fR\&
.br
Key = iodata()
.br
State = \fBhmac_state()\fR\&
.br
.RE
.RE
.RS
.LP
Initializes the context for streaming HMAC operations\&. \fIType\fR\& determines which hash function to use in the HMAC operation\&. \fIKey\fR\& is the authentication key\&. The key can be any length\&.
.RE

.LP
.nf

.B
hmac_update(State, Data) -> NewState
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Data = iodata()
.br
State = NewState = \fBhmac_state()\fR\&
.br
.RE
.RE
.RS
.LP
Updates the HMAC represented by \fIContext\fR\& using the given \fIData\fR\&\&. \fIContext\fR\& must have been generated using an HMAC init function (such as \fBhmac_init\fR\&)\&. \fIData\fR\& can be any length\&. \fINewContext\fR\& must be passed into the next call to \fIhmac_update\fR\& or to one of the functions \fBhmac_final\fR\& and \fBhmac_final_n\fR\& 
.LP

.RS -4
.B
Warning:
.RE
Do not use a \fIContext\fR\& as argument in more than one call to hmac_update or hmac_final\&. The semantics of reusing old contexts in any way is undefined and could even crash the VM in earlier releases\&. The reason for this limitation is a lack of support in the underlying libcrypto API\&.

.RE

.LP
.nf

.B
hmac_final(State) -> Mac
.br
.fi
.br
.RS
.LP
Types:

.RS 3
State = \fBhmac_state()\fR\&
.br
Mac = binary()
.br
.RE
.RE
.RS
.LP
Finalizes the HMAC operation referenced by \fIContext\fR\&\&. The size of the resultant MAC is determined by the type of hash function used to generate it\&.
.RE

.LP
.nf

.B
hmac_final_n(State, HashLen) -> Mac
.br
.fi
.br
.RS
.LP
Types:

.RS 3
State = \fBhmac_state()\fR\&
.br
HashLen = integer()
.br
Mac = binary()
.br
.RE
.RE
.RS
.LP
Finalizes the HMAC operation referenced by \fIContext\fR\&\&. \fIHashLen\fR\& must be greater than zero\&. \fIMac\fR\& will be a binary with at most \fIHashLen\fR\& bytes\&. Note that if HashLen is greater than the actual number of bytes returned from the underlying hash, the returned hash will have fewer than \fIHashLen\fR\& bytes\&.
.RE

.LP
.nf

.B
cmac(Type, Key, Data) -> Mac
.br
.fi
.br
.nf

.B
cmac(Type, Key, Data, MacLength) -> Mac
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = 
.br
    \fBcbc_cipher()\fR\& |
.br
    \fBcfb_cipher()\fR\& |
.br
    blowfish_cbc |
.br
    des_ede3 |
.br
    rc2_cbc
.br
Key = Data = iodata()
.br
MacLength = integer()
.br
Mac = binary()
.br
.RE
.RE
.RS
.LP
Computes a CMAC of type \fIType\fR\& from \fIData\fR\& using \fIKey\fR\& as the authentication key\&.
.LP
\fIMacLength\fR\& will limit the size of the resultant \fIMac\fR\&\&.
.RE

.LP
.nf

.B
info_fips() -> not_supported | not_enabled | enabled
.br
.fi
.br
.RS
.LP
Provides information about the FIPS operating status of crypto and the underlying libcrypto library\&. If crypto was built with FIPS support this can be either \fIenabled\fR\& (when running in FIPS mode) or \fInot_enabled\fR\&\&. For other builds this value is always \fInot_supported\fR\&\&.
.LP
See \fBenable_fips_mode/1\fR\& about how to enable FIPS mode\&.
.LP

.RS -4
.B
Warning:
.RE
In FIPS mode all non-FIPS compliant algorithms are disabled and raise exception \fIerror:notsup\fR\&\&. Check \fBsupports\fR\& that in FIPS mode returns the restricted list of available algorithms\&.

.RE

.LP
.nf

.B
enable_fips_mode(Enable) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Enable = Result = boolean()
.br
.RE
.RE
.RS
.LP
Enables (\fIEnable = true\fR\&) or disables (\fIEnable = false\fR\&) FIPS mode\&. Returns \fItrue\fR\& if the operation was successful or \fIfalse\fR\& otherwise\&.
.LP
Note that to enable FIPS mode succesfully, OTP must be built with the configure option \fI--enable-fips\fR\&, and the underlying libcrypto must also support FIPS\&.
.LP
See also \fBinfo_fips/0\fR\&\&.
.RE

.LP
.nf

.B
info_lib() -> [{Name, VerNum, VerStr}]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = binary()
.br
VerNum = integer()
.br
VerStr = binary()
.br
.RE
.RE
.RS
.LP
Provides the name and version of the libraries used by crypto\&.
.LP
\fIName\fR\& is the name of the library\&. \fIVerNum\fR\& is the numeric version according to the library\&'s own versioning scheme\&. \fIVerStr\fR\& contains a text variant of the version\&.
.LP
.nf

> info_lib()\&.
[{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c  10 Nov 2016"">>}]
        
.fi
.LP

.RS -4
.B
Note:
.RE
From OTP R16 the \fInumeric version\fR\& represents the version of the OpenSSL \fIheader files\fR\& (\fIopenssl/opensslv\&.h\fR\&) used when crypto was compiled\&. The text variant represents the libcrypto library used at runtime\&. In earlier OTP versions both numeric and text was taken from the library\&.

.RE

.LP
.nf

.B
mod_pow(N, P, M) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
N = P = M = binary() | integer()
.br
Result = binary() | error
.br
.RE
.RE
.RS
.LP
Computes the function \fIN^P mod M\fR\&\&.
.RE

.LP
.nf

.B
next_iv(Type :: cbc_cipher(), Data) -> NextIVec
.br
.fi
.br
.nf

.B
next_iv(Type :: des_cfb, Data, IVec) -> NextIVec
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Data = iodata()
.br
IVec = NextIVec = binary()
.br
.RE
.RE
.RS
.LP
Returns the initialization vector to be used in the next iteration of encrypt/decrypt of type \fIType\fR\&\&. \fIData\fR\& is the encrypted data from the previous iteration step\&. The \fIIVec\fR\& argument is only needed for \fIdes_cfb\fR\& as the vector used in the previous iteration step\&.
.RE

.LP
.nf

.B
poly1305(Key :: iodata(), Data :: iodata()) -> Mac
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Mac = binary()
.br
.RE
.RE
.RS
.LP
Computes a POLY1305 message authentication code (\fIMac\fR\&) from \fIData\fR\& using \fIKey\fR\& as the authentication key\&.
.RE

.LP
.nf

.B
private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
.B
                   PlainText
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Algorithm = \fBpk_encrypt_decrypt_algs()\fR\&
.br
CipherText = binary()
.br
PrivateKey = \fBrsa_private()\fR\& | \fBengine_key_ref()\fR\&
.br
Options = \fBpk_encrypt_decrypt_opts()\fR\&
.br
PlainText = binary()
.br
.RE
.RE
.RS
.LP
Decrypts the \fICipherText\fR\&, encrypted with \fBpublic_encrypt/4\fR\& (or equivalent function) using the \fIPrivateKey\fR\&, and returns the plaintext (message digest)\&. This is a low level signature verification operation used for instance by older versions of the SSL protocol\&. See also \fBpublic_key:decrypt_private/[2,3]\fR\& 
.RE

.LP
.nf

.B
private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
.B
                   CipherText
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Algorithm = \fBpk_encrypt_decrypt_algs()\fR\&
.br
PlainText = binary()
.br
PrivateKey = \fBrsa_private()\fR\& | \fBengine_key_ref()\fR\&
.br
Options = \fBpk_encrypt_decrypt_opts()\fR\&
.br
CipherText = binary()
.br
.RE
.RE
.RS
.LP
Encrypts the \fIPlainText\fR\& using the \fIPrivateKey\fR\& and returns the ciphertext\&. This is a low level signature operation used for instance by older versions of the SSL protocol\&. See also \fBpublic_key:encrypt_private/[2,3]\fR\& 
.RE

.LP
.nf

.B
public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
.B
                  PlainText
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Algorithm = \fBpk_encrypt_decrypt_algs()\fR\&
.br
CipherText = binary()
.br
PublicKey = \fBrsa_public()\fR\& | \fBengine_key_ref()\fR\&
.br
Options = \fBpk_encrypt_decrypt_opts()\fR\&
.br
PlainText = binary()
.br
.RE
.RE
.RS
.LP
Decrypts the \fICipherText\fR\&, encrypted with \fBprivate_encrypt/4\fR\&(or equivalent function) using the \fIPrivateKey\fR\&, and returns the plaintext (message digest)\&. This is a low level signature verification operation used for instance by older versions of the SSL protocol\&. See also \fBpublic_key:decrypt_public/[2,3]\fR\& 
.RE

.LP
.nf

.B
public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
.B
                  CipherText
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Algorithm = \fBpk_encrypt_decrypt_algs()\fR\&
.br
PlainText = binary()
.br
PublicKey = \fBrsa_public()\fR\& | \fBengine_key_ref()\fR\&
.br
Options = \fBpk_encrypt_decrypt_opts()\fR\&
.br
CipherText = binary()
.br
.RE
.RE
.RS
.LP
Encrypts the \fIPlainText\fR\& (message digest) using the \fIPublicKey\fR\& and returns the \fICipherText\fR\&\&. This is a low level signature operation used for instance by older versions of the SSL protocol\&. See also \fBpublic_key:encrypt_public/[2,3]\fR\& 
.RE

.LP
.nf

.B
rand_seed(Seed :: binary()) -> ok
.br
.fi
.br
.RS
.LP
Set the seed for PRNG to the given binary\&. This calls the RAND_seed function from openssl\&. Only use this if the system you are running on does not have enough "randomness" built in\&. Normally this is when \fBstrong_rand_bytes/1\fR\& raises \fIerror:low_entropy\fR\&
.RE

.LP
.B
rand_uniform(Lo, Hi) -> N
.br
.RS
.LP
Types:

.RS 3
Lo, Hi, N = integer()
.br
.RE
.RE
.RS
.LP
Generate a random number \fIN, Lo =< N < Hi\&.\fR\& Uses the \fIcrypto\fR\& library pseudo-random number generator\&. \fIHi\fR\& must be larger than \fILo\fR\&\&.
.RE

.LP
.nf

.B
start() -> ok | {error, Reason :: term()}
.br
.fi
.br
.RS
.LP
Equivalent to application:start(crypto)\&.
.RE

.LP
.nf

.B
stop() -> ok | {error, Reason :: term()}
.br
.fi
.br
.RS
.LP
Equivalent to application:stop(crypto)\&.
.RE

.LP
.nf

.B
strong_rand_bytes(N :: integer() >= 0) -> binary()
.br
.fi
.br
.RS
.LP
Generates N bytes randomly uniform 0\&.\&.255, and returns the result in a binary\&. Uses a cryptographically secure prng seeded and periodically mixed with operating system provided entropy\&. By default this is the \fIRAND_bytes\fR\& method from OpenSSL\&.
.LP
May raise exception \fIerror:low_entropy\fR\& in case the random generator failed due to lack of secure "randomness"\&.
.RE

.LP
.nf

.B
rand_seed() -> rand:state()
.br
.fi
.br
.RS
.LP
Creates state object for \fBrandom number generation\fR\&, in order to generate cryptographically strong random numbers (based on OpenSSL\&'s \fIBN_rand_range\fR\&), and saves it in the process dictionary before returning it as well\&. See also \fBrand:seed/1\fR\& and \fBrand_seed_s/0\fR\&\&.
.LP
When using the state object from this function the \fBrand\fR\& functions using it may raise exception \fIerror:low_entropy\fR\& in case the random generator failed due to lack of secure "randomness"\&.
.LP
\fIExample\fR\&
.LP
.nf

_ = crypto:rand_seed(),
_IntegerValue = rand:uniform(42), % [1; 42]
_FloatValue = rand:uniform().     % [0.0; 1.0[
.fi
.RE

.LP
.nf

.B
rand_seed_s() -> rand:state()
.br
.fi
.br
.RS
.LP
Creates state object for \fBrandom number generation\fR\&, in order to generate cryptographically strongly random numbers (based on OpenSSL\&'s \fIBN_rand_range\fR\&)\&. See also \fBrand:seed_s/1\fR\&\&.
.LP
When using the state object from this function the \fBrand\fR\& functions using it may raise exception \fIerror:low_entropy\fR\& in case the random generator failed due to lack of secure "randomness"\&.
.LP

.RS -4
.B
Note:
.RE
The state returned from this function can not be used to get a reproducable random sequence as from the other \fBrand\fR\& functions, since reproducability does not match cryptographically safe\&.
.LP
The only supported usage is to generate one distinct random sequence from this start state\&.

.RE

.LP
.B
rand_seed_alg(Alg) -> rand:state()
.br
.RS
.LP
Types:

.RS 3
Alg = crypto | crypto_cache
.br
.RE
.RE
.RS
.LP
Creates state object for \fBrandom number generation\fR\&, in order to generate cryptographically strong random numbers\&. See also \fBrand:seed/1\fR\& and \fBrand_seed_alg_s/1\fR\&\&.
.LP
When using the state object from this function the \fBrand\fR\& functions using it may raise exception \fIerror:low_entropy\fR\& in case the random generator failed due to lack of secure "randomness"\&.
.LP
The cache size can be changed from its default value using the \fB crypto app\&'s \fR\& configuration parameter \fIrand_cache_size\fR\&\&.
.LP
\fIExample\fR\&
.LP
.nf

_ = crypto:rand_seed_alg(crypto_cache),
_IntegerValue = rand:uniform(42), % [1; 42]
_FloatValue = rand:uniform().     % [0.0; 1.0[
.fi
.RE

.LP
.B
rand_seed_alg_s(Alg) -> rand:state()
.br
.RS
.LP
Types:

.RS 3
Alg = crypto | crypto_cache
.br
.RE
.RE
.RS
.LP
Creates state object for \fBrandom number generation\fR\&, in order to generate cryptographically strongly random numbers\&. See also \fBrand:seed_s/1\fR\&\&.
.LP
If \fIAlg\fR\& is \fIcrypto\fR\& this function behaves exactly like \fBrand_seed_s/0\fR\&\&.
.LP
If \fIAlg\fR\& is \fIcrypto_cache\fR\& this function fetches random data with OpenSSL\&'s \fIRAND_bytes\fR\& and caches it for speed using an internal word size of 56 bits that makes calculations fast on 64 bit machines\&.
.LP
When using the state object from this function the \fBrand\fR\& functions using it may raise exception \fIerror:low_entropy\fR\& in case the random generator failed due to lack of secure "randomness"\&.
.LP
The cache size can be changed from its default value using the \fB crypto app\&'s \fR\& configuration parameter \fIrand_cache_size\fR\&\&.
.LP

.RS -4
.B
Note:
.RE
The state returned from this function can not be used to get a reproducable random sequence as from the other \fBrand\fR\& functions, since reproducability does not match cryptographically safe\&.
.LP
In fact since random data is cached some numbers may get reproduced if you try, but this is unpredictable\&.
.LP
The only supported usage is to generate one distinct random sequence from this start state\&.

.RE

.LP
.nf

.B
stream_init(Type, Key) -> State
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = rc4
.br
Key = iodata()
.br
State = \fBstream_state()\fR\&
.br
.RE
.RE
.RS
.LP
Initializes the state for use in RC4 stream encryption \fBstream_encrypt\fR\& and \fBstream_decrypt\fR\&
.LP
For keylengths see the \fBUser\&'s Guide\fR\&\&.
.RE

.LP
.nf

.B
stream_init(Type, Key, IVec) -> State
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = aes_ctr | chacha20
.br
Key = iodata()
.br
IVec = binary()
.br
State = \fBstream_state()\fR\&
.br
.RE
.RE
.RS
.LP
Initializes the state for use in streaming AES encryption using Counter mode (CTR)\&. \fIKey\fR\& is the AES key and must be either 128, 192, or 256 bits long\&. \fIIVec\fR\& is an arbitrary initializing vector of 128 bits (16 bytes)\&. This state is for use with \fBstream_encrypt\fR\& and \fBstream_decrypt\fR\&\&.
.LP
For keylengths and iv-sizes see the \fBUser\&'s Guide\fR\&\&.
.RE

.LP
.nf

.B
stream_encrypt(State, PlainText) -> {NewState, CipherText}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
State = \fBstream_state()\fR\&
.br
PlainText = iodata()
.br
NewState = \fBstream_state()\fR\&
.br
CipherText = iodata()
.br
.RE
.RE
.RS
.LP
Encrypts \fIPlainText\fR\& according to the stream cipher \fIType\fR\& specified in stream_init/3\&. \fIText\fR\& can be any number of bytes\&. The initial \fIState\fR\& is created using \fBstream_init\fR\&\&. \fINewState\fR\& must be passed into the next call to \fIstream_encrypt\fR\&\&.
.RE

.LP
.nf

.B
stream_decrypt(State, CipherText) -> {NewState, PlainText}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
State = \fBstream_state()\fR\&
.br
CipherText = iodata()
.br
NewState = \fBstream_state()\fR\&
.br
PlainText = iodata()
.br
.RE
.RE
.RS
.LP
Decrypts \fICipherText\fR\& according to the stream cipher \fIType\fR\& specified in stream_init/3\&. \fIPlainText\fR\& can be any number of bytes\&. The initial \fIState\fR\& is created using \fBstream_init\fR\&\&. \fINewState\fR\& must be passed into the next call to \fIstream_decrypt\fR\&\&.
.RE

.LP
.nf

.B
supports() -> [Support]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Support = 
.br
    {hashs, Hashs} |
.br
    {ciphers, Ciphers} |
.br
    {public_keys, PKs} |
.br
    {macs, Macs} |
.br
    {curves, Curves} |
.br
    {rsa_opts, RSAopts}
.br
Hashs = 
.br
    [\fBsha1()\fR\& |
.br
     \fBsha2()\fR\& |
.br
     \fBsha3()\fR\& |
.br
     ripemd160 |
.br
     \fBcompatibility_only_hash()\fR\&]
.br
Ciphers = 
.br
    [\fBstream_cipher()\fR\& |
.br
     \fBblock_cipher_with_iv()\fR\& |
.br
     \fBblock_cipher_without_iv()\fR\& |
.br
     \fBaead_cipher()\fR\&]
.br
PKs = [rsa | dss | ecdsa | dh | ecdh | ec_gf2m]
.br
Macs = [hmac | cmac | poly1305]
.br
Curves = 
.br
    [\fBec_named_curve()\fR\& | \fBedwards_curve_dh()\fR\& | \fBedwards_curve_ed()\fR\&]
.br
RSAopts = [\fBrsa_sign_verify_opt()\fR\& | \fBrsa_opt()\fR\&]
.br
.RE
.RE
.RS
.LP
Can be used to determine which crypto algorithms that are supported by the underlying libcrypto library
.LP
Note: the \fIrsa_opts\fR\& entry is in an experimental state and may change or be removed without notice\&. No guarantee for the accuarcy of the rsa option\&'s value list should be assumed\&.
.RE

.LP
.nf

.B
ec_curves() -> [EllipticCurve]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
EllipticCurve = 
.br
    \fBec_named_curve()\fR\& | \fBedwards_curve_dh()\fR\& | \fBedwards_curve_ed()\fR\&
.br
.RE
.RE
.RS
.LP
Can be used to determine which named elliptic curves are supported\&.
.RE

.LP
.nf

.B
ec_curve(CurveName) -> ExplicitCurve
.br
.fi
.br
.RS
.LP
Types:

.RS 3
CurveName = \fBec_named_curve()\fR\&
.br
ExplicitCurve = \fBec_explicit_curve()\fR\&
.br
.RE
.RE
.RS
.LP
Return the defining parameters of a elliptic curve\&.
.RE

.LP
.nf

.B
sign(Algorithm, DigestType, Msg, Key) -> Signature
.br
.fi
.br
.nf

.B
sign(Algorithm, DigestType, Msg, Key, Options) -> Signature
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Algorithm = \fBpk_sign_verify_algs()\fR\&
.br
DigestType = 
.br
    \fBrsa_digest_type()\fR\& |
.br
    \fBdss_digest_type()\fR\& |
.br
    \fBecdsa_digest_type()\fR\& |
.br
    none
.br
Msg = binary() | {digest, binary()}
.br
Key = 
.br
    \fBrsa_private()\fR\& |
.br
    \fBdss_private()\fR\& |
.br
    [\fBecdsa_private()\fR\& | \fBecdsa_params()\fR\&] |
.br
    [\fBeddsa_private()\fR\& | \fBeddsa_params()\fR\&] |
.br
    \fBengine_key_ref()\fR\&
.br
Options = \fBpk_sign_verify_opts()\fR\&
.br
Signature = binary()
.br
.RE
.RE
.RS
.LP
Creates a digital signature\&.
.LP
The msg is either the binary "cleartext" data to be signed or it is the hashed value of "cleartext" i\&.e\&. the digest (plaintext)\&.
.LP
Algorithm \fIdss\fR\& can only be used together with digest type \fIsha\fR\&\&.
.LP
See also \fBpublic_key:sign/3\fR\&\&.
.RE

.LP
.nf

.B
verify(Algorithm, DigestType, Msg, Signature, Key) -> Result
.br
.fi
.br
.nf

.B
verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
.B
          Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Algorithm = \fBpk_sign_verify_algs()\fR\&
.br
DigestType = 
.br
    \fBrsa_digest_type()\fR\& | \fBdss_digest_type()\fR\& | \fBecdsa_digest_type()\fR\&
.br
Msg = binary() | {digest, binary()}
.br
Signature = binary()
.br
Key = 
.br
    \fBrsa_public()\fR\& |
.br
    \fBdss_public()\fR\& |
.br
    [\fBecdsa_public()\fR\& | \fBecdsa_params()\fR\&] |
.br
    [\fBeddsa_public()\fR\& | \fBeddsa_params()\fR\&] |
.br
    \fBengine_key_ref()\fR\&
.br
Options = \fBpk_sign_verify_opts()\fR\&
.br
Result = boolean()
.br
.RE
.RE
.RS
.LP
Verifies a digital signature
.LP
The msg is either the binary "cleartext" data to be signed or it is the hashed value of "cleartext" i\&.e\&. the digest (plaintext)\&.
.LP
Algorithm \fIdss\fR\& can only be used together with digest type \fIsha\fR\&\&.
.LP
See also \fBpublic_key:verify/4\fR\&\&.
.RE

.LP
.nf

.B
privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = rsa | dss
.br
EnginePrivateKeyRef = \fBengine_key_ref()\fR\&
.br
PublicKey = \fBrsa_public()\fR\& | \fBdss_public()\fR\&
.br
.RE
.RE
.RS
.LP
Fetches the corresponding public key from a private key stored in an Engine\&. The key must be of the type indicated by the Type parameter\&.
.RE

.LP
.nf

.B
engine_get_all_methods() -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Result = [\fBengine_method_type()\fR\&]
.br
.RE
.RE
.RS
.LP
Returns a list of all possible engine methods\&.
.LP
May raise exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
engine_load(EngineId, PreCmds, PostCmds) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
EngineId = \fBunicode:chardata()\fR\&
.br
PreCmds = PostCmds = [\fBengine_cmnd()\fR\&]
.br
Result = 
.br
    {ok, Engine :: \fBengine_ref()\fR\&} | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Loads the OpenSSL engine given by \fIEngineId\fR\& if it is available and then returns ok and an engine handle\&. This function is the same as calling \fIengine_load/4\fR\& with \fIEngineMethods\fR\& set to a list of all the possible methods\&. An error tuple is returned if the engine can\&'t be loaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
EngineId = \fBunicode:chardata()\fR\&
.br
PreCmds = PostCmds = [\fBengine_cmnd()\fR\&]
.br
EngineMethods = [\fBengine_method_type()\fR\&]
.br
Result = 
.br
    {ok, Engine :: \fBengine_ref()\fR\&} | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Loads the OpenSSL engine given by \fIEngineId\fR\& if it is available and then returns ok and an engine handle\&. An error tuple is returned if the engine can\&'t be loaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
engine_unload(Engine) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = \fBengine_ref()\fR\&
.br
Result = ok | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Unloads the OpenSSL engine given by \fIEngine\fR\&\&. An error tuple is returned if the engine can\&'t be unloaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameter is in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
engine_by_id(EngineId) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
EngineId = \fBunicode:chardata()\fR\&
.br
Result = 
.br
    {ok, Engine :: \fBengine_ref()\fR\&} | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Get a reference to an already loaded engine with \fIEngineId\fR\&\&. An error tuple is returned if the engine can\&'t be unloaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameter is in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = term()
.br
CmdName = CmdArg = \fBunicode:chardata()\fR\&
.br
Result = ok | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Sends ctrl commands to the OpenSSL engine given by \fIEngine\fR\&\&. This function is the same as calling \fIengine_ctrl_cmd_string/4\fR\& with \fIOptional\fR\& set to \fIfalse\fR\&\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.RE

.LP
.nf

.B
engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
.B
                          Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = term()
.br
CmdName = CmdArg = \fBunicode:chardata()\fR\&
.br
Optional = boolean()
.br
Result = ok | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Sends ctrl commands to the OpenSSL engine given by \fIEngine\fR\&\&. \fIOptional\fR\& is a boolean argument that can relax the semantics of the function\&. If set to \fItrue\fR\& it will only return failure if the ENGINE supported the given command name but failed while executing it, if the ENGINE doesn\&'t support the command name it will simply return success without doing anything\&. In this case we assume the user is only supplying commands specific to the given ENGINE so we set this to \fIfalse\fR\&\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.RE

.LP
.nf

.B
engine_add(Engine) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = \fBengine_ref()\fR\&
.br
Result = ok | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Add the engine to OpenSSL\&'s internal list\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.RE

.LP
.nf

.B
engine_remove(Engine) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = \fBengine_ref()\fR\&
.br
Result = ok | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Remove the engine from OpenSSL\&'s internal list\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.RE

.LP
.nf

.B
engine_get_id(Engine) -> EngineId
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = \fBengine_ref()\fR\&
.br
EngineId = \fBunicode:chardata()\fR\&
.br
.RE
.RE
.RS
.LP
Return the ID for the engine, or an empty binary if there is no id set\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.RE

.LP
.nf

.B
engine_get_name(Engine) -> EngineName
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = \fBengine_ref()\fR\&
.br
EngineName = \fBunicode:chardata()\fR\&
.br
.RE
.RE
.RS
.LP
Return the name (eg a description) for the engine, or an empty binary if there is no name set\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.RE

.LP
.nf

.B
engine_list() -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Result = [EngineId :: \fBunicode:chardata()\fR\&]
.br
.RE
.RE
.RS
.LP
List the id\&'s of all engines in OpenSSL\&'s internal list\&.
.LP
It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.LP
May raise exception \fIerror:notsup\fR\& in case engine functionality is not supported by the underlying OpenSSL implementation\&.
.RE

.LP
.nf

.B
ensure_engine_loaded(EngineId, LibPath) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
EngineId = LibPath = \fBunicode:chardata()\fR\&
.br
Result = 
.br
    {ok, Engine :: \fBengine_ref()\fR\&} | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Loads the OpenSSL engine given by \fIEngineId\fR\& and the path to the dynamic library implementing the engine\&. This function is the same as calling \fIensure_engine_loaded/3\fR\& with \fIEngineMethods\fR\& set to a list of all the possible methods\&. An error tuple is returned if the engine can\&'t be loaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
EngineId = LibPath = \fBunicode:chardata()\fR\&
.br
EngineMethods = [\fBengine_method_type()\fR\&]
.br
Result = 
.br
    {ok, Engine :: \fBengine_ref()\fR\&} | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Loads the OpenSSL engine given by \fIEngineId\fR\& and the path to the dynamic library implementing the engine\&. This function differs from the normal engine_load in that sense it also add the engine id to the internal list in OpenSSL\&. Then in the following calls to the function it just fetch the reference to the engine instead of loading it again\&. An error tuple is returned if the engine can\&'t be loaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
ensure_engine_unloaded(Engine) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = \fBengine_ref()\fR\&
.br
Result = ok | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Unloads an engine loaded with the \fIensure_engine_loaded\fR\& function\&. It both removes the label from the OpenSSL internal engine list and unloads the engine\&. This function is the same as calling \fIensure_engine_unloaded/2\fR\& with \fIEngineMethods\fR\& set to a list of all the possible methods\&. An error tuple is returned if the engine can\&'t be unloaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE

.LP
.nf

.B
ensure_engine_unloaded(Engine, EngineMethods) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Engine = \fBengine_ref()\fR\&
.br
EngineMethods = [\fBengine_method_type()\fR\&]
.br
Result = ok | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
Unloads an engine loaded with the \fIensure_engine_loaded\fR\& function\&. It both removes the label from the OpenSSL internal engine list and unloads the engine\&. An error tuple is returned if the engine can\&'t be unloaded\&.
.LP
The function raises a \fIerror:badarg\fR\& if the parameters are in wrong format\&. It may also raise the exception \fIerror:notsup\fR\& in case there is no engine support in the underlying OpenSSL implementation\&.
.LP
See also the chapter \fBEngine Load\fR\& in the User\&'s Guide\&.
.RE