cipher.h

All headers

Ciphers.

  1. Cipher primitives
  2. EVP_rc4
  3. EVP_des_cbc
  4. EVP_des_ecb
  5. EVP_des_ede
  6. EVP_des_ede3
  7. EVP_des_ede_cbc
  8. EVP_des_ede3_cbc
  9. EVP_aes_128_ecb
  10. EVP_aes_128_cbc
  11. EVP_aes_128_ctr
  12. EVP_aes_128_ofb
  13. EVP_aes_256_ecb
  14. EVP_aes_256_cbc
  15. EVP_aes_256_ctr
  16. EVP_aes_256_ofb
  17. EVP_aes_256_xts
  18. EVP_enc_null
  19. EVP_rc2_cbc
  20. EVP_rc2_40_cbc
  21. EVP_get_cipherbynid
  22. Cipher context allocation
  23. EVP_CIPHER_CTX_init
  24. EVP_CIPHER_CTX_new
  25. EVP_CIPHER_CTX_cleanup
  26. EVP_CIPHER_CTX_free
  27. EVP_CIPHER_CTX_copy
  28. EVP_CIPHER_CTX_reset
  29. Cipher context configuration
  30. EVP_CipherInit_ex
  31. EVP_EncryptInit_ex
  32. EVP_DecryptInit_ex
  33. Cipher operations
  34. EVP_EncryptUpdate
  35. EVP_EncryptFinal_ex
  36. EVP_DecryptUpdate
  37. EVP_DecryptFinal_ex
  38. EVP_Cipher
  39. EVP_CipherUpdate
  40. EVP_CipherFinal_ex
  41. Cipher context accessors
  42. EVP_CIPHER_CTX_cipher
  43. EVP_CIPHER_CTX_nid
  44. EVP_CIPHER_CTX_block_size
  45. EVP_CIPHER_CTX_key_length
  46. EVP_CIPHER_CTX_iv_length
  47. EVP_CIPHER_CTX_get_app_data
  48. EVP_CIPHER_CTX_set_app_data
  49. EVP_CIPHER_CTX_flags
  50. EVP_CIPHER_CTX_mode
  51. EVP_CIPHER_CTX_ctrl
  52. EVP_CIPHER_CTX_set_padding
  53. EVP_CIPHER_CTX_set_key_length
  54. Cipher accessors
  55. EVP_CIPHER_nid
  56. EVP_CIPHER_block_size
  57. EVP_CIPHER_key_length
  58. EVP_CIPHER_iv_length
  59. EVP_CIPHER_flags
  60. EVP_CIPHER_mode
  61. Key derivation
  62. EVP_BytesToKey
  63. Cipher modes (for EVP_CIPHER_mode)
  64. EVP_CIPH_STREAM_CIPHER
  65. EVP_CIPH_ECB_MODE
  66. EVP_CIPH_CBC_MODE
  67. EVP_CIPH_CFB_MODE
  68. EVP_CIPH_OFB_MODE
  69. EVP_CIPH_CTR_MODE
  70. EVP_CIPH_GCM_MODE
  71. EVP_CIPH_XTS_MODE
  72. Cipher flags (for EVP_CIPHER_flags)
  73. EVP_CIPH_VARIABLE_LENGTH
  74. EVP_CIPH_ALWAYS_CALL_INIT
  75. EVP_CIPH_CUSTOM_IV
  76. EVP_CIPH_CTRL_INIT
  77. EVP_CIPH_FLAG_CUSTOM_CIPHER
  78. EVP_CIPH_FLAG_AEAD_CIPHER
  79. EVP_CIPH_CUSTOM_COPY
  80. Deprecated functions
  81. EVP_CipherInit
  82. EVP_EncryptInit
  83. EVP_DecryptInit
  84. EVP_add_cipher_alias
  85. EVP_get_cipherbyname
  86. EVP_aes_128_gcm
  87. EVP_aes_256_gcm
  88. EVP_aes_192_ecb
  89. EVP_aes_192_cbc
  90. EVP_aes_192_ctr
  91. EVP_aes_192_gcm
  92. EVP_aes_128_cfb128
  93. EVP_CIPH_CCM_MODE
  94. EVP_CIPH_WRAP_MODE
  95. EVP_CIPHER_CTX_FLAG_WRAP_ALLOW
  96. EVP_CIPHER_CTX_set_flags

Cipher primitives.

The following functions return EVP_CIPHER objects that implement the named cipher algorithm.

