From cb654518a4fa58fa65f46e1386ff91c6375f6f5a Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Tue, 28 Aug 2018 16:08:13 +0200 Subject: crypto: Generate refman from types and specs and fix links in engine chapter for generated crypto module refman --- lib/crypto/doc/src/crypto.xml | 1104 ++++++++++++++++-------------------- lib/crypto/doc/src/engine_keys.xml | 2 +- 2 files changed, 481 insertions(+), 625 deletions(-) diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 4289bd4a64..9d436847ac 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -46,6 +46,12 @@

Block ciphers - DES and AES in Block Cipher Modes - ECB, CBC, CFB, OFB, CTR and GCM

+ +

GCM: Dworkin, M., + "Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC", + National Institute of Standards and Technology SP 800-38D, November 2007. +

+

RSA encryption RFC 1321

@@ -56,192 +62,358 @@

Secure Remote Password Protocol (SRP - RFC 2945)

- -

gcm: Dworkin, M., "Recommendation for Block Cipher Modes of - Operation: Galois/Counter Mode (GCM) and GMAC", - National Institute of Standards and Technology SP 800- - 38D, November 2007.

- - -
- DATA TYPES - - key_value() = integer() | binary() -

Always binary() when used as return value

+ +

The actual supported algorithms and features depends on their availability in the actual libcrypto used. + See the crypto (App) about dependencies. +

+

Enabling FIPS mode will also disable algorithms and features. +

+ - rsa_public() = [key_value()] = [E, N] -

Where E is the public exponent and N is public modulus.

+

The CRYPTO User's Guide has more information on + FIPS, Engines and Algorithm Details like key lengths. +

+ - rsa_private() = [key_value()] = [E, N, D] | [E, N, D, P1, P2, E1, E2, C] -

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.

+ + Ciphers + + + +

Stream ciphers for + stream_encrypt/2 and + stream_decrypt/2 . +

+ + - dss_public() = [key_value()] = [P, Q, G, Y] -

Where P, Q and G are the dss parameters and Y is the public key.

+ + + + + +

Block ciphers with initialization vector for + block_encrypt/4 and + block_decrypt/4 . +

+ + - dss_private() = [key_value()] = [P, Q, G, X] -

Where P, Q and G are the dss parameters and X is the private key.

+ + + + +

Block ciphers without initialization vector for + block_encrypt/3 and + block_decrypt/3 . +

+ + - srp_public() = key_value() -

Where is A or B from SRP design

+ + + +

Ciphers with simultaneous MAC-calculation or MAC-checking. + block_encrypt/4 and + block_decrypt/4 . +

+ + - srp_private() = key_value() -

Where is a or b from SRP design

+ Digests + + + + + + + -

Where Verifier is v, Generator is g and Prime is N, DerivedKey is X, and Scrambler is - u (optional will be generated if not provided) from SRP design - Version = '3' | '6' | '6a' -

+ + + +

The compatibility_only_hash() algorithms are recommended only for compatibility with existing applications.

+ + - dh_public() = key_value() + + + + + - dh_private() = key_value() + + + + + - dh_params() = [key_value()] = [P, G] | [P, G, PrivateKeyBitLength] + + + + + - ecdh_public() = key_value() + Elliptic Curves + + + + +

Note that some curves are disabled if FIPS is enabled.

+ + - ecdh_private() = key_value() + + + + + +

Parametric curve definition.

+ + - ecdh_params() = ec_named_curve() | ec_explicit_curve() + + + + + +

Curve definition details.

+ + - ed_named_curves_ecdh() -> x448 | x25519 -

Note that the curves are only supported if the underlying OpenSSL has support for them.

+ Keys + + + + +

For keylengths, iv-sizes and blocksizes see the + User's Guide. +

+

A key for des3 is a list of three iolists

+ + - ec_explicit_curve() = - {ec_field(), Prime :: key_value(), Point :: key_value(), Order :: integer(), - CoFactor :: none | integer()} + + + +

Always binary() when used as return value

+ + - ec_field() = {prime_field, Prime :: integer()} | - {characteristic_two_field, M :: integer(), Basis :: ec_basis()} + Public/Private Keys + + + + + + rsa_public() = [E, N] + rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C] +

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.

