From f7f03a2c738fa3cb523a5e509685f72fd0879bb2 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Wed, 25 Oct 2000 15:23:16 +0000 Subject: This commit was manufactured by cvs2git to create tag 'OPENBSD_2_8_BASE'. --- src/lib/libcrypto/doc/EVP_EncryptInit.pod | 224 ------------------------------ 1 file changed, 224 deletions(-) delete mode 100644 src/lib/libcrypto/doc/EVP_EncryptInit.pod (limited to 'src/lib/libcrypto/doc/EVP_EncryptInit.pod') diff --git a/src/lib/libcrypto/doc/EVP_EncryptInit.pod b/src/lib/libcrypto/doc/EVP_EncryptInit.pod deleted file mode 100644 index 77ed4ccdba..0000000000 --- a/src/lib/libcrypto/doc/EVP_EncryptInit.pod +++ /dev/null @@ -1,224 +0,0 @@ -=pod - -=head1 NAME - -EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines - -=head1 SYNOPSIS - - #include - - void EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv); - void EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - void EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - - void EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv); - void EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - void EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv, int enc); - void EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - void EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); - - const EVP_CIPHER *EVP_get_cipherbyname(const char *name); - #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) - #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) - - #define EVP_CIPHER_nid(e) ((e)->nid) - #define EVP_CIPHER_block_size(e) ((e)->block_size) - #define EVP_CIPHER_key_length(e) ((e)->key_len) - #define EVP_CIPHER_iv_length(e) ((e)->iv_len) - - int EVP_CIPHER_type(const EVP_CIPHER *ctx); - #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) - #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) - #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) - #define EVP_CIPHER_CTX_key_length(e) ((e)->cipher->key_len) - #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) - #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) - - int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); - int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); - -=head1 DESCRIPTION - -The EVP cipher routines are a high level interface to certain -symmetric ciphers. - -EVP_EncryptInit() initialises a cipher context B for encryption -with cipher B. B is normally supplied by a function such -as EVP_des_cbc() . B is the symmetric key to use and B is the -IV to use (if necessary), the actual number of bytes used for the -key and IV depends on the cipher. It is possible to set all parameters -to NULL except B in an initial call and supply the remaining -parameters in subsequent calls. This is normally done when the -EVP_CIPHER_asn1_to_param() function is called to set the cipher -parameters from an ASN1 AlgorithmIdentifier and the key from a -different source. - -EVP_EncryptUpdate() encrypts B bytes from the buffer B and -writes the encrypted version to B. This function can be called -multiple times to encrypt successive blocks of data. The amount -of data written depends on the block alignment of the encrypted data: -as a result the amount of data written may be anything from zero bytes -to (inl + cipher_block_size - 1) so B should contain sufficient -room. The actual number of bytes written is placed in B. - -EVP_EncryptFinal() encrypts the "final" data, that is any data that -remains in a partial block. It uses L (aka PKCS -padding). The encrypted final data is written to B which should -have sufficient space for one cipher block. The number of bytes written -is placed in B. After this function is called the encryption operation -is finished and no further calls to EVP_EncryptUpdate() should be made. - -EVP_DecryptInit(), EVP_DecryptUpdate() and EVP_DecryptFinal() are the -corresponding decryption operations. EVP_DecryptFinal() will return an -error code if the final block is not correctly formatted. The parameters -and restrictions are identical to the encryption operations except that -the decrypted data buffer B passed to EVP_DecryptUpdate() should -have sufficient room for (B + cipher_block_size) bytes unless the -cipher block size is 1 in which case B bytes is sufficient. - -EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal() are functions -that can be used for decryption or encryption. The operation performed -depends on the value of the B parameter. It should be set to 1 for -encryption and 0 for decryption. - -EVP_CIPHER_CTX_cleanup() clears all information from a cipher context. -It should be called after all operations using a cipher are complete -so sensitive information does not remain in memory. - -EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() -return an EVP_CIPHER structure when passed a cipher name, a NID or an -ASN1_OBJECT structure. - -EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when -passed an B or B structure. The actual NID -value is an internal value which may not have a corresponding OBJECT -IDENTIFIER. - -EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key -length of a cipher when passed an B or B -structure. The constant B is the maximum key length -for all ciphers. - -EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV -length of a cipher when passed an B or B. -It will return zero if the cipher does not use an IV. The constant -B is the maximum IV length for all ciphers. - -EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block -size of a cipher when passed an B or B -structure. The constant B is also the maximum block -length for all ciphers. - -EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed -cipher or context. This "type" is the actual NID of the cipher OBJECT -IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and -128 bit RC2 have the same NID. If the cipher does not have an object -identifier or does not have ASN1 support this function will return -B. - -EVP_CIPHER_CTX_cipher() returns the B structure when passed -an B structure. - -EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based -on the passed cipher. This will typically include any parameters and an -IV. The cipher IV (if any) must be set when this call is made. This call -should be made before the cipher is actually "used" (before any -EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function -may fail if the cipher does not have any ASN1 support. - -EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 -AlgorithmIdentifier "parameter". The precise effect depends on the cipher -In the case of RC2, for example, it will set the IV and effective key length. -This function should be called after the base cipher type is set but before -the key is set. For example EVP_CipherInit() will be called with the IV and -key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally -EVP_CipherInit() again with all parameters except the key set to NULL. It is -possible for this function to fail if the cipher does not have any ASN1 support -or the parameters cannot be set (for example the RC2 effective key length -does not have an B structure). - -=head1 RETURN VALUES - -EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() do not return -values. - -EVP_DecryptInit() and EVP_DecryptUpdate() do not return values. -EVP_DecryptFinal() returns 0 if the decrypt failed or 1 for success. - -EVP_CipherInit() and EVP_CipherUpdate() do not return values. -EVP_CipherFinal() returns 1 for a decryption failure or 1 for success, if -the operation is encryption then it always returns 1. - -EVP_CIPHER_CTX_cleanup() does not return a value. - -EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() -return an B structure or NULL on error. - -EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. - -EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block -size. - -EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key -length. - -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 structure. - -EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for -success or zero for failure. - -=head1 NOTES - -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. - -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 -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, 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. - -=head1 BUGS - -The current B cipher interface is not as flexible as it should be. Only -certain "spot" encryption algorithms can be used for ciphers which have various -parameters associated with them (RC2, RC5 for example) this is inadequate. - -Several of the functions do not return error codes because the software versions -can never fail. This is not true of hardware versions. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -=cut -- cgit v1.2.3-55-g6feb