OPENSSL_EXPORT const EVP_CIPHER *EVP_rc4(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_des_cbc(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ecb(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede3(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede_cbc(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede3_cbc(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_ecb(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_cbc(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_ctr(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_ofb(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ecb(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_cbc(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ctr(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ofb(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_xts(void);

EVP_enc_null returns a 'cipher' that passes plaintext through as ciphertext.

OPENSSL_EXPORT const EVP_CIPHER *EVP_enc_null(void);

EVP_rc2_cbc returns a cipher that implements 128-bit RC2 in CBC mode.

OPENSSL_EXPORT const EVP_CIPHER *EVP_rc2_cbc(void);

EVP_rc2_40_cbc returns a cipher that implements 40-bit RC2 in CBC mode. This is obviously very, very weak and is included only in order to read PKCS#12 files, which often encrypt the certificate chain using this cipher. It is deliberately not exported.

const EVP_CIPHER *EVP_rc2_40_cbc(void);

EVP_get_cipherbynid returns the cipher corresponding to the given NID, or NULL if no such cipher is known.

OPENSSL_EXPORT const EVP_CIPHER *EVP_get_cipherbynid(int nid);

Cipher context allocation.

An EVP_CIPHER_CTX represents the state of an encryption or decryption in progress.

EVP_CIPHER_CTX_init initialises an, already allocated, EVP_CIPHER_CTX.

OPENSSL_EXPORT void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_new allocates a fresh EVP_CIPHER_CTX, calls EVP_CIPHER_CTX_init and returns it, or NULL on allocation failure.

OPENSSL_EXPORT EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);

EVP_CIPHER_CTX_cleanup frees any memory referenced by ctx. It returns one.

OPENSSL_EXPORT int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_free calls EVP_CIPHER_CTX_cleanup on ctx and then frees ctx itself.

OPENSSL_EXPORT void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_copy sets out to be a duplicate of the current state of in. The out argument must have been previously initialised.

OPENSSL_EXPORT int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out,
                                       const EVP_CIPHER_CTX *in);

EVP_CIPHER_CTX_reset calls EVP_CIPHER_CTX_cleanup followed by EVP_CIPHER_CTX_init.

OPENSSL_EXPORT void EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);

Cipher context configuration.

EVP_CipherInit_ex configures ctx for a fresh encryption (or decryption, if enc is zero) operation using cipher. If ctx has been previously configured with a cipher then cipher, key and iv may be NULL and enc may be -1 to reuse the previous values. The operation will use key as the key and iv as the IV (if any). These should have the correct lengths given by EVP_CIPHER_key_length and EVP_CIPHER_iv_length. It returns one on success and zero on error.

OPENSSL_EXPORT int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx,
                                     const EVP_CIPHER *cipher, ENGINE *engine,
                                     const uint8_t *key, const uint8_t *iv,
                                     int enc);

EVP_EncryptInit_ex calls EVP_CipherInit_ex with enc equal to one.

OPENSSL_EXPORT int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx,
                                      const EVP_CIPHER *cipher, ENGINE *impl,
                                      const uint8_t *key, const uint8_t *iv);

EVP_DecryptInit_ex calls EVP_CipherInit_ex with enc equal to zero.

OPENSSL_EXPORT int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx,
                                      const EVP_CIPHER *cipher, ENGINE *impl,
                                      const uint8_t *key, const uint8_t *iv);

Cipher operations.

EVP_EncryptUpdate encrypts in_len bytes from in to out. The number of output bytes may be up to in_len plus the block length minus one and out must have sufficient space. The number of bytes actually output is written to *out_len. It returns one on success and zero otherwise.

OPENSSL_EXPORT int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out,
                                     int *out_len, const uint8_t *in,
                                     int in_len);

EVP_EncryptFinal_ex writes at most a block of ciphertext to out and sets *out_len to the number of bytes written. If padding is enabled (the default) then standard padding is applied to create the final block. If padding is disabled (with EVP_CIPHER_CTX_set_padding) then any partial block remaining will cause an error. The function returns one on success and zero otherwise.

OPENSSL_EXPORT int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
                                       int *out_len);

EVP_DecryptUpdate decrypts in_len bytes from in to out. The number of output bytes may be up to in_len plus the block length minus one and out must have sufficient space. The number of bytes actually output is written to *out_len. It returns one on success and zero otherwise.

OPENSSL_EXPORT int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out,
                                     int *out_len, const uint8_t *in,
                                     int in_len);

EVP_DecryptFinal_ex writes at most a block of ciphertext to out and sets *out_len to the number of bytes written. If padding is enabled (the default) then padding is removed from the final block.

WARNING: it is unsafe to call this function with unauthenticated ciphertext if padding is enabled.

OPENSSL_EXPORT int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
                                       int *out_len);

EVP_Cipher performs a one-shot encryption/decryption operation. No partial blocks are maintained between calls. However, any internal cipher state is still updated. For CBC-mode ciphers, the IV is updated to the final ciphertext block. For stream ciphers, the stream is advanced past the bytes used. It returns one on success and zero otherwise, unless EVP_CIPHER_flags has EVP_CIPH_FLAG_CUSTOM_CIPHER set. Then it returns the number of bytes written or -1 on error.

WARNING: this differs from the usual return value convention when using EVP_CIPH_FLAG_CUSTOM_CIPHER.

TODO(davidben): The normal ciphers currently never fail, even if, e.g., in_len is not a multiple of the block size for CBC-mode decryption. The input just gets rounded up while the output gets truncated. This should either be officially documented or fail.

OPENSSL_EXPORT int EVP_Cipher(EVP_CIPHER_CTX *ctx, uint8_t *out,
                              const uint8_t *in, size_t in_len);

EVP_CipherUpdate calls either EVP_EncryptUpdate or EVP_DecryptUpdate depending on how ctx has been setup.

OPENSSL_EXPORT int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out,
                                    int *out_len, const uint8_t *in,
                                    int in_len);

EVP_CipherFinal_ex calls either EVP_EncryptFinal_ex or EVP_DecryptFinal_ex depending on how ctx has been setup.

OPENSSL_EXPORT int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
                                      int *out_len);

Cipher context accessors.

EVP_CIPHER_CTX_cipher returns the EVP_CIPHER underlying ctx, or NULL if none has been set.

OPENSSL_EXPORT const EVP_CIPHER *EVP_CIPHER_CTX_cipher(
    const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_nid returns a NID identifying the EVP_CIPHER underlying ctx (e.g. NID_aes_128_gcm). It will crash if no cipher has been configured.

OPENSSL_EXPORT int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_block_size returns the block size, in bytes, of the cipher underlying ctx, or one if the cipher is a stream cipher. It will crash if no cipher has been configured.

OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_key_length returns the key size, in bytes, of the cipher underlying ctx or zero if no cipher has been configured.

OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_iv_length returns the IV size, in bytes, of the cipher underlying ctx. It will crash if no cipher has been configured.

OPENSSL_EXPORT unsigned EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_get_app_data returns the opaque, application data pointer for ctx, or NULL if none has been set.

OPENSSL_EXPORT void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_set_app_data sets the opaque, application data pointer for ctx to data.

OPENSSL_EXPORT void EVP_CIPHER_CTX_set_app_data(EVP_CIPHER_CTX *ctx,
                                                void *data);

EVP_CIPHER_CTX_flags returns a value which is the OR of zero or more EVP_CIPH_* flags. It will crash if no cipher has been configured.

OPENSSL_EXPORT uint32_t EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_mode returns one of the EVP_CIPH_* cipher mode values enumerated below. It will crash if no cipher has been configured.

OPENSSL_EXPORT uint32_t EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx);

EVP_CIPHER_CTX_ctrl is an ioctl like function. The command argument should be one of the EVP_CTRL_* values. The arg and ptr arguments are specific to the command in question.

OPENSSL_EXPORT int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int command,
                                       int arg, void *ptr);

EVP_CIPHER_CTX_set_padding sets whether padding is enabled for ctx and returns one. Pass a non-zero pad to enable padding (the default) or zero to disable.

OPENSSL_EXPORT int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *ctx, int pad);

