From cb1305212e71855890bbfb0a509a007543529d24 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 3 May 2013 10:20:37 +0200 Subject: ssl & crypto: Generalize the remaining crypto API --- lib/crypto/doc/src/crypto.xml | 106 ++++++++++++++++++++------------------ lib/crypto/doc/src/crypto_app.xml | 36 ++++--------- 2 files changed, 67 insertions(+), 75 deletions(-) (limited to 'lib/crypto/doc') diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 0fb53346ca..df765ade87 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -30,23 +30,24 @@

-

Hash functions - The MD4 Message Digest Algorithm (RFC 1320), +

Hash functions - + Secure Hash Standard, The MD5 Message Digest Algorithm (RFC 1321) and - Secure Hash Standard + The MD4 Message Digest Algorithm (RFC 1320)

Hmac functions - Keyed-Hashing for Message Authentication (RFC 2104)

-

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

+

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

RSA encryption RFC 1321

-

Digital signatures Digital Signature Standard (DSS) and Elliptic Curve Digital +

Digital signatures Digital Signature Standard (DSS) and Elliptic Curve Digital Signature Algorithm (ECDSA)

@@ -57,13 +58,7 @@
DATA TYPES - -

byte() = 0 ... 255

- -

ioelem() = byte() | binary() | iolist()

- -

iolist() = [ioelem()]

- +

key_value() = integer() | binary()

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

@@ -74,7 +69,7 @@ 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.

+ is the CRT coefficient. Terminology is taken from RFC 3447.

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

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

@@ -137,25 +132,28 @@

block_key() = aes_key() | blowfish_key() | des_key()| des3_key()

-

aes_key() = binary() Key length is 128, 192 or 256 bits

+

aes_key() = iodata() Key length is 128, 192 or 256 bits

-

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

+

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

-

blowfish_key() = binary() Variable key length from 32 bits up to 448 bits

+

blowfish_key() = iodata() Variable key length from 32 bits up to 448 bits

-

des_key() = binary() Key length is 64 bits (in CBC mod only 8 bits are used)

+

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 mod only 8 bits are used)

+

des3_key() = [binary(), binary(), binary()] Each key part is 64 bits (in CBC mode only 8 bits are used)

+ +

message_digest_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 md4 is aslo supported for hash_init/1 and hash/2. + Note that both md4 and md5 are recommended only for compatibility with existing applications. +

- algorithms() -> [atom()] + algorithms() -> [message_digest_algorithms() | md4 | ec] Provide a list of available crypto algorithms. -

Provides the available crypto algorithms in terms of a list - of atoms. This is interesting as older versions of the openssl - crypto library may not support all algorithms used in the crypto API.

+

Can be used to determine if the crypto library has support for elliptic curve (ec) and + which message digest algorithms that are supported.

 @@ -164,7 +162,7 @@ Encrypt PlainTextaccording to Type block cipher Key = block_key() - PlainText = iodata() | binary() + PlainText = iodata() IVec = CipherText = binary() @@ -179,7 +177,7 @@ Decrypt CipherTextaccording to Type block cipher Key = block_key() - PlainText = iodata() | binary() + PlainText = iodata() IVec = CipherText = binary() @@ -201,6 +199,7 @@

Computes the shared secret from the private key and the other party's public key. + See also public_key:compute_key/2

@@ -209,7 +208,7 @@ exor(Data1, Data2) -> Result XOR data - Data1, Data2 = iolist() | binary() + Data1, Data2 = iodata() Result = binary() @@ -229,6 +228,7 @@

Generates public keys of type Type. + See also public_key:generate_key/1

@@ -237,7 +237,7 @@ hash(Type, Data) -> Digest - Type = md4 | md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 + Type = md4 | message_digest_algorithms() Data = iodata() Digest = binary() @@ -252,7 +252,7 @@ hash_init(Type) -> Context - Type = md4 | md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 + Type = md4 | message_digest_algorithms()

Initializes the context for streaming hash operations. Type determines @@ -296,7 +296,7 @@ hmac(Type, Key, Data, MacLength) -> Mac - Type = md5 | sha | sha224 | sha256 | sha384 | sha512 + Type = message_digest_algorithms() Key = iodata() Data = iodata() MacLength = integer() @@ -313,8 +313,8 @@ hmac_init(Type, Key) -> Context - Type = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 - Key = iolist() | binary() + Type = message_digest_algorithms() + Key = iodata() Context = binary() @@ -329,13 +329,17 @@ Context = NewContext = binary() - Data = iolist() | 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 hmac_init). Data can be any length. NewContext - must be passed into the next call to hmac_update.

