EVP_get_cipherbynid man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

EVP_EncryptInit(3)					    EVP_EncryptInit(3)

NAME
       EVP_EncryptInit,	 EVP_EncryptUpdate, EVP_EncryptFinal, EVP_DecryptInit,
       EVP_DecryptUpdate, EVP_DecryptFinal, EVP_CipherInit,  EVP_CipherUpdate,
       EVP_CipherFinal,	  EVP_CIPHER_CTX_set_key_length,  EVP_CIPHER_CTX_ctrl,
       EVP_CIPHER_CTX_cleanup,	 EVP_get_cipherbyname,	  EVP_get_cipherbynid,
       EVP_get_cipherbyobj,	  EVP_CIPHER_nid,	EVP_CIPHER_block_size,
       EVP_CIPHER_key_length,	  EVP_CIPHER_iv_length,	     EVP_CIPHER_flags,
       EVP_CIPHER_mode,		EVP_CIPHER_type,	EVP_CIPHER_CTX_cipher,
       EVP_CIPHER_CTX_nid,			    EVP_CIPHER_CTX_block_size,
       EVP_CIPHER_CTX_key_length,		     EVP_CIPHER_CTX_iv_length,
       EVP_CIPHER_CTX_get_app_data,		  EVP_CIPHER_CTX_set_app_data,
       EVP_CIPHER_CTX_type,	EVP_CIPHER_CTX_flags,	  EVP_CIPHER_CTX_mode,
       EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param -  EVP  cipher  rou‐
       tines

SYNOPSIS
       #include <openssl/evp.h>

       int EVP_EncryptInit(
	       EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,	      unsigned
       char *key, unsigned char *iv ); int EVP_EncryptUpdate(
	       EVP_CIPHER_CTX *ctx, unsigned char *out,		   int	*outl,
       unsigned char *in, int inl ); int EVP_EncryptFinal(
	       EVP_CIPHER_CTX *ctx, unsigned char *out,		  int *outl );
       int EVP_DecryptInit(
	       EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,	      unsigned
       char *key, unsigned char *iv ); int 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
       ); int EVP_CipherInit(
	       EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,	      unsigned
       char *key, unsigned char *iv, int enc ); int 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
       ); int EVP_CIPHER_CTX_set_key_length(
	       EVP_CIPHER_CTX *x, int keylen ); int EVP_CIPHER_CTX_ctrl(
	       EVP_CIPHER_CTX *ctx, int	 type,	int  arg,  void	 *ptr  );  int
       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)		       #define
       EVP_CIPHER_flags(e)	  ((e)->flags)			       #define
       EVP_CIPHER_mode(e)	  ((e)->flags) & EVP_CIPH_MODE)

       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)->key_len)		       #define
       EVP_CIPHER_CTX_iv_length(e)     ((e)->cipher->iv_len)	       #define
       EVP_CIPHER_CTX_get_app_data(e)  ((e)->app_data)		       #define
       EVP_CIPHER_CTX_set_app_data(e,d)	 ((e)->app_data=(char  *)(d))  #define
       EVP_CIPHER_CTX_type(c)	     EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
       #define	  EVP_CIPHER_CTX_flags(e)      ((e)->cipher->flags)    #define
       EVP_CIPHER_CTX_mode(e)	       ((e)->cipher->flags & EVP_CIPH_MODE)

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