EVP_CIPHER_CTX_set_key_length sets the key length for ctx. This is only valid for ciphers that can take a variable length key. It returns one on success and zero on error.

OPENSSL_EXPORT int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *ctx,
                                                 unsigned key_len);

Cipher accessors.

EVP_CIPHER_nid returns a NID identifying cipher. (For example, NID_aes_128_gcm.)

OPENSSL_EXPORT int EVP_CIPHER_nid(const EVP_CIPHER *cipher);

EVP_CIPHER_block_size returns the block size, in bytes, for cipher, or one if cipher is a stream cipher.

OPENSSL_EXPORT unsigned EVP_CIPHER_block_size(const EVP_CIPHER *cipher);

EVP_CIPHER_key_length returns the key size, in bytes, for cipher. If cipher can take a variable key length then this function returns the default key length and EVP_CIPHER_flags will return a value with EVP_CIPH_VARIABLE_LENGTH set.

OPENSSL_EXPORT unsigned EVP_CIPHER_key_length(const EVP_CIPHER *cipher);

EVP_CIPHER_iv_length returns the IV size, in bytes, of cipher, or zero if cipher doesn't take an IV.

OPENSSL_EXPORT unsigned EVP_CIPHER_iv_length(const EVP_CIPHER *cipher);

EVP_CIPHER_flags returns a value which is the OR of zero or more EVP_CIPH_* flags.

OPENSSL_EXPORT uint32_t EVP_CIPHER_flags(const EVP_CIPHER *cipher);

EVP_CIPHER_mode returns one of the cipher mode values enumerated below.

OPENSSL_EXPORT uint32_t EVP_CIPHER_mode(const EVP_CIPHER *cipher);

