diff options
Diffstat (limited to 'lib/crypto/doc/src/crypto.xml')
| -rw-r--r-- | lib/crypto/doc/src/crypto.xml | 227 |
1 files changed, 129 insertions, 98 deletions
diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index df765ade87..99d167bfa9 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -60,6 +60,7 @@ <title>DATA TYPES </title> <p><code>key_value() = integer() | binary() </code></p> + <p>Always <c>binary()</c> when used as return value</p> <p><code>rsa_public() = [key_value()] = [E, N] </code></p> <p> Where E is the public exponent and N is public modulus. </p> @@ -77,21 +78,14 @@ <p><code>dss_private() = [key_value()] = [P, Q, G, X] </code></p> <p>Where P, Q and G are the dss parameters and X is the private key.</p> - <p><code>dss_public() = [key_value()] =[P, Q, G, Y] </code></p> - - <p><code>srp_public() = key_value() </code></p> + <p><code>srp_public() = key_value() </code></p> <p>Where is <c>A</c> or <c>B</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> <p><code>srp_private() = key_value() </code></p> <p>Where is <c>a</c> or <c>b</c> from <url href="http://srp.stanford.edu/design.html">SRP design</url></p> - <p><code>srp_params() = {user, [Generator::binary(), Prime::binary(), Version::atom()]} | - {host, [Verifier::binary(), Generator::binary(), Prime::binary(), Version::atom()]} - | {user, [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | [Scrambler:binary()]]} - | {host,[Verifier::binary(), Prime::binary(), Version::atom() | [Scrambler::binary]]} </code></p> - <p>Where Verifier is <c>v</c>, Generator is <c>g</c> and Prime is<c> N</c>, DerivedKey is <c>X</c>, and Scrambler is - <c>u</c> (optional will be genrated if not provided) from <url href="http://srp.stanford.edu/design.html">SRP design</url> + <c>u</c> (optional will be generated if not provided) from <url href="http://srp.stanford.edu/design.html">SRP design</url> Version = '3' | '6' | '6a' </p> @@ -142,25 +136,23 @@ <p><code>des3_key() = [binary(), binary(), binary()] </code> Each key part is 64 bits (in CBC mode only 8 bits are used)</p> - <p><code> message_digest_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 </code> md4 is aslo supported for hash_init/1 and hash/2. + <p><code>digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512</code></p> + + <p><code> hash_algorithms() = md5 | ripemd160 | sha | sha224 | sha256 | sha384 | sha512 </code> 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. </p> + <p><code> cipher_algorithms() = des_cbc | des_cfb | des3_cbc | des3_cbf | des_ede3 | + blowfish_cbc | blowfish_cfb64 | aes_cbc128 | aes_cfb128| aes_cbc256 | rc2_cbc | aes_ctr| rc4 </code> </p> + <p><code> public_key_algorithms() = rsa |dss | ecdsa | dh | ecdh </code> </p> + </section> <funcs> - <func> - <name>algorithms() -> [message_digest_algorithms() | md4 | ec]</name> - <fsummary>Provide a list of available crypto algorithms.</fsummary> - <desc> - <p> Can be used to determine if the crypto library has support for elliptic curve (ec) and - which message digest algorithms that are supported.</p> - </desc> - </func> - <func> <name>block_encrypt(Type, Key, Ivec, PlainText) -> CipherText</name> <fsummary>Encrypt <c>PlainText</c>according to <c>Type</c> block cipher</fsummary> <type> + <v>Type = block_cipher() </v> <v>Key = block_key() </v> <v>PlainText = iodata() </v> <v>IVec = CipherText = binary()</v> @@ -176,6 +168,7 @@ <name>block_decrypt(Type, Key, Ivec, CipherText) -> PlainText</name> <fsummary>Decrypt <c>CipherText</c>according to <c>Type</c> block cipher</fsummary> <type> + <v>Type = block_cipher() </v> <v>Key = block_key() </v> <v>PlainText = iodata() </v> <v>IVec = CipherText = binary()</v> @@ -186,20 +179,36 @@ </p> </desc> </func> + + <func> + <name>bytes_to_integer(Bin) -> Integer </name> + <fsummary>Convert binary representation, of an integer, to an Erlang integer.</fsummary> + <type> + <v>Bin = binary() - as returned by crypto functions</v> + + <v>Integer = integer() </v> + </type> + <desc> + <p>Convert binary representation, of an integer, to an Erlang integer. + </p> + </desc> + </func> <func> - <name>compute_key(Type, OthersPublicKey, MyPrivateKey, Params) -> SharedSecret</name> + <name>compute_key(Type, OthersPublicKey, MyKey, Params) -> SharedSecret</name> <fsummary>Computes the shared secret</fsummary> <type> <v> Type = dh | ecdh | srp </v> <v>OthersPublicKey = dh_public() | ecdh_public() | srp_public() </v> - <v>MyPrivate = dh_private() | ecdh_private() | srp_private() </v> - <v>Params = dh_params() | edhc_params() | srp_params() </v> + <v>MyKey = dh_private() | ecdh_private() | {srp_public(),srp_private()}</v> + <v>Params = dh_params() | ecdh_params() | SrpUserParams | SrpHostParams</v> + <v>SrpUserParams = {user, [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | [Scrambler:binary()]]} </v> + <v>SrpHostParams = {host, [Verifier::binary(), Prime::binary(), Version::atom() | [Scrambler::binary]]} </v> <v>SharedSecret = binary()</v> </type> <desc> <p>Computes the shared secret from the private key and the other party's public key. - See also <seealso marker="public_key:public_key#compute_key/2">public_key:compute_key/2</seealso> + See also <seealso marker="public_key:public_key#compute_key-2">public_key:compute_key/2</seealso> </p> </desc> </func> @@ -217,18 +226,21 @@ </func> <func> - <name>generate_key(Type, Params) -> {PublicKey, PrivateKey} </name> - <name>generate_key(Type, Params, PrivateKey) -> {PublicKey, PrivateKey} </name> + <name>generate_key(Type, Params) -> {PublicKey, PrivKeyOut} </name> + <name>generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut} </name> <fsummary>Generates a public keys of type <c>Type</c></fsummary> <type> <v> Type = dh | ecdh | srp </v> - <v>Params = dh_params() | edhc_params() | srp_params() </v> + <v>Params = dh_params() | ecdh_params() | SrpUserParams | SrpHostParams </v> + <v>SrpUserParams = {user, [Generator::binary(), Prime::binary(), Version::atom()]}</v> + <v>SrpHostParams = {host, [Verifier::binary(), Generator::binary(), Prime::binary(), Version::atom()]}</v> <v>PublicKey = dh_public() | ecdh_public() | srp_public() </v> - <v>PrivateKey = dh_private() | ecdh_private() | srp_private() </v> + <v>PrivKeyIn = undefined | dh_private() | srp_private() </v> + <v>PrivKeyOut = dh_private() | ecdh_private() | srp_private() </v> </type> <desc> <p>Generates public keys of type <c>Type</c>. - See also <seealso marker="public_key:public_key#generate_key/1">public_key:generate_key/1</seealso> + See also <seealso marker="public_key:public_key#generate_key-1">public_key:generate_key/1</seealso> </p> </desc> </func> @@ -237,7 +249,7 @@ <name>hash(Type, Data) -> Digest</name> <fsummary></fsummary> <type> - <v>Type = md4 | message_digest_algorithms()</v> + <v>Type = md4 | hash_algorithms()</v> <v>Data = iodata()</v> <v>Digest = binary()</v> </type> @@ -252,12 +264,12 @@ <name>hash_init(Type) -> Context</name> <fsummary></fsummary> <type> - <v>Type = md4 | message_digest_algorithms()</v> + <v>Type = md4 | hash_algorithms()</v> </type> <desc> <p>Initializes the context for streaming hash operations. <c>Type</c> determines which digest to use. The returned context should be used as argument - to <seealso marker="#hash_update/2">hash_update</seealso>.</p> + to <seealso marker="#hash_update-2">hash_update</seealso>.</p> <p>May throw exception <c>notsup</c> in case the chosen <c>Type</c> is not supported by the underlying OpenSSL implementation.</p> </desc> @@ -271,10 +283,10 @@ </type> <desc> <p>Updates the digest represented by <c>Context</c> using the given <c>Data</c>. <c>Context</c> - must have been generated using <seealso marker="#hash_init/1">hash_init</seealso> + must have been generated using <seealso marker="#hash_init-1">hash_init</seealso> or a previous call to this function. <c>Data</c> can be any length. <c>NewContext</c> must be passed into the next call to <c>hash_update</c> - or <seealso marker="#hash_final/1">hash_final</seealso>.</p> + or <seealso marker="#hash_final-1">hash_final</seealso>.</p> </desc> </func> <func> @@ -285,7 +297,7 @@ </type> <desc> <p>Finalizes the hash operation referenced by <c>Context</c> returned - from a previous call to <seealso marker="#hash_update/2">hash_update</seealso>. + from a previous call to <seealso marker="#hash_update-2">hash_update</seealso>. The size of <c>Digest</c> is determined by the type of hash function used to generate it.</p> </desc> @@ -296,7 +308,7 @@ <name>hmac(Type, Key, Data, MacLength) -> Mac</name> <fsummary></fsummary> <type> - <v>Type = message_digest_algorithms() </v> + <v>Type = hash_algorithms() - except ripemd160</v> <v>Key = iodata()</v> <v>Data = iodata()</v> <v>MacLength = integer()</v> @@ -313,7 +325,7 @@ <name>hmac_init(Type, Key) -> Context</name> <fsummary></fsummary> <type> - <v>Type = message_digest_algorithms()</v> + <v>Type = hash_algorithms() - except ripemd160</v> <v>Key = iodata()</v> <v>Context = binary()</v> </type> @@ -334,10 +346,10 @@ <desc> <p>Updates the HMAC represented by <c>Context</c> using the given <c>Data</c>. <c>Context</c> must have been generated using an HMAC init function (such as - <seealso marker="#hmac_init/2">hmac_init</seealso>). <c>Data</c> can be any length. <c>NewContext</c> + <seealso marker="#hmac_init-2">hmac_init</seealso>). <c>Data</c> can be any length. <c>NewContext</c> must be passed into the next call to <c>hmac_update</c> - or to one of the functions <seealso marker="#hmac_final/1">hmac_final</seealso> and - <seealso marker="#hmac_final_n/1">hmac_final_n</seealso> + or to one of the functions <seealso marker="#hmac_final-1">hmac_final</seealso> and + <seealso marker="#hmac_final_n-2">hmac_final_n</seealso> </p> </desc> @@ -407,16 +419,20 @@ </func> <func> - <name>next_iv(Type, Data) -> </name> + <name>next_iv(Type, Data) -> NextIVec</name> + <name>next_iv(Type, Data, IVec) -> NextIVec</name> <fsummary></fsummary> <type> - <v>Type = des_cbc | aes_cbc</v> + <v>Type = des_cbc | des3_cbc | aes_cbc | des_cfb</v> <v>Data = iodata()</v> + <v>IVec = NextIVec = binary()</v> </type> <desc> <p>Returns the initialization vector to be used in the next - iteration of encrypt/decrypt of type <c>Type</c>. Data is the - encrypted data from the previous iteration step.</p> + iteration of encrypt/decrypt of type <c>Type</c>. <c>Data</c> is the + encrypted data from the previous iteration step. The <c>IVec</c> + argument is only needed for <c>des_cfb</c> as the vector used + in the previous iteration step.</p> </desc> </func> @@ -431,36 +447,36 @@ <v>PlainText = binary()</v> </type> <desc> - <p>Decrypts the <c>ChipherText</c> (usually a session key encrypted with - <seealso marker="#public_encrypt/3">public_encrypt/3</seealso>) - using the <c>PrivateKey</c> and returns the - message. The <c>Padding</c> is the padding mode that was - used to encrypt the data, - see <seealso marker="#public_encrypt/3">public_encrypt/3</seealso>. - See also <seealso marker="public_key:public_key#decrypt_private/2">public_key:decrypt_private/[2,3]</seealso> + <p>Decrypts the <c>ChipherText</c>, encrypted with + <seealso marker="#public_encrypt-4">public_encrypt/4</seealso> (or equivalent function) + using the <c>PrivateKey</c>, 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 <seealso marker="public_key:public_key#decrypt_private-2">public_key:decrypt_private/[2,3]</seealso> </p> </desc> </func> - + <func> <name>private_encrypt(Type, PlainText, PrivateKey, Padding) -> ChipherText</name> - <fsummary>Encrypts Msg using the private Key.</fsummary> + <fsummary>Encrypts PlainText using the private Key.</fsummary> <type> <v>Type = rsa</v> <v>PlainText = binary()</v> + <d> The size of the <c>PlainText</c> must be less + than <c>byte_size(N)-11</c> if <c>rsa_pkcs1_padding</c> is + used, and <c>byte_size(N)</c> if <c>rsa_no_padding</c> is + used, where N is public modulus of the RSA key.</d> <v>PrivateKey = rsa_private()</v> <v>Padding = rsa_pkcs1_padding | rsa_no_padding</v> <v>ChipherText = binary()</v> </type> <desc> <p>Encrypts the <c>PlainText</c> using the <c>PrivateKey</c> - and returns the cipher. The <c>Padding</c> decides what padding mode is used, - <c>rsa_pkcs1_padding</c> is PKCS #1 v1.5 currently the most - used mode. - The size of the <c>Msg</c> must be less than <c>byte_size(N)-11</c> if - <c>rsa_pkcs1_padding</c> is used, and <c>byte_size(N)</c> if <c>rsa_no_padding</c> - is used. - See also <seealso marker="public_key:public_key#encrypt_private/2">public_key:encrypt_private/[2,3]</seealso> + and returns the ciphertext. This is a low level signature operation + used for instance by older versions of the SSL protocol. See + also <seealso + marker="public_key:public_key#encrypt_private-2">public_key:encrypt_private/[2,3]</seealso> </p> </desc> </func> @@ -475,40 +491,35 @@ <v>PlainText = binary()</v> </type> <desc> - <p>Decrypts the <c>ChipherText</c> (encrypted with - <seealso marker="#private_encrypt/3">private_encrypt/3</seealso>) - using the <c>PrivateKey</c> and returns the - message. The <c>Padding</c> is the padding mode that was - used to encrypt the data, - see <seealso marker="#private_encrypt/3">private_encrypt/3</seealso>. - See also <seealso marker="public_key:public_key#decrypt_public/2">public_key:decrypt_public/[2,3]</seealso> + <p>Decrypts the <c>ChipherText</c>, encrypted with + <seealso marker="#private_encrypt-4">private_encrypt/4</seealso>(or equivalent function) + using the <c>PrivateKey</c>, 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 <seealso marker="public_key:public_key#decrypt_public-2">public_key:decrypt_public/[2,3]</seealso> </p> </desc> </func> <func> <name>public_encrypt(Type, PlainText, PublicKey, Padding) -> ChipherText</name> - <fsummary>Encrypts Msg using the public Key.</fsummary> + <fsummary>Encrypts PlainText using the public Key.</fsummary> <type> <v>Type = rsa</v> <v>PlainText = binary()</v> + <d> The size of the <c>PlainText</c> must be less + than <c>byte_size(N)-11</c> if <c>rsa_pkcs1_padding</c> is + used, and <c>byte_size(N)</c> if <c>rsa_no_padding</c> is + used, where N is public modulus of the RSA key.</d> <v>PublicKey = rsa_public()</v> <v>Padding = rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_no_padding</v> <v>ChipherText = binary()</v> </type> <desc> - <p>Encrypts the <c>PlainText</c> (usually a session key) using the <c>PublicKey</c> - and returns the <c>CipherText</c>. The <c>Padding</c> decides what padding mode is used, - <c>rsa_pkcs1_padding</c> is PKCS #1 v1.5 currently the most - used mode and <c>rsa_pkcs1_oaep_padding</c> 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 <c>Msg</c> must be less - than <c>byte_size(N)-11</c> if - <c>rsa_pkcs1_padding</c> is used, <c>byte_size(N)-41</c> if - <c>rsa_pkcs1_oaep_padding</c> is used and <c>byte_size(N)</c> if <c>rsa_no_padding</c> - is used. - See also <seealso marker="public_key:public_key#encrypt_public/2">public_key:encrypt_public/[2,3]</seealso> + <p>Encrypts the <c>PlainText</c> (message digest) using the <c>PublicKey</c> + and returns the <c>CipherText</c>. This is a low level signature operation + used for instance by older versions of the SSL protocol. See also <seealso + marker="public_key:public_key#encrypt_public-2">public_key:encrypt_public/[2,3]</seealso> </p> </desc> </func> @@ -545,15 +556,17 @@ <type> <v>Algorithm = rsa | dss | ecdsa </v> <v>Msg = binary() | {digest,binary()}</v> - <d>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.</d> + <d>The msg is either the binary "cleartext" data to be + signed or it is the hashed value of "cleartext" i.e. the + digest (plaintext).</d> <v>DigestType = digest_type()</v> - <v>Key = rsa_private_key() | dsa_private_key() | ec_private_key()</v> + <v>Key = rsa_private() | dss_private() | [ecdh_private(),ecdh_params()]</v> </type> <desc> - <p> Creates a digital signature.</p> - See also <seealso marker="public_key:public_key#sign/3">public_key:sign/3</seealso> + <p>Creates a digital signature.</p> + <p>Algorithm <c>dss</c> can only be used together with digest type + <c>sha</c>.</p> + See also <seealso marker="public_key:public_key#sign-3">public_key:sign/3</seealso> </desc> </func> @@ -591,15 +604,14 @@ <name>stream_init(Type, Key) -> State</name> <fsummary></fsummary> <type> - <v>Type rc4 </v> + <v>Type = rc4 </v> <v>State = opaque() </v> <v>Key = iodata()</v> - <v>IVec = binary()</v> </type> <desc> <p>Initializes the state for use in RC4 stream encryption - <seealso marker="#stream_encrypt/2">stream_encrypt</seealso> and - <seealso marker="#stream_decrypt/2">stream_decrypt</seealso></p> + <seealso marker="#stream_encrypt-2">stream_encrypt</seealso> and + <seealso marker="#stream_decrypt-2">stream_decrypt</seealso></p> </desc> </func> @@ -607,7 +619,7 @@ <name>stream_init(Type, Key, IVec) -> State</name> <fsummary></fsummary> <type> - <v>Type aes_ctr </v> + <v>Type = aes_ctr </v> <v>State = opaque() </v> <v>Key = iodata()</v> <v>IVec = binary()</v> @@ -616,8 +628,8 @@ <p>Initializes the state for use in streaming AES encryption using Counter mode (CTR). <c>Key</c> is the AES key and must be either 128, 192, or 256 bts long. <c>IVec</c> is an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with - <seealso marker="#stream_encrypt/2">stream_encrypt</seealso> and - <seealso marker="#stream_decrypt/2">stream_decrypt</seealso>.</p> + <seealso marker="#stream_encrypt-2">stream_encrypt</seealso> and + <seealso marker="#stream_decrypt-2">stream_decrypt</seealso>.</p> </desc> </func> @@ -631,7 +643,7 @@ <desc> <p>Encrypts <c>PlainText</c> according to the stream cipher <c>Type</c> specified in stream_init/3. <c>Text</c> can be any number of bytes. The initial <c>State</c> is created using - <seealso marker="#stream_init/2">stream_init</seealso>. + <seealso marker="#stream_init-2">stream_init</seealso>. <c>NewState</c> must be passed into the next call to <c>stream_encrypt</c>.</p> </desc> </func> @@ -646,26 +658,45 @@ <desc> <p>Decrypts <c>CipherText</c> according to the stream cipher <c>Type</c> specified in stream_init/3. <c>PlainText</c> can be any number of bytes. The initial <c>State</c> is created using - <seealso marker="#stream_init/2">stream_init</seealso>. + <seealso marker="#stream_init-2">stream_init</seealso>. <c>NewState</c> must be passed into the next call to <c>stream_encrypt</c>.</p> </desc> </func> + <func> + <name>supports() -> AlgorithmList </name> + <fsummary>Provide a list of available crypto algorithms.</fsummary> + <type> + <v> AlgorithmList = [{hashs, [hash_algorithms()]}, + {ciphers, [cipher_algorithms()]}, + {public_keys, [public_key_algorithms()]} + </v> + </type> + <desc> + <p> Can be used to determine which crypto algorithms that are supported + by the underlying OpenSSL library</p> + </desc> + </func> + + <func> <name>verify(Algorithm, DigestType, Msg, Signature, Key) -> boolean()</name> <fsummary>Verifies a digital signature.</fsummary> <type> <v> Algorithm = rsa | dss | ecdsa </v> <v>Msg = binary() | {digest,binary()}</v> - <d>The msg is either the binary "plain text" data - or it is the hashed value of "plain text" i.e. the digest.</d> + <d>The msg is either the binary "cleartext" data + or it is the hashed value of "cleartext" i.e. the digest (plaintext).</d> <v>DigestType = digest_type()</v> <v>Signature = binary()</v> - <v>Key = rsa_public_key() | dsa_public_key() | ec_public_key()</v> + <v>Key = rsa_public() | dss_public() | [ecdh_public(),ecdh_params()]</v> </type> <desc> <p>Verifies a digital signature</p> - See also <seealso marker="public_key:public_key#sign/3">public_key:verify/3</seealso> + <p>Algorithm <c>dss</c> can only be used together with digest type + <c>sha</c>.</p> + + See also <seealso marker="public_key:public_key#verify-4">public_key:verify/4</seealso> </desc> </func> |