+ + - ec_basis() = {tpbasis, K :: non_neg_integer()} | - {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | - onbasis + + + + + dss_public() = [P, Q, G, Y] +

Where P, Q and G are the dss parameters and Y is the public key.

- ec_named_curve() -> - sect571r1| sect571k1| sect409r1| sect409k1| secp521r1| secp384r1| secp224r1| secp224k1| - secp192k1| secp160r2| secp128r2| secp128r1| sect233r1| sect233k1| sect193r2| sect193r1| - sect131r2| sect131r1| sect283r1| sect283k1| sect163r2| secp256k1| secp160k1| secp160r1| - secp112r2| secp112r1| sect113r2| sect113r1| sect239k1| sect163r1| sect163k1| secp256r1| - secp192r1| - brainpoolP160r1| brainpoolP160t1| brainpoolP192r1| brainpoolP192t1| brainpoolP224r1| - brainpoolP224t1| brainpoolP256r1| brainpoolP256t1| brainpoolP320r1| brainpoolP320t1| - brainpoolP384r1| brainpoolP384t1| brainpoolP512r1| brainpoolP512t1 - -

Note that the sect curves are GF2m (characteristic two) curves and are only supported if the - underlying OpenSSL has support for them. - See also crypto:supports/0 -

+ dss_private() = [P, Q, G, X] +

Where P, Q and G are the dss parameters and X is the private key.

+ + - - - engine_key_ref() = #{engine := engine_ref(), - key_id := key_id(), - password => password()} + + + + + + + - engine_ref() = term() -

The result of a call to for example engine_load/3. -

+ + + + + srp_public() = key_integer() +

Where is A or B from SRP design

+ + srp_private() = key_integer() +

Where is a or b from SRP design

+ + - key_id() = string() | binary() -

Identifies the key to be used. The format depends on the loaded engine. It is passed to - the ENGINE_load_(private|public)_key functions in libcrypto. -

+ + + + + + srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()] + + srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ] + + srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()] + + srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()] +

Where Verifier is v, Generator is g and Prime is N, DerivedKey is X, and Scrambler is + u (optional will be generated if not provided) from SRP design + Version = '3' | '6' | '6a' +

+ + - password() = string() | binary() -

The key's password -

+ Public Key Ciphers - stream_cipher() = rc4 | aes_ctr | chacha20 + + + +

Algorithms for public key encrypt/decrypt. Only RSA is supported.

+ + - block_cipher() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ige256 | blowfish_cbc | - blowfish_cfb64 | des_cbc | des_cfb | des3_cbc | des3_cfb | des_ede3 | rc2_cbc + + + + + +

Options for public key encrypt/decrypt. Only RSA is supported.

+ + - aead_cipher() = aes_gcm | chacha20_poly1305 -

Note that the actual supported algorithms depends on the underlying crypto library.

+ + + +

Those option forms are kept only for compatibility and should not be used in new code.

+ + - stream_key() = aes_key() | rc4_key() + Public Key Sign and Verify - block_key() = aes_key() | blowfish_key() | des_key()| des3_key() + + + +

Algorithms for sign and verify.

+ + - aes_key() = iodata()

Key length is 128, 192 or 256 bits

+ + + + + +

Options for sign and verify.

+ + - rc4_key() = iodata()

Variable key length from 8 bits up to 2048 bits (usually between 40 and 256)

+ Diffie-Hellman Keys and parameters + + + + + + - blowfish_key() = iodata()

Variable key length from 32 bits up to 448 bits

+ + + + dh_params() = [P, G] | [P, G, PrivateKeyBitLength] + + - des_key() = iodata()

Key length is 64 bits (in CBC mode only 8 bits are used)

+ + + + + + + - des3_key() = [binary(), binary(), binary()]

Each key part is 64 bits (in CBC mode only 8 bits are used)

+ Types for Engines - digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512 + + + + +

The result of a call to engine_load/3. +

+ + - rsa_digest_type() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 + + + +

Identifies the key to be used. The format depends on the loaded engine. It is passed to + the ENGINE_load_(private|public)_key functions in libcrypto. +

+ + - dss_digest_type() = sha | sha224 | sha256 | sha384 | sha512

Note that the actual supported - dss_digest_type depends on the underlying crypto library. In OpenSSL version >= 1.0.1 the listed digest are supported, while in 1.0.0 only sha, sha224 and sha256 are supported. In version 0.9.8 only sha is supported.

+ + + +

The password of the key stored in an engine. +