+ must be passed into the next call to hmac_update + or to one of the functions hmac_final and + hmac_final_n +

+ @@ -391,10 +395,10 @@ - mod_exp_prime(N, P, M) -> Result + mod_pow(N, P, M) -> Result Computes the function: N^P mod M - N, P, M = binary() + N, P, M = binary() | integer() Result = binary() | error @@ -433,6 +437,7 @@ message. The Padding is the padding mode that was used to encrypt the data, see public_encrypt/3. + See also public_key:decrypt_private/[2,3]

@@ -455,6 +460,7 @@ The size of the Msg must be less than byte_size(N)-11 if rsa_pkcs1_padding is used, and byte_size(N) if rsa_no_padding is used. + See also public_key:encrypt_private/[2,3]

@@ -475,6 +481,7 @@ message. The Padding is the padding mode that was used to encrypt the data, see private_encrypt/3. + See also public_key:decrypt_public/[2,3]

@@ -501,6 +508,7 @@ rsa_pkcs1_padding is used, byte_size(N)-41 if rsa_pkcs1_oaep_padding is used and byte_size(N) if rsa_no_padding is used. + See also public_key:encrypt_public/[2,3]

@@ -545,6 +553,7 @@

Creates a digital signature.

+ See also public_key:sign/3 @@ -613,36 +622,32 @@ - stream_encrypt(Type, State, PlainText) -> { NewState, CipherText} + stream_encrypt(State, PlainText) -> { NewState, CipherText} - Type = stream_cipher() - Text = iolist() | binary() + Text = iodata() CipherText = binary() -

Encrypts PlainText according to the stream cipher Type. - Text can be any number of bytes. State is initialized using - stream_init on - the next invocation of this function the returned State shall be - given as input and so on until the end of the stream is reached.

+

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 + stream_init. + NewState must be passed into the next call to stream_encrypt.

 - stream_decrypt(Type, State, CipherText) -> { NewState, PlainText } + stream_decrypt(State, CipherText) -> { NewState, PlainText } - Type = stream_cipher() - CipherText = iodata() | binary() + CipherText = iodata() PlainText = binary() -

Decrypts CipherText according to the stream cipher Type. - PlainText can be any number of bytes. State is initialized using - stream_init on - the next invocation of this function the returned State shall be - given as input and so on until the end of the stream is reached.

+

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 + stream_init. + NewState must be passed into the next call to stream_encrypt.

 @@ -660,6 +665,7 @@

Verifies a digital signature

+ See also public_key:verify/3 diff --git a/lib/crypto/doc/src/crypto_app.xml b/lib/crypto/doc/src/crypto_app.xml index 20f4ed5c45..6d26076c04 100644 --- a/lib/crypto/doc/src/crypto_app.xml +++ b/lib/crypto/doc/src/crypto_app.xml @@ -29,37 +29,23 @@ crypto The Crypto Application -

The purpose of the Crypto application is to provide erlang - acess to crypto graphic functions in openssl. +

The purpose of the Crypto application is to provide an Erlang API + to cryptographic functions, see crypto(3). + Note that the API is on a fairly low level and there are some + corresponding API functions available in public_key(3), + on a higher abstraction level, that uses the crypto application in its implementation.

- Configuration -

The following environment configuration parameters are defined - for the Crypto application. Refer to application(3) for more - information about configuration parameters. -

- - ]]> - -

Causes debug information to be written to standard - error or standard output. Default is false. -

- - -
+ DEPENDENCIES -
- OpenSSL libraries -

The current implementation of the Erlang Crypto application is - based on the OpenSSL package version 0.9.8 or higher. - There are source and binary releases on the web. -

+

The current crypto implementation uses nifs to interface OpenSSLs crypto library + and requires OpenSSL package version 0.9.8 or higher.

Source releases of OpenSSL can be downloaded from the OpenSSL project home page, - or mirror sites listed there. -

-
+ or mirror sites listed there. +

+
SEE ALSO -- cgit v1.2.3