evp_encryptinit.pod

开源的ssl算法openssl,版本0.9.8H

EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
length.

EVP_CIPHER_CTX_set_padding() always returns 1.

EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
length or zero if the cipher does not use an IV.

EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.

EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.

EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for 
success or zero for failure.

=head1 CIPHER LISTING

All algorithms have a fixed key length unless otherwise stated.

=over 4

=item EVP_enc_null()

Null cipher: does nothing.

=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)

DES 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)

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)

Three key triple DES in CBC, ECB, CFB and OFB modes respectively.

=item EVP_desx_cbc(void)

DESX algorithm in CBC mode.

=item EVP_rc4(void)

RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.

=item EVP_rc4_40(void)

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)

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)

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)

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);

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)

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)

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.

=back

=head1 NOTES

Where possible the B<EVP> 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.

PKCS padding works by adding B<n> padding bytes of value B<n> 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<n> will equal
the block size. For example if the block size is 8 and 11 bytes are to be
encrypted then 5 padding bytes of value 5 will be added.

When decrypting the final block is checked to see if it has the correct form.

Although the decryption operation can produce an error if padding is enabled,
it is not a strong test that the input data or key is correct. A random block
has better than 1 in 256 chance of being of the correct format and problems with
the input data earlier on will not produce a final decrypt error.

If padding is disabled then the decryption operation will always succeed if
the total amount of data decrypted is a multiple of the block size.

The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
compatibility with existing code. New code should use EVP_EncryptInit_ex(),
EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
existing context without allocating and freeing it up on each call.

=head1 BUGS

For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
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 
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
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:

 int do_crypt(char *outfile)
 	{
	unsigned char outbuf[1024];
	int outlen, tmplen;
	/* Bogus key and IV: we'd normally set these from
	 * another source.
	 */
	unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
	unsigned char iv[] = {1,2,3,4,5,6,7,8};
	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);

	if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
		{
		/* Error */
		return 0;
		}
	/* Buffer passed to EVP_EncryptFinal() must be after data just
	 * encrypted to avoid overwriting it.
	 */
	if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
		{
		/* Error */
		return 0;
		}
	outlen += tmplen;
	EVP_CIPHER_CTX_cleanup(&ctx);
	/* Need binary mode for fopen because encrypted data is
	 * binary data. Also cannot use strlen() on it because
         * it wont be null terminated and may contain embedded
	 * nulls.
	 */
	out = fopen(outfile, "wb");
	fwrite(outbuf, 1, outlen, out);
	fclose(out);
	return 1;
	}

The ciphertext from the above example can be decrypted using the B<openssl>
utility with the command line:
 
 S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d>

General encryption, decryption function example using FILE I/O and RC2 with an
80 bit key:

 int do_crypt(FILE *in, FILE *out, int do_encrypt)
 	{
	/* Allow enough space in output buffer for additional block */
	inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
	int inlen, outlen;
	/* Bogus key and IV: we'd normally set these from
	 * another source.
	 */
	unsigned char key[] = "0123456789";
	unsigned char iv[] = "12345678";
	/* Don't set key or IV because we will modify the parameters */
	EVP_CIPHER_CTX_init(&ctx);
	EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
	EVP_CIPHER_CTX_set_key_length(&ctx, 10);
	/* We finished modifying parameters so now we can set key and IV */
	EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);

	for(;;) 
		{
		inlen = fread(inbuf, 1, 1024, in);
		if(inlen <= 0) break;
		if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
			{
			/* Error */
			EVP_CIPHER_CTX_cleanup(&ctx);
			return 0;
			}
		fwrite(outbuf, 1, outlen, out);
		}
	if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
		{
		/* Error */
		EVP_CIPHER_CTX_cleanup(&ctx);
		return 0;
		}
	fwrite(outbuf, 1, outlen, out);

	EVP_CIPHER_CTX_cleanup(&ctx);
	return 1;
	}


=head1 SEE ALSO

L<evp(3)|evp(3)>

=head1 HISTORY

EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(),
EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
OpenSSL 0.9.7.

=cut