+ + - ecdsa_digest_type() = sha | sha224 | sha256 | sha384 | sha512 + + + - sign_options() = [{rsa_pad, rsa_sign_padding()} | {rsa_pss_saltlen, integer()}] + + + +

Pre and Post commands for engine_load/3 and /4. +

+ + - rsa_sign_padding() = rsa_pkcs1_padding | rsa_pkcs1_pss_padding + Internal data types - hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 | - sha3_224 | sha3_256 | sha3_384 | sha3_512 -

md4 is also supported for hash_init/1 and hash/2. - Note that both md4 and md5 are recommended only for compatibility with existing applications. - Note that the actual supported hash_algorithms depends on the underlying crypto library. -

- cipher_algorithms() = aes_cbc | aes_cfb8 | aes_cfb128 | aes_ctr | aes_gcm | - aes_ige256 | blowfish_cbc | blowfish_cfb64 | chacha20 | chacha20_poly1305 | des_cbc | - des_cfb | des3_cbc | des3_cfb | des_ede3 | rc2_cbc | rc4 - mac_algorithms() = hmac | cmac | poly1305 - public_key_algorithms() = rsa |dss | ecdsa | dh | ecdh | ec_gf2m -

Note that ec_gf2m is not strictly a public key algorithm, but a restriction on what curves are supported - with ecdsa and ecdh. -

- engine_method_type() = engine_method_rsa | engine_method_dsa | engine_method_dh | - engine_method_rand | engine_method_ecdh | engine_method_ecdsa | - engine_method_ciphers | engine_method_digests | engine_method_store | - engine_method_pkey_meths | engine_method_pkey_asn1_meths + + + + + +

Contexts with an internal state that should not be manipulated but passed between function calls. +

+ + -
+ + - block_encrypt(Type, Key, PlainText) -> CipherText + Encrypt PlainText according to Type block cipher - - Type = des_ecb | blowfish_ecb | aes_ecb - Key = block_key() - PlainText = iodata() - -

Encrypt PlainText according to Type block cipher.

-

May throw exception notsup in case the chosen Type - is not supported by the underlying OpenSSL implementation.

+

Encrypt PlainText according to Type block cipher.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths and blocksizes see the + User's Guide. +

- block_decrypt(Type, Key, CipherText) -> PlainText + Decrypt CipherText according to Type block cipher - - Type = des_ecb | blowfish_ecb | aes_ecb - Key = block_key() - PlainText = iodata() -

Decrypt CipherText according to Type block cipher.

-

May throw exception notsup in case the chosen Type - is not supported by the underlying OpenSSL implementation.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths and blocksizes see the + User's Guide. +

@@ -251,10 +423,10 @@ block_encrypt(aes_gcm, Key, Ivec, {AAD, PlainText, TagLength}) -> {CipherText, CipherTag} Encrypt PlainText according to Type block cipher - Type = block_cipher() - AeadType = aead_cipher() - Key = block_key() - PlainText = iodata() + Type = block_cipher_with_iv() + AeadType = aead_cipher() + Key = key() | des3_key() + PlainText = iodata() AAD = IVec = CipherText = CipherTag = binary() TagLength = 1..16 @@ -264,8 +436,11 @@

In AEAD (Authenticated Encryption with Associated Data) mode, encrypt PlainTextaccording to Type block cipher and calculate CipherTag that also authenticates the AAD (Associated Authenticated Data).

-

May throw exception notsup in case the chosen Type - is not supported by the underlying OpenSSL implementation.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths, iv-sizes and blocksizes see the + User's Guide. +

@@ -274,10 +449,10 @@ block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) -> PlainText | error Decrypt CipherText according to Type block cipher - Type = block_cipher() - AeadType = aead_cipher() - Key = block_key() - PlainText = iodata() + Type = block_cipher_with_iv() + AeadType = aead_cipher() + Key = key() | des3_key() + PlainText = iodata() AAD = IVec = CipherText = CipherTag = binary() @@ -287,19 +462,17 @@ CipherTextaccording to Type block cipher and check the authenticity the PlainText and AAD (Associated Authenticated Data) using the CipherTag. May return error if the decryption or validation fail's

-

May throw exception notsup in case the chosen Type - is not supported by the underlying OpenSSL implementation.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

+

For keylengths, iv-sizes and blocksizes see the + User's Guide. +

- bytes_to_integer(Bin) -> Integer + Convert binary representation, of an integer, to an Erlang integer. - - Bin = binary() - as returned by crypto functions - - Integer = integer() -

