X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FEVP_EncryptInit.pod;h=d68d4bca5bc5288698bf189c06b4e3abbb06fb30;hp=f6e4396ade3fbf19efaf4b19214a46eae956642e;hb=5aed169305941fb1eba15fd4bacc0f998b0e43f7;hpb=2b4ffc659eabec29f76821f0ac624a2b8c19e4c7 diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index f6e4396ade..d68d4bca5b 100644 --- a/doc/crypto/EVP_EncryptInit.pod +++ b/doc/crypto/EVP_EncryptInit.pod @@ -24,9 +24,12 @@ EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc, EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc, -EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, -EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, -EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines +EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, +EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb, +EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb, +EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb, +EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, +EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines =head1 SYNOPSIS @@ -138,7 +141,7 @@ calls to EVP_EncryptUpdate() should be made. If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more data and it will return an error if any data remains in a partial block: -that is if the total data length is not a multiple of the block size. +that is if the total data length is not a multiple of the block size. EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the corresponding decryption operations. EVP_DecryptFinal() will return an @@ -161,14 +164,15 @@ after all operations using a cipher are complete so sensitive information does not remain in memory. EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a -similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and +similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and EVP_CipherInit_ex() except the B parameter does not need to be initialized and they always use the default cipher implementation. -EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a -similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and -EVP_CipherFinal_ex() except B is automatically cleaned up -after the call. +EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are +identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and +EVP_CipherFinal_ex(). In previous releases they also cleaned up +the B, but this is no longer done and EVP_CIPHER_CTX_clean() +must be called to free any context resources. EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() return an EVP_CIPHER structure when passed a cipher name, a NID or an @@ -277,7 +281,7 @@ OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. EVP_CIPHER_CTX_cipher() returns an B structure. -EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for +EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for success or zero for failure. =head1 CIPHER LISTING @@ -290,70 +294,83 @@ All algorithms have a fixed key length unless otherwise stated. Null cipher: does nothing. -=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) +=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb() -DES in CBC, ECB, CFB and OFB modes respectively. +AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively. -=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void) +=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb() + +AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb() + +AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb() + +DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(), EVP_des_ede_cfb() Two key triple DES in CBC, ECB, CFB and OFB modes respectively. -=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void) +=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(), EVP_des_ede3_cfb() Three key triple DES in CBC, ECB, CFB and OFB modes respectively. -=item EVP_desx_cbc(void) +=item EVP_desx_cbc() DESX algorithm in CBC mode. -=item EVP_rc4(void) +=item EVP_rc4() RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. -=item EVP_rc4_40(void) +=item EVP_rc4_40() -RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4() +RC4 stream cipher with 40 bit key length. +This is obsolete and new code should use EVP_rc4() and the EVP_CIPHER_CTX_set_key_length() function. -=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void) +=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb(), EVP_idea_cbc() IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. -=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) +=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb() RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher with an additional parameter called "effective key bits" or "effective key length". By default both are set to 128 bits. -=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void) +=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc() RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits. These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and EVP_CIPHER_CTX_ctrl() to set the key length and effective key length. -=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); +=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb() Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher. -=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void) +=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb() CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher. -=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) +=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb() RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher with an additional "number of rounds" parameter. By default the key length is set to 128 bits and 12 rounds. -=item EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void) +=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm() AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively. These ciphers require additional control operations to function correctly: see L section below for details. -=item EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void) +=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm() AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively. These ciphers require additional control operations to function correctly: see @@ -367,7 +384,7 @@ For GCM mode ciphers the behaviour of the EVP interface is subtly altered and several GCM specific ctrl operations are supported. To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(), -EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output +EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output parameter B set to B. When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() @@ -381,7 +398,7 @@ The following ctrls are supported in GCM mode: Sets the GCM IV length: this call can only be made before specifying an IV. If not called a default IV length is used (96 bits for AES). - + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag); Writes B bytes of the tag value to the buffer indicated by B. @@ -392,7 +409,7 @@ processed (e.g. after an EVP_EncryptFinal() call). Sets the expected tag to B bytes from B. This call is only legal when decrypting data and must be made B any data is processed (e.g. -before any EVP_DecryptUpdate() call). +before any EVP_DecryptUpdate() call). See L below for an example of the use of GCM mode. @@ -402,14 +419,14 @@ The behaviour of CCM mode ciphers is similar to CCM mode but with a few additional requirements and different ctrl values. Like GCM mode any additional authenticated data (AAD) is passed by calling -EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output +EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output parameter B set to B. Additionally the total plaintext or ciphertext length B be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or -EVP_DecryptUpdate() with the output and input parameters (B and B) +EVP_DecryptUpdate() with the output and input parameters (B and B) set to B and the length passed in the B parameter. The following ctrls are supported in CCM mode: - + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag); This call is made to set the expected B tag value when decrypting or @@ -433,9 +450,12 @@ for AES. Where possible the B interface to symmetric ciphers should be used in preference to the low level interfaces. This is because the code then becomes -transparent to the cipher used and much more flexible. +transparent to the cipher used and much more flexible. Additionally, the +B interface will ensure the use of platform specific cryptographic +acceleration such as AES-NI (the low level interfaces do not provide the +guarantee). -PKCS padding works by adding B padding bytes of value B to make the total +PKCS padding works by adding B padding bytes of value B to make the total length of the encrypted data a multiple of the block size. Padding is always added so if the data is already a multiple of the block size B will equal the block size. For example if the block size is 8 and 11 bytes are to be @@ -465,7 +485,7 @@ a limitation of the current RC5 code rather than the EVP interface. EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with default key lengths. If custom ciphers exceed these values the results are -unpredictable. This is because it has become standard practice to define a +unpredictable. This is because it has become standard practice to define a generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes. The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested @@ -473,27 +493,7 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. =head1 EXAMPLES -Get the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); - -Get the RC2 effective key length: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); - -Set the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); - -Set the effective key length used in RC2: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); - -Encrypt a string using blowfish: +Encrypt a string using IDEA: int do_crypt(char *outfile) { @@ -507,8 +507,9 @@ Encrypt a string using blowfish: char intext[] = "Some Crypto Text"; EVP_CIPHER_CTX ctx; FILE *out; + EVP_CIPHER_CTX_init(&ctx); - EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv); + EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv); if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext))) { @@ -537,31 +538,37 @@ Encrypt a string using blowfish: } The ciphertext from the above example can be decrypted using the B -utility with the command line: - - S +utility with the command line (shown on two lines for clarity): -General encryption, decryption function example using FILE I/O and RC2 with an -80 bit key: + openssl idea -d