DESCRIPTION
       The EVP cipher routines are a high level interface to certain symmetric
       ciphers.

       The EVP_EncryptInit() function initializes a  cipher  context  ctx  for
       encryption  with	 cipher type.  The type is usually supplied by a func‐
       tion such as EVP_des_cbc().The key is the symmetric key to use, and  iv
       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 parame‐
       ters  to	 NULL  except type in an initial call and supply the remaining
       parameters in subsequent calls, all of which have  type	set  to	 NULL.
       This is done when the default cipher parameters are not appropriate.

       The  EVP_EncryptUpdate() function encrypts inl bytes from the buffer in
       and writes the encrypted version to out. 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 outl should contain sufficient	 room.
       The actual number of bytes written is placed in outl.

       The  EVP_EncryptFinal()	function  encrypts the final data, that is any
       data that remains in a partial block. It uses  standard	block  padding
       (PKCS padding). The encrypted final data is written to out which should
       have sufficient space for one cipher block. The number of bytes written
       is placed in outl.  After this function is called the encryption opera‐
       tion is finished and no further calls to EVP_EncryptUpdate() should  be
       made.

       The   EVP_DecryptInit(),	 EVP_DecryptUpdate(),  and  EVP_DecryptFinal()
       functions are the corresponding decryption operations. The EVP_Decrypt‐
       Final()	function  will	return an error code if the final block is not
       formatted correctly. The parameters and restrictions are	 identical  to
       the  encryption	operations  except  that the decrypted data buffer out
       passed to EVP_DecryptUpdate() should have sufficient room  for  (inl  +
       cipher_block_size)  bytes  unless  the  cipher block size is 1 in which
       case inl bytes is sufficient.

       The EVP_CipherInit(),  EVP_CipherUpdate(),  and	EVP_CipherFinal()func‐
       tions can be used for decryption or encryption. The operation performed
       depends on the value of the enc parameter. It should be set  to	1  for
       encryption,  0  for decryption and -1 to leave the value unchanged (the
       actual value of enc being supplied in a previous call).

       The EVP_CIPHER_CTX_cleanup() function 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.

       The EVP_get_cipherbyname(), EVP_get_cipherbynid(), and  EVP_get_cipher‐
       byobj()	functions  return an EVP_CIPHER structure when passed a cipher
       name, a NID or an ASN1_OBJECT structure.

       The EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() functions return the  NID
       of a cipher when passed an EVP_CIPHER or EVP_CIPHER_CTX structure.  The
       actual NID value is an internal value which may not have a  correspond‐
       ing OBJECT IDENTIFIER.

       The  EVP_CIPHER_key_length()  and  EVP_CIPHER_CTX_key_length() function
       return the key  length  of  a  cipher  when  passed  an	EVP_CIPHER  or
       EVP_CIPHER_CTX  structure. The constant EVP_MAX_KEY_LENGTH is the maxi‐
       mum key length for all ciphers.	Although  the  EVP_CIPHER_key_length()
       function	  is   fixed   for   a	 given	 cipher,   the	value  of  the
       EVP_CIPHER_CTX_key_length() function may be different for variable  key
       length ciphers.

       The EVP_CIPHER_CTX_set_key_length() function sets the key length of the
       cipher ctx. If the cipher is a fixed length cipher then	attempting  to
       set the key length to any value other than the fixed value is an error.

       The  EVP_CIPHER_iv_length()  and	 EVP_CIPHER_CTX_iv_length()  functions
       return the  IV  length  of  a  cipher  when  passed  an	EVP_CIPHER  or
       EVP_CIPHER_CTX.	It  will return zero if the cipher does not use an IV.
       The constant  EVP_MAX_IV_LENGTH	is  the	 maximum  IV  length  for  all
       ciphers.

       The  EVP_CIPHER_block_size()  and EVP_CIPHER_CTX_block_size() functions
       return the block	 size  of  a  cipher  when  passed  an	EVP_CIPHER  or
       EVP_CIPHER_CTX  structure.  The	constant EVP_MAX_IV_LENGTH is also the
       maximum block length for all ciphers.

       The EVP_CIPHER_type() and EVP_CIPHER_CTX_type()	functions  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  parame‐
       ters.  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 NID_undef.

       The  EVP_CIPHER_CTX_cipher()  function returns the EVP_CIPHER structure
       when passed an EVP_CIPHER_CTX structure.

       The EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode()	functions  return  the
       block	 cipher	    mode:     EVP_CIPH_ECB_MODE,    EVP_CIPH_CBC_MODE,
       EVP_CIPH_CFB_MODE, or EVP_CIPH_OFB_MODE. If  the	 cipher	 is  a	stream
       cipher then EVP_CIPH_STREAM_CIPHER is returned.

       The  EVP_CIPHER_param_to_asn1()	function  sets the AlgorithmIdentifier
       parameter based on the passed cipher. This typically will  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() or EVP_DecryptUpdate() calls, for exam‐
       ple). This function may fail if the cipher does not have any ASN1  sup‐
       port.

       The  EVP_CIPHER_asn1_to_param()	function  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, the
       EVP_CipherInit() function will be called with the IV  and  key  set  to
       NULL.  The  EVP_CIPHER_asn1_to_param()  function	 will  be  called  and
       finally the EVP_CipherInit() function. All parameters  except  the  key
       are 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 is not supported).

       The  EVP_CIPHER_CTX_ctrl()  function  allows  various  cipher  specific
       parameters to be determined and set. Currently only the	RC2  effective
       key length and the number of rounds of RC5 can be set.

   Cipher Listing
       All  algorithms	have a fixed key length unless otherwise stated.  Null
       cipher: does nothing.  DES in CBC, ECB, CFB and OFB modes respectively.
       Two  key triple DES in CBC, ECB, CFB and OFB modes respectively.	 Three
       key triple DES in CBC, ECB, CFB and OFB modes respectively.  DESX algo‐
       rithm  in  CBC mode.  RC4 stream cipher.	 This is a variable key length
       cipher with default key length 128 bits.	 RC4 stream cipher with 40 bit
       key  length.  This is obsolete and new code should use the EVP_rc4()and
       the EVP_CIPHER_CTX_set_key_length() functions.  IDEA  encryption	 algo‐
       rithm  in  CBC,	ECB,  CFB  and OFB modes respectively.	RC2 encryption
       algorithm in CBC, ECB, CFB and OFB modes respectively. This is a	 vari‐
       able  key  length  cipher with an additional parameter called effective
       key bits or effective key length. By default both are set to 128	 bits.
       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
       the	 EVP_rc2_cbc(),	     EVP_CIPHER_CTX_set_key_length(),	   and
       EVP_CIPHER_CTX_ctrl() functions to set the key length and effective key
       length.	 Blowfish  encryption algorithm in CBC, ECB, CFB and OFB modes
       respectively. This is a variable key length  cipher.   CAST  encryption
       algorithm  in CBC, ECB, CFB and OFB modes respectively. This is a vari‐
       able key length cipher.	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.