Convert binary representation, of an integer, to an Erlang integer.

@@ -307,17 +480,8 @@ - compute_key(Type, OthersPublicKey, MyKey, Params) -> SharedSecret + Computes the shared secret - - Type = dh | ecdh | srp - OthersPublicKey = dh_public() | ecdh_public() | srp_public() - MyKey = dh_private() | ecdh_private() | {srp_public(),srp_private()} - Params = dh_params() | ecdh_params() | ed_named_curves_ecdh() | SrpUserParams | SrpHostParams - SrpUserParams = {user, [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | [Scrambler:binary()]]} - SrpHostParams = {host, [Verifier::binary(), Prime::binary(), Version::atom() | [Scrambler::binary]]} - SharedSecret = binary() -

Computes the shared secret from the private key and the other party's public key. See also public_key:compute_key/2 @@ -326,85 +490,61 @@ - exor(Data1, Data2) -> Result + XOR data - - Data1, Data2 = iodata() - Result = binary() -

Performs bit-wise XOR (exclusive or) on the data supplied.

 - - generate_key(Type, Params) -> {PublicKey, PrivKeyOut} - generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut} + + + + Generates a public key of type Type - - Type = dh | ecdh | rsa | srp - Params = dh_params() | ecdh_params() | ed_named_curves_ecdh()| RsaParams | SrpUserParams | SrpHostParams - RsaParams = {ModulusSizeInBits::integer(), PublicExponent::key_value()} - SrpUserParams = {user, [Generator::binary(), Prime::binary(), Version::atom()]} - SrpHostParams = {host, [Verifier::binary(), Generator::binary(), Prime::binary(), Version::atom()]} - PublicKey = dh_public() | ecdh_public() | rsa_public() | srp_public() - PrivKeyIn = undefined | dh_private() | ecdh_private() | srp_private() - PrivKeyOut = dh_private() | ecdh_private() | rsa_private() | srp_private() -

Generates a public key of type Type. See also public_key:generate_key/1. - May throw exception an exception of class error: + May raise exception:

- badarg: an argument is of wrong type or has an illegal value, - low_entropy: the random generator failed due to lack of secure "randomness", - computation_failed: the computation fails of another reason than low_entropy. + error:badarg: an argument is of wrong type or has an illegal value, + error:low_entropy: the random generator failed due to lack of secure "randomness", + error:computation_failed: the computation fails of another reason than low_entropy.

RSA key generation is only available if the runtime was built with dirty scheduler support. Otherwise, attempting to - generate an RSA key will throw exception error:notsup.

+ generate an RSA key will raise exception error:notsup.

 - hash(Type, Data) -> Digest + - - Type = md4 | hash_algorithms() - Data = iodata() - Digest = binary() -

Computes a message digest of type Type from Data.

-

May throw exception notsup in case the chosen Type - is not supported by the underlying OpenSSL implementation.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

 - hash_init(Type) -> Context + - - Type = md4 | hash_algorithms() -

Initializes the context for streaming hash operations. Type determines which digest to use. The returned context should be used as argument to hash_update.

-

May throw exception notsup in case the chosen Type - is not supported by the underlying OpenSSL implementation.

+

May raise exception error:notsup in case the chosen Type + is not supported by the underlying libcrypto implementation.

 - hash_update(Context, Data) -> NewContext + - - Data = iodata() -

Updates the digest represented by Context using the given Data. Context must have been generated using hash_init @@ -413,12 +553,10 @@ or hash_final.

 + - hash_final(Context) -> Digest + - - Digest = binary() -

Finalizes the hash operation referenced by Context returned from a previous call to hash_update. @@ -428,16 +566,9 @@ - hmac(Type, Key, Data) -> Mac - hmac(Type, Key, Data, MacLength) -> Mac + + - - Type = hash_algorithms() - except ripemd160 - Key = iodata() - Data = iodata() - MacLength = integer() - Mac = binary() -

Computes a HMAC of type Type from Data using Key as the authentication key.

MacLength @@ -446,13 +577,8 @@ - hmac_init(Type, Key) -> Context + - - Type = hash_algorithms() - except ripemd160 - Key = iodata() - Context = binary() -

Initializes the context for streaming HMAC operations. Type determines which hash function to use in the HMAC operation. Key is the authentication @@ -461,12 +587,8 @@ - hmac_update(Context, Data) -> NewContext + - - Context = NewContext = binary() - Data = iodata() -

