crypto

19992018 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. crypto

crypto Crypto Functions

This module provides a set of cryptographic functions.

Hash functions

SHA1, SHA2 Secure Hash Standard [FIPS PUB 180-4] SHA3 SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [FIPS PUB 202] BLAKE2 BLAKE2 — fast secure hashing MD5 The MD5 Message Digest Algorithm [RFC 1321] MD4 The MD4 Message Digest Algorithm [RFC 1320]

MACs - Message Authentication Codes

Hmac functions Keyed-Hashing for Message Authentication [RFC 2104] Cmac functions The AES-CMAC Algorithm [RFC 4493] POLY1305 ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]

Symmetric Ciphers

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

Modes

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

Asymetric Ciphers - Public Key Techniques

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

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.

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

Ciphers, new API

Ciphers known by the CRYPTO application when using the new API.

Note that this list might be reduced if the underlying libcrypto does not support all of them.

Ciphers, old API

Ciphers known by the CRYPTO application when using the old API.

Note that this list might be reduced if the underlying libcrypto does not support all of them.

Alternative, old names of ciphers known by the CRYPTO application when using the old API. See Retired cipher names for names to use instead to be prepared for an easy convertion to the new API.

Note that this list might be reduced if the underlying libcrypto does not support all of them.

Digests and hash

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

Elliptic Curves

Note that some curves are disabled if FIPS is enabled.

Parametric curve definition.

Curve definition details.

Keys

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

A key for des3 is a list of three iolists

Always binary() when used as return value

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.

dss_public() = [P, Q, G, Y]

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

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

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

srp_public() = key_integer()

Where is A or B from SRP design

srp_private() = key_integer()

Where is a or b from SRP design

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'

Public Key Ciphers

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

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

The RSA options are experimental.

The exact set of options and there syntax may be changed without prior notice.

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

Public Key Sign and Verify

Algorithms for sign and verify.

Options for sign and verify.

The RSA options are experimental.

The exact set of options and there syntax may be changed without prior notice.

Diffie-Hellman Keys and parameters dh_params() = [P, G] | [P, G, PrivateKeyBitLength] Types for Engines

The result of a call to engine_load/3.

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.

The password of the key stored in an engine.

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

Internal data types

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

Error types

The exception error:badarg signifies that one or more arguments are of wrong data type, or are otherwise badly formed.

The exception error:notsup signifies that the algorithm is known but is not supported by current underlying libcrypto or explicitly disabled when building that.

For a list of supported algorithms, see supports/0.

This is a more developed variant of the older run_time_error().

The exception is:

	  {Tag, {C_FileName,LineNumber}, Description}

	   Tag = badarg | notsup | error
	   C_FileName = string()
	   LineNumber = integer()
	   Description = string()

It is like the older type an exception of the error class. In addition they contain a descriptive text in English. That text is targeted to a developer. Examples are "Bad key size" or "Cipher id is not an atom".

The exception tags are:

badarg

Signifies that one or more arguments are of wrong data type or are otherwise badly formed.

notsup

Signifies that the algorithm is known but is not supported by current underlying libcrypto or explicitly disabled when building that one.

error

An error condition that should not occur, for example a memory allocation failed or the underlying cryptolib returned an error code, for example "Can't initialize context, step 1". Thoose text usually needs searching the C-code to be understood.

To catch the exception, use for example:


	  try crypto:crypto_init(Ciph, Key, IV, true)
	  catch
	      error:{Tag, {C_FileName,LineNumber}, Description} ->
	              do_something(......)
	      .....
	  end

New API

Initializes a series of encryptions or decryptions

As crypto_init/4 but for ciphers without IVs.

Initializes a series of encryptions or decryptions

Part of the new API. Initializes a series of encryptions or decryptions. The actual encryption or decryption is done by crypto_update/2.

For encryption, set the EncryptFlag to true.