C9S/boringssl
2
0
Fork 0
mirror of https://boringssl.googlesource.com/boringssl synced 2026-07-21 14:43:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: Change |...| to ... for code references in comments 2/N

Browse Source 
This CL includes the result of running util/update_comment_style.py over
all public header files in include/openssl whose filenames begin with
c-e, and fixing omissions manually if necessary.

Bug: 42290410
Change-Id: I306fb029389ab99725deead22e77ad5e6a6a6964
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96127
Reviewed-by: David Benjamin <davidben@google.com>
Commit-Queue: Lily Chen <chlily@google.com>
This commit is contained in:
Lily Chen
2026-05-29 19:34:11 +00:00
committed by boringssl-scoped@luci-project-accounts.iam.gserviceaccount.com
parent d16fd05ba1
commit d671f42fa5
21 changed files with 1329 additions and 1329 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openssl/cast.h
+16 -16
View File
@@ -43,41 +43,41 @@ typedef struct cast_key_st {
int short_key; // Use reduced rounds for short key
} CAST_KEY;
// CAST_set_key initializes |key| from |len| bytes of key material starting from
// |data|. CAST-128 keys are between 5 and 16 bytes long. If |len| is greater
// than 16, |data| is truncated and only the first 16 bytes are processed. If
// |len| is less than 5, it is internally zero-padded.
// CAST_set_key initializes `key` from `len` bytes of key material starting from
// `data`. CAST-128 keys are between 5 and 16 bytes long. If `len` is greater
// than 16, `data` is truncated and only the first 16 bytes are processed. If
// `len` is less than 5, it is internally zero-padded.
OPENSSL_EXPORT void CAST_set_key(CAST_KEY *key, size_t len,
const uint8_t *data);
// CAST_ecb_encrypt encrypts (or decrypts, if |enc| is |CAST_DECRYPT|) a single
// 8-byte block from |in| to |out|, using |key|.
// CAST_ecb_encrypt encrypts (or decrypts, if `enc` is `CAST_DECRYPT`) a single
// 8-byte block from `in` to `out`, using `key`.
OPENSSL_EXPORT void CAST_ecb_encrypt(const uint8_t in[CAST_BLOCK],
uint8_t out[CAST_BLOCK],
const CAST_KEY *key, int enc);
// CAST_encrypt encrypts an 8-byte block from |data| in-place with |key|. An
// CAST_encrypt encrypts an 8-byte block from `data` in-place with `key`. An
// 8-byte block is represented in this function as two 32-bit integers,
// containing the first and second four bytes in big-endian order.
OPENSSL_EXPORT void CAST_encrypt(uint32_t data[2], const CAST_KEY *key);
// CAST_decrypt decrypts an 8-byte block from |data| in-place with |key|. An
// CAST_decrypt decrypts an 8-byte block from `data` in-place with `key`. An
// 8-byte block is represented in this function as two 32-bit integers,
// containing the first and second four bytes in big-endian order.
OPENSSL_EXPORT void CAST_decrypt(uint32_t data[2], const CAST_KEY *key);
// CAST_cbc_encrypt encrypts (or decrypts, if |enc| is |CAST_DECRYPT|) |length|
// bytes from |in| to |out| with CAST-128 in CBC mode. |length| must be a
// multiple of 8. The IV is taken from |iv|. When the function completes, the IV
// for the next block is written to |iv|.
// CAST_cbc_encrypt encrypts (or decrypts, if `enc` is `CAST_DECRYPT`) `length`
// bytes from `in` to `out` with CAST-128 in CBC mode. `length` must be a
// multiple of 8. The IV is taken from `iv`. When the function completes, the IV
// for the next block is written to `iv`.
OPENSSL_EXPORT void CAST_cbc_encrypt(const uint8_t *in, uint8_t *out,
size_t length, const CAST_KEY *ks,
uint8_t iv[8], int enc);
// CAST_cfb64_encrypt encrypts (or decrypts, if |enc| is |CAST_DECRYPT|)
// |length| bytes from |in| to |out| with CAST-128 in CFB-64 mode. |length| must
// be a multiple of 8. On the first call, |*num| should be zero and |ivec| the
// IV. On exit, this function will write state to |ivec| and |*num| to resume an
// CAST_cfb64_encrypt encrypts (or decrypts, if `enc` is `CAST_DECRYPT`)
// `length` bytes from `in` to `out` with CAST-128 in CFB-64 mode. `length` must
// be a multiple of 8. On the first call, `*num` should be zero and `ivec` the
// IV. On exit, this function will write state to `ivec` and `*num` to resume an
// encryption or decryption operation if the buffers are not contiguous.
OPENSSL_EXPORT void CAST_cfb64_encrypt(const uint8_t *in, uint8_t *out,
size_t length, const CAST_KEY *schedule,
include/openssl/chacha.h
+3 -3
View File
@@ -26,9 +26,9 @@ extern "C" {
// ChaCha20 is a stream cipher. See https://tools.ietf.org/html/rfc8439.
// CRYPTO_chacha_20 encrypts |in_len| bytes from |in| with the given key and
// nonce and writes the result to |out|. If |in| and |out| alias, they must be
// equal. The initial block counter is specified by |counter|.
// CRYPTO_chacha_20 encrypts `in_len` bytes from `in` with the given key and
// nonce and writes the result to `out`. If `in` and `out` alias, they must be
// equal. The initial block counter is specified by `counter`.
//
// This function implements a 32-bit block counter as in RFC 8439. On overflow,
// the counter wraps. Reusing a key, nonce, and block counter combination is not
include/openssl/cipher.h
+151 -151
View File
@@ -27,7 +27,7 @@ extern "C" {
// Cipher primitives.
//
// The following functions return |EVP_CIPHER| objects that implement the named
// The following functions return `EVP_CIPHER` objects that implement the named
// cipher algorithm.
OPENSSL_EXPORT const EVP_CIPHER *EVP_rc4(void);
@@ -73,54 +73,54 @@ 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
// 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|.
// 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.
// 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
// 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.
// 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.
// 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| and returns one.
// EVP_CIPHER_CTX_reset calls `EVP_CIPHER_CTX_cleanup` followed by
// `EVP_CIPHER_CTX_init` and returns one.
OPENSSL_EXPORT int 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
// 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.
// 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.
// 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);
@@ -128,29 +128,29 @@ OPENSSL_EXPORT int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx,
// Cipher operations.
// EVP_EncryptUpdate_ex encrypts |in_len| bytes from |in| and writes up to
// |max_out| bytes of ciphertext to |out|. On success, it sets |*out_len| to
// EVP_EncryptUpdate_ex encrypts `in_len` bytes from `in` and writes up to
// `max_out` bytes of ciphertext to `out`. On success, it sets `*out_len` to
// the number of output bytes and returns one. Otherwise, it returns zero.
//
// If |max_out| is not large enough for the output, the function will return
// If `max_out` is not large enough for the output, the function will return
// zero. The size of output buffer needed depends on the cipher and the number
// of bytes encrypted by |ctx| thus far.
// of bytes encrypted by `ctx` thus far.
//
// In ciphers whose block size is not 1, such as CBC, individual calls to
// |EVP_EncryptUpdate_ex| may output more or less than |in_len| bytes: a single
// call to |EVP_EncryptUpdate_ex| may output at most |in_len + block_size - 1|
// bytes. Additionally, the total output across all |EVP_EncryptUpdate_ex| and
// |EVP_EncryptFinal_ex2| calls will be at most the total input plus one byte,
// `EVP_EncryptUpdate_ex` may output more or less than `in_len` bytes: a single
// call to `EVP_EncryptUpdate_ex` may output at most `in_len + block_size - 1`
// bytes. Additionally, the total output across all `EVP_EncryptUpdate_ex` and
// `EVP_EncryptFinal_ex2` calls will be at most the total input plus one byte,
// rounded up to a multiple of the block size.
OPENSSL_EXPORT int EVP_EncryptUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len,
const uint8_t *in, size_t in_len);
// EVP_EncryptFinal_ex2 finishes an encryption operation and writes up to
// |max_out| bytes of output to out. On success, it sets |*out_len| to the
// `max_out` bytes of output to out. On success, it sets `*out_len` to the
// number of bytes written and returns one. Otherwise, it returns zero.
//
// If |max_out| is not large enough for the output, the function will return
// If `max_out` is not large enough for the output, the function will return
// zero. The size of output buffer needed depends on the cipher and the number
// of bytes encrypted.
//
@@ -159,38 +159,38 @@ OPENSSL_EXPORT int EVP_EncryptUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
//
// If padding is enabled (the default) and the block size is not 1, then
// standard padding is applied to create the final block. If padding is
// disabled (with |EVP_CIPHER_CTX_set_padding|) then any partial block
// 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_ex2(EVP_CIPHER_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len);
// EVP_DecryptUpdate_ex decrypts |in_len| bytes from |in| and writes up to
// |max_out| bytes of plaintext to |out|. On success, it sets |*out_len| to
// EVP_DecryptUpdate_ex decrypts `in_len` bytes from `in` and writes up to
// `max_out` bytes of plaintext to `out`. On success, it sets `*out_len` to
// the number of output bytes and returns one. Otherwise, it returns zero.
//
// If |max_out| is not large enough for the output, the function will return
// If `max_out` is not large enough for the output, the function will return
// zero. The size of output buffer needed depends on the cipher and the number
// of bytes decrypted by |ctx| thus far.
// of bytes decrypted by `ctx` thus far.
//
// In ciphers whose block size is not 1, such as CBC, individual calls to
// |EVP_DecryptUpdate_ex| may output more or less than |in_len| bytes: a single
// call to |EVP_DecryptUpdate_ex| may output at most |in_len + block_size - 1|
// bytes. Additionally, the total output across all |EVP_DecryptUpdate_ex| and
// |EVP_DecryptFinal_ex2| calls will be at most the total input.
// `EVP_DecryptUpdate_ex` may output more or less than `in_len` bytes: a single
// call to `EVP_DecryptUpdate_ex` may output at most `in_len + block_size - 1`
// bytes. Additionally, the total output across all `EVP_DecryptUpdate_ex` and
// `EVP_DecryptFinal_ex2` calls will be at most the total input.
//
// WARNING: if the cipher is an AEAD cipher, decrypted data should not be
// parsed or otherwise processed until success has been returned by
// |EVP_EncryptFinal_ex2|.
// `EVP_EncryptFinal_ex2`.
OPENSSL_EXPORT int EVP_DecryptUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len,
const uint8_t *in, size_t in_len);
// EVP_DecryptFinal_ex2 finishes a decryption operation and writes up to
// |max_out| bytes of output to out. On success, it sets |*out_len| to the
// `max_out` bytes of output to out. On success, it sets `*out_len` to the
// number of bytes written and returns one. Otherwise, it returns zero.
//
// If |max_out| is not large enough for the output, the function will return
// If `max_out` is not large enough for the output, the function will return
// zero. The size of output buffer needed depends on the cipher and the number
// of bytes decrypted.
//
@@ -206,83 +206,83 @@ OPENSSL_EXPORT int EVP_DecryptUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
OPENSSL_EXPORT int EVP_DecryptFinal_ex2(EVP_CIPHER_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len);
// EVP_CipherUpdate_ex calls either |EVP_EncryptUpdate_ex| or
// |EVP_DecryptUpdate_ex| depending on how |ctx| has been setup.
// EVP_CipherUpdate_ex calls either `EVP_EncryptUpdate_ex` or
// `EVP_DecryptUpdate_ex` depending on how `ctx` has been setup.
OPENSSL_EXPORT int EVP_CipherUpdate_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len,
const uint8_t *in, size_t in_len);
// EVP_CipherUpdateAAD adds |in_len| bytes from |in| to the AAD. The AAD must
// EVP_CipherUpdateAAD adds `in_len` bytes from `in` to the AAD. The AAD must
// be fully specified in this way before any plaintext or ciphertext is
// supplied to the other functions. Please consider moving to the |EVP_AEAD|
// supplied to the other functions. Please consider moving to the `EVP_AEAD`
// APIs instead.
OPENSSL_EXPORT int EVP_CipherUpdateAAD(EVP_CIPHER_CTX *ctx, const uint8_t *in,
size_t in_len);
// EVP_CipherFinal_ex2 calls either |EVP_EncryptFinal_ex2| or
// |EVP_DecryptFinal_ex2| depending on how |ctx| has been setup.
// EVP_CipherFinal_ex2 calls either `EVP_EncryptFinal_ex2` or
// `EVP_DecryptFinal_ex2` depending on how `ctx` has been setup.
OPENSSL_EXPORT int EVP_CipherFinal_ex2(EVP_CIPHER_CTX *ctx, uint8_t *out,
size_t *out_len, size_t max_out_len);
// Cipher context accessors.
// EVP_CIPHER_CTX_cipher returns the |EVP_CIPHER| underlying |ctx|, or NULL if
// 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
// 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_encrypting returns one if |ctx| is configured for encryption
// EVP_CIPHER_CTX_encrypting returns one if `ctx` is configured for encryption
// and zero otherwise.
OPENSSL_EXPORT int EVP_CIPHER_CTX_encrypting(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
// 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.
// 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.
// 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.
// `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|.
// `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.
// `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
// 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
// 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
// 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
// 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,
@@ -291,26 +291,26 @@ OPENSSL_EXPORT int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *ctx,
// Cipher accessors.
// EVP_CIPHER_nid returns a NID identifying |cipher|. (For example,
// |NID_aes_128_gcm|.)
// 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.
// 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.
// 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.
// 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.
// `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.
@@ -319,31 +319,31 @@ 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 an optional |salt|, writing the result to
// |key| and |iv|. If not NULL, the |key| and |iv| buffers must have enough
// space to hold a key and IV for |type|, as returned by |EVP_CIPHER_key_length|
// and |EVP_CIPHER_iv_length|. This function returns the length of the key
// EVP_BytesToKey generates a key and IV for the cipher `type` by iterating
// `md` `count` times using `data` and an optional `salt`, writing the result to
// `key` and `iv`. If not NULL, the `key` and `iv` buffers must have enough
// space to hold a key and IV for `type`, as returned by `EVP_CIPHER_key_length`
// and `EVP_CIPHER_iv_length`. This function returns the length of the key
// (without the IV) on success or zero on error.
//
// If |salt| is NULL, the empty string is used as the salt. Salt lengths other
// than 0 and 8 are not supported by this function. Either of |key| or |iv| may
// If `salt` is NULL, the empty string is used as the salt. Salt lengths other
// than 0 and 8 are not supported by this function. Either of `key` or `iv` may
// be NULL to skip that output.
//
// When the total data derived is less than the size of |md|, this function
// When the total data derived is less than the size of `md`, this function
// implements PBKDF1 from RFC 8018. Otherwise, it generalizes PBKDF1 by
// computing prepending the previous output to |data| and re-running PBKDF1 for
// computing prepending the previous output to `data` and re-running PBKDF1 for
// further output.
//
// This function is provided for compatibility with legacy uses of PBKDF1. New
// applications should use a more modern algorithm, such as |EVP_PBE_scrypt|.
// applications should use a more modern algorithm, such as `EVP_PBE_scrypt`.
OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
const uint8_t salt[8], const uint8_t *data,
size_t data_len, unsigned count, uint8_t *key,
uint8_t *iv);
// Cipher modes (for |EVP_CIPHER_mode|).
// Cipher modes (for `EVP_CIPHER_mode`).
#define EVP_CIPH_STREAM_CIPHER 0x0
#define EVP_CIPH_ECB_MODE 0x1
@@ -354,30 +354,30 @@ OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
#define EVP_CIPH_GCM_MODE 0x6
#define EVP_CIPH_XTS_MODE 0x7
// The following values are never returned from |EVP_CIPHER_mode| and are
// The following values are never returned from `EVP_CIPHER_mode` and are
// included only to make it easier to compile code with BoringSSL.
#define EVP_CIPH_CCM_MODE 0x8
#define EVP_CIPH_OCB_MODE 0x9
#define EVP_CIPH_WRAP_MODE 0xa
// Cipher flags (for |EVP_CIPHER_flags|).
// 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
// 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|.
// 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|.
// initialising an `EVP_CIPHER_CTX`.
#define EVP_CIPH_CTRL_INIT 0x200
// EVP_CIPH_FLAG_CUSTOM_CIPHER indicates that the cipher manages blocking
@@ -389,8 +389,8 @@ OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
// 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|
// 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
@@ -403,114 +403,114 @@ OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
// 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.
// 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.
// 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.
// 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_CipherUpdate does the same as |EVP_CipherUpdate_ex|, except that no
// EVP_CipherUpdate does the same as `EVP_CipherUpdate_ex`, except that no
// output size is given and thus no bounds checking is performed.
//
// Additionally, if |ctx| is an AEAD cipher, e.g. |EVP_aes_128_gcm|, and |out|
// is NULL, this function instead behaves like |EVP_CipherUpdateAAD|.
// Additionally, if `ctx` is an AEAD cipher, e.g. `EVP_aes_128_gcm`, and `out`
// is NULL, this function instead behaves like `EVP_CipherUpdateAAD`.
//
// WARNING: This function does not check bounds on |out|, and correctly sizing
// the output buffer is difficult. Use |EVP_CipherUpdate_ex| or
// |EVP_CipherUpdateAAD| instead.
// WARNING: This function does not check bounds on `out`, and correctly sizing
// the output buffer is difficult. Use `EVP_CipherUpdate_ex` or
// `EVP_CipherUpdateAAD` instead.
OPENSSL_EXPORT int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len, const uint8_t *in,
int in_len);
// EVP_EncryptUpdate does the same as |EVP_EncryptUpdate_ex|, except that no
// EVP_EncryptUpdate does the same as `EVP_EncryptUpdate_ex`, except that no
// output size is given and thus no bounds checking is performed.
//
// Additionally, if |ctx| is an AEAD cipher, e.g. |EVP_aes_128_gcm|, and |out|
// is NULL, this function instead behaves like |EVP_CipherUpdateAAD|.
// Additionally, if `ctx` is an AEAD cipher, e.g. `EVP_aes_128_gcm`, and `out`
// is NULL, this function instead behaves like `EVP_CipherUpdateAAD`.
//
// WARNING: This function does not check bounds on |out|, and correctly sizing
// the output buffer is difficult. Use |EVP_EncryptUpdate_ex| or
// |EVP_CipherUpdateAAD| instead.
// WARNING: This function does not check bounds on `out`, and correctly sizing
// the output buffer is difficult. Use `EVP_EncryptUpdate_ex` or
// `EVP_CipherUpdateAAD` instead.
OPENSSL_EXPORT int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len, const uint8_t *in,
int in_len);
// EVP_DecryptUpdate does the same as |EVP_DecryptUpdate_ex|, except that no
// EVP_DecryptUpdate does the same as `EVP_DecryptUpdate_ex`, except that no
// output size is given and thus no bounds checking is performed.
//
// Additionally, if |ctx| is an AEAD cipher, e.g. |EVP_aes_128_gcm|, and |out|
// is NULL, this function instead behaves like |EVP_CipherUpdateAAD|.
// Additionally, if `ctx` is an AEAD cipher, e.g. `EVP_aes_128_gcm`, and `out`
// is NULL, this function instead behaves like `EVP_CipherUpdateAAD`.
//
// WARNING: This function does not check bounds on out, and correctly sizing
// the output buffer is difficult. Use |EVP_DecryptUpdate_ex| or
// |EVP_CipherUpdateAAD| instead.
// the output buffer is difficult. Use `EVP_DecryptUpdate_ex` or
// `EVP_CipherUpdateAAD` instead.
OPENSSL_EXPORT int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len, const uint8_t *in,
int in_len);
// EVP_CipherFinal calls |EVP_CipherFinal_ex|.
// EVP_CipherFinal calls `EVP_CipherFinal_ex`.
OPENSSL_EXPORT int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_CipherFinal_ex does the same as |EVP_CipherFinal_ex2|, except that no
// EVP_CipherFinal_ex does the same as `EVP_CipherFinal_ex2`, except that no
// output size is given and thus no bounds checking is performed.
//
// WARNING: This function does not check bounds on out, and correctly sizing
// the output buffer is difficult. Use |EVP_CipherFinal_ex2| instead.
// the output buffer is difficult. Use `EVP_CipherFinal_ex2` instead.
OPENSSL_EXPORT int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_EncryptFinal calls |EVP_EncryptFinal_ex|.
// EVP_EncryptFinal calls `EVP_EncryptFinal_ex`.
OPENSSL_EXPORT int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_EncryptFinal_ex does the same as |EVP_EncryptFinal_ex2|, except that no
// EVP_EncryptFinal_ex does the same as `EVP_EncryptFinal_ex2`, except that no
// output size is given and thus no bounds checking is performed.
//
// WARNING: This function does not check bounds on out, and correctly sizing
// the output buffer is difficult. Use |EVP_EncryptFinal_ex2| instead.
// the output buffer is difficult. Use `EVP_EncryptFinal_ex2` instead.
OPENSSL_EXPORT int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_DecryptFinal calls |EVP_DecryptFinal_ex|.
// EVP_DecryptFinal calls `EVP_DecryptFinal_ex`.
OPENSSL_EXPORT int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_DecryptFinal_ex does the same as |EVP_DecryptFinal_ex2|, except that no
// EVP_DecryptFinal_ex does the same as `EVP_DecryptFinal_ex2`, except that no
// output size is given and thus no bounds checking is performed.
//
// WARNING: This function does not check bounds on out, and correctly sizing
// the output buffer is difficult. Use |EVP_DecryptFinal_ex2| instead.
// the output buffer is difficult. Use `EVP_DecryptFinal_ex2` instead.
OPENSSL_EXPORT int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, uint8_t *out,
int *out_len);
// EVP_Cipher historically exposed an internal implementation detail of |ctx|
// and should not be used. Use |EVP_CipherUpdate| and |EVP_CipherFinal_ex|
// EVP_Cipher historically exposed an internal implementation detail of `ctx`
// and should not be used. Use `EVP_CipherUpdate` and `EVP_CipherFinal_ex`
// instead.
//
// If |ctx|'s cipher does not have the |EVP_CIPH_FLAG_CUSTOM_CIPHER| flag, it
// encrypts or decrypts |in_len| bytes from |in| and writes the resulting
// |in_len| bytes to |out|. It returns one on success and zero on error.
// |in_len| must be a multiple of the cipher's block size, or the behavior is
// If `ctx`'s cipher does not have the `EVP_CIPH_FLAG_CUSTOM_CIPHER` flag, it
// encrypts or decrypts `in_len` bytes from `in` and writes the resulting
// `in_len` bytes to `out`. It returns one on success and zero on error.
// `in_len` must be a multiple of the cipher's block size, or the behavior is
// undefined.
//
// TODO(davidben): Rather than being undefined (it'll often round the length up
// and likely read past the buffer), just fail the operation.
//
// If |ctx|'s cipher has the |EVP_CIPH_FLAG_CUSTOM_CIPHER| flag, it runs in one
// of two modes: If |in| is non-NULL, it behaves like |EVP_CipherUpdate|. If
// |in| is NULL, it behaves like |EVP_CipherFinal_ex|. In both cases, it returns
// |*out_len| on success and -1 on error.
// If `ctx`'s cipher has the `EVP_CIPH_FLAG_CUSTOM_CIPHER` flag, it runs in one
// of two modes: If `in` is non-NULL, it behaves like `EVP_CipherUpdate`. If
// `in` is NULL, it behaves like `EVP_CipherFinal_ex`. In both cases, it returns
// `*out_len` on success and -1 on error.
//
// WARNING: The two possible calling conventions of this function signal errors
// incompatibly. In the first, zero indicates an error. In the second, zero
@@ -521,20 +521,20 @@ OPENSSL_EXPORT int EVP_Cipher(EVP_CIPHER_CTX *ctx, uint8_t *out,
// 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. Note using this function links almost
// EVP_get_cipherbyname returns an `EVP_CIPHER` given a human readable name in
// `name`, or NULL if the name is unknown. Note using this function links almost
// every cipher implemented by BoringSSL into the binary, not just the ones the
// caller requests. Size-conscious callers, such as client software, should not
// use this function.
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.
// `EVP_CIPH_FLAG_CUSTOM_CIPHER`. Use `EVP_aead_aes_128_gcm` and
// `EVP_aead_aes_256_gcm` instead.
//
// WARNING: Although these APIs allow streaming an individual AES-GCM operation,
// this is not secure. Until calling |EVP_DecryptFinal_ex|, the tag has not yet
// been checked and output released by |EVP_DecryptUpdate| is unauthenticated
// this is not secure. Until calling `EVP_DecryptFinal_ex`, the tag has not yet
// been checked and output released by `EVP_DecryptUpdate` is unauthenticated
// and easily manipulated by attackers. Callers must buffer the output and may
// not act on it until the entire operation is complete.
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_gcm(void);
@@ -547,27 +547,27 @@ OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ctr(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_gcm(void);
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ofb(void);
// EVP_des_ede3_ecb is an alias for |EVP_des_ede3|. Use the former instead.
// EVP_des_ede3_ecb is an alias for `EVP_des_ede3`. Use the former instead.
OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede3_ecb(void);
// EVP_aes_128_cfb128 is only available in decrepit.
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_cfb128(void);
// EVP_aes_128_cfb is an alias for |EVP_aes_128_cfb128| and is only available in
// EVP_aes_128_cfb is an alias for `EVP_aes_128_cfb128` and is only available in
// decrepit.
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_cfb(void);
// EVP_aes_192_cfb128 is only available in decrepit.
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cfb128(void);
// EVP_aes_192_cfb is an alias for |EVP_aes_192_cfb128| and is only available in
// EVP_aes_192_cfb is an alias for `EVP_aes_192_cfb128` and is only available in
// decrepit.
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cfb(void);
// EVP_aes_256_cfb128 is only available in decrepit.
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_cfb128(void);
// EVP_aes_256_cfb is an alias for |EVP_aes_256_cfb128| and is only available in
// EVP_aes_256_cfb is an alias for `EVP_aes_256_cfb128` and is only available in
// decrepit.
OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_cfb(void);
@@ -600,7 +600,7 @@ OPENSSL_EXPORT void EVP_CIPHER_CTX_set_flags(const EVP_CIPHER_CTX *ctx,
// EVP_CIPH_NO_PADDING disables padding in block ciphers.
#define EVP_CIPH_NO_PADDING 0x800
// The following are |EVP_CIPHER_CTX_ctrl| commands.
// The following are `EVP_CIPHER_CTX_ctrl` commands.
#define EVP_CTRL_INIT 0x0
#define EVP_CTRL_SET_KEY_LENGTH 0x1
#define EVP_CTRL_GET_RC2_KEY_BITS 0x2
@@ -625,7 +625,7 @@ OPENSSL_EXPORT void EVP_CIPHER_CTX_set_flags(const EVP_CIPHER_CTX *ctx,
#define EVP_GCM_TLS_EXPLICIT_IV_LEN 8
#define EVP_GCM_TLS_TAG_LEN 16
// The following are legacy aliases for AEAD |EVP_CIPHER_CTX_ctrl| values.
// The following are legacy aliases for AEAD `EVP_CIPHER_CTX_ctrl` values.
#define EVP_CTRL_GCM_SET_IVLEN EVP_CTRL_AEAD_SET_IVLEN
#define EVP_CTRL_GCM_GET_TAG EVP_CTRL_AEAD_GET_TAG
#define EVP_CTRL_GCM_SET_TAG EVP_CTRL_AEAD_SET_TAG
@@ -642,17 +642,17 @@ struct evp_cipher_ctx_st {
// app_data is a pointer to opaque, user data.
void *app_data; // application stuff
// cipher_data points to the |cipher| specific state.
// cipher_data points to the `cipher` specific state.
void *cipher_data;
// key_len contains the length of the key, which may differ from
// |cipher->key_len| if the cipher can take a variable key length.
// `cipher->key_len` if the cipher can take a variable key length.
unsigned key_len;
// encrypt is one if encrypting and zero if decrypting.
int encrypt;
// flags contains the OR of zero or more |EVP_CIPH_*| flags, above.
// flags contains the OR of zero or more `EVP_CIPH_*` flags, above.
uint32_t flags;
// oiv contains the original IV value.
@@ -666,14 +666,14 @@ struct evp_cipher_ctx_st {
uint8_t buf[EVP_MAX_BLOCK_LENGTH];
// buf_len contains the number of bytes of a partial block contained in
// |buf|.
// `buf`.
int buf_len;
// num contains the number of bytes of |iv| which are valid for modes that
// num contains the number of bytes of `iv` which are valid for modes that
// manage partial blocks themselves.
unsigned num;
// final_used is non-zero if the |final| buffer contains plaintext.
// final_used is non-zero if the `final` buffer contains plaintext.
int final_used;
uint8_t final[EVP_MAX_BLOCK_LENGTH]; // possible final block
include/openssl/cmac.h
+13 -13
View File
@@ -30,8 +30,8 @@ extern "C" {
// One-shot functions.
// AES_CMAC calculates the 16-byte, CMAC authenticator of |in_len| bytes of
// |in| and writes it to |out|. The |key_len| may be 16 or 32 bytes to select
// AES_CMAC calculates the 16-byte, CMAC authenticator of `in_len` bytes of
// `in` and writes it to `out`. The `key_len` may be 16 or 32 bytes to select
// between AES-128 and AES-256. It returns one on success or zero on error.
OPENSSL_EXPORT int AES_CMAC(uint8_t out[16], const uint8_t *key, size_t key_len,
const uint8_t *in, size_t in_len);
@@ -39,36 +39,36 @@ OPENSSL_EXPORT int AES_CMAC(uint8_t out[16], const uint8_t *key, size_t key_len,
// Incremental interface.
// CMAC_CTX_new allocates a fresh |CMAC_CTX| and returns it, or NULL on
// CMAC_CTX_new allocates a fresh `CMAC_CTX` and returns it, or NULL on
// error.
OPENSSL_EXPORT CMAC_CTX *CMAC_CTX_new(void);
// CMAC_CTX_free frees a |CMAC_CTX|.
// CMAC_CTX_free frees a `CMAC_CTX`.
OPENSSL_EXPORT void CMAC_CTX_free(CMAC_CTX *ctx);
// CMAC_CTX_copy sets |out| to be a duplicate of the current state |in|. It
// CMAC_CTX_copy sets `out` to be a duplicate of the current state `in`. It
// returns one on success and zero on error.
OPENSSL_EXPORT int CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in);
// CMAC_Init configures |ctx| to use the given |key| and |cipher|. The CMAC RFC
// only specifies the use of AES-128 thus |key_len| should be 16 and |cipher|
// should be |EVP_aes_128_cbc()|. However, this implementation also supports
// AES-256 by setting |key_len| to 32 and |cipher| to |EVP_aes_256_cbc()|. The
// |engine| argument is ignored.
// CMAC_Init configures `ctx` to use the given `key` and `cipher`. The CMAC RFC
// only specifies the use of AES-128 thus `key_len` should be 16 and `cipher`
// should be `EVP_aes_128_cbc()`. However, this implementation also supports
// AES-256 by setting `key_len` to 32 and `cipher` to `EVP_aes_256_cbc()`. The
// `engine` argument is ignored.
//
// It returns one on success or zero on error.
OPENSSL_EXPORT int CMAC_Init(CMAC_CTX *ctx, const void *key, size_t key_len,
const EVP_CIPHER *cipher, ENGINE *engine);
// CMAC_Reset resets |ctx| so that a fresh message can be authenticated.
// CMAC_Reset resets `ctx` so that a fresh message can be authenticated.
OPENSSL_EXPORT int CMAC_Reset(CMAC_CTX *ctx);
// CMAC_Update processes |in_len| bytes of message from |in|. It returns one on
// CMAC_Update processes `in_len` bytes of message from `in`. It returns one on
// success or zero on error.
OPENSSL_EXPORT int CMAC_Update(CMAC_CTX *ctx, const uint8_t *in, size_t in_len);
// CMAC_Final sets |*out_len| to 16 and, if |out| is not NULL, writes 16 bytes
// CMAC_Final sets `*out_len` to 16 and, if `out` is not NULL, writes 16 bytes
// of authenticator to it. It returns one on success or zero on error.
OPENSSL_EXPORT int CMAC_Final(CMAC_CTX *ctx, uint8_t *out, size_t *out_len);
include/openssl/cms.h
+33 -33
View File
@@ -31,10 +31,10 @@ extern "C" {
// for S/MIME, is out of scope for BoringSSL.
//
// As this library is intentionally not a general CMS implementation, BoringSSL
// continues to define |OPENSSL_NO_CMS|, so that most callers turn off their
// continues to define `OPENSSL_NO_CMS`, so that most callers turn off their
// general-purpose CMS code. In callers that are compatible with this subset,
// the |BORINGSSL_NO_NO_CMS| build option can be used to suppress
// |OPENSSL_NO_CMS|.
// the `BORINGSSL_NO_NO_CMS` build option can be used to suppress
// `OPENSSL_NO_CMS`.
DECLARE_STACK_OF(X509)
@@ -51,79 +51,79 @@ DECLARE_STACK_OF(X509)
#define CMS_USE_KEYID 0x10000
#define CMS_NO_SIGNING_TIME 0x400000
// CMS_sign returns a newly-allocated |CMS_ContentInfo| structure for building a
// CMS_sign returns a newly-allocated `CMS_ContentInfo` structure for building a
// SignedData (RFC 5652), or NULL on error.
//
// |certs| must be NULL or zero length. BoringSSL does not support embedding
// `certs` must be NULL or zero length. BoringSSL does not support embedding
// certificates in SignedData.
//
// |flags| must contain |CMS_DETACHED|, which indicates an external signature.
// `flags` must contain `CMS_DETACHED`, which indicates an external signature.
// BoringSSL only supports generating external signatures and does not support
// embedding encapsulated content directly in a SignedData.
//
// If |pkey| is non-NULL, |CMS_add1_signer| is automatically called with
// |signcert|, |pkey|, a default hash of SHA-256, and |flags|. |flags| will then
// additionally be interpreted as in |CMS_add1_signer|.
// If `pkey` is non-NULL, `CMS_add1_signer` is automatically called with
// `signcert`, `pkey`, a default hash of SHA-256, and `flags`. `flags` will then
// additionally be interpreted as in `CMS_add1_signer`.
//
// If |CMS_PARTIAL| or |CMS_STREAM| is set in |flags|, the object will be left
// incomplete. |data| will then be ignored and should be NULL. The caller can
// then continue configuring it and finalizing it with |CMS_final|. Otherwise,
// the object will be finalized with |data| and |flags| passed to |CMS_final|.
// If `CMS_PARTIAL` or `CMS_STREAM` is set in `flags`, the object will be left
// incomplete. `data` will then be ignored and should be NULL. The caller can
// then continue configuring it and finalizing it with `CMS_final`. Otherwise,
// the object will be finalized with `data` and `flags` passed to `CMS_final`.
OPENSSL_EXPORT CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey,
STACK_OF(X509) *certs, BIO *data,
uint32_t flags);
// CMS_ContentInfo_free releases memory associated with |cms|.
// CMS_ContentInfo_free releases memory associated with `cms`.
OPENSSL_EXPORT void CMS_ContentInfo_free(CMS_ContentInfo *cms);
// CMS_add1_signer adds a signer to |cms|, which must be a SignedData created by
// |CMS_sign|, with the |CMS_PARTIAL| flag set. The signer will use |signcert|,
// |pkey|, and |md| for the signing certificate, private key, and digest
// CMS_add1_signer adds a signer to `cms`, which must be a SignedData created by
// `CMS_sign`, with the `CMS_PARTIAL` flag set. The signer will use `signcert`,
// `pkey`, and `md` for the signing certificate, private key, and digest
// algorithm, respectively. It returns a non-NULL pointer to the signer on
// success, and NULL on error. The signer is owned by |cms| and should not be
// success, and NULL on error. The signer is owned by `cms` and should not be
// released by the caller.
//
// |flags| is interpreted as follows:
// `flags` is interpreted as follows:
//
// - |CMS_PARTIAL| must not be set. BoringSSL does not support configuring a
// - `CMS_PARTIAL` must not be set. BoringSSL does not support configuring a
// signer in multiple steps.
//
// - |CMS_NOCERTS| must be set. BoringSSL does not support embedding
// - `CMS_NOCERTS` must be set. BoringSSL does not support embedding
// certificates in SignedData.
//
// - |CMS_NOATTR| must be set. BoringSSL does not support attributes in
// - `CMS_NOATTR` must be set. BoringSSL does not support attributes in
// SignedData.
//
// - If |CMS_USE_KEYID| is set, SignerInfos will be identified by subject key
// identifier instead of issuer and serial number. |signcert| must then have
// - If `CMS_USE_KEYID` is set, SignerInfos will be identified by subject key
// identifier instead of issuer and serial number. `signcert` must then have
// the subject key identifier extension.
//
// BoringSSL currently only supports one signer per |CMS_ContentInfo|.
// BoringSSL currently only supports one signer per `CMS_ContentInfo`.
// Subsequent calls will fail. Additionally, only RSA keys are currently
// supported for |pkey|.
// supported for `pkey`.
OPENSSL_EXPORT CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms,
X509 *signcert, EVP_PKEY *pkey,
const EVP_MD *md,
uint32_t flags);
// CMS_final finalizes constructing |cms|, which must have been initialized with
// the |CMS_PARTIAL| flag. |data| is read, until EOF, as the data to be
// CMS_final finalizes constructing `cms`, which must have been initialized with
// the `CMS_PARTIAL` flag. `data` is read, until EOF, as the data to be
// processed by CMS. It returns one on success and zero on error.
//
// |CMS_BINARY| must be set in |flags|. BoringSSL does not support translating
// `CMS_BINARY` must be set in `flags`. BoringSSL does not support translating
// inputs according to S/MIME.
//
// |dcont| must be NULL. What a non-NULL |dcont| does is not clearly documented
// `dcont` must be NULL. What a non-NULL `dcont` does is not clearly documented
// by OpenSSL, and there are no tests to demonstrate its behavior.
OPENSSL_EXPORT int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont,
uint32_t flags);
// i2d_CMS_bio encodes |cms| as a DER-encoded ContentInfo structure (RFC 5652).
// i2d_CMS_bio encodes `cms` as a DER-encoded ContentInfo structure (RFC 5652).
// It returns one on success and zero on failure.
OPENSSL_EXPORT int i2d_CMS_bio(BIO *out, CMS_ContentInfo *cms);
// i2d_CMS_bio_stream calls |i2d_CMS_bio|. |in| must be NULL and |flags| must
// not contain |CMS_STREAM|. BoringSSL does not support any streaming modes for
// i2d_CMS_bio_stream calls `i2d_CMS_bio`. `in` must be NULL and `flags` must
// not contain `CMS_STREAM`. BoringSSL does not support any streaming modes for
// CMS.
OPENSSL_EXPORT int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *in,
int flags);
include/openssl/conf.h
+12 -12
View File
@@ -36,7 +36,7 @@ extern "C" {
// [section_name]
// key2=value2
//
// Config files are represented by a |CONF|. Use of this module is strongly
// Config files are represented by a `CONF`. Use of this module is strongly
// discouraged. It is a remnant of the OpenSSL command-line tool. Parsing an
// untrusted input as a config file risks string injection and denial of service
// vulnerabilities.
@@ -51,32 +51,32 @@ struct conf_value_st {
DEFINE_STACK_OF(CONF_VALUE)
// NCONF_new returns a fresh, empty |CONF|, or NULL on error. The |method|
// NCONF_new returns a fresh, empty `CONF`, or NULL on error. The `method`
// argument must be NULL.
OPENSSL_EXPORT CONF *NCONF_new(void *method);
// NCONF_free frees all the data owned by |conf| and then |conf| itself.
// NCONF_free frees all the data owned by `conf` and then `conf` itself.
OPENSSL_EXPORT void NCONF_free(CONF *conf);
// NCONF_load parses the file named |filename| and adds the values found to
// |conf|. It returns one on success and zero on error. In the event of an
// error, if |out_error_line| is not NULL, |*out_error_line| is set to the
// NCONF_load parses the file named `filename` and adds the values found to
// `conf`. It returns one on success and zero on error. In the event of an
// error, if `out_error_line` is not NULL, `*out_error_line` is set to the
// number of the line that contained the error.
OPENSSL_EXPORT int NCONF_load(CONF *conf, const char *filename,
long *out_error_line);
// NCONF_load_bio acts like |NCONF_load| but reads from |bio| rather than from
// NCONF_load_bio acts like `NCONF_load` but reads from `bio` rather than from
// a named file.
OPENSSL_EXPORT int NCONF_load_bio(CONF *conf, BIO *bio, long *out_error_line);
// NCONF_get_section returns a stack of values for a given section in |conf|.
// If |section| is NULL, the default section is returned. It returns NULL on
// NCONF_get_section returns a stack of values for a given section in `conf`.
// If `section` is NULL, the default section is returned. It returns NULL on
// error.
OPENSSL_EXPORT const STACK_OF(CONF_VALUE) *NCONF_get_section(
const CONF *conf, const char *section);
// NCONF_get_string returns the value of the key |name|, in section |section|.
// The |section| argument may be NULL to indicate the default section. It
// NCONF_get_string returns the value of the key `name`, in section `section`.
// The `section` argument may be NULL to indicate the default section. It
// returns the value or NULL on error.
OPENSSL_EXPORT const char *NCONF_get_string(const CONF *conf,
const char *section,
@@ -91,7 +91,7 @@ OPENSSL_EXPORT const char *NCONF_get_string(const CONF *conf,
#define CONF_MFLAGS_IGNORE_MISSING_FILE 0
// CONF_modules_load_file returns one. BoringSSL is defined to have no config
// file options, thus loading from |filename| always succeeds by doing nothing.
// file options, thus loading from `filename` always succeeds by doing nothing.
OPENSSL_EXPORT int CONF_modules_load_file(const char *filename,
const char *appname,
unsigned long flags);
include/openssl/crypto.h
+9 -9
View File
@@ -18,11 +18,11 @@
#include <openssl/base.h> // IWYU pragma: export
#include <openssl/sha.h>
// Upstream OpenSSL defines |OPENSSL_malloc|, etc., in crypto.h rather than
// Upstream OpenSSL defines `OPENSSL_malloc`, etc., in crypto.h rather than
// mem.h.
#include <openssl/mem.h>
// Upstream OpenSSL defines |CRYPTO_LOCK|, etc., in crypto.h rather than
// Upstream OpenSSL defines `CRYPTO_LOCK`, etc., in crypto.h rather than
// thread.h.
#include <openssl/thread.h>
@@ -111,7 +111,7 @@ enum fips_counter_t {
};
// FIPS_read_counter returns a counter of the number of times the specific
// function denoted by |counter| has been used. This always returns zero unless
// function denoted by `counter` has been used. This always returns zero unless
// BoringSSL was built with BORINGSSL_FIPS_COUNTERS defined.
OPENSSL_EXPORT size_t FIPS_read_counter(enum fips_counter_t counter);
@@ -129,7 +129,7 @@ OPENSSL_EXPORT size_t FIPS_read_counter(enum fips_counter_t counter);
#define OPENSSL_DIR 4
// OpenSSL_version is a compatibility function that returns the string
// "BoringSSL" if |which| is |OPENSSL_VERSION| and placeholder strings
// "BoringSSL" if `which` is `OPENSSL_VERSION` and placeholder strings
// otherwise.
OPENSSL_EXPORT const char *OpenSSL_version(int which);
@@ -139,7 +139,7 @@ OPENSSL_EXPORT const char *OpenSSL_version(int which);
#define SSLEAY_PLATFORM OPENSSL_PLATFORM
#define SSLEAY_DIR OPENSSL_DIR
// SSLeay_version calls |OpenSSL_version|.
// SSLeay_version calls `OpenSSL_version`.
OPENSSL_EXPORT const char *SSLeay_version(int which);
// SSLeay is a compatibility function that returns OPENSSL_VERSION_NUMBER from
@@ -196,8 +196,8 @@ OPENSSL_EXPORT int OPENSSL_init_crypto(uint64_t opts,
// OPENSSL_cleanup does nothing.
OPENSSL_EXPORT void OPENSSL_cleanup(void);
// FIPS_mode_set returns one if |on| matches whether BoringSSL was built with
// |BORINGSSL_FIPS| and zero otherwise.
// FIPS_mode_set returns one if `on` matches whether BoringSSL was built with
// `BORINGSSL_FIPS` and zero otherwise.
OPENSSL_EXPORT int FIPS_mode_set(int on);
// FIPS_module_name returns the name of the FIPS module.
@@ -210,10 +210,10 @@ OPENSSL_EXPORT const uint8_t *FIPS_module_hash(void);
// isn't exactly at a verified version. The version, expressed in base 10, will
// be a date in the form yyyymmdd.
//
// (This format exceeds a |uint32_t| in the year 4294.)
// (This format exceeds a `uint32_t` in the year 4294.)
OPENSSL_EXPORT uint32_t FIPS_version(void);
// FIPS_query_algorithm_status returns one if |algorithm| is FIPS validated in
// FIPS_query_algorithm_status returns one if `algorithm` is FIPS validated in
// the current BoringSSL and zero otherwise.
OPENSSL_EXPORT int FIPS_query_algorithm_status(const char *algorithm);
include/openssl/ctrdrbg.h
+12 -12
View File
@@ -53,17 +53,17 @@ extern "C" {
#define CTR_DRBG_NONCE_LEN 16
// CTR_DRBG_MAX_GENERATE_LENGTH is the maximum number of bytes that can be
// generated in a single call to |CTR_DRBG_generate|.
// generated in a single call to `CTR_DRBG_generate`.
#define CTR_DRBG_MAX_GENERATE_LENGTH 65536
// CTR_DRBG_new returns an initialized |CTR_DRBG_STATE|, or NULL if either
// allocation failed or if |personalization_len| is invalid. This DRBG will not
// CTR_DRBG_new returns an initialized `CTR_DRBG_STATE`, or NULL if either
// allocation failed or if `personalization_len` is invalid. This DRBG will not
// use a derivation function.
OPENSSL_EXPORT CTR_DRBG_STATE *CTR_DRBG_new(
const uint8_t entropy[CTR_DRBG_ENTROPY_LEN], const uint8_t *personalization,
size_t personalization_len);
// CTR_DRBG_new_df returns an initialized |CTR_DRBG_STATE|, or NULL if either
// CTR_DRBG_new_df returns an initialized `CTR_DRBG_STATE`, or NULL if either
// allocation failed or if an argument is invalid. This DRBG will use a
// derivation function.
OPENSSL_EXPORT CTR_DRBG_STATE *CTR_DRBG_new_df(
@@ -71,11 +71,11 @@ OPENSSL_EXPORT CTR_DRBG_STATE *CTR_DRBG_new_df(
const uint8_t nonce[CTR_DRBG_NONCE_LEN], const uint8_t *personalization,
size_t personalization_len);
// CTR_DRBG_free frees |state| if non-NULL, or else does nothing.
// CTR_DRBG_free frees `state` if non-NULL, or else does nothing.
OPENSSL_EXPORT void CTR_DRBG_free(CTR_DRBG_STATE *state);
// CTR_DRBG_reseed reseeds |drbg| given |CTR_DRBG_ENTROPY_LEN| bytes of entropy
// in |entropy| and, optionally, up to |CTR_DRBG_SEED_LEN| bytes of
// CTR_DRBG_reseed reseeds `drbg` given `CTR_DRBG_ENTROPY_LEN` bytes of entropy
// in `entropy` and, optionally, up to `CTR_DRBG_SEED_LEN` bytes of
// additional data. It returns one on success or zero on error.
OPENSSL_EXPORT int CTR_DRBG_reseed(CTR_DRBG_STATE *drbg,
const uint8_t entropy[CTR_DRBG_ENTROPY_LEN],
@@ -83,23 +83,23 @@ OPENSSL_EXPORT int CTR_DRBG_reseed(CTR_DRBG_STATE *drbg,
size_t additional_data_len);
// CTR_DRBG_reseed_ex acts like `CTR_DRBG_reseed` but with variable-length
// entropy input, up to |CTR_DRBG_MAX_ENTROPY_LEN|.
// entropy input, up to `CTR_DRBG_MAX_ENTROPY_LEN`.
OPENSSL_EXPORT int CTR_DRBG_reseed_ex(CTR_DRBG_STATE *drbg,
const uint8_t *entropy,
size_t entropy_len,
const uint8_t *additional_data,
size_t additional_data_len);
// CTR_DRBG_generate processes to up |CTR_DRBG_ENTROPY_LEN| bytes of additional
// data (if any) and then writes |out_len| random bytes to |out|, where
// |out_len| <= |CTR_DRBG_MAX_GENERATE_LENGTH|. It returns one on success or
// CTR_DRBG_generate processes to up `CTR_DRBG_ENTROPY_LEN` bytes of additional
// data (if any) and then writes `out_len` random bytes to `out`, where
// `out_len` <= `CTR_DRBG_MAX_GENERATE_LENGTH`. It returns one on success or
// zero on error.
OPENSSL_EXPORT int CTR_DRBG_generate(CTR_DRBG_STATE *drbg, uint8_t *out,
size_t out_len,
const uint8_t *additional_data,
size_t additional_data_len);
// CTR_DRBG_clear zeroises the state of |drbg|.
// CTR_DRBG_clear zeroises the state of `drbg`.
OPENSSL_EXPORT void CTR_DRBG_clear(CTR_DRBG_STATE *drbg);
include/openssl/curve25519.h
+24 -24
View File
@@ -37,12 +37,12 @@ extern "C" {
#define X25519_PUBLIC_VALUE_LEN 32
#define X25519_SHARED_KEY_LEN 32
// X25519_keypair sets |out_public_value| and |out_private_key| to a freshly
// X25519_keypair sets `out_public_value` and `out_private_key` to a freshly
// generated, public–private key pair.
OPENSSL_EXPORT void X25519_keypair(uint8_t out_public_value[32],
uint8_t out_private_key[32]);
// X25519 writes a shared key to |out_shared_key| that is calculated from the
// X25519 writes a shared key to `out_shared_key` that is calculated from the
// given private key and the peer's public value. It returns one on success and
// zero on error.
//
@@ -53,7 +53,7 @@ OPENSSL_EXPORT int X25519(uint8_t out_shared_key[32],
const uint8_t peer_public_value[32]);
// X25519_public_from_private calculates a Diffie-Hellman public value from the
// given private key and writes it to |out_public_value|.
// given private key and writes it to `out_public_value`.
OPENSSL_EXPORT void X25519_public_from_private(uint8_t out_public_value[32],
const uint8_t private_key[32]);
@@ -72,20 +72,20 @@ OPENSSL_EXPORT void X25519_public_from_private(uint8_t out_public_value[32],
#define ED25519_PUBLIC_KEY_LEN 32
#define ED25519_SIGNATURE_LEN 64
// ED25519_keypair sets |out_public_key| and |out_private_key| to a freshly
// ED25519_keypair sets `out_public_key` and `out_private_key` to a freshly
// generated, public–private key pair.
OPENSSL_EXPORT void ED25519_keypair(uint8_t out_public_key[32],
uint8_t out_private_key[64]);
// ED25519_sign sets |out_sig| to be a signature of |message_len| bytes from
// |message| using |private_key|. It returns one on success or zero on
// ED25519_sign sets `out_sig` to be a signature of `message_len` bytes from
// `message` using `private_key`. It returns one on success or zero on
// allocation failure.
OPENSSL_EXPORT int ED25519_sign(uint8_t out_sig[64], const uint8_t *message,
size_t message_len,
const uint8_t private_key[64]);
// ED25519_verify returns one iff |signature| is a valid signature, by
// |public_key| of |message_len| bytes from |message|. It returns zero
// ED25519_verify returns one iff `signature` is a valid signature, by
// `public_key` of `message_len` bytes from `message`. It returns zero
// otherwise.
OPENSSL_EXPORT int ED25519_verify(const uint8_t *message, size_t message_len,
const uint8_t signature[64],
@@ -118,12 +118,12 @@ enum spake2_role_t {
spake2_role_bob,
};
// SPAKE2_CTX_new creates a new |SPAKE2_CTX| (which can only be used for a
// SPAKE2_CTX_new creates a new `SPAKE2_CTX` (which can only be used for a
// single execution of the protocol). SPAKE2 requires the symmetry of the two
// parties to be broken which is indicated via |my_role| – each party must pass
// parties to be broken which is indicated via `my_role` – each party must pass
// a different value for this argument.
//
// The |my_name| and |their_name| arguments allow optional, opaque names to be
// The `my_name` and `their_name` arguments allow optional, opaque names to be
// bound into the protocol. For example MAC addresses, hostnames, usernames
// etc. These values are not exposed and can avoid context-confusion attacks
// when a password is shared between several devices.
@@ -132,19 +132,19 @@ OPENSSL_EXPORT SPAKE2_CTX *SPAKE2_CTX_new(
const uint8_t *my_name, size_t my_name_len,
const uint8_t *their_name, size_t their_name_len);
// SPAKE2_CTX_free frees |ctx| and all the resources that it has allocated.
// SPAKE2_CTX_free frees `ctx` and all the resources that it has allocated.
OPENSSL_EXPORT void SPAKE2_CTX_free(SPAKE2_CTX *ctx);
// SPAKE2_MAX_MSG_SIZE is the maximum size of a SPAKE2 message.
#define SPAKE2_MAX_MSG_SIZE 32
// SPAKE2_generate_msg generates a SPAKE2 message given |password|, writes
// it to |out| and sets |*out_len| to the number of bytes written.
// SPAKE2_generate_msg generates a SPAKE2 message given `password`, writes
// it to `out` and sets `*out_len` to the number of bytes written.
//
// At most |max_out_len| bytes are written to |out| and, in order to ensure
// success, |max_out_len| should be at least |SPAKE2_MAX_MSG_SIZE| bytes.
// At most `max_out_len` bytes are written to `out` and, in order to ensure
// success, `max_out_len` should be at least `SPAKE2_MAX_MSG_SIZE` bytes.
//
// This function can only be called once for a given |SPAKE2_CTX|.
// This function can only be called once for a given `SPAKE2_CTX`.
//
// It returns one on success and zero on error.
OPENSSL_EXPORT int SPAKE2_generate_msg(SPAKE2_CTX *ctx, uint8_t *out,
@@ -157,8 +157,8 @@ OPENSSL_EXPORT int SPAKE2_generate_msg(SPAKE2_CTX *ctx, uint8_t *out,
#define SPAKE2_MAX_KEY_SIZE 64
// SPAKE2_process_msg completes the SPAKE2 exchange given the peer's message in
// |their_msg|, writes at most |max_out_key_len| bytes to |out_key| and sets
// |*out_key_len| to the number of bytes written.
// `their_msg`, writes at most `max_out_key_len` bytes to `out_key` and sets
// `*out_key_len` to the number of bytes written.
//
// The resulting keying material is suitable for:
// - Using directly in a key-confirmation step: i.e. each side could
@@ -167,13 +167,13 @@ OPENSSL_EXPORT int SPAKE2_generate_msg(SPAKE2_CTX *ctx, uint8_t *out,
// - Using as input keying material to HKDF to generate a variety of subkeys
// for encryption etc.
//
// If |max_out_key_key| is smaller than the amount of key material generated
// If `max_out_key_key` is smaller than the amount of key material generated
// then the key is silently truncated. If you want to ensure that no truncation
// occurs then |max_out_key| should be at least |SPAKE2_MAX_KEY_SIZE|.
// occurs then `max_out_key` should be at least `SPAKE2_MAX_KEY_SIZE`.
//
// You must call |SPAKE2_generate_msg| on a given |SPAKE2_CTX| before calling
// this function. On successful return, |ctx| is complete and calling
// |SPAKE2_CTX_free| is the only acceptable operation on it.
// You must call `SPAKE2_generate_msg` on a given `SPAKE2_CTX` before calling
// this function. On successful return, `ctx` is complete and calling
// `SPAKE2_CTX_free` is the only acceptable operation on it.
//
// Returns one on success or zero on error.
OPENSSL_EXPORT int SPAKE2_process_msg(SPAKE2_CTX *ctx, uint8_t *out_key,
include/openssl/des.h
+22 -22
View File
@@ -49,32 +49,32 @@ typedef struct DES_ks {
#define DES_CBC_MODE 0
#define DES_PCBC_MODE 1
// DES_set_key performs a key schedule and initialises |schedule| with |key|.
// DES_set_key performs a key schedule and initialises `schedule` with `key`.
OPENSSL_EXPORT void DES_set_key(const DES_cblock *key,
DES_key_schedule *schedule);
// DES_set_odd_parity sets the parity bits (the least-significant bits in each
// byte) of |key| given the other bits in each byte.
// byte) of `key` given the other bits in each byte.
OPENSSL_EXPORT void DES_set_odd_parity(DES_cblock *key);
// DES_ecb_encrypt encrypts (or decrypts, if |is_encrypt| is |DES_DECRYPT|) a
// single DES block (8 bytes) from |in| to |out|, using the key configured in
// |schedule|.
// DES_ecb_encrypt encrypts (or decrypts, if `is_encrypt` is `DES_DECRYPT`) a
// single DES block (8 bytes) from `in` to `out`, using the key configured in
// `schedule`.
OPENSSL_EXPORT void DES_ecb_encrypt(const DES_cblock *in, DES_cblock *out,
const DES_key_schedule *schedule,
int is_encrypt);
// DES_ncbc_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) |len|
// bytes from |in| to |out| with DES in CBC mode. |len| must be a multiple of 8.
// The IV is taken from |ivec|. When the function completes, the IV for the next
// block is written to |ivec|.
// DES_ncbc_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) `len`
// bytes from `in` to `out` with DES in CBC mode. `len` must be a multiple of 8.
// The IV is taken from `ivec`. When the function completes, the IV for the next
// block is written to `ivec`.
OPENSSL_EXPORT void DES_ncbc_encrypt(const uint8_t *in, uint8_t *out,
size_t len,
const DES_key_schedule *schedule,
DES_cblock *ivec, int enc);
// DES_ecb3_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) a single
// block (8 bytes) of data from |input| to |output| using 3DES.
// DES_ecb3_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) a single
// block (8 bytes) of data from `input` to `output` using 3DES.
OPENSSL_EXPORT void DES_ecb3_encrypt(const DES_cblock *input,
DES_cblock *output,
const DES_key_schedule *ks1,
@@ -82,11 +82,11 @@ OPENSSL_EXPORT void DES_ecb3_encrypt(const DES_cblock *input,
const DES_key_schedule *ks3,
int enc);
// DES_ede3_cbc_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) |len|
// bytes from |in| to |out| with 3DES in CBC mode. 3DES uses three keys, thus
// the function takes three different |DES_key_schedule|s. |len| must be a
// multiple of 8. The IV is taken from |ivec|. When the function completes, the
// IV for the next block is written to |ivec|.
// DES_ede3_cbc_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) `len`
// bytes from `in` to `out` with 3DES in CBC mode. 3DES uses three keys, thus
// the function takes three different `DES_key_schedule`s. `len` must be a
// multiple of 8. The IV is taken from `ivec`. When the function completes, the
// IV for the next block is written to `ivec`.
OPENSSL_EXPORT void DES_ede3_cbc_encrypt(const uint8_t *in, uint8_t *out,
size_t len,
const DES_key_schedule *ks1,
@@ -94,12 +94,12 @@ OPENSSL_EXPORT void DES_ede3_cbc_encrypt(const uint8_t *in, uint8_t *out,
const DES_key_schedule *ks3,
DES_cblock *ivec, int enc);
// DES_ede2_cbc_encrypt encrypts (or decrypts, if |enc| is |DES_DECRYPT|) |len|
// bytes from |in| to |out| with 3DES in CBC mode. With this keying option, the
// DES_ede2_cbc_encrypt encrypts (or decrypts, if `enc` is `DES_DECRYPT`) `len`
// bytes from `in` to `out` with 3DES in CBC mode. With this keying option, the
// first and third 3DES keys are identical. Thus, this function takes only two
// different |DES_key_schedule|s. |len| must be a multiple of 8. The IV is taken
// from |ivec|. When the function completes, the IV for the next block is
// written to |ivec|.
// different `DES_key_schedule`s. `len` must be a multiple of 8. The IV is taken
// from `ivec`. When the function completes, the IV for the next block is
// written to `ivec`.
OPENSSL_EXPORT void DES_ede2_cbc_encrypt(const uint8_t *in, uint8_t *out,
size_t len,
const DES_key_schedule *ks1,
@@ -109,7 +109,7 @@ OPENSSL_EXPORT void DES_ede2_cbc_encrypt(const uint8_t *in, uint8_t *out,
// Deprecated functions.
// DES_set_key_unchecked calls |DES_set_key|.
// DES_set_key_unchecked calls `DES_set_key`.
OPENSSL_EXPORT void DES_set_key_unchecked(const DES_cblock *key,
DES_key_schedule *schedule);
include/openssl/dh.h
+79 -79
View File
@@ -32,21 +32,21 @@ extern "C" {
// Allocation and destruction.
//
// A |DH| object represents a Diffie-Hellman key or group parameters. A given
// A `DH` object represents a Diffie-Hellman key or group parameters. A given
// object may be used concurrently on multiple threads by non-mutating
// functions, provided no other thread is concurrently calling a mutating
// function. Unless otherwise documented, functions which take a |const| pointer
// are non-mutating and functions which take a non-|const| pointer are mutating.
// function. Unless otherwise documented, functions which take a `const` pointer
// are non-mutating and functions which take a non-`const` pointer are mutating.
// DH_new returns a new, empty DH object or NULL on error.
OPENSSL_EXPORT DH *DH_new(void);
// DH_free decrements the reference count of |dh| and frees it if the reference
// DH_free decrements the reference count of `dh` and frees it if the reference
// count drops to zero.
OPENSSL_EXPORT void DH_free(DH *dh);
// DH_up_ref increments the reference count of |dh| and returns one. It does not
// mutate |dh| for thread-safety purposes and may be used concurrently.
// DH_up_ref increments the reference count of `dh` and returns one. It does not
// mutate `dh` for thread-safety purposes and may be used concurrently.
OPENSSL_EXPORT int DH_up_ref(DH *dh);
@@ -56,52 +56,52 @@ OPENSSL_EXPORT int DH_up_ref(DH *dh);
// modulus, in bits.
#define OPENSSL_DH_MAX_MODULUS_BITS 8192
// DH_bits returns the size of |dh|'s group modulus, in bits.
// DH_bits returns the size of `dh`'s group modulus, in bits.
OPENSSL_EXPORT unsigned DH_bits(const DH *dh);
// DH_size returns the number of bytes in the DH group's prime.
OPENSSL_EXPORT int DH_size(const DH *dh);
// DH_get0_pub_key returns |dh|'s public key.
// DH_get0_pub_key returns `dh`'s public key.
OPENSSL_EXPORT const BIGNUM *DH_get0_pub_key(const DH *dh);
// DH_get0_priv_key returns |dh|'s private key, or NULL if |dh| is a public key.
// DH_get0_priv_key returns `dh`'s private key, or NULL if `dh` is a public key.
OPENSSL_EXPORT const BIGNUM *DH_get0_priv_key(const DH *dh);
// DH_get0_p returns |dh|'s group modulus.
// DH_get0_p returns `dh`'s group modulus.
OPENSSL_EXPORT const BIGNUM *DH_get0_p(const DH *dh);
// DH_get0_q returns the size of |dh|'s subgroup, or NULL if it is unset.
// DH_get0_q returns the size of `dh`'s subgroup, or NULL if it is unset.
OPENSSL_EXPORT const BIGNUM *DH_get0_q(const DH *dh);
// DH_get0_g returns |dh|'s group generator.
// DH_get0_g returns `dh`'s group generator.
OPENSSL_EXPORT const BIGNUM *DH_get0_g(const DH *dh);
// DH_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dh|'s
// public and private key, respectively. If |dh| is a public key, the private
// DH_get0_key sets `*out_pub_key` and `*out_priv_key`, if non-NULL, to `dh`'s
// public and private key, respectively. If `dh` is a public key, the private
// key will be set to NULL.
OPENSSL_EXPORT void DH_get0_key(const DH *dh, const BIGNUM **out_pub_key,
const BIGNUM **out_priv_key);
// DH_set0_key sets |dh|'s public and private key to the specified values. If
// DH_set0_key sets `dh`'s public and private key to the specified values. If
// NULL, the field is left unchanged. On success, it takes ownership of each
// argument and returns one. Otherwise, it returns zero.
OPENSSL_EXPORT int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key);
// DH_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dh|'s p,
// DH_get0_pqg sets `*out_p`, `*out_q`, and `*out_g`, if non-NULL, to `dh`'s p,
// q, and g parameters, respectively.
OPENSSL_EXPORT void DH_get0_pqg(const DH *dh, const BIGNUM **out_p,
const BIGNUM **out_q, const BIGNUM **out_g);
// DH_set0_pqg sets |dh|'s p, q, and g parameters to the specified values. If
// DH_set0_pqg sets `dh`'s p, q, and g parameters to the specified values. If
// NULL, the field is left unchanged. On success, it takes ownership of each
// argument and returns one. Otherwise, it returns zero. |q| may be NULL, but
// |p| and |g| must either be specified or already configured on |dh|.
// argument and returns one. Otherwise, it returns zero. `q` may be NULL, but
// `p` and `g` must either be specified or already configured on `dh`.
OPENSSL_EXPORT int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);
// DH_set_length sets the number of bits to use for the secret exponent when
// calling |DH_generate_key| on |dh| and returns one. If unset,
// |DH_generate_key| will use the bit length of p.
// calling `DH_generate_key` on `dh` and returns one. If unset,
// `DH_generate_key` will use the bit length of p.
OPENSSL_EXPORT int DH_set_length(DH *dh, unsigned priv_length);
@@ -112,38 +112,38 @@ OPENSSL_EXPORT int DH_set_length(DH *dh, unsigned priv_length);
// of memory.
OPENSSL_EXPORT DH *DH_get_rfc7919_2048(void);
// BN_get_rfc3526_prime_1536 sets |*ret| to the 1536-bit MODP group from RFC
// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated
// BN_get_rfc3526_prime_1536 sets `*ret` to the 1536-bit MODP group from RFC
// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated
// and returned. It returns NULL on allocation failure. The generator for this
// group is 2.
OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *ret);
// BN_get_rfc3526_prime_2048 sets |*ret| to the 2048-bit MODP group from RFC
// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated
// BN_get_rfc3526_prime_2048 sets `*ret` to the 2048-bit MODP group from RFC
// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated
// and returned. It returns NULL on allocation failure. The generator for this
// group is 2.
OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *ret);
// BN_get_rfc3526_prime_3072 sets |*ret| to the 3072-bit MODP group from RFC
// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated
// BN_get_rfc3526_prime_3072 sets `*ret` to the 3072-bit MODP group from RFC
// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated
// and returned. It returns NULL on allocation failure. The generator for this
// group is 2.
OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *ret);
// BN_get_rfc3526_prime_4096 sets |*ret| to the 4096-bit MODP group from RFC
// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated
// BN_get_rfc3526_prime_4096 sets `*ret` to the 4096-bit MODP group from RFC
// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated
// and returned. It returns NULL on allocation failure. The generator for this
// group is 2.
OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *ret);
// BN_get_rfc3526_prime_6144 sets |*ret| to the 6144-bit MODP group from RFC
// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated
// BN_get_rfc3526_prime_6144 sets `*ret` to the 6144-bit MODP group from RFC
// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated
// and returned. It returns NULL on allocation failure. The generator for this
// group is 2.
OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *ret);
// BN_get_rfc3526_prime_8192 sets |*ret| to the 8192-bit MODP group from RFC
// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated
// BN_get_rfc3526_prime_8192 sets `*ret` to the 8192-bit MODP group from RFC
// 3526 and returns `ret`. If `ret` is NULL then a fresh `BIGNUM` is allocated
// and returned. It returns NULL on allocation failure. The generator for this
// group is 2.
OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *ret);
@@ -155,12 +155,12 @@ OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *ret);
#define DH_GENERATOR_5 5
// DH_generate_parameters_ex generates a suitable Diffie-Hellman group with a
// prime that is |prime_bits| long and stores it in |dh|. The generator of the
// group will be |generator|, which should be |DH_GENERATOR_2| unless there's a
// good reason to use a different value. The |cb| argument contains a callback
// prime that is `prime_bits` long and stores it in `dh`. The generator of the
// group will be `generator`, which should be `DH_GENERATOR_2` unless there's a
// good reason to use a different value. The `cb` argument contains a callback
// function that will be called during the generation. See the documentation in
// |bn.h| about this. In addition to the callback invocations from |BN|, |cb|
// will also be called with |event| equal to three when the generation is
// `bn.h` about this. In addition to the callback invocations from `BN`, `cb`
// will also be called with `event` equal to three when the generation is
// complete.
OPENSSL_EXPORT int DH_generate_parameters_ex(DH *dh, int prime_bits,
int generator, BN_GENCB *cb);
@@ -169,43 +169,43 @@ OPENSSL_EXPORT int DH_generate_parameters_ex(DH *dh, int prime_bits,
// Diffie-Hellman operations.
// DH_generate_key generates a new, random, private key and stores it in
// |dh|, if |dh| does not already have a private key. Otherwise, it updates
// |dh|'s public key to match the private key. It returns one on success and
// `dh`, if `dh` does not already have a private key. Otherwise, it updates
// `dh`'s public key to match the private key. It returns one on success and
// zero on error.
OPENSSL_EXPORT int DH_generate_key(DH *dh);
// DH_compute_key_padded calculates the shared key between |dh| and |peers_key|
// and writes it as a big-endian integer into |out|, padded up to |DH_size|
// bytes. It returns the number of bytes written, which is always |DH_size|, or
// a negative number on error. |out| must have |DH_size| bytes of space.
// DH_compute_key_padded calculates the shared key between `dh` and `peers_key`
// and writes it as a big-endian integer into `out`, padded up to `DH_size`
// bytes. It returns the number of bytes written, which is always `DH_size`, or
// a negative number on error. `out` must have `DH_size` bytes of space.
//
// WARNING: this differs from the usual BoringSSL return-value convention.
//
// Note this function differs from |DH_compute_key| in that it preserves leading
// Note this function differs from `DH_compute_key` in that it preserves leading
// zeros in the secret. This function is the preferred variant. It matches PKCS
// #3 and avoids some side channel attacks. However, the two functions are not
// drop-in replacements for each other. Using a different variant than the
// application expects will result in sporadic key mismatches.
//
// Callers that expect a fixed-width secret should use this function over
// |DH_compute_key|. Callers that use either function should migrate to a modern
// `DH_compute_key`. Callers that use either function should migrate to a modern
// primitive such as X25519 or ECDH with P-256 instead.
//
// This function does not mutate |dh| for thread-safety purposes and may be used
// This function does not mutate `dh` for thread-safety purposes and may be used
// concurrently.
OPENSSL_EXPORT int DH_compute_key_padded(uint8_t *out, const BIGNUM *peers_key,
DH *dh);
// DH_compute_key_hashed calculates the shared key between |dh| and |peers_key|
// and hashes it with the given |digest|. If the hash output is less than
// |max_out_len| bytes then it writes the hash output to |out| and sets
// |*out_len| to the number of bytes written. Otherwise it signals an error. It
// DH_compute_key_hashed calculates the shared key between `dh` and `peers_key`
// and hashes it with the given `digest`. If the hash output is less than
// `max_out_len` bytes then it writes the hash output to `out` and sets
// `*out_len` to the number of bytes written. Otherwise it signals an error. It
// returns one on success or zero on error.
//
// NOTE: this follows the usual BoringSSL return-value convention, but that's
// different from |DH_compute_key| and |DH_compute_key_padded|.
// different from `DH_compute_key` and `DH_compute_key_padded`.
//
// This function does not mutate |dh| for thread-safety purposes and may be used
// This function does not mutate `dh` for thread-safety purposes and may be used
// concurrently.
OPENSSL_EXPORT int DH_compute_key_hashed(DH *dh, uint8_t *out, size_t *out_len,
size_t max_out_len,
@@ -226,9 +226,9 @@ OPENSSL_EXPORT int DH_compute_key_hashed(DH *dh, uint8_t *out, size_t *out_len,
#define DH_NOT_SUITABLE_GENERATOR DH_CHECK_NOT_SUITABLE_GENERATOR
#define DH_UNABLE_TO_CHECK_GENERATOR DH_CHECK_UNABLE_TO_CHECK_GENERATOR
// DH_check checks the suitability of |dh| as a Diffie-Hellman group. and sets
// |DH_CHECK_*| flags in |*out_flags| if it finds any errors. It returns one if
// |*out_flags| was successfully set and zero on error.
// DH_check checks the suitability of `dh` as a Diffie-Hellman group. and sets
// `DH_CHECK_*` flags in `*out_flags` if it finds any errors. It returns one if
// `*out_flags` was successfully set and zero on error.
//
// Note: these checks may be quite computationally expensive.
OPENSSL_EXPORT int DH_check(const DH *dh, int *out_flags);
@@ -237,73 +237,73 @@ OPENSSL_EXPORT int DH_check(const DH *dh, int *out_flags);
#define DH_CHECK_PUBKEY_TOO_LARGE 0x2
#define DH_CHECK_PUBKEY_INVALID 0x4
// DH_check_pub_key checks the suitability of |pub_key| as a public key for the
// DH group in |dh| and sets |DH_CHECK_PUBKEY_*| flags in |*out_flags| if it
// finds any errors. It returns one if |*out_flags| was successfully set and
// DH_check_pub_key checks the suitability of `pub_key` as a public key for the
// DH group in `dh` and sets `DH_CHECK_PUBKEY_*` flags in `*out_flags` if it
// finds any errors. It returns one if `*out_flags` was successfully set and
// zero on error.
OPENSSL_EXPORT int DH_check_pub_key(const DH *dh, const BIGNUM *pub_key,
int *out_flags);
// DHparams_dup allocates a fresh |DH| and copies the parameters from |dh| into
// it. It returns the new |DH| or NULL on error.
// DHparams_dup allocates a fresh `DH` and copies the parameters from `dh` into
// it. It returns the new `DH` or NULL on error.
OPENSSL_EXPORT DH *DHparams_dup(const DH *dh);
// ASN.1 functions.
// DH_parse_parameters decodes a DER-encoded DHParameter structure (PKCS #3)
// from |cbs| and advances |cbs|. It returns a newly-allocated |DH| or NULL on
// from `cbs` and advances `cbs`. It returns a newly-allocated `DH` or NULL on
// error.
OPENSSL_EXPORT DH *DH_parse_parameters(CBS *cbs);
// DH_marshal_parameters marshals |dh| as a DER-encoded DHParameter structure
// (PKCS #3) and appends the result to |cbb|. It returns one on success and zero
// DH_marshal_parameters marshals `dh` as a DER-encoded DHParameter structure
// (PKCS #3) and appends the result to `cbb`. It returns one on success and zero
// on error.
OPENSSL_EXPORT int DH_marshal_parameters(CBB *cbb, const DH *dh);
// Deprecated functions.
// DH_generate_parameters behaves like |DH_generate_parameters_ex|, which is
// DH_generate_parameters behaves like `DH_generate_parameters_ex`, which is
// what you should use instead. It returns NULL on error, or a newly-allocated
// |DH| on success. This function is provided for compatibility only.
// `DH` on success. This function is provided for compatibility only.
OPENSSL_EXPORT DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *),
void *cb_arg);
// d2i_DHparams parses a DER-encoded DHParameter structure (PKCS #3) from |len|
// bytes at |*inp|, as in |d2i_SAMPLE|.
// d2i_DHparams parses a DER-encoded DHParameter structure (PKCS #3) from `len`
// bytes at `*inp`, as in `d2i_SAMPLE`.
//
// Use |DH_parse_parameters| instead.
// Use `DH_parse_parameters` instead.
OPENSSL_EXPORT DH *d2i_DHparams(DH **ret, const unsigned char **inp, long len);
// i2d_DHparams marshals |in| to a DER-encoded DHParameter structure (PKCS #3),
// as described in |i2d_SAMPLE|.
// i2d_DHparams marshals `in` to a DER-encoded DHParameter structure (PKCS #3),
// as described in `i2d_SAMPLE`.
//
// Use |DH_marshal_parameters| instead.
// Use `DH_marshal_parameters` instead.
OPENSSL_EXPORT int i2d_DHparams(const DH *in, unsigned char **outp);
// DH_compute_key behaves like |DH_compute_key_padded| but, contrary to PKCS #3,
// DH_compute_key behaves like `DH_compute_key_padded` but, contrary to PKCS #3,
// returns a variable-length shared key with leading zeros. It returns the
// number of bytes written, or a negative number on error. |out| must have
// |DH_size| bytes of space.
// number of bytes written, or a negative number on error. `out` must have
// `DH_size` bytes of space.
//
// WARNING: this differs from the usual BoringSSL return-value convention.
//
// Note this function's running time and memory access pattern leaks information
// about the shared secret. Particularly if |dh| is reused, this may result in
// about the shared secret. Particularly if `dh` is reused, this may result in
// side channel attacks such as https://raccoon-attack.com/.
//
// |DH_compute_key_padded| is the preferred variant and avoids the above
// `DH_compute_key_padded` is the preferred variant and avoids the above
// attacks. However, the two functions are not drop-in replacements for each
// other. Using a different variant than the application expects will result in
// sporadic key mismatches.
//
// Callers that expect a fixed-width secret should use |DH_compute_key_padded|
// Callers that expect a fixed-width secret should use `DH_compute_key_padded`
// instead. Callers that use either function should migrate to a modern
// primitive such as X25519 or ECDH with P-256 instead.
//
// This function does not mutate |dh| for thread-safety purposes and may be used
// This function does not mutate `dh` for thread-safety purposes and may be used
// concurrently.
OPENSSL_EXPORT int DH_compute_key(uint8_t *out, const BIGNUM *peers_key,
DH *dh);
include/openssl/digest.h
+70 -70
View File
@@ -31,7 +31,7 @@ extern "C" {
// Hash algorithms.
//
// The following functions return |EVP_MD| objects that implement the named hash
// The following functions return `EVP_MD` objects that implement the named hash
// function.
OPENSSL_EXPORT const EVP_MD *EVP_md4(void);
@@ -44,15 +44,15 @@ OPENSSL_EXPORT const EVP_MD *EVP_sha512(void);
OPENSSL_EXPORT const EVP_MD *EVP_sha512_256(void);
OPENSSL_EXPORT const EVP_MD *EVP_blake2b256(void);
// EVP_md5_sha1 is a TLS-specific |EVP_MD| which computes the concatenation of
// EVP_md5_sha1 is a TLS-specific `EVP_MD` which computes the concatenation of
// MD5 and SHA-1, as used in TLS 1.1 and below.
OPENSSL_EXPORT const EVP_MD *EVP_md5_sha1(void);
// EVP_get_digestbynid returns an |EVP_MD| for the given NID, or NULL if no
// EVP_get_digestbynid returns an `EVP_MD` for the given NID, or NULL if no
// such digest is known.
OPENSSL_EXPORT const EVP_MD *EVP_get_digestbynid(int nid);
// EVP_get_digestbyobj returns an |EVP_MD| for the given |ASN1_OBJECT|, or NULL
// EVP_get_digestbyobj returns an `EVP_MD` for the given `ASN1_OBJECT`, or NULL
// if no such digest is known.
OPENSSL_EXPORT const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *obj);
@@ -62,56 +62,56 @@ OPENSSL_EXPORT const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *obj);
// An EVP_MD_CTX represents the state of a specific digest operation in
// progress.
// EVP_MD_CTX_init initialises an, already allocated, |EVP_MD_CTX|. This is the
// EVP_MD_CTX_init initialises an, already allocated, `EVP_MD_CTX`. This is the
// same as setting the structure to zero.
OPENSSL_EXPORT void EVP_MD_CTX_init(EVP_MD_CTX *ctx);
// EVP_MD_CTX_new allocates and initialises a fresh |EVP_MD_CTX| and returns
// it, or NULL on allocation failure. The caller must use |EVP_MD_CTX_free| to
// EVP_MD_CTX_new allocates and initialises a fresh `EVP_MD_CTX` and returns
// it, or NULL on allocation failure. The caller must use `EVP_MD_CTX_free` to
// release the resulting object.
OPENSSL_EXPORT EVP_MD_CTX *EVP_MD_CTX_new(void);
// EVP_MD_CTX_cleanup frees any resources owned by |ctx| and resets it to a
// freshly initialised state. It does not free |ctx| itself. It returns one.
// EVP_MD_CTX_cleanup frees any resources owned by `ctx` and resets it to a
// freshly initialised state. It does not free `ctx` itself. It returns one.
OPENSSL_EXPORT int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
// EVP_MD_CTX_cleanse zeros the digest state in |ctx| and then performs the
// actions of |EVP_MD_CTX_cleanup|. Note that some |EVP_MD_CTX| objects contain
// more than just a digest (e.g. those resulting from |EVP_DigestSignInit|) but
// EVP_MD_CTX_cleanse zeros the digest state in `ctx` and then performs the
// actions of `EVP_MD_CTX_cleanup`. Note that some `EVP_MD_CTX` objects contain
// more than just a digest (e.g. those resulting from `EVP_DigestSignInit`) but
// this function does not zero out more than just the digest state even in that
// case.
OPENSSL_EXPORT void EVP_MD_CTX_cleanse(EVP_MD_CTX *ctx);
// EVP_MD_CTX_free calls |EVP_MD_CTX_cleanup| and then frees |ctx| itself.
// EVP_MD_CTX_free calls `EVP_MD_CTX_cleanup` and then frees `ctx` itself.
OPENSSL_EXPORT void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
// EVP_MD_CTX_copy_ex sets |out|, which must already be initialised, to be a
// copy of |in|. It returns one on success and zero on allocation failure.
// EVP_MD_CTX_copy_ex sets `out`, which must already be initialised, to be a
// copy of `in`. It returns one on success and zero on allocation failure.
OPENSSL_EXPORT int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);
// EVP_MD_CTX_move sets |out|, which must already be initialised, to the hash
// state in |in|. |in| is mutated and left in an empty state.
// EVP_MD_CTX_move sets `out`, which must already be initialised, to the hash
// state in `in`. `in` is mutated and left in an empty state.
OPENSSL_EXPORT void EVP_MD_CTX_move(EVP_MD_CTX *out, EVP_MD_CTX *in);
// EVP_MD_CTX_reset calls |EVP_MD_CTX_cleanup| followed by |EVP_MD_CTX_init|. It
// EVP_MD_CTX_reset calls `EVP_MD_CTX_cleanup` followed by `EVP_MD_CTX_init`. It
// returns one.
OPENSSL_EXPORT int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
// Digest operations.
// EVP_DigestInit_ex configures |ctx|, which must already have been
// initialised, for a fresh hashing operation using |type|. It returns one on
// EVP_DigestInit_ex configures `ctx`, which must already have been
// initialised, for a fresh hashing operation using `type`. It returns one on
// success and zero on allocation failure.
OPENSSL_EXPORT int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type,
ENGINE *engine);
// EVP_DigestInit acts like |EVP_DigestInit_ex| except that |ctx| is
// EVP_DigestInit acts like `EVP_DigestInit_ex` except that `ctx` is
// initialised before use.
OPENSSL_EXPORT int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
// EVP_DigestUpdate hashes |len| bytes from |data| into the hashing operation
// in |ctx|. It returns one.
// EVP_DigestUpdate hashes `len` bytes from `data` into the hashing operation
// in `ctx`. It returns one.
OPENSSL_EXPORT int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *data,
size_t len);
@@ -124,24 +124,24 @@ OPENSSL_EXPORT int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *data,
// bytes.
#define EVP_MAX_MD_BLOCK_SIZE 128 // SHA-512 is the longest so far.
// EVP_DigestFinal_ex finishes the digest in |ctx| and writes the output to
// |md_out|. |EVP_MD_CTX_size| bytes are written, which is at most
// |EVP_MAX_MD_SIZE|. If |out_size| is not NULL then |*out_size| is set to the
// EVP_DigestFinal_ex finishes the digest in `ctx` and writes the output to
// `md_out`. `EVP_MD_CTX_size` bytes are written, which is at most
// `EVP_MAX_MD_SIZE`. If `out_size` is not NULL then `*out_size` is set to the
// number of bytes written. It returns one. After this call, the hash cannot be
// updated or finished again until |EVP_DigestInit_ex| is called to start
// updated or finished again until `EVP_DigestInit_ex` is called to start
// another hashing operation.
OPENSSL_EXPORT int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, uint8_t *md_out,
unsigned int *out_size);
// EVP_DigestFinal acts like |EVP_DigestFinal_ex| except that
// |EVP_MD_CTX_cleanup| is called on |ctx| before returning.
// EVP_DigestFinal acts like `EVP_DigestFinal_ex` except that
// `EVP_MD_CTX_cleanup` is called on `ctx` before returning.
OPENSSL_EXPORT int EVP_DigestFinal(EVP_MD_CTX *ctx, uint8_t *md_out,
unsigned int *out_size);
// EVP_Digest performs a complete hashing operation in one call. It hashes |len|
// bytes from |data| and writes the digest to |md_out|. |EVP_MD_CTX_size| bytes
// are written, which is at most |EVP_MAX_MD_SIZE|. If |out_size| is not NULL
// then |*out_size| is set to the number of bytes written. It returns one on
// EVP_Digest performs a complete hashing operation in one call. It hashes `len`
// bytes from `data` and writes the digest to `md_out`. `EVP_MD_CTX_size` bytes
// are written, which is at most `EVP_MAX_MD_SIZE`. If `out_size` is not NULL
// then `*out_size` is set to the number of bytes written. It returns one on
// success and zero otherwise.
OPENSSL_EXPORT int EVP_Digest(const void *data, size_t len, uint8_t *md_out,
unsigned int *md_out_size, const EVP_MD *type,
@@ -153,17 +153,17 @@ OPENSSL_EXPORT int EVP_Digest(const void *data, size_t len, uint8_t *md_out,
// These functions allow code to learn details about an abstract hash
// function.
// EVP_MD_type returns a NID identifying |md|. (For example, |NID_sha256|.)
// EVP_MD_type returns a NID identifying `md`. (For example, `NID_sha256`.)
OPENSSL_EXPORT int EVP_MD_type(const EVP_MD *md);
// EVP_MD_flags returns the flags for |md|, which is a set of |EVP_MD_FLAG_*|
// EVP_MD_flags returns the flags for `md`, which is a set of `EVP_MD_FLAG_*`
// values, ORed together.
OPENSSL_EXPORT uint32_t EVP_MD_flags(const EVP_MD *md);
// EVP_MD_size returns the digest size of |md|, in bytes.
// EVP_MD_size returns the digest size of `md`, in bytes.
OPENSSL_EXPORT size_t EVP_MD_size(const EVP_MD *md);
// EVP_MD_block_size returns the native block-size of |md|, in bytes.
// EVP_MD_block_size returns the native block-size of `md`, in bytes.
OPENSSL_EXPORT size_t EVP_MD_block_size(const EVP_MD *md);
// EVP_MD_FLAG_DIGALGID_ABSENT indicates that the parameter type in an X.509
@@ -173,7 +173,7 @@ OPENSSL_EXPORT size_t EVP_MD_block_size(const EVP_MD *md);
// EVP_MD_FLAG_XOF indicates that the digest is an extensible-output function
// (XOF). This flag is defined for compatibility and will never be set in any
// |EVP_MD| in BoringSSL.
// `EVP_MD` in BoringSSL.
#define EVP_MD_FLAG_XOF 4
@@ -184,26 +184,26 @@ OPENSSL_EXPORT size_t EVP_MD_block_size(const EVP_MD *md);
OPENSSL_EXPORT const EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx);
// EVP_MD_CTX_md returns the underlying digest function, or NULL if one has not
// been set. (This is the same as |EVP_MD_CTX_get0_md| but OpenSSL has
// been set. (This is the same as `EVP_MD_CTX_get0_md` but OpenSSL has
// deprecated this spelling.)
OPENSSL_EXPORT const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
// EVP_MD_CTX_size returns the digest size of |ctx|, in bytes. It
// will crash if a digest hasn't been set on |ctx|.
// EVP_MD_CTX_size returns the digest size of `ctx`, in bytes. It
// will crash if a digest hasn't been set on `ctx`.
OPENSSL_EXPORT size_t EVP_MD_CTX_size(const EVP_MD_CTX *ctx);
// EVP_MD_CTX_block_size returns the block size of the digest function used by
// |ctx|, in bytes. It will crash if a digest hasn't been set on |ctx|.
// `ctx`, in bytes. It will crash if a digest hasn't been set on `ctx`.
OPENSSL_EXPORT size_t EVP_MD_CTX_block_size(const EVP_MD_CTX *ctx);
// EVP_MD_CTX_type returns a NID describing the digest function used by |ctx|.
// (For example, |NID_sha256|.) It will crash if a digest hasn't been set on
// |ctx|.
// EVP_MD_CTX_type returns a NID describing the digest function used by `ctx`.
// (For example, `NID_sha256`.) It will crash if a digest hasn't been set on
// `ctx`.
OPENSSL_EXPORT int EVP_MD_CTX_type(const EVP_MD_CTX *ctx);
// EVP_MD_CTX_pkey_ctx returns the |EVP_PKEY_CTX| used to configure additional
// parameters on |ctx| if |ctx| is used for a sign or verify operation with
// |EVP_DigestSignInit| or |EVP_DigestVerifyInit|. It returns NULL otherwise.
// EVP_MD_CTX_pkey_ctx returns the `EVP_PKEY_CTX` used to configure additional
// parameters on `ctx` if `ctx` is used for a sign or verify operation with
// `EVP_DigestSignInit` or `EVP_DigestVerifyInit`. It returns NULL otherwise.
OPENSSL_EXPORT EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx);
@@ -214,19 +214,19 @@ OPENSSL_EXPORT EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx);
// EVP_parse_digest_algorithm parses an AlgorithmIdentifier structure containing
// a hash function OID (for example, 2.16.840.1.101.3.4.2.1 is SHA-256) and
// advances |cbs|. The parameters field may either be omitted or a NULL. It
// advances `cbs`. The parameters field may either be omitted or a NULL. It
// returns the digest function or NULL on error.
OPENSSL_EXPORT const EVP_MD *EVP_parse_digest_algorithm(CBS *cbs);
// EVP_parse_digest_algorithm_nid behaves like |EVP_parse_digest_algorithm|
// except it returns |NID_undef| on error and some other value on success. This
// EVP_parse_digest_algorithm_nid behaves like `EVP_parse_digest_algorithm`
// except it returns `NID_undef` on error and some other value on success. This
// may be used to avoid depending on every digest algorithm in the library.
OPENSSL_EXPORT int EVP_parse_digest_algorithm_nid(CBS *cbs);
// EVP_marshal_digest_algorithm marshals |md| as an AlgorithmIdentifier
// structure and appends the result to |cbb|. It returns one on success and zero
// EVP_marshal_digest_algorithm marshals `md` as an AlgorithmIdentifier
// structure and appends the result to `cbb`. It returns one on success and zero
// on error. It sets the parameters field to NULL. Use
// |EVP_marshal_digest_algorithm_no_params| to omit the parameters instead.
// `EVP_marshal_digest_algorithm_no_params` to omit the parameters instead.
//
// In general, the parameters should be omitted for digest algorithms, but the
// following specifications require a NULL parameter instead.
@@ -241,23 +241,23 @@ OPENSSL_EXPORT int EVP_parse_digest_algorithm_nid(CBS *cbs);
OPENSSL_EXPORT int EVP_marshal_digest_algorithm(CBB *cbb, const EVP_MD *md);
// EVP_marshal_digest_algorithm_no_params behaves like
// |EVP_marshal_digest_algorithm| but omits the parameters field.
// `EVP_marshal_digest_algorithm` but omits the parameters field.
OPENSSL_EXPORT int EVP_marshal_digest_algorithm_no_params(CBB *cbb,
const EVP_MD *md);
// Deprecated functions.
// EVP_MD_CTX_copy sets |out|, which must /not/ be initialised, to be a copy of
// |in|. It returns one on success and zero on error.
// EVP_MD_CTX_copy sets `out`, which must /not/ be initialised, to be a copy of
// `in`. It returns one on success and zero on error.
OPENSSL_EXPORT int EVP_MD_CTX_copy(EVP_MD_CTX *out, const EVP_MD_CTX *in);
// EVP_add_digest does nothing and returns one. It exists only for
// compatibility with OpenSSL.
OPENSSL_EXPORT int EVP_add_digest(const EVP_MD *digest);
// EVP_get_digestbyname returns an |EVP_MD| given a human readable name in
// |name|, or NULL if the name is unknown.
// EVP_get_digestbyname returns an `EVP_MD` given a human readable name in
// `name`, or NULL if the name is unknown.
OPENSSL_EXPORT const EVP_MD *EVP_get_digestbyname(const char *name);
// EVP_dss1 returns the value of EVP_sha1(). This was provided by OpenSSL to
@@ -266,10 +266,10 @@ OPENSSL_EXPORT const EVP_MD *EVP_get_digestbyname(const char *name);
// interface will always fail.
OPENSSL_EXPORT const EVP_MD *EVP_dss1(void);
// EVP_MD_CTX_create calls |EVP_MD_CTX_new|.
// EVP_MD_CTX_create calls `EVP_MD_CTX_new`.
OPENSSL_EXPORT EVP_MD_CTX *EVP_MD_CTX_create(void);
// EVP_MD_CTX_destroy calls |EVP_MD_CTX_free|.
// EVP_MD_CTX_destroy calls `EVP_MD_CTX_free`.
OPENSSL_EXPORT void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
// EVP_DigestFinalXOF returns zero and adds an error to the error queue.
@@ -277,7 +277,7 @@ OPENSSL_EXPORT void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
OPENSSL_EXPORT int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, uint8_t *out,
size_t len);
// EVP_MD_meth_get_flags calls |EVP_MD_flags|.
// EVP_MD_meth_get_flags calls `EVP_MD_flags`.
OPENSSL_EXPORT uint32_t EVP_MD_meth_get_flags(const EVP_MD *md);
// EVP_MD_CTX_set_flags does nothing.
@@ -289,23 +289,23 @@ OPENSSL_EXPORT void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);
// their needs). Thus this exists only to allow code to compile.
#define EVP_MD_CTX_FLAG_NON_FIPS_ALLOW 0
// EVP_MD_nid calls |EVP_MD_type|.
// EVP_MD_nid calls `EVP_MD_type`.
OPENSSL_EXPORT int EVP_MD_nid(const EVP_MD *md);
// EVP_MD_fetch behaves like |EVP_get_digestbyname|. |libctx| and |propq| are
// ignored. Although it returns a non-const pointer, |EVP_MD|s in BoringSSL are
// EVP_MD_fetch behaves like `EVP_get_digestbyname`. `libctx` and `propq` are
// ignored. Although it returns a non-const pointer, `EVP_MD`s in BoringSSL are
// static and do not need to be freed.
OPENSSL_EXPORT EVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *libctx, const char *name,
const char *propq);
// EVP_MD_up_ref returns one. |EVP_MD|s in BoringSSL are static.
// EVP_MD_up_ref returns one. `EVP_MD`s in BoringSSL are static.
OPENSSL_EXPORT int EVP_MD_up_ref(EVP_MD *md);
// EVP_MD_free does nothing. |EVP_MD|s in BoringSSL are static.
// EVP_MD_free does nothing. `EVP_MD`s in BoringSSL are static.
OPENSSL_EXPORT void EVP_MD_free(EVP_MD *md);
// EVP_Q_digest behaves like |EVP_Digest| but specifies the digest by a string
// |name|. |libctx| and |propq| are ignored.
// EVP_Q_digest behaves like `EVP_Digest` but specifies the digest by a string
// `name`. `libctx` and `propq` are ignored.
OPENSSL_EXPORT int EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name,
const char *propq, const void *in,
size_t in_len, uint8_t *out, size_t *out_len);
@@ -337,7 +337,7 @@ struct env_md_ctx_st {
EVP_PKEY_CTX *pctx;
// pctx_ops, if not NULL, points to a vtable that contains functions to
// manipulate |pctx|.
// manipulate `pctx`.
const struct evp_md_pctx_ops *pctx_ops;
} /* EVP_MD_CTX */;
include/openssl/dsa.h
+100 -100
View File
@@ -34,21 +34,21 @@ extern "C" {
// Allocation and destruction.
//
// A |DSA| object represents a DSA key or group parameters. A given object may
// A `DSA` object represents a DSA key or group parameters. A given object may
// be used concurrently on multiple threads by non-mutating functions, provided
// no other thread is concurrently calling a mutating function. Unless otherwise
// documented, functions which take a |const| pointer are non-mutating and
// functions which take a non-|const| pointer are mutating.
// documented, functions which take a `const` pointer are non-mutating and
// functions which take a non-`const` pointer are mutating.
// DSA_new returns a new, empty DSA object or NULL on error.
OPENSSL_EXPORT DSA *DSA_new(void);
// DSA_free decrements the reference count of |dsa| and frees it if the
// DSA_free decrements the reference count of `dsa` and frees it if the
// reference count drops to zero.
OPENSSL_EXPORT void DSA_free(DSA *dsa);
// DSA_up_ref increments the reference count of |dsa| and returns one. It does
// not mutate |dsa| for thread-safety purposes and may be used concurrently.
// DSA_up_ref increments the reference count of `dsa` and returns one. It does
// not mutate `dsa` for thread-safety purposes and may be used concurrently.
OPENSSL_EXPORT int DSA_up_ref(DSA *dsa);
@@ -58,49 +58,49 @@ OPENSSL_EXPORT int DSA_up_ref(DSA *dsa);
// bits.
#define OPENSSL_DSA_MAX_MODULUS_BITS 8192
// DSA_bits returns the size of |dsa|'s group modulus, in bits.
// DSA_bits returns the size of `dsa`'s group modulus, in bits.
OPENSSL_EXPORT unsigned DSA_bits(const DSA *dsa);
// DSA_get0_pub_key returns |dsa|'s public key.
// DSA_get0_pub_key returns `dsa`'s public key.
OPENSSL_EXPORT const BIGNUM *DSA_get0_pub_key(const DSA *dsa);
// DSA_get0_priv_key returns |dsa|'s private key, or NULL if |dsa| is a public
// DSA_get0_priv_key returns `dsa`'s private key, or NULL if `dsa` is a public
// key.
OPENSSL_EXPORT const BIGNUM *DSA_get0_priv_key(const DSA *dsa);
// DSA_get0_p returns |dsa|'s group modulus.
// DSA_get0_p returns `dsa`'s group modulus.
OPENSSL_EXPORT const BIGNUM *DSA_get0_p(const DSA *dsa);
// DSA_get0_q returns the size of |dsa|'s subgroup.
// DSA_get0_q returns the size of `dsa`'s subgroup.
OPENSSL_EXPORT const BIGNUM *DSA_get0_q(const DSA *dsa);
// DSA_get0_g returns |dsa|'s group generator.
// DSA_get0_g returns `dsa`'s group generator.
OPENSSL_EXPORT const BIGNUM *DSA_get0_g(const DSA *dsa);
// DSA_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dsa|'s
// public and private key, respectively. If |dsa| is a public key, the private
// DSA_get0_key sets `*out_pub_key` and `*out_priv_key`, if non-NULL, to `dsa`'s
// public and private key, respectively. If `dsa` is a public key, the private
// key will be set to NULL.
OPENSSL_EXPORT void DSA_get0_key(const DSA *dsa, const BIGNUM **out_pub_key,
const BIGNUM **out_priv_key);
// DSA_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dsa|'s
// DSA_get0_pqg sets `*out_p`, `*out_q`, and `*out_g`, if non-NULL, to `dsa`'s
// p, q, and g parameters, respectively.
OPENSSL_EXPORT void DSA_get0_pqg(const DSA *dsa, const BIGNUM **out_p,
const BIGNUM **out_q, const BIGNUM **out_g);
// DSA_set0_key sets |dsa|'s public and private key to |pub_key| and |priv_key|,
// DSA_set0_key sets `dsa`'s public and private key to `pub_key` and `priv_key`,
// respectively, if non-NULL. On success, it takes ownership of each argument
// and returns one. Otherwise, it returns zero.
//
// |priv_key| may be NULL, but |pub_key| must either be non-NULL or already
// configured on |dsa|.
// `priv_key` may be NULL, but `pub_key` must either be non-NULL or already
// configured on `dsa`.
OPENSSL_EXPORT int DSA_set0_key(DSA *dsa, BIGNUM *pub_key, BIGNUM *priv_key);
// DSA_set0_pqg sets |dsa|'s parameters to |p|, |q|, and |g|, if non-NULL, and
// DSA_set0_pqg sets `dsa`'s parameters to `p`, `q`, and `g`, if non-NULL, and
// takes ownership of them. On success, it takes ownership of each argument and
// returns one. Otherwise, it returns zero.
//
// Each argument must either be non-NULL or already configured on |dsa|.
// Each argument must either be non-NULL or already configured on `dsa`.
OPENSSL_EXPORT int DSA_set0_pqg(DSA *dsa, BIGNUM *p, BIGNUM *q, BIGNUM *g);
@@ -110,17 +110,17 @@ OPENSSL_EXPORT int DSA_set0_pqg(DSA *dsa, BIGNUM *p, BIGNUM *q, BIGNUM *g);
// the procedure given in FIPS 186-4, appendix A.
// (http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf)
//
// The larger prime will have a length of |bits| (e.g. 2048). The |seed| value
// The larger prime will have a length of `bits` (e.g. 2048). The `seed` value
// allows others to generate and verify the same parameters and should be
// random input which is kept for reference. If |out_counter| or |out_h| are
// random input which is kept for reference. If `out_counter` or `out_h` are
// not NULL then the counter and h value used in the generation are written to
// them.
//
// The |cb| argument is passed to |BN_generate_prime_ex| and is thus called
// The `cb` argument is passed to `BN_generate_prime_ex` and is thus called
// during the generation process in order to indicate progress. See the
// comments for that function for details. In addition to the calls made by
// |BN_generate_prime_ex|, |DSA_generate_parameters_ex| will call it with
// |event| equal to 2 and 3 at different stages of the process.
// `BN_generate_prime_ex`, `DSA_generate_parameters_ex` will call it with
// `event` equal to 2 and 3 at different stages of the process.
//
// It returns one on success and zero otherwise.
OPENSSL_EXPORT int DSA_generate_parameters_ex(DSA *dsa, unsigned bits,
@@ -129,14 +129,14 @@ OPENSSL_EXPORT int DSA_generate_parameters_ex(DSA *dsa, unsigned bits,
unsigned long *out_h,
BN_GENCB *cb);
// DSAparams_dup returns a freshly allocated |DSA| that contains a copy of the
// parameters from |dsa|. It returns NULL on error.
// DSAparams_dup returns a freshly allocated `DSA` that contains a copy of the
// parameters from `dsa`. It returns NULL on error.
OPENSSL_EXPORT DSA *DSAparams_dup(const DSA *dsa);
// Key generation.
// DSA_generate_key generates a public/private key pair in |dsa|, which must
// DSA_generate_key generates a public/private key pair in `dsa`, which must
// already have parameters setup. It returns one on success and zero on
// error.
OPENSSL_EXPORT int DSA_generate_key(DSA *dsa);
@@ -144,49 +144,49 @@ OPENSSL_EXPORT int DSA_generate_key(DSA *dsa);
// Signatures.
// DSA_SIG_st (aka |DSA_SIG|) contains a DSA signature as a pair of integers.
// DSA_SIG_st (aka `DSA_SIG`) contains a DSA signature as a pair of integers.
struct DSA_SIG_st {
BIGNUM *r, *s;
};
// DSA_SIG_new returns a freshly allocated, DIG_SIG structure or NULL on error.
// Both |r| and |s| in the signature will be NULL.
// Both `r` and `s` in the signature will be NULL.
OPENSSL_EXPORT DSA_SIG *DSA_SIG_new(void);
// DSA_SIG_free frees the contents of |sig| and then frees |sig| itself.
// DSA_SIG_free frees the contents of `sig` and then frees `sig` itself.
OPENSSL_EXPORT void DSA_SIG_free(DSA_SIG *sig);
// DSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two components
// of |sig|.
// DSA_SIG_get0 sets `*out_r` and `*out_s`, if non-NULL, to the two components
// of `sig`.
OPENSSL_EXPORT void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **out_r,
const BIGNUM **out_s);
// DSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may be
// DSA_SIG_set0 sets `sig`'s components to `r` and `s`, neither of which may be
// NULL. On success, it takes ownership of each argument and returns one.
// Otherwise, it returns zero.
OPENSSL_EXPORT int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s);
// DSA_do_sign returns a signature of the hash in |digest| by the key in |dsa|
// DSA_do_sign returns a signature of the hash in `digest` by the key in `dsa`
// and returns an allocated, DSA_SIG structure, or NULL on error.
OPENSSL_EXPORT DSA_SIG *DSA_do_sign(const uint8_t *digest, size_t digest_len,
const DSA *dsa);
// DSA_do_verify verifies that |sig| is a valid signature, by the public key in
// |dsa|, of the hash in |digest|. It returns one if so, zero if invalid and -1
// DSA_do_verify verifies that `sig` is a valid signature, by the public key in
// `dsa`, of the hash in `digest`. It returns one if so, zero if invalid and -1
// on error.
//
// WARNING: do not use. This function returns -1 for error, 0 for invalid and 1
// for valid. However, this is dangerously different to the usual OpenSSL
// convention and could be a disaster if a user did |if (DSA_do_verify(...))|.
// Because of this, |DSA_check_signature| is a safer version of this.
// convention and could be a disaster if a user did `if (DSA_do_verify(...))`.
// Because of this, `DSA_check_signature` is a safer version of this.
//
// TODO(fork): deprecate.
OPENSSL_EXPORT int DSA_do_verify(const uint8_t *digest, size_t digest_len,
const DSA_SIG *sig, const DSA *dsa);
// DSA_do_check_signature sets |*out_valid| to zero. Then it verifies that |sig|
// is a valid signature, by the public key in |dsa| of the hash in |digest|
// and, if so, it sets |*out_valid| to one.
// DSA_do_check_signature sets `*out_valid` to zero. Then it verifies that `sig`
// is a valid signature, by the public key in `dsa` of the hash in `digest`
// and, if so, it sets `*out_valid` to one.
//
// It returns one if it was able to verify the signature as valid or invalid,
// and zero on error.
@@ -198,38 +198,38 @@ OPENSSL_EXPORT int DSA_do_check_signature(int *out_valid, const uint8_t *digest,
// ASN.1 signatures.
//
// These functions also perform DSA signature operations, but deal with ASN.1
// encoded signatures as opposed to raw |BIGNUM|s. If you don't know what
// encoded signatures as opposed to raw `BIGNUM`s. If you don't know what
// encoding a DSA signature is in, it's probably ASN.1.
// DSA_sign signs |digest| with the key in |dsa| and writes the resulting
// signature, in ASN.1 form, to |out_sig| and the length of the signature to
// |*out_siglen|. There must be, at least, |DSA_size(dsa)| bytes of space in
// |out_sig|. It returns one on success and zero otherwise.
// DSA_sign signs `digest` with the key in `dsa` and writes the resulting
// signature, in ASN.1 form, to `out_sig` and the length of the signature to
// `*out_siglen`. There must be, at least, `DSA_size(dsa)` bytes of space in
// `out_sig`. It returns one on success and zero otherwise.
//
// (The |type| argument is ignored.)
// (The `type` argument is ignored.)
OPENSSL_EXPORT int DSA_sign(int type, const uint8_t *digest, size_t digest_len,
uint8_t *out_sig, unsigned int *out_siglen,
const DSA *dsa);
// DSA_verify verifies that |sig| is a valid, ASN.1 signature, by the public
// key in |dsa|, of the hash in |digest|. It returns one if so, zero if invalid
// DSA_verify verifies that `sig` is a valid, ASN.1 signature, by the public
// key in `dsa`, of the hash in `digest`. It returns one if so, zero if invalid
// and -1 on error.
//
// (The |type| argument is ignored.)
// (The `type` argument is ignored.)
//
// WARNING: do not use. This function returns -1 for error, 0 for invalid and 1
// for valid. However, this is dangerously different to the usual OpenSSL
// convention and could be a disaster if a user did |if (DSA_do_verify(...))|.
// Because of this, |DSA_check_signature| is a safer version of this.
// convention and could be a disaster if a user did `if (DSA_do_verify(...))`.
// Because of this, `DSA_check_signature` is a safer version of this.
//
// TODO(fork): deprecate.
OPENSSL_EXPORT int DSA_verify(int type, const uint8_t *digest,
size_t digest_len, const uint8_t *sig,
size_t sig_len, const DSA *dsa);
// DSA_check_signature sets |*out_valid| to zero. Then it verifies that |sig|
// is a valid, ASN.1 signature, by the public key in |dsa|, of the hash in
// |digest|. If so, it sets |*out_valid| to one.
// DSA_check_signature sets `*out_valid` to zero. Then it verifies that `sig`
// is a valid, ASN.1 signature, by the public key in `dsa`, of the hash in
// `digest`. If so, it sets `*out_valid` to one.
//
// It returns one if it was able to verify the signature as valid or invalid,
// and zero on error.
@@ -238,60 +238,60 @@ OPENSSL_EXPORT int DSA_check_signature(int *out_valid, const uint8_t *digest,
size_t sig_len, const DSA *dsa);
// DSA_size returns the size, in bytes, of an ASN.1 encoded, DSA signature
// generated by |dsa|. Parameters must already have been setup in |dsa|.
// generated by `dsa`. Parameters must already have been setup in `dsa`.
OPENSSL_EXPORT int DSA_size(const DSA *dsa);
// ASN.1 encoding.
// DSA_SIG_parse parses a DER-encoded DSA-Sig-Value structure from |cbs| and
// advances |cbs|. It returns a newly-allocated |DSA_SIG| or NULL on error.
// DSA_SIG_parse parses a DER-encoded DSA-Sig-Value structure from `cbs` and
// advances `cbs`. It returns a newly-allocated `DSA_SIG` or NULL on error.
OPENSSL_EXPORT DSA_SIG *DSA_SIG_parse(CBS *cbs);
// DSA_SIG_marshal marshals |sig| as a DER-encoded DSA-Sig-Value and appends the
// result to |cbb|. It returns one on success and zero on error.
// DSA_SIG_marshal marshals `sig` as a DER-encoded DSA-Sig-Value and appends the
// result to `cbb`. It returns one on success and zero on error.
OPENSSL_EXPORT int DSA_SIG_marshal(CBB *cbb, const DSA_SIG *sig);
// DSA_parse_public_key parses a DER-encoded DSA public key from |cbs| and
// advances |cbs|. It returns a newly-allocated |DSA| or NULL on error.
// DSA_parse_public_key parses a DER-encoded DSA public key from `cbs` and
// advances `cbs`. It returns a newly-allocated `DSA` or NULL on error.
OPENSSL_EXPORT DSA *DSA_parse_public_key(CBS *cbs);
// DSA_marshal_public_key marshals |dsa| as a DER-encoded DSA public key and
// appends the result to |cbb|. It returns one on success and zero on
// DSA_marshal_public_key marshals `dsa` as a DER-encoded DSA public key and
// appends the result to `cbb`. It returns one on success and zero on
// failure.
OPENSSL_EXPORT int DSA_marshal_public_key(CBB *cbb, const DSA *dsa);
// DSA_parse_private_key parses a DER-encoded DSA private key from |cbs| and
// advances |cbs|. It returns a newly-allocated |DSA| or NULL on error.
// DSA_parse_private_key parses a DER-encoded DSA private key from `cbs` and
// advances `cbs`. It returns a newly-allocated `DSA` or NULL on error.
OPENSSL_EXPORT DSA *DSA_parse_private_key(CBS *cbs);
// DSA_marshal_private_key marshals |dsa| as a DER-encoded DSA private key and
// appends the result to |cbb|. It returns one on success and zero on
// DSA_marshal_private_key marshals `dsa` as a DER-encoded DSA private key and
// appends the result to `cbb`. It returns one on success and zero on
// failure.
OPENSSL_EXPORT int DSA_marshal_private_key(CBB *cbb, const DSA *dsa);
// DSA_parse_parameters parses a DER-encoded Dss-Parms structure (RFC 3279)
// from |cbs| and advances |cbs|. It returns a newly-allocated |DSA| or NULL on
// from `cbs` and advances `cbs`. It returns a newly-allocated `DSA` or NULL on
// error.
OPENSSL_EXPORT DSA *DSA_parse_parameters(CBS *cbs);
// DSA_marshal_parameters marshals |dsa| as a DER-encoded Dss-Parms structure
// (RFC 3279) and appends the result to |cbb|. It returns one on success and
// DSA_marshal_parameters marshals `dsa` as a DER-encoded Dss-Parms structure
// (RFC 3279) and appends the result to `cbb`. It returns one on success and
// zero on failure.
OPENSSL_EXPORT int DSA_marshal_parameters(CBB *cbb, const DSA *dsa);
// Conversion.
// DSA_dup_DH returns a |DH| constructed from the parameters of |dsa|. This is
// DSA_dup_DH returns a `DH` constructed from the parameters of `dsa`. This is
// sometimes needed when Diffie-Hellman parameters are stored in the form of
// DSA parameters. It returns an allocated |DH| on success or NULL on error.
// DSA parameters. It returns an allocated `DH` on success or NULL on error.
OPENSSL_EXPORT DH *DSA_dup_DH(const DSA *dsa);
// ex_data functions.
//
// See |ex_data.h| for details.
// See `ex_data.h` for details.
OPENSSL_EXPORT int DSA_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_unused *unused,
@@ -303,57 +303,57 @@ OPENSSL_EXPORT void *DSA_get_ex_data(const DSA *dsa, int idx);
// Deprecated functions.
// d2i_DSA_SIG parses a DER-encoded DSA-Sig-Value structure from |len| bytes at
// |*inp|, as described in |d2i_SAMPLE|.
// d2i_DSA_SIG parses a DER-encoded DSA-Sig-Value structure from `len` bytes at
// `*inp`, as described in `d2i_SAMPLE`.
//
// Use |DSA_SIG_parse| instead.
// Use `DSA_SIG_parse` instead.
OPENSSL_EXPORT DSA_SIG *d2i_DSA_SIG(DSA_SIG **out_sig, const uint8_t **inp,
long len);
// i2d_DSA_SIG marshals |in| to a DER-encoded DSA-Sig-Value structure, as
// described in |i2d_SAMPLE|.
// i2d_DSA_SIG marshals `in` to a DER-encoded DSA-Sig-Value structure, as
// described in `i2d_SAMPLE`.
//
// Use |DSA_SIG_marshal| instead.
// Use `DSA_SIG_marshal` instead.
OPENSSL_EXPORT int i2d_DSA_SIG(const DSA_SIG *in, uint8_t **outp);
// d2i_DSAPublicKey parses a DER-encoded DSA public key from |len| bytes at
// |*inp|, as described in |d2i_SAMPLE|.
// d2i_DSAPublicKey parses a DER-encoded DSA public key from `len` bytes at
// `*inp`, as described in `d2i_SAMPLE`.
//
// Use |DSA_parse_public_key| instead.
// Use `DSA_parse_public_key` instead.
OPENSSL_EXPORT DSA *d2i_DSAPublicKey(DSA **out, const uint8_t **inp, long len);
// i2d_DSAPublicKey marshals |in| as a DER-encoded DSA public key, as described
// in |i2d_SAMPLE|.
// i2d_DSAPublicKey marshals `in` as a DER-encoded DSA public key, as described
// in `i2d_SAMPLE`.
//
// Use |DSA_marshal_public_key| instead.
// Use `DSA_marshal_public_key` instead.
OPENSSL_EXPORT int i2d_DSAPublicKey(const DSA *in, uint8_t **outp);
// d2i_DSAPrivateKey parses a DER-encoded DSA private key from |len| bytes at
// |*inp|, as described in |d2i_SAMPLE|.
// d2i_DSAPrivateKey parses a DER-encoded DSA private key from `len` bytes at
// `*inp`, as described in `d2i_SAMPLE`.
//
// Use |DSA_parse_private_key| instead.
// Use `DSA_parse_private_key` instead.
OPENSSL_EXPORT DSA *d2i_DSAPrivateKey(DSA **out, const uint8_t **inp, long len);
// i2d_DSAPrivateKey marshals |in| as a DER-encoded DSA private key, as
// described in |i2d_SAMPLE|.
// i2d_DSAPrivateKey marshals `in` as a DER-encoded DSA private key, as
// described in `i2d_SAMPLE`.
//
// Use |DSA_marshal_private_key| instead.
// Use `DSA_marshal_private_key` instead.
OPENSSL_EXPORT int i2d_DSAPrivateKey(const DSA *in, uint8_t **outp);
// d2i_DSAparams parses a DER-encoded Dss-Parms structure (RFC 3279) from |len|
// bytes at |*inp|, as described in |d2i_SAMPLE|.
// d2i_DSAparams parses a DER-encoded Dss-Parms structure (RFC 3279) from `len`
// bytes at `*inp`, as described in `d2i_SAMPLE`.
//
// Use |DSA_parse_parameters| instead.
// Use `DSA_parse_parameters` instead.
OPENSSL_EXPORT DSA *d2i_DSAparams(DSA **out, const uint8_t **inp, long len);
// i2d_DSAparams marshals |in|'s parameters as a DER-encoded Dss-Parms structure
// (RFC 3279), as described in |i2d_SAMPLE|.
// i2d_DSAparams marshals `in`'s parameters as a DER-encoded Dss-Parms structure
// (RFC 3279), as described in `i2d_SAMPLE`.
//
// Use |DSA_marshal_parameters| instead.
// Use `DSA_marshal_parameters` instead.
OPENSSL_EXPORT int i2d_DSAparams(const DSA *in, uint8_t **outp);
// DSA_generate_parameters is a deprecated version of
// |DSA_generate_parameters_ex| that creates and returns a |DSA*|. Don't use
// `DSA_generate_parameters_ex` that creates and returns a `DSA*`. Don't use
// it.
OPENSSL_EXPORT DSA *DSA_generate_parameters(int bits, unsigned char *seed,
int seed_len, int *counter_ret,
include/openssl/ec.h
+120 -120
View File
@@ -49,143 +49,143 @@ typedef enum {
// Elliptic curve groups.
//
// Elliptic curve groups are represented by |EC_GROUP| objects. Unlike OpenSSL,
// if limited to the APIs in this section, callers may treat |EC_GROUP|s as
// Elliptic curve groups are represented by `EC_GROUP` objects. Unlike OpenSSL,
// if limited to the APIs in this section, callers may treat `EC_GROUP`s as
// static, immutable objects which do not need to be copied or released. In
// BoringSSL, only custom |EC_GROUP|s created by |EC_GROUP_new_curve_GFp|
// BoringSSL, only custom `EC_GROUP`s created by `EC_GROUP_new_curve_GFp`
// (deprecated) are dynamic.
//
// Callers may cast away |const| and use |EC_GROUP_dup| and |EC_GROUP_free| with
// Callers may cast away `const` and use `EC_GROUP_dup` and `EC_GROUP_free` with
// static groups, for compatibility with OpenSSL or dynamic groups, but it is
// otherwise unnecessary.
// EC_group_p224 returns an |EC_GROUP| for P-224, also known as secp224r1.
// EC_group_p224 returns an `EC_GROUP` for P-224, also known as secp224r1.
OPENSSL_EXPORT const EC_GROUP *EC_group_p224(void);
// EC_group_p256 returns an |EC_GROUP| for P-256, also known as secp256r1 or
// EC_group_p256 returns an `EC_GROUP` for P-256, also known as secp256r1 or
// prime256v1.
OPENSSL_EXPORT const EC_GROUP *EC_group_p256(void);
// EC_group_p384 returns an |EC_GROUP| for P-384, also known as secp384r1.
// EC_group_p384 returns an `EC_GROUP` for P-384, also known as secp384r1.
OPENSSL_EXPORT const EC_GROUP *EC_group_p384(void);
// EC_group_p521 returns an |EC_GROUP| for P-521, also known as secp521r1.
// EC_group_p521 returns an `EC_GROUP` for P-521, also known as secp521r1.
OPENSSL_EXPORT const EC_GROUP *EC_group_p521(void);
// EC_GROUP_new_by_curve_name returns the |EC_GROUP| object for the elliptic
// curve specified by |nid|, or NULL on unsupported NID. For OpenSSL
// EC_GROUP_new_by_curve_name returns the `EC_GROUP` object for the elliptic
// curve specified by `nid`, or NULL on unsupported NID. For OpenSSL
// compatibility, this function returns a non-const pointer which may be passed
// to |EC_GROUP_free|. However, the resulting object is actually static and
// calling |EC_GROUP_free| is optional.
// to `EC_GROUP_free`. However, the resulting object is actually static and
// calling `EC_GROUP_free` is optional.
//
// The supported NIDs are:
// - |NID_secp224r1| (P-224)
// - |NID_X9_62_prime256v1| (P-256)
// - |NID_secp384r1| (P-384)
// - |NID_secp521r1| (P-521)
// - `NID_secp224r1` (P-224)
// - `NID_X9_62_prime256v1` (P-256)
// - `NID_secp384r1` (P-384)
// - `NID_secp521r1` (P-521)
//
// Calling this function causes all four curves to be linked into the binary.
// Prefer calling |EC_group_*| to allow the static linker to drop unused curves.
// Prefer calling `EC_group_*` to allow the static linker to drop unused curves.
//
// If in doubt, use |NID_X9_62_prime256v1|, or see the curve25519.h header for
// If in doubt, use `NID_X9_62_prime256v1`, or see the curve25519.h header for
// more modern primitives.
OPENSSL_EXPORT EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
// EC_GROUP_cmp returns zero if |a| and |b| are the same group and non-zero
// EC_GROUP_cmp returns zero if `a` and `b` are the same group and non-zero
// otherwise.
OPENSSL_EXPORT int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b,
BN_CTX *ignored);
// EC_GROUP_get0_generator returns a pointer to the internal |EC_POINT| object
// in |group| that specifies the generator for the group.
// EC_GROUP_get0_generator returns a pointer to the internal `EC_POINT` object
// in `group` that specifies the generator for the group.
OPENSSL_EXPORT const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
// EC_GROUP_get0_order returns a pointer to the internal |BIGNUM| object in
// |group| that specifies the order of the group.
// EC_GROUP_get0_order returns a pointer to the internal `BIGNUM` object in
// `group` that specifies the order of the group.
OPENSSL_EXPORT const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);
// EC_GROUP_order_bits returns the number of bits of the order of |group|.
// EC_GROUP_order_bits returns the number of bits of the order of `group`.
OPENSSL_EXPORT int EC_GROUP_order_bits(const EC_GROUP *group);
// EC_GROUP_get_cofactor sets |*cofactor| to the cofactor of |group|. It returns
// one on success and zero otherwise. |ctx| is ignored and may be NULL.
// EC_GROUP_get_cofactor sets `*cofactor` to the cofactor of `group`. It returns
// one on success and zero otherwise. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT int EC_GROUP_get_cofactor(const EC_GROUP *group,
BIGNUM *cofactor, BN_CTX *ctx);
// EC_GROUP_get_curve_GFp gets various parameters about a group. It sets
// |*out_p| to the order of the coordinate field and |*out_a| and |*out_b| to
// `*out_p` to the order of the coordinate field and `*out_a` and `*out_b` to
// the parameters of the curve when expressed as y² = x³ + ax + b. Any of the
// output parameters can be NULL. It returns one on success and zero on
// error. |ctx| is ignored and may be NULL.
// error. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *out_p,
BIGNUM *out_a, BIGNUM *out_b,
BN_CTX *ctx);
// EC_GROUP_get_curve_name returns a NID that identifies |group|.
// EC_GROUP_get_curve_name returns a NID that identifies `group`.
OPENSSL_EXPORT int EC_GROUP_get_curve_name(const EC_GROUP *group);
// EC_GROUP_get_degree returns the number of bits needed to represent an
// element of the field underlying |group|.
// element of the field underlying `group`.
OPENSSL_EXPORT unsigned EC_GROUP_get_degree(const EC_GROUP *group);
// EC_curve_nid2nist returns the NIST name of the elliptic curve specified by
// |nid|, or NULL if |nid| is not a NIST curve. For example, it returns "P-256"
// for |NID_X9_62_prime256v1|.
// `nid`, or NULL if `nid` is not a NIST curve. For example, it returns "P-256"
// for `NID_X9_62_prime256v1`.
OPENSSL_EXPORT const char *EC_curve_nid2nist(int nid);
// EC_curve_nist2nid returns the NID of the elliptic curve specified by the NIST
// name |name|, or |NID_undef| if |name| is not a recognized name. For example,
// it returns |NID_X9_62_prime256v1| for "P-256".
// name `name`, or `NID_undef` if `name` is not a recognized name. For example,
// it returns `NID_X9_62_prime256v1` for "P-256".
OPENSSL_EXPORT int EC_curve_nist2nid(const char *name);
// Points on elliptic curves.
// EC_POINT_new returns a fresh |EC_POINT| object in the given group, or NULL
// EC_POINT_new returns a fresh `EC_POINT` object in the given group, or NULL
// on error.
OPENSSL_EXPORT EC_POINT *EC_POINT_new(const EC_GROUP *group);
// EC_POINT_free frees |point| and the data that it points to.
// EC_POINT_free frees `point` and the data that it points to.
OPENSSL_EXPORT void EC_POINT_free(EC_POINT *point);
// EC_POINT_copy sets |*dest| equal to |*src|. It returns one on success and
// EC_POINT_copy sets `*dest` equal to `*src`. It returns one on success and
// zero otherwise.
OPENSSL_EXPORT int EC_POINT_copy(EC_POINT *dest, const EC_POINT *src);
// EC_POINT_dup returns a fresh |EC_POINT| that contains the same values as
// |src|, or NULL on error.
// EC_POINT_dup returns a fresh `EC_POINT` that contains the same values as
// `src`, or NULL on error.
OPENSSL_EXPORT EC_POINT *EC_POINT_dup(const EC_POINT *src,
const EC_GROUP *group);
// EC_POINT_set_to_infinity sets |point| to be the "point at infinity" for the
// EC_POINT_set_to_infinity sets `point` to be the "point at infinity" for the
// given group.
OPENSSL_EXPORT int EC_POINT_set_to_infinity(const EC_GROUP *group,
EC_POINT *point);
// EC_POINT_is_at_infinity returns one iff |point| is the point at infinity and
// EC_POINT_is_at_infinity returns one iff `point` is the point at infinity and
// zero otherwise.
OPENSSL_EXPORT int EC_POINT_is_at_infinity(const EC_GROUP *group,
const EC_POINT *point);
// EC_POINT_is_on_curve returns one if |point| is an element of |group| and
// EC_POINT_is_on_curve returns one if `point` is an element of `group` and
// and zero otherwise or when an error occurs. This is different from OpenSSL,
// which returns -1 on error. |ctx| is ignored and may be NULL.
// which returns -1 on error. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT int EC_POINT_is_on_curve(const EC_GROUP *group,
const EC_POINT *point, BN_CTX *ctx);
// EC_POINT_cmp returns zero if |a| is equal to |b|, greater than zero if
// not equal and -1 on error. |ctx| is ignored and may be NULL.
// EC_POINT_cmp returns zero if `a` is equal to `b`, greater than zero if
// not equal and -1 on error. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a,
const EC_POINT *b, BN_CTX *ctx);
// Point conversion.
// EC_POINT_get_affine_coordinates_GFp sets |x| and |y| to the affine value of
// |point|. It returns one on success and zero otherwise. |ctx| is ignored and
// EC_POINT_get_affine_coordinates_GFp sets `x` and `y` to the affine value of
// `point`. It returns one on success and zero otherwise. `ctx` is ignored and
// may be NULL.
//
// Either |x| or |y| may be NULL to skip computing that coordinate. This is
// Either `x` or `y` may be NULL to skip computing that coordinate. This is
// slightly faster in the common case where only the x-coordinate is needed.
OPENSSL_EXPORT int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
const EC_POINT *point,
@@ -193,21 +193,21 @@ OPENSSL_EXPORT int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
BN_CTX *ctx);
// EC_POINT_get_affine_coordinates is an alias of
// |EC_POINT_get_affine_coordinates_GFp|.
// `EC_POINT_get_affine_coordinates_GFp`.
OPENSSL_EXPORT int EC_POINT_get_affine_coordinates(const EC_GROUP *group,
const EC_POINT *point,
BIGNUM *x, BIGNUM *y,
BN_CTX *ctx);
// EC_POINT_set_affine_coordinates_GFp sets the value of |point| to be
// (|x|, |y|). |ctx| is ignored and may be NULL. It returns one on success or
// EC_POINT_set_affine_coordinates_GFp sets the value of `point` to be
// (`x`, `y`). `ctx` is ignored and may be NULL. It returns one on success or
// zero on error. It's considered an error if the point is not on the curve.
//
// Note that the corresponding function in OpenSSL versions prior to 1.0.2s does
// not check if the point is on the curve. This is a security-critical check, so
// code additionally supporting OpenSSL should repeat the check with
// |EC_POINT_is_on_curve| or check for older OpenSSL versions with
// |OPENSSL_VERSION_NUMBER|.
// `EC_POINT_is_on_curve` or check for older OpenSSL versions with
// `OPENSSL_VERSION_NUMBER`.
OPENSSL_EXPORT int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group,
EC_POINT *point,
const BIGNUM *x,
@@ -215,51 +215,51 @@ OPENSSL_EXPORT int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group,
BN_CTX *ctx);
// EC_POINT_set_affine_coordinates is an alias of
// |EC_POINT_set_affine_coordinates_GFp|.
// `EC_POINT_set_affine_coordinates_GFp`.
OPENSSL_EXPORT int EC_POINT_set_affine_coordinates(const EC_GROUP *group,
EC_POINT *point,
const BIGNUM *x,
const BIGNUM *y,
BN_CTX *ctx);
// EC_POINT_point2oct serialises |point| into the X9.62 form given by |form|
// into, at most, |max_out| bytes at |buf|. It returns the number of bytes
// written or zero on error if |buf| is non-NULL, else the number of bytes
// needed. |ctx| is ignored and may be NULL.
// EC_POINT_point2oct serialises `point` into the X9.62 form given by `form`
// into, at most, `max_out` bytes at `buf`. It returns the number of bytes
// written or zero on error if `buf` is non-NULL, else the number of bytes
// needed. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT size_t EC_POINT_point2oct(const EC_GROUP *group,
const EC_POINT *point,
point_conversion_form_t form,
uint8_t *buf, size_t max_out,
BN_CTX *ctx);
// EC_POINT_point2buf serialises |point| into the X9.62 form given by |form| to
// a newly-allocated buffer and sets |*out_buf| to point to it. It returns the
// EC_POINT_point2buf serialises `point` into the X9.62 form given by `form` to
// a newly-allocated buffer and sets `*out_buf` to point to it. It returns the
// length of the result on success or zero on error. The caller must release
// |*out_buf| with |OPENSSL_free| when done. |ctx| is ignored and may be NULL.
// `*out_buf` with `OPENSSL_free` when done. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT size_t EC_POINT_point2buf(const EC_GROUP *group,
const EC_POINT *point,
point_conversion_form_t form,
uint8_t **out_buf, BN_CTX *ctx);
// EC_POINT_point2cbb behaves like |EC_POINT_point2oct| but appends the
// serialised point to |cbb|. It returns one on success and zero on error. |ctx|
// EC_POINT_point2cbb behaves like `EC_POINT_point2oct` but appends the
// serialised point to `cbb`. It returns one on success and zero on error. `ctx`
// is ignored and may be NULL.
OPENSSL_EXPORT int EC_POINT_point2cbb(CBB *out, const EC_GROUP *group,
const EC_POINT *point,
point_conversion_form_t form,
BN_CTX *ctx);
// EC_POINT_oct2point sets |point| from |len| bytes of X9.62 format
// serialisation in |buf|. It returns one on success and zero on error. |ctx|
// may be NULL. It's considered an error if |buf| does not represent a point on
// EC_POINT_oct2point sets `point` from `len` bytes of X9.62 format
// serialisation in `buf`. It returns one on success and zero on error. `ctx`
// may be NULL. It's considered an error if `buf` does not represent a point on
// the curve.
OPENSSL_EXPORT int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *point,
const uint8_t *buf, size_t len,
BN_CTX *ctx);
// EC_POINT_set_compressed_coordinates_GFp sets |point| to equal the point with
// the given |x| coordinate and the y coordinate specified by |y_bit| (see
// X9.62). It returns one on success and zero otherwise. |ctx| may be NULL.
// EC_POINT_set_compressed_coordinates_GFp sets `point` to equal the point with
// the given `x` coordinate and the y coordinate specified by `y_bit` (see
// X9.62). It returns one on success and zero otherwise. `ctx` may be NULL.
OPENSSL_EXPORT int EC_POINT_set_compressed_coordinates_GFp(
const EC_GROUP *group, EC_POINT *point, const BIGNUM *x, int y_bit,
BN_CTX *ctx);
@@ -267,24 +267,24 @@ OPENSSL_EXPORT int EC_POINT_set_compressed_coordinates_GFp(
// Group operations.
// EC_POINT_add sets |r| equal to |a| plus |b|. It returns one on success and
// zero otherwise. |ctx| is ignored and may be NULL.
// EC_POINT_add sets `r` equal to `a` plus `b`. It returns one on success and
// zero otherwise. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT int EC_POINT_add(const EC_GROUP *group, EC_POINT *r,
const EC_POINT *a, const EC_POINT *b,
BN_CTX *ctx);
// EC_POINT_dbl sets |r| equal to |a| plus |a|. It returns one on success and
// zero otherwise. |ctx| is ignored and may be NULL.
// EC_POINT_dbl sets `r` equal to `a` plus `a`. It returns one on success and
// zero otherwise. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r,
const EC_POINT *a, BN_CTX *ctx);
// EC_POINT_invert sets |a| equal to minus |a|. It returns one on success and
// zero otherwise. |ctx| is ignored and may be NULL.
// EC_POINT_invert sets `a` equal to minus `a`. It returns one on success and
// zero otherwise. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a,
BN_CTX *ctx);
// EC_POINT_mul sets r = generator*n + q*m. It returns one on success and zero
// otherwise. |ctx| may be NULL.
// otherwise. `ctx` may be NULL.
OPENSSL_EXPORT int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r,
const BIGNUM *n, const EC_POINT *q,
const BIGNUM *m, BN_CTX *ctx);
@@ -292,44 +292,44 @@ OPENSSL_EXPORT int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r,
// Hash-to-curve.
//
// The following functions implement primitives from RFC 9380. The |dst|
// The following functions implement primitives from RFC 9380. The `dst`
// parameter in each function is the domain separation tag and must be unique
// for each protocol and between the |hash_to_curve| and |hash_to_scalar|
// for each protocol and between the `hash_to_curve` and `hash_to_scalar`
// variants. See section 3.1 of the spec for additional guidance on this
// parameter.
// EC_hash_to_curve_p256_xmd_sha256_sswu hashes |msg| to a point on |group| and
// writes the result to |out|, implementing the P256_XMD:SHA-256_SSWU_RO_ suite
// EC_hash_to_curve_p256_xmd_sha256_sswu hashes `msg` to a point on `group` and
// writes the result to `out`, implementing the P256_XMD:SHA-256_SSWU_RO_ suite
// from RFC 9380. It returns one on success and zero on error.
OPENSSL_EXPORT int EC_hash_to_curve_p256_xmd_sha256_sswu(
const EC_GROUP *group, EC_POINT *out, const uint8_t *dst, size_t dst_len,
const uint8_t *msg, size_t msg_len);
// EC_hash_to_curve_p384_xmd_sha384_sswu hashes |msg| to a point on |group| and
// writes the result to |out|, implementing the P384_XMD:SHA-384_SSWU_RO_ suite
// EC_hash_to_curve_p384_xmd_sha384_sswu hashes `msg` to a point on `group` and
// writes the result to `out`, implementing the P384_XMD:SHA-384_SSWU_RO_ suite
// from RFC 9380. It returns one on success and zero on error.
OPENSSL_EXPORT int EC_hash_to_curve_p384_xmd_sha384_sswu(
const EC_GROUP *group, EC_POINT *out, const uint8_t *dst, size_t dst_len,
const uint8_t *msg, size_t msg_len);
// EC_encode_to_curve_p256_xmd_sha256_sswu hashes |msg| to a point on |group|
// and writes the result to |out|, implementing the P256_XMD:SHA-256_SSWU_NU_
// EC_encode_to_curve_p256_xmd_sha256_sswu hashes `msg` to a point on `group`
// and writes the result to `out`, implementing the P256_XMD:SHA-256_SSWU_NU_
// suite from RFC 9380. It returns one on success and zero on error.
//
// This is a nonuniform encoding from byte strings to points in |group|. That
// is, the set of possible outputs is only a fraction of the points in |group|,
// This is a nonuniform encoding from byte strings to points in `group`. That
// is, the set of possible outputs is only a fraction of the points in `group`,
// and some points in this set are more likely to be output than others. See
// also RFC 9380, section 10.4
OPENSSL_EXPORT int EC_encode_to_curve_p256_xmd_sha256_sswu(
const EC_GROUP *group, EC_POINT *out, const uint8_t *dst, size_t dst_len,
const uint8_t *msg, size_t msg_len);
// EC_encode_to_curve_p384_xmd_sha384_sswu hashes |msg| to a point on |group|
// and writes the result to |out|, implementing the P384_XMD:SHA-384_SSWU_NU_
// EC_encode_to_curve_p384_xmd_sha384_sswu hashes `msg` to a point on `group`
// and writes the result to `out`, implementing the P384_XMD:SHA-384_SSWU_NU_
// suite from RFC 9380. It returns one on success and zero on error.
//
// This is a nonuniform encoding from byte strings to points in |group|. That
// is, the set of possible outputs is only a fraction of the points in |group|,
// This is a nonuniform encoding from byte strings to points in `group`. That
// is, the set of possible outputs is only a fraction of the points in `group`,
// and some points in this set are more likely to be output than others. See
// also RFC 9380, section 10.4
OPENSSL_EXPORT int EC_encode_to_curve_p384_xmd_sha384_sswu(
@@ -339,61 +339,61 @@ OPENSSL_EXPORT int EC_encode_to_curve_p384_xmd_sha384_sswu(
// Deprecated functions.
// EC_GROUP_free releases a reference to |group|, if |group| was created by
// |EC_GROUP_new_curve_GFp|. If |group| is static, it does nothing.
// EC_GROUP_free releases a reference to `group`, if `group` was created by
// `EC_GROUP_new_curve_GFp`. If `group` is static, it does nothing.
//
// This function exists for OpenSSL compatibility, and to manage dynamic
// |EC_GROUP|s constructed by |EC_GROUP_new_curve_GFp|. Callers that do not need
// `EC_GROUP`s constructed by `EC_GROUP_new_curve_GFp`. Callers that do not need
// either may ignore this function.
OPENSSL_EXPORT void EC_GROUP_free(EC_GROUP *group);
// EC_GROUP_dup increments |group|'s reference count and returns it, if |group|
// was created by |EC_GROUP_new_curve_GFp|. If |group| is static, it simply
// returns |group|.
// EC_GROUP_dup increments `group`'s reference count and returns it, if `group`
// was created by `EC_GROUP_new_curve_GFp`. If `group` is static, it simply
// returns `group`.
//
// This function exists for OpenSSL compatibility, and to manage dynamic
// |EC_GROUP|s constructed by |EC_GROUP_new_curve_GFp|. Callers that do not need
// `EC_GROUP`s constructed by `EC_GROUP_new_curve_GFp`. Callers that do not need
// either may ignore this function.
OPENSSL_EXPORT EC_GROUP *EC_GROUP_dup(const EC_GROUP *group);
// EC_GROUP_new_curve_GFp creates a new, arbitrary elliptic curve group based
// on the equation y² = x³ + a·x + b. It returns the new group or NULL on
// error. The lifetime of the resulting object must be managed with
// |EC_GROUP_dup| and |EC_GROUP_free|.
// `EC_GROUP_dup` and `EC_GROUP_free`.
//
// This new group has no generator. It is an error to use a generator-less group
// with any functions except for |EC_GROUP_free|, |EC_POINT_new|,
// |EC_POINT_set_affine_coordinates_GFp|, and |EC_GROUP_set_generator|.
// with any functions except for `EC_GROUP_free`, `EC_POINT_new`,
// `EC_POINT_set_affine_coordinates_GFp`, and `EC_GROUP_set_generator`.
//
// |EC_GROUP|s returned by this function will always compare as unequal via
// |EC_GROUP_cmp| (even to themselves). |EC_GROUP_get_curve_name| will always
// return |NID_undef|.
// `EC_GROUP`s returned by this function will always compare as unequal via
// `EC_GROUP_cmp` (even to themselves). `EC_GROUP_get_curve_name` will always
// return `NID_undef`.
//
// This function is provided for compatibility with some legacy applications
// only. Avoid using arbitrary curves and use |EC_GROUP_new_by_curve_name|
// only. Avoid using arbitrary curves and use `EC_GROUP_new_by_curve_name`
// instead. This ensures the result meets preconditions necessary for
// elliptic curve algorithms to function correctly and securely.
//
// Given invalid parameters, this function may fail or it may return an
// |EC_GROUP| which breaks these preconditions. Subsequent operations may then
// `EC_GROUP` which breaks these preconditions. Subsequent operations may then
// return arbitrary, incorrect values. Callers should not pass
// attacker-controlled values to this function.
OPENSSL_EXPORT EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p,
const BIGNUM *a,
const BIGNUM *b, BN_CTX *ctx);
// EC_GROUP_set_generator sets the generator for |group| to |generator|, which
// must have the given order and cofactor. It may only be used with |EC_GROUP|
// objects returned by |EC_GROUP_new_curve_GFp| and may only be used once on
// each group. |generator| must have been created using |group|.
// EC_GROUP_set_generator sets the generator for `group` to `generator`, which
// must have the given order and cofactor. It may only be used with `EC_GROUP`
// objects returned by `EC_GROUP_new_curve_GFp` and may only be used once on
// each group. `generator` must have been created using `group`.
OPENSSL_EXPORT int EC_GROUP_set_generator(EC_GROUP *group,
const EC_POINT *generator,
const BIGNUM *order,
const BIGNUM *cofactor);
// EC_GROUP_get_order sets |*order| to the order of |group|, if it's not
// NULL. It returns one on success and zero otherwise. |ctx| is ignored and may
// be NULL. Use |EC_GROUP_get0_order| instead.
// EC_GROUP_get_order sets `*order` to the order of `group`, if it's not
// NULL. It returns one on success and zero otherwise. `ctx` is ignored and may
// be NULL. Use `EC_GROUP_get0_order` instead.
OPENSSL_EXPORT int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order,
BN_CTX *ctx);
@@ -403,7 +403,7 @@ OPENSSL_EXPORT int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order,
// EC_GROUP_set_asn1_flag does nothing.
OPENSSL_EXPORT void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);
// EC_GROUP_get_asn1_flag returns |OPENSSL_EC_NAMED_CURVE|.
// EC_GROUP_get_asn1_flag returns `OPENSSL_EC_NAMED_CURVE`.
OPENSSL_EXPORT int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
typedef struct ec_method_st EC_METHOD;
@@ -414,8 +414,8 @@ OPENSSL_EXPORT const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
// EC_METHOD_get_field_type returns NID_X9_62_prime_field.
OPENSSL_EXPORT int EC_METHOD_get_field_type(const EC_METHOD *meth);
// EC_GROUP_set_point_conversion_form aborts the process if |form| is not
// |POINT_CONVERSION_UNCOMPRESSED| and otherwise does nothing.
// EC_GROUP_set_point_conversion_form aborts the process if `form` is not
// `POINT_CONVERSION_UNCOMPRESSED` and otherwise does nothing.
OPENSSL_EXPORT void EC_GROUP_set_point_conversion_form(
EC_GROUP *group, point_conversion_form_t form);
@@ -425,15 +425,15 @@ typedef struct {
const char *comment;
} EC_builtin_curve;
// EC_get_builtin_curves writes at most |max_num_curves| elements to
// |out_curves| and returns the total number that it would have written, had
// |max_num_curves| been large enough.
// EC_get_builtin_curves writes at most `max_num_curves` elements to
// `out_curves` and returns the total number that it would have written, had
// `max_num_curves` been large enough.
//
// The |EC_builtin_curve| items describe the supported elliptic curves.
// The `EC_builtin_curve` items describe the supported elliptic curves.
OPENSSL_EXPORT size_t EC_get_builtin_curves(EC_builtin_curve *out_curves,
size_t max_num_curves);
// EC_POINT_clear_free calls |EC_POINT_free|.
// EC_POINT_clear_free calls `EC_POINT_free`.
OPENSSL_EXPORT void EC_POINT_clear_free(EC_POINT *point);
include/openssl/ec_key.h
+97 -97
View File
@@ -33,83 +33,83 @@ extern "C" {
// EC key objects.
//
// An |EC_KEY| object represents a public or private EC key. A given object may
// An `EC_KEY` object represents a public or private EC key. A given object may
// be used concurrently on multiple threads by non-mutating functions, provided
// no other thread is concurrently calling a mutating function. Unless otherwise
// documented, functions which take a |const| pointer are non-mutating and
// functions which take a non-|const| pointer are mutating.
// documented, functions which take a `const` pointer are non-mutating and
// functions which take a non-`const` pointer are mutating.
// EC_KEY_new returns a fresh |EC_KEY| object or NULL on error.
// EC_KEY_new returns a fresh `EC_KEY` object or NULL on error.
OPENSSL_EXPORT EC_KEY *EC_KEY_new(void);
// EC_KEY_new_method acts the same as |EC_KEY_new|, but takes an explicit
// |ENGINE|.
// EC_KEY_new_method acts the same as `EC_KEY_new`, but takes an explicit
// `ENGINE`.
OPENSSL_EXPORT EC_KEY *EC_KEY_new_method(const ENGINE *engine);
// EC_KEY_new_by_curve_name returns a fresh EC_KEY for group specified by |nid|
// EC_KEY_new_by_curve_name returns a fresh EC_KEY for group specified by `nid`
// or NULL on error.
OPENSSL_EXPORT EC_KEY *EC_KEY_new_by_curve_name(int nid);
// EC_KEY_free frees all the data owned by |key| and |key| itself.
// EC_KEY_free frees all the data owned by `key` and `key` itself.
OPENSSL_EXPORT void EC_KEY_free(EC_KEY *key);
// EC_KEY_dup returns a fresh copy of |src| or NULL on error.
// EC_KEY_dup returns a fresh copy of `src` or NULL on error.
OPENSSL_EXPORT EC_KEY *EC_KEY_dup(const EC_KEY *src);
// EC_KEY_up_ref increases the reference count of |key| and returns one. It does
// not mutate |key| for thread-safety purposes and may be used concurrently.
// EC_KEY_up_ref increases the reference count of `key` and returns one. It does
// not mutate `key` for thread-safety purposes and may be used concurrently.
OPENSSL_EXPORT int EC_KEY_up_ref(EC_KEY *key);
// EC_KEY_is_opaque returns one if |key| is opaque and doesn't expose its key
// EC_KEY_is_opaque returns one if `key` is opaque and doesn't expose its key
// material. Otherwise it return zero.
OPENSSL_EXPORT int EC_KEY_is_opaque(const EC_KEY *key);
// EC_KEY_get0_group returns a pointer to the |EC_GROUP| object inside |key|.
// EC_KEY_get0_group returns a pointer to the `EC_GROUP` object inside `key`.
OPENSSL_EXPORT const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
// EC_KEY_set_group sets the |EC_GROUP| object that |key| will use to |group|.
// It returns one on success and zero if |key| is already configured with a
// EC_KEY_set_group sets the `EC_GROUP` object that `key` will use to `group`.
// It returns one on success and zero if `key` is already configured with a
// different group.
OPENSSL_EXPORT int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
// EC_KEY_get0_private_key returns a pointer to the private key inside |key|.
// EC_KEY_get0_private_key returns a pointer to the private key inside `key`.
OPENSSL_EXPORT const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);
// EC_KEY_set_private_key sets the private key of |key| to |priv|. It returns
// one on success and zero otherwise. |key| must already have had a group
// configured (see |EC_KEY_set_group| and |EC_KEY_new_by_curve_name|).
// EC_KEY_set_private_key sets the private key of `key` to `priv`. It returns
// one on success and zero otherwise. `key` must already have had a group
// configured (see `EC_KEY_set_group` and `EC_KEY_new_by_curve_name`).
OPENSSL_EXPORT int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *priv);
// EC_KEY_get0_public_key returns a pointer to the public key point inside
// |key|.
// `key`.
OPENSSL_EXPORT const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);
// EC_KEY_set_public_key sets the public key of |key| to |pub|, by copying it.
// It returns one on success and zero otherwise. |key| must already have had a
// group configured (see |EC_KEY_set_group| and |EC_KEY_new_by_curve_name|), and
// |pub| must also belong to that group, and must not be the point at infinity.
// EC_KEY_set_public_key sets the public key of `key` to `pub`, by copying it.
// It returns one on success and zero otherwise. `key` must already have had a
// group configured (see `EC_KEY_set_group` and `EC_KEY_new_by_curve_name`), and
// `pub` must also belong to that group, and must not be the point at infinity.
OPENSSL_EXPORT int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);
#define EC_PKEY_NO_PARAMETERS 0x001
#define EC_PKEY_NO_PUBKEY 0x002
// EC_KEY_get_enc_flags returns the encoding flags for |key|, which is a
// bitwise-OR of |EC_PKEY_*| values.
// EC_KEY_get_enc_flags returns the encoding flags for `key`, which is a
// bitwise-OR of `EC_PKEY_*` values.
OPENSSL_EXPORT unsigned EC_KEY_get_enc_flags(const EC_KEY *key);
// EC_KEY_set_enc_flags sets the encoding flags for |key|, which is a
// bitwise-OR of |EC_PKEY_*| values.
// EC_KEY_set_enc_flags sets the encoding flags for `key`, which is a
// bitwise-OR of `EC_PKEY_*` values.
OPENSSL_EXPORT void EC_KEY_set_enc_flags(EC_KEY *key, unsigned flags);
// EC_KEY_get_conv_form returns the conversation form that will be used by
// |key|.
// `key`.
OPENSSL_EXPORT point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
// EC_KEY_set_conv_form sets the conversion form to be used by |key|.
// EC_KEY_set_conv_form sets the conversion form to be used by `key`.
OPENSSL_EXPORT void EC_KEY_set_conv_form(EC_KEY *key,
point_conversion_form_t cform);
// EC_KEY_check_key performs several checks on |key| (possibly including an
// EC_KEY_check_key performs several checks on `key` (possibly including an
// expensive check that the public key is in the primary subgroup). It returns
// one if all checks pass and zero otherwise. If it returns zero then detail
// about the problem can be found on the error stack.
@@ -120,70 +120,70 @@ OPENSSL_EXPORT int EC_KEY_check_key(const EC_KEY *key);
// 5.6.2.1.4. It returns one if it passes and zero otherwise.
OPENSSL_EXPORT int EC_KEY_check_fips(const EC_KEY *key);
// EC_KEY_set_public_key_affine_coordinates sets the public key in |key| to
// (|x|, |y|). It returns one on success and zero on error. It's considered an
// error if |x| and |y| do not represent a point on |key|'s curve.
// EC_KEY_set_public_key_affine_coordinates sets the public key in `key` to
// (`x`, `y`). It returns one on success and zero on error. It's considered an
// error if `x` and `y` do not represent a point on `key`'s curve.
OPENSSL_EXPORT int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key,
const BIGNUM *x,
const BIGNUM *y);
// EC_KEY_oct2key decodes |len| bytes from |in| as an EC public key in X9.62
// form. |key| must already have a group configured. On success, it sets the
// public key in |key| to the result and returns one. Otherwise, it returns
// zero. |ctx| may be NULL.
// EC_KEY_oct2key decodes `len` bytes from `in` as an EC public key in X9.62
// form. `key` must already have a group configured. On success, it sets the
// public key in `key` to the result and returns one. Otherwise, it returns
// zero. `ctx` may be NULL.
OPENSSL_EXPORT int EC_KEY_oct2key(EC_KEY *key, const uint8_t *in, size_t len,
BN_CTX *ctx);
// EC_KEY_key2buf behaves like |EC_POINT_point2buf|, except it encodes the
// public key in |key|. |ctx| is ignored and may be NULL.
// EC_KEY_key2buf behaves like `EC_POINT_point2buf`, except it encodes the
// public key in `key`. `ctx` is ignored and may be NULL.
OPENSSL_EXPORT size_t EC_KEY_key2buf(const EC_KEY *key,
point_conversion_form_t form,
uint8_t **out_buf, BN_CTX *ctx);
// EC_KEY_oct2priv decodes a big-endian, zero-padded integer from |len| bytes
// from |in| and sets |key|'s private key to the result. It returns one on
// success and zero on error. The input must be padded to the size of |key|'s
// EC_KEY_oct2priv decodes a big-endian, zero-padded integer from `len` bytes
// from `in` and sets `key`'s private key to the result. It returns one on
// success and zero on error. The input must be padded to the size of `key`'s
// group order.
OPENSSL_EXPORT int EC_KEY_oct2priv(EC_KEY *key, const uint8_t *in, size_t len);
// EC_KEY_priv2oct serializes |key|'s private key as a big-endian integer,
// zero-padded to the size of |key|'s group order and writes the result to at
// most |max_out| bytes of |out|. It returns the number of bytes written on
// success and zero on error. If |out| is NULL, it returns the number of bytes
// EC_KEY_priv2oct serializes `key`'s private key as a big-endian integer,
// zero-padded to the size of `key`'s group order and writes the result to at
// most `max_out` bytes of `out`. It returns the number of bytes written on
// success and zero on error. If `out` is NULL, it returns the number of bytes
// needed without writing anything.
OPENSSL_EXPORT size_t EC_KEY_priv2oct(const EC_KEY *key, uint8_t *out,
size_t max_out);
// EC_KEY_priv2buf behaves like |EC_KEY_priv2oct| but sets |*out_buf| to a
// EC_KEY_priv2buf behaves like `EC_KEY_priv2oct` but sets `*out_buf` to a
// newly-allocated buffer containing the result. It returns the size of the
// result on success and zero on error. The caller must release |*out_buf| with
// |OPENSSL_free| when done.
// result on success and zero on error. The caller must release `*out_buf` with
// `OPENSSL_free` when done.
OPENSSL_EXPORT size_t EC_KEY_priv2buf(const EC_KEY *key, uint8_t **out_buf);
// Key generation.
// EC_KEY_generate_key generates a random, private key, calculates the
// corresponding public key and stores both in |key|. It returns one on success
// corresponding public key and stores both in `key`. It returns one on success
// or zero otherwise.
OPENSSL_EXPORT int EC_KEY_generate_key(EC_KEY *key);
// EC_KEY_generate_key_fips behaves like |EC_KEY_generate_key| but performs
// EC_KEY_generate_key_fips behaves like `EC_KEY_generate_key` but performs
// additional checks for FIPS compliance. This function is applicable when
// generating keys for either signing/verification or key agreement because
// both types of consistency check (PCT) are performed.
OPENSSL_EXPORT int EC_KEY_generate_key_fips(EC_KEY *key);
// EC_KEY_derive_from_secret deterministically derives a private key for |group|
// from an input secret using HKDF-SHA256. It returns a newly-allocated |EC_KEY|
// on success or NULL on error. |secret| must not be used in any other
// EC_KEY_derive_from_secret deterministically derives a private key for `group`
// from an input secret using HKDF-SHA256. It returns a newly-allocated `EC_KEY`
// on success or NULL on error. `secret` must not be used in any other
// algorithm. If using a base secret for multiple operations, derive separate
// values with a KDF such as HKDF first.
//
// Note this function implements an arbitrary derivation scheme, rather than any
// particular standard one. New protocols are recommended to use X25519 and
// Ed25519, which have standard byte import functions. See
// |X25519_public_from_private| and |ED25519_keypair_from_seed|.
// `X25519_public_from_private` and `ED25519_keypair_from_seed`.
OPENSSL_EXPORT EC_KEY *EC_KEY_derive_from_secret(const EC_GROUP *group,
const uint8_t *secret,
size_t secret_len);
@@ -192,45 +192,45 @@ OPENSSL_EXPORT EC_KEY *EC_KEY_derive_from_secret(const EC_GROUP *group,
// Serialisation.
// EC_KEY_parse_private_key parses a DER-encoded ECPrivateKey structure (RFC
// 5915) from |cbs| and advances |cbs|. It returns a newly-allocated |EC_KEY| or
// NULL on error. If |group| is non-null, the parameters field of the
// ECPrivateKey may be omitted (but must match |group| if present). Otherwise,
// 5915) from `cbs` and advances `cbs`. It returns a newly-allocated `EC_KEY` or
// NULL on error. If `group` is non-null, the parameters field of the
// ECPrivateKey may be omitted (but must match `group` if present). Otherwise,
// the parameters field is required.
OPENSSL_EXPORT EC_KEY *EC_KEY_parse_private_key(CBS *cbs,
const EC_GROUP *group);
// EC_KEY_marshal_private_key marshals |key| as a DER-encoded ECPrivateKey
// structure (RFC 5915) and appends the result to |cbb|. It returns one on
// success and zero on failure. |enc_flags| is a combination of |EC_PKEY_*|
// EC_KEY_marshal_private_key marshals `key` as a DER-encoded ECPrivateKey
// structure (RFC 5915) and appends the result to `cbb`. It returns one on
// success and zero on failure. `enc_flags` is a combination of `EC_PKEY_*`
// values and controls whether corresponding fields are omitted.
OPENSSL_EXPORT int EC_KEY_marshal_private_key(CBB *cbb, const EC_KEY *key,
unsigned enc_flags);
// EC_KEY_parse_curve_name parses a DER-encoded OBJECT IDENTIFIER as a curve
// name from |cbs| and advances |cbs|. It returns the decoded |EC_GROUP| or NULL
// name from `cbs` and advances `cbs`. It returns the decoded `EC_GROUP` or NULL
// on error.
//
// This function returns a non-const pointer which may be passed to
// |EC_GROUP_free|. However, the resulting object is actually static and calling
// |EC_GROUP_free| is optional.
// `EC_GROUP_free`. However, the resulting object is actually static and calling
// `EC_GROUP_free` is optional.
//
// TODO(davidben): Make this return a const pointer, if it does not break too
// many callers.
OPENSSL_EXPORT EC_GROUP *EC_KEY_parse_curve_name(CBS *cbs);
// EC_KEY_marshal_curve_name marshals |group| as a DER-encoded OBJECT IDENTIFIER
// and appends the result to |cbb|. It returns one on success and zero on
// EC_KEY_marshal_curve_name marshals `group` as a DER-encoded OBJECT IDENTIFIER
// and appends the result to `cbb`. It returns one on success and zero on
// failure.
OPENSSL_EXPORT int EC_KEY_marshal_curve_name(CBB *cbb, const EC_GROUP *group);
// EC_KEY_parse_parameters parses a DER-encoded ECParameters structure (RFC
// 5480) from |cbs| and advances |cbs|. It returns the resulting |EC_GROUP| or
// 5480) from `cbs` and advances `cbs`. It returns the resulting `EC_GROUP` or
// NULL on error. It supports the namedCurve and specifiedCurve options, but use
// of specifiedCurve is deprecated. Use |EC_KEY_parse_curve_name| instead.
// of specifiedCurve is deprecated. Use `EC_KEY_parse_curve_name` instead.
//
// This function returns a non-const pointer which may be passed to
// |EC_GROUP_free|. However, the resulting object is actually static and calling
// |EC_GROUP_free| is optional.
// `EC_GROUP_free`. However, the resulting object is actually static and calling
// `EC_GROUP_free` is optional.
//
// TODO(davidben): Make this return a const pointer, if it does not break too
// many callers.
@@ -239,7 +239,7 @@ OPENSSL_EXPORT EC_GROUP *EC_KEY_parse_parameters(CBS *cbs);
// ex_data functions.
//
// These functions are wrappers. See |ex_data.h| for details.
// These functions are wrappers. See `ex_data.h` for details.
OPENSSL_EXPORT int EC_KEY_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_unused *unused,
@@ -266,7 +266,7 @@ struct ecdsa_method_st {
int (*init)(EC_KEY *key);
int (*finish)(EC_KEY *key);
// sign matches the arguments and behaviour of |ECDSA_sign|.
// sign matches the arguments and behaviour of `ECDSA_sign`.
int (*sign)(const uint8_t *digest, size_t digest_len, uint8_t *sig,
unsigned int *sig_len, EC_KEY *eckey);
@@ -280,62 +280,62 @@ struct ecdsa_method_st {
OPENSSL_EXPORT void EC_KEY_set_asn1_flag(EC_KEY *key, int flag);
// d2i_ECPrivateKey parses a DER-encoded ECPrivateKey structure (RFC 5915) from
// |len| bytes at |*inp|, as described in |d2i_SAMPLE|. On input, if |*out_key|
// `len` bytes at `*inp`, as described in `d2i_SAMPLE`. On input, if `*out_key`
// is non-NULL and has a group configured, the parameters field may be omitted
// but must match that group if present.
//
// Use |EC_KEY_parse_private_key| instead.
// Use `EC_KEY_parse_private_key` instead.
OPENSSL_EXPORT EC_KEY *d2i_ECPrivateKey(EC_KEY **out_key, const uint8_t **inp,
long len);
// i2d_ECPrivateKey marshals |key| as a DER-encoded ECPrivateKey structure (RFC
// 5915), as described in |i2d_SAMPLE|.
// i2d_ECPrivateKey marshals `key` as a DER-encoded ECPrivateKey structure (RFC
// 5915), as described in `i2d_SAMPLE`.
//
// Use |EC_KEY_marshal_private_key| instead.
// Use `EC_KEY_marshal_private_key` instead.
OPENSSL_EXPORT int i2d_ECPrivateKey(const EC_KEY *key, uint8_t **outp);
// d2i_ECPKParameters parses a DER-encoded ECParameters structure (RFC 5480)
// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|. For legacy reasons,
// from `len` bytes at `*inp`, as described in `d2i_SAMPLE`. For legacy reasons,
// it recognizes the specifiedCurve form, but only for curves that are already
// supported as named curves.
//
// Use |EC_KEY_parse_parameters| or |EC_KEY_parse_curve_name| instead.
// Use `EC_KEY_parse_parameters` or `EC_KEY_parse_curve_name` instead.
OPENSSL_EXPORT EC_GROUP *d2i_ECPKParameters(EC_GROUP **out, const uint8_t **inp,
long len);
// i2d_ECPKParameters marshals |group| as a DER-encoded ECParameters structure
// (RFC 5480), as described in |i2d_SAMPLE|.
// i2d_ECPKParameters marshals `group` as a DER-encoded ECParameters structure
// (RFC 5480), as described in `i2d_SAMPLE`.
//
// Use |EC_KEY_marshal_curve_name| instead.
// Use `EC_KEY_marshal_curve_name` instead.
OPENSSL_EXPORT int i2d_ECPKParameters(const EC_GROUP *group, uint8_t **outp);
// d2i_ECParameters parses a DER-encoded ECParameters structure (RFC 5480) from
// |len| bytes at |*inp|, as described in |d2i_SAMPLE|. It returns the result as
// an |EC_KEY| with parameters, but no key, configured.
// `len` bytes at `*inp`, as described in `d2i_SAMPLE`. It returns the result as
// an `EC_KEY` with parameters, but no key, configured.
//
// Use |EC_KEY_parse_parameters| or |EC_KEY_parse_curve_name| instead.
// Use `EC_KEY_parse_parameters` or `EC_KEY_parse_curve_name` instead.
OPENSSL_EXPORT EC_KEY *d2i_ECParameters(EC_KEY **out_key, const uint8_t **inp,
long len);
// i2d_ECParameters marshals |key|'s parameters as a DER-encoded OBJECT
// IDENTIFIER, as described in |i2d_SAMPLE|.
// i2d_ECParameters marshals `key`'s parameters as a DER-encoded OBJECT
// IDENTIFIER, as described in `i2d_SAMPLE`.
//
// Use |EC_KEY_marshal_curve_name| instead.
// Use `EC_KEY_marshal_curve_name` instead.
OPENSSL_EXPORT int i2d_ECParameters(const EC_KEY *key, uint8_t **outp);
// o2i_ECPublicKey parses an EC point from |len| bytes at |*inp| into
// |*out_key|. Note that this differs from the d2i format in that |*out_key|
// must be non-NULL with a group set. On successful exit, |*inp| is advanced by
// |len| bytes. It returns |*out_key| or NULL on error.
// o2i_ECPublicKey parses an EC point from `len` bytes at `*inp` into
// `*out_key`. Note that this differs from the d2i format in that `*out_key`
// must be non-NULL with a group set. On successful exit, `*inp` is advanced by
// `len` bytes. It returns `*out_key` or NULL on error.
//
// Use |EC_POINT_oct2point| instead.
// Use `EC_POINT_oct2point` instead.
OPENSSL_EXPORT EC_KEY *o2i_ECPublicKey(EC_KEY **out_key, const uint8_t **inp,
long len);
// i2o_ECPublicKey marshals an EC point from |key|, as described in
// |i2d_SAMPLE|, except it returns zero on error instead of a negative value.
// i2o_ECPublicKey marshals an EC point from `key`, as described in
// `i2d_SAMPLE`, except it returns zero on error instead of a negative value.
//
// Use |EC_POINT_point2cbb| instead.
// Use `EC_POINT_point2cbb` instead.
OPENSSL_EXPORT int i2o_ECPublicKey(const EC_KEY *key, unsigned char **outp);
include/openssl/ecdh.h
+9 -9
View File
@@ -28,22 +28,22 @@ extern "C" {
// Elliptic curve Diffie-Hellman.
// ECDH_compute_key calculates the shared key between |pub_key| and |priv_key|.
// If |kdf| is not NULL, then it is called with the bytes of the shared key and
// the parameter |out|. When |kdf| returns, the value of |*outlen| becomes the
// ECDH_compute_key calculates the shared key between `pub_key` and `priv_key`.
// If `kdf` is not NULL, then it is called with the bytes of the shared key and
// the parameter `out`. When `kdf` returns, the value of `*outlen` becomes the
// return value. Otherwise, as many bytes of the shared key as will fit are
// copied directly to, at most, |outlen| bytes at |out|. It returns the number
// of bytes written to |out|, or -1 on error.
// copied directly to, at most, `outlen` bytes at `out`. It returns the number
// of bytes written to `out`, or -1 on error.
OPENSSL_EXPORT int ECDH_compute_key(
void *out, size_t outlen, const EC_POINT *pub_key, const EC_KEY *priv_key,
void *(*kdf)(const void *in, size_t inlen, void *out, size_t *outlen));
// ECDH_compute_key_fips calculates the shared key between |pub_key| and
// |priv_key| and hashes it with the appropriate SHA function for |out_len|. The
// only value values for |out_len| are thus 24 (SHA-224), 32 (SHA-256), 48
// ECDH_compute_key_fips calculates the shared key between `pub_key` and
// `priv_key` and hashes it with the appropriate SHA function for `out_len`. The
// only value values for `out_len` are thus 24 (SHA-224), 32 (SHA-256), 48
// (SHA-384), and 64 (SHA-512). It returns one on success and zero on error.
//
// Note that the return value is different to |ECDH_compute_key|: it returns an
// Note that the return value is different to `ECDH_compute_key`: it returns an
// error flag (as is common for BoringSSL) rather than the number of bytes
// written.
//
include/openssl/ecdsa.h
+50 -50
View File
@@ -36,24 +36,24 @@ extern "C" {
// format is variable-length. Callers must be prepared to receive signatures
// that are slightly shorter than the maximum for the ECDSA curve.
// ECDSA_sign signs |digest_len| bytes from |digest| with |key| and writes the
// resulting ASN.1-based signature to |sig|, which must have |ECDSA_size(key)|
// bytes of space. On successful exit, |*sig_len| is set to the actual number of
// bytes written. The |type| argument should be zero. It returns one on success
// ECDSA_sign signs `digest_len` bytes from `digest` with `key` and writes the
// resulting ASN.1-based signature to `sig`, which must have `ECDSA_size(key)`
// bytes of space. On successful exit, `*sig_len` is set to the actual number of
// bytes written. The `type` argument should be zero. It returns one on success
// and zero otherwise.
//
// WARNING: |digest| must be the output of some hash function on the data to be
// WARNING: `digest` must be the output of some hash function on the data to be
// signed. Passing unhashed inputs will not result in a secure signature scheme.
OPENSSL_EXPORT int ECDSA_sign(int type, const uint8_t *digest,
size_t digest_len, uint8_t *sig,
unsigned int *sig_len, const EC_KEY *key);
// ECDSA_verify verifies that |sig_len| bytes from |sig| constitute a valid
// ASN.1-based signature by |key| of |digest|. (The |type| argument should be
// ECDSA_verify verifies that `sig_len` bytes from `sig` constitute a valid
// ASN.1-based signature by `key` of `digest`. (The `type` argument should be
// zero.) It returns one on success or zero if the signature is invalid or an
// error occurred.
//
// WARNING: |digest| must be the output of some hash function on the data to be
// WARNING: `digest` must be the output of some hash function on the data to be
// verified. Passing unhashed inputs will not result in a secure signature
// scheme.
OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest,
@@ -61,13 +61,13 @@ OPENSSL_EXPORT int ECDSA_verify(int type, const uint8_t *digest,
size_t sig_len, const EC_KEY *key);
// ECDSA_size returns the maximum size of an ASN.1-based ECDSA signature using
// |key|. It returns zero if |key| is NULL or if it doesn't have a group set.
// `key`. It returns zero if `key` is NULL or if it doesn't have a group set.
OPENSSL_EXPORT size_t ECDSA_size(const EC_KEY *key);
// Low-level signing and verification.
//
// Low-level functions handle signatures as |ECDSA_SIG| structures which allow
// Low-level functions handle signatures as `ECDSA_SIG` structures which allow
// the two values in an ECDSA signature to be handled separately.
struct ecdsa_sig_st {
@@ -75,41 +75,41 @@ struct ecdsa_sig_st {
BIGNUM *s;
};
// ECDSA_SIG_new returns a fresh |ECDSA_SIG| structure or NULL on error.
// ECDSA_SIG_new returns a fresh `ECDSA_SIG` structure or NULL on error.
OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_new(void);
// ECDSA_SIG_free frees |sig| its member |BIGNUM|s.
// ECDSA_SIG_free frees `sig` its member `BIGNUM`s.
OPENSSL_EXPORT void ECDSA_SIG_free(ECDSA_SIG *sig);
// ECDSA_SIG_get0_r returns the r component of |sig|.
// ECDSA_SIG_get0_r returns the r component of `sig`.
OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig);
// ECDSA_SIG_get0_s returns the s component of |sig|.
// ECDSA_SIG_get0_s returns the s component of `sig`.
OPENSSL_EXPORT const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig);
// ECDSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two
// components of |sig|.
// ECDSA_SIG_get0 sets `*out_r` and `*out_s`, if non-NULL, to the two
// components of `sig`.
OPENSSL_EXPORT void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **out_r,
const BIGNUM **out_s);
// ECDSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may
// ECDSA_SIG_set0 sets `sig`'s components to `r` and `s`, neither of which may
// be NULL. On success, it takes ownership of each argument and returns one.
// Otherwise, it returns zero.
OPENSSL_EXPORT int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
// ECDSA_do_sign signs |digest_len| bytes from |digest| with |key| and returns
// ECDSA_do_sign signs `digest_len` bytes from `digest` with `key` and returns
// the resulting signature structure, or NULL on error.
//
// WARNING: |digest| must be the output of some hash function on the data to be
// WARNING: `digest` must be the output of some hash function on the data to be
// signed. Passing unhashed inputs will not result in a secure signature scheme.
OPENSSL_EXPORT ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest,
size_t digest_len, const EC_KEY *key);
// ECDSA_do_verify verifies that |sig| constitutes a valid signature by |key|
// of |digest|. It returns one on success or zero if the signature is invalid
// ECDSA_do_verify verifies that `sig` constitutes a valid signature by `key`
// of `digest`. It returns one on success or zero if the signature is invalid
// or on error.
//
// WARNING: |digest| must be the output of some hash function on the data to be
// WARNING: `digest` must be the output of some hash function on the data to be
// verified. Passing unhashed inputs will not result in a secure signature
// scheme.
OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len,
@@ -118,28 +118,28 @@ OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len,
// ASN.1 functions.
// ECDSA_SIG_parse parses a DER-encoded ECDSA-Sig-Value structure from |cbs| and
// advances |cbs|. It returns a newly-allocated |ECDSA_SIG| or NULL on error.
// ECDSA_SIG_parse parses a DER-encoded ECDSA-Sig-Value structure from `cbs` and
// advances `cbs`. It returns a newly-allocated `ECDSA_SIG` or NULL on error.
OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_parse(CBS *cbs);
// ECDSA_SIG_from_bytes parses |in| as a DER-encoded ECDSA-Sig-Value structure.
// It returns a newly-allocated |ECDSA_SIG| structure or NULL on error.
// ECDSA_SIG_from_bytes parses `in` as a DER-encoded ECDSA-Sig-Value structure.
// It returns a newly-allocated `ECDSA_SIG` structure or NULL on error.
OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_from_bytes(const uint8_t *in,
size_t in_len);
// ECDSA_SIG_marshal marshals |sig| as a DER-encoded ECDSA-Sig-Value and appends
// the result to |cbb|. It returns one on success and zero on error.
// ECDSA_SIG_marshal marshals `sig` as a DER-encoded ECDSA-Sig-Value and appends
// the result to `cbb`. It returns one on success and zero on error.
OPENSSL_EXPORT int ECDSA_SIG_marshal(CBB *cbb, const ECDSA_SIG *sig);
// ECDSA_SIG_to_bytes marshals |sig| as a DER-encoded ECDSA-Sig-Value and, on
// success, sets |*out_bytes| to a newly allocated buffer containing the result
// ECDSA_SIG_to_bytes marshals `sig` as a DER-encoded ECDSA-Sig-Value and, on
// success, sets `*out_bytes` to a newly allocated buffer containing the result
// and returns one. Otherwise, it returns zero. The result should be freed with
// |OPENSSL_free|.
// `OPENSSL_free`.
OPENSSL_EXPORT int ECDSA_SIG_to_bytes(uint8_t **out_bytes, size_t *out_len,
const ECDSA_SIG *sig);
// ECDSA_SIG_max_len returns the maximum length of a DER-encoded ECDSA-Sig-Value
// structure for a group whose order is represented in |order_len| bytes, or
// structure for a group whose order is represented in `order_len` bytes, or
// zero on overflow.
OPENSSL_EXPORT size_t ECDSA_SIG_max_len(size_t order_len);
@@ -153,23 +153,23 @@ OPENSSL_EXPORT size_t ECDSA_SIG_max_len(size_t order_len);
// the width of the group order. This format is fixed-width, so a given ECDSA
// curve's signatures will always have the same size.
// ECDSA_sign_p1363 signs |digest_len| bytes from |digest| with |key| and writes
// the resulting P1363-based signature to |sig|, which must have
// |ECDSA_size_p1363(key)| bytes of space. On successful exit, |*out_sig_len| is
// ECDSA_sign_p1363 signs `digest_len` bytes from `digest` with `key` and writes
// the resulting P1363-based signature to `sig`, which must have
// `ECDSA_size_p1363(key)` bytes of space. On successful exit, `*out_sig_len` is
// set to the actual number of bytes written, which will always match
// |ECDSA_size_p1363(key)|. It returns one on success and zero otherwise.
// `ECDSA_size_p1363(key)`. It returns one on success and zero otherwise.
//
// WARNING: |digest| must be the output of some hash function on the data to be
// WARNING: `digest` must be the output of some hash function on the data to be
// signed. Passing unhashed inputs will not result in a secure signature scheme.
OPENSSL_EXPORT int ECDSA_sign_p1363(const uint8_t *digest, size_t digest_len,
uint8_t *sig, size_t *out_sig_len,
size_t max_sig_len, const EC_KEY *key);
// ECDSA_verify_p1363 verifies that |sig_len| bytes from |sig| constitute a
// valid P1363-based signature by |key| of |digest|. It returns one on success
// ECDSA_verify_p1363 verifies that `sig_len` bytes from `sig` constitute a
// valid P1363-based signature by `key` of `digest`. It returns one on success
// or zero if the signature is invalid or an error occurred.
//
// WARNING: |digest| must be the output of some hash function on the data to be
// WARNING: `digest` must be the output of some hash function on the data to be
// verified. Passing unhashed inputs will not result in a secure signature
// scheme.
OPENSSL_EXPORT int ECDSA_verify_p1363(const uint8_t *digest, size_t digest_len,
@@ -177,16 +177,16 @@ OPENSSL_EXPORT int ECDSA_verify_p1363(const uint8_t *digest, size_t digest_len,
const EC_KEY *key);
// ECDSA_size_p1363 returns the size of a P1363-based ECDSA signature using
// |key|. It returns zero if |key| is NULL or if it doesn't have a group set.
// `key`. It returns zero if `key` is NULL or if it doesn't have a group set.
OPENSSL_EXPORT size_t ECDSA_size_p1363(const EC_KEY *key);
// Testing-only functions.
// ECDSA_sign_with_nonce_and_leak_private_key_for_testing behaves like
// |ECDSA_do_sign| but uses |nonce| for the ECDSA nonce 'k', instead of a random
// value. |nonce| is interpreted as a big-endian integer. It must be reduced
// modulo the group order and padded with zeros up to |BN_num_bytes(order)|
// `ECDSA_do_sign` but uses `nonce` for the ECDSA nonce 'k', instead of a random
// value. `nonce` is interpreted as a big-endian integer. It must be reduced
// modulo the group order and padded with zeros up to `BN_num_bytes(order)`
// bytes.
//
// WARNING: This function is only exported for testing purposes, when using test
@@ -202,17 +202,17 @@ ECDSA_sign_with_nonce_and_leak_private_key_for_testing(const uint8_t *digest,
// Deprecated functions.
// d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from |len|
// bytes at |*inp|, as described in |d2i_SAMPLE|.
// d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from `len`
// bytes at `*inp`, as described in `d2i_SAMPLE`.
//
// Use |ECDSA_SIG_parse| instead.
// Use `ECDSA_SIG_parse` instead.
OPENSSL_EXPORT ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **out, const uint8_t **inp,
long len);
// i2d_ECDSA_SIG marshals |sig| as a DER-encoded ECDSA-Sig-Value, as described
// in |i2d_SAMPLE|.
// i2d_ECDSA_SIG marshals `sig` as a DER-encoded ECDSA-Sig-Value, as described
// in `i2d_SAMPLE`.
//
// Use |ECDSA_SIG_marshal| instead.
// Use `ECDSA_SIG_marshal` instead.
OPENSSL_EXPORT int i2d_ECDSA_SIG(const ECDSA_SIG *sig, uint8_t **outp);
include/openssl/engine.h
+5 -5
View File
@@ -27,9 +27,9 @@ extern "C" {
// be overridden via a callback. This can be used, for example, to implement an
// RSA* that forwards operations to a hardware module.
//
// Methods are reference counted but |ENGINE|s are not. When creating a method,
// Methods are reference counted but `ENGINE`s are not. When creating a method,
// you should zero the whole structure and fill in the function pointers that
// you wish before setting it on an |ENGINE|. Any functions pointers that
// you wish before setting it on an `ENGINE`. Any functions pointers that
// are NULL indicate that the default behaviour should be used.
@@ -40,7 +40,7 @@ extern "C" {
OPENSSL_EXPORT ENGINE *ENGINE_new(void);
// ENGINE_free decrements the reference counts for all methods linked from
// |engine| and frees |engine| itself. It returns one.
// `engine` and frees `engine` itself. It returns one.
OPENSSL_EXPORT int ENGINE_free(ENGINE *engine);
@@ -69,11 +69,11 @@ OPENSSL_EXPORT ECDSA_METHOD *ENGINE_get_ECDSA_method(const ENGINE *engine);
// These functions take a void* type but actually operate on all method
// structures.
// METHOD_ref increments the reference count of |method|. This is a no-op for
// METHOD_ref increments the reference count of `method`. This is a no-op for
// now because all methods are currently static.
void METHOD_ref(void *method);
// METHOD_unref decrements the reference count of |method| and frees it if the
// METHOD_unref decrements the reference count of `method` and frees it if the
// reference count drops to zero. This is a no-op for now because all methods
// are currently static.
void METHOD_unref(void *method);
include/openssl/err.h
+52 -52
View File
@@ -48,20 +48,20 @@ extern "C" {
// Reading and formatting errors.
// ERR_GET_LIB returns the library code for the error. This is one of
// the |ERR_LIB_*| values.
// the `ERR_LIB_*` values.
OPENSSL_INLINE int ERR_GET_LIB(uint32_t packed_error) {
return (int)((packed_error >> 24) & 0xff);
}
// ERR_GET_REASON returns the reason code for the error. This is one of
// library-specific |LIB_R_*| values where |LIB| is the library (see
// |ERR_GET_LIB|). Note that reason codes are specific to the library.
// library-specific `LIB_R_*` values where `LIB` is the library (see
// `ERR_GET_LIB`). Note that reason codes are specific to the library.
OPENSSL_INLINE int ERR_GET_REASON(uint32_t packed_error) {
return (int)(packed_error & 0xfff);
}
// ERR_equals returns one if |packed_error|'s library and reason code are |lib|
// and |reason|, respectively, and zero otherwise.
// ERR_equals returns one if `packed_error`'s library and reason code are `lib`
// and `reason`, respectively, and zero otherwise.
OPENSSL_INLINE int ERR_equals(uint32_t packed_error, int lib, int reason) {
return ERR_GET_LIB(packed_error) == lib &&
ERR_GET_REASON(packed_error) == reason;
@@ -72,33 +72,33 @@ OPENSSL_INLINE int ERR_equals(uint32_t packed_error, int lib, int reason) {
// it returns zero.
OPENSSL_EXPORT uint32_t ERR_get_error(void);
// ERR_get_error_line acts like |ERR_get_error|, except that the file and line
// ERR_get_error_line acts like `ERR_get_error`, except that the file and line
// number of the call that added the error are also returned.
OPENSSL_EXPORT uint32_t ERR_get_error_line(const char **file, int *line);
// ERR_FLAG_STRING means that the |data| member is a NUL-terminated string that
// can be printed. This is always set if |data| is non-NULL.
// ERR_FLAG_STRING means that the `data` member is a NUL-terminated string that
// can be printed. This is always set if `data` is non-NULL.
#define ERR_FLAG_STRING 1
// ERR_FLAG_MALLOCED is passed into |ERR_set_error_data| to indicate that |data|
// was allocated with |OPENSSL_malloc|.
// ERR_FLAG_MALLOCED is passed into `ERR_set_error_data` to indicate that `data`
// was allocated with `OPENSSL_malloc`.
//
// It is, separately, returned in |*flags| from |ERR_get_error_line_data| to
// indicate that |*data| has a non-static lifetime, but this lifetime is still
// managed by the library. The caller must not call |OPENSSL_free| or |free| on
// |data|.
// It is, separately, returned in `*flags` from `ERR_get_error_line_data` to
// indicate that `*data` has a non-static lifetime, but this lifetime is still
// managed by the library. The caller must not call `OPENSSL_free` or `free` on
// `data`.
#define ERR_FLAG_MALLOCED 2
// ERR_get_error_line_data acts like |ERR_get_error_line|, but also returns the
// ERR_get_error_line_data acts like `ERR_get_error_line`, but also returns the
// error-specific data pointer and flags. The flags are a bitwise-OR of
// |ERR_FLAG_*| values. The error-specific data is owned by the error queue
// `ERR_FLAG_*` values. The error-specific data is owned by the error queue
// and the pointer becomes invalid after the next call that affects the same
// thread's error queue. If |*flags| contains |ERR_FLAG_STRING| then |*data| is
// thread's error queue. If `*flags` contains `ERR_FLAG_STRING` then `*data` is
// human-readable.
OPENSSL_EXPORT uint32_t ERR_get_error_line_data(const char **file, int *line,
const char **data, int *flags);
// The "peek" functions act like the |ERR_get_error| functions, above, but they
// The "peek" functions act like the `ERR_get_error` functions, above, but they
// do not remove the error from the queue.
OPENSSL_EXPORT uint32_t ERR_peek_error(void);
OPENSSL_EXPORT uint32_t ERR_peek_error_line(const char **file, int *line);
@@ -115,9 +115,9 @@ OPENSSL_EXPORT uint32_t ERR_peek_last_error_line_data(const char **file,
int *flags);
// ERR_error_string_n generates a human-readable string representing
// |packed_error|, places it at |buf|, and returns |buf|. It writes at most
// |len| bytes (including the terminating NUL) and truncates the string if
// necessary. If |len| is greater than zero then |buf| is always NUL terminated.
// `packed_error`, places it at `buf`, and returns `buf`. It writes at most
// `len` bytes (including the terminating NUL) and truncates the string if
// necessary. If `len` is greater than zero then `buf` is always NUL terminated.
//
// The string will have the following format:
//
@@ -129,31 +129,31 @@ OPENSSL_EXPORT char *ERR_error_string_n(uint32_t packed_error, char *buf,
size_t len);
// ERR_lib_error_string returns a string representation of the library that
// generated |packed_error|, or a placeholder string is the library is
// generated `packed_error`, or a placeholder string is the library is
// unrecognized.
OPENSSL_EXPORT const char *ERR_lib_error_string(uint32_t packed_error);
// ERR_reason_error_string returns a string representation of the reason for
// |packed_error|, or a placeholder string if the reason is unrecognized.
// `packed_error`, or a placeholder string if the reason is unrecognized.
OPENSSL_EXPORT const char *ERR_reason_error_string(uint32_t packed_error);
// ERR_lib_symbol_name returns the symbol name of library that generated
// |packed_error|, or NULL if unrecognized. For example, an error from
// |ERR_LIB_EVP| would return "EVP".
// `packed_error`, or NULL if unrecognized. For example, an error from
// `ERR_LIB_EVP` would return "EVP".
OPENSSL_EXPORT const char *ERR_lib_symbol_name(uint32_t packed_error);
// ERR_reason_symbol_name returns the symbol name of the reason for
// |packed_error|, or NULL if unrecognized. For example, |ERR_R_INTERNAL_ERROR|
// `packed_error`, or NULL if unrecognized. For example, `ERR_R_INTERNAL_ERROR`
// would return "INTERNAL_ERROR".
//
// Errors from the |ERR_LIB_SYS| library are typically |errno| values and will
// Errors from the `ERR_LIB_SYS` library are typically `errno` values and will
// return NULL. User-defined errors will also return NULL.
OPENSSL_EXPORT const char *ERR_reason_symbol_name(uint32_t packed_error);
// ERR_print_errors_callback_t is the type of a function used by
// |ERR_print_errors_cb|. It takes a pointer to a human readable string (and
// its length) that describes an entry in the error queue. The |ctx| argument
// is an opaque pointer given to |ERR_print_errors_cb|.
// `ERR_print_errors_cb`. It takes a pointer to a human readable string (and
// its length) that describes an entry in the error queue. The `ctx` argument
// is an opaque pointer given to `ERR_print_errors_cb`.
//
// It should return one on success or zero on error, which will stop the
// iteration over the error queue.
@@ -161,22 +161,22 @@ typedef int (*ERR_print_errors_callback_t)(const char *str, size_t len,
void *ctx);
// ERR_print_errors_cb clears the current thread's error queue, calling
// |callback| with a string representation of each error, from the least recent
// `callback` with a string representation of each error, from the least recent
// to the most recent error.
//
// The string will have the following format (which differs from
// |ERR_error_string|):
// `ERR_error_string`):
//
// [thread id]:error:[error code]:[library name]:OPENSSL_internal:[reason string]:[file]:[line number]:[optional string data]
//
// The callback can return one to continue the iteration or zero to stop it.
// The |ctx| argument is an opaque value that is passed through to the
// The `ctx` argument is an opaque value that is passed through to the
// callback.
OPENSSL_EXPORT void ERR_print_errors_cb(ERR_print_errors_callback_t callback,
void *ctx);
// ERR_print_errors_fp clears the current thread's error queue, printing each
// error to |file|. See |ERR_print_errors_cb| for the format.
// error to `file`. See `ERR_print_errors_cb` for the format.
OPENSSL_EXPORT void ERR_print_errors_fp(FILE *file);
@@ -185,21 +185,21 @@ OPENSSL_EXPORT void ERR_print_errors_fp(FILE *file);
// ERR_clear_error clears the error queue for the current thread.
OPENSSL_EXPORT void ERR_clear_error(void);
// ERR_set_mark "marks" the most recent error for use with |ERR_pop_to_mark|.
// ERR_set_mark "marks" the most recent error for use with `ERR_pop_to_mark`.
// It returns one if an error was marked and zero if there are no errors.
OPENSSL_EXPORT int ERR_set_mark(void);
// ERR_pop_to_mark removes errors from the most recent to the least recent
// until (and not including) a "marked" error. It returns zero if no marked
// error was found (and thus all errors were removed) and one otherwise. Errors
// are marked using |ERR_set_mark|.
// are marked using `ERR_set_mark`.
OPENSSL_EXPORT int ERR_pop_to_mark(void);
// Custom errors.
// ERR_get_next_error_library returns a value suitable for passing as the
// |library| argument to |ERR_put_error|. This is intended for code that wishes
// `library` argument to `ERR_put_error`. This is intended for code that wishes
// to push its own, non-standard errors to the error queue.
OPENSSL_EXPORT int ERR_get_next_error_library(void);
@@ -312,29 +312,29 @@ OPENSSL_EXPORT void ERR_load_RAND_strings(void);
// ERR_free_strings does nothing.
OPENSSL_EXPORT void ERR_free_strings(void);
// ERR_remove_state calls |ERR_clear_error|.
// ERR_remove_state calls `ERR_clear_error`.
OPENSSL_EXPORT void ERR_remove_state(unsigned long pid);
// ERR_remove_thread_state clears the error queue for the current thread if
// |tid| is NULL. Otherwise it calls |assert(0)|, because it's no longer
// `tid` is NULL. Otherwise it calls `assert(0)`, because it's no longer
// possible to delete the error queue for other threads.
//
// Use |ERR_clear_error| instead. Note error queues are deleted automatically on
// Use `ERR_clear_error` instead. Note error queues are deleted automatically on
// thread exit. You do not need to call this function to release memory.
OPENSSL_EXPORT void ERR_remove_thread_state(const CRYPTO_THREADID *tid);
// ERR_func_error_string returns the string "OPENSSL_internal".
OPENSSL_EXPORT const char *ERR_func_error_string(uint32_t packed_error);
// ERR_error_string behaves like |ERR_error_string_n| but |len| is implicitly
// |ERR_ERROR_STRING_BUF_LEN|.
// ERR_error_string behaves like `ERR_error_string_n` but `len` is implicitly
// `ERR_ERROR_STRING_BUF_LEN`.
//
// Additionally, if |buf| is NULL, the error string is placed in a static buffer
// Additionally, if `buf` is NULL, the error string is placed in a static buffer
// which is returned. This is not thread-safe and only exists for backwards
// compatibility with legacy callers. The static buffer will be overridden by
// calls in other threads.
//
// Use |ERR_error_string_n| instead.
// Use `ERR_error_string_n` instead.
//
// TODO(fork): remove this function.
OPENSSL_EXPORT char *ERR_error_string(uint32_t packed_error, char *buf);
@@ -373,7 +373,7 @@ OPENSSL_EXPORT void ERR_clear_system_error(void);
OPENSSL_EXPORT void ERR_put_error(int library, int unused, int reason,
const char *file, unsigned line);
// ERR_add_error_data takes a variable number (|count|) of const char*
// ERR_add_error_data takes a variable number (`count`) of const char*
// pointers, concatenates them and sets the result as the data on the most
// recent error.
OPENSSL_EXPORT void ERR_add_error_data(unsigned count, ...);
@@ -383,13 +383,13 @@ OPENSSL_EXPORT void ERR_add_error_data(unsigned count, ...);
OPENSSL_EXPORT void ERR_add_error_dataf(const char *format, ...)
OPENSSL_PRINTF_FORMAT_FUNC(1, 2);
// ERR_set_error_data sets the data on the most recent error to |data|, which
// must be a NUL-terminated string. |flags| must contain |ERR_FLAG_STRING|. If
// |flags| contains |ERR_FLAG_MALLOCED|, this function takes ownership of
// |data|, which must have been allocated with |OPENSSL_malloc|. Otherwise, it
// saves a copy of |data|.
// ERR_set_error_data sets the data on the most recent error to `data`, which
// must be a NUL-terminated string. `flags` must contain `ERR_FLAG_STRING`. If
// `flags` contains `ERR_FLAG_MALLOCED`, this function takes ownership of
// `data`, which must have been allocated with `OPENSSL_malloc`. Otherwise, it
// saves a copy of `data`.
//
// Note this differs from OpenSSL which, when |ERR_FLAG_MALLOCED| is unset,
// Note this differs from OpenSSL which, when `ERR_FLAG_MALLOCED` is unset,
// saves the pointer as-is and requires it remain valid for the lifetime of the
// address space.
OPENSSL_EXPORT void ERR_set_error_data(char *data, int flags);
@@ -404,7 +404,7 @@ OPENSSL_EXPORT void ERR_set_error_data(char *data, int flags);
// OPENSSL_DECLARE_ERROR_REASON is used by util/make_errors.h (which generates
// the error defines) to recognise that an additional reason value is needed.
// This is needed when the reason value is used outside of an
// |OPENSSL_PUT_ERROR| macro. The resulting define will be
// `OPENSSL_PUT_ERROR` macro. The resulting define will be
// ${lib}_R_${reason}.
#define OPENSSL_DECLARE_ERROR_REASON(lib, reason)
include/openssl/evp.h
+435 -435
View File
File diff suppressed because it is too large Load Diff
include/openssl/ex_data.h
+17 -17
View File
@@ -35,9 +35,9 @@ extern "C" {
// Each type that supports ex_data provides three functions:
// TYPE_get_ex_new_index allocates a new index for |TYPE|. An optional
// |free_func| argument may be provided which is called when the owning object
// is destroyed. See |CRYPTO_EX_free| for details. The |argl| and |argp|
// TYPE_get_ex_new_index allocates a new index for `TYPE`. An optional
// `free_func` argument may be provided which is called when the owning object
// is destroyed. See `CRYPTO_EX_free` for details. The `argl` and `argp`
// arguments are opaque values that are passed to the callback. It returns the
// new index or a negative number on error.
OPENSSL_EXPORT int TYPE_get_ex_new_index(long argl, void *argp,
@@ -45,24 +45,24 @@ OPENSSL_EXPORT int TYPE_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_dup *dup_unused,
CRYPTO_EX_free *free_func);
// TYPE_set_ex_data sets an extra data pointer on |t|. The |index| argument
// must have been returned from a previous call to |TYPE_get_ex_new_index|.
// TYPE_set_ex_data sets an extra data pointer on `t`. The `index` argument
// must have been returned from a previous call to `TYPE_get_ex_new_index`.
OPENSSL_EXPORT int TYPE_set_ex_data(TYPE *t, int index, void *arg);
// TYPE_get_ex_data returns an extra data pointer for |t|, or NULL if no such
// pointer exists. The |index| argument should have been returned from a
// previous call to |TYPE_get_ex_new_index|.
// TYPE_get_ex_data returns an extra data pointer for `t`, or NULL if no such
// pointer exists. The `index` argument should have been returned from a
// previous call to `TYPE_get_ex_new_index`.
OPENSSL_EXPORT void *TYPE_get_ex_data(const TYPE *t, int index);
// Some types additionally preallocate index zero, with all callbacks set to
// NULL. Applications that do not need the general ex_data machinery may use
// this instead.
// TYPE_set_app_data sets |t|'s application data pointer to |arg|. It returns
// TYPE_set_app_data sets `t`'s application data pointer to `arg`. It returns
// one on success and zero on error.
OPENSSL_EXPORT int TYPE_set_app_data(TYPE *t, void *arg);
// TYPE_get_app_data returns the application data pointer for |t|, or NULL if no
// TYPE_get_app_data returns the application data pointer for `t`, or NULL if no
// such pointer exists.
OPENSSL_EXPORT void *TYPE_get_app_data(const TYPE *t);
@@ -77,19 +77,19 @@ typedef struct crypto_ex_data_st CRYPTO_EX_DATA;
// CRYPTO_EX_free is a callback function that is called when an object of the
// class with extra data pointers is being destroyed. For example, if this
// callback has been passed to |SSL_get_ex_new_index| then it may be called each
// time an |SSL*| is destroyed.
// callback has been passed to `SSL_get_ex_new_index` then it may be called each
// time an `SSL*` is destroyed.
//
// |parent| and |ad| will be NULL. Historically, the parent object was passed in
// |parent|, but accessing the pointer was not safe because |parent| was in the
// `parent` and `ad` will be NULL. Historically, the parent object was passed in
// `parent`, but accessing the pointer was not safe because `parent` was in the
// process of being destroyed. If the callback has access to some other pointer
// to the parent object, it must not pass the pointer to any BoringSSL APIs.
// Mid-destruction, invariants on the parent object no longer hold.
//
// The arguments |argl| and |argp| contain opaque values that were given to
// |CRYPTO_get_ex_new_index_ex|.
// The arguments `argl` and `argp` contain opaque values that were given to
// `CRYPTO_get_ex_new_index_ex`.
//
// This callback may be called with a NULL value for |ptr| if the object has no
// This callback may be called with a NULL value for `ptr` if the object has no
// value set for this index. However, the callbacks may also be skipped entirely
// if no extra data pointers are set on the object at all.
typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,