Updates the HMAC represented by Context using the given Data. Context must have been generated using an HMAC init function (such as @@ -479,16 +601,13 @@ 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 - OpenSSL API.

+ libcrypto API.

 - hmac_final(Context) -> Mac + - - Context = Mac = binary() -

Finalizes the HMAC operation referenced by Context. The size of the resultant MAC is determined by the type of hash function used to generate it.

@@ -496,12 +615,8 @@ - hmac_final_n(Context, HashLen) -> Mac + - - Context = Mac = binary() - HashLen = non_neg_integer() -

Finalizes the HMAC operation referenced by Context. HashLen must be greater than zero. Mac will be a binary with at most HashLen 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 HashLen bytes.

@@ -509,16 +624,9 @@ - cmac(Type, Key, Data) -> Mac - cmac(Type, Key, Data, MacLength) -> Mac + + Calculates the Cipher-based Message Authentication Code. - - Type = block_cipher() - Key = iodata() - Data = iodata() - MacLength = integer() - Mac = binary() -

Computes a CMAC of type Type from Data using Key as the authentication key.

MacLength @@ -527,20 +635,17 @@ - info_fips() -> Status + Provides information about the FIPS operating status. - - Status = enabled | not_enabled | not_supported -

Provides information about the FIPS operating status of - crypto and the underlying OpenSSL library. If crypto was built + crypto and the underlying libcrypto library. If crypto was built with FIPS support this can be either enabled (when running in FIPS mode) or not_enabled. For other builds this value is always not_supported.

In FIPS mode all non-FIPS compliant algorithms are - disabled and throw exception not_supported. Check + disabled and raise exception error:notsup. Check supports that in FIPS mode returns the restricted list of available algorithms.

@@ -549,13 +654,8 @@ - info_lib() -> [{Name,VerNum,VerStr}] + Provides information about the libraries used by crypto. - - Name = binary() - VerNum = integer() - VerStr = binary() -

Provides the name and version of the libraries used by crypto.

Name is the name of the library. VerNum is @@ -568,50 +668,36 @@

From OTP R16 the numeric version represents the version of the OpenSSL header files (openssl/opensslv.h) used when crypto was compiled. - The text variant represents the OpenSSL library used at runtime. + The text variant represents the libcrypto library used at runtime. In earlier OTP versions both numeric and text was taken from the library.

- mod_pow(N, P, M) -> Result + Computes the function: N^P mod M - - N, P, M = binary() | integer() - Result = binary() | error -

Computes the function N^P mod M.

 - next_iv(Type, Data) -> NextIVec - next_iv(Type, Data, IVec) -> NextIVec - - - Type = des_cbc | des3_cbc | aes_cbc | des_cfb - Data = iodata() - IVec = NextIVec = binary() - - -

Returns the initialization vector to be used in the next - iteration of encrypt/decrypt of type Type. Data is the - encrypted data from the previous iteration step. The IVec - argument is only needed for des_cfb as the vector used - in the previous iteration step.

- + + + + +

Returns the initialization vector to be used in the next + iteration of encrypt/decrypt of type Type. Data is the + encrypted data from the previous iteration step. The IVec + argument is only needed for des_cfb as the vector used + in the previous iteration step.

+ - poly1305(Key, Data) -> Mac + - - Key = iodata() - Data = iodata() - Mac = binary() -

Computes a POLY1305 message authentication code (Mac) from Data using Key as the authentication key.

@@ -619,15 +705,8 @@ - private_decrypt(Type, CipherText, PrivateKey, Padding) -> PlainText + Decrypts CipherText using the private Key. - - Type = rsa - CipherText = binary() - PrivateKey = rsa_private() | engine_key_ref() - Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding - PlainText = binary() -

Decrypts the CipherText, encrypted with public_encrypt/4 (or equivalent function) @@ -640,34 +719,8 @@ - privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey - Fetches a public key from an Engine stored private key. - - Type = rsa | dss - EnginePrivateKeyRef = engine_key_ref() - PublicKey = rsa_public() | dss_public() - - -

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. -

- - - - - private_encrypt(Type, PlainText, PrivateKey, Padding) -> CipherText + Encrypts PlainText using the private Key. - - Type = rsa - PlainText = binary() - The size of the PlainText must be less - than byte_size(N)-11 if rsa_pkcs1_padding is - used, and byte_size(N) if rsa_no_padding is - used, where N is public modulus of the RSA key. - PrivateKey = rsa_private() | engine_key_ref() - Padding = rsa_pkcs1_padding | rsa_no_padding - CipherText = binary() -

Encrypts the PlainText using the PrivateKey and returns the ciphertext. This is a low level signature operation @@ -677,16 +730,10 @@

+ - public_decrypt(Type, CipherText, PublicKey, Padding) -> PlainText + Decrypts CipherText using the public Key. - - Type = rsa - CipherText = binary() - PublicKey = rsa_public() | engine_key_ref() - Padding = rsa_pkcs1_padding | rsa_no_padding - PlainText = binary() -

Decrypts the CipherText, encrypted with private_encrypt/4(or equivalent function) @@ -699,19 +746,8 @@ - public_encrypt(Type, PlainText, PublicKey, Padding) -> CipherText + Encrypts PlainText using the public Key. - - Type = rsa - PlainText = binary() - The size of the PlainText must be less - than byte_size(N)-11 if rsa_pkcs1_padding is - used, and byte_size(N) if rsa_no_padding is - used, where N is public modulus of the RSA key. - PublicKey = rsa_public() | engine_key_ref() - Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding - CipherText = binary() -

Encrypts the PlainText (message digest) using the PublicKey and returns the CipherText. This is a low level signature operation @@ -722,18 +758,15 @@ - rand_seed(Seed) -> ok + Set the seed for random bytes generation - - Seed = binary() -

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 strong_rand_bytes/1 - throws low_entropy

+ raises error:low_entropy

 @@ -751,36 +784,15 @@ - sign(Algorithm, DigestType, Msg, Key) -> binary() - sign(Algorithm, DigestType, Msg, Key, Options) -> binary() - Create digital signature. - - Algorithm = rsa | dss | ecdsa - Msg = binary() | {digest,binary()} - The msg is either the binary "cleartext" data to be - signed or it is the hashed value of "cleartext" i.e. the - digest (plaintext). - DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type() - Key = rsa_private() | dss_private() | [ecdh_private(),ecdh_params()] | engine_key_ref() - Options = sign_options() - - -

Creates a digital signature.

-

Algorithm dss can only be used together with digest type - sha.

-

See also public_key:sign/3.

- - - - - start() -> ok + Equivalent to application:start(crypto).

Equivalent to application:start(crypto).

 + - stop() -> ok + Equivalent to application:stop(crypto).

Equivalent to application:stop(crypto).

@@ -788,23 +800,20 @@ - strong_rand_bytes(N) -> binary() + Generate a binary of random bytes - - N = integer() -

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 RAND_bytes method from OpenSSL.

-

May throw exception low_entropy in case the random generator +

May raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness".

 - rand_seed() -> rand:state() + Strong random number generation plugin state

@@ -820,7 +829,7 @@

When using the state object from this function the rand functions using it - may throw exception low_entropy in case the random generator + may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness".

Example

@@ -832,7 +841,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - rand_seed_s() -> rand:state() + Strong random number generation plugin state

@@ -846,7 +855,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

When using the state object from this function the rand functions using it - may throw exception low_entropy in case the random generator + may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness".

@@ -885,7 +894,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

When using the state object from this function the rand functions using it - may throw exception low_entropy in case the random generator + may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness".

@@ -930,7 +939,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[

When using the state object from this function the rand functions using it - may throw exception low_entropy in case the random generator + may raise exception error:low_entropy in case the random generator failed due to lack of secure "randomness".

@@ -961,45 +970,36 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - stream_init(Type, Key) -> State + - - Type = rc4 - State = opaque() - Key = iodata() -

Initializes the state for use in RC4 stream encryption stream_encrypt and stream_decrypt

+

For keylengths see the + User's Guide. +

- stream_init(Type, Key, IVec) -> State + - - Type = aes_ctr | chacha20 - State = opaque() - Key = iodata() - IVec = binary() -

Initializes the state for use in streaming AES encryption using Counter mode (CTR). Key is the AES key and must be either 128, 192, or 256 bits long. IVec is an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with stream_encrypt and stream_decrypt.

+

For keylengths and iv-sizes see the + User's Guide. +

- stream_encrypt(State, PlainText) -> { NewState, CipherText} + - - Text = iodata() - CipherText = binary() -

Encrypts PlainText according to the stream cipher Type specified in stream_init/3. Text can be any number of bytes. The initial State is created using @@ -1009,12 +1009,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - stream_decrypt(State, CipherText) -> { NewState, PlainText } + - - CipherText = iodata() - PlainText = binary() -

Decrypts CipherText according to the stream cipher Type specified in stream_init/3. PlainText can be any number of bytes. The initial State is created using @@ -1024,60 +1020,54 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - supports() -> AlgorithmList + Provide a list of available crypto algorithms. - - AlgorithmList = [{hashs, [hash_algorithms()]}, - {ciphers, [cipher_algorithms()]}, - {public_keys, [public_key_algorithms()]}, - {macs, [mac_algorithms()]}] - -

Can be used to determine which crypto algorithms that are supported - by the underlying OpenSSL library

+ by the underlying libcrypto library

 - ec_curves() -> EllipticCurveList + Provide a list of available named elliptic curves. - - EllipticCurveList = [ec_named_curve()] -

Can be used to determine which named elliptic curves are supported.

 - ec_curve(NamedCurve) -> EllipticCurve + Get the defining parameters of a elliptic curve. - - NamedCurve = ec_named_curve() - EllipticCurve = ec_explicit_curve() -

Return the defining parameters of a elliptic curve.

 - - verify(Algorithm, DigestType, Msg, Signature, Key) -> boolean() - verify(Algorithm, DigestType, Msg, Signature, Key, Options) -> boolean() + + + + Create digital signature. + +

Creates a digital signature.

+

The msg is either the binary "cleartext" data to be + signed or it is the hashed value of "cleartext" i.e. the + digest (plaintext).

+

Algorithm dss can only be used together with digest type + sha.

+

See also public_key:sign/3.

+ + + + + + Verifies a digital signature. - - Algorithm = rsa | dss | ecdsa - Msg = binary() | {digest,binary()} - The msg is either the binary "cleartext" data - or it is the hashed value of "cleartext" i.e. the digest (plaintext). - DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type() - Signature = binary() - Key = rsa_public() | dss_public() | [ecdh_public(),ecdh_params()] | engine_key_ref() - Options = sign_options() -

Verifies a digital signature

+

The msg is either the binary "cleartext" data to be + signed or it is the hashed value of "cleartext" i.e. the + digest (plaintext).

Algorithm dss can only be used together with digest type sha.

@@ -1087,17 +1077,24 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - engine_get_all_methods() -> Result + + Fetches a public key from an Engine stored private key. + +

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. +

+ + + + + Return list of all possible engine methods - - Result = [EngineMethod::atom()] -

Returns a list of all possible engine methods.

- May throw exception notsup in case there is + May raise exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1108,13 +1105,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - engine_load(EngineId, PreCmds, PostCmds) -> Result + Dynamical load an encryption engine - - EngineId = unicode:chardata() - PreCmds, PostCmds = [{unicode:chardata(), unicode:chardata()}] - Result = {ok, Engine::engine_ref()} | {error, Reason::term()} -

Loads the OpenSSL engine given by EngineId if it is available and then returns ok and @@ -1123,8 +1115,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ returned if the engine can't be loaded.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1135,22 +1127,16 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result + Dynamical load an encryption engine - - EngineId = unicode:chardata() - PreCmds, PostCmds = [{unicode:chardata(), unicode:chardata()}] - EngineMethods = [engine_method_type()] - Result = {ok, Engine::engine_ref()} | {error, Reason::term()} -

Loads the OpenSSL engine given by EngineId if it is available and then returns ok and an engine handle. An error tuple is returned if the engine can't be loaded.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1161,20 +1147,16 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - engine_unload(Engine) -> Result + Dynamical load an encryption engine - - Engine = engine_ref() - Result = ok | {error, Reason::term()} -

Unloads the OpenSSL engine given by Engine. An error tuple is returned if the engine can't be unloaded.

- The function throws a badarg if the parameter is in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameter is in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1185,20 +1167,16 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - engine_by_id(EngineId) -> Result + Get a reference to an already loaded engine - - EngineID = unicode:chardata()engine_ref() - Result = {ok, Engine::engine_ref()} | {error, Reason::term()} -

Get a reference to an already loaded engine with EngineId. An error tuple is returned if the engine can't be unloaded.

- The function throws a badarg if the parameter is in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameter is in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1209,14 +1187,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result + Sends ctrl commands to an OpenSSL engine - - Engine = engine_ref() - CmdName = unicode:chardata() - CmdArg = unicode:chardata() - Result = ok | {error, Reason::term()} -

Sends ctrl commands to the OpenSSL engine given by Engine. @@ -1224,23 +1196,16 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ Optional set to false.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

- engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) -> Result + Sends ctrl commands to an OpenSSL engine - - Engine = engine_ref() - CmdName = unicode:chardata() - CmdArg = unicode:chardata() - Optional = boolean() - Result = ok | {error, Reason::term()} -

Sends ctrl commands to the OpenSSL engine given by Engine. @@ -1252,91 +1217,72 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ false.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

- engine_add(Engine) -> Result + Add engine to OpenSSL internal list - - Engine = engine_ref() - Result = ok | {error, Reason::term()} -

Add the engine to OpenSSL's internal list.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

- engine_remove(Engine) -> Result + Remove engine to OpenSSL internal list - - Engine = engine_ref() - Result = ok | {error, Reason::term()} -

Remove the engine from OpenSSL's internal list.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

- engine_get_id(Engine) -> EngineId + Fetch engine ID - - Engine = engine_ref() - EngineId = unicode:chardata() -

Return the ID for the engine, or an empty binary if there is no id set.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

- engine_get_name(Engine) -> EngineName + Fetch engine name - - Engine = engine_ref() - EngineName = unicode:chardata() -

Return the name (eg a description) for the engine, or an empty binary if there is no name set.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

- engine_list() -> Result + List the known engine ids - - Result = [EngineId::unicode:chardata()] -

List the id's of all engines in OpenSSL's internal list.

- It may also throw the exception notsup in case there is + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1344,20 +1290,15 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ in the User's Guide.

- May throw exception notsup in case engine functionality is not supported by the underlying + May raise exception error:notsup in case engine functionality is not supported by the underlying OpenSSL implementation.

- ensure_engine_loaded(EngineId, LibPath) -> Result + Ensure encryption engine just loaded once - - EngineId = unicode:chardata() - LibPath = unicode:chardata() - Result = {ok, Engine::engine_ref()} | {error, Reason::term()} -

Loads the OpenSSL engine given by EngineId and the path to the dynamic library @@ -1366,8 +1307,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ returned if the engine can't be loaded.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1378,14 +1319,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result + Ensure encryption engine just loaded once - - EngineId = unicode:chardata() - LibPath = unicode:chardata() - EngineMethods = [engine_method_type()] - Result = {ok, Engine::engine_ref()} | {error, Reason::term()} -

Loads the OpenSSL engine given by EngineId and the path to the dynamic library @@ -1395,8 +1330,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ An error tuple is returned if the engine can't be loaded.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1407,12 +1342,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - ensure_engine_unloaded(Engine) -> Result + Unload an engine loaded with the ensure function - - Engine = engine_ref() - Result = ok | {error, Reason::term()} -

Unloads an engine loaded with the ensure_engine_loaded function. @@ -1422,8 +1353,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ returned if the engine can't be unloaded.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1434,13 +1365,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - ensure_engine_unloaded(Engine, EngineMethods) -> Result + Unload an engine loaded with the ensure function - - Engine = engine_ref() - EngineMethods = [engine_method_type()] - Result = ok | {error, Reason::term()} -

Unloads an engine loaded with the ensure_engine_loaded function. @@ -1448,8 +1374,8 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ An error tuple is returned if the engine can't be unloaded.

- The function throws a badarg if the parameters are in wrong format. - It may also throw the exception notsup in case there is + The function raises a error:badarg if the parameters are in wrong format. + It may also raise the exception error:notsup in case there is no engine support in the underlying OpenSSL implementation.

@@ -1461,75 +1387,5 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + diff --git a/lib/crypto/doc/src/engine_keys.xml b/lib/crypto/doc/src/engine_keys.xml index 38714fed8a..4f7b0243fb 100644 --- a/lib/crypto/doc/src/engine_keys.xml +++ b/lib/crypto/doc/src/engine_keys.xml @@ -62,7 +62,7 @@ on the Engine loaded an Erlang map is constructed with the Engine reference, the key reference and possibly a key passphrase if - needed by the Engine. See the Reference Manual for + needed by the Engine. See the Reference Manual for details of the map. -- cgit v1.2.3