NOTES
       Where possible the 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 n padding bytes of value n to make the
       total  length of the encrypted data a multiple of the block size.  Pad‐
       ding  is always added so if the data is already a multiple of the block
       size 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  cor‐
       rect 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 a 1-in- 256 chance of being of the correct format. Problems
       with the input data earlier on will not produce a final decrypt error.

       The   EVP_EncryptInit(),	   EVP_EncryptUpdate(),	   EVP_EncryptFinal(),
       EVP_DecryptInit(), EVP_DecryptUpdate(), EVP_CipherInit(), EVP_CipherUp‐
       date(), and EVP_CIPHER_CTX_cleanup() functions did not return errors in
       OpenSSL	version	 0.9.5a or earlier.  Software only versions of encryp‐
       tion algorithms will never return  error	 codes	for  these  functions,
       unless there is a programming error (for example, an attempt to set the
       key before the cipher is set in EVP_EncryptInit()).

RESTRICTIONS
       For RC5 the number of rounds can be set only to 8, 12 or 16. This is  a
       limitation of the current RC5 code rather than the EVP interface.

       It is not possible to disable PKCS padding.

       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  con‐
       taining 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.

RETURN VALUES
       The   EVP_EncryptInit(),	 EVP_EncryptUpdate(),  and  EVP_EncryptFinal()
       functions return 1 for success and 0 for failure.

       The EVP_DecryptInit() and EVP_DecryptUpdate() functions	return	1  for
       success and 0 for failure. The EVP_DecryptFinal() function returns 0 if
       the decrypt failed or 1 for success.

       The EVP_CipherInit() and EVP_CipherUpdate() functions return 1 for suc‐
       cess and 0 for failure.

       The  EVP_CipherFinal() function returns 0 for a decryption failure or 1
       for success.

       The EVP_CIPHER_CTX_cleanup() function returns 1 for success and	0  for
       failure.

       The  EVP_get_cipherbyname(), EVP_get_cipherbynid(), and EVP_get_cipher‐
       byobj() functions return an EVP_CIPHER structure or NULL on error.

       The EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() functions return a NID.

       The EVP_CIPHER_block_size() and	EVP_CIPHER_CTX_block_size()  functions
       return the block size.

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

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

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

       The EVP_CIPHER_CTX_cipher() function returns an EVP_CIPHER structure.

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

EXAMPLES
       Get the number of rounds used in RC5:
	int nrounds;
	EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &i);

       Get the RC2 effective key length:
	int key_bits;
	EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &i);

       Set the number of rounds used in RC5:
	int nrounds;
	EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, i, NULL);

       Set the number of rounds used in RC2:
	int nrounds;
	EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, i, NULL);

SEE ALSO
       Functions: evp(3)

							    EVP_EncryptInit(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net