From 557151814b33cb3ed6c245e27f3b80e24284f19e Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 5 Jun 2013 18:02:34 +0200 Subject: crypto & public_key: Clearify documentation. --- lib/crypto/doc/src/crypto.xml | 113 ++++++++++++++++------------------ lib/public_key/doc/src/public_key.xml | 17 +++-- 2 files changed, 64 insertions(+), 66 deletions(-) diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 2df407018e..99d167bfa9 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -208,7 +208,7 @@

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

@@ -240,7 +240,7 @@

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

@@ -269,7 +269,7 @@

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

+ to hash_update.

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

 @@ -283,10 +283,10 @@

Updates the digest represented by Context using the given Data. Context - must have been generated using hash_init + must have been generated using hash_init or a previous call to this function. Data can be any length. NewContext must be passed into the next call to hash_update - or hash_final.

+ or hash_final.

 @@ -297,7 +297,7 @@

Finalizes the hash operation referenced by Context returned - from a previous call to hash_update. + from a previous call to hash_update. The size of Digest is determined by the type of hash function used to generate it.

 @@ -346,10 +346,10 @@

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 + hmac_init). Data can be any length. NewContext must be passed into the next call to hmac_update - or to one of the functions hmac_final and - hmac_final_n + or to one of the functions hmac_final and + hmac_final_n

@@ -447,36 +447,36 @@ PlainText = binary() -

Decrypts the ChipherText (usually a session key encrypted with - public_encrypt/3) - using the PrivateKey and returns the - 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] +

Decrypts the ChipherText, encrypted with + public_encrypt/4 (or equivalent function) + using the PrivateKey, 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 public_key:decrypt_private/[2,3]

- + private_encrypt(Type, PlainText, PrivateKey, Padding) -> ChipherText - Encrypts Msg using the private Key. + 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() Padding = rsa_pkcs1_padding | rsa_no_padding ChipherText = binary()

Encrypts the PlainText using the PrivateKey - and returns the cipher. The Padding decides what padding mode is used, - rsa_pkcs1_padding is PKCS #1 v1.5 currently the most - used mode. - 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, where N is public modulus of the RSA key. - See also public_key:encrypt_private/[2,3] + and returns the ciphertext. This is a low level signature operation + used for instance by older versions of the SSL protocol. See + also public_key:encrypt_private/[2,3]

@@ -491,42 +491,35 @@ PlainText = binary() -

Decrypts the ChipherText (encrypted with - private_encrypt/3) - using the PrivateKey and returns the - 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] +

Decrypts the ChipherText, encrypted with + private_encrypt/4(or equivalent function) + using the PrivateKey, 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 public_key:decrypt_public/[2,3]

public_encrypt(Type, PlainText, PublicKey, Padding) -> ChipherText - Encrypts Msg using the public Key. + 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() Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding ChipherText = binary() -

Encrypts the PlainText (usually a session key) using - the PublicKey and returns the CipherText. The - Padding decides what padding mode is used, - rsa_pkcs1_padding is PKCS #1 v1.5 currently the most - used mode and rsa_pkcs1_oaep_padding is EME-OAEP as - defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty encoding - parameter. This mode is recommended for all new - applications. The size of the Msg must be less than - byte_size(N)-11 if 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, where N is public modulus of the RSA key. - See also public_key:encrypt_public/[2,3] +

Encrypts the PlainText (message digest) using the PublicKey + and returns the CipherText. This is a low level signature operation + used for instance by older versions of the SSL protocol. See also public_key:encrypt_public/[2,3]

@@ -563,9 +556,9 @@ Algorithm = rsa | dss | ecdsa Msg = binary() | {digest,binary()} - The msg is either the binary "plain text" data to be - signed or it is the hashed value of "plain text" i.e. the - digest. + 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 = digest_type() Key = rsa_private() | dss_private() | [ecdh_private(),ecdh_params()] @@ -573,7 +566,7 @@

Creates a digital signature.

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

- See also public_key:sign/3 + See also public_key:sign/3 @@ -617,8 +610,8 @@

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

+ stream_encrypt and + stream_decrypt

 @@ -635,8 +628,8 @@

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 bts long. IVec is an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with - stream_encrypt and - stream_decrypt.

+ stream_encrypt and + stream_decrypt.

@@ -650,7 +643,7 @@

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

 @@ -665,7 +658,7 @@

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

 @@ -692,8 +685,8 @@ Algorithm = rsa | dss | ecdsa Msg = binary() | {digest,binary()} - The msg is either the binary "plain text" data - or it is the hashed value of "plain text" i.e. the digest. + The msg is either the binary "cleartext" data + or it is the hashed value of "cleartext" i.e. the digest (plaintext). DigestType = digest_type() Signature = binary() Key = rsa_public() | dss_public() | [ecdh_public(),ecdh_params()] @@ -703,7 +696,7 @@

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

- See also public_key:verify/3 + See also public_key:verify/4 diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index 10c95a39ac..c8236b94ca 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -154,8 +154,8 @@ - compute_key(OthersKey, MyKey)-> - compute_key(OthersKey, MyKey, Params)-> + compute_key(OthersKey, MyKey)-> + compute_key(OthersKey, MyKey, Params)-> Compute shared secret OthersKey = #'ECPoint'{} | binary(), MyKey = #'ECPrivateKey'{} | binary() @@ -176,7 +176,8 @@ Options = public_crypt_options() -

Public key decryption using the private key.

+

Public key decryption using the private key. See also crypto:private_decrypt/4

 @@ -190,7 +191,8 @@ Options = public_crypt_options() -

Public key decryption using the public key.

+

Public key decryption using the public key. See also crypto:public_decrypt/4

 @@ -304,7 +306,9 @@ Key = rsa_private_key() -

Public key encryption using the private key.

+

Public key encryption using the private key. + See also crypto:private_encrypt/4

 @@ -316,7 +320,8 @@ Key = rsa_public_key() -

Public key encryption using the public key.

+

Public key encryption using the public key. See also crypto:public_encrypt/4

 -- cgit v1.2.3