Key derivation.

EVP_BytesToKey generates a key and IV for the cipher type by iterating md count times using data and salt. On entry, the key and iv buffers must have enough space to hold a key and IV for type. It returns the length of the key on success or zero on error.

OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
                                  const uint8_t *salt, const uint8_t *data,
                                  size_t data_len, unsigned count, uint8_t *key,
                                  uint8_t *iv);

Cipher modes (for EVP_CIPHER_mode).

#define EVP_CIPH_STREAM_CIPHER 0x0
#define EVP_CIPH_ECB_MODE 0x1
#define EVP_CIPH_CBC_MODE 0x2
#define EVP_CIPH_CFB_MODE 0x3
#define EVP_CIPH_OFB_MODE 0x4
#define EVP_CIPH_CTR_MODE 0x5
#define EVP_CIPH_GCM_MODE 0x6
#define EVP_CIPH_XTS_MODE 0x7

Cipher flags (for EVP_CIPHER_flags).

EVP_CIPH_VARIABLE_LENGTH indicates that the cipher takes a variable length key.

#define EVP_CIPH_VARIABLE_LENGTH 0x40

EVP_CIPH_ALWAYS_CALL_INIT indicates that the init function for the cipher should always be called when initialising a new operation, even if the key is NULL to indicate that the same key is being used.

#define EVP_CIPH_ALWAYS_CALL_INIT 0x80

EVP_CIPH_CUSTOM_IV indicates that the cipher manages the IV itself rather than keeping it in the iv member of EVP_CIPHER_CTX.

#define EVP_CIPH_CUSTOM_IV 0x100

EVP_CIPH_CTRL_INIT indicates that EVP_CTRL_INIT should be used when initialising an EVP_CIPHER_CTX.

#define EVP_CIPH_CTRL_INIT 0x200

EVP_CIPH_FLAG_CUSTOM_CIPHER indicates that the cipher manages blocking itself. This causes EVP_(En|De)crypt_ex to be simple wrapper functions.

#define EVP_CIPH_FLAG_CUSTOM_CIPHER 0x400

EVP_CIPH_FLAG_AEAD_CIPHER specifies that the cipher is an AEAD. This is an older version of the proper AEAD interface. See aead.h for the current one.

#define EVP_CIPH_FLAG_AEAD_CIPHER 0x800

EVP_CIPH_CUSTOM_COPY indicates that the ctrl callback should be called with EVP_CTRL_COPY at the end of normal EVP_CIPHER_CTX_copy processing.

#define EVP_CIPH_CUSTOM_COPY 0x1000

Deprecated functions

EVP_CipherInit acts like EVP_CipherInit_ex except that EVP_CIPHER_CTX_init is called on cipher first, if cipher is not NULL.

OPENSSL_EXPORT int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher,
                                  const uint8_t *key, const uint8_t *iv,
                                  int enc);

EVP_EncryptInit calls EVP_CipherInit with enc equal to one.

OPENSSL_EXPORT int EVP_EncryptInit(EVP_CIPHER_CTX *ctx,
                                   const EVP_CIPHER *cipher, const uint8_t *key,
                                   const uint8_t *iv);

EVP_DecryptInit calls EVP_CipherInit with enc equal to zero.

OPENSSL_EXPORT int EVP_DecryptInit(EVP_CIPHER_CTX *ctx,
                                   const EVP_CIPHER *cipher, const uint8_t *key,
                                   const uint8_t *iv);

EVP_add_cipher_alias does nothing and returns one.

OPENSSL_EXPORT int EVP_add_cipher_alias(const char *a, const char *b);

EVP_get_cipherbyname returns an EVP_CIPHER given a human readable name in name, or NULL if the name is unknown.

OPENSSL_EXPORT const EVP_CIPHER *EVP_get_cipherbyname(const char *name);

These AEADs are deprecated AES-GCM implementations that set EVP_CIPH_FLAG_CUSTOM_CIPHER. Use EVP_aead_aes_128_gcm and EVP_aead_aes_256_gcm instead.

OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_gcm(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_gcm(void);

These are deprecated, 192-bit version of AES.

OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ecb(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cbc(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ctr(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_gcm(void);

EVP_aes_128_cfb128 is only available in decrepit.

OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_cfb128(void);

The following flags do nothing and are included only to make it easier to compile code with BoringSSL.

#define EVP_CIPH_CCM_MODE 0
#define EVP_CIPH_WRAP_MODE 0
#define EVP_CIPHER_CTX_FLAG_WRAP_ALLOW 0

EVP_CIPHER_CTX_set_flags does nothing.

OPENSSL_EXPORT void EVP_CIPHER_CTX_set_flags(const EVP_CIPHER_CTX *ctx,
                                             uint32_t flags);