From 07a743359947e97bd12b2df14ff86280ab8ad534 Mon Sep 17 00:00:00 2001 From: openssl-machine Date: Wed, 17 Jul 2024 00:49:40 +0000 Subject: [PATCH] deploy openssl/openssl@4ac531ddcb78e531f9e40166a9d1149b00838f5f to master --- master/man3/EVP_RAND/index.html | 2 +- master/man7/EVP_RAND-TEST-RAND/index.html | 2 +- master/man7/provider-rand/index.html | 2 +- master/search/search_index.json | 2 +- master/sitemap.xml | 1748 ++++++++++----------- master/sitemap.xml.gz | Bin 6509 -> 6509 bytes 6 files changed, 878 insertions(+), 878 deletions(-) diff --git a/master/man3/EVP_RAND/index.html b/master/man3/EVP_RAND/index.html index a2d01869d..0c47ca50a 100644 --- a/master/man3/EVP_RAND/index.html +++ b/master/man3/EVP_RAND/index.html @@ -50,4 +50,4 @@ #define EVP_RAND_STATE_UNINITIALISED 0 #define EVP_RAND_STATE_READY 1 #define EVP_RAND_STATE_ERROR 2 -

DESCRIPTION

The EVP RAND routines are a high-level interface to random number generators both deterministic and not. If you just want to generate random bytes then you don't need to use these functions: just call RAND_bytes() or RAND_priv_bytes(). If you want to do more, these calls should be used instead of the older RAND and RAND_DRBG functions.

After creating a EVP_RAND_CTX for the required algorithm using EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by passing them as part of the EVP_RAND_instantiate() call or using calls to EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate(). Finally, call EVP_RAND_generate() to produce cryptographically secure random bytes.

Types

EVP_RAND is a type that holds the implementation of a RAND.

EVP_RAND_CTX is a context type that holds the algorithm inputs. EVP_RAND_CTX structures are reference counted.

Algorithm implementation fetching

EVP_RAND_fetch() fetches an implementation of a RAND algorithm, given a library context libctx and a set of properties. See "ALGORITHM FETCHING" in crypto(7) for further information.

The returned value must eventually be freed with EVP_RAND_free(3).

EVP_RAND_up_ref() increments the reference count of an already fetched RAND.

EVP_RAND_free() frees a fetched algorithm. NULL is a valid parameter, for which this function is a no-op.

Context manipulation functions

EVP_RAND_CTX_new() creates a new context for the RAND implementation rand. If not NULL, parent specifies the seed source for this implementation. Not all random number generators need to have a seed source specified. If a parent is required, a NULL parent will utilise the operating system entropy sources. It is recommended to minimise the number of random number generators that rely on the operating system for their randomness because this is often scarce.

EVP_RAND_CTX_free() frees up the context ctx. If ctx is NULL, nothing is done.

EVP_RAND_CTX_get0_rand() returns the EVP_RAND associated with the context ctx.

Random Number Generator Functions

EVP_RAND_instantiate() processes any parameters in params and then instantiates the RAND ctx with a minimum security strength of <strength> and personalisation string pstr of length <pstr_len>. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_uninstantiate() uninstantiates the RAND ctx as per NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot be used to generate bytes. It can only be freed or instantiated again.

EVP_RAND_generate() produces random bytes from the RAND ctx with the additional input addin of length addin_len. The bytes produced will meet the security strength. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_reseed() reseeds the RAND with new entropy. Entropy ent of length ent_len bytes can be supplied as can additional input addin of length addin_len bytes. In the FIPS provider, both are treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2. Additional seed material is also drawn from the RAND's parent or the operating system. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_nonce() creates a nonce in out of maximum length outlen bytes from the RAND ctx. The function returns the length of the generated nonce. If out is NULL, the length is still returned but no generation takes place. This allows a caller to dynamically allocate a buffer of the appropriate size.

EVP_RAND_enable_locking() enables locking for the RAND ctx and all of its parents. After this ctx will operate in a thread safe manner, albeit more slowly. This function is not itself thread safe if called with the same ctx from multiple threads. Typically locking should be enabled before a ctx is shared across multiple threads.

EVP_RAND_get_params() retrieves details about the implementation rand. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_RAND_CTX_get_params() retrieves chosen parameters, given the context ctx and its underlying context. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_RAND_CTX_set_params() passes chosen parameters to the underlying context, given a context ctx. The set of parameters given with params determine exactly what parameters are passed down. Note that a parameter that is unknown in the underlying context is simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation.

EVP_RAND_gettable_params() returns an OSSL_PARAM(3) array that describes the retrievable and settable parameters. EVP_RAND_gettable_params() returns parameters that can be used with EVP_RAND_get_params().

EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() return constant OSSL_PARAM(3) arrays that describe the retrievable parameters that can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state.

EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() return constant OSSL_PARAM(3) arrays that describe the settable parameters that can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_settable_params() returns the parameters that can be retrieved in the context's current state.

Information functions

EVP_RAND_get_strength() returns the security strength of the RAND ctx.

EVP_RAND_get_state() returns the current state of the RAND ctx. States defined by the OpenSSL RNGs are:

EVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_RAND_get0_provider() returns the provider that holds the implementation of the given rand.

EVP_RAND_do_all_provided() traverses all RAND implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_RAND_get0_name() returns the canonical name of rand.

EVP_RAND_names_do_all() traverses all names for rand, and calls fn with each name and data.

EVP_RAND_get0_description() returns a description of the rand, meant for display and human consumption. The description is at the discretion of the rand implementation.

EVP_RAND_verify_zeroization() confirms if the internal DRBG state is currently zeroed. This is used by the FIPS provider to support the mandatory self tests.

PARAMETERS

The standard parameter names are:

For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. Not all parameters are relevant to, or are understood by all DRBG rands:

NOTES

The use of a nonzero value for the prediction_resistance argument to EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() should be used sparingly. In the default setup, this will cause all public and private DRBGs to be reseeded on next use. Since, by default, public and private DRBGs are allocated on a per thread basis, this can result in significant overhead for highly multi-threaded applications. For normal use-cases, the default "reseed_requests" and "reseed_time_interval" thresholds ensure sufficient prediction resistance over time and you can reduce those values if you think they are too high. Explicitly requesting prediction resistance is intended for more special use-cases like generating long-term secrets.

An EVP_RAND_CTX needs to have locking enabled if it acts as the parent of more than one child and the children can be accessed concurrently. This must be done by explicitly calling EVP_RAND_enable_locking().

The RAND life-cycle is described in life_cycle-rand(7). In the future, the transitions described there will be enforced. When this is done, it will not be considered a breaking change to the API.

RETURN VALUES

EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL if allocation failed.

EVP_RAND_get0_provider() returns a pointer to the provider for the RAND, or NULL on error.

EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated with the context.

EVP_RAND_get0_name() returns the name of the random number generation algorithm.

EVP_RAND_up_ref() returns 1 on success, 0 on error.

EVP_RAND_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX structure or NULL if an error occurred.

EVP_RAND_CTX_free() does not return a value.

EVP_RAND_CTX_up_ref() returns 1 on success, 0 on error.

EVP_RAND_nonce() returns the length of the nonce.

EVP_RAND_get_strength() returns the strength of the random number generator in bits.

EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.

EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is currently zeroed, and 0 if not.

The remaining functions return 1 for success and 0 or a negative value for failure.

SEE ALSO

RAND_bytes(3), EVP_RAND-CTR-DRBG(7), EVP_RAND-HASH-DRBG(7), EVP_RAND-HMAC-DRBG(7), EVP_RAND-TEST-RAND(7), provider-rand(7), life_cycle-rand(7)

HISTORY

EVP_RAND_CTX_up_ref() was added in OpenSSL 3.1.

The remaining functions were added in OpenSSL 3.0.

Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

\ No newline at end of file +

DESCRIPTION

The EVP RAND routines are a high-level interface to random number generators both deterministic and not. If you just want to generate random bytes then you don't need to use these functions: just call RAND_bytes() or RAND_priv_bytes(). If you want to do more, these calls should be used instead of the older RAND and RAND_DRBG functions.

After creating a EVP_RAND_CTX for the required algorithm using EVP_RAND_CTX_new(), inputs to the algorithm are supplied either by passing them as part of the EVP_RAND_instantiate() call or using calls to EVP_RAND_CTX_set_params() before calling EVP_RAND_instantiate(). Finally, call EVP_RAND_generate() to produce cryptographically secure random bytes.

Types

EVP_RAND is a type that holds the implementation of a RAND.

EVP_RAND_CTX is a context type that holds the algorithm inputs. EVP_RAND_CTX structures are reference counted.

Algorithm implementation fetching

EVP_RAND_fetch() fetches an implementation of a RAND algorithm, given a library context libctx and a set of properties. See "ALGORITHM FETCHING" in crypto(7) for further information.

The returned value must eventually be freed with EVP_RAND_free(3).

EVP_RAND_up_ref() increments the reference count of an already fetched RAND.

EVP_RAND_free() frees a fetched algorithm. NULL is a valid parameter, for which this function is a no-op.

Context manipulation functions

EVP_RAND_CTX_new() creates a new context for the RAND implementation rand. If not NULL, parent specifies the seed source for this implementation. Not all random number generators need to have a seed source specified. If a parent is required, a NULL parent will utilise the operating system entropy sources. It is recommended to minimise the number of random number generators that rely on the operating system for their randomness because this is often scarce.

EVP_RAND_CTX_free() frees up the context ctx. If ctx is NULL, nothing is done.

EVP_RAND_CTX_get0_rand() returns the EVP_RAND associated with the context ctx.

Random Number Generator Functions

EVP_RAND_instantiate() processes any parameters in params and then instantiates the RAND ctx with a minimum security strength of <strength> and personalisation string pstr of length <pstr_len>. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_uninstantiate() uninstantiates the RAND ctx as per NIST SP 800-90A and SP 800-90C. Subsequent to this call, the RAND cannot be used to generate bytes. It can only be freed or instantiated again.

EVP_RAND_generate() produces random bytes from the RAND ctx with the additional input addin of length addin_len. The bytes produced will meet the security strength. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_reseed() reseeds the RAND with new entropy. Entropy ent of length ent_len bytes can be supplied as can additional input addin of length addin_len bytes. In the FIPS provider, both are treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2. Additional seed material is also drawn from the RAND's parent or the operating system. If prediction_resistance is specified, fresh entropy from a live source will be sought. This call operates as per NIST SP 800-90A and SP 800-90C.

EVP_RAND_nonce() creates a nonce in out of maximum length outlen bytes from the RAND ctx. The function returns the length of the generated nonce. If out is NULL, the length is still returned but no generation takes place. This allows a caller to dynamically allocate a buffer of the appropriate size.

EVP_RAND_enable_locking() enables locking for the RAND ctx and all of its parents. After this ctx will operate in a thread safe manner, albeit more slowly. This function is not itself thread safe if called with the same ctx from multiple threads. Typically locking should be enabled before a ctx is shared across multiple threads.

EVP_RAND_get_params() retrieves details about the implementation rand. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_RAND_CTX_get_params() retrieves chosen parameters, given the context ctx and its underlying context. The set of parameters given with params determine exactly what parameters should be retrieved. Note that a parameter that is unknown in the underlying context is simply ignored.

EVP_RAND_CTX_set_params() passes chosen parameters to the underlying context, given a context ctx. The set of parameters given with params determine exactly what parameters are passed down. Note that a parameter that is unknown in the underlying context is simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation.

EVP_RAND_gettable_params() returns an OSSL_PARAM(3) array that describes the retrievable and settable parameters. EVP_RAND_gettable_params() returns parameters that can be used with EVP_RAND_get_params().

EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() return constant OSSL_PARAM(3) arrays that describe the retrievable parameters that can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state.

EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() return constant OSSL_PARAM(3) arrays that describe the settable parameters that can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_settable_params() returns the parameters that can be retrieved in the context's current state.

Information functions

EVP_RAND_get_strength() returns the security strength of the RAND ctx.

EVP_RAND_get_state() returns the current state of the RAND ctx. States defined by the OpenSSL RNGs are:

EVP_RAND_is_a() returns 1 if rand is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_RAND_get0_provider() returns the provider that holds the implementation of the given rand.

EVP_RAND_do_all_provided() traverses all RAND implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_RAND_get0_name() returns the canonical name of rand.

EVP_RAND_names_do_all() traverses all names for rand, and calls fn with each name and data.

EVP_RAND_get0_description() returns a description of the rand, meant for display and human consumption. The description is at the discretion of the rand implementation.

EVP_RAND_verify_zeroization() confirms if the internal DRBG state is currently zeroed. This is used by the FIPS provider to support the mandatory self tests.

PARAMETERS

The standard parameter names are:

For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. Not all parameters are relevant to, or are understood by all DRBG rands:

NOTES

The use of a nonzero value for the prediction_resistance argument to EVP_RAND_instantiate(), EVP_RAND_generate() or EVP_RAND_reseed() should be used sparingly. In the default setup, this will cause all public and private DRBGs to be reseeded on next use. Since, by default, public and private DRBGs are allocated on a per thread basis, this can result in significant overhead for highly multi-threaded applications. For normal use-cases, the default "reseed_requests" and "reseed_time_interval" thresholds ensure sufficient prediction resistance over time and you can reduce those values if you think they are too high. Explicitly requesting prediction resistance is intended for more special use-cases like generating long-term secrets.

An EVP_RAND_CTX needs to have locking enabled if it acts as the parent of more than one child and the children can be accessed concurrently. This must be done by explicitly calling EVP_RAND_enable_locking().

The RAND life-cycle is described in life_cycle-rand(7). In the future, the transitions described there will be enforced. When this is done, it will not be considered a breaking change to the API.

RETURN VALUES

EVP_RAND_fetch() returns a pointer to a newly fetched EVP_RAND, or NULL if allocation failed.

EVP_RAND_get0_provider() returns a pointer to the provider for the RAND, or NULL on error.

EVP_RAND_CTX_get0_rand() returns a pointer to the EVP_RAND associated with the context.

EVP_RAND_get0_name() returns the name of the random number generation algorithm.

EVP_RAND_up_ref() returns 1 on success, 0 on error.

EVP_RAND_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_RAND_CTX_new() returns either the newly allocated EVP_RAND_CTX structure or NULL if an error occurred.

EVP_RAND_CTX_free() does not return a value.

EVP_RAND_CTX_up_ref() returns 1 on success, 0 on error.

EVP_RAND_nonce() returns the length of the nonce.

EVP_RAND_get_strength() returns the strength of the random number generator in bits.

EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.

EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is currently zeroed, and 0 if not.

The remaining functions return 1 for success and 0 or a negative value for failure.

SEE ALSO

RAND_bytes(3), EVP_RAND-CTR-DRBG(7), EVP_RAND-HASH-DRBG(7), EVP_RAND-HMAC-DRBG(7), EVP_RAND-TEST-RAND(7), provider-rand(7), life_cycle-rand(7)

HISTORY

EVP_RAND_CTX_up_ref() was added in OpenSSL 3.1.

The remaining functions were added in OpenSSL 3.0.

Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

\ No newline at end of file diff --git a/master/man7/EVP_RAND-TEST-RAND/index.html b/master/man7/EVP_RAND-TEST-RAND/index.html index 90f1add3d..57d69787f 100644 --- a/master/man7/EVP_RAND-TEST-RAND/index.html +++ b/master/man7/EVP_RAND-TEST-RAND/index.html @@ -1,4 +1,4 @@ -EVP_RAND-TEST-RAND - OpenSSL Documentation
Skip to content

EVP_RAND-TEST-RAND

NAME

EVP_RAND-TEST-RAND - The test EVP_RAND implementation

DESCRIPTION

Support for a test generator through the EVP_RAND API. This generator is for test purposes only, it does not generate random numbers.

Identity

"TEST-RAND" is the name for this implementation; it can be used with the EVP_RAND_fetch() function.

Supported parameters

The supported parameters are:

  • "state" (OSSL_RAND_PARAM_STATE) <integer>

    These parameter works as described in "PARAMETERS" in EVP_RAND(3).

  • "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

  • "reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
  • "reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>
  • "max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
  • "min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>
  • "max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>
  • "min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>
  • "max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>
  • "max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>
  • "max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>

  • "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>

    These parameters work as described in "PARAMETERS" in EVP_RAND(3), except that they can all be set as well as read.

  • "test_entropy" (OSSL_RAND_PARAM_TEST_ENTROPY) <octet string>

    Sets the bytes returned when the test generator is sent an entropy request. The current position is remembered across generate calls. If there are insufficient data present to satisfy a call, an error is returned.

  • "test_nonce" (OSSL_RAND_PARAM_TEST_NONCE) <octet string>

    Sets the bytes returned when the test generator is sent a nonce request. Each nonce request will return all of the bytes.

  • "generate" (OSSL_RAND_PARAM_GENERATE) <integer>

    If this parameter is zero, it will only emit the nonce and entropy data supplied via the aforementioned parameters. Otherwise, low quality non-cryptographic pseudorandom output is produced. This parameter defaults to zero.

NOTES

A context for a test generator can be obtained by calling:

EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL);
+EVP_RAND-TEST-RAND - OpenSSL Documentation
EVP_RAND-TEST-RAND
NAME
EVP_RAND-TEST-RAND - The test EVP_RAND implementation
DESCRIPTION
Support for a test generator through the EVP_RAND API. This generator is for test purposes only, it does not generate random numbers.
Identity
"TEST-RAND" is the name for this implementation; it can be used with the EVP_RAND_fetch() function.
Supported parameters
The supported parameters are:
  • "state" (OSSL_RAND_PARAM_STATE) <integer>
  • "fips-indicator" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) <integer>
    These parameter works as described in "PARAMETERS" in EVP_RAND(3).
  • "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>
  • "reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
  • "reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>
  • "max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
  • "min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>
  • "max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>
  • "min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>
  • "max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>
  • "max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>
  • "max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>
  • "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>
    These parameters work as described in "PARAMETERS" in EVP_RAND(3), except that they can all be set as well as read.
  • "test_entropy" (OSSL_RAND_PARAM_TEST_ENTROPY) <octet string>
    Sets the bytes returned when the test generator is sent an entropy request. The current position is remembered across generate calls. If there are insufficient data present to satisfy a call, an error is returned.
  • "test_nonce" (OSSL_RAND_PARAM_TEST_NONCE) <octet string>
    Sets the bytes returned when the test generator is sent a nonce request. Each nonce request will return all of the bytes.
  • "generate" (OSSL_RAND_PARAM_GENERATE) <integer>
    If this parameter is zero, it will only emit the nonce and entropy data supplied via the aforementioned parameters. Otherwise, low quality non-cryptographic pseudorandom output is produced. This parameter defaults to zero.
NOTES
A context for a test generator can be obtained by calling:
EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST-RAND", NULL);
 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
 
EXAMPLES
EVP_RAND *rand;
 EVP_RAND_CTX *rctx;
diff --git a/master/man7/provider-rand/index.html b/master/man7/provider-rand/index.html
index e00d1eb73..d29bbcdd3 100644
--- a/master/man7/provider-rand/index.html
+++ b/master/man7/provider-rand/index.html
@@ -50,4 +50,4 @@
 int OSSL_FUNC_rand_get_params(OSSL_PARAM params[]);
 int OSSL_FUNC_rand_get_ctx_params(void *ctx, OSSL_PARAM params[]);
 int OSSL_FUNC_rand_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
-
DESCRIPTION
This documentation is primarily aimed at provider authors. See provider(7) for further information.
The RAND operation enables providers to implement random number generation algorithms and random number sources and make them available to applications via the API function EVP_RAND(3).
Context Management Functions
OSSL_FUNC_rand_newctx() should create and return a pointer to a provider side structure for holding context information during a rand operation. A pointer to this context will be passed back in a number of the other rand operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)). The parameter parent specifies another rand instance to be used for seeding purposes. If NULL and the specific instance supports it, the operating system will be used for seeding. The parameter parent_calls points to the dispatch table for parent. Thus, the parent need not be from the same provider as the new instance.
OSSL_FUNC_rand_freectx() is passed a pointer to the provider side rand context in the mctx parameter. If it receives NULL as ctx value, it should not do anything other than return. This function should free any resources associated with that context.
Random Number Generator Functions: NIST
These functions correspond to those defined in NIST SP 800-90A and SP 800-90C.
OSSL_FUNC_rand_instantiate() is used to instantiate the DRBG ctx at a requested security strength. In addition, prediction_resistance can be requested. Additional input addin of length addin_len bytes can optionally be provided. The parameters specified in params configure the DRBG and these should be processed before instantiation.
OSSL_FUNC_rand_uninstantiate() is used to uninstantiate the DRBG ctx. After being uninstantiated, a DRBG is unable to produce output until it is instantiated anew.
OSSL_FUNC_rand_generate() is used to generate random bytes from the DRBG ctx. It will generate outlen bytes placing them into the buffer pointed to by out. The generated bytes will meet the specified security strength and, if prediction_resistance is true, the bytes will be produced after reseeding from a live entropy source. Additional input addin of length addin_len bytes can optionally be provided.
Random Number Generator Functions: Additional
OSSL_FUNC_rand_nonce() is used to generate a nonce of the given strength with a length from min_noncelen to max_noncelen. If the output buffer out is NULL, the length of the nonce should be returned.
OSSL_FUNC_rand_get_seed() is used by deterministic generators to obtain their seeding material from their parent. The seed bytes will meet the specified security level of entropy bits and there will be between min_len and max_len inclusive bytes in total. If prediction_resistance is true, the bytes will be produced from a live entropy source. Additional input addin of length addin_len bytes can optionally be provided. A pointer to the seed material is returned in *buffer and this must be freed by a later call to OSSL_FUNC_rand_clear_seed().
OSSL_FUNC_rand_clear_seed() frees a seed buffer of length b_len bytes which was previously allocated by OSSL_FUNC_rand_get_seed().
OSSL_FUNC_rand_verify_zeroization() is used to determine if the internal state of the DRBG is zero. This capability is mandated by NIST as part of the self tests, it is unlikely to be useful in other circumstances.
Context Locking
When DRBGs are used by multiple threads, there must be locking employed to ensure their proper operation. Because locking introduces an overhead, it is disabled by default.
OSSL_FUNC_rand_enable_locking() allows locking to be turned on for a DRBG and all of its parent DRBGs. From this call onwards, the DRBG can be used in a thread safe manner.
OSSL_FUNC_rand_lock() is used to lock a DRBG. Once locked, exclusive access is guaranteed.
OSSL_FUNC_rand_unlock() is used to unlock a DRBG.
Rand Parameters
See OSSL_PARAM(3) for further details on the parameters structure used by these functions.
OSSL_FUNC_rand_get_params() gets details of parameter values associated with the provider algorithm and stores them in params.
OSSL_FUNC_rand_set_ctx_params() sets rand parameters associated with the given provider side rand context ctx to params. Any parameter settings are additional to any that were previously set. Passing NULL for params should return true.
OSSL_FUNC_rand_get_ctx_params() gets details of currently set parameter values associated with the given provider side rand context ctx and stores them in params. Passing NULL for params should return true.
OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params(), and OSSL_FUNC_rand_settable_ctx_params() all return constant OSSL_PARAM(3) arrays as descriptors of the parameters that OSSL_FUNC_rand_get_params(), OSSL_FUNC_rand_get_ctx_params(), and OSSL_FUNC_rand_set_ctx_params() can handle, respectively. OSSL_FUNC_rand_gettable_ctx_params() and OSSL_FUNC_rand_settable_ctx_params() will return the parameters associated with the provider side context ctx in its current state if it is not NULL. Otherwise, they return the parameters associated with the provider side algorithm provctx.
Parameters currently recognised by built-in rands are as follows. Not all parameters are relevant to, or are understood by all rands:
  • "state" (OSSL_RAND_PARAM_STATE) <integer>
    Returns the state of the random number generator.
  • "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>
    Returns the bit strength of the random number generator.
For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. Not all parameters are relevant to, or are understood by all DRBG rands:
  • "reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
    Reads or set the number of generate requests before reseeding the associated RAND ctx.
  • "reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>
    Reads or set the number of elapsed seconds before reseeding the associated RAND ctx.
  • "max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>
    Specifies the maximum number of bytes that can be generated in a single call to OSSL_FUNC_rand_generate.
  • "min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>
  • "max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>
    Specify the minimum and maximum number of bytes of random material that can be used to seed the DRBG.
  • "min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>
  • "max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>
    Specify the minimum and maximum number of bytes of nonce that can be used to instantiate the DRBG.
  • "max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>
  • "max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>
    Specify the minimum and maximum number of bytes of personalisation string that can be used with the DRBG.
  • "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>
    Specifies the number of times the DRBG has been seeded or reseeded.
  • "digest" (OSSL_DRBG_PARAM_DIGEST) 
  • "cipher" (OSSL_DRBG_PARAM_CIPHER) 
  • "mac" (OSSL_DRBG_PARAM_MAC) 
    Sets the name of the underlying cipher, digest or MAC to be used. It must name a suitable algorithm for the DRBG that's being used.
  • "properties" (OSSL_DRBG_PARAM_PROPERTIES) 
    Sets the properties to be queried when trying to fetch an underlying algorithm. This must be given together with the algorithm naming parameter to be considered valid.
  • "fips-indicator" (OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR) <integer>
    A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling OSSL_FUNC_rand_generate(). It may return 0 if the "digest-check" is set to 0. This option is used by the OpenSSL FIPS provider.
  • "digest-check" (OSSL_DRBG_PARAM_FIPS_DIGEST_CHECK) <integer>
    If required this parameter should be set before the digest is set. The default value of 1 causes an error when the digest is set if the digest is not FIPS approved (e.g. truncated digests). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if set to 0.
RETURN VALUES
OSSL_FUNC_rand_newctx() should return the newly created provider side rand context, or NULL on failure.
OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params() and OSSL_FUNC_rand_settable_ctx_params() should return a constant OSSL_PARAM(3) array, or NULL if none is offered.
OSSL_FUNC_rand_nonce() returns the size of the generated nonce, or 0 on error.
OSSL_FUNC_rand_get_seed() returns the size of the generated seed, or 0 on error.
All of the remaining functions should return 1 for success or 0 on error.
NOTES
The RAND life-cycle is described in life_cycle-rand(7). Providers should ensure that the various transitions listed there are supported. At some point the EVP layer will begin enforcing the listed transitions.
SEE ALSO
provider(7), RAND(7), EVP_RAND(7), life_cycle-rand(7), EVP_RAND(3)
HISTORY
The provider RAND interface was introduced in OpenSSL 3.0. The Rand Parameters "fips-indicator" and "digest-check" were added in OpenSSL 3.4.
Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

\ No newline at end of file
+

DESCRIPTION

This documentation is primarily aimed at provider authors. See provider(7) for further information.

The RAND operation enables providers to implement random number generation algorithms and random number sources and make them available to applications via the API function EVP_RAND(3).

Context Management Functions

OSSL_FUNC_rand_newctx() should create and return a pointer to a provider side structure for holding context information during a rand operation. A pointer to this context will be passed back in a number of the other rand operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)). The parameter parent specifies another rand instance to be used for seeding purposes. If NULL and the specific instance supports it, the operating system will be used for seeding. The parameter parent_calls points to the dispatch table for parent. Thus, the parent need not be from the same provider as the new instance.

OSSL_FUNC_rand_freectx() is passed a pointer to the provider side rand context in the mctx parameter. If it receives NULL as ctx value, it should not do anything other than return. This function should free any resources associated with that context.

Random Number Generator Functions: NIST

These functions correspond to those defined in NIST SP 800-90A and SP 800-90C.

OSSL_FUNC_rand_instantiate() is used to instantiate the DRBG ctx at a requested security strength. In addition, prediction_resistance can be requested. Additional input addin of length addin_len bytes can optionally be provided. The parameters specified in params configure the DRBG and these should be processed before instantiation.

OSSL_FUNC_rand_uninstantiate() is used to uninstantiate the DRBG ctx. After being uninstantiated, a DRBG is unable to produce output until it is instantiated anew.

OSSL_FUNC_rand_generate() is used to generate random bytes from the DRBG ctx. It will generate outlen bytes placing them into the buffer pointed to by out. The generated bytes will meet the specified security strength and, if prediction_resistance is true, the bytes will be produced after reseeding from a live entropy source. Additional input addin of length addin_len bytes can optionally be provided.

Random Number Generator Functions: Additional

OSSL_FUNC_rand_nonce() is used to generate a nonce of the given strength with a length from min_noncelen to max_noncelen. If the output buffer out is NULL, the length of the nonce should be returned.

OSSL_FUNC_rand_get_seed() is used by deterministic generators to obtain their seeding material from their parent. The seed bytes will meet the specified security level of entropy bits and there will be between min_len and max_len inclusive bytes in total. If prediction_resistance is true, the bytes will be produced from a live entropy source. Additional input addin of length addin_len bytes can optionally be provided. A pointer to the seed material is returned in *buffer and this must be freed by a later call to OSSL_FUNC_rand_clear_seed().

OSSL_FUNC_rand_clear_seed() frees a seed buffer of length b_len bytes which was previously allocated by OSSL_FUNC_rand_get_seed().

OSSL_FUNC_rand_verify_zeroization() is used to determine if the internal state of the DRBG is zero. This capability is mandated by NIST as part of the self tests, it is unlikely to be useful in other circumstances.

Context Locking

When DRBGs are used by multiple threads, there must be locking employed to ensure their proper operation. Because locking introduces an overhead, it is disabled by default.

OSSL_FUNC_rand_enable_locking() allows locking to be turned on for a DRBG and all of its parent DRBGs. From this call onwards, the DRBG can be used in a thread safe manner.

OSSL_FUNC_rand_lock() is used to lock a DRBG. Once locked, exclusive access is guaranteed.

OSSL_FUNC_rand_unlock() is used to unlock a DRBG.

Rand Parameters

See OSSL_PARAM(3) for further details on the parameters structure used by these functions.

OSSL_FUNC_rand_get_params() gets details of parameter values associated with the provider algorithm and stores them in params.

OSSL_FUNC_rand_set_ctx_params() sets rand parameters associated with the given provider side rand context ctx to params. Any parameter settings are additional to any that were previously set. Passing NULL for params should return true.

OSSL_FUNC_rand_get_ctx_params() gets details of currently set parameter values associated with the given provider side rand context ctx and stores them in params. Passing NULL for params should return true.

OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params(), and OSSL_FUNC_rand_settable_ctx_params() all return constant OSSL_PARAM(3) arrays as descriptors of the parameters that OSSL_FUNC_rand_get_params(), OSSL_FUNC_rand_get_ctx_params(), and OSSL_FUNC_rand_set_ctx_params() can handle, respectively. OSSL_FUNC_rand_gettable_ctx_params() and OSSL_FUNC_rand_settable_ctx_params() will return the parameters associated with the provider side context ctx in its current state if it is not NULL. Otherwise, they return the parameters associated with the provider side algorithm provctx.

Parameters currently recognised by built-in rands are as follows. Not all parameters are relevant to, or are understood by all rands:

  • "state" (OSSL_RAND_PARAM_STATE) <integer>

    Returns the state of the random number generator.

  • "strength" (OSSL_RAND_PARAM_STRENGTH) <unsigned integer>

    Returns the bit strength of the random number generator.

  • "fips-indicator" (OSSL_RAND_PARAM_FIPS_APPROVED_INDICATOR) <integer>

    A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This option is used by the OpenSSL FIPS provider and is not supported by all EVP_RAND sources.

For rands that are also deterministic random bit generators (DRBGs), these additional parameters are recognised. Not all parameters are relevant to, or are understood by all DRBG rands:

  • "reseed_requests" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

    Reads or set the number of generate requests before reseeding the associated RAND ctx.

  • "reseed_time_interval" (OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL) <integer>

    Reads or set the number of elapsed seconds before reseeding the associated RAND ctx.

  • "max_request" (OSSL_DRBG_PARAM_RESEED_REQUESTS) <unsigned integer>

    Specifies the maximum number of bytes that can be generated in a single call to OSSL_FUNC_rand_generate.

  • "min_entropylen" (OSSL_DRBG_PARAM_MIN_ENTROPYLEN) <unsigned integer>

  • "max_entropylen" (OSSL_DRBG_PARAM_MAX_ENTROPYLEN) <unsigned integer>

    Specify the minimum and maximum number of bytes of random material that can be used to seed the DRBG.

  • "min_noncelen" (OSSL_DRBG_PARAM_MIN_NONCELEN) <unsigned integer>

  • "max_noncelen" (OSSL_DRBG_PARAM_MAX_NONCELEN) <unsigned integer>

    Specify the minimum and maximum number of bytes of nonce that can be used to instantiate the DRBG.

  • "max_perslen" (OSSL_DRBG_PARAM_MAX_PERSLEN) <unsigned integer>

  • "max_adinlen" (OSSL_DRBG_PARAM_MAX_ADINLEN) <unsigned integer>

    Specify the minimum and maximum number of bytes of personalisation string that can be used with the DRBG.

  • "reseed_counter" (OSSL_DRBG_PARAM_RESEED_COUNTER) <unsigned integer>

    Specifies the number of times the DRBG has been seeded or reseeded.

  • "digest" (OSSL_DRBG_PARAM_DIGEST)

  • "cipher" (OSSL_DRBG_PARAM_CIPHER)

  • "mac" (OSSL_DRBG_PARAM_MAC)

    Sets the name of the underlying cipher, digest or MAC to be used. It must name a suitable algorithm for the DRBG that's being used.

  • "properties" (OSSL_DRBG_PARAM_PROPERTIES)

    Sets the properties to be queried when trying to fetch an underlying algorithm. This must be given together with the algorithm naming parameter to be considered valid.

  • "fips-indicator" (OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR) <integer>

    A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling OSSL_FUNC_rand_generate(). It may return 0 if the "digest-check" is set to 0. This option is used by the OpenSSL FIPS provider.

  • "digest-check" (OSSL_DRBG_PARAM_FIPS_DIGEST_CHECK) <integer>

    If required this parameter should be set before the digest is set. The default value of 1 causes an error when the digest is set if the digest is not FIPS approved (e.g. truncated digests). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0. This option is used by the OpenSSL FIPS provider, and breaks FIPS compliance if set to 0.

RETURN VALUES

OSSL_FUNC_rand_newctx() should return the newly created provider side rand context, or NULL on failure.

OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params() and OSSL_FUNC_rand_settable_ctx_params() should return a constant OSSL_PARAM(3) array, or NULL if none is offered.

OSSL_FUNC_rand_nonce() returns the size of the generated nonce, or 0 on error.

OSSL_FUNC_rand_get_seed() returns the size of the generated seed, or 0 on error.

All of the remaining functions should return 1 for success or 0 on error.

NOTES

The RAND life-cycle is described in life_cycle-rand(7). Providers should ensure that the various transitions listed there are supported. At some point the EVP layer will begin enforcing the listed transitions.

SEE ALSO

provider(7), RAND(7), EVP_RAND(7), life_cycle-rand(7), EVP_RAND(3)

HISTORY

The provider RAND interface was introduced in OpenSSL 3.0. The Rand Parameters "fips-indicator" and "digest-check" were added in OpenSSL 3.4.

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

\ No newline at end of file diff --git a/master/search/search_index.json b/master/search/search_index.json index 9e7f1c200..df9846645 100644 --- a/master/search/search_index.json +++ b/master/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"man1/CA.pl/","title":"CA.pl","text":""},{"location":"man1/CA.pl/#name","title":"NAME","text":"

CA.pl - friendlier interface for OpenSSL certificate programs

"},{"location":"man1/CA.pl/#synopsis","title":"SYNOPSIS","text":"

CA.pl -? | -h | -help

CA.pl -newcert | -newreq | -newreq-nodes | -xsign | -sign | -signCA | -signcert | -crl | -newca [-extra-cmd parameter]

CA.pl -pkcs12 [certname]

CA.pl -verify certfile ...

CA.pl -revoke certfile [reason]

"},{"location":"man1/CA.pl/#description","title":"DESCRIPTION","text":"

The CA.pl script is a perl script that supplies the relevant command line arguments to the openssl(1) command for some common certificate operations. It is intended to simplify the process of certificate creation and management by the use of some simple options.

The script is intended as a simple front end for the openssl(1) program for use by a beginner. Its behaviour isn't always what is wanted. For more control over the behaviour of the certificate commands call the openssl(1) command directly.

Most of the filenames mentioned below can be modified by editing the CA.pl script.

Under some environments it may not be possible to run the CA.pl script directly (for example Win32) and the default configuration file location may be wrong. In this case the command:

perl -S CA.pl\n

can be used and the OPENSSL_CONF environment variable can be set to point to the correct path of the configuration file.

"},{"location":"man1/CA.pl/#options","title":"OPTIONS","text":""},{"location":"man1/CA.pl/#examples","title":"EXAMPLES","text":"

Create a CA hierarchy:

CA.pl -newca\n

Complete certificate creation example: create a CA, create a request, sign the request and finally create a PKCS#12 file containing it.

CA.pl -newca\nCA.pl -newreq\nCA.pl -sign\nCA.pl -pkcs12 \"My Test Certificate\"\n
"},{"location":"man1/CA.pl/#environment","title":"ENVIRONMENT","text":"

The environment variable OPENSSL may be used to specify the name of the OpenSSL program. It can be a full pathname, or a relative one.

The environment variable OPENSSL_CONFIG may be used to specify a configuration option and value to the req and ca commands invoked by this script. It's value should be the option and pathname, as in -config /path/to/conf-file.

"},{"location":"man1/CA.pl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-x509(1), openssl-ca(1), openssl-req(1), openssl-pkcs12(1), config(5)

"},{"location":"man1/CA.pl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-asn1parse/","title":"openssl-asn1parse","text":""},{"location":"man1/openssl-asn1parse/#name","title":"NAME","text":"

openssl-asn1parse - ASN.1 parsing command

"},{"location":"man1/openssl-asn1parse/#synopsis","title":"SYNOPSIS","text":"

openssl asn1parse [-help] [-inform DER|PEM|B64] [-in filename] [-out filename] [-noout] [-offset number] [-length number] [-i] [-oid filename] [-dump] [-dlimit num] [-strparse offset] [-genstr string] [-genconf file] [-strictpem] [-item name]

"},{"location":"man1/openssl-asn1parse/#description","title":"DESCRIPTION","text":"

This command is a diagnostic utility that can parse ASN.1 structures. It can also be used to extract data from ASN.1 formatted data.

"},{"location":"man1/openssl-asn1parse/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-asn1parse/#output","title":"Output","text":"

The output will typically contain lines like this:

0:d=0  hl=4 l= 681 cons: SEQUENCE\n

.....

229:d=3  hl=3 l= 141 prim: BIT STRING\n373:d=2  hl=3 l= 162 cons: cont [ 3 ]\n376:d=3  hl=3 l= 159 cons: SEQUENCE\n379:d=4  hl=2 l=  29 cons: SEQUENCE\n381:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Subject Key Identifier\n386:d=5  hl=2 l=  22 prim: OCTET STRING\n410:d=4  hl=2 l= 112 cons: SEQUENCE\n412:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Authority Key Identifier\n417:d=5  hl=2 l= 105 prim: OCTET STRING\n524:d=4  hl=2 l=  12 cons: SEQUENCE\n

.....

This example is part of a self-signed certificate. Each line starts with the offset in decimal. d=XX specifies the current depth. The depth is increased within the scope of any SET or SEQUENCE. hl=XX gives the header length (tag and length octets) of the current type. l=XX gives the length of the contents octets.

The -i option can be used to make the output more readable.

Some knowledge of the ASN.1 structure is needed to interpret the output.

In this example the BIT STRING at offset 229 is the certificate public key. The contents octets of this will contain the public key information. This can be examined using the option -strparse 229 to yield:

  0:d=0  hl=3 l= 137 cons: SEQUENCE\n  3:d=1  hl=3 l= 129 prim: INTEGER           :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897\n135:d=1  hl=2 l=   3 prim: INTEGER           :010001\n
"},{"location":"man1/openssl-asn1parse/#notes","title":"NOTES","text":"

If an OID is not part of OpenSSL's internal table it will be represented in numerical form (for example 1.2.3.4). The file passed to the -oid option allows additional OIDs to be included. Each line consists of three columns, the first column is the OID in numerical format and should be followed by white space. The second column is the \"short name\" which is a single word followed by whitespace. The final column is the rest of the line and is the \"long name\". Example:

1.2.3.4 shortName A long name

For any OID with an associated short and long name, this command will display the long name.

"},{"location":"man1/openssl-asn1parse/#examples","title":"EXAMPLES","text":"

Parse a file:

openssl asn1parse -in file.pem\n

Parse a DER file:

openssl asn1parse -inform DER -in file.der\n

Generate a simple UTF8String:

openssl asn1parse -genstr 'UTF8:Hello World'\n

Generate and write out a UTF8String, don't print parsed output:

openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der\n

Generate using a config file:

openssl asn1parse -genconf asn1.cnf -noout -out asn1.der\n

Example config file:

asn1=SEQUENCE:seq_sect\n\n[seq_sect]\n\nfield1=BOOL:TRUE\nfield2=EXP:0, UTF8:some random string\n
"},{"location":"man1/openssl-asn1parse/#bugs","title":"BUGS","text":"

There should be options to change the format of output lines. The output of some ASN.1 types is not well handled (if at all).

"},{"location":"man1/openssl-asn1parse/#see-also","title":"SEE ALSO","text":"

openssl(1), ASN1_generate_nconf(3)

"},{"location":"man1/openssl-asn1parse/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-ca/","title":"openssl-ca","text":""},{"location":"man1/openssl-ca/#name","title":"NAME","text":"

openssl-ca - sample minimal CA application

"},{"location":"man1/openssl-ca/#synopsis","title":"SYNOPSIS","text":"

openssl ca [-help] [-verbose] [-quiet] [-config filename] [-name section] [-section section] [-gencrl] [-revoke file] [-valid file] [-status serial] [-updatedb] [-crl_reason reason] [-crl_hold instruction] [-crl_compromise time] [-crl_CA_compromise time] [-crl_lastupdate date] [-crl_nextupdate date] [-crldays days] [-crlhours hours] [-crlsec seconds] [-crlexts section] [-startdate date] [-not_before date] [-enddate date] [-not_after date] [-days arg] [-md arg] [-policy arg] [-keyfile filename|uri] [-keyform DER|PEM|P12|ENGINE] [-key arg] [-passin arg] [-cert file] [-certform DER|PEM|P12] [-selfsign] [-in file] [-inform DER|] [-out file] [-notext] [-dateopt] [-outdir dir] [-infiles] [-spkac file] [-ss_cert file] [-preserveDN] [-noemailDN] [-batch] [-msie_hack] [-extensions section] [-extfile section] [-subj arg] [-utf8] [-sigopt nm:v] [-vfyopt nm:v] [-create_serial] [-rand_serial] [-multivalue-rdn] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [certreq...]"},{"location":"man1/openssl-ca/#description","title":"DESCRIPTION","text":"

This command emulates a CA application. See the WARNINGS especially when considering to use it productively.

It generates certificates bearing X.509 version 3. Unless specified otherwise, key identifier extensions are included as described in x509v3_config(5).

It can be used to sign certificate requests (CSRs) in a variety of forms and generate certificate revocation lists (CRLs). It also maintains a text database of issued certificates and their status. When signing certificates, a single request can be specified with the -in option, or multiple requests can be processed by specifying a set of certreq files after all options.

Note that there are also very lean ways of generating certificates: the req and x509 commands can be used for directly creating certificates. See openssl-req(1) and openssl-x509(1) for details.

The descriptions of the ca command options are divided into each purpose.

"},{"location":"man1/openssl-ca/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-ca/#crl-options","title":"CRL OPTIONS","text":""},{"location":"man1/openssl-ca/#configuration-file-options","title":"CONFIGURATION FILE OPTIONS","text":"

The section of the configuration file containing options for this command is found as follows: If the -name command line option is used, then it names the section to be used. Otherwise the section to be used must be named in the default_ca option of the ca section of the configuration file (or in the default section of the configuration file). Besides default_ca, the following options are read directly from the ca section: RANDFILE preserve msie_hack With the exception of RANDFILE, this is probably a bug and may change in future releases.

Many of the configuration file options are identical to command line options. Where the option is present in the configuration file and the command line the command line value is used. Where an option is described as mandatory then it must be present in the configuration file or the command line equivalent (if any) used.

"},{"location":"man1/openssl-ca/#policy-format","title":"POLICY FORMAT","text":"

The policy section consists of a set of variables corresponding to certificate DN fields. If the value is \"match\" then the field value must match the same field in the CA certificate. If the value is \"supplied\" then it must be present. If the value is \"optional\" then it may be present. Any fields not mentioned in the policy section are silently deleted, unless the -preserveDN option is set but this can be regarded more of a quirk than intended behaviour.

"},{"location":"man1/openssl-ca/#spkac-format","title":"SPKAC FORMAT","text":"

The input to the -spkac command line option is a Netscape signed public key and challenge. This will usually come from the KEYGEN tag in an HTML form to create a new private key. It is however possible to create SPKACs using openssl-spkac(1).

The file should contain the variable SPKAC set to the value of the SPKAC and also the required DN components as name value pairs. If you need to include the same component twice then it can be preceded by a number and a '.'.

When processing SPKAC format, the output is DER if the -out flag is used, but PEM format if sending to stdout or the -outdir flag is used.

"},{"location":"man1/openssl-ca/#examples","title":"EXAMPLES","text":"

Note: these examples assume that the directory structure this command assumes is already set up and the relevant files already exist. This usually involves creating a CA certificate and private key with openssl-req(1), a serial number file and an empty index file and placing them in the relevant directories.

To use the sample configuration file below the directories demoCA, demoCA/private and demoCA/newcerts would be created. The CA certificate would be copied to demoCA/cacert.pem and its private key to demoCA/private/cakey.pem. A file demoCA/serial would be created containing for example \"01\" and the empty index file demoCA/index.txt.

Sign a certificate request:

openssl ca -in req.pem -out newcert.pem\n

Sign an SM2 certificate request:

openssl ca -in sm2.csr -out sm2.crt -md sm3 \\\n        -sigopt \"distid:1234567812345678\" \\\n        -vfyopt \"distid:1234567812345678\"\n

Sign a certificate request, using CA extensions:

openssl ca -in req.pem -extensions v3_ca -out newcert.pem\n

Generate a CRL

openssl ca -gencrl -out crl.pem\n

Sign several requests:

openssl ca -infiles req1.pem req2.pem req3.pem\n

Certify a Netscape SPKAC:

openssl ca -spkac spkac.txt\n

A sample SPKAC file (the SPKAC line has been truncated for clarity):

SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5\nCN=Steve Test\nemailAddress=steve@openssl.org\n0.OU=OpenSSL Group\n1.OU=Another Group\n

A sample configuration file with the relevant sections for this command:

[ ca ]\ndefault_ca      = CA_default         #   # The default ca section\n\n[ CA_default ]\n\ndir            = ./demoCA           #   # top dir\ndatabase       = $dir/index.txt     #   # index file.\nnew_certs_dir  = $dir/newcerts      #   # new certs dir\n\ncertificate    = $dir/cacert.pem    #   # The CA cert\nserial         = $dir/serial        #   # serial no file\n#rand_serial    = yes               #   # for random serial#'s\nprivate_key    = $dir/private/cakey.pem## CA private key\n\ndefault_days   = 365                #   # how long to certify for\ndefault_crl_days= 30                #   # how long before next CRL\ndefault_md     = md5                #   # md to use\n\npolicy         = policy_any         #   # default policy\nemail_in_dn    = no                 #   # Don't add the email into cert DN\n\nname_opt       = ca_default         #   # Subject name display option\ncert_opt       = ca_default         #   # Certificate display option\ncopy_extensions = none              #   # Don't copy extensions from request\n\n[ policy_any ]\ncountryName            = supplied\nstateOrProvinceName    = optional\norganizationName       = optional\norganizationalUnitName = optional\ncommonName             = supplied\nemailAddress           = optional\n
"},{"location":"man1/openssl-ca/#files","title":"FILES","text":"

Note: the location of all files can change either by compile time options, configuration file entries, environment variables or command line options. The values below reflect the default values.

/usr/local/ssl/lib/openssl.cnf - master configuration file\n./demoCA                       - main CA directory\n./demoCA/cacert.pem            - CA certificate\n./demoCA/private/cakey.pem     - CA private key\n./demoCA/serial                - CA serial number file\n./demoCA/serial.old            - CA serial number backup file\n./demoCA/index.txt             - CA text database file\n./demoCA/index.txt.old         - CA text database backup file\n./demoCA/certs                 - certificate output file\n
"},{"location":"man1/openssl-ca/#restrictions","title":"RESTRICTIONS","text":"

The text database index file is a critical part of the process and if corrupted it can be difficult to fix. It is theoretically possible to rebuild the index file from all the issued certificates and a current CRL: however there is no option to do this.

V2 CRL features like delta CRLs are not currently supported.

Although several requests can be input and handled at once it is only possible to include one SPKAC or self-signed certificate.

"},{"location":"man1/openssl-ca/#bugs","title":"BUGS","text":"

This command is quirky and at times downright unfriendly.

The use of an in-memory text database can cause problems when large numbers of certificates are present because, as the name implies the database has to be kept in memory.

This command really needs rewriting or the required functionality exposed at either a command or interface level so that a more user-friendly replacement could handle things properly. The script CA.pl helps a little but not very much.

Any fields in a request that are not present in a policy are silently deleted. This does not happen if the -preserveDN option is used. To enforce the absence of the EMAIL field within the DN, as suggested by RFCs, regardless the contents of the request' subject the -noemailDN option can be used. The behaviour should be more friendly and configurable.

Canceling some commands by refusing to certify a certificate can create an empty file.

"},{"location":"man1/openssl-ca/#warnings","title":"WARNINGS","text":"

This command was originally meant as an example of how to do things in a CA. Its code does not have production quality. It was not supposed to be used as a full blown CA itself, nevertheless some people are using it for this purpose at least internally. When doing so, specific care should be taken to properly secure the private key(s) used for signing certificates. It is advisable to keep them in a secure HW storage such as a smart card or HSM and access them via a suitable engine or crypto provider.

This command is effectively a single user command: no locking is done on the various files and attempts to run more than one openssl ca command on the same database can have unpredictable results.

The copy_extensions option should be used with caution. If care is not taken then it can be a security risk. For example if a certificate request contains a basicConstraints extension with CA:TRUE and the copy_extensions value is set to copyall and the user does not spot this when the certificate is displayed then this will hand the requester a valid CA certificate. This situation can be avoided by setting copy_extensions to copy and including basicConstraints with CA:FALSE in the configuration file. Then if the request contains a basicConstraints extension it will be ignored.

It is advisable to also include values for other extensions such as keyUsage to prevent a request supplying its own values.

Additional restrictions can be placed on the CA certificate itself. For example if the CA certificate has:

basicConstraints = CA:TRUE, pathlen:0\n

then even if a certificate is issued with CA:TRUE it will not be valid.

"},{"location":"man1/openssl-ca/#history","title":"HISTORY","text":"

Since OpenSSL 1.1.1, the program follows RFC5280. Specifically, certificate validity period (specified by any of -startdate, -enddate and -days) and CRL last/next update time (specified by any of -crl_lastupdate, -crl_nextupdate, -crldays, -crlhours and -crlsec) will be encoded as UTCTime if the dates are earlier than year 2049 (included), and as GeneralizedTime if the dates are in year 2050 or later.

OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an improved seeding mechanism. The new seeding mechanism makes it unnecessary to define a RANDFILE for saving and restoring randomness. This option is retained mainly for compatibility reasons.

The -section option was added in OpenSSL 3.0.0.

The -multivalue-rdn option has become obsolete in OpenSSL 3.0.0 and has no effect.

The -engine option was deprecated in OpenSSL 3.0.

Since OpenSSL 3.2, generated certificates bear X.509 version 3, and key identifier extensions are included by default.

"},{"location":"man1/openssl-ca/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-req(1), openssl-spkac(1), openssl-x509(1), CA.pl(1), config(5), x509v3_config(5)

"},{"location":"man1/openssl-ca/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-ciphers/","title":"openssl-ciphers","text":""},{"location":"man1/openssl-ciphers/#name","title":"NAME","text":"

openssl-ciphers - SSL cipher display and cipher list command

"},{"location":"man1/openssl-ciphers/#synopsis","title":"SYNOPSIS","text":"

openssl ciphers [-help] [-s] [-v] [-V] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-s] [-psk] [-srp] [-stdname] [-convert name] [-ciphersuites val] [-provider name] [-provider-path path] [-propquery propq] [cipherlist]

"},{"location":"man1/openssl-ciphers/#description","title":"DESCRIPTION","text":"

This command converts textual OpenSSL cipher lists into ordered SSL cipher preference lists. It can be used to determine the appropriate cipherlist.

"},{"location":"man1/openssl-ciphers/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-ciphers/#cipher-list-format","title":"CIPHER LIST FORMAT","text":"

The cipher list consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used.

The cipher string may reference a cipher using its standard name from the IANA TLS Cipher Suites Registry (https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4).

The actual cipher string can take several different forms.

It can consist of a single cipher suite such as RC4-SHA.

It can represent a list of cipher suites containing a certain algorithm, or cipher suites of a certain type. For example SHA1 represents all ciphers suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3 algorithms.

Lists of cipher suites can be combined in a single cipher string using the + character. This is used as a logical and operation. For example SHA1+DES represents all cipher suites containing the SHA1 and the DES algorithms.

Each cipher string can be optionally preceded by the characters !, - or +.

If ! is used then the ciphers are permanently deleted from the list. The ciphers deleted can never reappear in the list even if they are explicitly stated.

If - is used then the ciphers are deleted from the list, but some or all of the ciphers can be added again by later options.

If + is used then the ciphers are moved to the end of the list. This option doesn't add any new ciphers it just moves matching existing ones.

If none of these characters is present then the string is just interpreted as a list of ciphers to be appended to the current preference list. If the list includes any ciphers already present they will be ignored: that is they will not moved to the end of the list.

The cipher string @STRENGTH can be used at any point to sort the current cipher list in order of encryption algorithm key length.

The cipher string @SECLEVEL=n can be used at any point to set the security level to n, which should be a number between zero and five, inclusive. See SSL_CTX_set_security_level(3) for a description of what each level means.

The cipher list can be prefixed with the DEFAULT keyword, which enables the default cipher list as defined below. Unlike cipher strings, this prefix may not be combined with other strings using + character. For example, DEFAULT+DES is not valid.

The content of the default list is determined at compile time and normally corresponds to ALL:!COMPLEMENTOFDEFAULT:!eNULL.

"},{"location":"man1/openssl-ciphers/#cipher-strings","title":"CIPHER STRINGS","text":"

The following is a list of all permitted cipher strings and their meanings.

"},{"location":"man1/openssl-ciphers/#cipher-suite-names","title":"CIPHER SUITE NAMES","text":"

The following lists give the standard SSL or TLS cipher suites names from the relevant specification and their OpenSSL equivalents. You can use either standard names or OpenSSL names in cipher lists, or a mix of both.

It should be noted, that several cipher suite names do not include the authentication used, e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.

"},{"location":"man1/openssl-ciphers/#ssl-v30-cipher-suites","title":"SSL v3.0 cipher suites","text":"
SSL_RSA_WITH_NULL_MD5                   NULL-MD5\nSSL_RSA_WITH_NULL_SHA                   NULL-SHA\nSSL_RSA_WITH_RC4_128_MD5                RC4-MD5\nSSL_RSA_WITH_RC4_128_SHA                RC4-SHA\nSSL_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA\nSSL_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA\n\nSSL_DH_DSS_WITH_3DES_EDE_CBC_SHA        DH-DSS-DES-CBC3-SHA\nSSL_DH_RSA_WITH_3DES_EDE_CBC_SHA        DH-RSA-DES-CBC3-SHA\nSSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA       DHE-DSS-DES-CBC3-SHA\nSSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA       DHE-RSA-DES-CBC3-SHA\n\nSSL_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5\nSSL_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA\n\nSSL_FORTEZZA_KEA_WITH_NULL_SHA          Not implemented.\nSSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA  Not implemented.\nSSL_FORTEZZA_KEA_WITH_RC4_128_SHA       Not implemented.\n
"},{"location":"man1/openssl-ciphers/#tls-v10-cipher-suites","title":"TLS v1.0 cipher suites","text":"
TLS_RSA_WITH_NULL_MD5                   NULL-MD5\nTLS_RSA_WITH_NULL_SHA                   NULL-SHA\nTLS_RSA_WITH_RC4_128_MD5                RC4-MD5\nTLS_RSA_WITH_RC4_128_SHA                RC4-SHA\nTLS_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA\nTLS_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA\n\nTLS_DH_DSS_WITH_3DES_EDE_CBC_SHA        Not implemented.\nTLS_DH_RSA_WITH_3DES_EDE_CBC_SHA        Not implemented.\nTLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA       DHE-DSS-DES-CBC3-SHA\nTLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA       DHE-RSA-DES-CBC3-SHA\n\nTLS_DH_anon_WITH_RC4_128_MD5            ADH-RC4-MD5\nTLS_DH_anon_WITH_3DES_EDE_CBC_SHA       ADH-DES-CBC3-SHA\n
"},{"location":"man1/openssl-ciphers/#aes-cipher-suites-from-rfc3268-extending-tls-v10","title":"AES cipher suites from RFC3268, extending TLS v1.0","text":"
TLS_RSA_WITH_AES_128_CBC_SHA            AES128-SHA\nTLS_RSA_WITH_AES_256_CBC_SHA            AES256-SHA\n\nTLS_DH_DSS_WITH_AES_128_CBC_SHA         DH-DSS-AES128-SHA\nTLS_DH_DSS_WITH_AES_256_CBC_SHA         DH-DSS-AES256-SHA\nTLS_DH_RSA_WITH_AES_128_CBC_SHA         DH-RSA-AES128-SHA\nTLS_DH_RSA_WITH_AES_256_CBC_SHA         DH-RSA-AES256-SHA\n\nTLS_DHE_DSS_WITH_AES_128_CBC_SHA        DHE-DSS-AES128-SHA\nTLS_DHE_DSS_WITH_AES_256_CBC_SHA        DHE-DSS-AES256-SHA\nTLS_DHE_RSA_WITH_AES_128_CBC_SHA        DHE-RSA-AES128-SHA\nTLS_DHE_RSA_WITH_AES_256_CBC_SHA        DHE-RSA-AES256-SHA\n\nTLS_DH_anon_WITH_AES_128_CBC_SHA        ADH-AES128-SHA\nTLS_DH_anon_WITH_AES_256_CBC_SHA        ADH-AES256-SHA\n
"},{"location":"man1/openssl-ciphers/#camellia-cipher-suites-from-rfc4132-extending-tls-v10","title":"Camellia cipher suites from RFC4132, extending TLS v1.0","text":"
TLS_RSA_WITH_CAMELLIA_128_CBC_SHA      CAMELLIA128-SHA\nTLS_RSA_WITH_CAMELLIA_256_CBC_SHA      CAMELLIA256-SHA\n\nTLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA   DH-DSS-CAMELLIA128-SHA\nTLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA   DH-DSS-CAMELLIA256-SHA\nTLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA   DH-RSA-CAMELLIA128-SHA\nTLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA   DH-RSA-CAMELLIA256-SHA\n\nTLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA  DHE-DSS-CAMELLIA128-SHA\nTLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA  DHE-DSS-CAMELLIA256-SHA\nTLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA  DHE-RSA-CAMELLIA128-SHA\nTLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA  DHE-RSA-CAMELLIA256-SHA\n\nTLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA  ADH-CAMELLIA128-SHA\nTLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA  ADH-CAMELLIA256-SHA\n
"},{"location":"man1/openssl-ciphers/#seed-cipher-suites-from-rfc4162-extending-tls-v10","title":"SEED cipher suites from RFC4162, extending TLS v1.0","text":"
TLS_RSA_WITH_SEED_CBC_SHA              SEED-SHA\n\nTLS_DH_DSS_WITH_SEED_CBC_SHA           DH-DSS-SEED-SHA\nTLS_DH_RSA_WITH_SEED_CBC_SHA           DH-RSA-SEED-SHA\n\nTLS_DHE_DSS_WITH_SEED_CBC_SHA          DHE-DSS-SEED-SHA\nTLS_DHE_RSA_WITH_SEED_CBC_SHA          DHE-RSA-SEED-SHA\n\nTLS_DH_anon_WITH_SEED_CBC_SHA          ADH-SEED-SHA\n
"},{"location":"man1/openssl-ciphers/#gost-cipher-suites-from-draft-chudov-cryptopro-cptls-extending-tls-v10","title":"GOST cipher suites from draft-chudov-cryptopro-cptls, extending TLS v1.0","text":"

Note: these ciphers require an engine which including GOST cryptographic algorithms, such as the gost engine, which isn't part of the OpenSSL distribution.

TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89\nTLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89\nTLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94\nTLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94\n
"},{"location":"man1/openssl-ciphers/#gost-cipher-suites-extending-tls-v12","title":"GOST cipher suites, extending TLS v1.2","text":"

Note: these ciphers require an engine which including GOST cryptographic algorithms, such as the gost engine, which isn't part of the OpenSSL distribution.

TLS_GOSTR341112_256_WITH_28147_CNT_IMIT GOST2012-GOST8912-GOST8912\nTLS_GOSTR341112_256_WITH_NULL_GOSTR3411 GOST2012-NULL-GOST12\n

Note: GOST2012-GOST8912-GOST8912 is an alias for two ciphers ID old LEGACY-GOST2012-GOST8912-GOST8912 and new IANA-GOST2012-GOST8912-GOST8912

"},{"location":"man1/openssl-ciphers/#additional-export-1024-and-other-cipher-suites","title":"Additional Export 1024 and other cipher suites","text":"

Note: these ciphers can also be used in SSL v3.

TLS_DHE_DSS_WITH_RC4_128_SHA            DHE-DSS-RC4-SHA\n
"},{"location":"man1/openssl-ciphers/#elliptic-curve-cipher-suites","title":"Elliptic curve cipher suites","text":"
TLS_ECDHE_RSA_WITH_NULL_SHA             ECDHE-RSA-NULL-SHA\nTLS_ECDHE_RSA_WITH_RC4_128_SHA          ECDHE-RSA-RC4-SHA\nTLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA     ECDHE-RSA-DES-CBC3-SHA\nTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA      ECDHE-RSA-AES128-SHA\nTLS_ECDHE_RSA_WITH_AES_256_CBC_SHA      ECDHE-RSA-AES256-SHA\n\nTLS_ECDHE_ECDSA_WITH_NULL_SHA           ECDHE-ECDSA-NULL-SHA\nTLS_ECDHE_ECDSA_WITH_RC4_128_SHA        ECDHE-ECDSA-RC4-SHA\nTLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA   ECDHE-ECDSA-DES-CBC3-SHA\nTLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA    ECDHE-ECDSA-AES128-SHA\nTLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA    ECDHE-ECDSA-AES256-SHA\n\nTLS_ECDH_anon_WITH_NULL_SHA             AECDH-NULL-SHA\nTLS_ECDH_anon_WITH_RC4_128_SHA          AECDH-RC4-SHA\nTLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA     AECDH-DES-CBC3-SHA\nTLS_ECDH_anon_WITH_AES_128_CBC_SHA      AECDH-AES128-SHA\nTLS_ECDH_anon_WITH_AES_256_CBC_SHA      AECDH-AES256-SHA\n
"},{"location":"man1/openssl-ciphers/#tls-v12-cipher-suites","title":"TLS v1.2 cipher suites","text":"
TLS_RSA_WITH_NULL_SHA256                  NULL-SHA256\n\nTLS_RSA_WITH_AES_128_CBC_SHA256           AES128-SHA256\nTLS_RSA_WITH_AES_256_CBC_SHA256           AES256-SHA256\nTLS_RSA_WITH_AES_128_GCM_SHA256           AES128-GCM-SHA256\nTLS_RSA_WITH_AES_256_GCM_SHA384           AES256-GCM-SHA384\n\nTLS_DH_RSA_WITH_AES_128_CBC_SHA256        DH-RSA-AES128-SHA256\nTLS_DH_RSA_WITH_AES_256_CBC_SHA256        DH-RSA-AES256-SHA256\nTLS_DH_RSA_WITH_AES_128_GCM_SHA256        DH-RSA-AES128-GCM-SHA256\nTLS_DH_RSA_WITH_AES_256_GCM_SHA384        DH-RSA-AES256-GCM-SHA384\n\nTLS_DH_DSS_WITH_AES_128_CBC_SHA256        DH-DSS-AES128-SHA256\nTLS_DH_DSS_WITH_AES_256_CBC_SHA256        DH-DSS-AES256-SHA256\nTLS_DH_DSS_WITH_AES_128_GCM_SHA256        DH-DSS-AES128-GCM-SHA256\nTLS_DH_DSS_WITH_AES_256_GCM_SHA384        DH-DSS-AES256-GCM-SHA384\n\nTLS_DHE_RSA_WITH_AES_128_CBC_SHA256       DHE-RSA-AES128-SHA256\nTLS_DHE_RSA_WITH_AES_256_CBC_SHA256       DHE-RSA-AES256-SHA256\nTLS_DHE_RSA_WITH_AES_128_GCM_SHA256       DHE-RSA-AES128-GCM-SHA256\nTLS_DHE_RSA_WITH_AES_256_GCM_SHA384       DHE-RSA-AES256-GCM-SHA384\n\nTLS_DHE_DSS_WITH_AES_128_CBC_SHA256       DHE-DSS-AES128-SHA256\nTLS_DHE_DSS_WITH_AES_256_CBC_SHA256       DHE-DSS-AES256-SHA256\nTLS_DHE_DSS_WITH_AES_128_GCM_SHA256       DHE-DSS-AES128-GCM-SHA256\nTLS_DHE_DSS_WITH_AES_256_GCM_SHA384       DHE-DSS-AES256-GCM-SHA384\n\nTLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256     ECDHE-RSA-AES128-SHA256\nTLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384     ECDHE-RSA-AES256-SHA384\nTLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256     ECDHE-RSA-AES128-GCM-SHA256\nTLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384     ECDHE-RSA-AES256-GCM-SHA384\n\nTLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256   ECDHE-ECDSA-AES128-SHA256\nTLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384   ECDHE-ECDSA-AES256-SHA384\nTLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256   ECDHE-ECDSA-AES128-GCM-SHA256\nTLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384   ECDHE-ECDSA-AES256-GCM-SHA384\n\nTLS_DH_anon_WITH_AES_128_CBC_SHA256       ADH-AES128-SHA256\nTLS_DH_anon_WITH_AES_256_CBC_SHA256       ADH-AES256-SHA256\nTLS_DH_anon_WITH_AES_128_GCM_SHA256       ADH-AES128-GCM-SHA256\nTLS_DH_anon_WITH_AES_256_GCM_SHA384       ADH-AES256-GCM-SHA384\n\nRSA_WITH_AES_128_CCM                      AES128-CCM\nRSA_WITH_AES_256_CCM                      AES256-CCM\nDHE_RSA_WITH_AES_128_CCM                  DHE-RSA-AES128-CCM\nDHE_RSA_WITH_AES_256_CCM                  DHE-RSA-AES256-CCM\nRSA_WITH_AES_128_CCM_8                    AES128-CCM8\nRSA_WITH_AES_256_CCM_8                    AES256-CCM8\nDHE_RSA_WITH_AES_128_CCM_8                DHE-RSA-AES128-CCM8\nDHE_RSA_WITH_AES_256_CCM_8                DHE-RSA-AES256-CCM8\nECDHE_ECDSA_WITH_AES_128_CCM              ECDHE-ECDSA-AES128-CCM\nECDHE_ECDSA_WITH_AES_256_CCM              ECDHE-ECDSA-AES256-CCM\nECDHE_ECDSA_WITH_AES_128_CCM_8            ECDHE-ECDSA-AES128-CCM8\nECDHE_ECDSA_WITH_AES_256_CCM_8            ECDHE-ECDSA-AES256-CCM8\n
"},{"location":"man1/openssl-ciphers/#aria-cipher-suites-from-rfc6209-extending-tls-v12","title":"ARIA cipher suites from RFC6209, extending TLS v1.2","text":"

Note: the CBC modes mentioned in this RFC are not supported.

TLS_RSA_WITH_ARIA_128_GCM_SHA256          ARIA128-GCM-SHA256\nTLS_RSA_WITH_ARIA_256_GCM_SHA384          ARIA256-GCM-SHA384\nTLS_DHE_RSA_WITH_ARIA_128_GCM_SHA256      DHE-RSA-ARIA128-GCM-SHA256\nTLS_DHE_RSA_WITH_ARIA_256_GCM_SHA384      DHE-RSA-ARIA256-GCM-SHA384\nTLS_DHE_DSS_WITH_ARIA_128_GCM_SHA256      DHE-DSS-ARIA128-GCM-SHA256\nTLS_DHE_DSS_WITH_ARIA_256_GCM_SHA384      DHE-DSS-ARIA256-GCM-SHA384\nTLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256  ECDHE-ECDSA-ARIA128-GCM-SHA256\nTLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384  ECDHE-ECDSA-ARIA256-GCM-SHA384\nTLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256    ECDHE-ARIA128-GCM-SHA256\nTLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384    ECDHE-ARIA256-GCM-SHA384\nTLS_PSK_WITH_ARIA_128_GCM_SHA256          PSK-ARIA128-GCM-SHA256\nTLS_PSK_WITH_ARIA_256_GCM_SHA384          PSK-ARIA256-GCM-SHA384\nTLS_DHE_PSK_WITH_ARIA_128_GCM_SHA256      DHE-PSK-ARIA128-GCM-SHA256\nTLS_DHE_PSK_WITH_ARIA_256_GCM_SHA384      DHE-PSK-ARIA256-GCM-SHA384\nTLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256      RSA-PSK-ARIA128-GCM-SHA256\nTLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384      RSA-PSK-ARIA256-GCM-SHA384\n
"},{"location":"man1/openssl-ciphers/#camellia-hmac-based-cipher-suites-from-rfc6367-extending-tls-v12","title":"Camellia HMAC-Based cipher suites from RFC6367, extending TLS v1.2","text":"
TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256\nTLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384\nTLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256   ECDHE-RSA-CAMELLIA128-SHA256\nTLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384   ECDHE-RSA-CAMELLIA256-SHA384\n
"},{"location":"man1/openssl-ciphers/#pre-shared-keying-psk-cipher-suites","title":"Pre-shared keying (PSK) cipher suites","text":"
PSK_WITH_NULL_SHA                         PSK-NULL-SHA\nDHE_PSK_WITH_NULL_SHA                     DHE-PSK-NULL-SHA\nRSA_PSK_WITH_NULL_SHA                     RSA-PSK-NULL-SHA\n\nPSK_WITH_RC4_128_SHA                      PSK-RC4-SHA\nPSK_WITH_3DES_EDE_CBC_SHA                 PSK-3DES-EDE-CBC-SHA\nPSK_WITH_AES_128_CBC_SHA                  PSK-AES128-CBC-SHA\nPSK_WITH_AES_256_CBC_SHA                  PSK-AES256-CBC-SHA\n\nDHE_PSK_WITH_RC4_128_SHA                  DHE-PSK-RC4-SHA\nDHE_PSK_WITH_3DES_EDE_CBC_SHA             DHE-PSK-3DES-EDE-CBC-SHA\nDHE_PSK_WITH_AES_128_CBC_SHA              DHE-PSK-AES128-CBC-SHA\nDHE_PSK_WITH_AES_256_CBC_SHA              DHE-PSK-AES256-CBC-SHA\n\nRSA_PSK_WITH_RC4_128_SHA                  RSA-PSK-RC4-SHA\nRSA_PSK_WITH_3DES_EDE_CBC_SHA             RSA-PSK-3DES-EDE-CBC-SHA\nRSA_PSK_WITH_AES_128_CBC_SHA              RSA-PSK-AES128-CBC-SHA\nRSA_PSK_WITH_AES_256_CBC_SHA              RSA-PSK-AES256-CBC-SHA\n\nPSK_WITH_AES_128_GCM_SHA256               PSK-AES128-GCM-SHA256\nPSK_WITH_AES_256_GCM_SHA384               PSK-AES256-GCM-SHA384\nDHE_PSK_WITH_AES_128_GCM_SHA256           DHE-PSK-AES128-GCM-SHA256\nDHE_PSK_WITH_AES_256_GCM_SHA384           DHE-PSK-AES256-GCM-SHA384\nRSA_PSK_WITH_AES_128_GCM_SHA256           RSA-PSK-AES128-GCM-SHA256\nRSA_PSK_WITH_AES_256_GCM_SHA384           RSA-PSK-AES256-GCM-SHA384\n\nPSK_WITH_AES_128_CBC_SHA256               PSK-AES128-CBC-SHA256\nPSK_WITH_AES_256_CBC_SHA384               PSK-AES256-CBC-SHA384\nPSK_WITH_NULL_SHA256                      PSK-NULL-SHA256\nPSK_WITH_NULL_SHA384                      PSK-NULL-SHA384\nDHE_PSK_WITH_AES_128_CBC_SHA256           DHE-PSK-AES128-CBC-SHA256\nDHE_PSK_WITH_AES_256_CBC_SHA384           DHE-PSK-AES256-CBC-SHA384\nDHE_PSK_WITH_NULL_SHA256                  DHE-PSK-NULL-SHA256\nDHE_PSK_WITH_NULL_SHA384                  DHE-PSK-NULL-SHA384\nRSA_PSK_WITH_AES_128_CBC_SHA256           RSA-PSK-AES128-CBC-SHA256\nRSA_PSK_WITH_AES_256_CBC_SHA384           RSA-PSK-AES256-CBC-SHA384\nRSA_PSK_WITH_NULL_SHA256                  RSA-PSK-NULL-SHA256\nRSA_PSK_WITH_NULL_SHA384                  RSA-PSK-NULL-SHA384\nPSK_WITH_AES_128_GCM_SHA256               PSK-AES128-GCM-SHA256\nPSK_WITH_AES_256_GCM_SHA384               PSK-AES256-GCM-SHA384\n\nECDHE_PSK_WITH_RC4_128_SHA                ECDHE-PSK-RC4-SHA\nECDHE_PSK_WITH_3DES_EDE_CBC_SHA           ECDHE-PSK-3DES-EDE-CBC-SHA\nECDHE_PSK_WITH_AES_128_CBC_SHA            ECDHE-PSK-AES128-CBC-SHA\nECDHE_PSK_WITH_AES_256_CBC_SHA            ECDHE-PSK-AES256-CBC-SHA\nECDHE_PSK_WITH_AES_128_CBC_SHA256         ECDHE-PSK-AES128-CBC-SHA256\nECDHE_PSK_WITH_AES_256_CBC_SHA384         ECDHE-PSK-AES256-CBC-SHA384\nECDHE_PSK_WITH_NULL_SHA                   ECDHE-PSK-NULL-SHA\nECDHE_PSK_WITH_NULL_SHA256                ECDHE-PSK-NULL-SHA256\nECDHE_PSK_WITH_NULL_SHA384                ECDHE-PSK-NULL-SHA384\n\nPSK_WITH_CAMELLIA_128_CBC_SHA256          PSK-CAMELLIA128-SHA256\nPSK_WITH_CAMELLIA_256_CBC_SHA384          PSK-CAMELLIA256-SHA384\n\nDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256      DHE-PSK-CAMELLIA128-SHA256\nDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384      DHE-PSK-CAMELLIA256-SHA384\n\nRSA_PSK_WITH_CAMELLIA_128_CBC_SHA256      RSA-PSK-CAMELLIA128-SHA256\nRSA_PSK_WITH_CAMELLIA_256_CBC_SHA384      RSA-PSK-CAMELLIA256-SHA384\n\nECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256    ECDHE-PSK-CAMELLIA128-SHA256\nECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384    ECDHE-PSK-CAMELLIA256-SHA384\n\nPSK_WITH_AES_128_CCM                      PSK-AES128-CCM\nPSK_WITH_AES_256_CCM                      PSK-AES256-CCM\nDHE_PSK_WITH_AES_128_CCM                  DHE-PSK-AES128-CCM\nDHE_PSK_WITH_AES_256_CCM                  DHE-PSK-AES256-CCM\nPSK_WITH_AES_128_CCM_8                    PSK-AES128-CCM8\nPSK_WITH_AES_256_CCM_8                    PSK-AES256-CCM8\nDHE_PSK_WITH_AES_128_CCM_8                DHE-PSK-AES128-CCM8\nDHE_PSK_WITH_AES_256_CCM_8                DHE-PSK-AES256-CCM8\n
"},{"location":"man1/openssl-ciphers/#chacha20-poly1305-cipher-suites-extending-tls-v12","title":"ChaCha20-Poly1305 cipher suites, extending TLS v1.2","text":"
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256      ECDHE-RSA-CHACHA20-POLY1305\nTLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256    ECDHE-ECDSA-CHACHA20-POLY1305\nTLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256        DHE-RSA-CHACHA20-POLY1305\nTLS_PSK_WITH_CHACHA20_POLY1305_SHA256            PSK-CHACHA20-POLY1305\nTLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256      ECDHE-PSK-CHACHA20-POLY1305\nTLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256        DHE-PSK-CHACHA20-POLY1305\nTLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256        RSA-PSK-CHACHA20-POLY1305\n
"},{"location":"man1/openssl-ciphers/#tls-v13-cipher-suites","title":"TLS v1.3 cipher suites","text":"
TLS_AES_128_GCM_SHA256                     TLS_AES_128_GCM_SHA256\nTLS_AES_256_GCM_SHA384                     TLS_AES_256_GCM_SHA384\nTLS_CHACHA20_POLY1305_SHA256               TLS_CHACHA20_POLY1305_SHA256\nTLS_AES_128_CCM_SHA256                     TLS_AES_128_CCM_SHA256\nTLS_AES_128_CCM_8_SHA256                   TLS_AES_128_CCM_8_SHA256\n
"},{"location":"man1/openssl-ciphers/#tls-v13-integrity-only-cipher-suites-according-to-rfc-9150","title":"TLS v1.3 integrity-only cipher suites according to RFC 9150","text":"
TLS_SHA256_SHA256          TLS_SHA256_SHA256\nTLS_SHA384_SHA384          TLS_SHA384_SHA384\n

Note: these ciphers are purely HMAC based and do not provide any confidentiality and thus are disabled by default. These ciphers are only available at security level 0.

"},{"location":"man1/openssl-ciphers/#older-names-used-by-openssl","title":"Older names used by OpenSSL","text":"

The following names are accepted by older releases:

SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA    EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA)\nSSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA    EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA)\n
"},{"location":"man1/openssl-ciphers/#notes","title":"NOTES","text":"

Some compiled versions of OpenSSL may not include all the ciphers listed here because some ciphers were excluded at compile time.

"},{"location":"man1/openssl-ciphers/#examples","title":"EXAMPLES","text":"

Verbose listing of all OpenSSL ciphers including NULL ciphers:

openssl ciphers -v 'ALL:eNULL'\n

Include all ciphers except NULL and anonymous DH then sort by strength:

openssl ciphers -v 'ALL:!ADH:@STRENGTH'\n

Include all ciphers except ones with no encryption (eNULL) or no authentication (aNULL):

openssl ciphers -v 'ALL:!aNULL'\n

Include only 3DES ciphers and then place RSA ciphers last:

openssl ciphers -v '3DES:+RSA'\n

Include all RC4 ciphers but leave out those without authentication:

openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'\n

Include all ciphers with RSA authentication but leave out ciphers without encryption.

openssl ciphers -v 'RSA:!COMPLEMENTOFALL'\n

Set security level to 2 and display all ciphers consistent with level 2:

openssl ciphers -s -v 'ALL:@SECLEVEL=2'\n
"},{"location":"man1/openssl-ciphers/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-s_client(1), openssl-s_server(1), ssl(7)

"},{"location":"man1/openssl-ciphers/#history","title":"HISTORY","text":"

The -V option was added in OpenSSL 1.0.0.

The -stdname is only available if OpenSSL is built with tracing enabled (enable-ssl-trace argument to Configure) before OpenSSL 1.1.1.

The -convert option was added in OpenSSL 1.1.1.

Support for standard IANA names in cipher lists was added in OpenSSL 3.2.0.

The support for TLS v1.3 integrity-only cipher suites was added in OpenSSL 3.4.

"},{"location":"man1/openssl-ciphers/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-cmds/","title":"openssl-cmds","text":""},{"location":"man1/openssl-cmds/#name","title":"NAME","text":"

asn1parse, ca, ciphers, cmp, cms, crl, crl2pkcs7, dgst, dhparam, dsa, dsaparam, ec, ecparam, enc, engine, errstr, gendsa, genpkey, genrsa, info, kdf, mac, nseq, ocsp, passwd, pkcs12, pkcs7, pkcs8, pkey, pkeyparam, pkeyutl, prime, rand, rehash, req, rsa, rsautl, s_client, s_server, s_time, sess_id, smime, speed, spkac, srp, storeutl, ts, verify, version, x509 - OpenSSL application commands

"},{"location":"man1/openssl-cmds/#synopsis","title":"SYNOPSIS","text":"

openssl cmd -help | [-option | -option arg] ... [arg] ...

"},{"location":"man1/openssl-cmds/#description","title":"DESCRIPTION","text":"

Every cmd listed above is a (sub-)command of the openssl(1) application. It has its own detailed manual page at openssl-cmd(1). For example, to view the manual page for the openssl dgst command, type man openssl-dgst.

"},{"location":"man1/openssl-cmds/#options","title":"OPTIONS","text":"

Among others, every subcommand has a help option.

"},{"location":"man1/openssl-cmds/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-asn1parse(1), openssl-ca(1), openssl-ciphers(1), openssl-cmp(1), openssl-cms(1), openssl-crl(1), openssl-crl2pkcs7(1), openssl-dgst(1), openssl-dhparam(1), openssl-dsa(1), openssl-dsaparam(1), openssl-ec(1), openssl-ecparam(1), openssl-enc(1), openssl-engine(1), openssl-errstr(1), openssl-gendsa(1), openssl-genpkey(1), openssl-genrsa(1), openssl-info(1), openssl-kdf(1), openssl-mac(1), openssl-nseq(1), openssl-ocsp(1), openssl-passwd(1), openssl-pkcs12(1), openssl-pkcs7(1), openssl-pkcs8(1), openssl-pkey(1), openssl-pkeyparam(1), openssl-pkeyutl(1), openssl-prime(1), openssl-rand(1), openssl-rehash(1), openssl-req(1), openssl-rsa(1), openssl-rsautl(1), openssl-s_client(1), openssl-s_server(1), openssl-s_time(1), openssl-sess_id(1), openssl-smime(1), openssl-speed(1), openssl-spkac(1), openssl-srp(1), openssl-storeutl(1), openssl-ts(1), openssl-verify(1), openssl-version(1), openssl-x509(1),

"},{"location":"man1/openssl-cmds/#history","title":"HISTORY","text":"

Initially, the manual page entry for the openssl _cmd_ command used to be available at cmd(1). Later, the alias openssl-cmd(1) was introduced, which made it easier to group the openssl commands using the apropos(1) command or the shell's tab completion.

In order to reduce cluttering of the global manual page namespace, the manual page entries without the 'openssl-' prefix have been deprecated in OpenSSL 3.0 and will be removed in OpenSSL 4.0.

"},{"location":"man1/openssl-cmds/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-cmp/","title":"openssl-cmp","text":""},{"location":"man1/openssl-cmp/#name","title":"NAME","text":"

openssl-cmp - Certificate Management Protocol (CMP, RFC 4210) application

"},{"location":"man1/openssl-cmp/#synopsis","title":"SYNOPSIS","text":"

openssl cmp [-help] [-config filename] [-section names] [-verbosity level]

Generic message options:

[-cmd ir|cr|kur|p10cr|rr|genm] [-infotype name] [-profile name] [-geninfo values] [-template filename] [-keyspec filename]

Certificate enrollment options:

[-newkey filename|uri] [-newkeypass arg] [-subject name] [-days number] [-reqexts name] [-sans spec] [-san_nodefault] [-policies name] [-policy_oids names] [-policy_oids_critical] [-popo number] [-csr filename] [-out_trusted filenames|uris] [-implicit_confirm] [-disable_confirm] [-certout filename] [-chainout filename]

Certificate enrollment and revocation options:

[-oldcert filename|uri] [-issuer name] [-serial number] [-revreason number]

Message transfer options:

[-server [http[s]://][userinfo@]host[:port][/path][?query][#fragment]] [-proxy [http[s]://][userinfo@]host[:port][/path][?query][#fragment]] [-no_proxy addresses] [-recipient name] [-path remote_path] [-keep_alive value] [-msg_timeout seconds] [-total_timeout seconds]

Server authentication options:

[-trusted filenames|uris] [-untrusted filenames|uris] [-srvcert filename|uri] [-expect_sender name] [-ignore_keyusage] [-unprotected_errors] [-no_cache_extracerts] [-srvcertout filename] [-extracertsout filename] [-cacertsout filename] [-oldwithold filename] [-newwithnew filename] [-newwithold filename] [-oldwithnew filename] [-crlcert filename] [-oldcrl filename] [-crlout filename]

Client authentication and protection options:

[-ref value] [-secret arg] [-cert filename|uri] [-own_trusted filenames|uris] [-key filename|uri] [-keypass arg] [-digest name] [-mac name] [-extracerts filenames|uris] [-unprotected_requests]

Credentials format options:

[-certform PEM|DER] [-crlform PEM|DER] [-keyform PEM|DER|P12|ENGINE] [-otherpass arg] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

Random state options:

[-rand files] [-writerand file]

TLS connection options:

[-tls_used] [-tls_cert filename|uri] [-tls_key filename|uri] [-tls_keypass arg] [-tls_extra filenames|uris] [-tls_trusted filenames|uris] [-tls_host name]

Client-side debugging options:

[-batch] [-repeat number] [-reqin filenames] [-reqin_new_tid] [-reqout filenames] [-reqout_only filename] [-rspin filenames] [-rspout filenames] [-use_mock_srv]

Mock server options:

[-port number] [-max_msgs number] [-srv_ref value] [-srv_secret arg] [-srv_cert filename|uri] [-srv_key filename|uri] [-srv_keypass arg] [-srv_trusted filenames|uris] [-srv_untrusted filenames|uris] [-ref_cert filename|uri] [-rsp_cert filename|uri] [-rsp_crl filename|uri] [-rsp_extracerts filenames|uris] [-rsp_capubs filenames|uris] [-rsp_newwithnew filename|uri] [-rsp_newwithold filename|uri] [-rsp_oldwithnew filename|uri] [-poll_count number] [-check_after number] [-grant_implicitconf] [-pkistatus number] [-failure number] [-failurebits number] [-statusstring arg] [-send_error] [-send_unprotected] [-send_unprot_err] [-accept_unprotected] [-accept_unprot_err] [-accept_raverified]

Certificate verification options, for both CMP and TLS:

[-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks]

"},{"location":"man1/openssl-cmp/#description","title":"DESCRIPTION","text":"

The cmp command is a client implementation for the Certificate Management Protocol (CMP) as defined in RFC4210. It can be used to request certificates from a CA server, update their certificates, request certificates to be revoked, and perform other types of CMP requests.

"},{"location":"man1/openssl-cmp/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-cmp/#generic-message-options","title":"Generic message options","text":""},{"location":"man1/openssl-cmp/#certificate-enrollment-options","title":"Certificate enrollment options","text":""},{"location":"man1/openssl-cmp/#certificate-enrollment-and-revocation-options","title":"Certificate enrollment and revocation options","text":""},{"location":"man1/openssl-cmp/#message-transfer-options","title":"Message transfer options","text":""},{"location":"man1/openssl-cmp/#server-authentication-options","title":"Server authentication options","text":""},{"location":"man1/openssl-cmp/#client-authentication-options","title":"Client authentication options","text":""},{"location":"man1/openssl-cmp/#credentials-format-options","title":"Credentials format options","text":""},{"location":"man1/openssl-cmp/#provider-options","title":"Provider options","text":""},{"location":"man1/openssl-cmp/#random-state-options","title":"Random state options","text":""},{"location":"man1/openssl-cmp/#tls-connection-options","title":"TLS connection options","text":""},{"location":"man1/openssl-cmp/#client-side-options-for-debugging-and-offline-scenarios","title":"Client-side options for debugging and offline scenarios","text":""},{"location":"man1/openssl-cmp/#mock-server-options","title":"Mock server options","text":""},{"location":"man1/openssl-cmp/#certificate-verification-options-for-both-cmp-and-tls","title":"Certificate verification options, for both CMP and TLS","text":""},{"location":"man1/openssl-cmp/#notes","title":"NOTES","text":"

When a client obtains, from a CMP server, CA certificates that it is going to trust, for instance via the caPubs field of a certificate response or using general messages with infoType caCerts or rootCaCert, authentication of the CMP server is particularly critical. So special care must be taken setting up server authentication using -trusted and related options for certificate-based authentication or -secret for MAC-based protection. If authentication is certificate-based, the -srvcertout option should be used to obtain the validated server certificate and perform an authorization check based on it.

When setting up CMP configurations and experimenting with enrollment options typically various errors occur until the configuration is correct and complete. When the CMP server reports an error the client will by default check the protection of the CMP response message. Yet some CMP services tend not to protect negative responses. In this case the client will reject them, and thus their contents are not shown although they usually contain hints that would be helpful for diagnostics. For assisting in such cases the CMP client offers a workaround via the -unprotected_errors option, which allows accepting such negative messages.

If OpenSSL was built with trace support enabled (e.g., ./config enable-trace) and the environment variable OPENSSL_TRACE includes HTTP, the requests and the response headers transferred via HTTP are printed.

"},{"location":"man1/openssl-cmp/#examples","title":"EXAMPLES","text":""},{"location":"man1/openssl-cmp/#simple-examples-using-the-default-openssl-configuration-file","title":"Simple examples using the default OpenSSL configuration file","text":"

This CMP client implementation comes with demonstrative CMP sections in the example configuration file openssl/apps/openssl.cnf, which can be used to interact conveniently with the Insta Demo CA.

In order to enroll an initial certificate from that CA it is sufficient to issue the following shell commands.

export OPENSSL_CONF=/path/to/openssl/apps/openssl.cnf\n\nopenssl genrsa -out insta.priv.pem\nopenssl cmp -section insta\n

This should produce the file insta.cert.pem containing a new certificate for the private key held in insta.priv.pem. It can be viewed using, e.g.,

openssl x509 -noout -text -in insta.cert.pem\n

In case the network setup requires using an HTTP proxy it may be given as usual via the environment variable http_proxy or via the -proxy option in the configuration file or the CMP command-line argument -proxy, for example

-proxy http://192.168.1.1:8080\n

In the Insta Demo CA scenario both clients and the server may use the pre-shared secret insta and the reference value 3078 to authenticate to each other.

Alternatively, CMP messages may be protected in signature-based manner, where the trust anchor in this case is insta.ca.crt and the client may use any certificate already obtained from that CA, as specified in the [signature] section of the example configuration. This can be used in combination with the [insta] section simply by

openssl cmp -section insta,signature\n

By default the CMP IR message type is used, yet CR works equally here. This may be specified directly at the command line:

openssl cmp -section insta -cmd cr\n

or by referencing in addition the [cr] section of the example configuration:

openssl cmp -section insta,cr\n

In order to update the enrolled certificate one may call

openssl cmp -section insta,kur\n

using MAC-based protection with PBM or

openssl cmp -section insta,kur,signature\n

using signature-based protection.

In a similar way any previously enrolled certificate may be revoked by

openssl cmp -section insta,rr -trusted insta.ca.crt\n

or

openssl cmp -section insta,rr,signature\n

Many more options can be given in the configuration file and/or on the command line. For instance, the -reqexts CLI option may refer to a section in the configuration file defining X.509 extensions to use in certificate requests, such as v3_req in openssl/apps/openssl.cnf:

openssl cmp -section insta,cr -reqexts v3_req\n
"},{"location":"man1/openssl-cmp/#certificate-enrollment","title":"Certificate enrollment","text":"

The following examples do not make use of a configuration file at first. They assume that a CMP server can be contacted on the local TCP port 80 and accepts requests under the alias /pkix/.

For enrolling its very first certificate the client generates a client key and sends an initial request message to the local CMP server using a pre-shared secret key for mutual authentication. In this example the client does not have the CA certificate yet, so we specify the name of the CA with the -recipient option and save any CA certificates that we may receive in the capubs.pem file.

In below command line usage examples the \\ at line ends is used just for formatting; each of the command invocations should be on a single line.

openssl genrsa -out cl_key.pem\nopenssl cmp -cmd ir -server 127.0.0.1:80/pkix/ -recipient \"/CN=CMPserver\" \\\n  -ref 1234 -secret pass:1234-5678 \\\n  -newkey cl_key.pem -subject \"/CN=MyName\" \\\n  -cacertsout capubs.pem -certout cl_cert.pem\n
"},{"location":"man1/openssl-cmp/#certificate-update","title":"Certificate update","text":"

Then, when the client certificate and its related key pair needs to be updated, the client can send a key update request taking the certs in capubs.pem as trusted for authenticating the server and using the previous cert and key for its own authentication. Then it can start using the new cert and key.

openssl genrsa -out cl_key_new.pem\nopenssl cmp -cmd kur -server 127.0.0.1:80/pkix/ \\\n  -trusted capubs.pem \\\n  -cert cl_cert.pem -key cl_key.pem \\\n  -newkey cl_key_new.pem -certout cl_cert.pem\ncp cl_key_new.pem cl_key.pem\n

This command sequence can be repeated as often as needed.

"},{"location":"man1/openssl-cmp/#requesting-information-from-cmp-server","title":"Requesting information from CMP server","text":"

Requesting \"all relevant information\" with an empty General Message. This prints information about all received ITAV infoTypes to stdout.

openssl cmp -cmd genm -server 127.0.0.1/pkix/ -recipient \"/CN=CMPserver\" \\\n  -ref 1234 -secret pass:1234-5678\n
"},{"location":"man1/openssl-cmp/#using-a-custom-configuration-file","title":"Using a custom configuration file","text":"

For CMP client invocations, in particular for certificate enrollment, usually many parameters need to be set, which is tedious and error-prone to do on the command line. Therefore, the client offers the possibility to read options from sections of the OpenSSL config file, usually called openssl.cnf. The values found there can still be extended and even overridden by any subsequently loaded sections and on the command line.

After including in the configuration file the following sections:

[cmp]\nserver = 127.0.0.1\npath = pkix/\ntrusted = capubs.pem\ncert = cl_cert.pem\nkey = cl_key.pem\nnewkey = cl_key.pem\ncertout = cl_cert.pem\n\n[init]\nrecipient = \"/CN=CMPserver\"\ntrusted =\ncert =\nkey =\nref = 1234\nsecret = pass:1234-5678-1234-567\nsubject = \"/CN=MyName\"\ncacertsout = capubs.pem\n

the above enrollment transactions reduce to

openssl cmp -section cmp,init\nopenssl cmp -cmd kur -newkey cl_key_new.pem\n

and the above transaction using a general message reduces to

openssl cmp -section cmp,init -cmd genm\n
"},{"location":"man1/openssl-cmp/#see-also","title":"SEE ALSO","text":"

openssl-genrsa(1), openssl-ecparam(1), openssl-list(1), openssl-req(1), openssl-x509(1), x509v3_config(5)

"},{"location":"man1/openssl-cmp/#history","title":"HISTORY","text":"

The cmp application was added in OpenSSL 3.0.

The -engine option was deprecated in OpenSSL 3.0.

The -profile option was added in OpenSSL 3.3.

-crlcert, -oldcrl, -crlout, -crlform and -rsp_crl options were added in OpenSSL 3.4.

"},{"location":"man1/openssl-cmp/#copyright","title":"COPYRIGHT","text":"

Copyright 2007-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-cms/","title":"openssl-cms","text":""},{"location":"man1/openssl-cms/#name","title":"NAME","text":"

openssl-cms - CMS command

"},{"location":"man1/openssl-cms/#synopsis","title":"SYNOPSIS","text":"

openssl cms [-help]

General options:

[-in filename] [-out filename] [-config configfile]

Operation options:

[-encrypt] [-decrypt] [-sign] [-verify] [-resign] [-sign_receipt] [-verify_receipt receipt] [-digest digest] [-digest_create] [-digest_verify] [-compress] [-uncompress] [-EncryptedData_encrypt] [-EncryptedData_decrypt] [-data_create] [-data_out] [-cmsout]

File format options:

[-inform DER|PEM|SMIME] [-outform DER|PEM|SMIME] [-rctform DER|PEM|SMIME] [-stream] [-indef] [-noindef] [-binary] [-crlfeol] [-asciicrlf]

Keys and password options:

[-pwri_password password] [-secretkey key] [-secretkeyid id] [-inkey filename|uri] [-passin arg] [-keyopt name:parameter] [-keyform DER|PEM|P12|ENGINE] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-rand files] [-writerand file]

Encryption options:

[-originator file] [-recip file] [recipient-cert ...] [-cipher] [-wrap cipher] [-aes128-wrap] [-aes192-wrap] [-aes256-wrap] [-des3-wrap] [-debug_decrypt]

Signing options:

[-md digest] [-signer file] [-certfile file] [-cades] [-nodetach] [-nocerts] [-noattr] [-nosmimecap] [-receipt_request_all] [-receipt_request_first] [-receipt_request_from emailaddress] [-receipt_request_to emailaddress]

Verification options:

[-signer file] [-content filename] [-no_content_verify] [-no_attr_verify] [-nosigs] [-noverify] [-nointern] [-cades] [-verify_retcode] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore]

Output options:

[-keyid] [-econtent_type type] [-text] [-certsout file] [-to addr] [-from addr] [-subject subj]

Printing options:

[-noout] [-print] [-nameopt option] [-receipt_request_print]

Validation options:

[-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks]

"},{"location":"man1/openssl-cms/#description","title":"DESCRIPTION","text":"

This command handles data in CMS format such as S/MIME v3.1 email messages. It can encrypt, decrypt, sign, verify, compress, uncompress, and print messages.

"},{"location":"man1/openssl-cms/#options","title":"OPTIONS","text":"

There are a number of operation options that set the type of operation to be performed: encrypt, decrypt, sign, verify, resign, sign_receipt, verify_receipt, digest_create, digest_verify, compress, uncompress, EncryptedData_encrypt, EncryptedData_decrypt, data_create, data_out, or cmsout. The relevance of the other options depends on the operation type and their meaning may vary according to it.

"},{"location":"man1/openssl-cms/#general-options","title":"General options","text":""},{"location":"man1/openssl-cms/#operation-options","title":"Operation options","text":""},{"location":"man1/openssl-cms/#file-format-options","title":"File format options","text":""},{"location":"man1/openssl-cms/#keys-and-password-options","title":"Keys and password options","text":""},{"location":"man1/openssl-cms/#encryption-and-decryption-options","title":"Encryption and decryption options","text":""},{"location":"man1/openssl-cms/#signing-options","title":"Signing options","text":""},{"location":"man1/openssl-cms/#verification-options","title":"Verification options","text":""},{"location":"man1/openssl-cms/#output-options","title":"Output options","text":""},{"location":"man1/openssl-cms/#printing-options","title":"Printing options","text":""},{"location":"man1/openssl-cms/#validation-options","title":"Validation options","text":""},{"location":"man1/openssl-cms/#notes","title":"NOTES","text":"

The MIME message must be sent without any blank lines between the headers and the output. Some mail programs will automatically add a blank line. Piping the mail directly to sendmail is one way to achieve the correct format.

The supplied message to be signed or encrypted must include the necessary MIME headers or many S/MIME clients won't display it properly (if at all). You can use the -text option to automatically add plain text headers.

A \"signed and encrypted\" message is one where a signed message is then encrypted. This can be produced by encrypting an already signed message: see the examples section.

This version of the program only allows one signer per message but it will verify multiple signers on received messages. Some S/MIME clients choke if a message contains multiple signers. It is possible to sign messages \"in parallel\" by signing an already signed message.

The options -encrypt and -decrypt reflect common usage in S/MIME clients. Strictly speaking these process CMS enveloped data: CMS encrypted data is used for other purposes.

The -resign option uses an existing message digest when adding a new signer. This means that attributes must be present in at least one existing signer using the same message digest or this operation will fail.

The -stream and -indef options enable streaming I/O support. As a result the encoding is BER using indefinite length constructed encoding and no longer DER. Streaming is supported for the -encrypt operation and the -sign operation if the content is not detached.

Streaming is always used for the -sign operation with detached data but since the content is no longer part of the CMS structure the encoding remains DER.

If the -decrypt option is used without a recipient certificate then an attempt is made to locate the recipient by trying each potential recipient in turn using the supplied private key. To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or not and if no recipients match the message is \"decrypted\" using a random key which will typically output garbage. The -debug_decrypt option can be used to disable the MMA attack protection and return an error if no recipient can be found: this option should be used with caution. For a fuller description see CMS_decrypt(3)).

"},{"location":"man1/openssl-cms/#cades-basic-electronic-signature-cades-bes","title":"CADES BASIC ELECTRONIC SIGNATURE (CADES-BES)","text":"

A CAdES Basic Electronic Signature (CAdES-BES), as defined in the European Standard ETSI EN 319 122-1 V1.1.1, contains:

"},{"location":"man1/openssl-cms/#exit-codes","title":"EXIT CODES","text":""},{"location":"man1/openssl-cms/#compatibility-with-pkcs7-format","title":"COMPATIBILITY WITH PKCS#7 FORMAT","text":"

openssl-smime(1) can only process the older PKCS#7 format. openssl cms supports Cryptographic Message Syntax format. Use of some features will result in messages which cannot be processed by applications which only support the older format. These are detailed below.

The use of the -keyid option with -sign or -encrypt.

The -outform PEM option uses different headers.

The -compress option.

The -secretkey option when used with -encrypt.

The use of PSS with -sign.

The use of OAEP or non-RSA keys with -encrypt.

Additionally the -EncryptedData_create and -data_create type cannot be processed by the older openssl-smime(1) command.

"},{"location":"man1/openssl-cms/#examples","title":"EXAMPLES","text":"

Create a cleartext signed message:

openssl cms -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem\n

Create an opaque signed message

openssl cms -sign -in message.txt -text -out mail.msg -nodetach \\\n       -signer mycert.pem\n

Create a signed message, include some additional certificates and read the private key from another file:

openssl cms -sign -in in.txt -text -out mail.msg \\\n       -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem\n

Create a signed message with two signers, use key identifier:

openssl cms -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem -signer othercert.pem -keyid\n

Send a signed message under Unix directly to sendmail, including headers:

openssl cms -sign -in in.txt -text -signer mycert.pem \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed message\" | sendmail someone@somewhere\n

Verify a message and extract the signer's certificate if successful:

openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt\n

Send encrypted mail using triple DES:

openssl cms -encrypt -in in.txt -from steve@openssl.org \\\n       -to someone@somewhere -subject \"Encrypted message\" \\\n       -des3 user.pem -out mail.msg\n

Sign and encrypt mail:

openssl cms -sign -in ml.txt -signer my.pem -text \\\n       | openssl cms -encrypt -out mail.msg \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed and Encrypted message\" -des3 user.pem\n

Note: the encryption command does not include the -text option because the message being encrypted already has MIME headers.

Decrypt a message:

openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem\n

The output from Netscape form signing is a PKCS#7 structure with the detached signature format. You can use this program to verify the signature by line wrapping the base64 encoded structure and surrounding it with:

-----BEGIN PKCS7-----\n-----END PKCS7-----\n

and using the command,

openssl cms -verify -inform PEM -in signature.pem -content content.txt\n

alternatively you can base64 decode the signature and use

openssl cms -verify -inform DER -in signature.der -content content.txt\n

Create an encrypted message using 128 bit Camellia:

openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem\n

Add a signer to an existing message:

openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg\n

Sign a message using RSA-PSS:

openssl cms -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem -keyopt rsa_padding_mode:pss\n

Create an encrypted message using RSA-OAEP:

openssl cms -encrypt -in plain.txt -out mail.msg \\\n       -recip cert.pem -keyopt rsa_padding_mode:oaep\n

Use SHA256 KDF with an ECDH certificate:

openssl cms -encrypt -in plain.txt -out mail.msg \\\n       -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256\n

Print CMS signed binary data in human-readable form:

openssl cms -in signed.cms -binary -inform DER -cmsout -print

"},{"location":"man1/openssl-cms/#bugs","title":"BUGS","text":"

The MIME parser isn't very clever: it seems to handle most messages that I've thrown at it but it may choke on others.

The code currently will only write out the signer's certificate to a file: if the signer has a separate encryption certificate this must be manually extracted. There should be some heuristic that determines the correct encryption certificate.

Ideally a database should be maintained of a certificates for each email address.

The code doesn't currently take note of the permitted symmetric encryption algorithms as supplied in the SMIMECapabilities signed attribute. this means the user has to manually include the correct encryption algorithm. It should store the list of permitted ciphers in a database and only use those.

No revocation checking is done on the signer's certificate.

"},{"location":"man1/openssl-cms/#see-also","title":"SEE ALSO","text":"

ossl_store-file(7)

"},{"location":"man1/openssl-cms/#history","title":"HISTORY","text":"

The use of multiple -signer options and the -resign command were first added in OpenSSL 1.0.0.

The -keyopt option was added in OpenSSL 1.0.2.

Support for RSA-OAEP and RSA-PSS was added in OpenSSL 1.0.2.

The use of non-RSA keys with -encrypt and -decrypt was added in OpenSSL 1.0.2.

The -no_alt_chains option was added in OpenSSL 1.0.2b.

The -nameopt option was added in OpenSSL 3.0.0.

The -engine option was deprecated in OpenSSL 3.0.

The -digest option was added in OpenSSL 3.2.

"},{"location":"man1/openssl-cms/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-crl/","title":"openssl-crl","text":""},{"location":"man1/openssl-crl/#name","title":"NAME","text":"

openssl-crl - CRL command

"},{"location":"man1/openssl-crl/#synopsis","title":"SYNOPSIS","text":"

openssl crl [-help] [-inform DER|PEM] [-outform DER|PEM] [-key filename] [-keyform DER|PEM|P12] [-dateopt] [-text] [-in filename] [-out filename] [-gendelta filename] [-badsig] [-verify] [-noout] [-hash] [-hash_old] [-fingerprint] [-crlnumber] [-issuer] [-lastupdate] [-nextupdate] [-nameopt option] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-crl/#description","title":"DESCRIPTION","text":"

This command processes CRL files in DER or PEM format.

"},{"location":"man1/openssl-crl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-crl/#examples","title":"EXAMPLES","text":"

Convert a CRL file from PEM to DER:

openssl crl -in crl.pem -outform DER -out crl.der\n

Output the text form of a DER encoded certificate:

openssl crl -in crl.der -text -noout\n
"},{"location":"man1/openssl-crl/#bugs","title":"BUGS","text":"

Ideally it should be possible to create a CRL using appropriate options and files too.

"},{"location":"man1/openssl-crl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-crl2pkcs7(1), openssl-ca(1), openssl-x509(1), ossl_store-file(7)

"},{"location":"man1/openssl-crl/#history","title":"HISTORY","text":"

Since OpenSSL 3.3, the -verify option will exit with 1 on failure.

"},{"location":"man1/openssl-crl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-crl2pkcs7/","title":"openssl-crl2pkcs7","text":""},{"location":"man1/openssl-crl2pkcs7/#name","title":"NAME","text":"

openssl-crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates

"},{"location":"man1/openssl-crl2pkcs7/#synopsis","title":"SYNOPSIS","text":"

openssl crl2pkcs7 [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-certfile filename] [-nocrl] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-crl2pkcs7/#description","title":"DESCRIPTION","text":"

This command takes an optional CRL and one or more certificates and converts them into a PKCS#7 degenerate \"certificates only\" structure.

"},{"location":"man1/openssl-crl2pkcs7/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-crl2pkcs7/#examples","title":"EXAMPLES","text":"

Create a PKCS#7 structure from a certificate and CRL:

openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem\n

Creates a PKCS#7 structure in DER format with no CRL from several different certificates:

openssl crl2pkcs7 -nocrl -certfile newcert.pem\n       -certfile demoCA/cacert.pem -outform DER -out p7.der\n
"},{"location":"man1/openssl-crl2pkcs7/#notes","title":"NOTES","text":"

The output file is a PKCS#7 signed data structure containing no signers and just certificates and an optional CRL.

This command can be used to send certificates and CAs to Netscape as part of the certificate enrollment process. This involves sending the DER encoded output as MIME type application/x-x509-user-cert.

The PEM encoded form with the header and footer lines removed can be used to install user certificates and CAs in MSIE using the Xenroll control.

"},{"location":"man1/openssl-crl2pkcs7/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkcs7(1)

"},{"location":"man1/openssl-crl2pkcs7/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-dgst/","title":"openssl-dgst","text":""},{"location":"man1/openssl-dgst/#name","title":"NAME","text":"

openssl-dgst - perform digest operations

"},{"location":"man1/openssl-dgst/#synopsis","title":"SYNOPSIS","text":"

openssl dgst|digest [-digest] [-list] [-help] [-c] [-d] [-debug] [-hex] [-binary] [-xoflen length] [-r] [-out filename] [-sign filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-verify filename] [-prverify filename] [-signature filename] [-sigopt nm:v] [-hmac key] [-mac alg] [-macopt nm:v] [-fips-fingerprint] [-engine id] [-engine_impl id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [file ...]

"},{"location":"man1/openssl-dgst/#description","title":"DESCRIPTION","text":"

This command output the message digest of a supplied file or files in hexadecimal, and also generates and verifies digital signatures using message digests.

The generic name, openssl dgst, may be used with an option specifying the algorithm to be used. The default digest is sha256. A supported digest name may also be used as the sub-command name. To see the list of supported algorithms, use openssl list -digest-algorithms

"},{"location":"man1/openssl-dgst/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-dgst/#examples","title":"EXAMPLES","text":"

To create a hex-encoded message digest of a file:

openssl dgst -md5 -hex file.txt\nor\nopenssl md5 file.txt\n

To sign a file using SHA-256 with binary file output:

openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt\nor\nopenssl sha256 -sign privatekey.pem -out signature.sign file.txt\n

To verify a signature:

openssl dgst -sha256 -verify publickey.pem \\\n-signature signature.sign \\\nfile.txt\n
"},{"location":"man1/openssl-dgst/#notes","title":"NOTES","text":"

The digest mechanisms that are available will depend on the options used when building OpenSSL. The openssl list -digest-algorithms command can be used to list them.

New or agile applications should use probably use SHA-256. Other digests, particularly SHA-1 and MD5, are still widely used for interoperating with existing formats and protocols.

When signing a file, this command will automatically determine the algorithm (RSA, ECC, etc) to use for signing based on the private key's ASN.1 info. When verifying signatures, it only handles the RSA, DSA, or ECDSA signature itself, not the related data to identify the signer and algorithm used in formats such as x.509, CMS, and S/MIME.

A source of random numbers is required for certain signing algorithms, in particular ECDSA and DSA.

The signing and verify options should only be used if a single file is being signed or verified.

Hex signatures cannot be verified using openssl. Instead, use \"xxd -r\" or similar program to transform the hex signature into a binary signature prior to verification.

The openssl-mac(1) command is preferred over the -hmac, -mac and -macopt command line options.

"},{"location":"man1/openssl-dgst/#see-also","title":"SEE ALSO","text":"

openssl-mac(1)

"},{"location":"man1/openssl-dgst/#history","title":"HISTORY","text":"

The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0. The FIPS-related options were removed in OpenSSL 1.1.0.

The -engine and -engine_impl options were deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-dgst/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-dhparam/","title":"openssl-dhparam","text":""},{"location":"man1/openssl-dhparam/#name","title":"NAME","text":"

openssl-dhparam - DH parameter manipulation and generation

"},{"location":"man1/openssl-dhparam/#synopsis","title":"SYNOPSIS","text":"

openssl dhparam [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-dsaparam] [-check] [-noout] [-text] [-verbose] [-quiet] [-2] [-3] [-5] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [numbits]

"},{"location":"man1/openssl-dhparam/#description","title":"DESCRIPTION","text":"

This command is used to manipulate DH parameter files.

See \"EXAMPLES\" in openssl-genpkey(1) for examples on how to generate a key using a named safe prime group without generating intermediate parameters.

"},{"location":"man1/openssl-dhparam/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-dhparam/#notes","title":"NOTES","text":"

This command replaces the dh and gendh commands of previous releases.

"},{"location":"man1/openssl-dhparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyparam(1), openssl-dsaparam(1), openssl-genpkey(1).

"},{"location":"man1/openssl-dhparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-dhparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-dsa/","title":"openssl-dsa","text":""},{"location":"man1/openssl-dsa/#name","title":"NAME","text":"

openssl-dsa - DSA key processing

"},{"location":"man1/openssl-dsa/#synopsis","title":"SYNOPSIS","text":"

openssl dsa [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-passin arg] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-text] [-noout] [-modulus] [-pubin] [-pubout] [-pvk-strong] [-pvk-weak] [-pvk-none] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-dsa/#description","title":"DESCRIPTION","text":"

This command processes DSA keys. They can be converted between various forms and their components printed out. Note This command uses the traditional SSLeay compatible format for private key encryption: newer applications should use the more secure PKCS#8 format using the pkcs8

"},{"location":"man1/openssl-dsa/#options","title":"OPTIONS","text":"

The openssl-pkey(1) command is capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-dsa/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-pkey(1) command contains examples equivalent to the ones listed here.

To remove the pass phrase on a DSA private key:

openssl dsa -in key.pem -out keyout.pem\n

To encrypt a private key using triple DES:

openssl dsa -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl dsa -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl dsa -in key.pem -text -noout\n

To just output the public part of a private key:

openssl dsa -in key.pem -pubout -out pubkey.pem\n
"},{"location":"man1/openssl-dsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkey(1), openssl-dsaparam(1), openssl-gendsa(1), openssl-rsa(1), openssl-genrsa(1)

"},{"location":"man1/openssl-dsa/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-dsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-dsaparam/","title":"openssl-dsaparam","text":""},{"location":"man1/openssl-dsaparam/#name","title":"NAME","text":"

openssl-dsaparam - DSA parameter manipulation and generation

"},{"location":"man1/openssl-dsaparam/#synopsis","title":"SYNOPSIS","text":"

openssl dsaparam [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-noout] [-text] [-genkey] [-verbose] [-quiet] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [numbits] [numqbits]

"},{"location":"man1/openssl-dsaparam/#description","title":"DESCRIPTION","text":"

This command is used to manipulate or generate DSA parameter files.

DSA parameter generation can be a slow process and as a result the same set of DSA parameters is often used to generate several distinct keys.

"},{"location":"man1/openssl-dsaparam/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-dsaparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyparam(1), openssl-gendsa(1), openssl-dsa(1), openssl-genrsa(1), openssl-rsa(1)

"},{"location":"man1/openssl-dsaparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-dsaparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-ec/","title":"openssl-ec","text":""},{"location":"man1/openssl-ec/#name","title":"NAME","text":"

openssl-ec - EC key processing

"},{"location":"man1/openssl-ec/#synopsis","title":"SYNOPSIS","text":"

openssl ec [-help] [-inform DER|PEM|P12|ENGINE] [-outform DER|PEM] [-in filename|uri] [-passin arg] [-out filename] [-passout arg] [-des] [-des3] [-idea] [-text] [-noout] [-param_out] [-pubin] [-pubout] [-conv_form arg] [-param_enc arg] [-no_public] [-check] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ec/#description","title":"DESCRIPTION","text":"

The openssl-ec(1) command processes EC keys. They can be converted between various forms and their components printed out. Note OpenSSL uses the private key format specified in 'SEC 1: Elliptic Curve Cryptography' (http://www.secg.org/). To convert an OpenSSL EC private key into the PKCS#8 private key format use the openssl-pkcs8(1) command.

"},{"location":"man1/openssl-ec/#options","title":"OPTIONS","text":"

The openssl-pkey(1) command is capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-ec/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-pkey(1) command contains examples equivalent to the ones listed here.

To encrypt a private key using triple DES:

openssl ec -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl ec -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl ec -in key.pem -text -noout\n

To just output the public part of a private key:

openssl ec -in key.pem -pubout -out pubkey.pem\n

To change the parameters encoding to explicit:

openssl ec -in key.pem -param_enc explicit -out keyout.pem\n

To change the point conversion form to compressed:

openssl ec -in key.pem -conv_form compressed -out keyout.pem\n
"},{"location":"man1/openssl-ec/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkey(1), openssl-ecparam(1), openssl-dsa(1), openssl-rsa(1)

"},{"location":"man1/openssl-ec/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -conv_form and -no_public options are no longer supported with keys loaded from an engine in OpenSSL 3.0.

"},{"location":"man1/openssl-ec/#copyright","title":"COPYRIGHT","text":"

Copyright 2003-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-ecparam/","title":"openssl-ecparam","text":""},{"location":"man1/openssl-ecparam/#name","title":"NAME","text":"

openssl-ecparam - EC parameter manipulation and generation

"},{"location":"man1/openssl-ecparam/#synopsis","title":"SYNOPSIS","text":"

openssl ecparam [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-noout] [-text] [-check] [-check_named] [-name arg] [-list_curves] [-conv_form arg] [-param_enc arg] [-no_seed] [-genkey] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ecparam/#description","title":"DESCRIPTION","text":"

This command is used to manipulate or generate EC parameter files.

OpenSSL is currently not able to generate new groups and therefore this command can only create EC parameters from known (named) curves.

"},{"location":"man1/openssl-ecparam/#options","title":"OPTIONS","text":"

The openssl-genpkey(1) and openssl-pkeyparam(1) commands are capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-ecparam/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-genpkey(1) and openssl-pkeyparam(1) commands contains examples equivalent to the ones listed here.

To create EC parameters with the group 'prime192v1':

openssl ecparam -out ec_param.pem -name prime192v1\n

To create EC parameters with explicit parameters:

openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit\n

To validate given EC parameters:

openssl ecparam -in ec_param.pem -check\n

To create EC parameters and a private key:

openssl ecparam -out ec_key.pem -name prime192v1 -genkey\n

To change the point encoding to 'compressed':

openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed\n

To print out the EC parameters to standard output:

openssl ecparam -in ec_param.pem -noout -text\n
"},{"location":"man1/openssl-ecparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyparam(1), openssl-genpkey(1), openssl-ec(1), openssl-dsaparam(1)

"},{"location":"man1/openssl-ecparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-ecparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2003-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-enc/","title":"openssl-enc","text":""},{"location":"man1/openssl-enc/#name","title":"NAME","text":"

openssl-enc - symmetric cipher routines

"},{"location":"man1/openssl-enc/#synopsis","title":"SYNOPSIS","text":"

openssl enc|cipher [-cipher] [-help] [-list] [-ciphers] [-in filename] [-out filename] [-pass arg] [-e] [-d] [-a] [-base64] [-A] [-k password] [-kfile filename] [-K key] [-iv IV] [-S salt] [-salt] [-nosalt] [-z] [-md digest] [-iter count] [-pbkdf2] [-saltlen size] [-p] [-P] [-bufsize number] [-nopad] [-v] [-debug] [-none] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

openssl cipher [...]

"},{"location":"man1/openssl-enc/#description","title":"DESCRIPTION","text":"

The symmetric cipher commands allow data to be encrypted or decrypted using various block and stream ciphers using keys based on passwords or explicitly provided. Base64 encoding or decoding can also be performed either by itself or in addition to the encryption or decryption.

"},{"location":"man1/openssl-enc/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-enc/#notes","title":"NOTES","text":"

The program can be called either as openssl _cipher_ or openssl enc -_cipher_. The first form doesn't work with engine-provided ciphers, because this form is processed before the configuration file is read and any ENGINEs loaded. Use the openssl-list(1) command to get a list of supported ciphers.

Engines which provide entirely new encryption algorithms (such as the ccgost engine which provides gost89 algorithm) should be configured in the configuration file. Engines specified on the command line using -engine option can only be used for hardware-assisted implementations of ciphers which are supported by the OpenSSL core or another engine specified in the configuration file.

When the enc command lists supported ciphers, ciphers provided by engines, specified in the configuration files are listed too.

A password will be prompted for to derive the key and IV if necessary.

The -salt option should ALWAYS be used if the key is being derived from a password unless you want compatibility with previous versions of OpenSSL.

Without the -salt option it is possible to perform efficient dictionary attacks on the password and to attack stream cipher encrypted data. The reason for this is that without the salt the same password always generates the same encryption key.

When the salt is generated at random (that means when encrypting using a passphrase without explicit salt given using -S option), the first bytes of the encrypted data are reserved to store the salt for later decrypting.

Some of the ciphers do not have large keys and others have security implications if not used correctly. A beginner is advised to just use a strong block cipher, such as AES, in CBC mode.

All the block ciphers normally use PKCS#5 padding, also known as standard block padding. This allows a rudimentary integrity or password check to be performed. However, since the chance of random data passing the test is better than 1 in 256 it isn't a very good test.

If padding is disabled then the input data must be a multiple of the cipher block length.

All RC2 ciphers have the same key and effective key length.

Blowfish and RC5 algorithms use a 128 bit key.

Please note that OpenSSL 3.0 changed the effect of the -S option. Any explicit salt value specified via this option is no longer prepended to the ciphertext when encrypting, and must again be explicitly provided when decrypting. Conversely, when the -S option is used during decryption, the ciphertext is expected to not have a prepended salt value.

When using OpenSSL 3.0 or later to decrypt data that was encrypted with an explicit salt under OpenSSL 1.1.1 do not use the -S option, the salt will then be read from the ciphertext. To generate ciphertext that can be decrypted with OpenSSL 1.1.1 do not use the -S option, the salt will be then be generated randomly and prepended to the output.

"},{"location":"man1/openssl-enc/#supported-ciphers","title":"SUPPORTED CIPHERS","text":"

Note that some of these ciphers can be disabled at compile time and some are available only if an appropriate engine is configured in the configuration file. The output when invoking this command with the -list option (that is openssl enc -list) is a list of ciphers, supported by your version of OpenSSL, including ones provided by configured engines.

This command does not support authenticated encryption modes like CCM and GCM, and will not support such modes in the future. This is due to having to begin streaming output (e.g., to standard output when -out is not used) before the authentication tag could be validated. When this command is used in a pipeline, the receiving end will not be able to roll back upon authentication failure. The AEAD modes currently in common use also suffer from catastrophic failure of confidentiality and/or integrity upon reuse of key/iv/nonce, and since openssl enc places the entire burden of key/iv/nonce management upon the user, the risk of exposing AEAD modes is too great to allow. These key/iv/nonce management issues also affect other modes currently exposed in this command, but the failure modes are less extreme in these cases, and the functionality cannot be removed with a stable release branch. For bulk encryption of data, whether using authenticated encryption modes or other modes, openssl-cms(1) is recommended, as it provides a standard data format and performs the needed key/iv/nonce management.

When enc is used with key wrapping modes the input data cannot be streamed, meaning it must be processed in a single pass. Consequently, the input data size must be less than the buffer size (-bufsize arg, default to 8*1024 bytes). The '*-wrap' ciphers require the input to be a multiple of 8 bytes long, because no padding is involved. The '*-wrap-pad' ciphers allow any input length. In both cases, no IV is needed. See example below.

base64             Base 64\n\nbf-cbc             Blowfish in CBC mode\nbf                 Alias for bf-cbc\nblowfish           Alias for bf-cbc\nbf-cfb             Blowfish in CFB mode\nbf-ecb             Blowfish in ECB mode\nbf-ofb             Blowfish in OFB mode\n\ncast-cbc           CAST in CBC mode\ncast               Alias for cast-cbc\ncast5-cbc          CAST5 in CBC mode\ncast5-cfb          CAST5 in CFB mode\ncast5-ecb          CAST5 in ECB mode\ncast5-ofb          CAST5 in OFB mode\n\nchacha20           ChaCha20 algorithm\n\ndes-cbc            DES in CBC mode\ndes                Alias for des-cbc\ndes-cfb            DES in CFB mode\ndes-ofb            DES in OFB mode\ndes-ecb            DES in ECB mode\n\ndes-ede-cbc        Two key triple DES EDE in CBC mode\ndes-ede            Two key triple DES EDE in ECB mode\ndes-ede-cfb        Two key triple DES EDE in CFB mode\ndes-ede-ofb        Two key triple DES EDE in OFB mode\n\ndes-ede3-cbc       Three key triple DES EDE in CBC mode\ndes-ede3           Three key triple DES EDE in ECB mode\ndes3               Alias for des-ede3-cbc\ndes-ede3-cfb       Three key triple DES EDE CFB mode\ndes-ede3-ofb       Three key triple DES EDE in OFB mode\n\ndesx               DESX algorithm.\n\ngost89             GOST 28147-89 in CFB mode (provided by ccgost engine)\ngost89-cnt         GOST 28147-89 in CNT mode (provided by ccgost engine)\n\nidea-cbc           IDEA algorithm in CBC mode\nidea               same as idea-cbc\nidea-cfb           IDEA in CFB mode\nidea-ecb           IDEA in ECB mode\nidea-ofb           IDEA in OFB mode\n\nrc2-cbc            128 bit RC2 in CBC mode\nrc2                Alias for rc2-cbc\nrc2-cfb            128 bit RC2 in CFB mode\nrc2-ecb            128 bit RC2 in ECB mode\nrc2-ofb            128 bit RC2 in OFB mode\nrc2-64-cbc         64 bit RC2 in CBC mode\nrc2-40-cbc         40 bit RC2 in CBC mode\n\nrc4                128 bit RC4\nrc4-64             64 bit RC4\nrc4-40             40 bit RC4\n\nrc5-cbc            RC5 cipher in CBC mode\nrc5                Alias for rc5-cbc\nrc5-cfb            RC5 cipher in CFB mode\nrc5-ecb            RC5 cipher in ECB mode\nrc5-ofb            RC5 cipher in OFB mode\n\nseed-cbc           SEED cipher in CBC mode\nseed               Alias for seed-cbc\nseed-cfb           SEED cipher in CFB mode\nseed-ecb           SEED cipher in ECB mode\nseed-ofb           SEED cipher in OFB mode\n\nsm4-cbc            SM4 cipher in CBC mode\nsm4                Alias for sm4-cbc\nsm4-cfb            SM4 cipher in CFB mode\nsm4-ctr            SM4 cipher in CTR mode\nsm4-ecb            SM4 cipher in ECB mode\nsm4-ofb            SM4 cipher in OFB mode\n\naes-[128|192|256]-cbc  128/192/256 bit AES in CBC mode\naes[128|192|256]       Alias for aes-[128|192|256]-cbc\naes-[128|192|256]-cfb  128/192/256 bit AES in 128 bit CFB mode\naes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode\naes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode\naes-[128|192|256]-ctr  128/192/256 bit AES in CTR mode\naes-[128|192|256]-ecb  128/192/256 bit AES in ECB mode\naes-[128|192|256]-ofb  128/192/256 bit AES in OFB mode\n\naes-[128|192|256]-wrap     key wrapping using 128/192/256 bit AES\naes-[128|192|256]-wrap-pad key wrapping with padding using 128/192/256 bit AES\n\naria-[128|192|256]-cbc  128/192/256 bit ARIA in CBC mode\naria[128|192|256]       Alias for aria-[128|192|256]-cbc\naria-[128|192|256]-cfb  128/192/256 bit ARIA in 128 bit CFB mode\naria-[128|192|256]-cfb1 128/192/256 bit ARIA in 1 bit CFB mode\naria-[128|192|256]-cfb8 128/192/256 bit ARIA in 8 bit CFB mode\naria-[128|192|256]-ctr  128/192/256 bit ARIA in CTR mode\naria-[128|192|256]-ecb  128/192/256 bit ARIA in ECB mode\naria-[128|192|256]-ofb  128/192/256 bit ARIA in OFB mode\n\ncamellia-[128|192|256]-cbc  128/192/256 bit Camellia in CBC mode\ncamellia[128|192|256]       Alias for camellia-[128|192|256]-cbc\ncamellia-[128|192|256]-cfb  128/192/256 bit Camellia in 128 bit CFB mode\ncamellia-[128|192|256]-cfb1 128/192/256 bit Camellia in 1 bit CFB mode\ncamellia-[128|192|256]-cfb8 128/192/256 bit Camellia in 8 bit CFB mode\ncamellia-[128|192|256]-ctr  128/192/256 bit Camellia in CTR mode\ncamellia-[128|192|256]-ecb  128/192/256 bit Camellia in ECB mode\ncamellia-[128|192|256]-ofb  128/192/256 bit Camellia in OFB mode\n
"},{"location":"man1/openssl-enc/#examples","title":"EXAMPLES","text":"

Just base64 encode a binary file:

openssl base64 -in file.bin -out file.b64\n

Decode the same file

openssl base64 -d -in file.b64 -out file.bin\n

Encrypt a file using AES-128 using a prompted password and PBKDF2 key derivation:

openssl enc -aes128 -pbkdf2 -in file.txt -out file.aes128\n

Decrypt a file using a supplied password:

openssl enc -aes128 -pbkdf2 -d -in file.aes128 -out file.txt \\\n   -pass pass:<password>\n

Encrypt a file then base64 encode it (so it can be sent via mail for example) using AES-256 in CTR mode and PBKDF2 key derivation:

openssl enc -aes-256-ctr -pbkdf2 -a -in file.txt -out file.aes256\n

Base64 decode a file then decrypt it using a password supplied in a file:

openssl enc -aes-256-ctr -pbkdf2 -d -a -in file.aes256 -out file.txt \\\n   -pass file:<passfile>\n

AES key wrapping:

openssl enc -e -a -id-aes128-wrap-pad -K 000102030405060708090A0B0C0D0E0F -in file.bin\n

or openssl aes128-wrap-pad -e -a -K 000102030405060708090A0B0C0D0E0F -in file.bin

"},{"location":"man1/openssl-enc/#bugs","title":"BUGS","text":"

The -A option when used with large files doesn't work properly. On the other hand, when base64 decoding without the -A option, if the first 1024 bytes of input do not include a newline character the first two lines of input are ignored.

The openssl enc command only supports a fixed number of algorithms with certain parameters. So if, for example, you want to use RC2 with a 76 bit key or RC4 with an 84 bit key you can't use this program.

"},{"location":"man1/openssl-enc/#history","title":"HISTORY","text":"

The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0.

The -list option was added in OpenSSL 1.1.1e.

The -ciphers and -engine options were deprecated in OpenSSL 3.0.

The -saltlen option was added in OpenSSL 3.2.

"},{"location":"man1/openssl-enc/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-engine/","title":"openssl-engine","text":""},{"location":"man1/openssl-engine/#name","title":"NAME","text":"

openssl-engine - load and query engines

"},{"location":"man1/openssl-engine/#synopsis","title":"SYNOPSIS","text":"

openssl engine [-help] [-v] [-vv] [-vvv] [-vvvv] [-c] [-t] [-tt] [-pre command] ... [-post command] ... [engine ...]

"},{"location":"man1/openssl-engine/#description","title":"DESCRIPTION","text":"

This command has been deprecated. Providers should be used instead of engines.

This command is used to query the status and capabilities of the specified _engine_s. Engines may be specified before and after all other command-line flags. Only those specified are queried.

"},{"location":"man1/openssl-engine/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-engine/#examples","title":"EXAMPLES","text":"

To list all the commands available to a dynamic engine:

$ openssl engine -t -tt -vvvv dynamic\n(dynamic) Dynamic engine loading support\n     [ unavailable ]\n     SO_PATH: Specifies the path to the new ENGINE shared library\n          (input flags): STRING\n     NO_VCHECK: Specifies to continue even if version checking fails (boolean)\n          (input flags): NUMERIC\n     ID: Specifies an ENGINE id name for loading\n          (input flags): STRING\n     LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory)\n          (input flags): NUMERIC\n     DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory)\n          (input flags): NUMERIC\n     DIR_ADD: Adds a directory from which ENGINEs can be loaded\n          (input flags): STRING\n     LOAD: Load up the ENGINE specified by other settings\n          (input flags): NO_INPUT\n

To list the capabilities of the rsax engine:

$ openssl engine -c\n(rsax) RSAX engine support\n [RSA]\n(dynamic) Dynamic engine loading support\n
"},{"location":"man1/openssl-engine/#environment","title":"ENVIRONMENT","text":""},{"location":"man1/openssl-engine/#see-also","title":"SEE ALSO","text":"

openssl(1), config(5)

"},{"location":"man1/openssl-engine/#history","title":"HISTORY","text":"

This command was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-engine/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-errstr/","title":"openssl-errstr","text":""},{"location":"man1/openssl-errstr/#name","title":"NAME","text":"

openssl-errstr - lookup error codes

"},{"location":"man1/openssl-errstr/#synopsis","title":"SYNOPSIS","text":"

openssl errstr [-help] error_code...

"},{"location":"man1/openssl-errstr/#description","title":"DESCRIPTION","text":"

Sometimes an application will not load error message texts and only numerical forms will be available. This command can be used to display the meaning of the hex code. The hex code is the hex digits after the second colon.

"},{"location":"man1/openssl-errstr/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-errstr/#examples","title":"EXAMPLES","text":"

The error code:

27594:error:2006D080:lib(32)::reason(128)::107:\n

can be displayed with:

openssl errstr 2006D080\n

to produce the error message:

error:2006D080:BIO routines::no such file\n
"},{"location":"man1/openssl-errstr/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-fipsinstall/","title":"openssl-fipsinstall","text":""},{"location":"man1/openssl-fipsinstall/#name","title":"NAME","text":"

openssl-fipsinstall - perform FIPS configuration installation

"},{"location":"man1/openssl-fipsinstall/#synopsis","title":"SYNOPSIS","text":"

openssl fipsinstall [-help] [-in configfilename] [-out configfilename] [-module modulefilename] [-provider_name providername] [-section_name sectionname] [-verify] [-mac_name macname] [-macopt nm:v] [-noout] [-quiet] [-pedantic] [-no_conditional_errors] [-no_security_checks] [-ems_check] [-no_drbg_truncated_digests] [-self_test_onload] [-self_test_oninstall] [-corrupt_desc selftest_description] [-corrupt_type selftest_type] [-config parent_config]

"},{"location":"man1/openssl-fipsinstall/#description","title":"DESCRIPTION","text":"

This command is used to generate a FIPS module configuration file. This configuration file can be used each time a FIPS module is loaded in order to pass data to the FIPS module self tests. The FIPS module always verifies its MAC, but optionally only needs to run the KAT's once, at installation.

The generated configuration file consists of:

This file is described in fips_config(5).

"},{"location":"man1/openssl-fipsinstall/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-fipsinstall/#notes","title":"NOTES","text":"

Self tests results are logged by default if the options -quiet and -noout are not specified, or if either of the options -corrupt_desc or -corrupt_type are used. If the base configuration file is set up to autoload the fips module, then the fips module will be loaded and self tested BEFORE the fipsinstall application has a chance to set up its own self test callback. As a result of this the self test output and the options -corrupt_desc and -corrupt_type will be ignored. For normal usage the base configuration file should use the default provider when generating the fips configuration file.

The -self_test_oninstall option was added and the -self_test_onload option was made the default in OpenSSL 3.1.

The command and all remaining options were added in OpenSSL 3.0.

"},{"location":"man1/openssl-fipsinstall/#examples","title":"EXAMPLES","text":"

Calculate the mac of a FIPS module fips.so and run a FIPS self test for the module, and save the fips.cnf configuration file:

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips\n

Verify that the configuration file fips.cnf contains the correct info:

openssl fipsinstall -module ./fips.so -in fips.cnf  -provider_name fips -verify\n

Corrupt any self tests which have the description SHA1:

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \\\n        -corrupt_desc 'SHA1'\n

Validate that the fips module can be loaded from a base configuration file:

export OPENSSL_CONF_INCLUDE=<path of configuration files>\nexport OPENSSL_MODULES=<provider-path>\nopenssl fipsinstall -config' 'default.cnf'\n
"},{"location":"man1/openssl-fipsinstall/#see-also","title":"SEE ALSO","text":"

config(5), fips_config(5), OSSL_PROVIDER-FIPS(7), EVP_MAC(3)

"},{"location":"man1/openssl-fipsinstall/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-format-options/","title":"openssl-format-options","text":""},{"location":"man1/openssl-format-options/#name","title":"NAME","text":"

openssl-format-options - OpenSSL command input and output format options

"},{"location":"man1/openssl-format-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-format-options/#description","title":"DESCRIPTION","text":"

Several OpenSSL commands can take input or generate output in a variety of formats.

Since OpenSSL 3.0 keys, single certificates, and CRLs can be read from files in any of the DER, PEM or P12 formats. Specifying their input format is no more needed and the openssl commands will automatically try all the possible formats. However if the DER or PEM input format is specified it will be enforced.

In order to access a key via an engine the input format ENGINE may be used; alternatively the key identifier in the <uri> argument of the respective key option may be preceded by org.openssl.engine:. See \"Engine Options\" in openssl(1) for an example usage of the latter.

"},{"location":"man1/openssl-format-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-format-options/#format-options","title":"Format Options","text":"

The options to specify the format are as follows. Refer to the individual man page to see which options are accepted.

"},{"location":"man1/openssl-format-options/#format-option-arguments","title":"Format Option Arguments","text":"

The possible format arguments are described below. Both uppercase and lowercase are accepted.

The list of acceptable format arguments, and the default, is described in each command documentation.

"},{"location":"man1/openssl-format-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-gendsa/","title":"openssl-gendsa","text":""},{"location":"man1/openssl-gendsa/#name","title":"NAME","text":"

openssl-gendsa - generate a DSA private key from a set of parameters

"},{"location":"man1/openssl-gendsa/#synopsis","title":"SYNOPSIS","text":"

openssl gendsa [-help] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-verbose] [-quiet] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [paramfile]

"},{"location":"man1/openssl-gendsa/#description","title":"DESCRIPTION","text":"

This command generates a DSA private key from a DSA parameter file (which will be typically generated by the openssl-dsaparam(1) command).

"},{"location":"man1/openssl-gendsa/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-gendsa/#notes","title":"NOTES","text":"

DSA key generation is little more than random number generation so it is much quicker that RSA key generation for example.

"},{"location":"man1/openssl-gendsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-dsaparam(1), openssl-dsa(1), openssl-genrsa(1), openssl-rsa(1)

"},{"location":"man1/openssl-gendsa/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-gendsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-genpkey/","title":"openssl-genpkey","text":""},{"location":"man1/openssl-genpkey/#name","title":"NAME","text":"

openssl-genpkey - generate a private key or key pair

"},{"location":"man1/openssl-genpkey/#synopsis","title":"SYNOPSIS","text":"

openssl genpkey [-help] [-out filename] [-outpubkey filename] [-outform DER|PEM] [-verbose] [-quiet] [-pass arg] [-cipher] [-paramfile file] [-algorithm alg] [-pkeyopt opt:value] [-genparam] [-text] [-rand files] [-writerand file] [-engine id]

[-provider name] [-provider-path path] [-propquery propq] [-config configfile]

"},{"location":"man1/openssl-genpkey/#description","title":"DESCRIPTION","text":"

This command generates a private key or key pair.

"},{"location":"man1/openssl-genpkey/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-genpkey/#key-generation-options","title":"KEY GENERATION OPTIONS","text":"

The options supported by each algorithm and indeed each implementation of an algorithm can vary. The options for the OpenSSL implementations are detailed below. There are no key generation options defined for the X25519, X448, ED25519 or ED448 algorithms.

"},{"location":"man1/openssl-genpkey/#rsa-key-generation-options","title":"RSA Key Generation Options","text":""},{"location":"man1/openssl-genpkey/#rsa-pss-key-generation-options","title":"RSA-PSS Key Generation Options","text":"

Note: by default an RSA-PSS key has no parameter restrictions.

"},{"location":"man1/openssl-genpkey/#ec-key-generation-options","title":"EC Key Generation Options","text":"

The EC key generation options can also be used for parameter generation.

"},{"location":"man1/openssl-genpkey/#dh-key-generation-options","title":"DH Key Generation Options","text":""},{"location":"man1/openssl-genpkey/#parameter-generation-options","title":"PARAMETER GENERATION OPTIONS","text":"

The options supported by each algorithm and indeed each implementation of an algorithm can vary. The options for the OpenSSL implementations are detailed below.

"},{"location":"man1/openssl-genpkey/#dsa-parameter-generation-options","title":"DSA Parameter Generation Options","text":""},{"location":"man1/openssl-genpkey/#dh-parameter-generation-options","title":"DH Parameter Generation Options","text":"

For most use cases it is recommended to use the group option rather than the type options. Note that the group option is not used by default if no parameter generation options are specified.

"},{"location":"man1/openssl-genpkey/#ec-parameter-generation-options","title":"EC Parameter Generation Options","text":"

The EC parameter generation options are the same as for key generation. See \"EC Key Generation Options\" above.

"},{"location":"man1/openssl-genpkey/#notes","title":"NOTES","text":"

The use of the genpkey program is encouraged over the algorithm specific utilities because additional algorithm options and ENGINE provided algorithms can be used.

"},{"location":"man1/openssl-genpkey/#examples","title":"EXAMPLES","text":"

Generate an RSA private key using default parameters:

openssl genpkey -algorithm RSA -out key.pem\n

Encrypt output private key using 128 bit AES and the passphrase \"hello\":

openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello\n

Generate a 2048 bit RSA key using 3 as the public exponent:

openssl genpkey -algorithm RSA -out key.pem \\\n    -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3\n

Generate 2048 bit DSA parameters that can be validated: The output values for gindex and seed are required for key validation purposes and are not saved to the output pem file).

openssl genpkey -genparam -algorithm DSA -out dsap.pem -pkeyopt pbits:2048 \\\n    -pkeyopt qbits:224 -pkeyopt digest:SHA256 -pkeyopt gindex:1 -text\n

Generate DSA key from parameters:

openssl genpkey -paramfile dsap.pem -out dsakey.pem\n

Generate 4096 bit DH Key using safe prime group ffdhe4096:

openssl genpkey -algorithm DH -out dhkey.pem -pkeyopt group:ffdhe4096\n

Generate 2048 bit X9.42 DH key with 256 bit subgroup using RFC5114 group3:

openssl genpkey -algorithm DHX -out dhkey.pem -pkeyopt dh_rfc5114:3\n

Generate a DH key using a DH parameters file:

openssl genpkey -paramfile dhp.pem -out dhkey.pem\n

Output DH parameters for safe prime group ffdhe2048:

openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt group:ffdhe2048\n

Output 2048 bit X9.42 DH parameters with 224 bit subgroup using RFC5114 group2:

openssl genpkey -genparam -algorithm DHX -out dhp.pem -pkeyopt dh_rfc5114:2\n

Output 2048 bit X9.42 DH parameters with 224 bit subgroup using FIP186-4 keygen:

openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \\\n    -pkeyopt pbits:2048 -pkeyopt qbits:224 -pkeyopt digest:SHA256 \\\n    -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:2\n

Output 1024 bit X9.42 DH parameters with 160 bit subgroup using FIP186-2 keygen:

openssl genpkey -genparam -algorithm DHX -out dhp.pem -text \\\n    -pkeyopt pbits:1024 -pkeyopt qbits:160 -pkeyopt digest:SHA1 \\\n    -pkeyopt gindex:1 -pkeyopt dh_paramgen_type:1\n

Output 2048 bit DH parameters:

openssl genpkey -genparam -algorithm DH -out dhp.pem \\\n    -pkeyopt dh_paramgen_prime_len:2048\n

Output 2048 bit DH parameters using a generator:

openssl genpkey -genparam -algorithm DH -out dhpx.pem \\\n    -pkeyopt dh_paramgen_prime_len:2048 \\\n    -pkeyopt dh_paramgen_type:1\n

Generate EC parameters:

openssl genpkey -genparam -algorithm EC -out ecp.pem \\\n       -pkeyopt ec_paramgen_curve:secp384r1 \\\n       -pkeyopt ec_param_enc:named_curve\n

Generate EC key from parameters:

openssl genpkey -paramfile ecp.pem -out eckey.pem\n

Generate EC key directly:

openssl genpkey -algorithm EC -out eckey.pem \\\n       -pkeyopt ec_paramgen_curve:P-384 \\\n       -pkeyopt ec_param_enc:named_curve\n

Generate an X25519 private key:

openssl genpkey -algorithm X25519 -out xkey.pem\n

Generate an ED448 private key:

openssl genpkey -algorithm ED448 -out xkey.pem\n
"},{"location":"man1/openssl-genpkey/#history","title":"HISTORY","text":"

The ability to use NIST curve names, and to generate an EC key directly, were added in OpenSSL 1.0.2. The ability to generate X25519 keys was added in OpenSSL 1.1.0. The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-genpkey/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-genrsa/","title":"openssl-genrsa","text":""},{"location":"man1/openssl-genrsa/#name","title":"NAME","text":"

openssl-genrsa - generate an RSA private key

"},{"location":"man1/openssl-genrsa/#synopsis","title":"SYNOPSIS","text":"

openssl genrsa [-help] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-F4] [-f4] [-3] [-primes num] [-verbose] [-quiet] [-traditional] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [numbits]

"},{"location":"man1/openssl-genrsa/#description","title":"DESCRIPTION","text":"

This command generates an RSA private key.

"},{"location":"man1/openssl-genrsa/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-genrsa/#notes","title":"NOTES","text":"

RSA private key generation essentially involves the generation of two or more prime numbers. When generating a private key various symbols will be output to indicate the progress of the generation. A . represents each number which has passed an initial sieve test, + means a number has passed a single round of the Miller-Rabin primality test, * means the current prime starts a regenerating progress due to some failed tests. A newline means that the number has passed all the prime tests (the actual number depends on the key size).

Because key generation is a random process the time taken to generate a key may vary somewhat. But in general, more primes lead to less generation time of a key.

"},{"location":"man1/openssl-genrsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-gendsa(1)

"},{"location":"man1/openssl-genrsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-info/","title":"openssl-info","text":""},{"location":"man1/openssl-info/#name","title":"NAME","text":"

openssl-info - print OpenSSL built-in information

"},{"location":"man1/openssl-info/#synopsis","title":"SYNOPSIS","text":"

openssl info [-help] [-configdir] [-enginesdir] [-modulesdir ] [-dsoext] [-dirnamesep] [-listsep] [-seeds] [-cpusettings]

"},{"location":"man1/openssl-info/#description","title":"DESCRIPTION","text":"

This command is used to print out information about OpenSSL. The information is written exactly as it is with no extra text, which makes useful for scripts.

As a consequence, only one item may be chosen for each run of this command.

"},{"location":"man1/openssl-info/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-info/#history","title":"HISTORY","text":"

This command was added in OpenSSL 3.0.

"},{"location":"man1/openssl-info/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-kdf/","title":"openssl-kdf","text":""},{"location":"man1/openssl-kdf/#name","title":"NAME","text":"

openssl-kdf - perform Key Derivation Function operations

"},{"location":"man1/openssl-kdf/#synopsis","title":"SYNOPSIS","text":"

openssl kdf [-help] [-cipher] [-digest] [-mac] [-kdfopt nm:v] [-keylen num] [-out filename] [-binary] [-provider name] [-provider-path path] [-propquery propq] kdf_name

"},{"location":"man1/openssl-kdf/#description","title":"DESCRIPTION","text":"

The key derivation functions generate a derived key from either a secret or password.

"},{"location":"man1/openssl-kdf/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-kdf/#examples","title":"EXAMPLES","text":"

Use TLS1-PRF to create a hex-encoded derived key from a secret key and seed:

openssl kdf -keylen 16 -kdfopt digest:SHA2-256 -kdfopt key:secret \\\n            -kdfopt seed:seed TLS1-PRF\n

Use HKDF to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 10 -kdfopt digest:SHA2-256 -kdfopt key:secret \\\n            -kdfopt salt:salt -kdfopt info:label HKDF\n

Use SSKDF with KMAC to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 64 -kdfopt mac:KMAC-128 -kdfopt maclen:20 \\\n            -kdfopt hexkey:b74a149a161545 -kdfopt hexinfo:348a37a2 \\\n            -kdfopt hexsalt:3638271ccd68a2 SSKDF\n

Use SSKDF with HMAC to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 16 -kdfopt mac:HMAC -kdfopt digest:SHA2-256 \\\n            -kdfopt hexkey:b74a149a -kdfopt hexinfo:348a37a2 \\\n            -kdfopt hexsalt:3638271c SSKDF\n

Use SSKDF with Hash to create a hex-encoded derived key from a secret key, salt and info:

openssl kdf -keylen 14 -kdfopt digest:SHA2-256 \\\n            -kdfopt hexkey:6dbdc23f045488 \\\n            -kdfopt hexinfo:a1b2c3d4 SSKDF\n

Use SSHKDF to create a hex-encoded derived key from a secret key, hash and session_id:

openssl kdf -keylen 16 -kdfopt digest:SHA2-256 \\\n            -kdfopt hexkey:0102030405 \\\n            -kdfopt hexxcghash:06090A \\\n            -kdfopt hexsession_id:01020304 \\\n            -kdfopt type:A SSHKDF\n

Use PBKDF2 to create a hex-encoded derived key from a password and salt:

openssl kdf -keylen 32 -kdfopt digest:SHA256 -kdfopt pass:password \\\n            -kdfopt salt:salt -kdfopt iter:2 PBKDF2\n

Use scrypt to create a hex-encoded derived key from a password and salt:

openssl kdf -keylen 64 -kdfopt pass:password -kdfopt salt:NaCl \\\n            -kdfopt n:1024 -kdfopt r:8 -kdfopt p:16 \\\n            -kdfopt maxmem_bytes:10485760 SCRYPT\n
"},{"location":"man1/openssl-kdf/#notes","title":"NOTES","text":"

The KDF mechanisms that are available will depend on the options used when building OpenSSL.

"},{"location":"man1/openssl-kdf/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyutl(1), EVP_KDF(3), EVP_KDF-SCRYPT(7), EVP_KDF-TLS1_PRF(7), EVP_KDF-PBKDF2(7), EVP_KDF-HKDF(7), EVP_KDF-SS(7), EVP_KDF-SSHKDF(7), EVP_KDF-X942-ASN1(7), EVP_KDF-X942-CONCAT(7), EVP_KDF-X963(7)

"},{"location":"man1/openssl-kdf/#history","title":"HISTORY","text":"

Added in OpenSSL 3.0

"},{"location":"man1/openssl-kdf/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-list/","title":"openssl-list","text":""},{"location":"man1/openssl-list/#name","title":"NAME","text":"

openssl-list - list algorithms and features

"},{"location":"man1/openssl-list/#synopsis","title":"SYNOPSIS","text":"

openssl list [-help] [-verbose] [-select name] [-1] [-all-algorithms] [-commands] [-standard-commands] [-digest-algorithms] [-digest-commands] [-kdf-algorithms] [-mac-algorithms] [-random-instances] [-random-generators] [-cipher-algorithms] [-cipher-commands] [-encoders] [-decoders] [-key-managers] [-key-exchange-algorithms] [-kem-algorithms] [-signature-algorithms] [-asymcipher-algorithms] [-public-key-algorithms] [-public-key-methods] [-store-loaders] [-providers] [-engines] [-disabled] [-objects] [-options command] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-list/#description","title":"DESCRIPTION","text":"

This command is used to generate list of algorithms or disabled features.

"},{"location":"man1/openssl-list/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-list/#display-of-algorithm-names","title":"Display of algorithm names","text":"

Algorithm names may be displayed in one of two manners:

"},{"location":"man1/openssl-list/#history","title":"HISTORY","text":"

The -engines, -digest-commands, and -cipher-commands options were deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-list/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-mac/","title":"openssl-mac","text":""},{"location":"man1/openssl-mac/#name","title":"NAME","text":"

openssl-mac - perform Message Authentication Code operations

"},{"location":"man1/openssl-mac/#synopsis","title":"SYNOPSIS","text":"

openssl mac [-help] [-cipher] [-digest] [-macopt] [-in filename] [-out filename] [-binary] [-provider name] [-provider-path path] [-propquery propq] mac_name

"},{"location":"man1/openssl-mac/#description","title":"DESCRIPTION","text":"

The message authentication code functions output the MAC of a supplied input file.

"},{"location":"man1/openssl-mac/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-mac/#examples","title":"EXAMPLES","text":"

To create a hex-encoded HMAC-SHA1 MAC of a file and write to stdout:

openssl mac -digest SHA1 \\\n        -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \\\n        -in msg.bin HMAC\n

To create a SipHash MAC from a file with a binary file output:

openssl mac -macopt hexkey:000102030405060708090A0B0C0D0E0F \\\n        -in msg.bin -out out.bin -binary SipHash\n

To create a hex-encoded CMAC-AES-128-CBC MAC from a file:

openssl mac -cipher AES-128-CBC \\\n        -macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B \\\n        -in msg.bin CMAC\n

To create a hex-encoded KMAC128 MAC from a file with a Customisation String 'Tag' and output length of 16:

openssl mac -macopt custom:Tag -macopt hexkey:40414243444546 \\\n        -macopt size:16 -in msg.bin KMAC128\n

To create a hex-encoded GMAC-AES-128-GCM with a IV from a file:

openssl mac -cipher AES-128-GCM -macopt hexiv:E0E00F19FED7BA0136A797F3 \\\n        -macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B -in msg.bin GMAC\n
"},{"location":"man1/openssl-mac/#notes","title":"NOTES","text":"

The MAC mechanisms that are available will depend on the options used when building OpenSSL. Use openssl list -mac-algorithms to list them.

"},{"location":"man1/openssl-mac/#see-also","title":"SEE ALSO","text":"

openssl(1), EVP_MAC(3), EVP_MAC-CMAC(7), EVP_MAC-GMAC(7), EVP_MAC-HMAC(7), EVP_MAC-KMAC(7), EVP_MAC-Siphash(7), EVP_MAC-Poly1305(7)

"},{"location":"man1/openssl-mac/#copyright","title":"COPYRIGHT","text":"

Copyright 2018-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-namedisplay-options/","title":"openssl-namedisplay-options","text":""},{"location":"man1/openssl-namedisplay-options/#name","title":"NAME","text":"

openssl-namedisplay-options - Distinguished name display options

"},{"location":"man1/openssl-namedisplay-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-namedisplay-options/#description","title":"DESCRIPTION","text":"

OpenSSL provides fine-grain control over how the subject and issuer DN's are displayed. This is specified by using the -nameopt option, which takes a comma-separated list of options from the following set. An option may be preceded by a minus sign, -, to turn it off. The default value is utf8,sep_comma_plus_space. The first four are the most commonly used.

"},{"location":"man1/openssl-namedisplay-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-namedisplay-options/#name-format-option-arguments","title":"Name Format Option Arguments","text":"

The DN output format can be fine tuned with the following flags.

"},{"location":"man1/openssl-namedisplay-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-nseq/","title":"openssl-nseq","text":""},{"location":"man1/openssl-nseq/#name","title":"NAME","text":"

openssl-nseq - create or examine a Netscape certificate sequence

"},{"location":"man1/openssl-nseq/#synopsis","title":"SYNOPSIS","text":"

openssl nseq [-help] [-in filename] [-out filename] [-toseq] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-nseq/#description","title":"DESCRIPTION","text":"

This command takes a file containing a Netscape certificate sequence and prints out the certificates contained in it or takes a file of certificates and converts it into a Netscape certificate sequence.

A Netscape certificate sequence is an old Netscape-specific format that can be sometimes be sent to browsers as an alternative to the standard PKCS#7 format when several certificates are sent to the browser, for example during certificate enrollment. It was also used by Netscape certificate server.

"},{"location":"man1/openssl-nseq/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-nseq/#examples","title":"EXAMPLES","text":"

Output the certificates in a Netscape certificate sequence

openssl nseq -in nseq.pem -out certs.pem\n

Create a Netscape certificate sequence

openssl nseq -in certs.pem -toseq -out nseq.pem\n
"},{"location":"man1/openssl-nseq/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-ocsp/","title":"openssl-ocsp","text":""},{"location":"man1/openssl-ocsp/#name","title":"NAME","text":"

openssl-ocsp - Online Certificate Status Protocol command

"},{"location":"man1/openssl-ocsp/#synopsis","title":"SYNOPSIS","text":""},{"location":"man1/openssl-ocsp/#ocsp-client","title":"OCSP Client","text":"

openssl ocsp [-help] [-out file] [-issuer file] [-cert file] [-no_certs] [-serial n] [-signer file] [-signkey file] [-sign_other file] [-nonce] [-no_nonce] [-req_text] [-resp_text] [-text] [-reqout file] [-respout file] [-reqin file] [-respin file] [-url URL] [-host host:port] [-path pathname] [-proxy [http[s]://][userinfo@]host[:port][/path]] [-no_proxy addresses] [-header] [-timeout seconds] [-VAfile file] [-validity_period n] [-status_age n] [-noverify] [-verify_other file] [-trust_other] [-no_intern] [-no_signature_verify] [-no_cert_verify] [-no_chain] [-no_cert_checks] [-no_explicit] [-port num] [-ignore_err]

"},{"location":"man1/openssl-ocsp/#ocsp-server","title":"OCSP Server","text":"

openssl ocsp [-index file] [-CA file] [-rsigner file] [-rkey file] [-passin arg] [-rother file] [-rsigopt nm:v] [-rmd digest] [-badsig] [-resp_no_certs] [-nmin n] [-ndays n] [-resp_key_id] [-nrequest n] [-multi process-count] [-rcid digest] [-digest] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ocsp/#description","title":"DESCRIPTION","text":"

The Online Certificate Status Protocol (OCSP) enables applications to determine the (revocation) state of an identified certificate (RFC 2560).

This command performs many common OCSP tasks. It can be used to print out requests and responses, create requests and send queries to an OCSP responder and behave like a mini OCSP server itself.

"},{"location":"man1/openssl-ocsp/#options","title":"OPTIONS","text":"

This command operates as either a client or a server. The options are described below, divided into those two modes.

"},{"location":"man1/openssl-ocsp/#ocsp-client-options","title":"OCSP Client Options","text":""},{"location":"man1/openssl-ocsp/#ocsp-server-options","title":"OCSP Server Options","text":""},{"location":"man1/openssl-ocsp/#ocsp-response-verification","title":"OCSP RESPONSE VERIFICATION","text":"

OCSP Response follows the rules specified in RFC2560.

Initially the OCSP responder certificate is located and the signature on the OCSP request checked using the responder certificate's public key.

Then a normal certificate verify is performed on the OCSP responder certificate building up a certificate chain in the process. The locations of the trusted certificates used to build the chain can be specified by the -CAfile, -CApath or -CAstore options or they will be looked for in the standard OpenSSL certificates directory.

If the initial verify fails then the OCSP verify process halts with an error.

Otherwise the issuing CA certificate in the request is compared to the OCSP responder certificate: if there is a match then the OCSP verify succeeds.

Otherwise the OCSP responder certificate's CA is checked against the issuing CA certificate in the request. If there is a match and the OCSPSigning extended key usage is present in the OCSP responder certificate then the OCSP verify succeeds.

Otherwise, if -no_explicit is not set the root CA of the OCSP responders CA is checked to see if it is trusted for OCSP signing. If it is the OCSP verify succeeds.

If none of these checks is successful then the OCSP verify fails.

What this effectively means if that if the OCSP responder certificate is authorised directly by the CA it is issuing revocation information about (and it is correctly configured) then verification will succeed.

If the OCSP responder is a \"global responder\" which can give details about multiple CAs and has its own separate certificate chain then its root CA can be trusted for OCSP signing. For example:

openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem\n

Alternatively the responder certificate itself can be explicitly trusted with the -VAfile option.

"},{"location":"man1/openssl-ocsp/#notes","title":"NOTES","text":"

As noted, most of the verify options are for testing or debugging purposes. Normally only the -CApath, -CAfile, -CAstore and (if the responder is a 'global VA') -VAfile options need to be used.

The OCSP server is only useful for test and demonstration purposes: it is not really usable as a full OCSP responder. It contains only a very simple HTTP request handling and can only handle the POST form of OCSP queries. It also handles requests serially meaning it cannot respond to new requests until it has processed the current one. The text index file format of revocation is also inefficient for large quantities of revocation data.

It is possible to run this command in responder mode via a CGI script using the -reqin and -respout options.

"},{"location":"man1/openssl-ocsp/#examples","title":"EXAMPLES","text":"

Create an OCSP request and write it to a file:

openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der\n

Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the response to a file, print it out in text form, and verify the response:

openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \\\n    -url http://ocsp.myhost.com/ -resp_text -respout resp.der\n

Read in an OCSP response and print out text form:

openssl ocsp -respin resp.der -text -noverify\n

OCSP server on port 8888 using a standard ca configuration, and a separate responder certificate. All requests and responses are printed to a file.

openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem\n       -text -out log.txt\n

As above but exit after processing one request:

openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem\n    -nrequest 1\n

Query status information using an internally generated request:

openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem\n    -issuer demoCA/cacert.pem -serial 1\n

Query status information using request read from a file, and write the response to a second file.

openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem\n    -reqin req.der -respout resp.der\n
"},{"location":"man1/openssl-ocsp/#history","title":"HISTORY","text":"

The -no_alt_chains option was added in OpenSSL 1.1.0.

"},{"location":"man1/openssl-ocsp/#copyright","title":"COPYRIGHT","text":"

Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-passphrase-options/","title":"openssl-passphrase-options","text":""},{"location":"man1/openssl-passphrase-options/#name","title":"NAME","text":"

openssl-passphrase-options - Pass phrase options

"},{"location":"man1/openssl-passphrase-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-passphrase-options/#description","title":"DESCRIPTION","text":"

Several OpenSSL commands accept password arguments, typically using -passin and -passout for input and output passwords respectively. These allow the password to be obtained from a variety of sources. Both of these options take a single argument whose format is described below. If no password argument is given and a password is required then the user is prompted to enter one: this will typically be read from the current terminal with echoing turned off.

Note that character encoding may be relevant, please see passphrase-encoding(7).

"},{"location":"man1/openssl-passphrase-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-passphrase-options/#pass-phrase-option-arguments","title":"Pass Phrase Option Arguments","text":"

Pass phrase arguments can be formatted as follows.

"},{"location":"man1/openssl-passphrase-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-passwd/","title":"openssl-passwd","text":""},{"location":"man1/openssl-passwd/#name","title":"NAME","text":"

openssl-passwd - compute password hashes

"},{"location":"man1/openssl-passwd/#synopsis","title":"SYNOPSIS","text":"

openssl passwd [-help] [-1] [-apr1] [-aixmd5] [-5] [-6] [-salt string] [-in file] [-stdin] [-noverify] [-quiet] [-table] [-reverse] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [password]

"},{"location":"man1/openssl-passwd/#description","title":"DESCRIPTION","text":"

This command computes the hash of a password typed at run-time or the hash of each password in a list. The password list is taken from the named file for option -in, from stdin for option -stdin, or from the command line, or from the terminal otherwise.

"},{"location":"man1/openssl-passwd/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-passwd/#examples","title":"EXAMPLES","text":"
% openssl passwd -1 -salt xxxxxxxx password\n$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.\n\n% openssl passwd -apr1 -salt xxxxxxxx password\n$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0\n\n% openssl passwd -aixmd5 -salt xxxxxxxx password\nxxxxxxxx$8Oaipk/GPKhC64w/YVeFD/\n
"},{"location":"man1/openssl-passwd/#history","title":"HISTORY","text":"

The -crypt option was removed in OpenSSL 3.0.

"},{"location":"man1/openssl-passwd/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-pkcs12/","title":"openssl-pkcs12","text":""},{"location":"man1/openssl-pkcs12/#name","title":"NAME","text":"

openssl-pkcs12 - PKCS#12 file command

"},{"location":"man1/openssl-pkcs12/#synopsis","title":"SYNOPSIS","text":"

openssl pkcs12 [-help] [-passin arg] [-passout arg] [-password arg] [-twopass] [-in filename|uri] [-out filename] [-nokeys] [-nocerts] [-noout] [-legacy] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-rand files] [-writerand file]

PKCS#12 input (parsing) options: [-info] [-nomacver] [-clcerts] [-cacerts]

[-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-noenc] [-nodes]

PKCS#12 output (export) options:

[-export] [-inkey filename|uri] [-certfile filename] [-passcerts arg] [-chain] [-untrusted filename] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-name name] [-caname name] [-CSP name] [-LMK] [-keyex] [-keysig] [-keypbe cipher] [-certpbe cipher] [-descert] [-macalg digest] [-iter count] [-noiter] [-nomaciter] [-maciter] [-macsaltlen] [-nomac] [-jdktrust usage]

"},{"location":"man1/openssl-pkcs12/#description","title":"DESCRIPTION","text":"

This command allows PKCS#12 files (sometimes referred to as PFX files) to be created and parsed. PKCS#12 files are used by several programs including Netscape, MSIE and MS Outlook.

"},{"location":"man1/openssl-pkcs12/#options","title":"OPTIONS","text":"

There are a lot of options the meaning of some depends of whether a PKCS#12 file is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 file can be created by using the -export option (see below). The PKCS#12 export encryption and MAC options such as -certpbe and -iter and many further options such as -chain are relevant only with -export. Conversely, the options regarding encryption of private keys when outputting PKCS#12 input are relevant only when the -export option is not given.

The default encryption algorithm is AES-256-CBC with PBKDF2 for key derivation.

When encountering problems loading legacy PKCS#12 files that involve, for example, RC2-40-CBC, try using the -legacy option and, if needed, the -provider-path option.

"},{"location":"man1/openssl-pkcs12/#pkcs12-input-parsing-options","title":"PKCS#12 input (parsing) options","text":""},{"location":"man1/openssl-pkcs12/#pkcs12-output-export-options","title":"PKCS#12 output (export) options","text":""},{"location":"man1/openssl-pkcs12/#notes","title":"NOTES","text":"

Although there are a large number of options most of them are very rarely used. For PKCS#12 file parsing only -in and -out need to be used for PKCS#12 file creation -export and -name are also used.

If none of the -clcerts, -cacerts or -nocerts options are present then all certificates will be output in the order they appear in the input PKCS#12 files. There is no guarantee that the first certificate present is the one corresponding to the private key. Certain software which tries to get a private key and the corresponding certificate might assume that the first certificate in the file is the one corresponding to the private key, but that may not always be the case. Using the -clcerts option will solve this problem by only outputting the certificate corresponding to the private key. If the CA certificates are required then they can be output to a separate file using the -nokeys -cacerts options to just output CA certificates.

The -keypbe and -certpbe algorithms allow the precise encryption algorithms for private keys and certificates to be specified. Normally the defaults are fine but occasionally software can't handle triple DES encrypted private keys, then the option -keypbe PBE-SHA1-RC2-40 can be used to reduce the private key encryption to 40 bit RC2. A complete description of all algorithms is contained in openssl-pkcs8(1).

Prior 1.1 release passwords containing non-ASCII characters were encoded in non-compliant manner, which limited interoperability, in first hand with Windows. But switching to standard-compliant password encoding poses problem accessing old data protected with broken encoding. For this reason even legacy encodings is attempted when reading the data. If you use PKCS#12 files in production application you are advised to convert the data, because implemented heuristic approach is not MT-safe, its sole goal is to facilitate the data upgrade with this command.

"},{"location":"man1/openssl-pkcs12/#examples","title":"EXAMPLES","text":"

Parse a PKCS#12 file and output it to a PEM file:

openssl pkcs12 -in file.p12 -out file.pem\n

Output only client certificates to a file:

openssl pkcs12 -in file.p12 -clcerts -out file.pem\n

Don't encrypt the private key:

openssl pkcs12 -in file.p12 -out file.pem -noenc\n

Print some info about a PKCS#12 file:

openssl pkcs12 -in file.p12 -info -noout\n

Print some info about a PKCS#12 file in legacy mode:

openssl pkcs12 -in file.p12 -info -noout -legacy\n

Create a PKCS#12 file from a PEM file that may contain a key and certificates:

openssl pkcs12 -export -in file.pem -out file.p12 -name \"My PSE\"\n

Include some extra certificates:

openssl pkcs12 -export -in file.pem -out file.p12 -name \"My PSE\" \\\n -certfile othercerts.pem\n

Export a PKCS#12 file with data from a certificate PEM file and from a further PEM file containing a key, with default algorithms as in the legacy provider:

openssl pkcs12 -export -in cert.pem -inkey key.pem -out file.p12 -legacy\n
"},{"location":"man1/openssl-pkcs12/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkcs8(1), ossl_store-file(7)

"},{"location":"man1/openssl-pkcs12/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0. The -nodes option was deprecated in OpenSSL 3.0, too; use -noenc instead.

"},{"location":"man1/openssl-pkcs12/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-pkcs7/","title":"openssl-pkcs7","text":""},{"location":"man1/openssl-pkcs7/#name","title":"NAME","text":"

openssl-pkcs7 - PKCS#7 command

"},{"location":"man1/openssl-pkcs7/#synopsis","title":"SYNOPSIS","text":"

openssl pkcs7 [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-out filename] [-print] [-print_certs] [-quiet] [-text] [-noout] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-pkcs7/#description","title":"DESCRIPTION","text":"

This command processes PKCS#7 files. Note that it only understands PKCS#7 v 1.5 as specified in IETF RFC 2315. It cannot currently parse CMS as described in IETF RFC 2630.

"},{"location":"man1/openssl-pkcs7/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkcs7/#examples","title":"EXAMPLES","text":"

Convert a PKCS#7 file from PEM to DER:

openssl pkcs7 -in file.pem -outform DER -out file.der\n

Output all certificates in a file:

openssl pkcs7 -in file.pem -print_certs -out certs.pem\n
"},{"location":"man1/openssl-pkcs7/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-crl2pkcs7(1)

"},{"location":"man1/openssl-pkcs7/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkcs7/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-pkcs8/","title":"openssl-pkcs8","text":""},{"location":"man1/openssl-pkcs8/#name","title":"NAME","text":"

openssl-pkcs8 - PKCS#8 format private key conversion command

"},{"location":"man1/openssl-pkcs8/#synopsis","title":"SYNOPSIS","text":"

openssl pkcs8 [-help] [-topk8] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-passin arg] [-out filename] [-passout arg] [-iter count] [-noiter] [-nocrypt] [-traditional] [-v2 alg] [-v2prf alg] [-v1 alg] [-scrypt] [-scrypt_N N] [-scrypt_r r] [-scrypt_p p] [-saltlen size] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-pkcs8/#description","title":"DESCRIPTION","text":"

This command processes private keys in PKCS#8 format. It can handle both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.

"},{"location":"man1/openssl-pkcs8/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkcs8/#notes","title":"NOTES","text":"

By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit AES with HMAC and SHA256 is used.

Some older implementations do not support PKCS#5 v2.0 format and require the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak encryption algorithms such as 56 bit DES.

Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration counts are more secure that those encrypted using the traditional SSLeay compatible formats. So if additional security is considered important the keys should be converted.

It is possible to write out DER encoded encrypted private keys in PKCS#8 format because the encryption details are included at an ASN1 level whereas the traditional format includes them at a PEM level.

"},{"location":"man1/openssl-pkcs8/#pkcs5-v15-and-pkcs12-algorithms","title":"PKCS#5 V1.5 AND PKCS#12 ALGORITHMS","text":"

Various algorithms can be used with the -v1 command line option, including PKCS#5 v1.5 and PKCS#12. These are described in more detail below.

"},{"location":"man1/openssl-pkcs8/#examples","title":"EXAMPLES","text":"

Convert a private key to PKCS#8 format using default parameters (AES with 256 bit key and hmacWithSHA256):

openssl pkcs8 -in key.pem -topk8 -out enckey.pem\n

Convert a private key to PKCS#8 unencrypted format:

openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem\n

Convert a private key to PKCS#5 v2.0 format using triple DES:

openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem\n

Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC mode and hmacWithSHA512 PRF:

openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem\n

Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm (DES):

openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem\n

Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm (3DES):

openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES\n

Read a DER unencrypted PKCS#8 format private key:

openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem\n

Convert a private key from any PKCS#8 encrypted format to traditional format:

openssl pkcs8 -in pk8.pem -traditional -out key.pem\n

Convert a private key to PKCS#8 format, encrypting with AES-256 and with one million iterations of the password:

openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem\n
"},{"location":"man1/openssl-pkcs8/#standards","title":"STANDARDS","text":"

Test vectors from this PKCS#5 v2.0 implementation were posted to the pkcs-tng mailing list using triple DES, DES and RC2 with high iteration counts, several people confirmed that they could decrypt the private keys produced and therefore, it can be assumed that the PKCS#5 v2.0 implementation is reasonably accurate at least as far as these algorithms are concerned.

The format of PKCS#8 DSA (and other) private keys is not well documented: it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA PKCS#8 private key format complies with this standard.

"},{"location":"man1/openssl-pkcs8/#bugs","title":"BUGS","text":"

There should be an option that prints out the encryption algorithm in use and other details such as the iteration count.

"},{"location":"man1/openssl-pkcs8/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-dsa(1), openssl-rsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-pkcs8/#history","title":"HISTORY","text":"

The -iter option was added in OpenSSL 1.1.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkcs8/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-pkey/","title":"openssl-pkey","text":""},{"location":"man1/openssl-pkey/#name","title":"NAME","text":"

openssl-pkey - public or private key processing command

"},{"location":"man1/openssl-pkey/#synopsis","title":"SYNOPSIS","text":"

openssl pkey [-help] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-check] [-pubcheck] [-in filename|uri] [-inform DER|PEM|P12|ENGINE] [-passin arg] [-pubin] [-out filename] [-outform DER|PEM] [-cipher] [-passout arg] [-traditional] [-pubout] [-noout] [-text] [-text_pub] [-ec_conv_form arg] [-ec_param_enc arg]

"},{"location":"man1/openssl-pkey/#description","title":"DESCRIPTION","text":"

This command processes public or private keys. They can be converted between various forms and their components printed.

"},{"location":"man1/openssl-pkey/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkey/#general-options","title":"General options","text":""},{"location":"man1/openssl-pkey/#input-options","title":"Input options","text":""},{"location":"man1/openssl-pkey/#output-options","title":"Output options","text":""},{"location":"man1/openssl-pkey/#examples","title":"EXAMPLES","text":"

To remove the pass phrase on a private key:

openssl pkey -in key.pem -out keyout.pem\n

To encrypt a private key using triple DES:

openssl pkey -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl pkey -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl pkey -in key.pem -text -noout\n

To print out the public components of a private key to standard output:

openssl pkey -in key.pem -text_pub -noout\n

To just output the public part of a private key:

openssl pkey -in key.pem -pubout -out pubkey.pem\n

To change the EC parameters encoding to explicit:

openssl pkey -in key.pem -ec_param_enc explicit -out keyout.pem\n

To change the EC point conversion form to compressed:

openssl pkey -in key.pem -ec_conv_form compressed -out keyout.pem\n
"},{"location":"man1/openssl-pkey/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-rsa(1), openssl-pkcs8(1), openssl-dsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-pkey/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkey/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-pkeyparam/","title":"openssl-pkeyparam","text":""},{"location":"man1/openssl-pkeyparam/#name","title":"NAME","text":"

openssl-pkeyparam - public key algorithm parameter processing command

"},{"location":"man1/openssl-pkeyparam/#synopsis","title":"SYNOPSIS","text":"

openssl pkeyparam [-help] [-in filename] [-out filename] [-text] [-noout] [-check] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-pkeyparam/#description","title":"DESCRIPTION","text":"

This command processes public key algorithm parameters. They can be checked for correctness and their components printed out.

"},{"location":"man1/openssl-pkeyparam/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkeyparam/#examples","title":"EXAMPLES","text":"

Print out text version of parameters:

openssl pkeyparam -in param.pem -text\n
"},{"location":"man1/openssl-pkeyparam/#notes","title":"NOTES","text":"

There are no -inform or -outform options for this command because only PEM format is supported because the key type is determined by the PEM headers.

"},{"location":"man1/openssl-pkeyparam/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-rsa(1), openssl-pkcs8(1), openssl-dsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-pkeyparam/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkeyparam/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-pkeyutl/","title":"openssl-pkeyutl","text":""},{"location":"man1/openssl-pkeyutl/#name","title":"NAME","text":"

openssl-pkeyutl - public key algorithm command

"},{"location":"man1/openssl-pkeyutl/#synopsis","title":"SYNOPSIS","text":"

openssl pkeyutl [-help] [-in file] [-rawin] [-digest algorithm] [-out file] [-sigfile file] [-inkey filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-peerkey file] [-peerform DER|PEM|P12|ENGINE] [-pubin] [-certin] [-rev] [-sign] [-verify] [-verifyrecover] [-encrypt] [-decrypt] [-derive] [-kdf algorithm] [-kdflen length] [-pkeyopt opt:value] [-pkeyopt_passin opt[:passarg]] [-hexdump] [-asn1parse] [-engine id] [-engine_impl] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-config configfile]

"},{"location":"man1/openssl-pkeyutl/#description","title":"DESCRIPTION","text":"

This command can be used to perform low-level public key operations using any supported algorithm.

"},{"location":"man1/openssl-pkeyutl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-pkeyutl/#notes","title":"NOTES","text":"

The operations and options supported vary according to the key algorithm and its implementation. The OpenSSL operations and options are indicated below.

Unless otherwise mentioned all algorithms support the digest:alg option which specifies the digest in use for sign, verify and verifyrecover operations. The value alg should represent a digest name as used in the EVP_get_digestbyname() function for example sha1. This value is not used to hash the input data. It is used (by some algorithms) for sanity-checking the lengths of data passed in and for creating the structures that make up the signature (e.g. DigestInfo in RSASSA PKCS#1 v1.5 signatures).

This command does not hash the input data (except where -rawin is used) but rather it will use the data directly as input to the signature algorithm. Depending on the key type, signature type, and mode of padding, the maximum acceptable lengths of input data differ. The signed data can't be longer than the key modulus with RSA. In case of ECDSA and DSA the data shouldn't be longer than the field size, otherwise it will be silently truncated to the field size. In any event the input size must not be larger than the largest supported digest size.

In other words, if the value of digest is sha1 the input should be the 20 bytes long binary encoding of the SHA-1 hash function output.

"},{"location":"man1/openssl-pkeyutl/#rsa-algorithm","title":"RSA ALGORITHM","text":"

The RSA algorithm generally supports the encrypt, decrypt, sign, verify and verifyrecover operations. However, some padding modes support only a subset of these operations. The following additional pkeyopt values are supported:

"},{"location":"man1/openssl-pkeyutl/#rsa-pss-algorithm","title":"RSA-PSS ALGORITHM","text":"

The RSA-PSS algorithm is a restricted version of the RSA algorithm which only supports the sign and verify operations with PSS padding. The following additional -pkeyopt values are supported:

"},{"location":"man1/openssl-pkeyutl/#dsa-algorithm","title":"DSA ALGORITHM","text":"

The DSA algorithm supports signing and verification operations only. Currently there are no additional -pkeyopt options other than digest. The SHA1 digest is assumed by default.

"},{"location":"man1/openssl-pkeyutl/#dh-algorithm","title":"DH ALGORITHM","text":"

The DH algorithm only supports the derivation operation and no additional -pkeyopt options.

"},{"location":"man1/openssl-pkeyutl/#ec-algorithm","title":"EC ALGORITHM","text":"

The EC algorithm supports sign, verify and derive operations. The sign and verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for the -pkeyopt digest option.

"},{"location":"man1/openssl-pkeyutl/#x25519-and-x448-algorithms","title":"X25519 AND X448 ALGORITHMS","text":"

The X25519 and X448 algorithms support key derivation only. Currently there are no additional options.

"},{"location":"man1/openssl-pkeyutl/#ed25519-and-ed448-algorithms","title":"ED25519 AND ED448 ALGORITHMS","text":"

These algorithms only support signing and verifying. OpenSSL only implements the \"pure\" variants of these algorithms so raw data can be passed directly to them without hashing them first. The option -rawin must be used with these algorithms with no -digest specified. Additionally OpenSSL only supports \"oneshot\" operation with these algorithms. This means that the entire file to be signed/verified must be read into memory before processing it. Signing or Verifying very large files should be avoided. Additionally the size of the file must be known for this to work. If the size of the file cannot be determined (for example if the input is stdin) then the sign or verify operation will fail.

"},{"location":"man1/openssl-pkeyutl/#sm2","title":"SM2","text":"

The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For the sign and verify operations, SM2 requires an Distinguishing ID string to be passed in. The following -pkeyopt value is supported:

"},{"location":"man1/openssl-pkeyutl/#examples","title":"EXAMPLES","text":"

Sign some data using a private key:

openssl pkeyutl -sign -in file -inkey key.pem -out sig\n

Recover the signed data (e.g. if an RSA key is used):

openssl pkeyutl -verifyrecover -in sig -inkey key.pem\n

Verify the signature (e.g. a DSA key):

openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem\n

Sign data using a message digest value (this is currently only valid for RSA):

openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256\n

Derive a shared secret value:

openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret\n

Hexdump 48 bytes of TLS1 PRF using digest SHA256 and shared secret and seed consisting of the single byte 0xFF:

openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \\\n   -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump\n

Derive a key using scrypt where the password is read from command line:

openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \\\n   -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1\n

Derive using the same algorithm, but read key from environment variable MYPASS:

openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \\\n   -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1\n

Sign some data using an SM2(7) private key and a specific ID:

openssl pkeyutl -sign -in file -inkey sm2.key -out sig -rawin -digest sm3 \\\n   -pkeyopt distid:someid\n

Verify some data using an SM2(7) certificate and a specific ID:

openssl pkeyutl -verify -certin -in file -inkey sm2.cert -sigfile sig \\\n   -rawin -digest sm3 -pkeyopt distid:someid\n

Decrypt some data using a private key with OAEP padding using SHA256:

openssl pkeyutl -decrypt -in file -inkey key.pem -out secret \\\n   -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256\n
"},{"location":"man1/openssl-pkeyutl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-genpkey(1), openssl-pkey(1), openssl-rsautl(1) openssl-dgst(1), openssl-rsa(1), openssl-genrsa(1), openssl-kdf(1) EVP_PKEY_CTX_set_hkdf_md(3), EVP_PKEY_CTX_set_tls1_prf_md(3),

"},{"location":"man1/openssl-pkeyutl/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-pkeyutl/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-prime/","title":"openssl-prime","text":""},{"location":"man1/openssl-prime/#name","title":"NAME","text":"

openssl-prime - compute prime numbers

"},{"location":"man1/openssl-prime/#synopsis","title":"SYNOPSIS","text":"

openssl prime [-help] [-hex] [-generate] [-bits num] [-safe] [-provider name] [-provider-path path] [-propquery propq] [-checks num] [number ...]

"},{"location":"man1/openssl-prime/#description","title":"DESCRIPTION","text":"

This command checks if the specified numbers are prime.

If no numbers are given on the command line, the -generate flag should be used to generate primes according to the requirements specified by the rest of the flags.

"},{"location":"man1/openssl-prime/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-prime/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-rand/","title":"openssl-rand","text":""},{"location":"man1/openssl-rand/#name","title":"NAME","text":"

openssl-rand - generate pseudo-random bytes

"},{"location":"man1/openssl-rand/#synopsis","title":"SYNOPSIS","text":"

openssl rand [-help] [-out file] [-base64] [-hex] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] num[K|M|G|T]

"},{"location":"man1/openssl-rand/#description","title":"DESCRIPTION","text":"

This command generates num random bytes using a cryptographically secure pseudo random number generator (CSPRNG). A suffix [K|M|G|T] may be appended to the num value to indicate the requested value be scaled as a multiple of KiB/MiB/GiB/TiB respectively. Note that suffixes are case sensitive, and that the suffixes represent binary multiples (K = 1024 bytes, M = 1024*1024 bytes, etc).

The string 'max' may be substituted for a numerical value in num, to request the maximum number of bytes the CSPRNG can produce per instantiation. Currently, this is restricted to 2^61 bytes as per NIST SP 800-90C.

The random bytes are generated using the RAND_bytes(3) function, which provides a security level of 256 bits, provided it managed to seed itself successfully from a trusted operating system entropy source. Otherwise, the command will fail with a nonzero error code. For more details, see RAND_bytes(3), RAND(7), and EVP_RAND(7).

"},{"location":"man1/openssl-rand/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rand/#see-also","title":"SEE ALSO","text":"

openssl(1), RAND_bytes(3), RAND(7), EVP_RAND(7)

"},{"location":"man1/openssl-rand/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-rand/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-rehash/","title":"openssl-rehash","text":""},{"location":"man1/openssl-rehash/#name","title":"NAME","text":"

openssl-rehash, c_rehash - Create symbolic links to files named by the hash values

"},{"location":"man1/openssl-rehash/#synopsis","title":"SYNOPSIS","text":"

openssl rehash [-h] [-help] [-old] [-compat] [-n] [-v] [-provider name] [-provider-path path] [-propquery propq] [directory] ...

c_rehash [-h] [-help] [-old] [-n] [-v] [-provider name] [-provider-path path] [-propquery propq] [directory] ...

"},{"location":"man1/openssl-rehash/#description","title":"DESCRIPTION","text":"

This command is generally equivalent to the external script c_rehash, except for minor differences noted below.

openssl rehash scans directories and calculates a hash value of each .pem, .crt, .cer, or .crl file in the specified directory list and creates symbolic links for each file, where the name of the link is the hash value. (If the platform does not support symbolic links, a copy is made.) This command is useful as many programs that use OpenSSL require directories to be set up like this in order to find certificates.

If any directories are named on the command line, then those are processed in turn. If not, then the SSL_CERT_DIR environment variable is consulted; this should be a colon-separated list of directories, like the Unix PATH variable. If that is not set then the default directory (installation-specific but often /usr/local/ssl/certs) is processed.

In order for a directory to be processed, the user must have write permissions on that directory, otherwise an error will be generated.

The links created are of the form HHHHHHHH.D, where each H is a hexadecimal character and D is a single decimal digit. When a directory is processed, all links in it that have a name in that syntax are first removed, even if they are being used for some other purpose. To skip the removal step, use the -n flag. Hashes for CRL's look similar except the letter r appears after the period, like this: HHHHHHHH.rD.

Multiple objects may have the same hash; they will be indicated by incrementing the D value. Duplicates are found by comparing the full SHA-1 fingerprint. A warning will be displayed if a duplicate is found.

A warning will also be displayed if there are files that cannot be parsed as either a certificate or a CRL or if more than one such object appears in the file.

"},{"location":"man1/openssl-rehash/#script-configuration","title":"Script Configuration","text":"

The c_rehash script uses the openssl program to compute the hashes and fingerprints. If not found in the user's PATH, then set the OPENSSL environment variable to the full pathname. Any program can be used, it will be invoked as follows for either a certificate or CRL:

$OPENSSL x509 -hash -fingerprint -noout -in FILENAME\n$OPENSSL crl -hash -fingerprint -noout -in FILENAME\n

where FILENAME is the filename. It must output the hash of the file on the first line, and the fingerprint on the second, optionally prefixed with some text and an equals sign.

"},{"location":"man1/openssl-rehash/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rehash/#environment","title":"ENVIRONMENT","text":""},{"location":"man1/openssl-rehash/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-crl(1), openssl-x509(1)

"},{"location":"man1/openssl-rehash/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-req/","title":"openssl-req","text":""},{"location":"man1/openssl-req/#name","title":"NAME","text":"

openssl-req - PKCS#10 certificate request and certificate generating command

"},{"location":"man1/openssl-req/#synopsis","title":"SYNOPSIS","text":"

openssl req [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-passin arg] [-out filename] [-passout arg] [-text] [-pubkey] [-noout] [-verify] [-modulus] [-new] [-newkey arg] [-pkeyopt opt:value] [-noenc] [-nodes] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-keyout filename] [-keygen_engine id] [-digest] [-config filename] [-section name] [-x509] [-x509v1] [-CA filename|uri] [-CAkey filename|uri] [-not_before date] [-not_after date] [-days n] [-set_serial n] [-newhdr] [-copy_extensions arg] [-extensions section] [-reqexts section] [-addext ext] [-precert] [-utf8] [-reqopt] [-subject] [-subj arg] [-multivalue-rdn] [-sigopt nm:v] [-vfyopt nm:v] [-batch] [-verbose] [-quiet] [-nameopt option] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-req/#description","title":"DESCRIPTION","text":"

This command primarily creates and processes certificate requests (CSRs) in PKCS#10 format. It can additionally create self-signed certificates for use as root CAs for example.

"},{"location":"man1/openssl-req/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-req/#configuration-file-format","title":"CONFIGURATION FILE FORMAT","text":"

The configuration options are specified in the req section of the configuration file. An alternate name be specified by using the -section option. As with all configuration files, if no value is specified in the specific section then the initial unnamed or default section is searched too.

The options available are described in detail below.

"},{"location":"man1/openssl-req/#distinguished-name-and-attribute-section-format","title":"DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT","text":"

There are two separate formats for the distinguished name and attribute sections. If the prompt option is set to no then these sections just consist of field names and values: for example,

CN=My Name\nOU=My Organization\nemailAddress=someone@somewhere.org\n

This allows external programs (e.g. GUI based) to generate a template file with all the field names and values and just pass it to this command. An example of this kind of configuration file is contained in the EXAMPLES section.

Alternatively if the prompt option is absent or not set to no then the file contains field prompting information. It consists of lines of the form:

fieldName=\"prompt\"\nfieldName_default=\"default field value\"\nfieldName_min= 2\nfieldName_max= 4\n

\"fieldName\" is the field name being used, for example commonName (or CN). The \"prompt\" string is used to ask the user to enter the relevant details. If the user enters nothing then the default value is used if no default value is present then the field is omitted. A field can still be omitted if a default value is present if the user just enters the '.' character.

The number of characters entered must be between the fieldName_min and fieldName_max limits: there may be additional restrictions based on the field being used (for example countryName can only ever be two characters long and must fit in a PrintableString).

Some fields (such as organizationName) can be used more than once in a DN. This presents a problem because configuration files will not recognize the same name occurring twice. To avoid this problem if the fieldName contains some characters followed by a full stop they will be ignored. So for example a second organizationName can be input by calling it \"1.organizationName\".

The actual permitted field names are any object identifier short or long names. These are compiled into OpenSSL and include the usual values such as commonName, countryName, localityName, organizationName, organizationalUnitName, stateOrProvinceName. Additionally emailAddress is included as well as name, surname, givenName, initials, and dnQualifier.

Additional object identifiers can be defined with the oid_file or oid_section options in the configuration file. Any additional fields will be treated as though they were a DirectoryString.

"},{"location":"man1/openssl-req/#examples","title":"EXAMPLES","text":"

Examine and verify certificate request:

openssl req -in req.pem -text -verify -noout\n

Create a private key and then generate a certificate request from it:

openssl genrsa -out key.pem 2048\nopenssl req -new -key key.pem -out req.pem\n

The same but just using req:

openssl req -newkey rsa:2048 -keyout key.pem -out req.pem\n

Generate a self-signed root certificate:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem\n

Create an SM2 private key and then generate a certificate request from it:

openssl ecparam -genkey -name SM2 -out sm2.key\nopenssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt \"distid:1234567812345678\"\n

Examine and verify an SM2 certificate request:

openssl req -verify -in sm2.csr -sm3 -vfyopt \"distid:1234567812345678\"\n

Example of a file pointed to by the oid_file option:

1.2.3.4        shortName       A longer Name\n1.2.3.6        otherName       Other longer Name\n

Example of a section pointed to by oid_section making use of variable expansion:

testoid1=1.2.3.5\ntestoid2=${testoid1}.6\n

Sample configuration file prompting for field values:

[ req ]\ndefault_bits           = 2048\ndefault_keyfile        = privkey.pem\ndistinguished_name     = req_distinguished_name\nattributes             = req_attributes\nreq_extensions         = v3_ca\n\ndirstring_type = nobmp\n\n[ req_distinguished_name ]\ncountryName                    = Country Name (2 letter code)\ncountryName_default            = AU\ncountryName_min                = 2\ncountryName_max                = 2\n\nlocalityName                   = Locality Name (eg, city)\n\norganizationalUnitName         = Organizational Unit Name (eg, section)\n\ncommonName                     = Common Name (eg, YOUR name)\ncommonName_max                 = 64\n\nemailAddress                   = Email Address\nemailAddress_max               = 40\n\n[ req_attributes ]\nchallengePassword              = A challenge password\nchallengePassword_min          = 4\nchallengePassword_max          = 20\n\n[ v3_ca ]\n\nsubjectKeyIdentifier=hash\nauthorityKeyIdentifier=keyid:always,issuer:always\nbasicConstraints = critical, CA:true\n

Sample configuration containing all field values:

[ req ]\ndefault_bits           = 2048\ndefault_keyfile        = keyfile.pem\ndistinguished_name     = req_distinguished_name\nattributes             = req_attributes\nprompt                 = no\noutput_password        = mypass\n\n[ req_distinguished_name ]\nC                      = GB\nST                     = Test State or Province\nL                      = Test Locality\nO                      = Organization Name\nOU                     = Organizational Unit Name\nCN                     = Common Name\nemailAddress           = test@email.address\n\n[ req_attributes ]\nchallengePassword              = A challenge password\n

Example of giving the most common attributes (subject and extensions) on the command line:

openssl req -new -subj \"/C=GB/CN=foo\" \\\n                 -addext \"subjectAltName = DNS:foo.co.uk\" \\\n                 -addext \"certificatePolicies = 1.2.3.4\" \\\n                 -newkey rsa:2048 -keyout key.pem -out req.pem\n
"},{"location":"man1/openssl-req/#notes","title":"NOTES","text":"

The certificate requests generated by Xenroll with MSIE have extensions added. It includes the keyUsage extension which determines the type of key (signature only or general purpose) and any additional OIDs entered by the script in an extendedKeyUsage extension.

"},{"location":"man1/openssl-req/#diagnostics","title":"DIAGNOSTICS","text":"

The following messages are frequently asked about:

    Using configuration from /some/path/openssl.cnf\n    Unable to load config info\n

This is followed some time later by:

    unable to find 'distinguished_name' in config\n    problems making Certificate Request\n

The first error message is the clue: it can't find the configuration file! Certain operations (like examining a certificate request) don't need a configuration file so its use isn't enforced. Generation of certificates or requests however does need a configuration file. This could be regarded as a bug.

Another puzzling message is this:

    Attributes:\n        a0:00\n

this is displayed when no attributes are present and the request includes the correct empty SET OF structure (the DER encoding of which is 0xa0 0x00). If you just see:

    Attributes:\n

then the SET OF is missing and the encoding is technically invalid (but it is tolerated). See the description of the command line option -asn1-kludge for more information.

"},{"location":"man1/openssl-req/#bugs","title":"BUGS","text":"

OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. This can cause problems if you need characters that aren't available in PrintableStrings and you don't want to or can't use BMPStrings.

As a consequence of the T61String handling the only correct way to represent accented characters in OpenSSL is to use a BMPString: unfortunately Netscape currently chokes on these. If you have to use accented characters with Netscape and MSIE then you currently need to use the invalid T61String form.

The current prompting is not very friendly. It doesn't allow you to confirm what you've just entered. Other things like extensions in certificate requests are statically defined in the configuration file. Some of these: like an email address in subjectAltName should be input by the user.

"},{"location":"man1/openssl-req/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-x509(1), openssl-ca(1), openssl-genrsa(1), openssl-gendsa(1), config(5), x509v3_config(5)

"},{"location":"man1/openssl-req/#history","title":"HISTORY","text":"

The -section option was added in OpenSSL 3.0.0.

The -multivalue-rdn option has become obsolete in OpenSSL 3.0.0 and has no effect.

The -engine option was deprecated in OpenSSL 3.0. The <-nodes> option was deprecated in OpenSSL 3.0, too; use -noenc instead.

The -reqexts option has been made an alias of -extensions in OpenSSL 3.2.

Since OpenSSL 3.2, generated certificates bear X.509 version 3 unless -x509v1 is given, and key identifier extensions are included by default.

Since OpenSSL 3.3, the -verify option will exit with 1 on failure.

"},{"location":"man1/openssl-req/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-rsa/","title":"openssl-rsa","text":""},{"location":"man1/openssl-rsa/#name","title":"NAME","text":"

openssl-rsa - RSA key processing command

"},{"location":"man1/openssl-rsa/#synopsis","title":"SYNOPSIS","text":"

openssl rsa [-help] [-inform DER|PEM|P12|ENGINE] [-outform DER|PEM] [-in filename|uri] [-passin arg] [-out filename] [-passout arg] [-aes128] [-aes192] [-aes256] [-aria128] [-aria192] [-aria256] [-camellia128] [-camellia192] [-camellia256] [-des] [-des3] [-idea] [-text] [-noout] [-modulus] [-traditional] [-check] [-pubin] [-pubout] [-RSAPublicKey_in] [-RSAPublicKey_out] [-pvk-strong] [-pvk-weak] [-pvk-none] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-rsa/#description","title":"DESCRIPTION","text":"

This command processes RSA keys. They can be converted between various forms and their components printed out.

"},{"location":"man1/openssl-rsa/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rsa/#notes","title":"NOTES","text":"

The openssl-pkey(1) command is capable of performing all the operations this command can, as well as supporting other public key types.

"},{"location":"man1/openssl-rsa/#examples","title":"EXAMPLES","text":"

The documentation for the openssl-pkey(1) command contains examples equivalent to the ones listed here.

To remove the pass phrase on an RSA private key:

openssl rsa -in key.pem -out keyout.pem\n

To encrypt a private key using triple DES:

openssl rsa -in key.pem -des3 -out keyout.pem\n

To convert a private key from PEM to DER format:

openssl rsa -in key.pem -outform DER -out keyout.der\n

To print out the components of a private key to standard output:

openssl rsa -in key.pem -text -noout\n

To just output the public part of a private key:

openssl rsa -in key.pem -pubout -out pubkey.pem\n

Output the public part of a private key in RSAPublicKey format:

openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem\n
"},{"location":"man1/openssl-rsa/#bugs","title":"BUGS","text":"

There should be an option that automatically handles .key files, without having to manually edit them.

"},{"location":"man1/openssl-rsa/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkey(1), openssl-pkcs8(1), openssl-dsa(1), openssl-genrsa(1), openssl-gendsa(1)

"},{"location":"man1/openssl-rsa/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-rsa/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-rsautl/","title":"openssl-rsautl","text":""},{"location":"man1/openssl-rsautl/#name","title":"NAME","text":"

openssl-rsautl - RSA command

"},{"location":"man1/openssl-rsautl/#synopsis","title":"SYNOPSIS","text":"

openssl rsautl [-help] [-in file] [-passin arg] [-rev] [-out file] [-inkey filename|uri] [-keyform DER|PEM|P12|ENGINE] [-pubin] [-certin] [-sign] [-verify] [-encrypt] [-decrypt] [-pkcs] [-x931] [-oaep] [-raw] [-hexdump] [-asn1parse] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-rsautl/#description","title":"DESCRIPTION","text":"

This command has been deprecated. The openssl-pkeyutl(1) command should be used instead.

This command can be used to sign, verify, encrypt and decrypt data using the RSA algorithm.

"},{"location":"man1/openssl-rsautl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-rsautl/#notes","title":"NOTES","text":"

Since this command uses the RSA algorithm directly, it can only be used to sign or verify small pieces of data.

"},{"location":"man1/openssl-rsautl/#examples","title":"EXAMPLES","text":"

Examples equivalent to these can be found in the documentation for the non-deprecated openssl-pkeyutl(1) command.

Sign some data using a private key:

openssl rsautl -sign -in file -inkey key.pem -out sig\n

Recover the signed data

openssl rsautl -verify -in sig -inkey key.pem\n

Examine the raw signed data:

openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump\n\n0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................\n0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world\n

The PKCS#1 block formatting is evident from this. If this was done using encrypt and decrypt the block would have been of type 2 (the second byte) and random padding data visible instead of the 0xff bytes.

It is possible to analyse the signature of certificates using this command in conjunction with openssl-asn1parse(1). Consider the self signed example in certs/pca-cert.pem. Running openssl-asn1parse(1) as follows yields:

openssl asn1parse -in pca-cert.pem\n\n   0:d=0  hl=4 l= 742 cons: SEQUENCE\n   4:d=1  hl=4 l= 591 cons:  SEQUENCE\n   8:d=2  hl=2 l=   3 cons:   cont [ 0 ]\n  10:d=3  hl=2 l=   1 prim:    INTEGER           :02\n  13:d=2  hl=2 l=   1 prim:   INTEGER           :00\n  16:d=2  hl=2 l=  13 cons:   SEQUENCE\n  18:d=3  hl=2 l=   9 prim:    OBJECT            :md5WithRSAEncryption\n  29:d=3  hl=2 l=   0 prim:    NULL\n  31:d=2  hl=2 l=  92 cons:   SEQUENCE\n  33:d=3  hl=2 l=  11 cons:    SET\n  35:d=4  hl=2 l=   9 cons:     SEQUENCE\n  37:d=5  hl=2 l=   3 prim:      OBJECT            :countryName\n  42:d=5  hl=2 l=   2 prim:      PRINTABLESTRING   :AU\n ....\n 599:d=1  hl=2 l=  13 cons:  SEQUENCE\n 601:d=2  hl=2 l=   9 prim:   OBJECT            :md5WithRSAEncryption\n 612:d=2  hl=2 l=   0 prim:   NULL\n 614:d=1  hl=3 l= 129 prim:  BIT STRING\n

The final BIT STRING contains the actual signature. It can be extracted with:

openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614\n

The certificate public key can be extracted with:

openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem\n

The signature can be analysed with:

openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin\n\n   0:d=0  hl=2 l=  32 cons: SEQUENCE\n   2:d=1  hl=2 l=  12 cons:  SEQUENCE\n   4:d=2  hl=2 l=   8 prim:   OBJECT            :md5\n  14:d=2  hl=2 l=   0 prim:   NULL\n  16:d=1  hl=2 l=  16 prim:  OCTET STRING\n     0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5   .F...Js.7...H%..\n

This is the parsed version of an ASN1 DigestInfo structure. It can be seen that the digest used was md5. The actual part of the certificate that was signed can be extracted with:

openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4\n

and its digest computed with:

openssl md5 -c tbs\nMD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5\n

which it can be seen agrees with the recovered value above.

"},{"location":"man1/openssl-rsautl/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-pkeyutl(1), openssl-dgst(1), openssl-rsa(1), openssl-genrsa(1)

"},{"location":"man1/openssl-rsautl/#history","title":"HISTORY","text":"

This command was deprecated in OpenSSL 3.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-rsautl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-s_client/","title":"openssl-s_client","text":""},{"location":"man1/openssl-s_client/#name","title":"NAME","text":"

openssl-s_client - SSL/TLS client program

"},{"location":"man1/openssl-s_client/#synopsis","title":"SYNOPSIS","text":"

openssl s_client [-help] [-ssl_config section] [-connect host:port] [-host hostname] [-port port] [-bind host:port] [-proxy host:port] [-proxy_user userid] [-proxy_pass arg] [-unix path] [-4] [-6] [-quic] [-servername name] [-noservername] [-verify depth] [-verify_return_error] [-verify_quiet] [-verifyCAfile filename] [-verifyCApath dir] [-verifyCAstore uri] [-cert filename] [-certform DER|PEM|P12] [-cert_chain filename] [-build_chain] [-CRL filename] [-CRLform DER|PEM] [-crl_download] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-pass arg] [-chainCAfile filename] [-chainCApath directory] [-chainCAstore uri] [-requestCAfile filename] [-dane_tlsa_domain domain] [-dane_tlsa_rrdata rrdata] [-dane_ee_no_namechecks] [-reconnect] [-showcerts] [-prexit] [-no-interactive] [-debug] [-trace] [-nocommands] [-adv] [-security_debug] [-security_debug_verbose] [-msg] [-timeout] [-mtu size] [-no_etm] [-no_ems] [-keymatexport label] [-keymatexportlen len] [-msgfile filename] [-nbio_test] [-state] [-nbio] [-crlf] [-ign_eof] [-no_ign_eof] [-psk_identity identity] [-psk key] [-psk_session file] [-quiet] [-sctp] [-sctp_label_bug] [-fallback_scsv] [-async] [-maxfraglen len] [-max_send_frag] [-split_send_frag] [-max_pipelines] [-read_buf] [-ignore_unexpected_eof] [-bugs] [-no_tx_cert_comp] [-no_rx_cert_comp] [-comp] [-no_comp] [-brief] [-legacy_server_connect] [-no_legacy_server_connect] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-sigalgs sigalglist] [-curves curvelist] [-cipher cipherlist] [-ciphersuites val] [-serverpref] [-starttls protocol] [-name hostname] [-xmpphost hostname] [-name hostname] [-tlsextdebug] [-no_ticket] [-sess_out filename] [-serverinfo types] [-sess_in filename] [-serverinfo types] [-status] [-alpn protocols] [-nextprotoneg protocols] [-ct] [-noct] [-ctlogfile] [-keylogfile file] [-early_data file] [-enable_pha] [-use_srtp value] [-srpuser value] [-srppass value] [-srp_lateuser] [-srp_moregroups] [-srp_strength number] [-ktls] [-tfo] [-nameopt option] [-no_ssl3] [-no_tls1] [-no_tls1_1] [-no_tls1_2] [-no_tls1_3] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-dtls] [-dtls1] [-dtls1_2] [-xkey infile] [-xcert file] [-xchain file] [-xchain_build file] [-xcertform DER|PEM]> [-xkeyform DER|PEM]> [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-bugs] [-no_comp] [-comp] [-no_ticket] [-serverpref] [-client_renegotiation] [-legacy_renegotiation] [-no_renegotiation] [-no_resumption_on_reneg] [-legacy_server_connect] [-no_legacy_server_connect] [-no_etm] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-prioritize_chacha] [-strict] [-sigalgs algs] [-client_sigalgs algs] [-groups groups] [-curves curves] [-named_curve curve] [-cipher ciphers] [-ciphersuites 1.3ciphers] [-min_protocol minprot] [-max_protocol maxprot] [-record_padding padding] [-debug_broken_protocol] [-no_middlebox] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-engine id] [-ssl_client_engine id] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-enable_server_rpk] [-enable_client_rpk] [host:port]

"},{"location":"man1/openssl-s_client/#description","title":"DESCRIPTION","text":"

This command implements a generic SSL/TLS client which connects to a remote host using SSL/TLS. It is a very useful diagnostic tool for SSL servers.

"},{"location":"man1/openssl-s_client/#options","title":"OPTIONS","text":"

In addition to the options below, this command also supports the common and client only options documented in the \"Supported Command Line Commands\" section of the SSL_CONF_cmd(3) manual page.

"},{"location":"man1/openssl-s_client/#connected-commands-basic","title":"CONNECTED COMMANDS (BASIC)","text":"

If a connection is established with an SSL/TLS server then any data received from the server is displayed and any key presses will be sent to the server. If end of file is reached then the connection will be closed down.

When used interactively (which means neither -quiet nor -ign_eof have been given), and neither of -adv or -nocommands are given then \"Basic\" command mode is entered. In this mode certain commands are recognized which perform special operations. These commands are a letter which must appear at the start of a line. All further data after the initial letter on the line is ignored. The commands are listed below.

"},{"location":"man1/openssl-s_client/#connected-commands-advanced","title":"CONNECTED COMMANDS (ADVANCED)","text":"

If -adv has been given then \"advanced\" command mode is entered. As with basic mode, if a connection is established with an SSL/TLS server then any data received from the server is displayed and any key presses will be sent to the server. If end of file is reached then the connection will be closed down.

Special commands can be supplied by enclosing them in braces, e.g. \"{help}\" or \"{quit}\". These commands can appear anywhere in the text entered into s_client, but they are not sent to the server. Some commands can take an argument by ending the command name with \":\" and then providing the argument, e.g. \"{keyup:req}\". Some commands are only available when certain protocol versions have been negotiated.

If a newline appears at the end of a line entered into s_client then this is also sent to the server. If a command appears on a line on its own with no other text on the same line, then the newline is suppressed and not sent to the server.

The following commands are recognised.

"},{"location":"man1/openssl-s_client/#notes","title":"NOTES","text":"

This command can be used to debug SSL servers. To connect to an SSL HTTP server the command:

openssl s_client -connect servername:443\n

would typically be used (https uses port 443). If the connection succeeds then an HTTP command can be given such as \"GET /\" to retrieve a web page.

If the handshake fails then there are several possible causes, if it is nothing obvious like no client certificate then the -bugs, -ssl3, -tls1, -no_ssl3, -no_tls1 options can be tried in case it is a buggy server. In particular you should play with these options before submitting a bug report to an OpenSSL mailing list.

A frequent problem when attempting to get client certificates working is that a web client complains it has no certificates or gives an empty list to choose from. This is normally because the server is not sending the clients certificate authority in its \"acceptable CA list\" when it requests a certificate. By using this command, the CA list can be viewed and checked. However, some servers only request client authentication after a specific URL is requested. To obtain the list in this case it is necessary to use the -prexit option and send an HTTP request for an appropriate page.

If a certificate is specified on the command line using the -cert option it will not be used unless the server specifically requests a client certificate. Therefore, merely including a client certificate on the command line is no guarantee that the certificate works.

If there are problems verifying a server certificate then the -showcerts option can be used to show all the certificates sent by the server.

This command is a test tool and is designed to continue the handshake after any certificate verification errors. As a result it will accept any certificate chain (trusted or not) sent by the peer. Non-test applications should not do this as it makes them vulnerable to a MITM attack. This behaviour can be changed by with the -verify_return_error option: any verify errors are then returned aborting the handshake.

The -bind option may be useful if the server or a firewall requires connections to come from some particular address and or port.

"},{"location":"man1/openssl-s_client/#bugs","title":"BUGS","text":"

Because this program has a lot of options and also because some of the techniques used are rather old, the C source for this command is rather hard to read and not a model of how things should be done. A typical SSL client program would be much simpler.

The -prexit option is a bit of a hack. We should really report information whenever a session is renegotiated.

"},{"location":"man1/openssl-s_client/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-sess_id(1), openssl-s_server(1), openssl-ciphers(1), SSL_CONF_cmd(3), SSL_CTX_set_max_send_fragment(3), SSL_CTX_set_split_send_fragment(3), SSL_CTX_set_max_pipelines(3), ossl_store-file(7)

"},{"location":"man1/openssl-s_client/#history","title":"HISTORY","text":"

The -no_alt_chains option was added in OpenSSL 1.1.0. The -name option was added in OpenSSL 1.1.1.

The -certform option has become obsolete in OpenSSL 3.0.0 and has no effect.

The -engine option was deprecated in OpenSSL 3.0.

The -enable_client_rpk, -enable_server_rpk, -no_rx_cert_comp, -no_tx_cert_comp, and -tfo options were added in OpenSSL 3.2.

"},{"location":"man1/openssl-s_client/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-s_server/","title":"openssl-s_server","text":""},{"location":"man1/openssl-s_server/#name","title":"NAME","text":"

openssl-s_server - SSL/TLS server program

"},{"location":"man1/openssl-s_server/#synopsis","title":"SYNOPSIS","text":"

openssl s_server [-help] [-port +int] [-accept val] [-unix val] [-4] [-6] [-unlink] [-context val] [-verify int] [-Verify int] [-cert infile] [-cert2 infile] [-certform DER|PEM|P12] [-cert_chain infile] [-build_chain] [-serverinfo val] [-key filename|uri] [-key2 filename|uri] [-keyform DER|PEM|P12|ENGINE] [-pass val] [-dcert infile] [-dcertform DER|PEM|P12] [-dcert_chain infile] [-dkey filename|uri] [-dkeyform DER|PEM|P12|ENGINE] [-dpass val] [-nbio_test] [-crlf] [-debug] [-msg] [-msgfile outfile] [-state] [-nocert] [-quiet] [-no_resume_ephemeral] [-www] [-WWW] [-http_server_binmode] [-no_ca_names] [-ignore_unexpected_eof] [-servername] [-servername_fatal] [-tlsextdebug] [-HTTP] [-id_prefix val] [-keymatexport val] [-keymatexportlen +int] [-CRL infile] [-CRLform DER|PEM] [-crl_download] [-chainCAfile infile] [-chainCApath dir] [-chainCAstore uri] [-verifyCAfile infile] [-verifyCApath dir] [-verifyCAstore uri] [-no_cache] [-ext_cache] [-verify_return_error] [-verify_quiet] [-ign_eof] [-no_ign_eof] [-no_etm] [-no_ems] [-status] [-status_verbose] [-status_timeout int] [-proxy [http[s]://][userinfo@]host[:port][/path]] [-no_proxy addresses] [-status_url val] [-status_file infile] [-ssl_config val] [-trace] [-security_debug] [-security_debug_verbose] [-brief] [-rev] [-async] [-max_send_frag +int] [-split_send_frag +int] [-max_pipelines +int] [-naccept +int] [-read_buf +int] [-bugs] [-no_tx_cert_comp] [-no_rx_cert_comp] [-no_comp] [-comp] [-no_ticket] [-serverpref] [-legacy_renegotiation] [-no_renegotiation] [-no_resumption_on_reneg] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-prioritize_chacha] [-strict] [-sigalgs val] [-client_sigalgs val] [-groups val] [-curves val] [-named_curve val] [-cipher val] [-ciphersuites val] [-dhparam infile] [-record_padding val] [-debug_broken_protocol] [-nbio] [-psk_identity val] [-psk_hint val] [-psk val] [-psk_session file] [-srpvfile infile] [-srpuserseed val] [-timeout] [-mtu +int] [-listen] [-sctp] [-sctp_label_bug] [-use_srtp val] [-no_dhe] [-nextprotoneg val] [-alpn val] [-ktls] [-sendfile] [-zerocopy_sendfile] [-keylogfile outfile] [-recv_max_early_data int] [-max_early_data int] [-early_data] [-stateless] [-anti_replay] [-no_anti_replay] [-num_tickets] [-tfo] [-cert_comp] [-nameopt option] [-no_ssl3] [-no_tls1] [-no_tls1_1] [-no_tls1_2] [-no_tls1_3] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-dtls] [-dtls1] [-dtls1_2] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-bugs] [-no_comp] [-comp] [-no_ticket] [-serverpref] [-client_renegotiation] [-legacy_renegotiation] [-no_renegotiation] [-no_resumption_on_reneg] [-legacy_server_connect] [-no_legacy_server_connect] [-no_etm] [-allow_no_dhe_kex] [-prefer_no_dhe_kex] [-prioritize_chacha] [-strict] [-sigalgs algs] [-client_sigalgs algs] [-groups groups] [-curves curves] [-named_curve curve] [-cipher ciphers] [-ciphersuites 1.3ciphers] [-min_protocol minprot] [-max_protocol maxprot] [-record_padding padding] [-debug_broken_protocol] [-no_middlebox] [-xkey infile] [-xcert file] [-xchain file] [-xchain_build file] [-xcertform DER|PEM]> [-xkeyform DER|PEM]> [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [-enable_server_rpk] [-enable_client_rpk]

"},{"location":"man1/openssl-s_server/#description","title":"DESCRIPTION","text":"

This command implements a generic SSL/TLS server which listens for connections on a given port using SSL/TLS.

"},{"location":"man1/openssl-s_server/#options","title":"OPTIONS","text":"

In addition to the options below, this command also supports the common and server only options documented \"Supported Command Line Commands\" in SSL_CONF_cmd(3)

"},{"location":"man1/openssl-s_server/#connected-commands","title":"CONNECTED COMMANDS","text":"

If a connection request is established with an SSL client and neither the -www nor the -WWW option has been used then normally any data received from the client is displayed and any key presses will be sent to the client.

Certain commands are also recognized which perform special operations. These commands are a letter which must appear at the start of a line. They are listed below.

"},{"location":"man1/openssl-s_server/#notes","title":"NOTES","text":"

This command can be used to debug SSL clients. To accept connections from a web browser the command:

openssl s_server -accept 443 -www\n

can be used for example.

Although specifying an empty list of CAs when requesting a client certificate is strictly speaking a protocol violation, some SSL clients interpret this to mean any CA is acceptable. This is useful for debugging purposes.

The session parameters can printed out using the openssl-sess_id(1) command.

"},{"location":"man1/openssl-s_server/#bugs","title":"BUGS","text":"

Because this program has a lot of options and also because some of the techniques used are rather old, the C source for this command is rather hard to read and not a model of how things should be done. A typical SSL server program would be much simpler.

The output of common ciphers is wrong: it just gives the list of ciphers that OpenSSL recognizes and the client supports.

There should be a way for this command to print out details of any unknown cipher suites a client says it supports.

"},{"location":"man1/openssl-s_server/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-sess_id(1), openssl-s_client(1), openssl-ciphers(1), SSL_CONF_cmd(3), SSL_CTX_set_max_send_fragment(3), SSL_CTX_set_split_send_fragment(3), SSL_CTX_set_max_pipelines(3), ossl_store-file(7)

"},{"location":"man1/openssl-s_server/#history","title":"HISTORY","text":"

The -no_alt_chains option was added in OpenSSL 1.1.0.

The -allow-no-dhe-kex and -prioritize_chacha options were added in OpenSSL 1.1.1.

The -srpvfile, -srpuserseed, and -engine option were deprecated in OpenSSL 3.0.

The -enable_client_rpk, -enable_server_rpk, -no_rx_cert_comp, -no_tx_cert_comp, and -tfo options were added in OpenSSL 3.2.

"},{"location":"man1/openssl-s_server/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-s_time/","title":"openssl-s_time","text":""},{"location":"man1/openssl-s_time/#name","title":"NAME","text":"

openssl-s_time - SSL/TLS performance timing program

"},{"location":"man1/openssl-s_time/#synopsis","title":"SYNOPSIS","text":"

openssl s_time [-help] [-connect host:port] [-www page] [-cert filename] [-key filename] [-reuse] [-new] [-verify depth] [-time seconds] [-ssl3] [-tls1] [-tls1_1] [-tls1_2] [-tls1_3] [-bugs] [-cipher cipherlist] [-ciphersuites val] [-nameopt option] [-cafile file] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-s_time/#description","title":"DESCRIPTION","text":"

This command implements a generic SSL/TLS client which connects to a remote host using SSL/TLS. It can request a page from the server and includes the time to transfer the payload data in its timing measurements. It measures the number of connections within a given timeframe, the amount of data transferred (if any), and calculates the average time spent for one connection.

"},{"location":"man1/openssl-s_time/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-s_time/#notes","title":"NOTES","text":"

This command can be used to measure the performance of an SSL connection. To connect to an SSL HTTP server and get the default page the command

openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]\n

would typically be used (https uses port 443). commoncipher is a cipher to which both client and server can agree, see the openssl-ciphers(1) command for details.

If the handshake fails then there are several possible causes, if it is nothing obvious like no client certificate then the -bugs and -ssl3 options can be tried in case it is a buggy server. In particular you should play with these options before submitting a bug report to an OpenSSL mailing list.

A frequent problem when attempting to get client certificates working is that a web client complains it has no certificates or gives an empty list to choose from. This is normally because the server is not sending the clients certificate authority in its \"acceptable CA list\" when it requests a certificate. By using openssl-s_client(1) the CA list can be viewed and checked. However, some servers only request client authentication after a specific URL is requested. To obtain the list in this case it is necessary to use the -prexit option of openssl-s_client(1) and send an HTTP request for an appropriate page.

If a certificate is specified on the command line using the -cert option it will not be used unless the server specifically requests a client certificate. Therefore, merely including a client certificate on the command line is no guarantee that the certificate works.

"},{"location":"man1/openssl-s_time/#bugs","title":"BUGS","text":"

Because this program does not have all the options of the openssl-s_client(1) program to turn protocols on and off, you may not be able to measure the performance of all protocols with all servers.

The -verify option should really exit if the server verification fails.

"},{"location":"man1/openssl-s_time/#history","title":"HISTORY","text":"

The -cafile option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-s_time/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-s_client(1), openssl-s_server(1), openssl-ciphers(1), ossl_store-file(7)

"},{"location":"man1/openssl-s_time/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-sess_id/","title":"openssl-sess_id","text":""},{"location":"man1/openssl-sess_id/#name","title":"NAME","text":"

openssl-sess_id - SSL/TLS session handling command

"},{"location":"man1/openssl-sess_id/#synopsis","title":"SYNOPSIS","text":"

openssl sess_id [-help] [-inform DER|PEM] [-outform DER|PEM|NSS] [-in filename] [-out filename] [-text] [-cert] [-noout] [-context ID]

"},{"location":"man1/openssl-sess_id/#description","title":"DESCRIPTION","text":"

This command processes the encoded version of the SSL session structure and optionally prints out SSL session details (for example the SSL session master key) in human readable format. Since this is a diagnostic tool that needs some knowledge of the SSL protocol to use properly, most users will not need to use it.

The precise format of the data can vary across OpenSSL versions and is not documented.

"},{"location":"man1/openssl-sess_id/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-sess_id/#output","title":"OUTPUT","text":"

Typical output:

SSL-Session:\n    Protocol  : TLSv1\n    Cipher    : 0016\n    Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED\n    Session-ID-ctx: 01000000\n    Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD\n    Key-Arg   : None\n    Start Time: 948459261\n    Timeout   : 300 (sec)\n    Verify return code 0 (ok)\n

These are described below in more detail.

"},{"location":"man1/openssl-sess_id/#notes","title":"NOTES","text":"

Since the SSL session output contains the master key it is possible to read the contents of an encrypted session using this information. Therefore, appropriate security precautions should be taken if the information is being output by a \"real\" application. This is however strongly discouraged and should only be used for debugging purposes.

"},{"location":"man1/openssl-sess_id/#bugs","title":"BUGS","text":"

The cipher and start time should be printed out in human readable form.

"},{"location":"man1/openssl-sess_id/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-ciphers(1), openssl-s_server(1)

"},{"location":"man1/openssl-sess_id/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-smime/","title":"openssl-smime","text":""},{"location":"man1/openssl-smime/#name","title":"NAME","text":"

openssl-smime - S/MIME command

"},{"location":"man1/openssl-smime/#synopsis","title":"SYNOPSIS","text":"

openssl smime [-help] [-encrypt] [-decrypt] [-sign] [-resign] [-verify] [-pk7out] [-binary] [-crlfeol] [-cipher] [-in file] [-certfile file] [-signer file] [-nointern] [-noverify] [-nochain] [-nosigs] [-nocerts] [-noattr] [-nodetach] [-nosmimecap] [-recip _ file_] [-inform DER|PEM|SMIME] [-outform DER|PEM|SMIME] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-inkey filename|uri] [-out file] [-content file] [-to addr] [-from ad] [-subject s] [-text] [-indef] [-noindef] [-stream] [-md digest] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-engine id] [-rand files] [-writerand file] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq] [-config configfile] recipcert ...

"},{"location":"man1/openssl-smime/#description","title":"DESCRIPTION","text":"

This command handles S/MIME mail. It can encrypt, decrypt, sign and verify S/MIME messages.

"},{"location":"man1/openssl-smime/#options","title":"OPTIONS","text":"

There are six operation options that set the type of operation to be performed: -encrypt, -decrypt, -sign, -resign, -verify, and -pk7out. These are mutually exclusive. The meaning of the other options varies according to the operation type.

"},{"location":"man1/openssl-smime/#notes","title":"NOTES","text":"

The MIME message must be sent without any blank lines between the headers and the output. Some mail programs will automatically add a blank line. Piping the mail directly to sendmail is one way to achieve the correct format.

The supplied message to be signed or encrypted must include the necessary MIME headers or many S/MIME clients won't display it properly (if at all). You can use the -text option to automatically add plain text headers.

A \"signed and encrypted\" message is one where a signed message is then encrypted. This can be produced by encrypting an already signed message: see the examples section.

This version of the program only allows one signer per message but it will verify multiple signers on received messages. Some S/MIME clients choke if a message contains multiple signers. It is possible to sign messages \"in parallel\" by signing an already signed message.

The options -encrypt and -decrypt reflect common usage in S/MIME clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 encrypted data is used for other purposes.

The -resign option uses an existing message digest when adding a new signer. This means that attributes must be present in at least one existing signer using the same message digest or this operation will fail.

The -stream and -indef options enable streaming I/O support. As a result the encoding is BER using indefinite length constructed encoding and no longer DER. Streaming is supported for the -encrypt operation and the -sign operation if the content is not detached.

Streaming is always used for the -sign operation with detached data but since the content is no longer part of the PKCS#7 structure the encoding remains DER.

"},{"location":"man1/openssl-smime/#exit-codes","title":"EXIT CODES","text":""},{"location":"man1/openssl-smime/#examples","title":"EXAMPLES","text":"

Create a cleartext signed message:

openssl smime -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem\n

Create an opaque signed message:

openssl smime -sign -in message.txt -text -out mail.msg -nodetach \\\n       -signer mycert.pem\n

Create a signed message, include some additional certificates and read the private key from another file:

openssl smime -sign -in in.txt -text -out mail.msg \\\n       -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem\n

Create a signed message with two signers:

openssl smime -sign -in message.txt -text -out mail.msg \\\n       -signer mycert.pem -signer othercert.pem\n

Send a signed message under Unix directly to sendmail, including headers:

openssl smime -sign -in in.txt -text -signer mycert.pem \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed message\" | sendmail someone@somewhere\n

Verify a message and extract the signer's certificate if successful:

openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt\n

Send encrypted mail using triple DES:

openssl smime -encrypt -in in.txt -from steve@openssl.org \\\n       -to someone@somewhere -subject \"Encrypted message\" \\\n       -des3 user.pem -out mail.msg\n

Sign and encrypt mail:

openssl smime -sign -in ml.txt -signer my.pem -text \\\n       | openssl smime -encrypt -out mail.msg \\\n       -from steve@openssl.org -to someone@somewhere \\\n       -subject \"Signed and Encrypted message\" -des3 user.pem\n

Note: the encryption command does not include the -text option because the message being encrypted already has MIME headers.

Decrypt mail:

openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem\n

The output from Netscape form signing is a PKCS#7 structure with the detached signature format. You can use this program to verify the signature by line wrapping the base64 encoded structure and surrounding it with:

-----BEGIN PKCS7-----\n-----END PKCS7-----\n

and using the command:

openssl smime -verify -inform PEM -in signature.pem -content content.txt\n

Alternatively you can base64 decode the signature and use:

openssl smime -verify -inform DER -in signature.der -content content.txt\n

Create an encrypted message using 128 bit Camellia:

openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem\n

Add a signer to an existing message:

openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg\n
"},{"location":"man1/openssl-smime/#bugs","title":"BUGS","text":"

The MIME parser isn't very clever: it seems to handle most messages that I've thrown at it but it may choke on others.

The code currently will only write out the signer's certificate to a file: if the signer has a separate encryption certificate this must be manually extracted. There should be some heuristic that determines the correct encryption certificate.

Ideally a database should be maintained of a certificates for each email address.

The code doesn't currently take note of the permitted symmetric encryption algorithms as supplied in the SMIMECapabilities signed attribute. This means the user has to manually include the correct encryption algorithm. It should store the list of permitted ciphers in a database and only use those.

No revocation checking is done on the signer's certificate.

The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 structures may cause parsing errors.

"},{"location":"man1/openssl-smime/#see-also","title":"SEE ALSO","text":"

ossl_store-file(7)

"},{"location":"man1/openssl-smime/#history","title":"HISTORY","text":"

The use of multiple -signer options and the -resign command were first added in OpenSSL 1.0.0

The -no_alt_chains option was added in OpenSSL 1.1.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-smime/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-speed/","title":"openssl-speed","text":""},{"location":"man1/openssl-speed/#name","title":"NAME","text":"

openssl-speed - test library performance

"},{"location":"man1/openssl-speed/#synopsis","title":"SYNOPSIS","text":"

openssl speed [-help] [-config filename] [-elapsed] [-evp algo] [-hmac algo] [-cmac algo] [-mb] [-aead] [-kem-algorithms] [-signature-algorithms] [-multi num] [-async_jobs num] [-misalign num] [-decrypt] [-primes num] [-seconds num] [-bytes num] [-mr] [-mlock] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq] [algorithm ...]

"},{"location":"man1/openssl-speed/#description","title":"DESCRIPTION","text":"

This command is used to test the performance of cryptographic algorithms.

"},{"location":"man1/openssl-speed/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-speed/#bugs","title":"BUGS","text":"

The algorithm can be selected only from a pre-compiled subset of things that the openssl speed command knows about. To test any additional digest or cipher algorithm supported by OpenSSL use the -evp option.

There is no way to test the speed of any additional public key algorithms supported by third party providers with the openssl speed command.

"},{"location":"man1/openssl-speed/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

DSA512 was removed in OpenSSL 3.2.

"},{"location":"man1/openssl-speed/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-spkac/","title":"openssl-spkac","text":""},{"location":"man1/openssl-spkac/#name","title":"NAME","text":"

openssl-spkac - SPKAC printing and generating command

"},{"location":"man1/openssl-spkac/#synopsis","title":"SYNOPSIS","text":"

openssl spkac [-help] [-in filename] [-out filename] [-digest digest] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-passin arg] [-challenge string] [-pubkey] [-spkac spkacname] [-spksect section] [-noout] [-verify] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-spkac/#description","title":"DESCRIPTION","text":"

This command processes Netscape signed public key and challenge (SPKAC) files. It can print out their contents, verify the signature and produce its own SPKACs from a supplied private key.

"},{"location":"man1/openssl-spkac/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-spkac/#examples","title":"EXAMPLES","text":"

Print out the contents of an SPKAC:

openssl spkac -in spkac.cnf\n

Verify the signature of an SPKAC:

openssl spkac -in spkac.cnf -noout -verify\n

Create an SPKAC using the challenge string \"hello\":

openssl spkac -key key.pem -challenge hello -out spkac.cnf\n

Example of an SPKAC, (long lines split up for clarity):

SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA\\\n1cCoq2Wa3Ixs47uI7FPVwHVIPDx5yso105Y6zpozam135a\\\n8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03uPFoQIDAQAB\\\nFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJ\\\nh1bEIYuc2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnD\\\ndq+NQ3F+X4deMx9AaEglZtULwV4=\n
"},{"location":"man1/openssl-spkac/#notes","title":"NOTES","text":"

A created SPKAC with suitable DN components appended can be fed to openssl-ca(1).

SPKACs are typically generated by Netscape when a form is submitted containing the KEYGEN tag as part of the certificate enrollment process.

The challenge string permits a primitive form of proof of possession of private key. By checking the SPKAC signature and a random challenge string some guarantee is given that the user knows the private key corresponding to the public key being certified. This is important in some applications. Without this it is possible for a previous SPKAC to be used in a \"replay attack\".

"},{"location":"man1/openssl-spkac/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-ca(1)

"},{"location":"man1/openssl-spkac/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

The -digest option was added in OpenSSL 3.0.

"},{"location":"man1/openssl-spkac/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-srp/","title":"openssl-srp","text":""},{"location":"man1/openssl-srp/#name","title":"NAME","text":"

openssl-srp - maintain SRP password file

"},{"location":"man1/openssl-srp/#synopsis","title":"SYNOPSIS","text":"

openssl srp [-help] [-verbose] [-add] [-modify] [-delete] [-list] [-name section] [-srpvfile file] [-gn identifier] [-userinfo text] [-passin arg] [-passout arg] [-engine id] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq] [-config configfile] [user ...]

"},{"location":"man1/openssl-srp/#description","title":"DESCRIPTION","text":"

This command is deprecated. It is used to maintain an SRP (secure remote password) file. At most one of the -add, -modify, -delete, and -list options can be specified. These options take zero or more usernames as parameters and perform the appropriate operation on the SRP file. For -list, if no user is given then all users are displayed.

The configuration file to use, and the section within the file, can be specified with the -config and -name flags, respectively.

"},{"location":"man1/openssl-srp/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-srp/#history","title":"HISTORY","text":"

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-srp/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-storeutl/","title":"openssl-storeutl","text":""},{"location":"man1/openssl-storeutl/#name","title":"NAME","text":"

openssl-storeutl - STORE command

"},{"location":"man1/openssl-storeutl/#synopsis","title":"SYNOPSIS","text":"

openssl storeutl [-help] [-out file] [-noout] [-passin arg] [-text arg] [-r] [-certs] [-keys] [-crls] [-subject arg] [-issuer arg] [-serial arg] [-alias arg] [-fingerprint arg] [-digest] [-engine id] [-provider name] [-provider-path path] [-propquery propq] uri

"},{"location":"man1/openssl-storeutl/#description","title":"DESCRIPTION","text":"

This command can be used to display the contents (after decryption as the case may be) fetched from the given URI.

"},{"location":"man1/openssl-storeutl/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-storeutl/#see-also","title":"SEE ALSO","text":"

openssl(1)

"},{"location":"man1/openssl-storeutl/#history","title":"HISTORY","text":"

This command was added in OpenSSL 1.1.1.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-storeutl/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-ts/","title":"openssl-ts","text":""},{"location":"man1/openssl-ts/#name","title":"NAME","text":"

openssl-ts - Time Stamping Authority command

"},{"location":"man1/openssl-ts/#synopsis","title":"SYNOPSIS","text":"

openssl ts -help

openssl ts -query [-config configfile] [-data file_to_hash] [-digest digest_bytes] [-digest] [-tspolicy object_id] [-no_nonce] [-cert] [-in request.tsq] [-out request.tsq] [-text] [-rand files] [-writerand file] [-provider name] [-provider-path path] [-propquery propq]

openssl ts -reply [-config configfile] [-section tsa_section] [-queryfile request.tsq] [-passin password_src] [-signer tsa_cert.pem] [-inkey filename|uri] [-digest] [-chain certs_file.pem] [-tspolicy object_id] [-in response.tsr] [-token_in] [-out response.tsr] [-token_out] [-text] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

openssl ts -verify [-data file_to_hash] [-digest digest_bytes] [-queryfile request.tsq] [-in response.tsr] [-token_in] [-untrusted files|uris] [-CAfile file] [-CApath dir] [-CAstore uri] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-ts/#description","title":"DESCRIPTION","text":"

This command is a basic Time Stamping Authority (TSA) client and server application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A TSA can be part of a PKI deployment and its role is to provide long term proof of the existence of a certain datum before a particular time. Here is a brief description of the protocol:

  1. The TSA client computes a one-way hash value for a data file and sends the hash to the TSA.
  2. The TSA attaches the current date and time to the received hash value, signs them and sends the timestamp token back to the client. By creating this token the TSA certifies the existence of the original data file at the time of response generation.
  3. The TSA client receives the timestamp token and verifies the signature on it. It also checks if the token contains the same hash value that it had sent to the TSA.

There is one DER encoded protocol data unit defined for transporting a timestamp request to the TSA and one for sending the timestamp response back to the client. This command has three main functions: creating a timestamp request based on a data file, creating a timestamp response based on a request, verifying if a response corresponds to a particular request or a data file.

There is no support for sending the requests/responses automatically over HTTP or TCP yet as suggested in RFC 3161. The users must send the requests either by ftp or e-mail.

"},{"location":"man1/openssl-ts/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-ts/#timestamp-request-generation","title":"Timestamp Request generation","text":"

The -query command can be used for creating and printing a timestamp request with the following options:

"},{"location":"man1/openssl-ts/#timestamp-response-generation","title":"Timestamp Response generation","text":"

A timestamp response (TimeStampResp) consists of a response status and the timestamp token itself (ContentInfo), if the token generation was successful. The -reply command is for creating a timestamp response or timestamp token based on a request and printing the response/token in human-readable format. If -token_out is not specified the output is always a timestamp response (TimeStampResp), otherwise it is a timestamp token (ContentInfo).

"},{"location":"man1/openssl-ts/#timestamp-response-verification","title":"Timestamp Response verification","text":"

The -verify command is for verifying if a timestamp response or timestamp token is valid and matches a particular timestamp request or data file. The -verify command does not use the configuration file.

"},{"location":"man1/openssl-ts/#configuration-file-options","title":"CONFIGURATION FILE OPTIONS","text":"

The -query and -reply commands make use of a configuration file. See config(5) for a general description of the syntax of the config file. The -query command uses only the symbolic OID names section and it can work without it. However, the -reply command needs the config file for its operation.

When there is a command line switch equivalent of a variable the switch always overrides the settings in the config file.

"},{"location":"man1/openssl-ts/#examples","title":"EXAMPLES","text":"

All the examples below presume that OPENSSL_CONF is set to a proper configuration file, e.g. the example configuration file openssl/apps/openssl.cnf will do.

"},{"location":"man1/openssl-ts/#timestamp-request","title":"Timestamp Request","text":"

To create a timestamp request for design1.txt with SHA-256 digest, without nonce and policy, and without requirement for a certificate in the response:

openssl ts -query -data design1.txt -no_nonce \\\n      -out design1.tsq\n

To create a similar timestamp request with specifying the message imprint explicitly:

openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \\\n       -no_nonce -out design1.tsq\n

To print the content of the previous request in human readable format:

openssl ts -query -in design1.tsq -text\n

To create a timestamp request which includes the SHA-512 digest of design2.txt, requests the signer certificate and nonce, and specifies a policy id (assuming the tsa_policy1 name is defined in the OID section of the config file):

openssl ts -query -data design2.txt -sha512 \\\n      -tspolicy tsa_policy1 -cert -out design2.tsq\n
"},{"location":"man1/openssl-ts/#timestamp-response","title":"Timestamp Response","text":"

Before generating a response a signing certificate must be created for the TSA that contains the timeStamping critical extended key usage extension without any other key usage extensions. You can add this line to the user certificate section of the config file to generate a proper certificate;

extendedKeyUsage = critical,timeStamping\n

See openssl-req(1), openssl-ca(1), and openssl-x509(1) for instructions. The examples below assume that cacert.pem contains the certificate of the CA, tsacert.pem is the signing certificate issued by cacert.pem and tsakey.pem is the private key of the TSA.

To create a timestamp response for a request:

openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \\\n      -signer tsacert.pem -out design1.tsr\n

If you want to use the settings in the config file you could just write:

openssl ts -reply -queryfile design1.tsq -out design1.tsr\n

To print a timestamp reply to stdout in human readable format:

openssl ts -reply -in design1.tsr -text\n

To create a timestamp token instead of timestamp response:

openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out\n

To print a timestamp token to stdout in human readable format:

openssl ts -reply -in design1_token.der -token_in -text -token_out\n

To extract the timestamp token from a response:

openssl ts -reply -in design1.tsr -out design1_token.der -token_out\n

To add 'granted' status info to a timestamp token thereby creating a valid response:

openssl ts -reply -in design1_token.der -token_in -out design1.tsr\n
"},{"location":"man1/openssl-ts/#timestamp-verification","title":"Timestamp Verification","text":"

To verify a timestamp reply against a request:

openssl ts -verify -queryfile design1.tsq -in design1.tsr \\\n      -CAfile cacert.pem -untrusted tsacert.pem\n

To verify a timestamp reply that includes the certificate chain:

openssl ts -verify -queryfile design2.tsq -in design2.tsr \\\n      -CAfile cacert.pem\n

To verify a timestamp token against the original data file: openssl ts -verify -data design2.txt -in design2.tsr \\ -CAfile cacert.pem

To verify a timestamp token against a message imprint: openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \\ -in design2.tsr -CAfile cacert.pem

You could also look at the 'test' directory for more examples.

"},{"location":"man1/openssl-ts/#bugs","title":"BUGS","text":""},{"location":"man1/openssl-ts/#history","title":"HISTORY","text":"

OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an improved seeding mechanism. The new seeding mechanism makes it unnecessary to define a RANDFILE for saving and restoring randomness. This option is retained mainly for compatibility reasons.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-ts/#see-also","title":"SEE ALSO","text":"

openssl(1), tsget(1), openssl-req(1), openssl-x509(1), openssl-ca(1), openssl-genrsa(1), config(5), ossl_store-file(7)

"},{"location":"man1/openssl-ts/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-verification-options/","title":"openssl-verification-options","text":""},{"location":"man1/openssl-verification-options/#name","title":"NAME","text":"

openssl-verification-options - generic X.509 certificate verification options

"},{"location":"man1/openssl-verification-options/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

"},{"location":"man1/openssl-verification-options/#description","title":"DESCRIPTION","text":"

There are many situations where X.509 certificates are verified within the OpenSSL libraries and in various OpenSSL commands.

Certificate verification is implemented by X509_verify_cert(3). It is a complicated process consisting of a number of steps and depending on numerous options. The most important of them are detailed in the following sections.

In a nutshell, a valid chain of certificates needs to be built up and verified starting from the target certificate that is to be verified and ending in a certificate that due to some policy is trusted. Verification is done relative to the given purpose, which is the intended use of the target certificate, such as SSL server, or by default for any purpose.

The details of how each OpenSSL command handles errors are documented on the specific command page.

DANE support is documented in openssl-s_client(1), SSL_CTX_dane_enable(3), SSL_set1_host(3), X509_VERIFY_PARAM_set_flags(3), and X509_check_host(3).

"},{"location":"man1/openssl-verification-options/#trust-anchors","title":"Trust Anchors","text":"

In general, according to RFC 4158 and RFC 5280, a trust anchor is any public key and related subject distinguished name (DN) that for some reason is considered trusted and thus is acceptable as the root of a chain of certificates.

In practice, trust anchors are given in the form of certificates, where their essential fields are the public key and the subject DN. In addition to the requirements in RFC 5280, OpenSSL checks the validity period of such certificates and makes use of some further fields. In particular, the subject key identifier extension, if present, is used for matching trust anchors during chain building.

In the most simple and common case, trust anchors are by default all self-signed \"root\" CA certificates that are placed in the trust store, which is a collection of certificates that are trusted for certain uses. This is akin to what is used in the trust stores of Mozilla Firefox, or Apple's and Microsoft's certificate stores, ...

From the OpenSSL perspective, a trust anchor is a certificate that should be augmented with an explicit designation for which uses of a target certificate the certificate may serve as a trust anchor. In PEM encoding, this is indicated by the TRUSTED CERTIFICATE string. Such a designation provides a set of positive trust attributes explicitly stating trust for the listed purposes and/or a set of negative trust attributes explicitly rejecting the use for the listed purposes. The purposes are encoded using the values defined for the extended key usages (EKUs) that may be given in X.509 extensions of end-entity certificates. See also the \"Extended Key Usage\" section below.

The currently recognized uses are clientAuth (SSL client use), serverAuth (SSL server use), emailProtection (S/MIME email use), codeSigning (object signer use), OCSPSigning (OCSP responder use), OCSP (OCSP request use), timeStamping (TSA server use), and anyExtendedKeyUsage. As of OpenSSL 1.1.0, the last of these blocks all uses when rejected or enables all uses when trusted.

A certificate, which may be CA certificate or an end-entity certificate, is considered a trust anchor for the given use if and only if all the following conditions hold:

"},{"location":"man1/openssl-verification-options/#certification-path-building","title":"Certification Path Building","text":"

First, a certificate chain is built up starting from the target certificate and ending in a trust anchor.

The chain is built up iteratively, looking up in turn a certificate with suitable key usage that matches as an issuer of the current \"subject\" certificate as described below. If there is such a certificate, the first one found that is currently valid is taken, otherwise the one that expired most recently of all such certificates. For efficiency, no backtracking is performed, thus any further candidate issuer certificates that would match equally are ignored.

When a self-signed certificate has been added, chain construction stops. In this case it must fully match a trust anchor, otherwise chain building fails.

A candidate issuer certificate matches a subject certificate if all of the following conditions hold:

The lookup first searches for issuer certificates in the trust store. If it does not find a match there it consults the list of untrusted (\"intermediate\" CA) certificates, if provided.

"},{"location":"man1/openssl-verification-options/#certification-path-validation","title":"Certification Path Validation","text":"

When the certificate chain building process was successful the chain components and their links are checked thoroughly.

The first step is to check that each certificate is well-formed. Part of these checks are enabled only if the -x509_strict option is given.

The second step is to check the extensions of every untrusted certificate for consistency with the supplied purpose. If the -purpose option is not given then no such checks are done except for SSL/TLS connection setup, where by default sslserver or sslclient, are checked. The target or \"leaf\" certificate, as well as any other untrusted certificates, must have extensions compatible with the specified purpose. All certificates except the target or \"leaf\" must also be valid CA certificates. The precise extensions required are described in more detail in \"CERTIFICATE EXTENSIONS\" in openssl-x509(1).

The third step is to check the trust settings on the last certificate (which typically is a self-signed root CA certificate). It must be trusted for the given use. For compatibility with previous versions of OpenSSL, a self-signed certificate with no trust attributes is considered to be valid for all uses.

The fourth, and final, step is to check the validity of the certificate chain. For each element in the chain, including the root CA certificate, the validity period as specified by the notBefore and notAfter fields is checked against the current system time. The -attime flag may be used to use a reference time other than \"now.\" The certificate signature is checked as well (except for the signature of the typically self-signed root CA certificate, which is verified only if the -check_ss_sig option is given). When verifying a certificate signature the keyUsage extension (if present) of the candidate issuer certificate is checked to permit digitalSignature for signing proxy certificates or to permit keyCertSign for signing other certificates, respectively. If all operations complete successfully then certificate is considered valid. If any operation fails then the certificate is not valid.

"},{"location":"man1/openssl-verification-options/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-verification-options/#trusted-certificate-options","title":"Trusted Certificate Options","text":"

The following options specify how to supply the certificates that can be used as trust anchors for certain uses. As mentioned, a collection of such certificates is called a trust store.

Note that OpenSSL does not provide a default set of trust anchors. Many Linux distributions include a system default and configure OpenSSL to point to that. Mozilla maintains an influential trust store that can be found at https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/.

The certificates to add to the trust store can be specified using following options.

"},{"location":"man1/openssl-verification-options/#verification-options","title":"Verification Options","text":"

The certificate verification can be fine-tuned with the following flags.

"},{"location":"man1/openssl-verification-options/#extended-verification-options","title":"Extended Verification Options","text":"

Sometimes there may be more than one certificate chain leading to an end-entity certificate. This usually happens when a root or intermediate CA signs a certificate for another a CA in other organization. Another reason is when a CA might have intermediates that use two different signature formats, such as a SHA-1 and a SHA-256 digest.

The following options can be used to provide data that will allow the OpenSSL command to generate an alternative chain.

"},{"location":"man1/openssl-verification-options/#certificate-extensions","title":"Certificate Extensions","text":"

Options like -purpose lead to checking the certificate extensions, which determine what the target certificate and intermediate CA certificates can be used for.

"},{"location":"man1/openssl-verification-options/#basic-constraints","title":"Basic Constraints","text":"

The basicConstraints extension CA flag is used to determine whether the certificate can be used as a CA. If the CA flag is true then it is a CA, if the CA flag is false then it is not a CA. All CAs should have the CA flag set to true.

If the basicConstraints extension is absent, which includes the case that it is an X.509v1 certificate, then the certificate is considered to be a \"possible CA\" and other extensions are checked according to the intended use of the certificate. The treatment of certificates without basicConstraints as a CA is presently supported, but this could change in the future.

"},{"location":"man1/openssl-verification-options/#key-usage","title":"Key Usage","text":"

If the keyUsage extension is present then additional restraints are made on the uses of the certificate. A CA certificate must have the keyCertSign bit set if the keyUsage extension is present.

"},{"location":"man1/openssl-verification-options/#extended-key-usage","title":"Extended Key Usage","text":"

The extKeyUsage (EKU) extension places additional restrictions on the certificate uses. If this extension is present (whether critical or not) the key can only be used for the purposes specified.

A complete description of each check is given below. The comments about basicConstraints and keyUsage and X.509v1 certificates above apply to all CA certificates.

"},{"location":"man1/openssl-verification-options/#bugs","title":"BUGS","text":"

The issuer checks still suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that trusted certificates with matching subject name must appear in a file (as specified by the -CAfile option), a directory (as specified by -CApath), or a store (as specified by -CAstore). If there are multiple such matches, possibly in multiple locations, only the first one (in the mentioned order of locations) is recognised.

"},{"location":"man1/openssl-verification-options/#see-also","title":"SEE ALSO","text":"

X509_verify_cert(3), openssl-verify(1), openssl-ocsp(1), openssl-ts(1), openssl-s_client(1), openssl-s_server(1), openssl-smime(1), openssl-cmp(1), openssl-cms(1)

"},{"location":"man1/openssl-verification-options/#history","title":"HISTORY","text":"

The checks enabled by -x509_strict have been extended in OpenSSL 3.0.

"},{"location":"man1/openssl-verification-options/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-verify/","title":"openssl-verify","text":""},{"location":"man1/openssl-verify/#name","title":"NAME","text":"

openssl-verify - certificate verification command

"},{"location":"man1/openssl-verify/#synopsis","title":"SYNOPSIS","text":"

openssl verify [-help] [-CRLfile filename|uri] [-crl_download] [-show_chain] [-verbose] [-trusted filename|uri] [-untrusted filename|uri] [-vfyopt nm:v] [-nameopt option] [-CAfile file] [-no-CAfile] [-CApath dir] [-no-CApath] [-CAstore uri] [-no-CAstore] [-engine id] [-allow_proxy_certs] [-attime timestamp] [-no_check_time] [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map] [-partial_chain] [-policy arg] [-policy_check] [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192] [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num] [-verify_depth num] [-verify_email email] [-verify_hostname hostname] [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks] [-provider name] [-provider-path path] [-propquery propq] [--] [certificate ...]

"},{"location":"man1/openssl-verify/#description","title":"DESCRIPTION","text":"

This command verifies certificate chains. If a certificate chain has multiple problems, this program attempts to display all of them.

"},{"location":"man1/openssl-verify/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-verify/#diagnostics","title":"DIAGNOSTICS","text":"

When a verify operation fails the output messages can be somewhat cryptic. The general form of the error message is:

server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)\nerror 24 at 1 depth lookup:invalid CA certificate\n

The first line contains the name of the certificate being verified followed by the subject name of the certificate. The second line contains the error number and the depth. The depth is number of the certificate being verified when a problem was detected starting with zero for the target (\"leaf\") certificate itself then 1 for the CA that signed the target certificate and so on. Finally a textual version of the error number is presented.

A list of the error codes and messages can be found in X509_STORE_CTX_get_error(3); the full list is defined in the header file <openssl/x509_vfy.h>.

This command ignores many errors, in order to allow all the problems with a certificate chain to be determined.

"},{"location":"man1/openssl-verify/#see-also","title":"SEE ALSO","text":"

openssl-verification-options(1), openssl-x509(1), ossl_store-file(7)

"},{"location":"man1/openssl-verify/#history","title":"HISTORY","text":"

The -show_chain option was added in OpenSSL 1.1.0.

The -engine option was deprecated in OpenSSL 3.0.

"},{"location":"man1/openssl-verify/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-version/","title":"openssl-version","text":""},{"location":"man1/openssl-version/#name","title":"NAME","text":"

openssl-version - print OpenSSL version information

"},{"location":"man1/openssl-version/#synopsis","title":"SYNOPSIS","text":"

openssl version [-help] [-a] [-v] [-b] [-o] [-f] [-p] [-d] [-e] [-m] [-r] [-c] [-w]

"},{"location":"man1/openssl-version/#description","title":"DESCRIPTION","text":"

This command is used to print out version information about OpenSSL.

"},{"location":"man1/openssl-version/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-version/#history","title":"HISTORY","text":"

In OpenSSL versions prior to 3.4, OpenSSL had a limitation regarding the OPENSSLDIR, MODULESDIR and ENGINESDIR build time macros. These macros were defined at build time, and represented filesystem paths. This is common practice on unix like systems, as there was an expectation that a given build would be installed to a pre-determined location. On Windows however, there is no such expectation, as libraries can be installed to arbitrary locations. OSSL_WINCTX was introduced as a new build time variable to define a set of registry keys identified by the name openssl-<version>-<ctx>, in which the <version> value is derived from the version string in the openssl source, and the <ctx> extension is derived from the OSSL_WINCTX variable. The values of OPENSSLDIR, ENGINESDIR and MODULESDIR can be set to various paths underneath this key to break the requirement to predict the installation path at build time.

"},{"location":"man1/openssl-version/#notes","title":"NOTES","text":"

The output of openssl version -a would typically be used when sending in a bug report.

"},{"location":"man1/openssl-version/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl-x509/","title":"openssl-x509","text":""},{"location":"man1/openssl-x509/#name","title":"NAME","text":"

openssl-x509 - Certificate display and signing command

"},{"location":"man1/openssl-x509/#synopsis","title":"SYNOPSIS","text":"

openssl x509 [-help] [-in filename|uri] [-passin arg] [-new] [-x509toreq] [-req] [-copy_extensions arg] [-inform DER|PEM] [-vfyopt nm:v] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-signkey filename|uri] [-out filename] [-outform DER|PEM] [-nocert] [-noout] [-dateopt] [-text] [-certopt option] [-fingerprint] [-alias] [-serial] [-startdate] [-enddate] [-dates] [-subject] [-issuer] [-nameopt option] [-email] [-hash] [-subject_hash] [-subject_hash_old] [-issuer_hash] [-issuer_hash_old] [-ext extensions] [-ocspid] [-ocsp_uri] [-purpose] [-pubkey] [-modulus] [-checkend num] [-checkhost host] [-checkemail host] [-checkip ipaddr] [-set_serial n] [-next_serial] [-not_before date] [-not_after date] [-days arg] [-preserve_dates] [-set_issuer arg] [-set_subject arg] [-subj arg] [-force_pubkey filename] [-clrext] [-extfile filename] [-extensions section] [-sigopt nm:v] [-badsig] [-digest] [-CA filename|uri] [-CAform DER|PEM|P12] [-CAkey filename|uri] [-CAkeyform DER|PEM|P12|ENGINE] [-CAserial filename] [-CAcreateserial] [-trustout] [-setalias arg] [-clrtrust] [-addtrust arg] [-clrreject] [-addreject arg] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

"},{"location":"man1/openssl-x509/#description","title":"DESCRIPTION","text":"

This command is a multi-purposes certificate handling command. It can be used to print certificate information, convert certificates to various forms, edit certificate trust settings, generate certificates from scratch or from certification requests and then self-signing them or signing them like a \"micro CA\".

Generated certificates bear X.509 version 3. Unless specified otherwise, key identifier extensions are included as described in x509v3_config(5).

Since there are a large number of options they will split up into various sections.

"},{"location":"man1/openssl-x509/#options","title":"OPTIONS","text":""},{"location":"man1/openssl-x509/#input-output-and-general-purpose-options","title":"Input, Output, and General Purpose Options","text":""},{"location":"man1/openssl-x509/#certificate-printing-options","title":"Certificate Printing Options","text":"

Note: the -alias and -purpose options are also printing options but are described in the \"Trust Settings\" section.

"},{"location":"man1/openssl-x509/#certificate-checking-options","title":"Certificate Checking Options","text":""},{"location":"man1/openssl-x509/#certificate-output-options","title":"Certificate Output Options","text":""},{"location":"man1/openssl-x509/#micro-ca-options","title":"Micro-CA Options","text":""},{"location":"man1/openssl-x509/#trust-settings","title":"Trust Settings","text":"

A trusted certificate is an ordinary certificate which has several additional pieces of information attached to it such as the permitted and prohibited uses of the certificate and possibly an \"alias\" (nickname).

Normally when a certificate is being verified at least one certificate must be \"trusted\". By default a trusted certificate must be stored locally and must be a root CA: any certificate chain ending in this CA is then usable for any purpose.

Trust settings currently are only used with a root CA. They allow a finer control over the purposes the root CA can be used for. For example, a CA may be trusted for SSL client but not SSL server use.

See openssl-verification-options(1) for more information on the meaning of trust settings.

Future versions of OpenSSL will recognize trust settings on any certificate: not just root CAs.

"},{"location":"man1/openssl-x509/#generic-options","title":"Generic options","text":""},{"location":"man1/openssl-x509/#text-printing-flags","title":"Text Printing Flags","text":"

As well as customising the name printing format, it is also possible to customise the actual fields printed using the certopt option when the text option is present. The default behaviour is to print all fields.

"},{"location":"man1/openssl-x509/#examples","title":"EXAMPLES","text":"

Note: in these examples the '\\' means the example should be all on one line.

Print the contents of a certificate:

openssl x509 -in cert.pem -noout -text\n

Print the \"Subject Alternative Name\" extension of a certificate:

openssl x509 -in cert.pem -noout -ext subjectAltName\n

Print more extensions of a certificate:

openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType\n

Print the certificate serial number:

openssl x509 -in cert.pem -noout -serial\n

Print the certificate subject name:

openssl x509 -in cert.pem -noout -subject\n

Print the certificate subject name in RFC2253 form:

openssl x509 -in cert.pem -noout -subject -nameopt RFC2253\n

Print the certificate subject name in oneline form on a terminal supporting UTF8:

openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb\n

Print the certificate SHA1 fingerprint:

openssl x509 -sha1 -in cert.pem -noout -fingerprint\n

Convert a certificate from PEM to DER format:

openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER\n

Convert a certificate to a certificate request:

openssl x509 -x509toreq -in cert.pem -out req.pem -key key.pem\n

Convert a certificate request into a self-signed certificate using extensions for a CA:

openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \\\n       -key key.pem -out cacert.pem\n

Sign a certificate request using the CA certificate above and add user certificate extensions:

openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \\\n       -CA cacert.pem -CAkey key.pem -CAcreateserial\n

Set a certificate to be trusted for SSL client use and change set its alias to \"Steve's Class 1 CA\"

openssl x509 -in cert.pem -addtrust clientAuth \\\n       -setalias \"Steve's Class 1 CA\" -out trust.pem\n
"},{"location":"man1/openssl-x509/#notes","title":"NOTES","text":"

The conversion to UTF8 format used with the name options assumes that T61Strings use the ISO8859-1 character set. This is wrong but Netscape and MSIE do this as do many certificates. So although this is incorrect it is more likely to print the majority of certificates correctly.

The -email option searches the subject name and the subject alternative name extension. Only unique email addresses will be printed out: it will not print the same address more than once.

"},{"location":"man1/openssl-x509/#bugs","title":"BUGS","text":"

It is possible to produce invalid certificates or requests by specifying the wrong private key, using unsuitable X.509 extensions, or using inconsistent options in some cases: these should be checked.

There should be options to explicitly set such things as start and end dates rather than an offset from the current time.

"},{"location":"man1/openssl-x509/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-req(1), openssl-ca(1), openssl-genrsa(1), openssl-gendsa(1), openssl-verify(1), x509v3_config(5)

"},{"location":"man1/openssl-x509/#history","title":"HISTORY","text":"

The hash algorithm used in the -subject_hash and -issuer_hash options before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding of the distinguished name. In OpenSSL 1.0.0 and later it is based on a canonical version of the DN using SHA1. This means that any directories using the old form must have their links rebuilt using openssl-rehash(1) or similar.

The -signkey option has been renamed to -key in OpenSSL 3.0, keeping the old name as an alias.

The -engine option was deprecated in OpenSSL 3.0.

The -C option was removed in OpenSSL 3.0.

Since OpenSSL 3.2, generated certificates bear X.509 version 3, and key identifier extensions are included by default.

"},{"location":"man1/openssl-x509/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/openssl/","title":"openssl","text":""},{"location":"man1/openssl/#name","title":"NAME","text":"

openssl - OpenSSL command line program

"},{"location":"man1/openssl/#synopsis","title":"SYNOPSIS","text":"

openssl command [ options ... ] [ parameters ... ]

openssl no-XXX [ options ]

openssl -help | -version

"},{"location":"man1/openssl/#description","title":"DESCRIPTION","text":"

OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) network protocols and related cryptography standards required by them.

The openssl program is a command line program for using the various cryptography functions of OpenSSL's crypto library from the shell. It can be used for

o  Creation and management of private keys, public keys and parameters\no  Public key cryptographic operations\no  Creation of X.509 certificates, CSRs and CRLs\no  Calculation of Message Digests and Message Authentication Codes\no  Encryption and Decryption with Ciphers\no  SSL/TLS Client and Server Tests\no  Handling of S/MIME signed or encrypted mail\no  Timestamp requests, generation and verification\n
"},{"location":"man1/openssl/#command-summary","title":"COMMAND SUMMARY","text":"

The openssl program provides a rich variety of commands (command in the \"SYNOPSIS\" above). Each command can have many options and argument parameters, shown above as options and parameters.

Detailed documentation and use cases for most standard subcommands are available (e.g., openssl-x509(1)). The subcommand openssl-list(1) may be used to list subcommands.

The command no-XXX tests whether a command of the specified name is available. If no command named XXX exists, it returns 0 (success) and prints no-XXX; otherwise it returns 1 and prints XXX. In both cases, the output goes to stdout and nothing is printed to stderr. Additional command line arguments are always ignored. Since for each cipher there is a command of the same name, this provides an easy way for shell scripts to test for the availability of ciphers in the openssl program. (no-XXX is not able to detect pseudo-commands such as quit, list, or no-XXX itself.)

"},{"location":"man1/openssl/#configuration-option","title":"Configuration Option","text":"

Many commands use an external configuration file for some or all of their arguments and have a -config option to specify that file. The default name of the file is openssl.cnf in the default certificate storage area, which can be determined from the openssl-version(1) command using the -d or -a option. The environment variable OPENSSL_CONF can be used to specify a different file location or to disable loading a configuration (using the empty string).

Among others, the configuration file can be used to load modules and to specify parameters for generating certificates and random numbers. See config(5) for details.

"},{"location":"man1/openssl/#standard-commands","title":"Standard Commands","text":""},{"location":"man1/openssl/#message-digest-commands","title":"Message Digest Commands","text":""},{"location":"man1/openssl/#encryption-decryption-and-encoding-commands","title":"Encryption, Decryption, and Encoding Commands","text":"

The following aliases provide convenient access to the most used encodings and ciphers.

Depending on how OpenSSL was configured and built, not all ciphers listed here may be present. See openssl-enc(1) for more information.

"},{"location":"man1/openssl/#options","title":"OPTIONS","text":"

Details of which options are available depend on the specific command. This section describes some common options with common behavior.

"},{"location":"man1/openssl/#program-options","title":"Program Options","text":"

These options can be specified without a command specified to get help or version information.

"},{"location":"man1/openssl/#common-options","title":"Common Options","text":""},{"location":"man1/openssl/#format-options","title":"Format Options","text":"

See openssl-format-options(1) for manual page.

"},{"location":"man1/openssl/#pass-phrase-options","title":"Pass Phrase Options","text":"

See the openssl-passphrase-options(1) manual page.

"},{"location":"man1/openssl/#random-state-options","title":"Random State Options","text":"

Prior to OpenSSL 1.1.1, it was common for applications to store information about the state of the random-number generator in a file that was loaded at startup and rewritten upon exit. On modern operating systems, this is generally no longer necessary as OpenSSL will seed itself from a trusted entropy source provided by the operating system. These flags are still supported for special platforms or circumstances that might require them.

It is generally an error to use the same seed file more than once and every use of -rand should be paired with -writerand.

"},{"location":"man1/openssl/#certificate-verification-options","title":"Certificate Verification Options","text":"

See the openssl-verification-options(1) manual page.

"},{"location":"man1/openssl/#name-format-options","title":"Name Format Options","text":"

See the openssl-namedisplay-options(1) manual page.

"},{"location":"man1/openssl/#tls-version-options","title":"TLS Version Options","text":"

Several commands use SSL, TLS, or DTLS. By default, the commands use TLS and clients will offer the lowest and highest protocol version they support, and servers will pick the highest version that the client offers that is also supported by the server.

The options below can be used to limit which protocol versions are used, and whether TCP (SSL and TLS) or UDP (DTLS) is used. Note that not all protocols and flags may be available, depending on how OpenSSL was built.

"},{"location":"man1/openssl/#engine-options","title":"Engine Options","text":"

Options specifying keys, like -key and similar, can use the generic OpenSSL engine key loading URI scheme org.openssl.engine: to retrieve private keys and public keys. The URI syntax is as follows, in simplified form:

org.openssl.engine:{engineid}:{keyid}\n

Where {engineid} is the identity/name of the engine, and {keyid} is a key identifier that's acceptable by that engine. For example, when using an engine that interfaces against a PKCS#11 implementation, the generic key URI would be something like this (this happens to be an example for the PKCS#11 engine that's part of OpenSC):

-key org.openssl.engine:pkcs11:label_some-private-key\n

As a third possibility, for engines and providers that have implemented their own OSSL_STORE_LOADER(3), org.openssl.engine: should not be necessary. For a PKCS#11 implementation that has implemented such a loader, the PKCS#11 URI as defined in RFC 7512 should be possible to use directly:

-key pkcs11:object=some-private-key;pin-value=1234\n
"},{"location":"man1/openssl/#provider-options","title":"Provider Options","text":""},{"location":"man1/openssl/#environment","title":"ENVIRONMENT","text":"

The OpenSSL library can be take some configuration parameters from the environment. Some of these variables are listed below. For information about specific commands, see openssl-engine(1), openssl-rehash(1), and tsget(1).

For information about the use of environment variables in configuration, see \"ENVIRONMENT\" in config(5).

For information about querying or specifying CPU architecture flags, see OPENSSL_ia32cap(3), OPENSSL_s390xcap(3) and OPENSSL_riscvcap(3).

For information about all environment variables used by the OpenSSL libraries, see openssl-env(7).

"},{"location":"man1/openssl/#see-also","title":"SEE ALSO","text":"

openssl-asn1parse(1), openssl-ca(1), openssl-ciphers(1), openssl-cms(1), openssl-crl(1), openssl-crl2pkcs7(1), openssl-dgst(1), openssl-dhparam(1), openssl-dsa(1), openssl-dsaparam(1), openssl-ec(1), openssl-ecparam(1), openssl-enc(1), openssl-engine(1), openssl-errstr(1), openssl-gendsa(1), openssl-genpkey(1), openssl-genrsa(1), openssl-kdf(1), openssl-list(1), openssl-mac(1), openssl-nseq(1), openssl-ocsp(1), openssl-passwd(1), openssl-pkcs12(1), openssl-pkcs7(1), openssl-pkcs8(1), openssl-pkey(1), openssl-pkeyparam(1), openssl-pkeyutl(1), openssl-prime(1), openssl-rand(1), openssl-rehash(1), openssl-req(1), openssl-rsa(1), openssl-rsautl(1), openssl-s_client(1), openssl-s_server(1), openssl-s_time(1), openssl-sess_id(1), openssl-smime(1), openssl-speed(1), openssl-spkac(1), openssl-srp(1), openssl-storeutl(1), openssl-ts(1), openssl-verify(1), openssl-version(1), openssl-x509(1), config(5), crypto(7), openssl-env(7). ssl(7), x509v3_config(5)

"},{"location":"man1/openssl/#history","title":"HISTORY","text":"

The list -XXX-algorithms options were added in OpenSSL 1.0.0; For notes on the availability of other commands, see their individual manual pages.

The -issuer_checks option is deprecated as of OpenSSL 1.1.0 and is silently ignored.

The -xcertform and -xkeyform options are obsolete since OpenSSL 3.0 and have no effect.

The interactive mode, which could be invoked by running openssl with no further arguments, was removed in OpenSSL 3.0, and running that program with no arguments is now equivalent to openssl help.

"},{"location":"man1/openssl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man1/tsget/","title":"tsget","text":""},{"location":"man1/tsget/#name","title":"NAME","text":"

tsget - Time Stamping HTTP/HTTPS client

"},{"location":"man1/tsget/#synopsis","title":"SYNOPSIS","text":"

tsget -h server_url [-e extension] [-o output] [-v] [-d] [-k private_key.pem] [-p key_password] [-c client_cert.pem] [-C CA_certs.pem] [-P CA_path] [-r files] [-g EGD_socket] [request ...]

"},{"location":"man1/tsget/#description","title":"DESCRIPTION","text":"

This command can be used for sending a timestamp request, as specified in RFC 3161, to a timestamp server over HTTP or HTTPS and storing the timestamp response in a file. It cannot be used for creating the requests and verifying responses, you have to use openssl-ts(1) to do that. This command can send several requests to the server without closing the TCP connection if more than one requests are specified on the command line.

This command sends the following HTTP request for each timestamp request:

    POST url HTTP/1.1\n    User-Agent: OpenTSA tsget.pl/<version>\n    Host: <host>:<port>\n    Pragma: no-cache\n    Content-Type: application/timestamp-query\n    Accept: application/timestamp-reply\n    Content-Length: length of body\n\n    ...binary request specified by the user...\n

It expects a response of type application/timestamp-reply, which is written to a file without any interpretation.

"},{"location":"man1/tsget/#options","title":"OPTIONS","text":""},{"location":"man1/tsget/#environment-variables","title":"ENVIRONMENT VARIABLES","text":"

The TSGET environment variable can optionally contain default arguments. The content of this variable is added to the list of command line arguments.

"},{"location":"man1/tsget/#examples","title":"EXAMPLES","text":"

The examples below presume that file1.tsq and file2.tsq contain valid timestamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests and at port 8443 for HTTPS requests, the TSA service is available at the /tsa absolute path.

Get a timestamp response for file1.tsq over HTTP, output is written to file1.tsr:

tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq\n

Get a timestamp response for file1.tsq and file2.tsq over HTTP showing progress, output is written to file1.reply and file2.reply respectively:

tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \\\n      file1.tsq file2.tsq\n

Create a timestamp request, write it to file3.tsq, send it to the server and write the response to file3.tsr:

openssl ts -query -data file3.txt -cert | tee file3.tsq \\\n      | tsget -h http://tsa.opentsa.org:8080/tsa \\\n      -o file3.tsr\n

Get a timestamp response for file1.tsq over HTTPS without client authentication:

tsget -h https://tsa.opentsa.org:8443/tsa \\\n      -C cacerts.pem file1.tsq\n

Get a timestamp response for file1.tsq over HTTPS with certificate-based client authentication (it will ask for the passphrase if client_key.pem is protected):

tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \\\n      -k client_key.pem -c client_cert.pem file1.tsq\n

You can shorten the previous command line if you make use of the TSGET environment variable. The following commands do the same as the previous example:

TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \\\n      -k client_key.pem -c client_cert.pem'\nexport TSGET\ntsget file1.tsq\n
"},{"location":"man1/tsget/#see-also","title":"SEE ALSO","text":"

openssl(1), openssl-ts(1), WWW::Curl::Easy, https://www.rfc-editor.org/rfc/rfc3161.html

"},{"location":"man1/tsget/#copyright","title":"COPYRIGHT","text":"

Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ADMISSIONS/","title":"ADMISSIONS","text":""},{"location":"man3/ADMISSIONS/#name","title":"NAME","text":"

ADMISSIONS, ADMISSIONS_get0_admissionAuthority, ADMISSIONS_get0_namingAuthority, ADMISSIONS_get0_professionInfos, ADMISSIONS_set0_admissionAuthority, ADMISSIONS_set0_namingAuthority, ADMISSIONS_set0_professionInfos, ADMISSION_SYNTAX, ADMISSION_SYNTAX_get0_admissionAuthority, ADMISSION_SYNTAX_get0_contentsOfAdmissions, ADMISSION_SYNTAX_set0_admissionAuthority, ADMISSION_SYNTAX_set0_contentsOfAdmissions, NAMING_AUTHORITY, NAMING_AUTHORITY_get0_authorityId, NAMING_AUTHORITY_get0_authorityURL, NAMING_AUTHORITY_get0_authorityText, NAMING_AUTHORITY_set0_authorityId, NAMING_AUTHORITY_set0_authorityURL, NAMING_AUTHORITY_set0_authorityText, PROFESSION_INFO, PROFESSION_INFOS, PROFESSION_INFO_get0_addProfessionInfo, PROFESSION_INFO_get0_namingAuthority, PROFESSION_INFO_get0_professionItems, PROFESSION_INFO_get0_professionOIDs, PROFESSION_INFO_get0_registrationNumber, PROFESSION_INFO_set0_addProfessionInfo, PROFESSION_INFO_set0_namingAuthority, PROFESSION_INFO_set0_professionItems, PROFESSION_INFO_set0_professionOIDs, PROFESSION_INFO_set0_registrationNumber - Accessors and settors for ADMISSION_SYNTAX

"},{"location":"man3/ADMISSIONS/#synopsis","title":"SYNOPSIS","text":"
typedef struct NamingAuthority_st NAMING_AUTHORITY;\ntypedef struct ProfessionInfo_st PROFESSION_INFO;\ntypedef STACK_OF(PROFESSION_INFO) PROFESSION_INFOS;\ntypedef struct Admissions_st ADMISSIONS;\ntypedef struct AdmissionSyntax_st ADMISSION_SYNTAX;\n\nconst ASN1_OBJECT *NAMING_AUTHORITY_get0_authorityId(\n    const NAMING_AUTHORITY *n);\nvoid NAMING_AUTHORITY_set0_authorityId(NAMING_AUTHORITY *n,\n    ASN1_OBJECT* namingAuthorityId);\nconst ASN1_IA5STRING *NAMING_AUTHORITY_get0_authorityURL(\n    const NAMING_AUTHORITY *n);\nvoid NAMING_AUTHORITY_set0_authorityURL(NAMING_AUTHORITY *n,\n    ASN1_IA5STRING* namingAuthorityUrl);\nconst ASN1_STRING *NAMING_AUTHORITY_get0_authorityText(\n    const NAMING_AUTHORITY *n);\nvoid NAMING_AUTHORITY_set0_authorityText(NAMING_AUTHORITY *n,\n    ASN1_STRING* namingAuthorityText);\n\nconst GENERAL_NAME *ADMISSION_SYNTAX_get0_admissionAuthority(\n    const ADMISSION_SYNTAX *as);\nvoid ADMISSION_SYNTAX_set0_admissionAuthority(\n    ADMISSION_SYNTAX *as, GENERAL_NAME *aa);\nconst STACK_OF(ADMISSIONS) *ADMISSION_SYNTAX_get0_contentsOfAdmissions(\n    const ADMISSION_SYNTAX *as);\nvoid ADMISSION_SYNTAX_set0_contentsOfAdmissions(\n    ADMISSION_SYNTAX *as, STACK_OF(ADMISSIONS) *a);\n\nconst GENERAL_NAME *ADMISSIONS_get0_admissionAuthority(const ADMISSIONS *a);\nvoid ADMISSIONS_set0_admissionAuthority(ADMISSIONS *a, GENERAL_NAME *aa);\nconst NAMING_AUTHORITY *ADMISSIONS_get0_namingAuthority(const ADMISSIONS *a);\nvoid ADMISSIONS_set0_namingAuthority(ADMISSIONS *a, NAMING_AUTHORITY *na);\nconst PROFESSION_INFOS *ADMISSIONS_get0_professionInfos(const ADMISSIONS *a);\nvoid ADMISSIONS_set0_professionInfos(ADMISSIONS *a, PROFESSION_INFOS *pi);\n\nconst ASN1_OCTET_STRING *PROFESSION_INFO_get0_addProfessionInfo(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_addProfessionInfo(\n    PROFESSION_INFO *pi, ASN1_OCTET_STRING *aos);\nconst NAMING_AUTHORITY *PROFESSION_INFO_get0_namingAuthority(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_namingAuthority(\n    PROFESSION_INFO *pi, NAMING_AUTHORITY *na);\nconst STACK_OF(ASN1_STRING) *PROFESSION_INFO_get0_professionItems(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_professionItems(\n    PROFESSION_INFO *pi, STACK_OF(ASN1_STRING) *as);\nconst STACK_OF(ASN1_OBJECT) *PROFESSION_INFO_get0_professionOIDs(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_professionOIDs(\n    PROFESSION_INFO *pi, STACK_OF(ASN1_OBJECT) *po);\nconst ASN1_PRINTABLESTRING *PROFESSION_INFO_get0_registrationNumber(\n    const PROFESSION_INFO *pi);\nvoid PROFESSION_INFO_set0_registrationNumber(\n    PROFESSION_INFO *pi, ASN1_PRINTABLESTRING *rn);\n
"},{"location":"man3/ADMISSIONS/#description","title":"DESCRIPTION","text":"

The PROFESSION_INFOS, ADMISSION_SYNTAX, ADMISSIONS, and PROFESSION_INFO types are opaque structures representing the analogous types defined in the Common PKI Specification published by https://www.t7ev.org. Knowledge of those structures and their semantics is assumed.

The conventional routines to convert between DER and the local format are described in d2i_X509(3). The conventional routines to allocate and free the types are defined in X509_dup(3).

The PROFESSION_INFOS type is a stack of PROFESSION_INFO; see DEFINE_STACK_OF(3) for details.

The NAMING_AUTHORITY type has an authority ID and URL, and text fields. The NAMING_AUTHORITY_get0_authorityId(), NAMING_AUTHORITY_get0_get0_authorityURL(), and NAMING_AUTHORITY_get0_get0_authorityText(), functions return pointers to those values within the object. The NAMING_AUTHORITY_set0_authorityId(), NAMING_AUTHORITY_set0_get0_authorityURL(), and NAMING_AUTHORITY_set0_get0_authorityText(), functions free any existing value and set the pointer to the specified value.

The ADMISSION_SYNTAX type has an authority name and a stack of ADMISSION objects. The ADMISSION_SYNTAX_get0_admissionAuthority() and ADMISSION_SYNTAX_get0_contentsOfAdmissions() functions return pointers to those values within the object. The ADMISSION_SYNTAX_set0_admissionAuthority() and ADMISSION_SYNTAX_set0_contentsOfAdmissions() functions free any existing value and set the pointer to the specified value.

The ADMISSION type has an authority name, authority object, and a stack of PROFESSION_INFO items. The ADMISSIONS_get0_admissionAuthority(), ADMISSIONS_get0_namingAuthority(), and ADMISSIONS_get0_professionInfos() functions return pointers to those values within the object. The ADMISSIONS_set0_admissionAuthority(), ADMISSIONS_set0_namingAuthority(), and ADMISSIONS_set0_professionInfos() functions free any existing value and set the pointer to the specified value.

The PROFESSION_INFO type has a name authority, stacks of profession Items and OIDs, a registration number, and additional profession info. The functions PROFESSION_INFO_get0_addProfessionInfo(), PROFESSION_INFO_get0_namingAuthority(), PROFESSION_INFO_get0_professionItems(), PROFESSION_INFO_get0_professionOIDs(), and PROFESSION_INFO_get0_registrationNumber() functions return pointers to those values within the object. The PROFESSION_INFO_set0_addProfessionInfo(), PROFESSION_INFO_set0_namingAuthority(), PROFESSION_INFO_set0_professionItems(), PROFESSION_INFO_set0_professionOIDs(), and PROFESSION_INFO_set0_registrationNumber() functions free any existing value and set the pointer to the specified value.

"},{"location":"man3/ADMISSIONS/#return-values","title":"RETURN VALUES","text":"

Described above. Note that all of the get0 functions return a pointer to the internal data structure and must not be freed.

"},{"location":"man3/ADMISSIONS/#see-also","title":"SEE ALSO","text":"

X509_dup(3), d2i_X509(3),

"},{"location":"man3/ADMISSIONS/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_EXTERN_FUNCS/","title":"ASN1_EXTERN_FUNCS","text":""},{"location":"man3/ASN1_EXTERN_FUNCS/#name","title":"NAME","text":"

ASN1_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func, ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func, IMPLEMENT_EXTERN_ASN1 - ASN.1 external function support

"},{"location":"man3/ASN1_EXTERN_FUNCS/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1t.h>\n\ntypedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len,\n                        const ASN1_ITEM *it, int tag, int aclass, char opt,\n                        ASN1_TLC *ctx);\ntypedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len,\n                           const ASN1_ITEM *it, int tag, int aclass, char opt,\n                           ASN1_TLC *ctx, OSSL_LIB_CTX *libctx,\n                           const char *propq);\ntypedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out,\n                        const ASN1_ITEM *it, int tag, int aclass);\ntypedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it);\ntypedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it,\n                                OSSL_LIB_CTX *libctx, const char *propq);\ntypedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it);\ntypedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval,\n                               int indent, const char *fname,\n                               const ASN1_PCTX *pctx);\n\nstruct ASN1_EXTERN_FUNCS_st {\n   void *app_data;\n   ASN1_ex_new_func *asn1_ex_new;\n   ASN1_ex_free_func *asn1_ex_free;\n   ASN1_ex_free_func *asn1_ex_clear;\n   ASN1_ex_d2i *asn1_ex_d2i;\n   ASN1_ex_i2d *asn1_ex_i2d;\n   ASN1_ex_print_func *asn1_ex_print;\n   ASN1_ex_new_ex_func *asn1_ex_new_ex;\n   ASN1_ex_d2i_ex *asn1_ex_d2i_ex;\n};\ntypedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS;\n\n#define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs)\n
"},{"location":"man3/ASN1_EXTERN_FUNCS/#description","title":"DESCRIPTION","text":"

ASN.1 data structures templates are typically defined in OpenSSL using a series of macros such as ASN1_SEQUENCE(), ASN1_SEQUENCE_END() and so on. Instead templates can also be defined based entirely on external functions. These external functions are called to perform operations such as creating a new ASN1_VALUE or converting an ASN1_VALUE to or from DER encoding.

The macro IMPLEMENT_EXTERN_ASN1() can be used to create such an externally defined structure. The name of the structure should be supplied in the sname parameter. The tag for the structure (e.g. typically V_ASN1_SEQUENCE) should be supplied in the tag parameter. Finally a pointer to an ASN1_EXTERN_FUNCS structure should be supplied in the fptrs parameter.

The ASN1_EXTERN_FUNCS structure has the following entries.

"},{"location":"man3/ASN1_EXTERN_FUNCS/#return-values","title":"RETURN VALUES","text":"

Return values for the various callbacks are as described above.

"},{"location":"man3/ASN1_EXTERN_FUNCS/#see-also","title":"SEE ALSO","text":"

ASN1_item_new_ex(3)

"},{"location":"man3/ASN1_EXTERN_FUNCS/#history","title":"HISTORY","text":"

The asn1_ex_new_ex and asn1_ex_d2i_ex callbacks were added in OpenSSL 3.0.

"},{"location":"man3/ASN1_EXTERN_FUNCS/#copyright","title":"COPYRIGHT","text":"

Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_INTEGER_get_int64/","title":"ASN1_INTEGER_get_int64","text":""},{"location":"man3/ASN1_INTEGER_get_int64/#name","title":"NAME","text":"

ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN - ASN.1 INTEGER and ENUMERATED utilities

"},{"location":"man3/ASN1_INTEGER_get_int64/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);\nlong ASN1_INTEGER_get(const ASN1_INTEGER *a);\n\nint ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);\nint ASN1_INTEGER_set(ASN1_INTEGER *a, long v);\n\nint ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);\nint ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);\n\nASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);\nBIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);\n\nint ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a);\nlong ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);\n\nint ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r);\nint ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);\n\nASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(const BIGNUM *bn, ASN1_ENUMERATED *ai);\nBIGNUM *ASN1_ENUMERATED_to_BN(const ASN1_ENUMERATED *ai, BIGNUM *bn);\n
"},{"location":"man3/ASN1_INTEGER_get_int64/#description","title":"DESCRIPTION","text":"

These functions convert to and from ASN1_INTEGER and ASN1_ENUMERATED structures.

ASN1_INTEGER_get_int64() converts an ASN1_INTEGER into an int64_t type If successful it returns 1 and sets *pr to the value of a. If it fails (due to invalid type or the value being too big to fit into an int64_t type) it returns 0.

ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it converts to a uint64_t type and an error is returned if the passed integer is negative.

ASN1_INTEGER_get() also returns the value of a but it returns 0 if a is NULL and -1 on error (which is ambiguous because -1 is a legitimate value for an ASN1_INTEGER). New applications should use ASN1_INTEGER_get_int64() instead.

ASN1_INTEGER_set_int64() sets the value of ASN1_INTEGER a to the int64_t value r.

ASN1_INTEGER_set_uint64() sets the value of ASN1_INTEGER a to the uint64_t value r.

ASN1_INTEGER_set() sets the value of ASN1_INTEGER a to the long value v.

BN_to_ASN1_INTEGER() converts BIGNUM bn to an ASN1_INTEGER. If ai is NULL a new ASN1_INTEGER structure is returned. If ai is not NULL then the existing structure will be used instead.

ASN1_INTEGER_to_BN() converts ASN1_INTEGER ai into a BIGNUM. If bn is NULL a new BIGNUM structure is returned. If bn is not NULL then the existing structure will be used instead.

ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(), ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN() behave in an identical way to their ASN1_INTEGER counterparts except they operate on an ASN1_ENUMERATED value.

ASN1_ENUMERATED_get() returns the value of a in a similar way to ASN1_INTEGER_get() but it returns 0xffffffffL if the value of a will not fit in a long type. New applications should use ASN1_ENUMERATED_get_int64() instead.

"},{"location":"man3/ASN1_INTEGER_get_int64/#notes","title":"NOTES","text":"

In general an ASN1_INTEGER or ASN1_ENUMERATED type can contain an integer of almost arbitrary size and so cannot always be represented by a C int64_t type. However, in many cases (for example version numbers) they represent small integers which can be more easily manipulated if converted to an appropriate C integer type.

"},{"location":"man3/ASN1_INTEGER_get_int64/#bugs","title":"BUGS","text":"

The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get() mean these functions should be avoided if possible. They are retained for compatibility. Normally the ambiguous return values are not legitimate values for the fields they represent.

"},{"location":"man3/ASN1_INTEGER_get_int64/#return-values","title":"RETURN VALUES","text":"

ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only fail if a memory allocation error occurs.

ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success and 0 for failure. They will fail if the passed type is incorrect (this will only happen if there is a programming error) or if the value exceeds the range of an int64_t type.

BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an ASN1_INTEGER or ASN1_ENUMERATED structure respectively or NULL if an error occurs. They will only fail due to a memory allocation error.

ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a BIGNUM structure of NULL if an error occurs. They can fail if the passed type is incorrect (due to programming error) or due to a memory allocation failure.

"},{"location":"man3/ASN1_INTEGER_get_int64/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_INTEGER_get_int64/#history","title":"HISTORY","text":"

ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(), ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64() were added in OpenSSL 1.1.0.

"},{"location":"man3/ASN1_INTEGER_get_int64/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_INTEGER_new/","title":"ASN1_INTEGER_new","text":""},{"location":"man3/ASN1_INTEGER_new/#name","title":"NAME","text":"

ASN1_INTEGER_new, ASN1_INTEGER_free - ASN1_INTEGER allocation functions

"},{"location":"man3/ASN1_INTEGER_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_INTEGER *ASN1_INTEGER_new(void);\nvoid ASN1_INTEGER_free(ASN1_INTEGER *a);\n
"},{"location":"man3/ASN1_INTEGER_new/#description","title":"DESCRIPTION","text":"

ASN1_INTEGER_new() returns an allocated ASN1_INTEGER structure.

ASN1_INTEGER_free() frees up a single ASN1_INTEGER object. If the argument is NULL, nothing is done.

ASN1_INTEGER structure representing the ASN.1 INTEGER type

"},{"location":"man3/ASN1_INTEGER_new/#return-values","title":"RETURN VALUES","text":"

ASN1_INTEGER_new() return a valid ASN1_INTEGER structure or NULL if an error occurred.

ASN1_INTEGER_free() does not return a value.

"},{"location":"man3/ASN1_INTEGER_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_INTEGER_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_ITEM_lookup/","title":"ASN1_ITEM_lookup","text":""},{"location":"man3/ASN1_ITEM_lookup/#name","title":"NAME","text":"

ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures

"},{"location":"man3/ASN1_ITEM_lookup/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nconst ASN1_ITEM *ASN1_ITEM_lookup(const char *name);\nconst ASN1_ITEM *ASN1_ITEM_get(size_t i);\n
"},{"location":"man3/ASN1_ITEM_lookup/#description","title":"DESCRIPTION","text":"

ASN1_ITEM_lookup() returns the ASN1_ITEM named name.

ASN1_ITEM_get() returns the ASN1_ITEM with index i. This function returns NULL if the index i is out of range.

"},{"location":"man3/ASN1_ITEM_lookup/#return-values","title":"RETURN VALUES","text":"

ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid ASN1_ITEM structure or NULL if an error occurred.

"},{"location":"man3/ASN1_ITEM_lookup/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_ITEM_lookup/#copyright","title":"COPYRIGHT","text":"

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_OBJECT_new/","title":"ASN1_OBJECT_new","text":""},{"location":"man3/ASN1_OBJECT_new/#name","title":"NAME","text":"

ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions

"},{"location":"man3/ASN1_OBJECT_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_OBJECT *ASN1_OBJECT_new(void);\nvoid ASN1_OBJECT_free(ASN1_OBJECT *a);\n
"},{"location":"man3/ASN1_OBJECT_new/#description","title":"DESCRIPTION","text":"

The ASN1_OBJECT allocation routines, allocate and free an ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.

ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.

ASN1_OBJECT_free() frees up the ASN1_OBJECT structure a. If a is NULL, nothing is done.

"},{"location":"man3/ASN1_OBJECT_new/#notes","title":"NOTES","text":"

Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it is almost never used in applications. The ASN1 object utility functions such as OBJ_nid2obj() are used instead.

"},{"location":"man3/ASN1_OBJECT_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, ASN1_OBJECT_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

ASN1_OBJECT_free() returns no value.

"},{"location":"man3/ASN1_OBJECT_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), d2i_ASN1_OBJECT(3)

"},{"location":"man3/ASN1_OBJECT_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_STRING_TABLE_add/","title":"ASN1_STRING_TABLE_add","text":""},{"location":"man3/ASN1_STRING_TABLE_add/#name","title":"NAME","text":"

ASN1_STRING_TABLE, ASN1_STRING_TABLE_add, ASN1_STRING_TABLE_get, ASN1_STRING_TABLE_cleanup - ASN1_STRING_TABLE manipulation functions

"},{"location":"man3/ASN1_STRING_TABLE_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\ntypedef struct asn1_string_table_st ASN1_STRING_TABLE;\n\nint ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize,\n                          unsigned long mask, unsigned long flags);\nASN1_STRING_TABLE *ASN1_STRING_TABLE_get(int nid);\nvoid ASN1_STRING_TABLE_cleanup(void);\n
"},{"location":"man3/ASN1_STRING_TABLE_add/#description","title":"DESCRIPTION","text":""},{"location":"man3/ASN1_STRING_TABLE_add/#types","title":"Types","text":"

ASN1_STRING_TABLE is a table which holds string information (basically minimum size, maximum size, type and etc) for a NID object.

"},{"location":"man3/ASN1_STRING_TABLE_add/#functions","title":"Functions","text":"

ASN1_STRING_TABLE_add() adds a new ASN1_STRING_TABLE item into the local ASN1 string table based on the nid along with other parameters.

If the item is already in the table, fields of ASN1_STRING_TABLE are updated (depending on the values of those parameters, e.g., minsize and maxsize >= 0, mask and flags != 0). If the nid is standard, a copy of the standard ASN1_STRING_TABLE is created and updated with other parameters.

ASN1_STRING_TABLE_get() searches for an ASN1_STRING_TABLE item based on nid. It will search the local table first, then the standard one.

ASN1_STRING_TABLE_cleanup() frees all ASN1_STRING_TABLE items added by ASN1_STRING_TABLE_add().

"},{"location":"man3/ASN1_STRING_TABLE_add/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_TABLE_add() returns 1 on success, 0 if an error occurred.

ASN1_STRING_TABLE_get() returns a valid ASN1_STRING_TABLE structure or NULL if nothing is found.

ASN1_STRING_TABLE_cleanup() does not return a value.

"},{"location":"man3/ASN1_STRING_TABLE_add/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_STRING_TABLE_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_STRING_length/","title":"ASN1_STRING_length","text":""},{"location":"man3/ASN1_STRING_length/#name","title":"NAME","text":"

ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, ASN1_STRING_to_UTF8 - ASN1_STRING utility functions

"},{"location":"man3/ASN1_STRING_length/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_STRING_length(ASN1_STRING *x);\nconst unsigned char *ASN1_STRING_get0_data(const ASN1_STRING *x);\nunsigned char *ASN1_STRING_data(ASN1_STRING *x);\n\nASN1_STRING *ASN1_STRING_dup(const ASN1_STRING *a);\n\nint ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);\n\nint ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);\n\nint ASN1_STRING_type(const ASN1_STRING *x);\n\nint ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);\n
"},{"location":"man3/ASN1_STRING_length/#description","title":"DESCRIPTION","text":"

These functions allow an ASN1_STRING structure to be manipulated.

ASN1_STRING_length() returns the length of the content of x.

ASN1_STRING_get0_data() returns an internal pointer to the data of x. Since this is an internal pointer it should not be freed or modified in any way.

ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the returned value is not constant. This function is deprecated: applications should use ASN1_STRING_get0_data() instead.

ASN1_STRING_dup() returns a copy of the structure a.

ASN1_STRING_cmp() compares a and b returning 0 if the two are identical. The string types and content are compared.

ASN1_STRING_set() sets the data of string str to the buffer data or length len. The supplied data is copied. If len is -1 then the length is determined by strlen(data).

ASN1_STRING_type() returns the type of x, using standard constants such as V_ASN1_OCTET_STRING.

ASN1_STRING_to_UTF8() converts the string in to UTF8 format, the converted data is allocated in a buffer in *out. The length of out is returned or a negative error code. The buffer *out should be freed using OPENSSL_free().

"},{"location":"man3/ASN1_STRING_length/#notes","title":"NOTES","text":"

Almost all ASN1 types in OpenSSL are represented as an ASN1_STRING structure. Other types such as ASN1_OCTET_STRING are simply typedef'ed to ASN1_STRING and the functions call the ASN1_STRING equivalents. ASN1_STRING is also used for some CHOICE types which consist entirely of primitive string types such as DirectoryString and Time.

These functions should not be used to examine or modify ASN1_INTEGER or ASN1_ENUMERATED types: the relevant INTEGER or ENUMERATED utility functions should be used instead.

In general it cannot be assumed that the data returned by ASN1_STRING_data() is null terminated or does not contain embedded nulls. The actual format of the data will depend on the actual string type itself: for example for an IA5String the data will be ASCII, for a BMPString two bytes per character in big endian format, and for a UTF8String it will be in UTF8 format.

Similar care should be take to ensure the data is in the correct format when calling ASN1_STRING_set().

"},{"location":"man3/ASN1_STRING_length/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_length() returns the length of the content of x.

ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to the data of x.

ASN1_STRING_dup() returns a valid ASN1_STRING structure or NULL if an error occurred.

ASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0, according to whether a is greater than, equal to, or less than b.

ASN1_STRING_set() returns 1 on success or 0 on error.

ASN1_STRING_type() returns the type of x.

ASN1_STRING_to_UTF8() returns the number of bytes in output string out or a negative value if an error occurred.

"},{"location":"man3/ASN1_STRING_length/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_STRING_length/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_STRING_new/","title":"ASN1_STRING_new","text":""},{"location":"man3/ASN1_STRING_new/#name","title":"NAME","text":"

ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free - ASN1_STRING allocation functions

"},{"location":"man3/ASN1_STRING_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_STRING *ASN1_STRING_new(void);\nASN1_STRING *ASN1_STRING_type_new(int type);\nvoid ASN1_STRING_free(ASN1_STRING *a);\n
"},{"location":"man3/ASN1_STRING_new/#description","title":"DESCRIPTION","text":"

ASN1_STRING_new() returns an allocated ASN1_STRING structure. Its type is undefined.

ASN1_STRING_type_new() returns an allocated ASN1_STRING structure of type type.

ASN1_STRING_free() frees up a. If a is NULL nothing is done.

"},{"location":"man3/ASN1_STRING_new/#notes","title":"NOTES","text":"

Other string types call the ASN1_STRING functions. For example ASN1_OCTET_STRING_new() calls ASN1_STRING_type_new(V_ASN1_OCTET_STRING).

"},{"location":"man3/ASN1_STRING_new/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_new() and ASN1_STRING_type_new() return a valid ASN1_STRING structure or NULL if an error occurred.

ASN1_STRING_free() does not return a value.

"},{"location":"man3/ASN1_STRING_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_STRING_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_STRING_print_ex/","title":"ASN1_STRING_print_ex","text":""},{"location":"man3/ASN1_STRING_print_ex/#name","title":"NAME","text":"

ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines

"},{"location":"man3/ASN1_STRING_print_ex/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);\nint ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);\nint ASN1_STRING_print(BIO *out, const ASN1_STRING *str);\n\nconst char *ASN1_tag2str(int tag);\n
"},{"location":"man3/ASN1_STRING_print_ex/#description","title":"DESCRIPTION","text":"

These functions output an ASN1_STRING structure. ASN1_STRING is used to represent all the ASN1 string types.

ASN1_STRING_print_ex() outputs str to out, the format is determined by the options flags. ASN1_STRING_print_ex_fp() is identical except it outputs to fp instead.

ASN1_STRING_print() prints str to out but using a different format to ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF) with '.'.

ASN1_tag2str() returns a human-readable name of the specified ASN.1 tag.

"},{"location":"man3/ASN1_STRING_print_ex/#notes","title":"NOTES","text":"

ASN1_STRING_print() is a deprecated function which should be avoided; use ASN1_STRING_print_ex() instead.

Although there are a large number of options frequently ASN1_STRFLGS_RFC2253 is suitable, or on UTF8 terminals ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB.

The complete set of supported options for flags is listed below.

Various characters can be escaped. If ASN1_STRFLGS_ESC_2253 is set the characters determined by RFC2253 are escaped. If ASN1_STRFLGS_ESC_CTRL is set control characters are escaped. If ASN1_STRFLGS_ESC_MSB is set characters with the MSB set are escaped: this option should not be used if the terminal correctly interprets UTF8 sequences.

Escaping takes several forms.

If the character being escaped is a 16 bit character then the form \"\\UXXXX\" is used using exactly four characters for the hex representation. If it is 32 bits then \"\\WXXXXXXXX\" is used using eight characters of its hex representation. These forms will only be used if UTF8 conversion is not set (see below).

Printable characters are normally escaped using the backslash '\\' character. If ASN1_STRFLGS_ESC_QUOTE is set then the whole string is instead surrounded by double quote characters: this is arguably more readable than the backslash notation. Other characters use the \"\\XX\" using exactly two characters of the hex representation.

If ASN1_STRFLGS_UTF8_CONVERT is set then characters are converted to UTF8 format first. If the terminal supports the display of UTF8 sequences then this option will correctly display multi byte characters.

If ASN1_STRFLGS_IGNORE_TYPE is set then the string type is not interpreted at all: everything is assumed to be one byte per character. This is primarily for debugging purposes and can result in confusing output in multi character strings.

If ASN1_STRFLGS_SHOW_TYPE is set then the string type itself is printed out before its value (for example \"BMPSTRING\"), this actually uses ASN1_tag2str().

The content of a string instead of being interpreted can be \"dumped\": this just outputs the value of the string using the form #XXXX using hex format for each octet.

If ASN1_STRFLGS_DUMP_ALL is set then any type is dumped.

Normally non character string types (such as OCTET STRING) are assumed to be one byte per character, if ASN1_STRFLGS_DUMP_UNKNOWN is set then they will be dumped instead.

When a type is dumped normally just the content octets are printed, if ASN1_STRFLGS_DUMP_DER is set then the complete encoding is dumped instead (including tag and length octets).

ASN1_STRFLGS_RFC2253 includes all the flags required by RFC2253. It is equivalent to: ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER

"},{"location":"man3/ASN1_STRING_print_ex/#return-values","title":"RETURN VALUES","text":"

ASN1_STRING_print_ex() and ASN1_STRING_print_ex_fp() return the number of characters written or -1 if an error occurred.

ASN1_STRING_print() returns 1 on success or 0 on error.

ASN1_tag2str() returns a human-readable name of the specified ASN.1 tag.

"},{"location":"man3/ASN1_STRING_print_ex/#see-also","title":"SEE ALSO","text":"

X509_NAME_print_ex(3), ASN1_tag2str(3)

"},{"location":"man3/ASN1_STRING_print_ex/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_TIME_set/","title":"ASN1_TIME_set","text":""},{"location":"man3/ASN1_TIME_set/#name","title":"NAME","text":"

ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, ASN1_TIME_set_string_X509, ASN1_TIME_normalize, ASN1_TIME_to_tm, ASN1_TIME_print, ASN1_TIME_print_ex, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, ASN1_TIME_diff, ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t, ASN1_TIME_compare, ASN1_TIME_to_generalizedtime, ASN1_TIME_dup, ASN1_UTCTIME_dup, ASN1_GENERALIZEDTIME_dup - ASN.1 Time functions

"},{"location":"man3/ASN1_TIME_set/#synopsis","title":"SYNOPSIS","text":"
ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);\nASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);\nASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,\n                                               time_t t);\n\nASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day,\n                         long offset_sec);\nASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,\n                               int offset_day, long offset_sec);\nASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,\n                                               time_t t, int offset_day,\n                                               long offset_sec);\n\nint ASN1_TIME_set_string(ASN1_TIME *s, const char *str);\nint ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);\nint ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);\nint ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s,\n                                    const char *str);\n\nint ASN1_TIME_normalize(ASN1_TIME *s);\n\nint ASN1_TIME_check(const ASN1_TIME *t);\nint ASN1_UTCTIME_check(const ASN1_UTCTIME *t);\nint ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t);\n\nint ASN1_TIME_print(BIO *b, const ASN1_TIME *s);\nint ASN1_TIME_print_ex(BIO *bp, const ASN1_TIME *tm, unsigned long flags);\nint ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s);\nint ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s);\n\nint ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);\nint ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from,\n                   const ASN1_TIME *to);\n\nint ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t);\nint ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);\n\nint ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b);\n\nASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t,\n                                                   ASN1_GENERALIZEDTIME **out);\n\nASN1_TIME *ASN1_TIME_dup(const ASN1_TIME *t);\nASN1_UTCTIME *ASN1_UTCTIME_dup(const ASN1_UTCTIME *t);\nASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_dup(const ASN1_GENERALIZEDTIME *t);\n
"},{"location":"man3/ASN1_TIME_set/#description","title":"DESCRIPTION","text":"

The ASN1_TIME_set(), ASN1_UTCTIME_set() and ASN1_GENERALIZEDTIME_set() functions set the structure s to the time represented by the time_t value t. If s is NULL a new time structure is allocated and returned.

The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj() functions set the time structure s to the time represented by the time offset_day and offset_sec after the time_t value t. The values of offset_day or offset_sec can be negative to set a time before t. The offset_sec value can also exceed the number of seconds in a day. If s is NULL a new structure is allocated and returned.

The ASN1_TIME_set_string(), ASN1_UTCTIME_set_string() and ASN1_GENERALIZEDTIME_set_string() functions set the time structure s to the time represented by string str which must be in appropriate ASN.1 time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If s is NULL this function performs a format check on str only. The string str is copied into s.

ASN1_TIME_set_string_X509() sets ASN1_TIME structure s to the time represented by string str which must be in appropriate time format that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format are not allowed. If s is NULL this function performs a format check on str only.

The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or ASN1_UTCTIME into a time value that can be used in a certificate. It should be used after the ASN1_TIME_set_string() functions and before ASN1_TIME_print() functions to get consistent (i.e. GMT) results.

The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check() functions check the syntax of the time structure s.

The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() functions print the time structure s to BIO b in human readable format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example \"Feb 3 00:55:52 2015 GMT\", which does not include a newline. If the time structure has invalid format it prints out \"Bad time value\" and returns an error. The output for generalized time may include a fractional part following the second.

ASN1_TIME_print_ex() provides flags to specify the output format of the datetime. This can be either ASN1_DTFLGS_RFC822 or ASN1_DTFLGS_ISO8601.

ASN1_TIME_to_tm() converts the time s to the standard tm structure. If s is NULL, then the current time is converted. The output time is GMT. The tm_sec, tm_min, tm_hour, tm_mday, tm_wday, tm_yday, tm_mon and tm_year fields of tm structure are set to proper values, whereas all other fields are set to 0. If tm is NULL this function performs a format check on s only. If s is in Generalized format with fractional seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while converting s to tm structure.

ASN1_TIME_diff() sets *pday and *psec to the time difference between from and to. If to represents a time later than from then one or both (depending on the time difference) of *pday and *psec will be positive. If to represents a time earlier than from then one or both of *pday and *psec will be negative. If to and from represent the same time then *pday and *psec will both be zero. If both *pday and *psec are nonzero they will always have the same sign. The value of *psec will always be less than the number of seconds in a day. If from or to is NULL the current time is used.

The ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() functions compare the two times represented by the time structure s and the time_t t.

The ASN1_TIME_compare() function compares the two times represented by the time structures a and b.

The ASN1_TIME_to_generalizedtime() function converts an ASN1_TIME to an ASN1_GENERALIZEDTIME, regardless of year. If either out or *out are NULL, then a new object is allocated and must be freed after use.

The ASN1_TIME_dup(), ASN1_UTCTIME_dup() and ASN1_GENERALIZEDTIME_dup() functions duplicate the time structure t and return the duplicated result correspondingly.

"},{"location":"man3/ASN1_TIME_set/#notes","title":"NOTES","text":"

The ASN1_TIME structure corresponds to the ASN.1 structure Time defined in RFC5280 et al. The time setting functions obey the rules outlined in RFC5280: if the date can be represented by UTCTime it is used, else GeneralizedTime is used.

The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented as an ASN1_STRING internally and can be freed up using ASN1_STRING_free().

The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt is made to correct ancient calendar changes (for example from Julian to Gregorian calendars).

ASN1_UTCTIME is limited to a year range of 1950 through 2049.

Some applications add offset times directly to a time_t value and pass the results to ASN1_TIME_set() (or equivalent). This can cause problems as the time_t value can overflow on some systems resulting in unexpected results. New applications should use ASN1_TIME_adj() instead and pass the offset value in the offset_sec and offset_day parameters instead of directly manipulating a time_t value.

ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME, or vice versa, based on the resulting year. ASN1_GENERALIZEDTIME_adj() and ASN1_UTCTIME_adj() will not modify the type of the return structure.

It is recommended that functions starting with ASN1_TIME be used instead of those starting with ASN1_UTCTIME or ASN1_GENERALIZEDTIME. The functions starting with ASN1_UTCTIME and ASN1_GENERALIZEDTIME act only on that specific time format. The functions starting with ASN1_TIME will operate on either format.

"},{"location":"man3/ASN1_TIME_set/#bugs","title":"BUGS","text":"

ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() do not print out the timezone: it either prints out \"GMT\" or nothing. But all certificates complying with RFC5280 et al use GMT anyway.

ASN1_TIME_print(), ASN1_TIME_print_ex(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() do not distinguish if they fail because of an I/O error or invalid time format.

Use the ASN1_TIME_normalize() function to normalize the time value before printing to get GMT results.

"},{"location":"man3/ASN1_TIME_set/#return-values","title":"RETURN VALUES","text":"

ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_set() return a pointer to a time structure or NULL if an error occurred.

ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), ASN1_GENERALIZEDTIME_set_string() and ASN1_TIME_set_string_X509() return 1 if the time value is successfully set and 0 otherwise.

ASN1_TIME_normalize() returns 1 on success, and 0 on error.

ASN1_TIME_check(), ASN1_UTCTIME_check and ASN1_GENERALIZEDTIME_check() return 1 if the structure is syntactically correct and 0 otherwise.

ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return 1 if the time is successfully printed out and 0 if an I/O error occurred an error occurred (I/O error or invalid time format).

ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an error occurred (invalid time format).

ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the passed-in time structure has invalid syntax, for example.

ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if s is before t, 0 if s equals t, or 1 if s is after t. -2 is returned on error.

ASN1_TIME_compare() returns -1 if a is before b, 0 if a equals b, or 1 if a is after b. -2 is returned on error.

ASN1_TIME_to_generalizedtime() returns a pointer to the appropriate time structure on success or NULL if an error occurred.

ASN1_TIME_dup(), ASN1_UTCTIME_dup() and ASN1_GENERALIZEDTIME_dup() return a pointer to a time structure or NULL if an error occurred.

"},{"location":"man3/ASN1_TIME_set/#examples","title":"EXAMPLES","text":"

Set a time structure to one hour after the current time and print it out:

#include <time.h>\n#include <openssl/asn1.h>\n\nASN1_TIME *tm;\ntime_t t;\nBIO *b;\n\nt = time(NULL);\ntm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);\nb = BIO_new_fp(stdout, BIO_NOCLOSE);\nASN1_TIME_print(b, tm);\nASN1_STRING_free(tm);\nBIO_free(b);\n

Determine if one time is later or sooner than the current time:

int day, sec;\n\nif (!ASN1_TIME_diff(&day, &sec, NULL, to))\n    /* Invalid time format */\n\nif (day > 0 || sec > 0)\n    printf(\"Later\\n\");\nelse if (day < 0 || sec < 0)\n    printf(\"Sooner\\n\");\nelse\n    printf(\"Same\\n\");\n
"},{"location":"man3/ASN1_TIME_set/#history","title":"HISTORY","text":"

The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1. The ASN1_TIME_set_string_X509() function was added in OpenSSL 1.1.1. The ASN1_TIME_normalize() function was added in OpenSSL 1.1.1. The ASN1_TIME_cmp_time_t() function was added in OpenSSL 1.1.1. The ASN1_TIME_compare() function was added in OpenSSL 1.1.1.

"},{"location":"man3/ASN1_TIME_set/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_TYPE_get/","title":"ASN1_TYPE_get","text":""},{"location":"man3/ASN1_TYPE_get/#name","title":"NAME","text":"

ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility functions

"},{"location":"man3/ASN1_TYPE_get/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nint ASN1_TYPE_get(const ASN1_TYPE *a);\nvoid ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);\nint ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);\nint ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);\n\nvoid *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);\nASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s,\n                                   ASN1_TYPE **t);\n
"},{"location":"man3/ASN1_TYPE_get/#description","title":"DESCRIPTION","text":"

These functions allow an ASN1_TYPE structure to be manipulated. The ASN1_TYPE structure can contain any ASN.1 type or constructed type such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.

ASN1_TYPE_get() returns the type of a or 0 if it fails.

ASN1_TYPE_set() sets the value of a to type and value. This function uses the pointer value internally so it must not be freed up after the call.

ASN1_TYPE_set1() sets the value of a to type a copy of value.

ASN1_TYPE_cmp() compares ASN.1 types a and b and returns 0 if they are identical and nonzero otherwise.

ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in t using the ASN.1 structure it. If successful it returns a pointer to the ASN.1 structure corresponding to it which must be freed by the caller. If it fails it return NULL.

ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure s corresponding to it into an ASN1_TYPE. If successful the encoded ASN1_TYPE is returned. If t and *t are not NULL the encoded type is written to t overwriting any existing data. If t is not NULL but *t is NULL the returned ASN1_TYPE is written to *t.

"},{"location":"man3/ASN1_TYPE_get/#notes","title":"NOTES","text":"

The type and meaning of the value parameter for ASN1_TYPE_set() and ASN1_TYPE_set1() is determined by the type parameter. If type is V_ASN1_NULL value is ignored. If type is V_ASN1_BOOLEAN then the boolean is set to TRUE if value is not NULL. If type is V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise type is and ASN1_STRING structure. If type corresponds to a primitive type (or a string type) then the contents of the ASN1_STRING contain the content octets of the type. If type corresponds to a constructed type or a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and length octets).

ASN1_TYPE_cmp() may not return zero if two types are equivalent but have different encodings. For example the single content octet of the boolean TRUE value under BER can have any nonzero encoding but ASN1_TYPE_cmp() will only return zero if the values are the same.

If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the return value is nonzero. Technically if both parameters are NULL the two types could be absent OPTIONAL fields and so should match, however, passing NULL values could also indicate a programming error (for example an unparsable type which returns NULL) for types which do not match. So applications should handle the case of two absent values separately.

"},{"location":"man3/ASN1_TYPE_get/#return-values","title":"RETURN VALUES","text":"

ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.

ASN1_TYPE_set() does not return a value.

ASN1_TYPE_set1() returns 1 for success and 0 for failure.

ASN1_TYPE_cmp() returns 0 if the types are identical and nonzero otherwise.

ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or NULL on failure.

ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or NULL on failure.

"},{"location":"man3/ASN1_TYPE_get/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_aux_cb/","title":"ASN1_aux_cb","text":""},{"location":"man3/ASN1_aux_cb/#name","title":"NAME","text":"

ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb - ASN.1 auxiliary data

"},{"location":"man3/ASN1_aux_cb/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1t.h>\n\nstruct ASN1_AUX_st {\n    void *app_data;\n    int flags;\n    int ref_offset;             /* Offset of reference value */\n    int ref_lock;               /* Offset to an CRYPTO_RWLOCK */\n    ASN1_aux_cb *asn1_cb;\n    int enc_offset;             /* Offset of ASN1_ENCODING structure */\n    ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */\n};\ntypedef struct ASN1_AUX_st ASN1_AUX;\n\nstruct ASN1_PRINT_ARG_st {\n    BIO *out;\n    int indent;\n    const ASN1_PCTX *pctx;\n};\ntypedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;\n\nstruct ASN1_STREAM_ARG_st {\n    BIO *out;\n    BIO *ndef_bio;\n    unsigned char **boundary;\n};\ntypedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;\n\ntypedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it,\n                        void *exarg);\ntypedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,\n                              const ASN1_ITEM *it, void *exarg);\n
"},{"location":"man3/ASN1_aux_cb/#description","title":"DESCRIPTION","text":"

ASN.1 data structures can be associated with an ASN1_AUX object to supply additional information about the ASN.1 structure. An ASN1_AUX structure is associated with the structure during the definition of the ASN.1 template. For example an ASN1_AUX structure will be associated by using one of the various ASN.1 template definition macros that supply auxiliary information such as ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(), ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().

An ASN1_AUX structure contains the following information.

During the processing of an ASN1_VALUE object the callbacks set via asn1_cb or asn1_const_cb will be invoked as a result of various events indicated via the operation parameter. The value of *in will be the ASN1_VALUE object being processed based on the template in it. An additional operation specific parameter may be passed in exarg. The currently supported operations are as follows. The callbacks should return a positive value on success or zero on error, unless otherwise noted below.

An ASN1_PRINT_ARG object is used during processing of ASN1_OP_PRINT_PRE and ASN1_OP_PRINT_POST callback operations. It contains the following information.

An ASN1_STREAM_ARG object is used during processing of ASN1_OP_STREAM_PRE, ASN1_OP_STREAM_POST, ASN1_OP_DETACHED_PRE and ASN1_OP_DETACHED_POST callback operations. It contains the following information.

"},{"location":"man3/ASN1_aux_cb/#return-values","title":"RETURN VALUES","text":"

The callbacks return 0 on error and a positive value on success. Some operations require specific positive success values as noted above.

"},{"location":"man3/ASN1_aux_cb/#see-also","title":"SEE ALSO","text":"

ASN1_item_new_ex(3)

"},{"location":"man3/ASN1_aux_cb/#history","title":"HISTORY","text":"

The ASN1_aux_const_cb() callback and the ASN1_OP_GET0_LIBCTX and ASN1_OP_GET0_PROPQ operation types were added in OpenSSL 3.0.

"},{"location":"man3/ASN1_aux_cb/#copyright","title":"COPYRIGHT","text":"

Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_generate_nconf/","title":"ASN1_generate_nconf","text":""},{"location":"man3/ASN1_generate_nconf/#name","title":"NAME","text":"

ASN1_generate_nconf, ASN1_generate_v3 - ASN1 string generation functions

"},{"location":"man3/ASN1_generate_nconf/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);\nASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);\n
"},{"location":"man3/ASN1_generate_nconf/#description","title":"DESCRIPTION","text":"

These functions generate the ASN1 encoding of a string in an ASN1_TYPE structure.

str contains the string to encode. nconf or cnf contains the optional configuration information where additional strings will be read from. nconf will typically come from a config file whereas cnf is obtained from an X509V3_CTX structure, which will typically be used by X509 v3 certificate extension functions. cnf or nconf can be set to NULL if no additional configuration will be used.

"},{"location":"man3/ASN1_generate_nconf/#generation-string-format","title":"GENERATION STRING FORMAT","text":"

The actual data encoded is determined by the string str and the configuration information. The general format of the string is:

That is zero or more comma separated modifiers followed by a type followed by an optional colon and a value. The formats of type, value and modifier are explained below.

"},{"location":"man3/ASN1_generate_nconf/#supported-types","title":"Supported Types","text":"

The supported types are listed below. Case is not significant in the type names. Unless otherwise specified only the ASCII format is permissible.

"},{"location":"man3/ASN1_generate_nconf/#modifiers","title":"Modifiers","text":"

Modifiers affect the following structure, they can be used to add EXPLICIT or IMPLICIT tagging, add wrappers or to change the string format of the final type and value. The supported formats are documented below.

"},{"location":"man3/ASN1_generate_nconf/#return-values","title":"RETURN VALUES","text":"

ASN1_generate_nconf() and ASN1_generate_v3() return the encoded data as an ASN1_TYPE structure or NULL if an error occurred.

The error codes that can be obtained by ERR_get_error(3).

"},{"location":"man3/ASN1_generate_nconf/#examples","title":"EXAMPLES","text":"

A simple IA5String:

IA5STRING:Hello World\n

An IA5String explicitly tagged:

EXPLICIT:0,IA5STRING:Hello World\n

An IA5String explicitly tagged using APPLICATION tagging:

EXPLICIT:0A,IA5STRING:Hello World\n

A BITSTRING with bits 1 and 5 set and all others zero:

FORMAT:BITLIST,BITSTRING:1,5\n

A more complex example using a config file to produce a SEQUENCE consisting of a BOOL an OID and a UTF8String:

asn1 = SEQUENCE:seq_section\n\n[seq_section]\n\nfield1 = BOOLEAN:TRUE\nfield2 = OID:commonName\nfield3 = UTF8:Third field\n

This example produces an RSAPrivateKey structure, this is the key contained in the file client.pem in all OpenSSL distributions (note: the field names such as 'coeff' are ignored and are present just for clarity):

asn1=SEQUENCE:private_key\n[private_key]\nversion=INTEGER:0\n\nn=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\\\nD4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9\n\ne=INTEGER:0x010001\n\nd=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\\\nF810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D\n\np=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\\\nD4BD57\n\nq=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\\\n46EC4F\n\nexp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\\\n9C0A39B9\n\nexp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\\\nE7B2458F\n\ncoeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\\\n628657053A\n

This example is the corresponding public key in a SubjectPublicKeyInfo structure:

# # Start with a SEQUENCE asn1=SEQUENCE:pubkeyinfo

# # pubkeyinfo contains an algorithm identifier and the public key wrapped # # in a BIT STRING [pubkeyinfo] algorithm=SEQUENCE:rsa_alg pubkey=BITWRAP,SEQUENCE:rsapubkey

# # algorithm ID for RSA is just an OID and a NULL [rsa_alg] algorithm=OID:rsaEncryption parameter=NULL

# # Actual public key: modulus and exponent [rsapubkey] n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\\ D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9

e=INTEGER:0x010001\n
"},{"location":"man3/ASN1_generate_nconf/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ASN1_generate_nconf/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_item_d2i_bio/","title":"ASN1_item_d2i_bio","text":""},{"location":"man3/ASN1_item_d2i_bio/#name","title":"NAME","text":"

ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio, ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio, ASN1_item_pack, ASN1_item_unpack_ex, ASN1_item_unpack - decode and encode DER-encoded ASN.1 structures

"},{"location":"man3/ASN1_item_d2i_bio/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in,\n                             long len, const ASN1_ITEM *it,\n                             OSSL_LIB_CTX *libctx, const char *propq);\nASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in,\n                          long len, const ASN1_ITEM *it);\n\nvoid *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x,\n                           OSSL_LIB_CTX *libctx, const char *propq);\nvoid *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);\n\nvoid *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x,\n                          OSSL_LIB_CTX *libctx, const char *propq);\nvoid *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);\n\nBIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val);\n\nASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **oct);\n\nvoid *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it);\n\nvoid *ASN1_item_unpack_ex(const ASN1_STRING *oct, const ASN1_ITEM *it,\n                         OSSL_LIB_CTX *libctx, const char *propq);\n
"},{"location":"man3/ASN1_item_d2i_bio/#description","title":"DESCRIPTION","text":"

ASN1_item_d2i_ex() decodes the contents of the data stored in *in of length len which must be a DER-encoded ASN.1 structure, using the ASN.1 template it. It places the result in *pval unless pval is NULL. If *pval is non-NULL on entry then the ASN1_VALUE present there will be reused. Otherwise a new ASN1_VALUE will be allocated. If any algorithm fetches are required during the process then they will use the OSSL_LIB_CTXprovided in the libctx parameter and the property query string in propq. See \"ALGORITHM FETCHING\" in crypto(7) for more information about algorithm fetching. On exit *in will be updated to point to the next byte in the buffer after the decoded structure.

ASN1_item_d2i() is the same as ASN1_item_d2i_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

ASN1_item_d2i_bio_ex() decodes the contents of its input BIO in, which must be a DER-encoded ASN.1 structure, using the ASN.1 template it and places the result in *pval unless pval is NULL. If in is NULL it returns NULL, else a pointer to the parsed structure. If any algorithm fetches are required during the process then they will use the OSSL_LIB_CTX provided in the libctx parameter and the property query string in propq. See \"ALGORITHM FETCHING\" in crypto(7) for more information about algorithm fetching.

ASN1_item_d2i_bio() is the same as ASN1_item_d2i_bio_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

ASN1_item_d2i_fp_ex() is the same as ASN1_item_d2i_bio_ex() except that a FILE pointer is provided instead of a BIO.

ASN1_item_d2i_fp() is the same as ASN1_item_d2i_fp_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

ASN1_item_i2d_mem_bio() encodes the given ASN.1 value val using the ASN.1 template it and returns the result in a memory BIO.

ASN1_item_pack() encodes the given ASN.1 value in obj using the ASN.1 template it and returns an ASN1_STRING object. If the passed in *oct is not NULL then this is used to store the returned result, otherwise a new ASN1_STRING object is created. If oct is not NULL and *oct is NULL then the returned return is also set into *oct. If there is an error the optional passed in ASN1_STRING will not be freed, but the previous value may be cleared when ASN1_STRING_set0(*oct, NULL, 0) is called internally.

ASN1_item_unpack() uses ASN1_item_d2i() to decode the DER-encoded ASN1_STRING oct using the ASN.1 template it.

ASN1_item_unpack_ex() is similar to ASN1_item_unpack(), but uses ASN1_item_d2i_ex() so that the libctx and propq can be used when doing algorithm fetching.

"},{"location":"man3/ASN1_item_d2i_bio/#return-values","title":"RETURN VALUES","text":"

ASN1_item_d2i_bio(), ASN1_item_unpack_ex() and ASN1_item_unpack() return a pointer to an ASN1_VALUE or NULL on error.

ASN1_item_i2d_mem_bio() returns a pointer to a memory BIO or NULL on error.

ASN1_item_pack() returns a pointer to an ASN1_STRING or NULL on error.

"},{"location":"man3/ASN1_item_d2i_bio/#history","title":"HISTORY","text":"

The functions ASN1_item_d2i_ex(), ASN1_item_d2i_bio_ex(), ASN1_item_d2i_fp_ex() and ASN1_item_i2d_mem_bio() were added in OpenSSL 3.0.

The function ASN1_item_unpack_ex() was added in OpenSSL 3.2.

"},{"location":"man3/ASN1_item_d2i_bio/#copyright","title":"COPYRIGHT","text":"

Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_item_new/","title":"ASN1_item_new","text":""},{"location":"man3/ASN1_item_new/#name","title":"NAME","text":"

ASN1_item_new_ex, ASN1_item_new - create new ASN.1 values

"},{"location":"man3/ASN1_item_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/asn1.h>\n\nASN1_VALUE *ASN1_item_new_ex(const ASN1_ITEM *it, OSSL_LIB_CTX *libctx,\n                             const char *propq);\nASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it);\n
"},{"location":"man3/ASN1_item_new/#description","title":"DESCRIPTION","text":"

ASN1_item_new_ex() creates a new ASN1_VALUE structure based on the ASN1_ITEM template given in the it parameter. If any algorithm fetches are required during the process then they will use the OSSL_LIB_CTX provided in the libctx parameter and the property query string in propq. See \"ALGORITHM FETCHING\" in crypto(7) for more information about algorithm fetching.

ASN1_item_new() is the same as ASN1_item_new_ex() except that the default OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.

"},{"location":"man3/ASN1_item_new/#return-values","title":"RETURN VALUES","text":"

ASN1_item_new_ex() and ASN1_item_new() return a pointer to the newly created ASN1_VALUE or NULL on error.

"},{"location":"man3/ASN1_item_new/#history","title":"HISTORY","text":"

The function ASN1_item_new_ex() was added in OpenSSL 3.0.

"},{"location":"man3/ASN1_item_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASN1_item_sign/","title":"ASN1_item_sign","text":""},{"location":"man3/ASN1_item_sign/#name","title":"NAME","text":"

ASN1_item_sign, ASN1_item_sign_ex, ASN1_item_sign_ctx, ASN1_item_verify, ASN1_item_verify_ex, ASN1_item_verify_ctx - ASN1 sign and verify

"},{"location":"man3/ASN1_item_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/x509.h>\n\nint ASN1_item_sign_ex(const ASN1_ITEM *it, X509_ALGOR *algor1,\n                      X509_ALGOR *algor2, ASN1_BIT_STRING *signature,\n                      const void *data, const ASN1_OCTET_STRING *id,\n                      EVP_PKEY *pkey, const EVP_MD *md, OSSL_LIB_CTX *libctx,\n                      const char *propq);\n\nint ASN1_item_sign(const ASN1_ITEM *it, X509_ALGOR *algor1, X509_ALGOR *algor2,\n                   ASN1_BIT_STRING *signature, const void *data,\n                   EVP_PKEY *pkey, const EVP_MD *md);\n\nint ASN1_item_sign_ctx(const ASN1_ITEM *it, X509_ALGOR *algor1,\n                       X509_ALGOR *algor2, ASN1_BIT_STRING *signature,\n                       const void *data, EVP_MD_CTX *ctx);\n\nint ASN1_item_verify_ex(const ASN1_ITEM *it, const X509_ALGOR *alg,\n                        const ASN1_BIT_STRING *signature, const void *data,\n                        const ASN1_OCTET_STRING *id, EVP_PKEY *pkey,\n                        OSSL_LIB_CTX *libctx, const char *propq);\n\nint ASN1_item_verify(const ASN1_ITEM *it, const X509_ALGOR *alg,\n                     const ASN1_BIT_STRING *signature, const void *data,\n                     EVP_PKEY *pkey);\n\nint ASN1_item_verify_ctx(const ASN1_ITEM *it, const X509_ALGOR *alg,\n                         const ASN1_BIT_STRING *signature, const void *data,\n                         EVP_MD_CTX *ctx);\n
"},{"location":"man3/ASN1_item_sign/#description","title":"DESCRIPTION","text":"

ASN1_item_sign_ex() is used to sign arbitrary ASN1 data using a data object data, the ASN.1 structure it, private key pkey and message digest md. The data that is signed is formed by taking the data object in data and converting it to der format using the ASN.1 structure it. The data that will be signed, and a structure containing the signature may both have a copy of the X509_ALGOR. The ASN1_item_sign_ex() function will write the correct X509_ALGOR to the structs based on the algorithms and parameters that have been set up. If one of algor1 or algor2 points to the X509_ALGOR of the data to be signed, then that X509_ALGOR will first be written before the signature is generated. Examples of valid values that can be used by the ASN.1 structure it are ASN1_ITEM_rptr(X509_CINF), ASN1_ITEM_rptr(X509_REQ_INFO) and ASN1_ITEM_rptr(X509_CRL_INFO). The OSSL_LIB_CTX specified in libctx and the property query string specified in props are used when searching for algorithms in providers. The generated signature is set into signature. The optional parameter id can be NULL, but can be set for special key types. See EVP_PKEY_CTX_set1_id() for further info. The output parameters <algor1> and algor2 are ignored if they are NULL.

ASN1_item_sign() is similar to ASN1_item_sign_ex() but uses default values of NULL for the id, libctx and propq.

ASN1_item_sign_ctx() is similar to ASN1_item_sign() but uses the parameters contained in digest context ctx.

ASN1_item_verify_ex() is used to verify the signature signature of internal data data using the public key pkey and algorithm identifier alg. The data that is verified is formed by taking the data object in data and converting it to der format using the ASN.1 structure it. The OSSL_LIB_CTX specified in libctx and the property query string specified in props are used when searching for algorithms in providers. The optional parameter id can be NULL, but can be set for special key types. See EVP_PKEY_CTX_set1_id() for further info.

ASN1_item_verify() is similar to ASN1_item_verify_ex() but uses default values of NULL for the id, libctx and propq.

ASN1_item_verify_ctx() is similar to ASN1_item_verify() but uses the parameters contained in digest context ctx.

"},{"location":"man3/ASN1_item_sign/#return-values","title":"RETURN VALUES","text":"

All sign functions return the size of the signature in bytes for success and zero for failure.

All verify functions return 1 if the signature is valid and 0 if the signature check fails. If the signature could not be checked at all because it was ill-formed or some other error occurred then -1 is returned.

"},{"location":"man3/ASN1_item_sign/#examples","title":"EXAMPLES","text":"

In the following example a 'MyObject' object is signed using the key contained in an EVP_MD_CTX. The signature is written to MyObject.signature. The object is then output in DER format and then loaded back in and verified.

#include <openssl/x509.h>\n#include <openssl/asn1t.h>\n\n/* An object used to store the ASN1 data fields that will be signed */\ntypedef struct MySignInfoObject_st\n{\n    ASN1_INTEGER *version;\n    X509_ALGOR sig_alg;\n} MySignInfoObject;\n\nDECLARE_ASN1_FUNCTIONS(MySignInfoObject)\n/*\n * A higher level object containing the ASN1 fields, signature alg and\n * output signature.\n */\ntypedef struct MyObject_st\n{\n    MySignInfoObject info;\n    X509_ALGOR sig_alg;\n    ASN1_BIT_STRING *signature;\n} MyObject;\n\nDECLARE_ASN1_FUNCTIONS(MyObject)\n\n/* The ASN1 definition of MySignInfoObject */\nASN1_SEQUENCE_cb(MySignInfoObject, NULL) = {\n    ASN1_SIMPLE(MySignInfoObject, version, ASN1_INTEGER)\n    ASN1_EMBED(MySignInfoObject, sig_alg, X509_ALGOR),\n} ASN1_SEQUENCE_END_cb(MySignInfoObject, MySignInfoObject)\n\n/* new, free, d2i & i2d functions for MySignInfoObject */\nIMPLEMENT_ASN1_FUNCTIONS(MySignInfoObject)\n\n/* The ASN1 definition of MyObject */\nASN1_SEQUENCE_cb(MyObject, NULL) = {\n    ASN1_EMBED(MyObject, info, MySignInfoObject),\n    ASN1_EMBED(MyObject, sig_alg, X509_ALGOR),\n    ASN1_SIMPLE(MyObject, signature, ASN1_BIT_STRING)\n} ASN1_SEQUENCE_END_cb(MyObject, MyObject)\n\n/* new, free, d2i & i2d functions for MyObject */\nIMPLEMENT_ASN1_FUNCTIONS(MyObject)\n\nint test_asn1_item_sign_verify(const char *mdname, EVP_PKEY *pkey, long version)\n{\n   int ret = 0;\n   unsigned char *obj_der = NULL;\n   const unsigned char *p = NULL;\n   MyObject *obj = NULL, *loaded_obj = NULL;\n   const ASN1_ITEM *it = ASN1_ITEM_rptr(MySignInfoObject);\n   EVP_MD_CTX *sctx = NULL, *vctx = NULL;\n   int len;\n\n   /* Create MyObject and set its version */\n   obj = MyObject_new();\n   if (obj == NULL)\n       goto err;\n   if (!ASN1_INTEGER_set(obj->info.version, version))\n       goto err;\n\n   /* Set the key and digest used for signing */\n   sctx = EVP_MD_CTX_new();\n   if (sctx == NULL\n       || !EVP_DigestSignInit_ex(sctx, NULL, mdname, NULL, NULL, pkey))\n       goto err;\n\n   /*\n    * it contains the mapping between ASN.1 data and an object MySignInfoObject\n    * obj->info is the 'MySignInfoObject' object that will be\n    *   converted into DER data and then signed.\n    * obj->signature will contain the output signature.\n    * obj->sig_alg is filled with the private key's signing algorithm id.\n    * obj->info.sig_alg is another copy of the signing algorithm id that sits\n    * within MyObject.\n    */\n   len = ASN1_item_sign_ctx(it, &obj->sig_alg, &obj->info.sig_alg,\n                            obj->signature, &obj->info, sctx);\n   if (len <= 0\n       || X509_ALGOR_cmp(&obj->sig_alg, &obj->info.sig_alg) != 0)\n       goto err;\n\n   /* Output MyObject in der form */\n   len = i2d_MyObject(obj, &obj_der);\n   if (len <= 0)\n       goto err;\n\n   /* Set the key and digest used for verifying */\n   vctx = EVP_MD_CTX_new();\n   if (vctx == NULL\n       || !EVP_DigestVerifyInit_ex(vctx, NULL, mdname, NULL, NULL, pkey))\n       goto err;\n\n   /* Load the der data back into an object */\n   p = obj_der;\n   loaded_obj = d2i_MyObject(NULL, &p, len);\n   if (loaded_obj == NULL)\n       goto err;\n   /* Verify the loaded object */\n   ret = ASN1_item_verify_ctx(it, &loaded_obj->sig_alg, loaded_obj->signature,\n                              &loaded_obj->info, vctx);\n

err: OPENSSL_free(obj_der); MyObject_free(loaded_obj); MyObject_free(obj); EVP_MD_CTX_free(sctx); EVP_MD_CTX_free(vctx); return ret; }

"},{"location":"man3/ASN1_item_sign/#see-also","title":"SEE ALSO","text":"

X509_sign(3), X509_verify(3)

"},{"location":"man3/ASN1_item_sign/#history","title":"HISTORY","text":"

ASN1_item_sign_ex() and ASN1_item_verify_ex() were added in OpenSSL 3.0.

"},{"location":"man3/ASN1_item_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASYNC_WAIT_CTX_new/","title":"ASYNC_WAIT_CTX_new","text":""},{"location":"man3/ASYNC_WAIT_CTX_new/#name","title":"NAME","text":"

ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback, ASYNC_WAIT_CTX_set_status, ASYNC_WAIT_CTX_get_status, ASYNC_callback_fn, ASYNC_STATUS_UNSUPPORTED, ASYNC_STATUS_ERR, ASYNC_STATUS_OK, ASYNC_STATUS_EAGAIN - functions to manage waiting for asynchronous jobs to complete

"},{"location":"man3/ASYNC_WAIT_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/async.h>\n\n#define ASYNC_STATUS_UNSUPPORTED    0\n#define ASYNC_STATUS_ERR            1\n#define ASYNC_STATUS_OK             2\n#define ASYNC_STATUS_EAGAIN         3\ntypedef int (*ASYNC_callback_fn)(void *arg);\nASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);\nvoid ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);\nint ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,\n                               OSSL_ASYNC_FD fd,\n                               void *custom_data,\n                               void (*cleanup)(ASYNC_WAIT_CTX *, const void *,\n                                               OSSL_ASYNC_FD, void *));\nint ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,\n                          OSSL_ASYNC_FD *fd, void **custom_data);\nint ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,\n                               size_t *numfds);\nint ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,\n                                   size_t *numaddfds, OSSL_ASYNC_FD *delfd,\n                                   size_t *numdelfds);\nint ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);\nint ASYNC_WAIT_CTX_set_callback(ASYNC_WAIT_CTX *ctx,\n                                ASYNC_callback_fn callback,\n                                void *callback_arg);\nint ASYNC_WAIT_CTX_get_callback(ASYNC_WAIT_CTX *ctx,\n                                ASYNC_callback_fn *callback,\n                                void **callback_arg);\nint ASYNC_WAIT_CTX_set_status(ASYNC_WAIT_CTX *ctx, int status);\nint ASYNC_WAIT_CTX_get_status(ASYNC_WAIT_CTX *ctx);\n
"},{"location":"man3/ASYNC_WAIT_CTX_new/#description","title":"DESCRIPTION","text":"

For an overview of how asynchronous operations are implemented in OpenSSL see ASYNC_start_job(3). An ASYNC_WAIT_CTX object represents an asynchronous \"session\", i.e. a related set of crypto operations. For example in SSL terms this would have a one-to-one correspondence with an SSL connection.

Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new() function prior to calling ASYNC_start_job() (see ASYNC_start_job(3)). When the job is started it is associated with the ASYNC_WAIT_CTX for the duration of that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one time, but can be reused after an ASYNC_JOB has finished for a subsequent ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed), application code cleans up with ASYNC_WAIT_CTX_free().

ASYNC_WAIT_CTXs can have \"wait\" file descriptors associated with them. Calling ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in the ctx parameter will return the wait file descriptors associated with that job in *fd. The number of file descriptors returned will be stored in *numfds. It is the caller's responsibility to ensure that sufficient memory has been allocated in *fd to receive all the file descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL fd value will return no file descriptors but will still populate *numfds. Therefore, application code is typically expected to call this function twice: once to get the number of fds, and then again when sufficient memory has been allocated. If only one asynchronous engine is being used then normally this call will only ever return one fd. If multiple asynchronous engines are being used then more could be returned.

The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds have changed since the last call time ASYNC_start_job() returned ASYNC_PAUSE (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has been received). The numaddfds and numdelfds parameters will be populated with the number of fds added or deleted respectively. *addfd and *delfd will be populated with the list of added and deleted fds respectively. Similarly to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not NULL then the caller is responsible for ensuring sufficient memory is allocated.

Implementers of async aware code (e.g. engines) are encouraged to return a stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the \"churn\" of regularly changing fds - although no guarantees of this are provided to applications.

Applications can wait for the file descriptor to be ready for \"read\" using a system function call such as select or poll (being ready for \"read\" indicates that the job should be resumed). If no file descriptor is made available then an application will have to periodically \"poll\" the job by attempting to restart it to see if it is ready to continue.

Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job via ASYNC_get_wait_ctx(3) and provide a file descriptor to use for waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an engine immediately prior to calling ASYNC_pause_job() and not by end user code. An existing association with a file descriptor can be obtained using ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of these functions requires a key value which is unique to the async aware code. This could be any unique value but a good candidate might be the ENGINE * for the engine. The custom_data parameter can be any value, and will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a \"cleanup\" routine. This can be NULL but if provided will automatically get called when the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the fd or any other resources. Note: The \"cleanup\" routine does not get called if the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().

An example of typical usage might be an async capable engine. User code would initiate cryptographic operations. The engine would initiate those operations asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by ASYNC_pause_job() to return control to the user code. The user code can then perform other tasks or wait for the job to be ready by calling \"select\" or other similar function on the wait file descriptor. The engine can signal to the user code that the job should be resumed by making the wait file descriptor \"readable\". Once resumed the engine should clear the wake signal on the wait file descriptor.

As well as a file descriptor, user code may also be notified via a callback. The callback and data pointers are stored within the ASYNC_WAIT_CTX along with an additional status field that can be used for the notification of retries from an engine. This additional method can be used when the user thinks that a file descriptor is too costly in terms of CPU cycles or in some context where a file descriptor is not appropriate.

ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The callback will be called to notify user code when an engine completes a cryptography operation. It is a requirement that the callback function is small and nonblocking as it will be run in the context of a polling mechanism or an interrupt.

ASYNC_WAIT_CTX_get_callback() returns the callback set in the ASYNC_WAIT_CTX structure.

ASYNC_WAIT_CTX_set_status() allows an engine to set the current engine status. The possible status values are the following:

ASYNC_WAIT_CTX_get_status() allows user code to obtain the current status value. If the status is any value other than ASYNC_STATUS_OK then the user code should not expect to receive a callback from the engine even if one has been set.

An example of the usage of the callback method might be the following. User code would initiate cryptographic operations, and the engine code would dispatch this operation to hardware, and if the dispatch is successful, then the engine code would call ASYNC_pause_job() to return control to the user code. After that, user code can perform other tasks. When the hardware completes the operation, normally it is detected by a polling function or an interrupt, as the user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously, then the registered callback will be called.

ASYNC_WAIT_CTX_free() frees up a single ASYNC_WAIT_CTX object. If the argument is NULL, nothing is done.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#return-values","title":"RETURN VALUES","text":"

ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or NULL on error.

ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd, ASYNC_WAIT_CTX_set_callback, ASYNC_WAIT_CTX_get_callback and ASYNC_WAIT_CTX_set_status all return 1 on success or 0 on error. ASYNC_WAIT_CTX_get_status() returns the engine status.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#notes","title":"NOTES","text":"

On Windows platforms the <openssl/async.h> header is dependent on some of the types customarily made available by including <windows.h>. The application developer is likely to require control over when the latter is included, commonly as one of the first included headers. Therefore, it is defined as an application developer's responsibility to include <windows.h> prior to <openssl/async.h>.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#see-also","title":"SEE ALSO","text":"

crypto(7), ASYNC_start_job(3)

"},{"location":"man3/ASYNC_WAIT_CTX_new/#history","title":"HISTORY","text":"

ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(), ASYNC_WAIT_CTX_set_wait_fd(), ASYNC_WAIT_CTX_get_fd(), ASYNC_WAIT_CTX_get_all_fds(), ASYNC_WAIT_CTX_get_changed_fds() and ASYNC_WAIT_CTX_clear_fd() were added in OpenSSL 1.1.0.

ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(), ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status() were added in OpenSSL 3.0.

"},{"location":"man3/ASYNC_WAIT_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ASYNC_start_job/","title":"ASYNC_start_job","text":""},{"location":"man3/ASYNC_start_job/#name","title":"NAME","text":"

ASYNC_get_wait_ctx, ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable, ASYNC_stack_alloc_fn, ASYNC_stack_free_fn, ASYNC_set_mem_functions, ASYNC_get_mem_functions - asynchronous job management functions

"},{"location":"man3/ASYNC_start_job/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/async.h>\n\nint ASYNC_init_thread(size_t max_size, size_t init_size);\nvoid ASYNC_cleanup_thread(void);\n\nint ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,\n                    int (*func)(void *), void *args, size_t size);\nint ASYNC_pause_job(void);\n\nASYNC_JOB *ASYNC_get_current_job(void);\nASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);\nvoid ASYNC_block_pause(void);\nvoid ASYNC_unblock_pause(void);\n\nint ASYNC_is_capable(void);\n\ntypedef void *(*ASYNC_stack_alloc_fn)(size_t *num);\ntypedef void (*ASYNC_stack_free_fn)(void *addr);\nint ASYNC_set_mem_functions(ASYNC_stack_alloc_fn alloc_fn,\n                            ASYNC_stack_free_fn free_fn);\nvoid ASYNC_get_mem_functions(ASYNC_stack_alloc_fn *alloc_fn,\n                             ASYNC_stack_free_fn *free_fn);\n
"},{"location":"man3/ASYNC_start_job/#description","title":"DESCRIPTION","text":"

OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This represents code that can be started and executes until some event occurs. At that point the code can be paused and control returns to user code until some subsequent event indicates that the job can be resumed. It's OpenSSL specific implementation of cooperative multitasking.

The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for efficiency reasons, jobs can be created up front and reused many times. They are held in a pool until they are needed, at which point they are removed from the pool, used, and then returned to the pool when the job completes. If the user application is multi-threaded, then ASYNC_init_thread() may be called for each thread that will initiate asynchronous jobs. Before user code exits per-thread resources need to be cleaned up. This will normally occur automatically (see OPENSSL_init_crypto(3)) but may be explicitly initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to ensure this will result in memory leaks.

The max_size argument limits the number of ASYNC_JOBs that will be held in the pool. If max_size is set to 0 then no upper limit is set. When an ASYNC_JOB is needed but there are none available in the pool already then one will be automatically created, as long as the total of ASYNC_JOBs managed by the pool does not exceed max_size. When the pool is first initialised init_size ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is not called before the pool is first used then it will be called automatically with a max_size of 0 (no upper limit) and an init_size of 0 (no ASYNC_JOBs created up front).

An asynchronous job is started by calling the ASYNC_start_job() function. Initially *job should be NULL. ctx should point to an ASYNC_WAIT_CTX object created through the ASYNC_WAIT_CTX_new(3) function. ret should point to a location where the return value of the asynchronous function should be stored on completion of the job. func represents the function that should be started asynchronously. The data pointed to by args and of size size will be copied and then passed as an argument to func when the job starts. ASYNC_start_job will return one of the following values:

At any one time there can be a maximum of one job actively running per thread (you can have many that are paused). ASYNC_get_current_job() can be used to get a pointer to the currently executing ASYNC_JOB. If no job is currently executing then this will return NULL.

If executing within the context of a job (i.e. having been called directly or indirectly by the function \"func\" passed as an argument to ASYNC_start_job()) then ASYNC_pause_job() will immediately return control to the calling application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the *job parameter will resume execution from the ASYNC_pause_job() call. If ASYNC_pause_job() is called whilst not within the context of a job then no action is taken and ASYNC_pause_job() returns immediately.

ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX for the job (see ASYNC_WAIT_CTX_new(3)). ASYNC_WAIT_CTXs contain two different ways to notify applications that a job is ready to be resumed. One is a \"wait\" file descriptor, and the other is a \"callback\" mechanism.

The \"wait\" file descriptor associated with ASYNC_WAIT_CTX is used for applications to wait for the file descriptor to be ready for \"read\" using a system function call such as select(2) or poll(2) (being ready for \"read\" indicates that the job should be resumed). If no file descriptor is made available then an application will have to periodically \"poll\" the job by attempting to restart it to see if it is ready to continue.

ASYNC_WAIT_CTXs also have a \"callback\" mechanism to notify applications. The callback is set by an application, and it will be automatically called when an engine completes a cryptography operation, so that the application can resume the paused work flow without polling. An engine could be written to look whether the callback has been set. If it has then it would use the callback mechanism in preference to the file descriptor notifications. If a callback is not set then the engine may use file descriptor based notifications. Please note that not all engines may support the callback mechanism, so the callback may not be used even if it has been set. See ASYNC_WAIT_CTX_new() for more details.

The ASYNC_block_pause() function will prevent the currently active job from pausing. The block will remain in place until a subsequent call to ASYNC_unblock_pause(). These functions can be nested, e.g. if you call ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in order to re-enable pausing. If these functions are called while there is no currently active job then they have no effect. This functionality can be useful to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an application acquires a lock. It then calls some cryptographic function which invokes ASYNC_pause_job(). This returns control back to the code that created the ASYNC_JOB. If that code then attempts to acquire the same lock before resuming the original job then a deadlock can occur. By calling ASYNC_block_pause() immediately after acquiring the lock and ASYNC_unblock_pause() immediately before releasing it then this situation cannot occur.

Some platforms cannot support async operations. The ASYNC_is_capable() function can be used to detect whether the current platform is async capable or not.

Custom memory allocation functions are supported for the POSIX platform. Custom memory allocation functions allow alternative methods of allocating stack memory such as mmap, or using stack memory from the current thread. Using an ASYNC_stack_alloc_fn callback also allows manipulation of the stack size, which defaults to 32k. The stack size can be altered by allocating a stack of a size different to the requested size, and passing back the new stack size in the callback's *num parameter.

"},{"location":"man3/ASYNC_start_job/#return-values","title":"RETURN VALUES","text":"

ASYNC_init_thread returns 1 on success or 0 otherwise.

ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or ASYNC_FINISH as described above.

ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when not within the context of an ASYNC_JOB then this is counted as success so 1 is returned.

ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or NULL if not within the context of a job.

ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.

ASYNC_is_capable() returns 1 if the current platform is async capable or 0 otherwise.

ASYNC_set_mem_functions returns 1 if custom stack allocators are supported by the current platform and no allocations have already occurred or 0 otherwise.

"},{"location":"man3/ASYNC_start_job/#notes","title":"NOTES","text":"

On Windows platforms the <openssl/async.h> header is dependent on some of the types customarily made available by including <windows.h>. The application developer is likely to require control over when the latter is included, commonly as one of the first included headers. Therefore, it is defined as an application developer's responsibility to include <windows.h> prior to <openssl/async.h>.

"},{"location":"man3/ASYNC_start_job/#examples","title":"EXAMPLES","text":"

The following example demonstrates how to use most of the core async APIs:

#ifdef _WIN32\n

# # include #endif #include #include #include #include 

int unique = 0;\n\nvoid cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)\n{\n    OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;\n\n    close(r);\n    close(*w);\n    OPENSSL_free(w);\n}\n\nint jobfunc(void *arg)\n{\n    ASYNC_JOB *currjob;\n    unsigned char *msg;\n    int pipefds[2] = {0, 0};\n    OSSL_ASYNC_FD *wptr;\n    char buf = 'X';\n\n    currjob = ASYNC_get_current_job();\n    if (currjob != NULL) {\n        printf(\"Executing within a job\\n\");\n    } else {\n        printf(\"Not executing within a job - should not happen\\n\");\n        return 0;\n    }\n\n    msg = (unsigned char *)arg;\n    printf(\"Passed in message is: %s\\n\", msg);\n\n    /*\n     * Create a way to inform the calling thread when this job is ready\n     * to resume, in this example we're using file descriptors.\n     * For offloading the task to an asynchronous ENGINE it's not necessary,\n     * the ENGINE should handle that internally.\n     */\n\n    if (pipe(pipefds) != 0) {\n        printf(\"Failed to create pipe\\n\");\n        return 0;\n    }\n    wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));\n    if (wptr == NULL) {\n        printf(\"Failed to malloc\\n\");\n        return 0;\n    }\n    *wptr = pipefds[1];\n    ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,\n                               pipefds[0], wptr, cleanup);\n\n    /*\n     * Normally some external event (like a network read being ready,\n     * disk access being finished, or some hardware offload operation\n     * completing) would cause this to happen at some\n     * later point - but we do it here for demo purposes, i.e.\n     * immediately signalling that the job is ready to be woken up after\n     * we return to main via ASYNC_pause_job().\n     */\n    write(pipefds[1], &buf, 1);\n\n    /*\n     * Return control back to main just before calling a blocking\n     * method. The main thread will wait until pipefds[0] is ready\n     * for reading before returning control to this thread.\n     */\n    ASYNC_pause_job();\n\n    /* Perform the blocking call (it won't block with this example code) */\n    read(pipefds[0], &buf, 1);\n\n    printf (\"Resumed the job after a pause\\n\");\n\n    return 1;\n}\n\nint main(void)\n{\n    ASYNC_JOB *job = NULL;\n    ASYNC_WAIT_CTX *ctx = NULL;\n    int ret;\n    OSSL_ASYNC_FD waitfd;\n    fd_set waitfdset;\n    size_t numfds;\n    unsigned char msg[13] = \"Hello world!\";\n\n    printf(\"Starting...\\n\");\n\n    ctx = ASYNC_WAIT_CTX_new();\n    if (ctx == NULL) {\n        printf(\"Failed to create ASYNC_WAIT_CTX\\n\");\n        abort();\n    }\n\n    for (;;) {\n        switch (ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {\n        case ASYNC_ERR:\n        case ASYNC_NO_JOBS:\n            printf(\"An error occurred\\n\");\n            goto end;\n        case ASYNC_PAUSE:\n            printf(\"Job was paused\\n\");\n            break;\n        case ASYNC_FINISH:\n            printf(\"Job finished with return value %d\\n\", ret);\n            goto end;\n        }\n\n        /* Get the file descriptor we can use to wait for the job\n         * to be ready to be woken up\n         */\n        printf(\"Waiting for the job to be woken up\\n\");\n\n        if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)\n                || numfds > 1) {\n            printf(\"Unexpected number of fds\\n\");\n            abort();\n        }\n        ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);\n        FD_ZERO(&waitfdset);\n        FD_SET(waitfd, &waitfdset);\n\n        /* Wait for the job to be ready for wakeup */\n        select(waitfd + 1, &waitfdset, NULL, NULL, NULL);\n    }\n\nend:\n    ASYNC_WAIT_CTX_free(ctx);\n    printf(\"Finishing\\n\");\n\n    return 0;\n}\n

The expected output from executing the above example program is:

Starting...\nExecuting within a job\nPassed in message is: Hello world!\nJob was paused\nWaiting for the job to be woken up\nResumed the job after a pause\nJob finished with return value 1\nFinishing\n
"},{"location":"man3/ASYNC_start_job/#see-also","title":"SEE ALSO","text":"

crypto(7), ERR_print_errors(3)

"},{"location":"man3/ASYNC_start_job/#history","title":"HISTORY","text":"

ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(), ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first added in OpenSSL 1.1.0.

"},{"location":"man3/ASYNC_start_job/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BF_encrypt/","title":"BF_encrypt","text":""},{"location":"man3/BF_encrypt/#name","title":"NAME","text":"

BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption

"},{"location":"man3/BF_encrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/blowfish.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void BF_set_key(BF_KEY *key, int len, const unsigned char *data);\n\nvoid BF_ecb_encrypt(const unsigned char *in, unsigned char *out,\n                    BF_KEY *key, int enc);\nvoid BF_cbc_encrypt(const unsigned char *in, unsigned char *out,\n                    long length, BF_KEY *schedule,\n                    unsigned char *ivec, int enc);\nvoid BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                      long length, BF_KEY *schedule,\n                      unsigned char *ivec, int *num, int enc);\nvoid BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                      long length, BF_KEY *schedule,\n                      unsigned char *ivec, int *num);\nconst char *BF_options(void);\n\nvoid BF_encrypt(BF_LONG *data, const BF_KEY *key);\nvoid BF_decrypt(BF_LONG *data, const BF_KEY *key);\n
"},{"location":"man3/BF_encrypt/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3) and EVP_EncryptFinal_ex(3) or the equivalently named decrypt functions.

This library implements the Blowfish cipher, which was invented and described by Counterpane (see http://www.counterpane.com/blowfish.html ).

Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. It uses a variable size key, but typically, 128 bit (16 byte) keys are considered good for strong encryption. Blowfish can be used in the same modes as DES (see des_modes(7)). Blowfish is currently one of the faster block ciphers. It is quite a bit faster than DES, and much faster than IDEA or RC2.

Blowfish consists of a key setup phase and the actual encryption or decryption phase.

BF_set_key() sets up the BF_KEY key using the len bytes long key at data.

BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. It encrypts or decrypts the first 64 bits of in using the key key, putting the result in out. enc decides if encryption (BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. The vector pointed at by in and out must be 64 bits in length, no less. If they are larger, everything after the first 64 bits is ignored.

The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() all operate on variable length data. They all take an initialization vector ivec which needs to be passed along into the next call of the same function for the same message. ivec may be initialized with anything, but the recipient needs to know what it was initialized with, or it won't be able to decrypt. Some programs and protocols simplify this, like SSH, where ivec is simply initialized to zero. BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt a variable number of bytes (the amount does not have to be an exact multiple of 8). The purpose of the latter two is to simulate stream ciphers, and therefore, they need the parameter num, which is a pointer to an integer where the current offset in ivec is stored between calls. This integer must be initialized to zero when ivec is initialized.

BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It encrypts or decrypts the 64 bits chunks of in using the key schedule, putting the result in out. enc decides if encryption (BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. ivec must point at an 8 byte long initialization vector.

BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. It encrypts or decrypts the bytes in in using the key schedule, putting the result in out. enc decides if encryption (BF_ENCRYPT) or decryption (BF_DECRYPT) shall be performed. ivec must point at an 8 byte long initialization vector. num must point at an integer which must be initially zero.

BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. It uses the same parameters as BF_cfb64_encrypt(), which must be initialized the same way.

BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish encryption. They encrypt/decrypt the first 64 bits of the vector pointed by data, using the key key. These functions should not be used unless you implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt(). If you still want to use these functions, you should be aware that they take each 32-bit chunk in host-byte order, which is little-endian on little-endian platforms and big-endian on big-endian ones.

"},{"location":"man3/BF_encrypt/#return-values","title":"RETURN VALUES","text":"

None of the functions presented here return any value.

"},{"location":"man3/BF_encrypt/#note","title":"NOTE","text":"

Applications should use the higher level functions EVP_EncryptInit(3) etc. instead of calling these functions directly.

"},{"location":"man3/BF_encrypt/#see-also","title":"SEE ALSO","text":"

EVP_EncryptInit(3), des_modes(7)

"},{"location":"man3/BF_encrypt/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/BF_encrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_ADDR/","title":"BIO_ADDR","text":""},{"location":"man3/BIO_ADDR/#name","title":"NAME","text":"

BIO_ADDR, BIO_ADDR_new, BIO_ADDR_copy, BIO_ADDR_dup, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, BIO_ADDR_hostname_string, BIO_ADDR_service_string, BIO_ADDR_path_string - BIO_ADDR routines

"},{"location":"man3/BIO_ADDR/#synopsis","title":"SYNOPSIS","text":"
#include <sys/types.h>\n#include <openssl/bio.h>\n\ntypedef union bio_addr_st BIO_ADDR;\n\nBIO_ADDR *BIO_ADDR_new(void);\nint BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);\nBIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);\nvoid BIO_ADDR_free(BIO_ADDR *ap);\nvoid BIO_ADDR_clear(BIO_ADDR *ap);\nint BIO_ADDR_rawmake(BIO_ADDR *ap, int family,\n                     const void *where, size_t wherelen, unsigned short port);\nint BIO_ADDR_family(const BIO_ADDR *ap);\nint BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);\nunsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);\nchar *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);\nchar *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);\nchar *BIO_ADDR_path_string(const BIO_ADDR *ap);\n
"},{"location":"man3/BIO_ADDR/#description","title":"DESCRIPTION","text":"

The BIO_ADDR type is a wrapper around all types of socket addresses that OpenSSL deals with, currently transparently supporting AF_INET, AF_INET6 and AF_UNIX according to what's available on the platform at hand.

BIO_ADDR_new() creates a new unfilled BIO_ADDR, to be used with routines that will fill it with information, such as BIO_accept_ex().

BIO_ADDR_copy() copies the contents of src into dst. Neither src or dst can be NULL.

BIO_ADDR_dup() creates a new BIO_ADDR, with a copy of the address data in ap.

BIO_ADDR_free() frees a BIO_ADDR created with BIO_ADDR_new() or BIO_ADDR_dup(). If the argument is NULL, nothing is done.

BIO_ADDR_clear() clears any data held within the provided BIO_ADDR and sets it back to an uninitialised state.

BIO_ADDR_rawmake() takes a protocol family, a byte array of size wherelen with an address in network byte order pointed at by where and a port number in network byte order in port (except for the AF_UNIX protocol family, where port is meaningless and therefore ignored) and populates the given BIO_ADDR with them. In case this creates a AF_UNIX BIO_ADDR, wherelen is expected to be the length of the path string (not including the terminating NUL, such as the result of a call to strlen()). Read on about the addresses in \"RAW ADDRESSES\" below.

BIO_ADDR_family() returns the protocol family of the given BIO_ADDR. The possible non-error results are one of the constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the BIO_ADDR has not been initialised.

BIO_ADDR_rawaddress() will write the raw address of the given BIO_ADDR in the area pointed at by p if p is non-NULL, and will set *l to be the amount of bytes the raw address takes up if l is non-NULL. A technique to only find out the size of the address is a call with p set to NULL. The raw address will be in network byte order, most significant byte first. In case this is a AF_UNIX BIO_ADDR, l gets the length of the path string (not including the terminating NUL, such as the result of a call to strlen()). Read on about the addresses in \"RAW ADDRESSES\" below.

BIO_ADDR_rawport() returns the raw port of the given BIO_ADDR. The raw port will be in network byte order.

BIO_ADDR_hostname_string() returns a character string with the hostname of the given BIO_ADDR. If numeric is 1, the string will contain the numerical form of the address. This only works for BIO_ADDR of the protocol families AF_INET and AF_INET6. The returned string has been allocated on the heap and must be freed with OPENSSL_free().

BIO_ADDR_service_string() returns a character string with the service name of the port of the given BIO_ADDR. If numeric is 1, the string will contain the port number. This only works for BIO_ADDR of the protocol families AF_INET and AF_INET6. The returned string has been allocated on the heap and must be freed with OPENSSL_free().

BIO_ADDR_path_string() returns a character string with the path of the given BIO_ADDR. This only works for BIO_ADDR of the protocol family AF_UNIX. The returned string has been allocated on the heap and must be freed with OPENSSL_free().

"},{"location":"man3/BIO_ADDR/#raw-addresses","title":"RAW ADDRESSES","text":"

Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a network byte order address of a specific site. Internally, those are treated as a pointer to struct in_addr (for AF_INET), struct in6_addr (for AF_INET6) or char * (for AF_UNIX), all depending on the protocol family the address is for.

"},{"location":"man3/BIO_ADDR/#return-values","title":"RETURN VALUES","text":"

The string producing functions BIO_ADDR_hostname_string(), BIO_ADDR_service_string() and BIO_ADDR_path_string() will return NULL on error and leave an error indication on the OpenSSL error stack.

BIO_ADDR_copy() returns 1 on success or 0 on error.

All other functions described here return 0 or NULL when the information they should return isn't available.

"},{"location":"man3/BIO_ADDR/#see-also","title":"SEE ALSO","text":"

BIO_connect(3), BIO_s_connect(3)

"},{"location":"man3/BIO_ADDR/#history","title":"HISTORY","text":"

BIO_ADDR_copy() and BIO_ADDR_dup() were added in OpenSSL 3.2.

"},{"location":"man3/BIO_ADDR/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_ADDRINFO/","title":"BIO_ADDRINFO","text":""},{"location":"man3/BIO_ADDRINFO/#name","title":"NAME","text":"

BIO_lookup_type, BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, BIO_ADDRINFO_address, BIO_lookup_ex, BIO_lookup - BIO_ADDRINFO type and routines

"},{"location":"man3/BIO_ADDRINFO/#synopsis","title":"SYNOPSIS","text":"
#include <sys/types.h>\n#include <openssl/bio.h>\n\ntypedef union bio_addrinfo_st BIO_ADDRINFO;\n\nenum BIO_lookup_type {\n    BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER\n};\n\nint BIO_lookup_ex(const char *host, const char *service, int lookup_type,\n                  int family, int socktype, int protocol, BIO_ADDRINFO **res);\nint BIO_lookup(const char *host, const char *service,\n               enum BIO_lookup_type lookup_type,\n               int family, int socktype, BIO_ADDRINFO **res);\n\nconst BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);\nint BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);\nint BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);\nint BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);\nconst BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);\nvoid BIO_ADDRINFO_free(BIO_ADDRINFO *bai);\n
"},{"location":"man3/BIO_ADDRINFO/#description","title":"DESCRIPTION","text":"

The BIO_ADDRINFO type is a wrapper for address information types provided on your platform.

BIO_ADDRINFO normally forms a chain of several that can be picked at one by one.

BIO_lookup_ex() looks up a specified host and service, and uses lookup_type to determine what the default address should be if host is NULL. family, socktype and protocol are used to determine what protocol family, socket type and protocol should be used for the lookup. family can be any of AF_INET, AF_INET6, AF_UNIX and AF_UNSPEC. socktype can be SOCK_STREAM, SOCK_DGRAM or 0. Specifying 0 indicates that any type can be used. protocol specifies a protocol such as IPPROTO_TCP, IPPROTO_UDP or IPPORTO_SCTP. If set to 0 than any protocol can be used. res points at a pointer to hold the start of a BIO_ADDRINFO chain.

For the family AF_UNIX, BIO_lookup_ex() will ignore the service parameter and expects the host parameter to hold the path to the socket file.

BIO_lookup() does the same as BIO_lookup_ex() but does not provide the ability to select based on the protocol (any protocol may be returned).

BIO_ADDRINFO_family() returns the family of the given BIO_ADDRINFO. The result will be one of the constants AF_INET, AF_INET6 and AF_UNIX.

BIO_ADDRINFO_socktype() returns the socket type of the given BIO_ADDRINFO. The result will be one of the constants SOCK_STREAM and SOCK_DGRAM.

BIO_ADDRINFO_protocol() returns the protocol id of the given BIO_ADDRINFO. The result will be one of the constants IPPROTO_TCP and IPPROTO_UDP.

BIO_ADDRINFO_address() returns the underlying BIO_ADDR of the given BIO_ADDRINFO.

BIO_ADDRINFO_next() returns the next BIO_ADDRINFO in the chain from the given one.

BIO_ADDRINFO_free() frees the chain of BIO_ADDRINFO starting with the given one. If the argument is NULL, nothing is done.

"},{"location":"man3/BIO_ADDRINFO/#return-values","title":"RETURN VALUES","text":"

BIO_lookup_ex() and BIO_lookup() return 1 on success and 0 when an error occurred, and will leave an error indication on the OpenSSL error stack in that case.

All other functions described here return 0 or NULL when the information they should return isn't available.

"},{"location":"man3/BIO_ADDRINFO/#notes","title":"NOTES","text":"

The BIO_lookup_ex() implementation uses the platform provided getaddrinfo() function. On Linux it is known that specifying 0 for the protocol will not return any SCTP based addresses when calling getaddrinfo(). Therefore, if an SCTP address is required then the protocol parameter to BIO_lookup_ex() should be explicitly set to IPPROTO_SCTP. The same may be true on other platforms.

"},{"location":"man3/BIO_ADDRINFO/#history","title":"HISTORY","text":"

The BIO_lookup_ex() function was added in OpenSSL 1.1.1.

"},{"location":"man3/BIO_ADDRINFO/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_connect/","title":"BIO_connect","text":""},{"location":"man3/BIO_connect/#name","title":"NAME","text":"

BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO socket communication setup routines

"},{"location":"man3/BIO_connect/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_socket(int domain, int socktype, int protocol, int options);\nint BIO_bind(int sock, const BIO_ADDR *addr, int options);\nint BIO_connect(int sock, const BIO_ADDR *addr, int options);\nint BIO_listen(int sock, const BIO_ADDR *addr, int options);\nint BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);\nint BIO_closesocket(int sock);\n
"},{"location":"man3/BIO_connect/#description","title":"DESCRIPTION","text":"

BIO_socket() creates a socket in the domain domain, of type socktype and protocol. Socket options are currently unused, but is present for future use.

BIO_bind() binds the source address and service to a socket and may be useful before calling BIO_connect(). The options may include BIO_SOCK_REUSEADDR, which is described in \"FLAGS\" below.

BIO_connect() connects sock to the address and service given by addr. Connection options may be zero or any combination of BIO_SOCK_KEEPALIVE, BIO_SOCK_NONBLOCK and BIO_SOCK_NODELAY. The flags are described in \"FLAGS\" below.

BIO_listen() has sock start listening on the address and service given by addr. Connection options may be zero or any combination of BIO_SOCK_KEEPALIVE, BIO_SOCK_NONBLOCK, BIO_SOCK_NODELAY, BIO_SOCK_REUSEADDR and BIO_SOCK_V6_ONLY. The flags are described in \"FLAGS\" below.

BIO_accept_ex() waits for an incoming connections on the given socket accept_sock. When it gets a connection, the address and port of the peer gets stored in peer if that one is non-NULL. Accept options may be zero or BIO_SOCK_NONBLOCK, and is applied on the accepted socket. The flags are described in \"FLAGS\" below.

BIO_closesocket() closes sock.

"},{"location":"man3/BIO_connect/#flags","title":"FLAGS","text":"

These flags are bit flags, so they are to be combined with the | operator, for example:

BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);\n
"},{"location":"man3/BIO_connect/#return-values","title":"RETURN VALUES","text":"

BIO_socket() returns the socket number on success or INVALID_SOCKET (-1) on error. When an error has occurred, the OpenSSL error stack will hold the error data and errno has the system error.

BIO_bind(), BIO_connect() and BIO_listen() return 1 on success or 0 on error. When an error has occurred, the OpenSSL error stack will hold the error data and errno has the system error.

BIO_accept_ex() returns the accepted socket on success or INVALID_SOCKET (-1) on error. When an error has occurred, the OpenSSL error stack will hold the error data and errno has the system error.

"},{"location":"man3/BIO_connect/#see-also","title":"SEE ALSO","text":"

BIO_ADDR(3)

"},{"location":"man3/BIO_connect/#history","title":"HISTORY","text":"

BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(), BIO_get_accept_socket() and BIO_accept() were deprecated in OpenSSL 1.1.0. Use the functions described above instead.

"},{"location":"man3/BIO_connect/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_ctrl/","title":"BIO_ctrl","text":""},{"location":"man3/BIO_ctrl/#name","title":"NAME","text":"

BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send, BIO_get_ktls_recv, BIO_set_conn_mode, BIO_get_conn_mode, BIO_set_tfo - BIO control operations

"},{"location":"man3/BIO_ctrl/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef int BIO_info_cb(BIO *b, int state, int res);\n\nlong BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);\nlong BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb);\nvoid *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);\nlong BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);\n\nint BIO_reset(BIO *b);\nint BIO_seek(BIO *b, int ofs);\nint BIO_tell(BIO *b);\nint BIO_flush(BIO *b);\nint BIO_eof(BIO *b);\nint BIO_set_close(BIO *b, long flag);\nint BIO_get_close(BIO *b);\nint BIO_pending(BIO *b);\nint BIO_wpending(BIO *b);\nsize_t BIO_ctrl_pending(BIO *b);\nsize_t BIO_ctrl_wpending(BIO *b);\n\nint BIO_get_info_callback(BIO *b, BIO_info_cb **cbp);\nint BIO_set_info_callback(BIO *b, BIO_info_cb *cb);\n\nint BIO_get_ktls_send(BIO *b);\nint BIO_get_ktls_recv(BIO *b);\n\nint BIO_set_conn_mode(BIO *b, int mode);\nint BIO_get_conn_mode(BIO *b);\n\nint BIO_set_tfo(BIO *b, int onoff);\n
"},{"location":"man3/BIO_ctrl/#description","title":"DESCRIPTION","text":"

BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() are BIO \"control\" operations taking arguments of various types. These functions are not normally called directly, various macros are used instead. The standard macros are described below, macros specific to a particular type of BIO are described in the specific BIOs manual page as well as any special features of the standard calls.

BIO_reset() typically resets a BIO to some initial state, in the case of file related BIOs for example it rewinds the file pointer to the start of the file.

BIO_seek() resets a file related BIO's (that is file descriptor and FILE BIOs) file position pointer to ofs bytes from start of file.

BIO_tell() returns the current file position of a file related BIO.

BIO_flush() normally writes out any internally buffered data, in some cases it is used to signal EOF and that no more data will be written.

BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of \"EOF\" varies according to the BIO type.

BIO_set_close() sets the BIO b close flag to flag. flag can take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used in a source/sink BIO to indicate that the underlying I/O stream should be closed when the BIO is freed.

BIO_get_close() returns the BIOs close flag.

BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() return the number of pending characters in the BIOs read and write buffers. Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() return a size_t type and are functions, BIO_pending() and BIO_wpending() are macros which call BIO_ctrl().

BIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for sending. Otherwise, it returns zero. BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for receiving. Otherwise, it returns zero.

BIO_get_conn_mode() returns the BIO connection mode. BIO_set_conn_mode() sets the BIO connection mode.

BIO_set_tfo() disables TCP Fast Open when onoff is 0, and enables TCP Fast Open when onoff is nonzero. Setting the value to 1 is equivalent to setting BIO_SOCK_TFO in BIO_set_conn_mode().

"},{"location":"man3/BIO_ctrl/#return-values","title":"RETURN VALUES","text":"

BIO_reset() normally returns 1 for success and <=0 for failure. File BIOs are an exception, they return 0 for success and -1 for failure.

BIO_seek() and BIO_tell() both return the current file position on success and -1 for failure, except file BIOs which for BIO_seek() always return 0 for success and -1 for failure.

BIO_flush() returns 1 for success and <=0 for failure.

BIO_eof() returns 1 if EOF has been reached, 0 if not, or negative values for failure.

BIO_set_close() returns 1 on success or <=0 for failure.

BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. It also returns other negative values if an error occurs.

BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() return the amount of pending data. BIO_pending() and BIO_wpending() return negative value or 0 on error. BIO_ctrl_pending() and BIO_ctrl_wpending() return 0 on error.

BIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for sending. Otherwise, it returns zero. BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for receiving. Otherwise, it returns zero.

BIO_set_conn_mode() returns 1 for success and 0 for failure. BIO_get_conn_mode() returns the current connection mode. Which may contain the bitwise-or of the following flags:

BIO_SOCK_REUSEADDR\nBIO_SOCK_V6_ONLY\nBIO_SOCK_KEEPALIVE\nBIO_SOCK_NONBLOCK\nBIO_SOCK_NODELAY\nBIO_SOCK_TFO\n

BIO_set_tfo() returns 1 for success, and 0 for failure.

"},{"location":"man3/BIO_ctrl/#notes","title":"NOTES","text":"

BIO_flush(), because it can write data may return 0 or -1 indicating that the call should be retried later in a similar manner to BIO_write_ex(). The BIO_should_retry() call should be used and appropriate action taken is the call fails.

The return values of BIO_pending() and BIO_wpending() may not reliably determine the amount of pending data in all cases. For example in the case of a file BIO some data may be available in the FILE structures internal buffers but it is not possible to determine this in a portably way. For other types of BIO they may not be supported.

Filter BIOs if they do not internally handle a particular BIO_ctrl() operation usually pass the operation to the next BIO in the chain. This often means there is no need to locate the required BIO for a particular operation, it can be called on a chain and it will be automatically passed to the relevant BIO. However, this can cause unexpected results: for example no current filter BIOs implement BIO_seek(), but this may still succeed if the chain ends in a FILE or file descriptor BIO.

Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() operation.

"},{"location":"man3/BIO_ctrl/#bugs","title":"BUGS","text":"

Some of the return values are ambiguous and care should be taken. In particular a return value of 0 can be returned if an operation is not supported, if an error occurred, if EOF has not been reached and in the case of BIO_seek() on a file BIO for a successful operation.

In older versions of OpenSSL the BIO_ctrl_pending() and BIO_ctrl_wpending() could return values greater than INT_MAX on error.

"},{"location":"man3/BIO_ctrl/#history","title":"HISTORY","text":"

The BIO_get_ktls_send() and BIO_get_ktls_recv() macros were added in OpenSSL 3.0. They were modified to never return -1 in OpenSSL 3.0.4.

The BIO_get_conn_mode(), BIO_set_conn_mode() and BIO_set_tfo() functions were added in OpenSSL 3.2.

"},{"location":"man3/BIO_ctrl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_base64/","title":"BIO_f_base64","text":""},{"location":"man3/BIO_f_base64/#name","title":"NAME","text":"

BIO_f_base64 - base64 BIO filter

"},{"location":"man3/BIO_f_base64/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/evp.h>\n\nconst BIO_METHOD *BIO_f_base64(void);\n
"},{"location":"man3/BIO_f_base64/#description","title":"DESCRIPTION","text":"

BIO_f_base64() returns the base64 BIO method. This is a filter BIO that base64 encodes any data written through it and decodes any data read through it.

Base64 BIOs do not support BIO_gets() or BIO_puts().

For writing, by default output is divided to lines of length 64 characters and there is a newline at the end of output. This behavior can be changed with BIO_FLAGS_BASE64_NO_NL flag.

For reading, first line should be at most 1024 bytes long including newline unless the flag BIO_FLAGS_BASE64_NO_NL is set. Further input lines can be of any length (i.e., newlines may appear anywhere in the input) and a newline at the end of input is not needed.

BIO_flush() on a base64 BIO that is being written through is used to signal that no more data is to be encoded: this is used to flush the final block through the BIO.

The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags(). For writing, it causes all data to be written on one line without newline at the end. For reading, it removes all expectations on newlines in the input data.

"},{"location":"man3/BIO_f_base64/#notes","title":"NOTES","text":"

Because of the format of base64 encoding the end of the encoded block cannot always be reliably determined.

"},{"location":"man3/BIO_f_base64/#return-values","title":"RETURN VALUES","text":"

BIO_f_base64() returns the base64 BIO method.

"},{"location":"man3/BIO_f_base64/#examples","title":"EXAMPLES","text":"

Base64 encode the string \"Hello World\\n\" and write the result to standard output:

BIO *bio, *b64;\nchar message[] = \"Hello World \\n\";\n\nb64 = BIO_new(BIO_f_base64());\nbio = BIO_new_fp(stdout, BIO_NOCLOSE);\nBIO_push(b64, bio);\nBIO_write(b64, message, strlen(message));\nBIO_flush(b64);\n\nBIO_free_all(b64);\n

Read Base64 encoded data from standard input and write the decoded data to standard output:

BIO *bio, *b64, *bio_out;\nchar inbuf[512];\nint inlen;\n\nb64 = BIO_new(BIO_f_base64());\nbio = BIO_new_fp(stdin, BIO_NOCLOSE);\nbio_out = BIO_new_fp(stdout, BIO_NOCLOSE);\nBIO_push(b64, bio);\nwhile ((inlen = BIO_read(b64, inbuf, 512)) > 0)\n    BIO_write(bio_out, inbuf, inlen);\n\nBIO_flush(bio_out);\nBIO_free_all(b64);\n
"},{"location":"man3/BIO_f_base64/#bugs","title":"BUGS","text":"

On decoding, if the flag BIO_FLAGS_BASE64_NO_NL is not set and the first 1024 bytes of input do not include a newline character the first two lines of input are ignored.

The ambiguity of EOF in base64 encoded data can cause additional data following the base64 encoded block to be misinterpreted.

There should be some way of specifying a test that the BIO can perform to reliably determine EOF (for example a MIME boundary).

"},{"location":"man3/BIO_f_base64/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_buffer/","title":"BIO_f_buffer","text":""},{"location":"man3/BIO_f_buffer/#name","title":"NAME","text":"

BIO_get_buffer_num_lines, BIO_set_read_buffer_size, BIO_set_write_buffer_size, BIO_set_buffer_size, BIO_set_buffer_read_data, BIO_f_buffer - buffering BIO

"},{"location":"man3/BIO_f_buffer/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_buffer(void);\n\nlong BIO_get_buffer_num_lines(BIO *b);\nlong BIO_set_read_buffer_size(BIO *b, long size);\nlong BIO_set_write_buffer_size(BIO *b, long size);\nlong BIO_set_buffer_size(BIO *b, long size);\nlong BIO_set_buffer_read_data(BIO *b, void *buf, long num);\n
"},{"location":"man3/BIO_f_buffer/#description","title":"DESCRIPTION","text":"

BIO_f_buffer() returns the buffering BIO method.

Data written to a buffering BIO is buffered and periodically written to the next BIO in the chain. Data read from a buffering BIO comes from an internal buffer which is filled from the next BIO in the chain. Both BIO_gets() and BIO_puts() are supported.

Calling BIO_reset() on a buffering BIO clears any buffered data.

BIO_get_buffer_num_lines() returns the number of lines currently buffered.

BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() set the read, write or both read and write buffer sizes to size. The initial buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared when the buffer is resized.

BIO_set_buffer_read_data() clears the read buffer and fills it with num bytes of buf. If num is larger than the current buffer size the buffer is expanded.

"},{"location":"man3/BIO_f_buffer/#notes","title":"NOTES","text":"

These functions, other than BIO_f_buffer(), are implemented as macros.

Buffering BIOs implement BIO_read_ex() and BIO_gets() by using BIO_read_ex() operations on the next BIO in the chain and storing the result in an internal buffer, from which bytes are given back to the caller as appropriate for the call; a BIO_gets() is guaranteed to give the caller a whole line, and BIO_read_ex() is guaranteed to give the caller the number of bytes it asks for, unless there's an error or end of communication is reached in the next BIO. By prepending a buffering BIO to a chain it is therefore possible to provide BIO_gets() or exact size BIO_read_ex() functionality if the following BIOs do not support it.

Do not add more than one BIO_f_buffer() to a BIO chain. The result of doing so will force a full read of the size of the internal buffer of the top BIO_f_buffer(), which is 4 KiB at a minimum.

Data is only written to the next BIO in the chain when the write buffer fills or when BIO_flush() is called. It is therefore important to call BIO_flush() whenever any pending data should be written such as when removing a buffering BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate source/sink BIO is non blocking.

"},{"location":"man3/BIO_f_buffer/#return-values","title":"RETURN VALUES","text":"

BIO_f_buffer() returns the buffering BIO method.

BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0) or a negative value in case of errors.

BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() return 1 if the buffer was successfully resized or <=0 for failure.

BIO_set_buffer_read_data() returns 1 if the data was set correctly or <=0 if there was an error.

"},{"location":"man3/BIO_f_buffer/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_reset(3), BIO_flush(3), BIO_pop(3), BIO_ctrl(3).

"},{"location":"man3/BIO_f_buffer/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_cipher/","title":"BIO_f_cipher","text":""},{"location":"man3/BIO_f_cipher/#name","title":"NAME","text":"

BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter

"},{"location":"man3/BIO_f_cipher/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/evp.h>\n\nconst BIO_METHOD *BIO_f_cipher(void);\nint BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,\n                   const unsigned char *key, const unsigned char *iv, int enc);\nint BIO_get_cipher_status(BIO *b);\nint BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx);\n
"},{"location":"man3/BIO_f_cipher/#description","title":"DESCRIPTION","text":"

BIO_f_cipher() returns the cipher BIO method. This is a filter BIO that encrypts any data written through it, and decrypts any data read from it. It is a BIO wrapper for the cipher routines EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().

Cipher BIOs do not support BIO_gets() or BIO_puts().

BIO_flush() on an encryption BIO that is being written through is used to signal that no more data is to be encrypted: this is used to flush and possibly pad the final block through the BIO.

BIO_set_cipher() sets the cipher of BIO b to cipher using key key and IV iv. enc should be set to 1 for encryption and zero for decryption.

When reading from an encryption BIO the final block is automatically decrypted and checked when EOF is detected. BIO_get_cipher_status() is a BIO_ctrl() macro which can be called to determine whether the decryption operation was successful.

BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal BIO cipher context. The retrieved context can be used in conjunction with the standard cipher routines to set it up. This is useful when BIO_set_cipher() is not flexible enough for the applications needs.

"},{"location":"man3/BIO_f_cipher/#notes","title":"NOTES","text":"

When encrypting BIO_flush() must be called to flush the final block through the BIO. If it is not then the final block will fail a subsequent decrypt.

When decrypting an error on the final block is signaled by a zero return value from the read operation. A successful decrypt followed by EOF will also return zero for the final read. BIO_get_cipher_status() should be called to determine if the decrypt was successful.

As always, if BIO_gets() or BIO_puts() support is needed then it can be achieved by preceding the cipher BIO with a buffering BIO.

"},{"location":"man3/BIO_f_cipher/#return-values","title":"RETURN VALUES","text":"

BIO_f_cipher() returns the cipher BIO method.

BIO_set_cipher() returns 1 for success and 0 for failure.

BIO_get_cipher_status() returns 1 for a successful decrypt and <=0 for failure.

BIO_get_cipher_ctx() returns 1 for success and <=0 for failure.

"},{"location":"man3/BIO_f_cipher/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_md/","title":"BIO_f_md","text":""},{"location":"man3/BIO_f_md/#name","title":"NAME","text":"

BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter

"},{"location":"man3/BIO_f_md/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/evp.h>\n\nconst BIO_METHOD *BIO_f_md(void);\nint BIO_set_md(BIO *b, EVP_MD *md);\nint BIO_get_md(BIO *b, EVP_MD **mdp);\nint BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);\n
"},{"location":"man3/BIO_f_md/#description","title":"DESCRIPTION","text":"

BIO_f_md() returns the message digest BIO method. This is a filter BIO that digests any data passed through it. It is a BIO wrapper for the digest routines EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal().

Any data written or read through a digest BIO using BIO_read_ex() and BIO_write_ex() is digested.

BIO_gets(), if its size parameter is large enough finishes the digest calculation and returns the digest value. BIO_puts() is not supported.

BIO_reset() reinitialises a digest BIO.

BIO_set_md() sets the message digest of BIO b to md: this must be called to initialize a digest BIO before any data is passed through it. It is a BIO_ctrl() macro.

BIO_get_md() places a pointer to the digest BIOs digest method in mdp. It is a BIO_ctrl() macro.

BIO_get_md_ctx() returns the digest BIOs context into mdcp.

"},{"location":"man3/BIO_f_md/#notes","title":"NOTES","text":"

The context returned by BIO_get_md_ctx() can be used in calls to EVP_DigestFinal() and also the signature routines EVP_SignFinal() and EVP_VerifyFinal().

The context returned by BIO_get_md_ctx() is an internal context structure. Changes made to this context will affect the digest BIO itself and the context pointer will become invalid when the digest BIO is freed.

After the digest has been retrieved from a digest BIO it must be reinitialized by calling BIO_reset(), or BIO_set_md() before any more data is passed through it.

If an application needs to call BIO_gets() or BIO_puts() through a chain containing digest BIOs then this can be done by prepending a buffering BIO.

Calling BIO_get_md_ctx() will return the context and initialize the BIO state. This allows applications to initialize the context externally if the standard calls such as BIO_set_md() are not sufficiently flexible.

"},{"location":"man3/BIO_f_md/#return-values","title":"RETURN VALUES","text":"

BIO_f_md() returns the digest BIO method.

BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and <=0 for failure.

"},{"location":"man3/BIO_f_md/#examples","title":"EXAMPLES","text":"

The following example creates a BIO chain containing an SHA1 and MD5 digest BIO and passes the string \"Hello World\" through it. Error checking has been omitted for clarity.

BIO *bio, *mdtmp;\nchar message[] = \"Hello World\";\n\nbio = BIO_new(BIO_s_null());\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_sha1());\n/*\n * For BIO_push() we want to append the sink BIO and keep a note of\n * the start of the chain.\n */\nbio = BIO_push(mdtmp, bio);\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_md5());\nbio = BIO_push(mdtmp, bio);\n/* Note: mdtmp can now be discarded */\nBIO_write(bio, message, strlen(message));\n

The next example digests data by reading through a chain instead:

BIO *bio, *mdtmp;\nchar buf[1024];\nint rdlen;\n\nbio = BIO_new_file(file, \"rb\");\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_sha1());\nbio = BIO_push(mdtmp, bio);\nmdtmp = BIO_new(BIO_f_md());\nBIO_set_md(mdtmp, EVP_md5());\nbio = BIO_push(mdtmp, bio);\ndo {\n    rdlen = BIO_read(bio, buf, sizeof(buf));\n    /* Might want to do something with the data here */\n} while (rdlen > 0);\n

This next example retrieves the message digests from a BIO chain and outputs them. This could be used with the examples above.

BIO *mdtmp;\nunsigned char mdbuf[EVP_MAX_MD_SIZE];\nint mdlen;\nint i;\n\nmdtmp = bio;   /* Assume bio has previously been set up */\ndo {\n    EVP_MD *md;\n\n    mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);\n    if (!mdtmp)\n        break;\n    BIO_get_md(mdtmp, &md);\n    printf(\"%s digest\", OBJ_nid2sn(EVP_MD_get_type(md)));\n    mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);\n    for (i = 0; i < mdlen; i++) printf(\":%02X\", mdbuf[i]);\n    printf(\"\\n\");\n    mdtmp = BIO_next(mdtmp);\n} while (mdtmp);\n\nBIO_free_all(bio);\n
"},{"location":"man3/BIO_f_md/#bugs","title":"BUGS","text":"

The lack of support for BIO_puts() and the non standard behaviour of BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() and BIO_puts() should be passed to the next BIO in the chain and digest the data passed through and that digests should be retrieved using a separate BIO_ctrl() call.

"},{"location":"man3/BIO_f_md/#history","title":"HISTORY","text":"

Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the BIO was initialized first.

"},{"location":"man3/BIO_f_md/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_null/","title":"BIO_f_null","text":""},{"location":"man3/BIO_f_null/#name","title":"NAME","text":"

BIO_f_null - null filter

"},{"location":"man3/BIO_f_null/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_null(void);\n
"},{"location":"man3/BIO_f_null/#description","title":"DESCRIPTION","text":"

BIO_f_null() returns the null filter BIO method. This is a filter BIO that does nothing.

All requests to a null filter BIO are passed through to the next BIO in the chain: this means that a BIO chain containing a null filter BIO behaves just as though the BIO was not there.

"},{"location":"man3/BIO_f_null/#notes","title":"NOTES","text":"

As may be apparent a null filter BIO is not particularly useful.

"},{"location":"man3/BIO_f_null/#return-values","title":"RETURN VALUES","text":"

BIO_f_null() returns the null filter BIO method.

"},{"location":"man3/BIO_f_null/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_prefix/","title":"BIO_f_prefix","text":""},{"location":"man3/BIO_f_prefix/#name","title":"NAME","text":"

BIO_f_prefix, BIO_set_prefix, BIO_set_indent, BIO_get_indent - prefix BIO filter

"},{"location":"man3/BIO_f_prefix/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_prefix(void);\nlong BIO_set_prefix(BIO *b, const char *prefix);\nlong BIO_set_indent(BIO *b, long indent);\nlong BIO_get_indent(BIO *b);\n
"},{"location":"man3/BIO_f_prefix/#description","title":"DESCRIPTION","text":"

BIO_f_cipher() returns the prefix BIO method. This is a filter for text output, where each line gets automatically prefixed and indented according to user input.

The prefix and the indentation are combined. For each line of output going through this filter, the prefix is output first, then the amount of additional spaces indicated by the indentation, and then the line itself.

By default, there is no prefix, and indentation is set to 0.

BIO_set_prefix() sets the prefix to be used for future lines of text, using prefix. prefix may be NULL, signifying that there should be no prefix. If prefix isn't NULL, this function makes a copy of it.

BIO_set_indent() sets the indentation to be used for future lines of text, using indent. Negative values are not allowed.

BIO_get_indent() gets the current indentation.

"},{"location":"man3/BIO_f_prefix/#notes","title":"NOTES","text":"

BIO_set_prefix(), BIO_set_indent() and BIO_get_indent() are implemented as macros.

"},{"location":"man3/BIO_f_prefix/#return-values","title":"RETURN VALUES","text":"

BIO_f_prefix() returns the prefix BIO method.

BIO_set_prefix() returns 1 if the prefix was correctly set, or <=0 on failure.

BIO_set_indent() returns 1 if the prefix was correctly set, or <=0 on failure.

BIO_get_indent() returns the current indentation, or a negative value for failure.

"},{"location":"man3/BIO_f_prefix/#see-also","title":"SEE ALSO","text":"

bio(7)

"},{"location":"man3/BIO_f_prefix/#copyright","title":"COPYRIGHT","text":"

Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_readbuffer/","title":"BIO_f_readbuffer","text":""},{"location":"man3/BIO_f_readbuffer/#name","title":"NAME","text":"

BIO_f_readbuffer - read only buffering BIO that supports BIO_tell() and BIO_seek()

"},{"location":"man3/BIO_f_readbuffer/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_f_readbuffer(void);\n
"},{"location":"man3/BIO_f_readbuffer/#description","title":"DESCRIPTION","text":"

BIO_f_readbuffer() returns the read buffering BIO method.

This BIO filter can be inserted on top of BIO's that do not support BIO_tell() or BIO_seek() (e.g. A file BIO that uses stdin).

Data read from a read buffering BIO comes from an internal buffer which is filled from the next BIO in the chain.

BIO_gets() is supported for read buffering BIOs. Writing data to a read buffering BIO is not supported.

Calling BIO_reset() on a read buffering BIO does not clear any buffered data.

"},{"location":"man3/BIO_f_readbuffer/#notes","title":"NOTES","text":"

Read buffering BIOs implement BIO_read_ex() by using BIO_read_ex() operations on the next BIO (e.g. a file BIO) in the chain and storing the result in an internal buffer, from which bytes are given back to the caller as appropriate for the call. BIO_read_ex() is guaranteed to give the caller the number of bytes it asks for, unless there's an error or end of communication is reached in the next BIO. The internal buffer can grow to cache the entire contents of the next BIO in the chain. BIO_seek() uses the internal buffer, so that it can only seek into data that is already read.

"},{"location":"man3/BIO_f_readbuffer/#return-values","title":"RETURN VALUES","text":"

BIO_f_readbuffer() returns the read buffering BIO method.

"},{"location":"man3/BIO_f_readbuffer/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_read(3), BIO_gets(3), BIO_reset(3), BIO_ctrl(3).

"},{"location":"man3/BIO_f_readbuffer/#copyright","title":"COPYRIGHT","text":"

Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_f_ssl/","title":"BIO_f_ssl","text":""},{"location":"man3/BIO_f_ssl/#name","title":"NAME","text":"

BIO_do_handshake, BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO

"},{"location":"man3/BIO_f_ssl/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n#include <openssl/ssl.h>\n\nconst BIO_METHOD *BIO_f_ssl(void);\n\nlong BIO_set_ssl(BIO *b, SSL *ssl, long c);\nlong BIO_get_ssl(BIO *b, SSL **sslp);\nlong BIO_set_ssl_mode(BIO *b, long client);\nlong BIO_set_ssl_renegotiate_bytes(BIO *b, long num);\nlong BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);\nlong BIO_get_num_renegotiates(BIO *b);\n\nBIO *BIO_new_ssl(SSL_CTX *ctx, int client);\nBIO *BIO_new_ssl_connect(SSL_CTX *ctx);\nBIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);\nint BIO_ssl_copy_session_id(BIO *to, BIO *from);\nvoid BIO_ssl_shutdown(BIO *bio);\n\nlong BIO_do_handshake(BIO *b);\n
"},{"location":"man3/BIO_f_ssl/#description","title":"DESCRIPTION","text":"

BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which is a wrapper round the OpenSSL SSL routines adding a BIO \"flavour\" to SSL I/O.

I/O performed on an SSL BIO communicates using the SSL protocol with the SSLs read and write BIOs. If an SSL connection is not established then an attempt is made to establish one on the first I/O call.

If a BIO is appended to an SSL BIO using BIO_push() it is automatically used as the SSL BIOs read and write BIOs.

Calling BIO_reset() on an SSL BIO closes down any current SSL connection by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in the chain: this will typically disconnect the underlying transport. The SSL BIO is then reset to the initial accept or connect state.

If the close flag is set when an SSL BIO is freed then the internal SSL structure is also freed using SSL_free().

BIO_set_ssl() sets the internal SSL pointer of SSL BIO b to ssl using the close flag c.

BIO_get_ssl() retrieves the SSL pointer of SSL BIO b, it can then be manipulated using the standard SSL library functions.

BIO_set_ssl_mode() sets the SSL BIO mode to client. If client is 1 client mode is set. If client is 0 server mode is set.

BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count of SSL BIO b to num. When set after every num bytes of I/O (read and write) the SSL session is automatically renegotiated. num must be at least 512 bytes.

BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout of SSL BIO b to seconds. When the renegotiate timeout elapses the session is automatically renegotiated.

BIO_get_num_renegotiates() returns the total number of session renegotiations due to I/O or timeout of SSL BIO b.

BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client mode if client is non zero.

BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO (using ctx) followed by a connect BIO.

BIO_new_buffer_ssl_connect() creates a new BIO chain consisting of a buffering BIO, an SSL BIO (using ctx), and a connect BIO.

BIO_ssl_copy_session_id() copies an SSL session id between BIO chains from and to. It does this by locating the SSL BIOs in each chain and calling SSL_copy_session_id() on the internal SSL pointer.

BIO_ssl_shutdown() closes down an SSL connection on BIO chain bio. It does this by locating the SSL BIO in the chain and calling SSL_shutdown() on its internal SSL pointer.

BIO_do_handshake() attempts to complete an SSL handshake on the supplied BIO and establish the SSL connection. For non-SSL BIOs the connection is done typically at TCP level. If domain name resolution yields multiple IP addresses all of them are tried after connect() failures. The function returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established. The call BIO_should_retry() should be used for nonblocking connect BIOs to determine if the call should be retried. If a connection has already been established this call has no effect.

"},{"location":"man3/BIO_f_ssl/#notes","title":"NOTES","text":"

SSL BIOs are exceptional in that if the underlying transport is non blocking they can still request a retry in exceptional circumstances. Specifically this will happen if a session renegotiation takes place during a BIO_read_ex() operation, one case where this happens is when step up occurs.

The SSL flag SSL_AUTO_RETRY can be set to disable this behaviour. That is when this flag is set an SSL BIO using a blocking transport will never request a retry.

Since unknown BIO_ctrl() operations are sent through filter BIOs the servers name and port can be set using BIO_set_host() on the BIO returned by BIO_new_ssl_connect() without having to locate the connect BIO first.

Applications do not have to call BIO_do_handshake() but may wish to do so to separate the handshake process from other I/O processing.

BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.

BIO_ssl_copy_session_id() is not currently supported on QUIC SSL objects and fails if called on such an object.

"},{"location":"man3/BIO_f_ssl/#return-values","title":"RETURN VALUES","text":"

BIO_f_ssl() returns the SSL BIO_METHOD structure.

BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on success or a value which is less than or equal to 0 if an error occurred.

BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return a valid BIO structure on success or NULL if an error occurred.

BIO_ssl_copy_session_id() returns 1 on success or 0 on error, or if called on a QUIC SSL object.

BIO_do_handshake() returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established.

"},{"location":"man3/BIO_f_ssl/#examples","title":"EXAMPLES","text":"

This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web server. The I/O routines are identical to those of the unencrypted example in BIO_s_connect(3).

BIO *sbio, *out;\nint len;\nchar tmpbuf[1024];\nSSL_CTX *ctx;\nSSL *ssl;\n\n/* XXX Seed the PRNG if needed. */\n\nctx = SSL_CTX_new(TLS_client_method());\n\n/* XXX Set verify paths and mode here. */\n\nsbio = BIO_new_ssl_connect(ctx);\nBIO_get_ssl(sbio, &ssl);\nif (ssl == NULL) {\n    fprintf(stderr, \"Can't locate SSL pointer\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* XXX We might want to do other things with ssl here */\n\n/* An empty host part means the loopback address */\nBIO_set_conn_hostname(sbio, \":https\");\n\nout = BIO_new_fp(stdout, BIO_NOCLOSE);\nif (BIO_do_connect(sbio) <= 0) {\n    fprintf(stderr, \"Error connecting to server\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* XXX Could examine ssl here to get connection info */\n\nBIO_puts(sbio, \"GET / HTTP/1.0\\n\\n\");\nfor (;;) {\n    len = BIO_read(sbio, tmpbuf, 1024);\n    if (len <= 0)\n        break;\n    BIO_write(out, tmpbuf, len);\n}\nBIO_free_all(sbio);\nBIO_free(out);\n

Here is a simple server example. It makes use of a buffering BIO to allow lines to be read from the SSL BIO using BIO_gets. It creates a pseudo web page containing the actual request from a client and also echoes the request to standard output.

BIO *sbio, *bbio, *acpt, *out;\nint len;\nchar tmpbuf[1024];\nSSL_CTX *ctx;\nSSL *ssl;\n\n/* XXX Seed the PRNG if needed. */\n\nctx = SSL_CTX_new(TLS_server_method());\nif (!SSL_CTX_use_certificate_file(ctx, \"server.pem\", SSL_FILETYPE_PEM)\n        || !SSL_CTX_use_PrivateKey_file(ctx, \"server.pem\", SSL_FILETYPE_PEM)\n        || !SSL_CTX_check_private_key(ctx)) {\n    fprintf(stderr, \"Error setting up SSL_CTX\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* XXX Other things like set verify locations, EDH temp callbacks. */\n\n/* New SSL BIO setup as server */\nsbio = BIO_new_ssl(ctx, 0);\nBIO_get_ssl(sbio, &ssl);\nif (ssl == NULL) {\n    fprintf(stderr, \"Can't locate SSL pointer\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\nbbio = BIO_new(BIO_f_buffer());\nsbio = BIO_push(bbio, sbio);\nacpt = BIO_new_accept(\"4433\");\n\n/*\n * By doing this when a new connection is established\n * we automatically have sbio inserted into it. The\n * BIO chain is now 'swallowed' by the accept BIO and\n * will be freed when the accept BIO is freed.\n */\nBIO_set_accept_bios(acpt, sbio);\nout = BIO_new_fp(stdout, BIO_NOCLOSE);\n\n/* First call to BIO_do_accept() sets up accept BIO */\nif (BIO_do_accept(acpt) <= 0) {\n    fprintf(stderr, \"Error setting up accept BIO\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n

/* Second call to BIO_do_accept() waits for incoming connection */ if (BIO_do_accept(acpt) <= 0) { fprintf(stderr, \"Error accepting connection\\n\"); ERR_print_errors_fp(stderr); exit(1); }

/* We only want one connection so remove and free accept BIO */\nsbio = BIO_pop(acpt);\nBIO_free_all(acpt);\n\nif (BIO_do_handshake(sbio) <= 0) {\n    fprintf(stderr, \"Error in SSL handshake\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\nBIO_puts(sbio, \"HTTP/1.0 200 OK\\r\\nContent-type: text/plain\\r\\n\\r\\n\");\nBIO_puts(sbio, \"\\r\\nConnection Established\\r\\nRequest headers:\\r\\n\");\nBIO_puts(sbio, \"--------------------------------------------------\\r\\n\");\n\nfor (;;) {\n    len = BIO_gets(sbio, tmpbuf, 1024);\n    if (len <= 0)\n        break;\n    BIO_write(sbio, tmpbuf, len);\n    BIO_write(out, tmpbuf, len);\n    /* Look for blank line signifying end of headers*/\n    if (tmpbuf[0] == '\\r' || tmpbuf[0] == '\\n')\n        break;\n}\n\nBIO_puts(sbio, \"--------------------------------------------------\\r\\n\");\nBIO_puts(sbio, \"\\r\\n\");\nBIO_flush(sbio);\nBIO_free_all(sbio);\n
"},{"location":"man3/BIO_f_ssl/#history","title":"HISTORY","text":"

In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly, the I/O BIO reference count was incorrectly incremented (instead of decremented) and dissociated with the SSL BIO even if the SSL BIO was not explicitly being popped (e.g. a pop higher up the chain). Applications which included workarounds for this bug (e.g. freeing BIOs more than once) should be modified to handle this fix or they may free up an already freed BIO.

"},{"location":"man3/BIO_f_ssl/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_find_type/","title":"BIO_find_type","text":""},{"location":"man3/BIO_find_type/#name","title":"NAME","text":"

BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal

"},{"location":"man3/BIO_find_type/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO *BIO_find_type(BIO *b, int bio_type);\nBIO *BIO_next(BIO *b);\nint BIO_method_type(const BIO *b);\n
"},{"location":"man3/BIO_find_type/#description","title":"DESCRIPTION","text":"

The BIO_find_type() searches for a BIO of a given type in a chain, starting at BIO b. If type is a specific type (such as BIO_TYPE_MEM) then a search is made for a BIO of that type. If type is a general type (such as BIO_TYPE_SOURCE_SINK) then the next matching BIO of the given general type is searched for. BIO_find_type() returns the next matching BIO or NULL if none is found. If type is BIO_TYPE_NONE it will not find a match.

The following general types are defined: BIO_TYPE_DESCRIPTOR, BIO_TYPE_FILTER, and BIO_TYPE_SOURCE_SINK.

For a list of the specific types, see the <openssl/bio.h> header file.

BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs in a chain or used in conjunction with BIO_find_type() to find all BIOs of a certain type.

BIO_method_type() returns the type of a BIO.

"},{"location":"man3/BIO_find_type/#return-values","title":"RETURN VALUES","text":"

BIO_find_type() returns a matching BIO or NULL for no match.

BIO_next() returns the next BIO in a chain.

BIO_method_type() returns the type of the BIO b.

"},{"location":"man3/BIO_find_type/#examples","title":"EXAMPLES","text":"

Traverse a chain looking for digest BIOs:

BIO *btmp;\n\nbtmp = in_bio; /* in_bio is chain to search through */\ndo {\n    btmp = BIO_find_type(btmp, BIO_TYPE_MD);\n    if (btmp == NULL)\n        break; /* Not found */\n    /* btmp is a digest BIO, do something with it ...*/\n    ...\n\n    btmp = BIO_next(btmp);\n} while (btmp);\n
"},{"location":"man3/BIO_find_type/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_get_data/","title":"BIO_get_data","text":""},{"location":"man3/BIO_get_data/#name","title":"NAME","text":"

BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown, BIO_get_shutdown - functions for managing BIO state information

"},{"location":"man3/BIO_get_data/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nvoid BIO_set_data(BIO *a, void *ptr);\nvoid *BIO_get_data(BIO *a);\nvoid BIO_set_init(BIO *a, int init);\nint BIO_get_init(BIO *a);\nvoid BIO_set_shutdown(BIO *a, int shut);\nint BIO_get_shutdown(BIO *a);\n
"},{"location":"man3/BIO_get_data/#description","title":"DESCRIPTION","text":"

These functions are mainly useful when implementing a custom BIO.

The BIO_set_data() function associates the custom data pointed to by ptr with the BIO. This data can subsequently be retrieved via a call to BIO_get_data(). This can be used by custom BIOs for storing implementation specific information.

The BIO_set_init() function sets the value of the BIO's \"init\" flag to indicate whether initialisation has been completed for this BIO or not. A nonzero value indicates that initialisation is complete, whilst zero indicates that it is not. Often initialisation will complete during initial construction of the BIO. For some BIOs however, initialisation may not complete until after additional steps have occurred (for example through calling custom ctrls). The BIO_get_init() function returns the value of the \"init\" flag.

The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource is also closed when the BIO is freed.

"},{"location":"man3/BIO_get_data/#return-values","title":"RETURN VALUES","text":"

BIO_get_data() returns a pointer to the implementation specific custom data associated with this BIO, or NULL if none has been set.

BIO_get_init() returns the state of the BIO's init flag.

BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.

"},{"location":"man3/BIO_get_data/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_meth_new(3)

"},{"location":"man3/BIO_get_data/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_get_data/#copyright","title":"COPYRIGHT","text":"

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_get_ex_new_index/","title":"BIO_get_ex_new_index","text":""},{"location":"man3/BIO_get_ex_new_index/#name","title":"NAME","text":"

BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data, BIO_set_app_data, BIO_get_app_data, DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data, DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data, EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data, ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, EVP_PKEY_get_ex_new_index, EVP_PKEY_set_ex_data, EVP_PKEY_get_ex_data, RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data, RSA_set_app_data, RSA_get_app_data, SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data, SSL_set_app_data, SSL_get_app_data, SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data, SSL_CTX_set_app_data, SSL_CTX_get_app_data, SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data, SSL_SESSION_set_app_data, SSL_SESSION_get_app_data, UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, UI_set_app_data, UI_get_app_data, X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, X509_STORE_CTX_set_app_data, X509_STORE_CTX_get_app_data, X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data, X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data - application-specific data

"},{"location":"man3/BIO_get_ex_new_index/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/x509.h>\n\nint TYPE_get_ex_new_index(long argl, void *argp,\n                          CRYPTO_EX_new *new_func,\n                          CRYPTO_EX_dup *dup_func,\n                          CRYPTO_EX_free *free_func);\n\nint TYPE_set_ex_data(TYPE *d, int idx, void *arg);\n\nvoid *TYPE_get_ex_data(const TYPE *d, int idx);\n\n#define TYPE_set_app_data(TYPE *d, void *arg)\n#define TYPE_get_app_data(TYPE *d)\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                        CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint DH_set_ex_data(DH *type, int idx, void *arg);\nvoid *DH_get_ex_data(DH *type, int idx);\nint DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint DSA_set_ex_data(DSA *type, int idx, void *arg);\nvoid *DSA_get_ex_data(DSA *type, int idx);\nint EC_KEY_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                            CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint EC_KEY_set_ex_data(EC_KEY *type, int idx, void *arg);\nvoid *EC_KEY_get_ex_data(EC_KEY *type, int idx);\nint RSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint RSA_set_ex_data(RSA *type, int idx, void *arg);\nvoid *RSA_get_ex_data(RSA *type, int idx);\nint RSA_set_app_data(RSA *type, void *arg);\nvoid *RSA_get_app_data(RSA *type);\nint ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,\n                            CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);\nint ENGINE_set_ex_data(ENGINE *type, int idx, void *arg);\nvoid *ENGINE_get_ex_data(ENGINE *type, int idx);\n
"},{"location":"man3/BIO_get_ex_new_index/#description","title":"DESCRIPTION","text":"

In the description here, TYPE is used a placeholder for any of the OpenSSL datatypes listed in CRYPTO_get_ex_new_index(3).

All functions with a TYPE of DH, DSA, RSA and EC_KEY are deprecated. Applications should instead use EVP_PKEY_set_ex_data(), EVP_PKEY_get_ex_data() and EVP_PKEY_get_ex_new_index().

All functions with a TYPE of ENGINE are deprecated. Applications using engines should be replaced by providers.

These functions handle application-specific data for OpenSSL data structures.

TYPE_get_ex_new_index() is a macro that calls CRYPTO_get_ex_new_index() with the correct index value.

TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with an offset into the opaque exdata part of the TYPE object.

TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an offset into the opaque exdata part of the TYPE object.

For compatibility with previous releases, the exdata index of zero is reserved for \"application data.\" There are two convenience functions for this. TYPE_set_app_data() is a macro that invokes TYPE_set_ex_data() with idx set to zero. TYPE_get_app_data() is a macro that invokes TYPE_get_ex_data() with idx set to zero.

"},{"location":"man3/BIO_get_ex_new_index/#return-values","title":"RETURN VALUES","text":"

TYPE_get_ex_new_index() returns a new index on success or -1 on error.

TYPE_set_ex_data() returns 1 on success or 0 on error.

TYPE_get_ex_data() returns the application data or NULL if an error occurred.

"},{"location":"man3/BIO_get_ex_new_index/#see-also","title":"SEE ALSO","text":"

CRYPTO_get_ex_new_index(3).

"},{"location":"man3/BIO_get_ex_new_index/#history","title":"HISTORY","text":"

The functions DH_get_ex_new_index(), DH_set_ex_data(), DH_get_ex_data(), DSA_get_ex_new_index(), DSA_set_ex_data(), DSA_get_ex_data(), EC_KEY_get_ex_new_index(), EC_KEY_set_ex_data(), EC_KEY_get_ex_data(), ENGINE_get_ex_new_index(), ENGINE_set_ex_data(), ENGINE_get_ex_data(), RSA_get_ex_new_index(), RSA_set_ex_data(), RSA_get_ex_data(), RSA_set_app_data() and RSA_get_app_data() were deprecated in OpenSSL 3.0.

"},{"location":"man3/BIO_get_ex_new_index/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_get_rpoll_descriptor/","title":"BIO_get_rpoll_descriptor","text":""},{"location":"man3/BIO_get_rpoll_descriptor/#name","title":"NAME","text":"

BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor - obtain a structure which can be used to determine when a BIO object can next be read or written

"},{"location":"man3/BIO_get_rpoll_descriptor/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef struct bio_poll_descriptor_st {\n    uint32_t type;\n    union {\n        int        fd;\n        void       *custom;\n        uintptr_t  custom_ui;\n    } value;\n} BIO_POLL_DESCRIPTOR;\n\nint BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);\nint BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);\n
"},{"location":"man3/BIO_get_rpoll_descriptor/#description","title":"DESCRIPTION","text":"

BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), on success, fill *desc with a poll descriptor. A poll descriptor is a tagged union structure which represents some kind of OS or non-OS resource which can be used to synchronise on I/O availability events.

BIO_get_rpoll_descriptor() outputs a descriptor which can be used to determine when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor() outputs a descriptor which can be used to determine when the BIO can (potentially) next be written.

It is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() to output the same descriptor.

Poll descriptors can represent different kinds of information. A typical kind of resource which might be represented by a poll descriptor is an OS file descriptor which can be used with APIs such as select().

The kinds of poll descriptor defined by OpenSSL are:

Because poll descriptors are a tagged union structure, they can represent different kinds of information. New types of poll descriptor may be defined, including by applications, according to their needs.

"},{"location":"man3/BIO_get_rpoll_descriptor/#return-values","title":"RETURN VALUES","text":"

The functions BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1 on success and 0 on failure.

These functions are permitted to succeed and initialise *desc with a poll descriptor of type BIO_POLL_DESCRIPTOR_TYPE_NONE to indicate that the BIO is not pollable for readability or writeability respectively.

"},{"location":"man3/BIO_get_rpoll_descriptor/#see-also","title":"SEE ALSO","text":"

SSL_handle_events(3), SSL_get_event_timeout(3), SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3), bio(7)

"},{"location":"man3/BIO_get_rpoll_descriptor/#history","title":"HISTORY","text":"

The SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() functions were added in OpenSSL 3.2.

"},{"location":"man3/BIO_get_rpoll_descriptor/#copyright","title":"COPYRIGHT","text":"

Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_meth_new/","title":"BIO_meth_new","text":""},{"location":"man3/BIO_meth_new/#name","title":"NAME","text":"

BIO_get_new_index, BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex, BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write, BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg, BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg - Routines to build up BIO methods

"},{"location":"man3/BIO_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_get_new_index(void);\n\nBIO_METHOD *BIO_meth_new(int type, const char *name);\n\nvoid BIO_meth_free(BIO_METHOD *biom);\n\nint (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,\n                                               size_t *);\nint (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);\nint BIO_meth_set_write_ex(BIO_METHOD *biom,\n                          int (*bwrite)(BIO *, const char *, size_t, size_t *));\nint BIO_meth_set_write(BIO_METHOD *biom,\n                       int (*write)(BIO *, const char *, int));\n\nint (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);\nint (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);\nint BIO_meth_set_read_ex(BIO_METHOD *biom,\n                         int (*bread)(BIO *, char *, size_t, size_t *));\nint BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));\n\nint (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);\nint BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));\n\nint (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);\nint BIO_meth_set_gets(BIO_METHOD *biom,\n                      int (*gets)(BIO *, char *, int));\n\nlong (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);\nint BIO_meth_set_ctrl(BIO_METHOD *biom,\n                      long (*ctrl)(BIO *, int, long, void *));\n\nint (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);\nint BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));\n\nint (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);\nint BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));\n\nlong (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);\nint BIO_meth_set_callback_ctrl(BIO_METHOD *biom,\n                               long (*callback_ctrl)(BIO *, int, BIO_info_cb *));\n\nossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *,\n                                                              BIO_MSG *,\n                                                              size_t,\n                                                              size_t,\n                                                              uint64_t);\nint BIO_meth_set_sendmmsg(BIO_METHOD *biom,\n                          ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,\n                                             size_t, uint64_t));\n\nossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *,\n                                                              BIO_MSG *,\n                                                              size_t,\n                                                              size_t,\n                                                              uint64_t);\nint BIO_meth_set_recvmmsg(BIO_METHOD *biom,\n                          ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,\n                                             size_t, uint64_t));\n
"},{"location":"man3/BIO_meth_new/#description","title":"DESCRIPTION","text":"

The BIO_METHOD type is a structure used for the implementation of new BIO types. It provides a set of functions used by OpenSSL for the implementation of the various BIO capabilities. See the bio(7) page for more information.

BIO_meth_new() creates a new BIO_METHOD structure that contains a type identifier type and a string that represents its name. type can be set to either BIO_TYPE_NONE or via BIO_get_new_index() if a unique type is required for searching (See BIO_find_type(3))

Note that BIO_get_new_index() can only be used 127 times before it returns an error.

The set of standard OpenSSL provided BIO types is provided in <openssl/bio.h>. Some examples include BIO_TYPE_BUFFER and BIO_TYPE_CIPHER. Filter BIOs should have a type which have the \"filter\" bit set (BIO_TYPE_FILTER). Source/sink BIOs should have the \"source/sink\" bit set (BIO_TYPE_SOURCE_SINK). File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the \"descriptor\" bit set (BIO_TYPE_DESCRIPTOR). See the BIO_find_type(3) page for more information.

BIO_meth_free() destroys a BIO_METHOD structure and frees up any memory associated with it. If the argument is NULL, nothing is done.

BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function used for writing arbitrary length data to the BIO respectively. This function will be called in response to the application calling BIO_write_ex() or BIO_write(). The parameters for the function have the same meaning as for BIO_write_ex(). Older code may call BIO_meth_get_write() and BIO_meth_set_write() instead. Applications should not call both BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write() when the function was set with BIO_meth_set_write_ex().

BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used for reading arbitrary length data from the BIO respectively. This function will be called in response to the application calling BIO_read_ex() or BIO_read(). The parameters for the function have the same meaning as for BIO_read_ex(). Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead. Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read() or call BIO_meth_get_read() when the function was set with BIO_meth_set_read_ex().

BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for writing a NULL terminated string to the BIO respectively. This function will be called in response to the application calling BIO_puts(). The parameters for the function have the same meaning as for BIO_puts().

BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically used for reading a line of data from the BIO respectively (see the BIO_gets(3) page for more information). This function will be called in response to the application calling BIO_gets(). The parameters for the function have the same meaning as for BIO_gets().

BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for processing ctrl messages in the BIO respectively. See the BIO_ctrl(3) page for more information. This function will be called in response to the application calling BIO_ctrl(). The parameters for the function have the same meaning as for BIO_ctrl().

BIO_meth_get_create() and BIO_meth_set_create() get and set the function used for creating a new instance of the BIO respectively. This function will be called in response to the application calling BIO_new() and passing in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the memory for the new BIO, and a pointer to this newly allocated structure will be passed as a parameter to the function. If a create function is set, BIO_new() will not mark the BIO as initialised on allocation. BIO_set_init(3) must then be called either by the create function, or later, by a BIO ctrl function, once BIO initialisation is complete.

BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used for destroying an instance of a BIO respectively. This function will be called in response to the application calling BIO_free(). A pointer to the BIO to be destroyed is passed as a parameter. The destroy function should be used for BIO specific clean up. The memory for the BIO itself should not be freed by this function.

BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the function used for processing callback ctrl messages in the BIO respectively. See the BIO_callback_ctrl(3) page for more information. This function will be called in response to the application calling BIO_callback_ctrl(). The parameters for the function have the same meaning as for BIO_callback_ctrl().

BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and BIO_meth_set_recvmmsg() get and set the functions used for handling BIO_sendmmsg() and BIO_recvmmsg() calls respectively. See BIO_sendmmsg(3) for more information.

"},{"location":"man3/BIO_meth_new/#return-values","title":"RETURN VALUES","text":"

BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.

BIO_meth_new(int type, const char *name) returns a valid BIO_METHOD or NULL if an error occurred.

The BIO_meth_set functions return 1 on success or 0 on error.

The BIO_meth_get functions return the corresponding function pointers.

"},{"location":"man3/BIO_meth_new/#see-also","title":"SEE ALSO","text":"

bio(7), BIO_find_type(3), BIO_ctrl(3), BIO_read_ex(3), BIO_new(3)

"},{"location":"man3/BIO_meth_new/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_new/","title":"BIO_new","text":""},{"location":"man3/BIO_new/#name","title":"NAME","text":"

BIO_new_ex, BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions

"},{"location":"man3/BIO_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO *BIO_new_ex(OSSL_LIB_CTX *libctx, const BIO_METHOD *type);\nBIO *BIO_new(const BIO_METHOD *type);\nint BIO_up_ref(BIO *a);\nint BIO_free(BIO *a);\nvoid BIO_vfree(BIO *a);\nvoid BIO_free_all(BIO *a);\n
"},{"location":"man3/BIO_new/#description","title":"DESCRIPTION","text":"

The BIO_new_ex() function returns a new BIO using method type associated with the library context libctx (see OSSL_LIB_CTX(3)). The library context may be NULL to indicate the default library context.

The BIO_new() is the same as BIO_new_ex() except the default library context is always used.

BIO_up_ref() increments the reference count associated with the BIO object.

BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO but it does not return a value. If a is NULL nothing is done. Calling BIO_free() may also have some effect on the underlying I/O structure, for example it may close the file being referred to under certain circumstances. For more details see the individual BIO_METHOD descriptions.

BIO_free_all() frees up an entire BIO chain, it does not halt if an error occurs freeing up an individual BIO in the chain. If a is NULL nothing is done.

"},{"location":"man3/BIO_new/#return-values","title":"RETURN VALUES","text":"

BIO_new_ex() and BIO_new() return a newly created BIO or NULL if the call fails.

BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.

BIO_free_all() and BIO_vfree() do not return values.

"},{"location":"man3/BIO_new/#notes","title":"NOTES","text":"

If BIO_free() is called on a BIO chain it will only free one BIO resulting in a memory leak.

Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() on it other than the discarded return value.

"},{"location":"man3/BIO_new/#history","title":"HISTORY","text":"

BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.

BIO_new_ex() was added in OpenSSL 3.0.

"},{"location":"man3/BIO_new/#examples","title":"EXAMPLES","text":"

Create a memory BIO:

BIO *mem = BIO_new(BIO_s_mem());\n
"},{"location":"man3/BIO_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_new_CMS/","title":"BIO_new_CMS","text":""},{"location":"man3/BIO_new_CMS/#name","title":"NAME","text":"

BIO_new_CMS - CMS streaming filter BIO

"},{"location":"man3/BIO_new_CMS/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nBIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);\n
"},{"location":"man3/BIO_new_CMS/#description","title":"DESCRIPTION","text":"

BIO_new_CMS() returns a streaming filter BIO chain based on cms. The output of the filter is written to out. Any data written to the chain is automatically translated to a BER format CMS structure of the appropriate type.

"},{"location":"man3/BIO_new_CMS/#notes","title":"NOTES","text":"

The chain returned by this function behaves like a standard filter BIO. It supports non blocking I/O. Content is processed and streamed on the fly and not all held in memory at once: so it is possible to encode very large structures. After all content has been written through the chain BIO_flush() must be called to finalise the structure.

The CMS_STREAM flag must be included in the corresponding flags parameter of the cms creation function.

If an application wishes to write additional data to out BIOs should be removed from the chain using BIO_pop() and freed with BIO_free() until out is reached. If no additional data needs to be written BIO_free_all() can be called to free up the whole chain.

Any content written through the filter is used verbatim: no canonical translation is performed.

It is possible to chain multiple BIOs to, for example, create a triple wrapped signed, enveloped, signed structure. In this case it is the applications responsibility to set the inner content type of any outer CMS_ContentInfo structures.

Large numbers of small writes through the chain should be avoided as this will produce an output consisting of lots of OCTET STRING structures. Prepending a BIO_f_buffer() buffering BIO will prevent this.

"},{"location":"man3/BIO_new_CMS/#bugs","title":"BUGS","text":"

There is currently no corresponding inverse BIO: i.e. one which can decode a CMS structure on the fly.

"},{"location":"man3/BIO_new_CMS/#return-values","title":"RETURN VALUES","text":"

BIO_new_CMS() returns a BIO chain when successful or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/BIO_new_CMS/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_encrypt(3)

"},{"location":"man3/BIO_new_CMS/#history","title":"HISTORY","text":"

The BIO_new_CMS() function was added in OpenSSL 1.0.0.

"},{"location":"man3/BIO_new_CMS/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_parse_hostserv/","title":"BIO_parse_hostserv","text":""},{"location":"man3/BIO_parse_hostserv/#name","title":"NAME","text":"

BIO_hostserv_priorities, BIO_parse_hostserv - utility routines to parse a standard host and service string

"},{"location":"man3/BIO_parse_hostserv/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nenum BIO_hostserv_priorities {\n    BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV\n};\nint BIO_parse_hostserv(const char *hostserv, char **host, char **service,\n                       enum BIO_hostserv_priorities hostserv_prio);\n
"},{"location":"man3/BIO_parse_hostserv/#description","title":"DESCRIPTION","text":"

BIO_parse_hostserv() will parse the information given in hostserv, create strings with the hostname and service name and give those back via host and service. Those will need to be freed after they are used. hostserv_prio helps determine if hostserv shall be interpreted primarily as a hostname or a service name in ambiguous cases.

The syntax the BIO_parse_hostserv() recognises is:

host + ':' + service\nhost + ':' + '*'\nhost + ':'\n       ':' + service\n'*'  + ':' + service\nhost\nservice\n

The host part can be a name or an IP address. If it's a IPv6 address, it MUST be enclosed in brackets, such as '[::1]'.

The service part can be a service name or its port number. A service name will be mapped to a port number using the system function getservbyname().

The returned values will depend on the given hostserv string and hostserv_prio, as follows:

host + ':' + service  => *host = \"host\", *service = \"service\"\nhost + ':' + '*'      => *host = \"host\", *service = NULL\nhost + ':'            => *host = \"host\", *service = NULL\n       ':' + service  => *host = NULL, *service = \"service\"\n '*' + ':' + service  => *host = NULL, *service = \"service\"\n\nin case no ':' is present in the string, the result depends on\nhostserv_prio, as follows:\n\nwhen hostserv_prio == BIO_PARSE_PRIO_HOST\nhost                 => *host = \"host\", *service untouched\n\nwhen hostserv_prio == BIO_PARSE_PRIO_SERV\nservice              => *host untouched, *service = \"service\"\n
"},{"location":"man3/BIO_parse_hostserv/#return-values","title":"RETURN VALUES","text":"

BIO_parse_hostserv() returns 1 on success or 0 on error.

"},{"location":"man3/BIO_parse_hostserv/#see-also","title":"SEE ALSO","text":"

BIO_ADDRINFO(3)

"},{"location":"man3/BIO_parse_hostserv/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_printf/","title":"BIO_printf","text":""},{"location":"man3/BIO_printf/#name","title":"NAME","text":"

BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf - formatted output to a BIO

"},{"location":"man3/BIO_printf/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_printf(BIO *bio, const char *format, ...);\nint BIO_vprintf(BIO *bio, const char *format, va_list args);\n\nint BIO_snprintf(char *buf, size_t n, const char *format, ...);\nint BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args);\n
"},{"location":"man3/BIO_printf/#description","title":"DESCRIPTION","text":"

BIO_printf() is similar to the standard C printf() function, except that the output is sent to the specified BIO, bio, rather than standard output. All common format specifiers are supported.

BIO_vprintf() is similar to the vprintf() function found on many platforms, the output is sent to the specified BIO, bio, rather than standard output. All common format specifiers are supported. The argument list args is a stdarg argument list.

BIO_snprintf() is for platforms that do not have the common snprintf() function. It is like sprintf() except that the size parameter, n, specifies the size of the output buffer.

BIO_vsnprintf() is to BIO_snprintf() as BIO_vprintf() is to BIO_printf().

"},{"location":"man3/BIO_printf/#return-values","title":"RETURN VALUES","text":"

All functions return the number of bytes written, or -1 on error. For BIO_snprintf() and BIO_vsnprintf() this includes when the output buffer is too small.

"},{"location":"man3/BIO_printf/#notes","title":"NOTES","text":"

Except when n is 0, both BIO_snprintf() and BIO_vsnprintf() always terminate their output with '\\0'. This includes cases where -1 is returned, such as when there is insufficient space to output the whole string.

"},{"location":"man3/BIO_printf/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_push/","title":"BIO_push","text":""},{"location":"man3/BIO_push/#name","title":"NAME","text":"

BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain

"},{"location":"man3/BIO_push/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO *BIO_push(BIO *b, BIO *next);\nBIO *BIO_pop(BIO *b);\nvoid BIO_set_next(BIO *b, BIO *next);\n
"},{"location":"man3/BIO_push/#description","title":"DESCRIPTION","text":"

BIO_push() pushes b on next. If b is NULL the function does nothing and returns next. Otherwise it prepends b, which may be a single BIO or a chain of BIOs, to next (unless next is NULL). It then makes a control call on b and returns b.

BIO_pop() removes the BIO b from any chain is is part of. If b is NULL the function does nothing and returns NULL. Otherwise it makes a control call on b and returns the next BIO in the chain, or NULL if there is no next BIO. The removed BIO becomes a single BIO with no association with the original chain, it can thus be freed or be made part of a different chain.

BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to by next. The new chain may include some of the same BIOs from the old chain or it may be completely different.

"},{"location":"man3/BIO_push/#notes","title":"NOTES","text":"

The names of these functions are perhaps a little misleading. BIO_push() joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, the deleted BIO does not need to be at the end of a chain.

The process of calling BIO_push() and BIO_pop() on a BIO may have additional consequences (a control call is made to the affected BIOs). Any effects will be noted in the descriptions of individual BIOs.

"},{"location":"man3/BIO_push/#return-values","title":"RETURN VALUES","text":"

BIO_push() returns the head of the chain, which usually is b, or next if b is NULL.

BIO_pop() returns the next BIO in the chain, or NULL if there is no next BIO.

"},{"location":"man3/BIO_push/#examples","title":"EXAMPLES","text":"

For these examples suppose md1 and md2 are digest BIOs, b64 is a base64 BIO and f is a file BIO.

If the call:

BIO_push(b64, f);\n

is made then the new chain will be b64-f. After making the calls

BIO_push(md2, b64);\nBIO_push(md1, md2);\n

the new chain is md1-md2-b64-f. Data written to md1 will be digested by md1 and md2, base64 encoded, and finally written to f.

It should be noted that reading causes data to pass in the reverse direction, that is data is read from f, base64 decoded, and digested by md2 and then md1.

The call:

BIO_pop(md2);\n

will return b64 and the new chain will be md1-b64-f. Data can be written to and read from md1 as before, except that md2 will no more be applied.

"},{"location":"man3/BIO_push/#see-also","title":"SEE ALSO","text":"

bio(7)

"},{"location":"man3/BIO_push/#history","title":"HISTORY","text":"

The BIO_set_next() function was added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_push/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_read/","title":"BIO_read","text":""},{"location":"man3/BIO_read/#name","title":"NAME","text":"

BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_get_line, BIO_puts - BIO I/O functions

"},{"location":"man3/BIO_read/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes);\nint BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written);\n\nint BIO_read(BIO *b, void *data, int dlen);\nint BIO_gets(BIO *b, char *buf, int size);\nint BIO_get_line(BIO *b, char *buf, int size);\nint BIO_write(BIO *b, const void *data, int dlen);\nint BIO_puts(BIO *b, const char *buf);\n
"},{"location":"man3/BIO_read/#description","title":"DESCRIPTION","text":"

BIO_read_ex() attempts to read dlen bytes from BIO b and places the data in data. If any bytes were successfully read then the number of bytes read is stored in *readbytes.

BIO_write_ex() attempts to write dlen bytes from data to BIO b. If successful then the number of bytes written is stored in *written unless written is NULL.

BIO_read() attempts to read len bytes from BIO b and places the data in buf.

BIO_gets() performs the BIOs \"gets\" operation and places the data in buf. Usually this operation will attempt to read a line of data from the BIO of maximum length size-1. There are exceptions to this, however; for example, BIO_gets() on a digest BIO will calculate and return the digest and other BIOs may not support BIO_gets() at all. The returned string is always NUL-terminated and the '\\n' is preserved if present in the input data. On binary input there may be NUL characters within the string; in this case the return value (if nonnegative) may give an incorrect length.

BIO_get_line() attempts to read from BIO b a line of data up to the next '\\n' or the maximum length size-1 is reached and places the data in buf. The returned string is always NUL-terminated and the '\\n' is preserved if present in the input data. On binary input there may be NUL characters within the string; in this case the return value (if nonnegative) gives the actual length read. For implementing this, unfortunately the data needs to be read byte-by-byte.

BIO_write() attempts to write len bytes from buf to BIO b.

BIO_puts() attempts to write a NUL-terminated string buf to BIO b.

"},{"location":"man3/BIO_read/#return-values","title":"RETURN VALUES","text":"

BIO_read_ex() returns 1 if data was successfully read, and 0 otherwise.

BIO_write_ex() returns 1 if no error was encountered writing data, 0 otherwise. Requesting to write 0 bytes is not considered an error.

BIO_write() returns -2 if the \"write\" operation is not implemented by the BIO or -1 on other errors. Otherwise it returns the number of bytes written. This may be 0 if the BIO b is NULL or dlen <= 0.

BIO_gets() returns -2 if the \"gets\" operation is not implemented by the BIO or -1 on other errors. Otherwise it typically returns the amount of data read, but depending on the implementation it may return only the length up to the first NUL character contained in the data read. In any case the trailing NUL that is added after the data read is not included in the length returned.

All other functions return either the amount of data successfully read or written (if the return value is positive) or that no data was successfully read or written if the result is 0 or -1. If the return value is -2 then the operation is not implemented in the specific BIO type.

"},{"location":"man3/BIO_read/#notes","title":"NOTES","text":"

A 0 or -1 return is not necessarily an indication of an error. In particular when the source/sink is nonblocking or of a certain type it may merely be an indication that no data is currently available and that the application should retry the operation later.

One technique sometimes used with blocking sockets is to use a system call (such as select(), poll() or equivalent) to determine when data is available and then call read() to read the data. The equivalent with BIOs (that is call select() on the underlying I/O structure and then call BIO_read() to read the data) should not be used because a single call to BIO_read() can cause several reads (and writes in the case of SSL BIOs) on the underlying I/O structure and may block as a result. Instead select() (or equivalent) should be combined with non blocking I/O so successive reads will request a retry instead of blocking.

See BIO_should_retry(3) for details of how to determine the cause of a retry and other I/O issues.

If the \"gets\" method is not supported by a BIO then BIO_get_line() can be used. It is also possible to make BIO_gets() usable even if the \"gets\" method is not supported by adding a buffering BIO BIO_f_buffer(3) to the chain.

"},{"location":"man3/BIO_read/#see-also","title":"SEE ALSO","text":"

BIO_should_retry(3)

"},{"location":"man3/BIO_read/#history","title":"HISTORY","text":"

BIO_gets() on 1.1.0 and older when called on BIO_fd() based BIO did not keep the '\\n' at the end of the line in the buffer.

BIO_get_line() was added in OpenSSL 3.0.

BIO_write_ex() returns 1 if the size of the data to write is 0 and the written parameter of the function can be NULL since OpenSSL 3.0.

"},{"location":"man3/BIO_read/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_accept/","title":"BIO_s_accept","text":""},{"location":"man3/BIO_s_accept/#name","title":"NAME","text":"

BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_accept, BIO_set_accept_bios, BIO_get_peer_name, BIO_get_peer_port, BIO_get_accept_ip_family, BIO_set_accept_ip_family, BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO

"},{"location":"man3/BIO_s_accept/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_accept(void);\n\nlong BIO_set_accept_name(BIO *b, char *name);\nchar *BIO_get_accept_name(BIO *b);\n\nlong BIO_set_accept_port(BIO *b, char *port);\nchar *BIO_get_accept_port(BIO *b);\n\nBIO *BIO_new_accept(char *host_port);\n\nlong BIO_set_nbio_accept(BIO *b, int n);\nlong BIO_set_tfo_accept(BIO *b, int n);\nlong BIO_set_accept_bios(BIO *b, char *bio);\n\nchar *BIO_get_peer_name(BIO *b);\nchar *BIO_get_peer_port(BIO *b);\nlong BIO_get_accept_ip_family(BIO *b);\nlong BIO_set_accept_ip_family(BIO *b, long family);\n\nlong BIO_set_bind_mode(BIO *b, long mode);\nlong BIO_get_bind_mode(BIO *b);\n\nint BIO_do_accept(BIO *b);\n
"},{"location":"man3/BIO_s_accept/#description","title":"DESCRIPTION","text":"

BIO_s_accept() returns the accept BIO method. This is a wrapper round the platform's TCP/IP socket accept routines.

Using accept BIOs, TCP/IP connections can be accepted and data transferred using only BIO routines. In this way any platform specific operations are hidden by the BIO abstraction.

Read and write operations on an accept BIO will perform I/O on the underlying connection. If no connection is established and the port (see below) is set up properly then the BIO waits for an incoming connection.

Accept BIOs support BIO_puts() but not BIO_gets().

If the close flag is set on an accept BIO then any active connection on that chain is shutdown and the socket closed when the BIO is freed.

Calling BIO_reset() on an accept BIO will close any active connection and reset the BIO into a state where it awaits another incoming connection.

BIO_get_fd() and BIO_set_fd() can be called to retrieve or set the accept socket. See BIO_s_fd(3)

BIO_set_accept_name() uses the string name to set the accept name. The name is represented as a string of the form \"host:port\", where \"host\" is the interface to use and \"port\" is the port. The host can be \"*\" or empty which is interpreted as meaning any interface. If the host is an IPv6 address, it has to be enclosed in brackets, for example \"[::1]:https\". \"port\" has the same syntax as the port specified in BIO_set_conn_port() for connect BIOs, that is it can be a numerical port string or a string to lookup using getservbyname() and a string table.

BIO_set_accept_port() uses the string port to set the accept port of BIO b. \"port\" has the same syntax as the port specified in BIO_set_conn_port() for connect BIOs, that is it can be a numerical port string or a string to lookup using getservbyname() and a string table. If the given port is 0 then a random available port is chosen. It may be queried using BIO_sock_info() and BIO_ADDR_service_string(3).

BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into a single call: that is it creates a new accept BIO with port host_port.

BIO_set_nbio_accept() sets the accept socket to blocking mode (the default) if n is 0 or non blocking mode if n is 1.

BIO_set_tfo_accept() enables TCP Fast Open on the accept socket if n is 1 or disables TCP Fast Open if n is 0 (the default). Setting the value to 1 is equivalent to setting BIO_SOCK_TFO in BIO_set_bind_mode().

BIO_set_accept_bios() can be used to set a chain of BIOs which will be duplicated and prepended to the chain when an incoming connection is received. This is useful if, for example, a buffering or SSL BIO is required for each connection. The chain of BIOs must not be freed after this call, they will be automatically freed when the accept BIO is freed.

BIO_get_accept_ip_family() returns the IP family accepted by the BIO b, which may be BIO_FAMILY_IPV4, BIO_FAMILY_IPV6, or BIO_FAMILY_IPANY.

BIO_set_accept_ip_family() sets the IP family family accepted by BIO b. The default is BIO_FAMILY_IPANY.

BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve the current bind mode. If BIO_BIND_NORMAL (the default) is set then another socket cannot be bound to the same port. If BIO_BIND_REUSEADDR is set then other sockets can bind to the same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and attempt is first made to use BIO_BIN_NORMAL, if this fails and the port is not in use then a second attempt is made using BIO_BIND_REUSEADDR. If BIO_SOCK_TFO is set, then the socket will be configured to accept TCP Fast Open connections.

BIO_do_accept() serves two functions. When it is first called, after the accept BIO has been setup, it will attempt to create the accept socket and bind an address to it. Second and subsequent calls to BIO_do_accept() will await an incoming connection, or request a retry in non blocking mode.

"},{"location":"man3/BIO_s_accept/#notes","title":"NOTES","text":"

When an accept BIO is at the end of a chain it will await an incoming connection before processing I/O calls. When an accept BIO is not at then end of a chain it passes I/O calls to the next BIO in the chain.

When a connection is established a new socket BIO is created for the connection and appended to the chain. That is the chain is now accept->socket. This effectively means that attempting I/O on an initial accept socket will await an incoming connection then perform I/O on it.

If any additional BIOs have been set using BIO_set_accept_bios() then they are placed between the socket and the accept BIO, that is the chain will be accept->otherbios->socket.

If a server wishes to process multiple connections (as is normally the case) then the accept BIO must be made available for further incoming connections. This can be done by waiting for a connection and then calling:

connection = BIO_pop(accept);\n

After this call connection will contain a BIO for the recently established connection and accept will now be a single BIO again which can be used to await further incoming connections. If no further connections will be accepted the accept can be freed using BIO_free().

If only a single connection will be processed it is possible to perform I/O using the accept BIO itself. This is often undesirable however because the accept BIO will still accept additional incoming connections. This can be resolved by using BIO_pop() (see above) and freeing up the accept BIO after the initial connection.

If the underlying accept socket is nonblocking and BIO_do_accept() is called to await an incoming connection it is possible for BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens then it is an indication that an accept attempt would block: the application should take appropriate action to wait until the underlying socket has accepted a connection and retry the call.

BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_get_peer_name(), BIO_get_peer_port(), BIO_get_accept_ip_family(), BIO_set_accept_ip_family(), BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.

"},{"location":"man3/BIO_s_accept/#return-values","title":"RETURN VALUES","text":"

BIO_do_accept(), BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_set_accept_ip_family(), and BIO_set_bind_mode() return 1 for success and <=0 for failure.

BIO_get_accept_name() returns the accept name or NULL on error. BIO_get_peer_name() returns the peer name or NULL on error.

BIO_get_accept_port() returns the accept port as a string or NULL on error. BIO_get_peer_port() returns the peer port as a string or NULL on error. BIO_get_accept_ip_family() returns the IP family or <=0 on error.

BIO_get_bind_mode() returns the set of BIO_BIND flags, or <=0 on failure.

BIO_new_accept() returns a BIO or NULL on error.

"},{"location":"man3/BIO_s_accept/#examples","title":"EXAMPLES","text":"

This example accepts two connections on port 4444, sends messages down each and finally closes both down.

BIO *abio, *cbio, *cbio2;\n\n/* First call to BIO_do_accept() sets up accept BIO */\nabio = BIO_new_accept(\"4444\");\nif (BIO_do_accept(abio) <= 0) {\n    fprintf(stderr, \"Error setting up accept\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n\n/* Wait for incoming connection */\nif (BIO_do_accept(abio) <= 0) {\n    fprintf(stderr, \"Error accepting connection\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\nfprintf(stderr, \"Connection 1 established\\n\");\n\n/* Retrieve BIO for connection */\ncbio = BIO_pop(abio);\nBIO_puts(cbio, \"Connection 1: Sending out Data on initial connection\\n\");\nfprintf(stderr, \"Sent out data on connection 1\\n\");\n\n/* Wait for another connection */\nif (BIO_do_accept(abio) <= 0) {\n    fprintf(stderr, \"Error accepting connection\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\nfprintf(stderr, \"Connection 2 established\\n\");\n\n/* Close accept BIO to refuse further connections */\ncbio2 = BIO_pop(abio);\nBIO_free(abio);\nBIO_puts(cbio2, \"Connection 2: Sending out Data on second\\n\");\nfprintf(stderr, \"Sent out data on connection 2\\n\");\n\nBIO_puts(cbio, \"Connection 1: Second connection established\\n\");\n\n/* Close the two established connections */\nBIO_free(cbio);\nBIO_free(cbio2);\n
"},{"location":"man3/BIO_s_accept/#history","title":"HISTORY","text":"

BIO_set_tfo_accept() was added in OpenSSL 3.2.

"},{"location":"man3/BIO_s_accept/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_bio/","title":"BIO_s_bio","text":""},{"location":"man3/BIO_s_bio/#name","title":"NAME","text":"

BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO

"},{"location":"man3/BIO_s_bio/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_bio(void);\n\nint BIO_make_bio_pair(BIO *b1, BIO *b2);\nint BIO_destroy_bio_pair(BIO *b);\nint BIO_shutdown_wr(BIO *b);\n\nint BIO_set_write_buf_size(BIO *b, long size);\nsize_t BIO_get_write_buf_size(BIO *b, long size);\n\nint BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);\n\nint BIO_get_write_guarantee(BIO *b);\nsize_t BIO_ctrl_get_write_guarantee(BIO *b);\nint BIO_get_read_request(BIO *b);\nsize_t BIO_ctrl_get_read_request(BIO *b);\nint BIO_ctrl_reset_read_request(BIO *b);\n
"},{"location":"man3/BIO_s_bio/#description","title":"DESCRIPTION","text":"

BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink BIOs where data written to either half of the pair is buffered and can be read from the other half. Both halves must usually by handled by the same application thread since no locking is done on the internal data structures.

Since BIO chains typically end in a source/sink BIO it is possible to make this one half of a BIO pair and have all the data processed by the chain under application control.

One typical use of BIO pairs is to place TLS/SSL I/O under application control, this can be used when the application wishes to use a non standard transport for TLS/SSL or the normal socket routines are inappropriate.

Calls to BIO_read_ex() will read data from the buffer or request a retry if no data is available.

Calls to BIO_write_ex() will place data in the buffer or request a retry if the buffer is full.

The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to determine the amount of pending data in the read or write buffer.

BIO_reset() clears any data in the write buffer.

BIO_make_bio_pair() joins two separate BIOs into a connected pair.

BIO_destroy_pair() destroys the association between two connected BIOs. Freeing up any half of the pair will automatically destroy the association.

BIO_shutdown_wr() is used to close down a BIO b. After this call no further writes on BIO b are allowed (they will return an error). Reads on the other half of the pair will return any pending data or EOF when all pending data has been read.

BIO_set_write_buf_size() sets the write buffer size of BIO b to size. If the size is not initialized a default value is used. This is currently 17K, sufficient for a maximum size TLS record.

BIO_get_write_buf_size() returns the size of the write buffer.

BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and BIO_set_write_buf_size() to create a connected pair of BIOs bio1, bio2 with write buffer sizes writebuf1 and writebuf2. If either size is zero then the default size is used. BIO_new_bio_pair() does not check whether bio1 or bio2 do point to some other BIO, the values are overwritten, BIO_free() is not called.

BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum length of data that can be currently written to the BIO. Writes larger than this value will return a value from BIO_write_ex() less than the amount requested or if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function whereas BIO_get_write_guarantee() is a macro.

BIO_get_read_request() and BIO_ctrl_get_read_request() return the amount of data requested, or the buffer size if it is less, if the last read attempt at the other half of the BIO pair failed due to an empty buffer. This can be used to determine how much data should be written to the BIO so the next read will succeed: this is most useful in TLS/SSL applications where the amount of data read is usually meaningful rather than just a buffer size. After a successful read this call will return zero. It also will return zero once new data has been written satisfying the read request or part of it. Note that BIO_get_read_request() never returns an amount larger than that returned by BIO_get_write_guarantee().

BIO_ctrl_reset_read_request() can also be used to reset the value returned by BIO_get_read_request() to zero.

"},{"location":"man3/BIO_s_bio/#notes","title":"NOTES","text":"

Both halves of a BIO pair should be freed. That is even if one half is implicit freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.

When used in bidirectional applications (such as TLS/SSL) care should be taken to flush any data in the write buffer. This can be done by calling BIO_pending() on the other half of the pair and, if any data is pending, reading it and sending it to the underlying transport. This must be done before any normal processing (such as calling select() ) due to a request and BIO_should_read() being true.

To see why this is important consider a case where a request is sent using BIO_write_ex() and a response read with BIO_read_ex(), this can occur during an TLS/SSL handshake for example. BIO_write_ex() will succeed and place data in the write buffer. BIO_read_ex() will initially fail and BIO_should_read() will be true. If the application then waits for data to be available on the underlying transport before flushing the write buffer it will never succeed because the request was never sent!

BIO_eof() is true if no data is in the peer BIO and the peer BIO has been shutdown.

BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), BIO_set_write_buf_size(), BIO_get_write_buf_size(), BIO_get_write_guarantee(), and BIO_get_read_request() are implemented as macros.

"},{"location":"man3/BIO_s_bio/#return-values","title":"RETURN VALUES","text":"

BIO_new_bio_pair() returns 1 on success, with the new BIOs available in bio1 and bio2, or 0 on failure, with NULL pointers stored into the locations for bio1 and bio2. Check the error stack for more information.

[XXXXX: More return values need to be added here]

"},{"location":"man3/BIO_s_bio/#examples","title":"EXAMPLES","text":"

The BIO pair can be used to have full control over the network access of an application. The application can call select() on the socket as required without having to go through the SSL-interface.

BIO *internal_bio, *network_bio;\n\n...\nBIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);\nSSL_set_bio(ssl, internal_bio, internal_bio);\nSSL_operations(); /* e.g. SSL_read and SSL_write */\n...\n\napplication |   TLS-engine\n   |        |\n   +----------> SSL_operations()\n            |     /\\    ||\n            |     ||    \\/\n            |   BIO-pair (internal_bio)\n            |   BIO-pair (network_bio)\n            |     ||     /\\\n            |     \\/     ||\n   +-----------< BIO_operations()\n   |        |\n   |        |\n  socket\n\n ...\n SSL_free(ssl);                /* implicitly frees internal_bio */\n BIO_free(network_bio);\n ...\n

As the BIO pair will only buffer the data and never directly access the connection, it behaves nonblocking and will return as soon as the write buffer is full or the read buffer is drained. Then the application has to flush the write buffer and/or fill the read buffer.

Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO and must be transferred to the network. Use BIO_ctrl_get_read_request() to find out, how many bytes must be written into the buffer before the SSL_operation() can successfully be continued.

"},{"location":"man3/BIO_s_bio/#warnings","title":"WARNINGS","text":"

As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ condition, but there is still data in the write buffer. An application must not rely on the error value of SSL_operation() but must assure that the write buffer is always flushed first. Otherwise a deadlock may occur as the peer might be waiting for the data before being able to continue.

"},{"location":"man3/BIO_s_bio/#see-also","title":"SEE ALSO","text":"

SSL_set_bio(3), ssl(7), bio(7), BIO_should_retry(3), BIO_read_ex(3)

"},{"location":"man3/BIO_s_bio/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_connect/","title":"BIO_s_connect","text":""},{"location":"man3/BIO_s_connect/#name","title":"NAME","text":"

BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_address, BIO_set_conn_ip_family, BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_address, BIO_get_conn_ip_family, BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get0_dgram_bio, BIO_do_connect - connect BIO

"},{"location":"man3/BIO_s_connect/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_connect(void);\n\nBIO *BIO_new_connect(const char *name);\n\nlong BIO_set_conn_hostname(BIO *b, char *name);\nlong BIO_set_conn_port(BIO *b, char *port);\nlong BIO_set_conn_address(BIO *b, BIO_ADDR *addr);\nlong BIO_set_conn_ip_family(BIO *b, long family);\nconst char *BIO_get_conn_hostname(BIO *b);\nconst char *BIO_get_conn_port(BIO *b);\nconst BIO_ADDR *BIO_get_conn_address(BIO *b);\nconst long BIO_get_conn_ip_family(BIO *b);\n\nlong BIO_set_nbio(BIO *b, long n);\n\nint BIO_set_sock_type(BIO *b, int sock_type);\nint BIO_get_sock_type(BIO *b);\nint BIO_get0_dgram_bio(BIO *B, BIO **dgram_bio);\n\nlong BIO_do_connect(BIO *b);\n
"},{"location":"man3/BIO_s_connect/#description","title":"DESCRIPTION","text":"

BIO_s_connect() returns the connect BIO method. This is a wrapper round the platform's TCP/IP socket connection routines.

Using connect BIOs, TCP/IP connections can be made and data transferred using only BIO routines. In this way any platform specific operations are hidden by the BIO abstraction.

Read and write operations on a connect BIO will perform I/O on the underlying connection. If no connection is established and the port and hostname (see below) is set up properly then a connection is established first.

Connect BIOs support BIO_puts() and BIO_gets().

If the close flag is set on a connect BIO then any active connection is shutdown and the socket closed when the BIO is freed.

Calling BIO_reset() on a connect BIO will close any active connection and reset the BIO into a state where it can connect to the same host again.

BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into a single call: that is it creates a new connect BIO with hostname name.

BIO_set_conn_hostname() uses the string name to set the hostname. The hostname can be an IP address; if the address is an IPv6 one, it must be enclosed with brackets [ and ]. The hostname can also include the port in the form hostname:port; see BIO_parse_hostserv(3) and BIO_set_conn_port() for details.

BIO_set_conn_port() sets the port to port. port can be the numerical form or a service string such as \"http\", which will be mapped to a port number using the system function getservbyname().

BIO_set_conn_address() sets the address and port information using a BIO_ADDR(3ssl).

BIO_set_conn_ip_family() sets the IP family.

BIO_get_conn_hostname() returns the hostname of the connect BIO or NULL if the BIO is initialized but no hostname is set. This return value is an internal pointer which should not be modified.

BIO_get_conn_port() returns the port as a string. This return value is an internal pointer which should not be modified.

BIO_get_conn_address() returns the address information as a BIO_ADDR. This return value is an internal pointer which should not be modified.

BIO_get_conn_ip_family() returns the IP family of the connect BIO.

BIO_set_nbio() sets the non blocking I/O flag to n. If n is zero then blocking I/O is set. If n is 1 then non blocking I/O is set. Blocking I/O is the default. The call to BIO_set_nbio() should be made before the connection is established because non blocking I/O is set during the connect process.

BIO_do_connect() attempts to connect the supplied BIO. This performs an SSL/TLS handshake as far as supported by the BIO. For non-SSL BIOs the connection is done typically at TCP level. If domain name resolution yields multiple IP addresses all of them are tried after connect() failures. The function returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established. The call BIO_should_retry() should be used for non blocking connect BIOs to determine if the call should be retried. If a connection has already been established this call has no effect.

BIO_set_sock_type() can be used to set a socket type value as would be passed in a call to socket(2). The only currently supported values are SOCK_STREAM (the default) and SOCK_DGRAM. If SOCK_DGRAM is configured, the connection created is a UDP datagram socket handled via BIO_s_datagram(3). I/O calls such as BIO_read(3) and BIO_write(3) are forwarded transparently to an internal BIO_s_datagram(3) instance. The created BIO_s_datagram(3) instance can be retrieved using BIO_get0_dgram_bio() if desired, which writes a pointer to the BIO_s_datagram(3) instance to *dgram_bio. The lifetime of the internal BIO_s_datagram(3) is managed by BIO_s_connect() and does not need to be freed by the caller.

BIO_get_sock_type() retrieves the value set using BIO_set_sock_type().

"},{"location":"man3/BIO_s_connect/#notes","title":"NOTES","text":"

If blocking I/O is set then a non positive return value from any I/O call is caused by an error condition, although a zero return will normally mean that the connection was closed.

If the port name is supplied as part of the hostname then this will override any value set with BIO_set_conn_port(). This may be undesirable if the application does not wish to allow connection to arbitrary ports. This can be avoided by checking for the presence of the ':' character in the passed hostname and either indicating an error or truncating the string at that point.

The values returned by BIO_get_conn_hostname(), BIO_get_conn_address(), and BIO_get_conn_port() are updated when a connection attempt is made. Before any connection attempt the values returned are those set by the application itself.

Applications do not have to call BIO_do_connect() but may wish to do so to separate the connection process from other I/O processing.

If non blocking I/O is set then retries will be requested as appropriate.

It addition to BIO_should_read() and BIO_should_write() it is also possible for BIO_should_io_special() to be true during the initial connection process with the reason BIO_RR_CONNECT. If this is returned then this is an indication that a connection attempt would block, the application should then take appropriate action to wait until the underlying socket has connected and retry the call.

BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_get_conn_hostname(), BIO_set_conn_address(), BIO_get_conn_port(), BIO_get_conn_address(), BIO_set_conn_ip_family(), BIO_get_conn_ip_family(), BIO_set_nbio(), and BIO_do_connect() are macros.

"},{"location":"man3/BIO_s_connect/#return-values","title":"RETURN VALUES","text":"

BIO_s_connect() returns the connect BIO method.

BIO_set_conn_address(), BIO_set_conn_port(), and BIO_set_conn_ip_family() return 1 or <=0 if an error occurs.

BIO_set_conn_hostname() returns 1 on success and <=0 on failure.

BIO_get_conn_address() returns the address information or NULL if none was set.

BIO_get_conn_hostname() returns the connected hostname or NULL if none was set.

BIO_get_conn_ip_family() returns the address family or -1 if none was set.

BIO_get_conn_port() returns a string representing the connected port or NULL if not set.

BIO_set_nbio() returns 1 or <=0 if an error occurs.

BIO_do_connect() returns 1 if the connection was successfully established and <=0 if the connection failed.

BIO_set_sock_type() returns 1 on success or 0 on failure.

BIO_get_sock_type() returns a socket type or 0 if the call is not supported.

BIO_get0_dgram_bio() returns 1 on success or 0 on failure.

"},{"location":"man3/BIO_s_connect/#examples","title":"EXAMPLES","text":"

This is example connects to a webserver on the local host and attempts to retrieve a page and copy the result to standard output.

BIO *cbio, *out;\nint len;\nchar tmpbuf[1024];\n\ncbio = BIO_new_connect(\"localhost:http\");\nout = BIO_new_fp(stdout, BIO_NOCLOSE);\nif (BIO_do_connect(cbio) <= 0) {\n    fprintf(stderr, \"Error connecting to server\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\nBIO_puts(cbio, \"GET / HTTP/1.0\\n\\n\");\nfor (;;) {\n    len = BIO_read(cbio, tmpbuf, 1024);\n    if (len <= 0)\n        break;\n    BIO_write(out, tmpbuf, len);\n}\nBIO_free(cbio);\nBIO_free(out);\n
"},{"location":"man3/BIO_s_connect/#see-also","title":"SEE ALSO","text":"

BIO_ADDR(3), BIO_parse_hostserv(3)

"},{"location":"man3/BIO_s_connect/#history","title":"HISTORY","text":"

BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(), and BIO_get_conn_ip() were removed in OpenSSL 1.1.0. Use BIO_set_conn_address() and BIO_get_conn_address() instead.

Connect BIOs support BIO_gets() since OpenSSL 3.2.

"},{"location":"man3/BIO_s_connect/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_core/","title":"BIO_s_core","text":""},{"location":"man3/BIO_s_core/#name","title":"NAME","text":"

BIO_s_core, BIO_new_from_core_bio - OSSL_CORE_BIO functions

"},{"location":"man3/BIO_s_core/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_core(void);\n\nBIO *BIO_new_from_core_bio(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio);\n
"},{"location":"man3/BIO_s_core/#description","title":"DESCRIPTION","text":"

BIO_s_core() returns the core BIO method function.

A core BIO is treated as source/sink BIO which communicates to some external BIO. This is primarily useful to provider authors. A number of calls from libcrypto into a provider supply an OSSL_CORE_BIO parameter. This represents a BIO within libcrypto, but cannot be used directly by a provider. Instead it should be wrapped using a BIO_s_core().

Once a BIO is constructed based on BIO_s_core(), the associated OSSL_CORE_BIO object should be set on it using BIO_set_data(3). Note that the BIO will only operate correctly if it is associated with a library context constructed using OSSL_LIB_CTX_new_from_dispatch(3). To associate the BIO with a library context construct it using BIO_new_ex(3).

BIO_new_from_core_bio() is a convenience function that constructs a new BIO based on BIO_s_core() and that is associated with the given library context. It then also sets the OSSL_CORE_BIO object on the BIO using BIO_set_data(3).

"},{"location":"man3/BIO_s_core/#return-values","title":"RETURN VALUES","text":"

BIO_s_core() return a core BIO BIO_METHOD structure.

BIO_new_from_core_bio() returns a BIO structure on success or NULL on failure. A failure will most commonly be because the library context was not constructed using OSSL_LIB_CTX_new_from_dispatch(3).

"},{"location":"man3/BIO_s_core/#history","title":"HISTORY","text":"

BIO_s_core() and BIO_new_from_core_bio() were added in OpenSSL 3.0.

"},{"location":"man3/BIO_s_core/#examples","title":"EXAMPLES","text":"

Create a core BIO and write some data to it:

int some_function(OSSL_LIB_CTX *libctx, OSSL_CORE_BIO *corebio) {\n    BIO *cbio = BIO_new_from_core_bio(libctx, corebio);\n\n    if (cbio == NULL)\n        return 0;\n\n    BIO_puts(cbio, \"Hello World\\n\");\n\n    BIO_free(cbio);\n    return 1;\n}\n
"},{"location":"man3/BIO_s_core/#copyright","title":"COPYRIGHT","text":"

Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_datagram/","title":"BIO_s_datagram","text":""},{"location":"man3/BIO_s_datagram/#name","title":"NAME","text":"

BIO_s_datagram, BIO_new_dgram, BIO_ctrl_dgram_connect, BIO_ctrl_set_connected, BIO_dgram_recv_timedout, BIO_dgram_send_timedout, BIO_dgram_get_peer, BIO_dgram_set_peer, BIO_dgram_detect_peer_addr, BIO_dgram_get_mtu_overhead - Network BIO with datagram semantics

"},{"location":"man3/BIO_s_datagram/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nBIO_METHOD *BIO_s_datagram(void);\nBIO *BIO_new_dgram(int fd, int close_flag);\n\nint BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer);\nint BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer);\nint BIO_dgram_recv_timedout(BIO *bio);\nint BIO_dgram_send_timedout(BIO *bio);\nint BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer);\nint BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer);\nint BIO_dgram_get_mtu_overhead(BIO *bio);\nint BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer);\n
"},{"location":"man3/BIO_s_datagram/#description","title":"DESCRIPTION","text":"

BIO_s_datagram() is a BIO implementation designed for use with network sockets which provide datagram semantics, such as UDP sockets. It is suitable for use with DTLSv1 or QUIC.

Because BIO_s_datagram() has datagram semantics, a single BIO_write() call sends a single datagram and a single BIO_read() call receives a single datagram. If the size of the buffer passed to BIO_read() is inadequate, the datagram is silently truncated.

For a memory-based BIO which provides datagram semantics identical to those of BIO_s_datagram(), see BIO_s_dgram_pair(3).

This BIO supports the BIO_sendmmsg(3) and BIO_recvmmsg(3) functions.

When using BIO_s_datagram(), it is important to note that:

Various controls are available for configuring the BIO_s_datagram() using BIO_ctrl(3):

BIO_new_dgram() is a helper function which instantiates a BIO_s_datagram() and sets the BIO to use the socket given in fd by calling BIO_set_fd().

"},{"location":"man3/BIO_s_datagram/#return-values","title":"RETURN VALUES","text":"

BIO_s_datagram() returns a BIO method.

BIO_new_dgram() returns a BIO on success and NULL on failure.

BIO_ctrl_dgram_connect(), BIO_ctrl_set_connected() and BIO_dgram_set_peer() return 1 on success and 0 on failure.

BIO_dgram_get_peer() and BIO_dgram_detect_peer_addr() return 0 on failure and the number of bytes for the outputted address representation (a positive value) on success.

BIO_dgram_recv_timedout() and BIO_dgram_send_timedout() return 0 or 1 depending on the circumstance; see discussion above.

BIO_dgram_get_mtu_overhead() returns a value in bytes.

"},{"location":"man3/BIO_s_datagram/#see-also","title":"SEE ALSO","text":"

BIO_sendmmsg(3), BIO_s_dgram_pair(3), DTLSv1_listen(3), bio(7)

"},{"location":"man3/BIO_s_datagram/#copyright","title":"COPYRIGHT","text":"

Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_dgram_pair/","title":"BIO_s_dgram_pair","text":""},{"location":"man3/BIO_s_dgram_pair/#name","title":"NAME","text":"

BIO_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps, BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu - datagram pair BIO

"},{"location":"man3/BIO_s_dgram_pair/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_dgram_pair(void);\n\nint BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1,\n                           BIO **bio2, size_t writebuf2);\nint BIO_dgram_set_no_trunc(BIO *bio, int enable);\nint BIO_dgram_get_no_trunc(BIO *bio);\nuint32_t BIO_dgram_get_effective_caps(BIO *bio);\nuint32_t BIO_dgram_get_caps(BIO *bio);\nint BIO_dgram_set_caps(BIO *bio, uint32_t caps);\nint BIO_dgram_set_mtu(BIO *bio, unsigned int mtu);\nunsigned int BIO_dgram_get_mtu(BIO *bio);\n
"},{"location":"man3/BIO_s_dgram_pair/#description","title":"DESCRIPTION","text":"

BIO_s_dgram_pair() returns the method for a BIO datagram pair. A BIO datagram pair is similar to a BIO pair (see BIO_s_bio(3)) but has datagram semantics. Broadly, this means that the length of the buffer passed to a write call will match that retrieved by a read call. If the buffer passed to a read call is too short, the datagram is truncated or the read fails, depending on how the BIO is configured.

The BIO datagram pair attaches certain metadata to each write, such as source and destination addresses. This information may be retrieved on read.

A typical application of a BIO datagram pair is to allow an application to keep all datagram network I/O requested by libssl under application control.

The BIO datagram pair is designed to support multithreaded use where certain restrictions are observed; see THREADING.

The BIO datagram pair allows each half of a pair to signal to the other half whether they support certain capabilities; see CAPABILITY INDICATION.

BIO_new_bio_dgram_pair() combines the calls to BIO_new(3), BIO_make_bio_pair(3) and BIO_set_write_buf_size(3) to create a connected pair of BIOs bio1, bio2 with write buffer sizes writebuf1 and writebuf2. If either size is zero then the default size is used.

BIO_make_bio_pair(3) may be used to join two datagram pair BIOs into a pair. The two BIOs must both use the method returned by BIO_s_dgram_pair() and neither of the BIOs may currently be associated in a pair.

BIO_destroy_bio_pair(3) destroys the association between two connected BIOs. Freeing either half of the pair will automatically destroy the association.

BIO_reset(3) clears any data in the write buffer of the given BIO. This means that the opposite BIO in the pair will no longer have any data waiting to be read.

The BIO maintains a fixed size internal write buffer. When the buffer is full, further writes will fail until the buffer is drained via calls to BIO_read(3). The size of the buffer can be changed using BIO_set_write_buf_size(3) and queried using BIO_get_write_buf_size(3).

Note that the write buffer is partially consumed by metadata stored internally which is attached to each datagram, such as source and destination addresses. The size of this overhead is undefined and may change between releases.

The standard BIO_ctrl_pending(3) call has modified behaviour and returns the size of the next datagram waiting to be read in bytes. An application can use this function to ensure it provides an adequate buffer to a subsequent read call. If no datagram is waiting to be read, zero is returned.

This BIO does not support sending or receiving zero-length datagrams. Passing a zero-length buffer to BIO_write is treated as a no-op.

BIO_eof(3) returns 1 only if the given BIO datagram pair BIO is not currently connected to a peer BIO.

BIO_get_write_guarantee(3) and BIO_ctrl_get_write_guarantee(3) return how large a datagram the next call to BIO_write(3) can accept. If there is not enough space in the write buffer to accept another datagram equal in size to the configured MTU, zero is returned (see below). This is intended to avoid a situation where an application attempts to read a datagram from a network intending to write it to a BIO datagram pair, but where the received datagram ends up being too large to write to the BIO datagram pair.

BIO_dgram_set_no_trunc() and BIO_ctrl_get_no_trunc() set and retrieve the truncation mode for the given half of a BIO datagram pair. When no-truncate mode is enabled, BIO_read() will fail if the buffer provided is inadequate to hold the next datagram to be read. If no-truncate mode is disabled (the default), the datagram will be silently truncated. This default behaviour maintains compatibility with the semantics of the Berkeley sockets API.

BIO_dgram_set_mtu() and BIO_dgram_get_mtu() may be used to set an informational MTU value on the BIO datagram pair. If BIO_dgram_set_mtu() is used on a BIO which is currently part of a BIO datagram pair, the MTU value is set on both halves of the pair. The value does not affect the operation of the BIO datagram pair (except for BIO_get_write_guarantee(); see above) but may be used by other code to determine a requested MTU. When a BIO datagram pair BIO is created, the MTU is set to an unspecified but valid value.

BIO_flush(3) is a no-op.

"},{"location":"man3/BIO_s_dgram_pair/#notes","title":"NOTES","text":"

The halves of a BIO datagram pair have independent lifetimes and must be separately freed.

"},{"location":"man3/BIO_s_dgram_pair/#threading","title":"THREADING","text":"

BIO_recvmmsg(3), BIO_sendmmsg(3), BIO_read(3), BIO_write(3), BIO_pending(3), BIO_get_write_guarantee(3) and BIO_flush(3) may be used by multiple threads simultaneously on the same BIO datagram pair. Specific BIO_ctrl(3) operations (namely BIO_CTRL_PENDING, BIO_CTRL_FLUSH and BIO_C_GET_WRITE_GUARANTEE) may also be used. Invoking any other BIO call, or any other BIO_ctrl(3) operation, on either half of a BIO datagram pair while any other BIO call is also in progress to either half of the same BIO datagram pair results in undefined behaviour.

"},{"location":"man3/BIO_s_dgram_pair/#capability-indication","title":"CAPABILITY INDICATION","text":"

The BIO datagram pair can be used to enqueue datagrams which have source and destination addresses attached. It is important that the component consuming one side of a BIO datagram pair understand whether the other side of the pair will honour any source and destination addresses it attaches to each datagram. For example, if datagrams are queued with destination addresses set but simply read by simple calls to BIO_read(3), the destination addresses will be discarded.

Each half of a BIO datagram pair can have capability flags set on it which indicate whether source and destination addresses will be honoured by the reader and whether they will be provided by the writer. These capability flags should be set via a call to BIO_dgram_set_caps(), and these capabilities will be reflected in the value returned by BIO_dgram_get_effective_caps() on the opposite BIO. If necessary, the capability value previously set can be retrieved using BIO_dgram_get_caps(). Note that BIO_dgram_set_caps() on a given BIO controls the capabilities advertised to the peer, and BIO_dgram_get_effective_caps() on a given BIO determines the capabilities advertised by the peer of that BIO.

The following capabilities are available:

If a caller attempts to specify a destination address (for example, using BIO_sendmmsg(3)) and the peer has not advertised the BIO_DGRAM_CAP_HANDLES_DST_ADDR capability, the operation fails. Thus, capability negotiation is mandatory.

If a caller attempts to specify a source address when writing, or requests a destination address when receiving, and local address support has not been enabled, the operation fails; see BIO_dgram_set_local_addr_enable(3).

If a caller attempts to enable local address support using BIO_dgram_set_local_addr_enable(3) and BIO_dgram_get_local_addr_cap(3) does not return 1 (meaning that the peer has not advertised both the BIO_DGRAM_CAP_HANDLES_SRC_ADDR and the BIO_DGRAM_CAP_PROVIDES_DST_ADDR capability), the operation fails.

BIO_DGRAM_CAP_PROVIDES_SRC_ADDR and BIO_DGRAM_CAP_PROVIDES_DST_ADDR indicate that the application using that half of a BIO datagram pair promises to provide source and destination addresses respectively when writing datagrams to that half of the BIO datagram pair. However, these capability flags do not affect the behaviour of the BIO datagram pair.

"},{"location":"man3/BIO_s_dgram_pair/#return-values","title":"RETURN VALUES","text":"

BIO_new_bio_dgram_pair() returns 1 on success, with the new BIOs available in bio1 and bio2, or 0 on failure, with NULL pointers stored into the locations for bio1 and bio2. Check the error stack for more information.

BIO_dgram_set_no_trunc(), BIO_dgram_set_caps() and BIO_dgram_set_mtu() return 1 on success and 0 on failure.

BIO_dgram_get_no_trunc() returns 1 if no-truncate mode is enabled on a BIO, or 0 if no-truncate mode is not enabled or not supported on a given BIO.

BIO_dgram_get_effective_caps() and BIO_dgram_get_caps() return zero if no capabilities are supported.

BIO_dgram_get_mtu() returns the MTU value configured on the BIO, or zero if the operation is not supported.

"},{"location":"man3/BIO_s_dgram_pair/#see-also","title":"SEE ALSO","text":"

BIO_s_bio(3), bio(7)

"},{"location":"man3/BIO_s_dgram_pair/#copyright","title":"COPYRIGHT","text":"

Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_fd/","title":"BIO_s_fd","text":""},{"location":"man3/BIO_s_fd/#name","title":"NAME","text":"

BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO

"},{"location":"man3/BIO_s_fd/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_fd(void);\n\nint BIO_set_fd(BIO *b, int fd, int c);\nint BIO_get_fd(BIO *b, int *c);\n\nBIO *BIO_new_fd(int fd, int close_flag);\n
"},{"location":"man3/BIO_s_fd/#description","title":"DESCRIPTION","text":"

BIO_s_fd() returns the file descriptor BIO method. This is a wrapper round the platforms file descriptor routines such as read() and write().

BIO_read_ex() and BIO_write_ex() read or write the underlying descriptor. BIO_puts() is supported but BIO_gets() is not.

If the close flag is set then close() is called on the underlying file descriptor when the BIO is freed.

BIO_reset() attempts to change the file pointer to the start of file such as by using lseek(fd, 0, 0).

BIO_seek() sets the file pointer to position ofs from start of file such as by using lseek(fd, ofs, 0).

BIO_tell() returns the current file position such as by calling lseek(fd, 0, 1).

BIO_set_fd() sets the file descriptor of BIO b to fd and the close flag to c.

BIO_get_fd() places the file descriptor of BIO b in c if it is not NULL. It also returns the file descriptor.

BIO_new_fd() returns a file descriptor BIO using fd and close_flag.

"},{"location":"man3/BIO_s_fd/#notes","title":"NOTES","text":"

The behaviour of BIO_read_ex() and BIO_write_ex() depends on the behavior of the platforms read() and write() calls on the descriptor. If the underlying file descriptor is in a non blocking mode then the BIO will behave in the manner described in the BIO_read_ex(3) and BIO_should_retry(3) manual pages.

File descriptor BIOs should not be used for socket I/O. Use socket BIOs instead.

BIO_set_fd() and BIO_get_fd() are implemented as macros.

"},{"location":"man3/BIO_s_fd/#return-values","title":"RETURN VALUES","text":"

BIO_s_fd() returns the file descriptor BIO method.

BIO_set_fd() returns 1 on success or <=0 for failure.

BIO_get_fd() returns the file descriptor or -1 if the BIO has not been initialized. It also returns zero and negative values if other error occurs.

BIO_new_fd() returns the newly allocated BIO or NULL is an error occurred.

"},{"location":"man3/BIO_s_fd/#examples","title":"EXAMPLES","text":"

This is a file descriptor BIO version of \"Hello World\":

BIO *out;\n\nout = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);\nBIO_printf(out, \"Hello World\\n\");\nBIO_free(out);\n
"},{"location":"man3/BIO_s_fd/#see-also","title":"SEE ALSO","text":"

BIO_seek(3), BIO_tell(3), BIO_reset(3), BIO_read_ex(3), BIO_write_ex(3), BIO_puts(3), BIO_gets(3), BIO_printf(3), BIO_set_close(3), BIO_get_close(3)

"},{"location":"man3/BIO_s_fd/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_file/","title":"BIO_s_file","text":""},{"location":"man3/BIO_s_file/#name","title":"NAME","text":"

BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, BIO_read_filename, BIO_write_filename, BIO_append_filename, BIO_rw_filename - FILE bio

"},{"location":"man3/BIO_s_file/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_file(void);\nBIO *BIO_new_file(const char *filename, const char *mode);\nBIO *BIO_new_fp(FILE *stream, int flags);\n\nBIO_set_fp(BIO *b, FILE *fp, int flags);\nBIO_get_fp(BIO *b, FILE **fpp);\n\nint BIO_read_filename(BIO *b, char *name);\nint BIO_write_filename(BIO *b, char *name);\nint BIO_append_filename(BIO *b, char *name);\nint BIO_rw_filename(BIO *b, char *name);\n
"},{"location":"man3/BIO_s_file/#description","title":"DESCRIPTION","text":"

BIO_s_file() returns the BIO file method. As its name implies it is a wrapper round the stdio FILE structure and it is a source/sink BIO.

Calls to BIO_read_ex() and BIO_write_ex() read and write data to the underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.

BIO_flush() on a file BIO calls the fflush() function on the wrapped stream.

BIO_reset() attempts to change the file pointer to the start of file using fseek(stream, 0, 0).

BIO_seek() sets the file pointer to position ofs from start of file using fseek(stream, ofs, 0).

BIO_eof() calls feof().

Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO is freed.

BIO_new_file() creates a new file BIO with mode mode the meaning of mode is the same as the stdio function fopen(). The BIO_CLOSE flag is set on the returned BIO.

BIO_new_fp() creates a file BIO wrapping stream. Flags can be: BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying stream to text mode, default is binary: this only has any effect under Win32).

BIO_set_fp() sets the fp of a file BIO to fp. flags has the same meaning as in BIO_new_fp(), it is a macro.

BIO_get_fp() retrieves the fp of a file BIO, it is a macro.

BIO_seek() is a macro that sets the position pointer to offset bytes from the start of file.

BIO_tell() returns the value of the position pointer.

BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() set the file BIO b to use file name for reading, writing, append or read write respectively.

"},{"location":"man3/BIO_s_file/#notes","title":"NOTES","text":"

When wrapping stdout, stdin or stderr the underlying stream should not normally be closed so the BIO_NOCLOSE flag should be set.

Because the file BIO calls the underlying stdio functions any quirks in stdio behaviour will be mirrored by the corresponding BIO.

On Windows BIO_new_files reserves for the filename argument to be UTF-8 encoded. In other words if you have to make it work in multi- lingual environment, encode filenames in UTF-8.

"},{"location":"man3/BIO_s_file/#return-values","title":"RETURN VALUES","text":"

BIO_s_file() returns the file BIO method.

BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error occurred.

BIO_set_fp() and BIO_get_fp() return 1 for success or <=0 for failure (although the current implementation never return 0).

BIO_seek() returns 0 for success or negative values for failure.

BIO_tell() returns the current file position or negative values for failure.

BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() return 1 for success or <=0 for failure.

"},{"location":"man3/BIO_s_file/#examples","title":"EXAMPLES","text":"

File BIO \"hello world\":

BIO *bio_out;\n\nbio_out = BIO_new_fp(stdout, BIO_NOCLOSE);\nBIO_printf(bio_out, \"Hello World\\n\");\n

Alternative technique:

BIO *bio_out;\n\nbio_out = BIO_new(BIO_s_file());\nif (bio_out == NULL)\n    /* Error */\nif (BIO_set_fp(bio_out, stdout, BIO_NOCLOSE) <= 0)\n    /* Error */\nBIO_printf(bio_out, \"Hello World\\n\");\n

Write to a file:

BIO *out;\n\nout = BIO_new_file(\"filename.txt\", \"w\");\nif (!out)\n    /* Error */\nBIO_printf(out, \"Hello World\\n\");\nBIO_free(out);\n

Alternative technique:

BIO *out;\n\nout = BIO_new(BIO_s_file());\nif (out == NULL)\n    /* Error */\nif (BIO_write_filename(out, \"filename.txt\") <= 0)\n    /* Error */\nBIO_printf(out, \"Hello World\\n\");\nBIO_free(out);\n
"},{"location":"man3/BIO_s_file/#bugs","title":"BUGS","text":"

BIO_reset() and BIO_seek() are implemented using fseek() on the underlying stream. The return value for fseek() is 0 for success or -1 if an error occurred this differs from other types of BIO which will typically return 1 for success and a non positive value if an error occurred.

"},{"location":"man3/BIO_s_file/#see-also","title":"SEE ALSO","text":"

BIO_seek(3), BIO_tell(3), BIO_reset(3), BIO_flush(3), BIO_read_ex(3), BIO_write_ex(3), BIO_puts(3), BIO_gets(3), BIO_printf(3), BIO_set_close(3), BIO_get_close(3)

"},{"location":"man3/BIO_s_file/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_mem/","title":"BIO_s_mem","text":""},{"location":"man3/BIO_s_mem/#name","title":"NAME","text":"

BIO_s_secmem, BIO_s_dgram_mem, BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO

"},{"location":"man3/BIO_s_mem/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_mem(void);\nconst BIO_METHOD *BIO_s_dgram_mem(void);\nconst BIO_METHOD *BIO_s_secmem(void);\n\nBIO_set_mem_eof_return(BIO *b, int v);\nlong BIO_get_mem_data(BIO *b, char **pp);\nBIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c);\nBIO_get_mem_ptr(BIO *b, BUF_MEM **pp);\n\nBIO *BIO_new_mem_buf(const void *buf, int len);\n
"},{"location":"man3/BIO_s_mem/#description","title":"DESCRIPTION","text":"

BIO_s_mem() returns the memory BIO method function.

A memory BIO is a source/sink BIO which uses memory for its I/O. Data written to a memory BIO is stored in a BUF_MEM structure which is extended as appropriate to accommodate the stored data.

BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used for buffer storage.

BIO_s_dgram_mem() is a memory BIO that respects datagram semantics. A single call to BIO_write(3) will write a single datagram to the memory BIO. A subsequent call to BIO_read(3) will read the data in that datagram. The BIO_read(3) call will never return more data than was written in the original BIO_write(3) call even if there were subsequent BIO_write(3) calls that wrote more datagrams. Each successive call to BIO_read(3) will read the next datagram. If a BIO_read(3) call supplies a read buffer that is smaller than the size of the datagram, then the read buffer will be completely filled and the remaining data from the datagram will be discarded.

It is not possible to write a zero length datagram. Calling BIO_write(3) in this case will return 0 and no datagrams will be written. Calling BIO_read(3) when there are no datagrams in the BIO to read will return a negative result and the \"retry\" flags will be set (i.e. calling BIO_should_retry(3) will return true). A datagram mem BIO will never return true from BIO_eof(3).

Any data written to a memory BIO can be recalled by reading from it. Unless the memory BIO is read only any data read from it is deleted from the BIO.

Memory BIOs except BIO_s_dgram_mem() support BIO_gets() and BIO_puts().

BIO_s_dgram_mem() supports BIO_sendmmsg(3) and BIO_recvmmsg(3) calls and calls related to BIO_ADDR and MTU handling similarly to the BIO_s_dgram_pair(3).

If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying BUF_MEM structure is also freed.

Calling BIO_reset() on a read write memory BIO clears any data in it if the flag BIO_FLAGS_NONCLEAR_RST is not set, otherwise it just restores the read pointer to the state it was just after the last write was performed and the data can be read again. On a read only BIO it similarly restores the BIO to its original state and the read only data can be read again.

BIO_eof() is true if no data is in the BIO.

BIO_ctrl_pending() returns the number of bytes currently stored.

BIO_set_mem_eof_return() sets the behaviour of memory BIO b when it is empty. If the v is zero then an empty memory BIO will return EOF (that is it will return zero and BIO_should_retry(b) will be false. If v is non zero then it will return v when it is empty and it will set the read retry flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal positive return value v should be set to a negative value, typically -1. Calling this macro will fail for datagram mem BIOs.

BIO_get_mem_data() sets *pp to a pointer to the start of the memory BIOs data and returns the total amount of data available. It is implemented as a macro. Note the pointer returned by this call is informative, no transfer of ownership of this memory is implied. See notes on BIO_set_close().

BIO_set_mem_buf() sets the internal BUF_MEM structure to bm and sets the close flag to c, that is c should be either BIO_CLOSE or BIO_NOCLOSE. It is a macro.

BIO_get_mem_ptr() places the underlying BUF_MEM structure in *pp. It is a macro.

BIO_new_mem_buf() creates a memory BIO using len bytes of data at buf, if len is -1 then the buf is assumed to be nul terminated and its length is determined by strlen. The BIO is set to a read only state and as a result cannot be written to. This is useful when some data needs to be made available from a static area of memory in the form of a BIO. The supplied data is read directly from the supplied buffer: it is not copied first, so the supplied area of memory must be unchanged until the BIO is freed.

All of the five functions described above return an error with BIO_s_dgram_mem().

"},{"location":"man3/BIO_s_mem/#notes","title":"NOTES","text":"

Writes to memory BIOs will always succeed if memory is available: that is their size can grow indefinitely. An exception is BIO_s_dgram_mem() when BIO_set_write_buf_size(3) is called on it. In such case the write buffer size will be fixed and any writes that would overflow the buffer will return an error.

Every write after partial read (not all data in the memory buffer was read) to a read write memory BIO will have to move the unread data with an internal copy operation, if a BIO contains a lot of data and it is read in small chunks intertwined with writes the operation can be very slow. Adding a buffering BIO to the chain can speed up the process.

Calling BIO_set_mem_buf() on a secmem or dgram BIO will give undefined results, including perhaps a program crash.

Switching a memory BIO from read write to read only is not supported and can give undefined results including a program crash. There are two notable exceptions to the rule. The first one is to assign a static memory buffer immediately after BIO creation and set the BIO as read only.

The other supported sequence is to start with a read write BIO then temporarily switch it to read only and call BIO_reset() on the read only BIO immediately before switching it back to read write. Before the BIO is freed it must be switched back to the read write mode.

Calling BIO_get_mem_ptr() on read only BIO will return a BUF_MEM that contains only the remaining data to be read. If the close status of the BIO is set to BIO_NOCLOSE, before freeing the BUF_MEM the data pointer in it must be set to NULL as the data pointer does not point to an allocated memory.

Calling BIO_reset() on a read write memory BIO with BIO_FLAGS_NONCLEAR_RST flag set can have unexpected outcome when the reads and writes to the BIO are intertwined. As documented above the BIO will be reset to the state after the last completed write operation. The effects of reads preceding that write operation cannot be undone.

Calling BIO_get_mem_ptr() prior to a BIO_reset() call with BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation.

Calling BIO_set_close() with BIO_NOCLOSE orphans the BUF_MEM internal to the BIO, _not_ its actual data buffer. See the examples section for the proper method for claiming ownership of the data pointer for a deferred free operation.

"},{"location":"man3/BIO_s_mem/#return-values","title":"RETURN VALUES","text":"

BIO_s_mem(), BIO_s_dgram_mem() and BIO_s_secmem() return a valid memory BIO_METHOD structure.

BIO_set_mem_eof_return(), BIO_set_mem_buf() and BIO_get_mem_ptr() return 1 on success or a value which is less than or equal to 0 if an error occurred.

BIO_get_mem_data() returns the total number of bytes available on success, 0 if b is NULL, or a negative value in case of other errors.

BIO_new_mem_buf() returns a valid BIO structure on success or NULL on error.

"},{"location":"man3/BIO_s_mem/#examples","title":"EXAMPLES","text":"

Create a memory BIO and write some data to it:

BIO *mem = BIO_new(BIO_s_mem());\n\nBIO_puts(mem, \"Hello World\\n\");\n

Create a read only memory BIO:

char data[] = \"Hello World\";\nBIO *mem = BIO_new_mem_buf(data, -1);\n

Extract the BUF_MEM structure from a memory BIO and then free up the BIO:

BUF_MEM *bptr;\n\nBIO_get_mem_ptr(mem, &bptr);\nBIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */\nBIO_free(mem);\n

Extract the BUF_MEM ptr, claim ownership of the internal data and free the BIO and BUF_MEM structure:

BUF_MEM *bptr;\nchar *data;\n\nBIO_get_mem_data(bio, &data);\nBIO_get_mem_ptr(bio, &bptr);\nBIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free orphans BUF_MEM */\nBIO_free(bio);\nbptr->data = NULL; /* Tell BUF_MEM to orphan data */\nBUF_MEM_free(bptr);\n...\nfree(data);\n
"},{"location":"man3/BIO_s_mem/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_null/","title":"BIO_s_null","text":""},{"location":"man3/BIO_s_null/#name","title":"NAME","text":"

BIO_s_null - null data sink

"},{"location":"man3/BIO_s_null/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_null(void);\n
"},{"location":"man3/BIO_s_null/#description","title":"DESCRIPTION","text":"

BIO_s_null() returns the null sink BIO method. Data written to the null sink is discarded, reads return EOF.

"},{"location":"man3/BIO_s_null/#notes","title":"NOTES","text":"

A null sink BIO behaves in a similar manner to the Unix /dev/null device.

A null bio can be placed on the end of a chain to discard any data passed through it.

A null sink is useful if, for example, an application wishes to digest some data by writing through a digest bio but not send the digested data anywhere. Since a BIO chain must normally include a source/sink BIO this can be achieved by adding a null sink BIO to the end of the chain

"},{"location":"man3/BIO_s_null/#return-values","title":"RETURN VALUES","text":"

BIO_s_null() returns the null sink BIO method.

"},{"location":"man3/BIO_s_null/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_s_socket/","title":"BIO_s_socket","text":""},{"location":"man3/BIO_s_socket/#name","title":"NAME","text":"

BIO_s_socket, BIO_new_socket - socket BIO

"},{"location":"man3/BIO_s_socket/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nconst BIO_METHOD *BIO_s_socket(void);\n\nBIO *BIO_new_socket(int sock, int close_flag);\n
"},{"location":"man3/BIO_s_socket/#description","title":"DESCRIPTION","text":"

BIO_s_socket() returns the socket BIO method. This is a wrapper round the platform's socket routines.

BIO_read_ex() and BIO_write_ex() read or write the underlying socket. BIO_puts() is supported but BIO_gets() is not.

If the close flag is set then the socket is shut down and closed when the BIO is freed.

BIO_new_socket() returns a socket BIO using sock and close_flag.

"},{"location":"man3/BIO_s_socket/#notes","title":"NOTES","text":"

Socket BIOs also support any relevant functionality of file descriptor BIOs.

The reason for having separate file descriptor and socket BIOs is that on some platforms sockets are not file descriptors and use distinct I/O routines, Windows is one such platform. Any code mixing the two will not work on all platforms.

"},{"location":"man3/BIO_s_socket/#return-values","title":"RETURN VALUES","text":"

BIO_s_socket() returns the socket BIO method.

BIO_new_socket() returns the newly allocated BIO or NULL is an error occurred.

"},{"location":"man3/BIO_s_socket/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_sendmmsg/","title":"BIO_sendmmsg","text":""},{"location":"man3/BIO_sendmmsg/#name","title":"NAME","text":"

BIO_sendmmsg, BIO_recvmmsg, BIO_dgram_set_local_addr_enable, BIO_dgram_get_local_addr_enable, BIO_dgram_get_local_addr_cap, BIO_err_is_non_fatal - send and receive multiple datagrams in a single call

"},{"location":"man3/BIO_sendmmsg/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef struct bio_msg_st {\n    void *data;\n    size_t data_len;\n    BIO_ADDR *peer, *local;\n    uint64_t flags;\n} BIO_MSG;\n\nint BIO_sendmmsg(BIO *b, BIO_MSG *msg,\n                 size_t stride, size_t num_msg, uint64_t flags,\n                 size_t *msgs_processed);\nint BIO_recvmmsg(BIO *b, BIO_MSG *msg,\n                 size_t stride, size_t num_msg, uint64_t flags,\n                 size_t *msgs_processed);\n\nint BIO_dgram_set_local_addr_enable(BIO *b, int enable);\nint BIO_dgram_get_local_addr_enable(BIO *b, int *enable);\nint BIO_dgram_get_local_addr_cap(BIO *b);\nint BIO_err_is_non_fatal(unsigned int errcode);\n
"},{"location":"man3/BIO_sendmmsg/#description","title":"DESCRIPTION","text":"

BIO_sendmmsg() and BIO_recvmmsg() functions can be used to send and receive multiple messages in a single call to a BIO. They are analogous to sendmmsg(2) and recvmmsg(2) on operating systems which provide those functions.

The BIO_MSG structure provides a subset of the functionality of the struct msghdr structure defined by POSIX. These functions accept an array of BIO_MSG structures. On any particular invocation, these functions may process all of the passed structures, some of them, or none of them. This is indicated by the value stored in *msgs_processed, which expresses the number of messages processed.

The caller should set the data member of a BIO_MSG to a buffer containing the data to send, or to be filled with a received message. data_len should be set to the size of the buffer in bytes. If the given BIO_MSG is processed (in other words, if the integer returned by the function is greater than or equal to that BIO_MSG's array index), data_len will be modified to specify the actual amount of data sent or received.

The flags field of a BIO_MSG provides input per-message flags to the invocation. If the invocation processes that BIO_MSG, the flags field is written with output per-message flags, or zero if no such flags are applicable.

Currently, no input or output per-message flags are defined and this field should be set to zero before calling BIO_sendmmsg() or BIO_recvmmsg().

The flags argument to BIO_sendmmsg() and BIO_recvmmsg() provides global flags which affect the entire invocation. No global flags are currently defined and this argument should be set to zero.

When these functions are used to send and receive datagrams, the peer field of a BIO_MSG allows the destination address of sent datagrams to be specified on a per-datagram basis, and the source address of received datagrams to be determined. The peer field should be set to point to a BIO_ADDR, which will be read by BIO_sendmmsg() and used as the destination address for sent datagrams, and written by BIO_recvmmsg() with the source address of received datagrams.

Similarly, the local field of a BIO_MSG allows the source address of sent datagrams to be specified on a per-datagram basis, and the destination address of received datagrams to be determined. Unlike peer, support for local must be explicitly enabled on a BIO before it can be used; see BIO_dgram_set_local_addr_enable(). If local is non-NULL in a BIO_MSG and support for local has not been enabled, processing of that BIO_MSG fails.

peer and local should be set to NULL if they are not required. Support for local may not be available on all platforms; on these platforms, these functions always fail if local is non-NULL.

If local is specified and local address support is enabled, but the operating system does not report a local address for a specific received message, the BIO_ADDR it points to will be cleared (address family set to AF_UNSPEC). This is known to happen on Windows when a packet is received which was sent by the local system, regardless of whether the packet's destination address was the loopback address or the IP address of a local non-loopback interface. This is also known to happen on macOS in some circumstances, such as for packets sent before local address support was enabled for a receiving socket. These are OS-specific limitations. As such, users of this API using local address support should expect to sometimes receive a cleared local BIO_ADDR instead of the correct value.

The stride argument must be set to sizeof(BIO_MSG). This argument facilitates backwards compatibility if fields are added to BIO_MSG. Callers must zero-initialize BIO_MSG.

num_msg should be sent to the maximum number of messages to send or receive, which is also the length of the array pointed to by msg.

msgs_processed must be non-NULL and points to an integer written with the number of messages successfully processed; see the RETURN VALUES section for further discussion.

Unlike most BIO functions, these functions explicitly support multi-threaded use. Multiple concurrent writers and multiple concurrent readers of the same BIO are permitted in any combination. As such, these functions do not clear, set, or otherwise modify BIO retry flags. The return value must be used to determine whether an operation should be retried; see below.

The support for concurrent use extends to BIO_sendmmsg() and BIO_recvmmsg() only, and no other function may be called on a given BIO while any call to BIO_sendmmsg() or BIO_recvmmsg() is in progress, or vice versa.

BIO_dgram_set_local_addr_enable() and BIO_dgram_get_local_addr_enable() control whether local address support is enabled. To enable local address support, call BIO_dgram_set_local_addr_enable() with an argument of 1. The call will fail if local address support is not available for the platform. BIO_dgram_get_local_addr_enable() retrieves the value set by BIO_dgram_set_local_addr_enable().

BIO_dgram_get_local_addr_cap() determines if the BIO is capable of supporting local addresses.

BIO_err_is_non_fatal() determines if a packed error code represents an error which is transient in nature.

"},{"location":"man3/BIO_sendmmsg/#notes","title":"NOTES","text":"

Some implementations of the BIO_sendmmsg() and BIO_recvmmsg() BIO methods might always process at most one message at a time, for example when OS-level functionality to transmit or receive multiple messages at a time is not available.

"},{"location":"man3/BIO_sendmmsg/#return-values","title":"RETURN VALUES","text":"

On success, the functions BIO_sendmmsg() and BIO_recvmmsg() return 1 and write the number of messages successfully processed (which need not be nonzero) to msgs_processed. Where a positive value n is written to msgs_processed, all entries in the BIO_MSG array from 0 through n-1 inclusive have their data_len and flags fields updated with the results of the operation on that message. If the call was to BIO_recvmmsg() and the peer or local fields of that message are non-NULL, the BIO_ADDR structures they point to are written with the relevant address.

On failure, the functions BIO_sendmmsg() and BIO_recvmmsg() return 0 and write zero to msgs_processed. Thus msgs_processed is always written regardless of the outcome of the function call.

If BIO_sendmmsg() and BIO_recvmmsg() fail, they always raise an ERR_LIB_BIO error using ERR_raise(3). Any error may be raised, but the following in particular may be noted:

Third parties implementing custom BIOs supporting the BIO_sendmmsg() or BIO_recvmmsg() methods should note that it is a required part of the API contract that an error is always raised when either of these functions return 0.

BIO_dgram_set_local_addr_enable() returns 1 if local address support was successfully enabled or disabled and 0 otherwise.

BIO_dgram_get_local_addr_enable() returns 1 if the local address support enable flag was successfully retrieved.

BIO_dgram_get_local_addr_cap() returns 1 if the BIO can support local addresses.

BIO_err_is_non_fatal() returns 1 if the passed packed error code represents an error which is transient in nature.

"},{"location":"man3/BIO_sendmmsg/#history","title":"HISTORY","text":"

These functions were added in OpenSSL 3.2.

"},{"location":"man3/BIO_sendmmsg/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_set_callback/","title":"BIO_set_callback","text":""},{"location":"man3/BIO_set_callback/#name","title":"NAME","text":"

BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn - BIO callback functions

"},{"location":"man3/BIO_set_callback/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\ntypedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,\n                                   size_t len, int argi,\n                                   long argl, int ret, size_t *processed);\n\nvoid BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);\nBIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);\n\nvoid BIO_set_callback_arg(BIO *b, char *arg);\nchar *BIO_get_callback_arg(const BIO *b);\n\nlong BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len,\n                           int argi, long argl, int ret, size_t *processed);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,\n                                long argl, long ret);\nvoid BIO_set_callback(BIO *b, BIO_callback_fn cb);\nBIO_callback_fn BIO_get_callback(const BIO *b);\nlong BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,\n                        long argl, long ret);\n\ntypedef struct bio_mmsg_cb_args_st {\n    BIO_MSG    *msg;\n    size_t      stride, num_msg;\n    uint64_t    flags;\n    size_t     *msgs_processed;\n} BIO_MMSG_CB_ARGS;\n
"},{"location":"man3/BIO_set_callback/#description","title":"DESCRIPTION","text":"

BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO callback. The callback is called during most high-level BIO operations. It can be used for debugging purposes to trace operations on a BIO or to modify its operation.

BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO callback. New code should not use these functions, but they are retained for backwards compatibility. Any callback set via BIO_set_callback_ex() will get called in preference to any set by BIO_set_callback().

BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be used to set and retrieve an argument for use in the callback.

BIO_debug_callback_ex() is a standard debugging callback which prints out information relating to each BIO operation. If the callback argument is set it is interpreted as a BIO to send the information to, otherwise stderr is used. The BIO_debug_callback() function is the deprecated version of the same callback for use with the old callback format BIO_set_callback() function.

BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn is the type of the old format callback function. The meaning of each argument is described below:

The callback should normally simply return ret when it has finished processing, unless it specifically wishes to modify the value returned to the application.

"},{"location":"man3/BIO_set_callback/#callback-operations","title":"CALLBACK OPERATIONS","text":"

In the notes below, callback defers to the actual callback function that is called.

"},{"location":"man3/BIO_set_callback/#return-values","title":"RETURN VALUES","text":"

BIO_get_callback_ex() and BIO_get_callback() return the callback function previously set by a call to BIO_set_callback_ex() and BIO_set_callback() respectively.

BIO_get_callback_arg() returns a char pointer to the value previously set via a call to BIO_set_callback_arg().

BIO_debug_callback() returns 1 or ret if it's called after specific BIO operations.

"},{"location":"man3/BIO_set_callback/#examples","title":"EXAMPLES","text":"

The BIO_debug_callback_ex() function is an example, its source is in crypto/bio/bio_cb.c

"},{"location":"man3/BIO_set_callback/#history","title":"HISTORY","text":"

The BIO_debug_callback_ex() function was added in OpenSSL 3.0.

BIO_set_callback(), BIO_get_callback(), and BIO_debug_callback() were deprecated in OpenSSL 3.0. Use the non-deprecated _ex functions instead.

"},{"location":"man3/BIO_set_callback/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_should_retry/","title":"BIO_should_retry","text":""},{"location":"man3/BIO_should_retry/#name","title":"NAME","text":"

BIO_should_read, BIO_should_write, BIO_should_io_special, BIO_retry_type, BIO_should_retry, BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry functions

"},{"location":"man3/BIO_should_retry/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\nint BIO_should_read(BIO *b);\nint BIO_should_write(BIO *b);\nint BIO_should_io_special(iBIO *b);\nint BIO_retry_type(BIO *b);\nint BIO_should_retry(BIO *b);\n\nBIO *BIO_get_retry_BIO(BIO *bio, int *reason);\nint BIO_get_retry_reason(BIO *bio);\nvoid BIO_set_retry_reason(BIO *bio, int reason);\n
"},{"location":"man3/BIO_should_retry/#description","title":"DESCRIPTION","text":"

These functions determine why a BIO is not able to read or write data. They will typically be called after a failed BIO_read_ex() or BIO_write_ex() call.

BIO_should_retry() is true if the call that produced this condition should then be retried at a later time.

If BIO_should_retry() is false then the cause is an error condition.

BIO_should_read() is true if the cause of the condition is that the BIO has insufficient data to return. Check for readability and/or retry the last operation.

BIO_should_write() is true if the cause of the condition is that the BIO has pending data to write. Check for writability and/or retry the last operation.

BIO_should_io_special() is true if some \"special\" condition, that is a reason other than reading or writing is the cause of the condition.

BIO_retry_type() returns a mask of the cause of a retry condition consisting of the values BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL though current BIO types will only set one of these.

BIO_get_retry_BIO() determines the precise reason for the special condition, it returns the BIO that caused this condition and if reason is not NULL it contains the reason code. The meaning of the reason code and the action that should be taken depends on the type of BIO that resulted in this condition.

BIO_get_retry_reason() returns the reason for a special condition if passed the relevant BIO, for example as returned by BIO_get_retry_BIO().

BIO_set_retry_reason() sets the retry reason for a special condition for a given BIO. This would usually only be called by BIO implementations.

"},{"location":"man3/BIO_should_retry/#notes","title":"NOTES","text":"

BIO_should_read(), BIO_should_write(), BIO_should_io_special(), BIO_retry_type(), and BIO_should_retry(), are implemented as macros.

If BIO_should_retry() returns false then the precise \"error condition\" depends on the BIO type that caused it and the return code of the BIO operation. For example if a call to BIO_read_ex() on a socket BIO returns 0 and BIO_should_retry() is false then the cause will be that the connection closed. A similar condition on a file BIO will mean that it has reached EOF. Some BIO types may place additional information on the error queue. For more details see the individual BIO type manual pages.

If the underlying I/O structure is in a blocking mode almost all current BIO types will not request a retry, because the underlying I/O calls will not. If the application knows that the BIO type will never signal a retry then it need not call BIO_should_retry() after a failed BIO I/O call. This is typically done with file BIOs.

SSL BIOs are the only current exception to this rule: they can request a retry even if the underlying I/O structure is blocking, if a handshake occurs during a call to BIO_read(). An application can retry the failed call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY on the underlying SSL structure.

While an application may retry a failed non blocking call immediately this is likely to be very inefficient because the call will fail repeatedly until data can be processed or is available. An application will normally wait until the necessary condition is satisfied. How this is done depends on the underlying I/O structure.

For example if the cause is ultimately a socket and BIO_should_read() is true then a call to select() may be made to wait until data is available and then retry the BIO operation. By combining the retry conditions of several non blocking BIOs in a single select() call it is possible to service several BIOs in a single thread, though the performance may be poor if SSL BIOs are present because long delays can occur during the initial handshake process.

It is possible for a BIO to block indefinitely if the underlying I/O structure cannot process or return any data. This depends on the behaviour of the platforms I/O functions. This is often not desirable: one solution is to use non blocking I/O and use a timeout on the select() (or equivalent) call.

"},{"location":"man3/BIO_should_retry/#bugs","title":"BUGS","text":"

The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: that is they cannot retry after a partial read or write. This is usually worked around by only passing the relevant data to ASN1 functions when the entire structure can be read or written.

"},{"location":"man3/BIO_should_retry/#return-values","title":"RETURN VALUES","text":"

BIO_should_read(), BIO_should_write(), BIO_should_io_special(), and BIO_should_retry() return either 1 or 0 based on the actual conditions of the BIO.

BIO_retry_type() returns a flag combination presenting the cause of a retry condition or false if there is no retry condition.

BIO_get_retry_BIO() returns a valid BIO structure.

BIO_get_retry_reason() returns the reason for a special condition.

"},{"location":"man3/BIO_should_retry/#see-also","title":"SEE ALSO","text":"

bio(7)

"},{"location":"man3/BIO_should_retry/#history","title":"HISTORY","text":"

The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in OpenSSL 1.1.0.

"},{"location":"man3/BIO_should_retry/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BIO_socket_wait/","title":"BIO_socket_wait","text":""},{"location":"man3/BIO_socket_wait/#name","title":"NAME","text":"

BIO_socket_wait, BIO_wait, BIO_do_connect_retry - BIO connection utility functions

"},{"location":"man3/BIO_socket_wait/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bio.h>\n\n#ifndef OPENSSL_NO_SOCK\nint BIO_socket_wait(int fd, int for_read, time_t max_time);\n#endif\nint BIO_wait(BIO *bio, time_t max_time, unsigned int nap_milliseconds);\nint BIO_do_connect_retry(BIO *bio, int timeout, int nap_milliseconds);\n
"},{"location":"man3/BIO_socket_wait/#description","title":"DESCRIPTION","text":"

BIO_socket_wait() waits on the socket fd for reading if for_read is not 0, else for writing, at most until max_time. It succeeds immediately if max_time == 0 (which means no timeout given).

BIO_wait() waits at most until max_time on the given (typically socket-based) bio, for reading if bio is supposed to read, else for writing. It is used by BIO_do_connect_retry() and can be used together BIO_read(3). It succeeds immediately if max_time == 0 (which means no timeout given). If sockets are not available it supports polling by succeeding after sleeping at most the given nap_milliseconds in order to avoid a tight busy loop. Via nap_milliseconds the caller determines the polling granularity.

BIO_do_connect_retry() connects via the given bio. It retries BIO_do_connect() as far as needed to reach a definite outcome, i.e., connection succeeded, timeout has been reached, or an error occurred. For nonblocking and potentially even non-socket BIOs it polls every nap_milliseconds and sleeps in between using BIO_wait(). If nap_milliseconds is < 0 then a default value of 100 ms is used. If the timeout parameter is > 0 this indicates the maximum number of seconds to wait until the connection is established or a definite error occurred. A value of 0 enables waiting indefinitely (i.e, no timeout), while a value < 0 means that BIO_do_connect() is tried only once. The function may, directly or indirectly, invoke ERR_clear_error().

"},{"location":"man3/BIO_socket_wait/#return-values","title":"RETURN VALUES","text":"

BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() return -1 on error, 0 on timeout, and 1 on success.

"},{"location":"man3/BIO_socket_wait/#see-also","title":"SEE ALSO","text":"

BIO_do_connect(3), BIO_read(3)

"},{"location":"man3/BIO_socket_wait/#history","title":"HISTORY","text":"

BIO_socket_wait(), BIO_wait(), and BIO_do_connect_retry() were added in OpenSSL 3.0.

"},{"location":"man3/BIO_socket_wait/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_BLINDING_new/","title":"BN_BLINDING_new","text":""},{"location":"man3/BN_BLINDING_new/#name","title":"NAME","text":"

BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions

"},{"location":"man3/BN_BLINDING_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,\n                             BIGNUM *mod);\nvoid BN_BLINDING_free(BN_BLINDING *b);\nint BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);\nint BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);\nint BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);\nint BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,\n                           BN_CTX *ctx);\nint BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,\n                          BN_CTX *ctx);\nint BN_BLINDING_is_current_thread(BN_BLINDING *b);\nvoid BN_BLINDING_set_current_thread(BN_BLINDING *b);\nint BN_BLINDING_lock(BN_BLINDING *b);\nint BN_BLINDING_unlock(BN_BLINDING *b);\nunsigned long BN_BLINDING_get_flags(const BN_BLINDING *b);\nvoid BN_BLINDING_set_flags(BN_BLINDING *b, unsigned long flags);\nBN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,\n                                      const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,\n                                      int (*bn_mod_exp)(BIGNUM *r,\n                                                        const BIGNUM *a,\n                                                        const BIGNUM *p,\n                                                        const BIGNUM *m,\n                                                        BN_CTX *ctx,\n                                                        BN_MONT_CTX *m_ctx),\n                                      BN_MONT_CTX *m_ctx);\n
"},{"location":"man3/BN_BLINDING_new/#description","title":"DESCRIPTION","text":"

BN_BLINDING_new() allocates a new BN_BLINDING structure and copies the A and Ai values into the newly created BN_BLINDING object.

BN_BLINDING_free() frees the BN_BLINDING structure. If b is NULL, nothing is done.

BN_BLINDING_update() updates the BN_BLINDING parameters by squaring the A and Ai or, after specific number of uses and if the necessary parameters are set, by re-creating the blinding parameters.

BN_BLINDING_convert_ex() multiplies n with the blinding factor A. If r is not NULL a copy the inverse blinding factor Ai will be returned in r (this is useful if a RSA object is shared among several threads). BN_BLINDING_invert_ex() multiplies n with the inverse blinding factor Ai. If r is not NULL it will be used as the inverse blinding.

BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() with r set to NULL.

BN_BLINDING_is_current_thread() returns whether the BN_BLINDING structure is owned by the current thread. This is to help users provide proper locking if needed for multi-threaded use.

BN_BLINDING_set_current_thread() sets the current thread as the owner of the BN_BLINDING structure.

BN_BLINDING_lock() locks the BN_BLINDING structure.

BN_BLINDING_unlock() unlocks the BN_BLINDING structure.

BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently there are two supported flags: BN_BLINDING_NO_UPDATE and BN_BLINDING_NO_RECREATE. BN_BLINDING_NO_UPDATE inhibits the automatic update of the BN_BLINDING parameters after each use and BN_BLINDING_NO_RECREATE inhibits the automatic re-creation of the BN_BLINDING parameters after a fixed number of uses (currently 32). In newly allocated BN_BLINDING objects no flags are set. BN_BLINDING_set_flags() sets the BN_BLINDING parameters flags.

BN_BLINDING_create_param() creates new BN_BLINDING parameters using the exponent e and the modulus m. bn_mod_exp and m_ctx can be used to pass special functions for exponentiation (normally BN_mod_exp_mont() and BN_MONT_CTX).

"},{"location":"man3/BN_BLINDING_new/#return-values","title":"RETURN VALUES","text":"

BN_BLINDING_new() returns the newly allocated BN_BLINDING structure or NULL in case of an error.

BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(), BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on success and 0 if an error occurred.

BN_BLINDING_is_current_thread() returns 1 if the current thread owns the BN_BLINDING object, 0 otherwise.

BN_BLINDING_set_current_thread() doesn't return anything.

BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation succeeded or 0 on error.

BN_BLINDING_get_flags() returns the currently set BN_BLINDING flags (a unsigned long value).

BN_BLINDING_create_param() returns the newly created BN_BLINDING parameters or NULL on error.

"},{"location":"man3/BN_BLINDING_new/#history","title":"HISTORY","text":"

BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().

"},{"location":"man3/BN_BLINDING_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2005-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_CTX_new/","title":"BN_CTX_new","text":""},{"location":"man3/BN_CTX_new/#name","title":"NAME","text":"

BN_CTX_new_ex, BN_CTX_new, BN_CTX_secure_new_ex, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures

"},{"location":"man3/BN_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_CTX *BN_CTX_new_ex(OSSL_LIB_CTX *ctx);\nBN_CTX *BN_CTX_new(void);\n\nBN_CTX *BN_CTX_secure_new_ex(OSSL_LIB_CTX *ctx);\nBN_CTX *BN_CTX_secure_new(void);\n\nvoid BN_CTX_free(BN_CTX *c);\n
"},{"location":"man3/BN_CTX_new/#description","title":"DESCRIPTION","text":"

A BN_CTX is a structure that holds BIGNUM temporary variables used by library functions. Since dynamic memory allocation to create BIGNUMs is rather expensive when used in conjunction with repeated subroutine calls, the BN_CTX structure is used.

BN_CTX_new_ex() allocates and initializes a BN_CTX structure for the given library context ctx. The <ctx> value may be NULL in which case the default library context will be used. BN_CTX_new() is the same as BN_CTX_new_ex() except that the default library context is always used.

BN_CTX_secure_new_ex() allocates and initializes a BN_CTX structure but uses the secure heap (see CRYPTO_secure_malloc(3)) to hold the BIGNUMs for the given library context ctx. The <ctx> value may be NULL in which case the default library context will be used. BN_CTX_secure_new() is the same as BN_CTX_secure_new_ex() except that the default library context is always used.

BN_CTX_free() frees the components of the BN_CTX and the structure itself. Since BN_CTX_start() is required in order to obtain BIGNUMs from the BN_CTX, in most cases BN_CTX_end() must be called before the BN_CTX may be freed by BN_CTX_free(). If c is NULL, nothing is done.

A given BN_CTX must only be used by a single thread of execution. No locking is performed, and the internal pool allocator will not properly handle multiple threads of execution.

"},{"location":"man3/BN_CTX_new/#return-values","title":"RETURN VALUES","text":"

BN_CTX_new() and BN_CTX_secure_new() return a pointer to the BN_CTX. If the allocation fails, they return NULL and sets an error code that can be obtained by ERR_get_error(3).

BN_CTX_free() has no return values.

"},{"location":"man3/BN_CTX_new/#removed-functionality","title":"REMOVED FUNCTIONALITY","text":"
void BN_CTX_init(BN_CTX *c);\n

BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should replace use of BN_CTX_init with BN_CTX_new instead:

BN_CTX *ctx;\nctx = BN_CTX_new();\nif (!ctx)\n    /* error */\n...\nBN_CTX_free(ctx);\n
"},{"location":"man3/BN_CTX_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3), BN_CTX_start(3)

"},{"location":"man3/BN_CTX_new/#history","title":"HISTORY","text":"

BN_CTX_init() was removed in OpenSSL 1.1.0.

"},{"location":"man3/BN_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_CTX_start/","title":"BN_CTX_start","text":""},{"location":"man3/BN_CTX_start/#name","title":"NAME","text":"

BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables

"},{"location":"man3/BN_CTX_start/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nvoid BN_CTX_start(BN_CTX *ctx);\n\nBIGNUM *BN_CTX_get(BN_CTX *ctx);\n\nvoid BN_CTX_end(BN_CTX *ctx);\n
"},{"location":"man3/BN_CTX_start/#description","title":"DESCRIPTION","text":"

These functions are used to obtain temporary BIGNUM variables from a BN_CTX (which can been created by using BN_CTX_new(3)) in order to save the overhead of repeatedly creating and freeing BIGNUMs in functions that are called from inside a loop.

A function must call BN_CTX_start() first. Then, BN_CTX_get() may be called repeatedly to obtain temporary BIGNUMs. All BN_CTX_get() calls must be made before calling any other functions that use the ctx as an argument.

Finally, BN_CTX_end() must be called before returning from the function. If ctx is NULL, nothing is done. When BN_CTX_end() is called, the BIGNUM pointers obtained from BN_CTX_get() become invalid.

"},{"location":"man3/BN_CTX_start/#return-values","title":"RETURN VALUES","text":"

BN_CTX_start() and BN_CTX_end() return no values.

BN_CTX_get() returns a pointer to the BIGNUM, or NULL on error. Once BN_CTX_get() has failed, the subsequent calls will return NULL as well, so it is sufficient to check the return value of the last BN_CTX_get() call. In case of an error, an error code is set, which can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_CTX_start/#see-also","title":"SEE ALSO","text":"

BN_CTX_new(3)

"},{"location":"man3/BN_CTX_start/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_add/","title":"BN_add","text":""},{"location":"man3/BN_add/#name","title":"NAME","text":"

BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add, BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_mod_sqrt, BN_exp, BN_mod_exp, BN_gcd - arithmetic operations on BIGNUMs

"},{"location":"man3/BN_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);\n\nint BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);\n\nint BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);\n\nint BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);\n\nint BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,\n           BN_CTX *ctx);\n\nint BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);\n\nint BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);\n\nint BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,\n               BN_CTX *ctx);\n\nint BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,\n               BN_CTX *ctx);\n\nint BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m,\n               BN_CTX *ctx);\n\nint BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);\n\nBIGNUM *BN_mod_sqrt(BIGNUM *in, BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);\n\nint BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);\n\nint BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,\n               const BIGNUM *m, BN_CTX *ctx);\n\nint BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);\n
"},{"location":"man3/BN_add/#description","title":"DESCRIPTION","text":"

BN_add() adds a and b and places the result in r (r=a+b). r may be the same BIGNUM as a or b.

BN_sub() subtracts b from a and places the result in r (r=a-b). r may be the same BIGNUM as a or b.

BN_mul() multiplies a and b and places the result in r (r=a*b). r may be the same BIGNUM as a or b. For multiplication by powers of 2, use BN_lshift(3).

BN_sqr() takes the square of a and places the result in r (r=a^2). r and a may be the same BIGNUM. This function is faster than BN_mul(r,a,a).

BN_div() divides a by d and places the result in dv and the remainder in rem (dv=a/d, rem=a%d). Either of dv and rem may be NULL, in which case the respective value is not returned. The result is rounded towards zero; thus if a is negative, the remainder will be zero or negative. For division by powers of 2, use BN_rshift(3).

BN_mod() corresponds to BN_div() with dv set to NULL.

BN_nnmod() reduces a modulo m and places the nonnegative remainder in r.

BN_mod_add() adds a to b modulo m and places the nonnegative result in r.

BN_mod_sub() subtracts b from a modulo m and places the nonnegative result in r.

BN_mod_mul() multiplies a by b and finds the nonnegative remainder respective to modulus m (r=(a*b) mod m). r may be the same BIGNUM as a or b. For more efficient algorithms for repeated computations using the same modulus, see BN_mod_mul_montgomery(3) and BN_mod_mul_reciprocal(3).

BN_mod_sqr() takes the square of a modulo m and places the result in r.

BN_mod_sqrt() returns the modular square root of a such that in^2 = a (mod p). The modulus p must be a prime, otherwise an error or an incorrect \"result\" will be returned. The result is stored into in which can be NULL. The result will be newly allocated in that case.

BN_exp() raises a to the p-th power and places the result in r (r=a^p). This function is faster than repeated applications of BN_mul().

BN_mod_exp() computes a to the p-th power modulo m (r=a^p % m). This function uses less time and space than BN_exp(). Do not call this function when m is even and any of the parameters have the BN_FLG_CONSTTIME flag set.

BN_gcd() computes the greatest common divisor of a and b and places the result in r. r may be the same BIGNUM as a or b.

For all functions, ctx is a previously allocated BN_CTX used for temporary variables; see BN_CTX_new(3).

Unless noted otherwise, the result BIGNUM must be different from the arguments.

"},{"location":"man3/BN_add/#notes","title":"NOTES","text":"

For modular operations such as BN_nnmod() or BN_mod_exp() it is an error to use the same BIGNUM object for the modulus as for the output.

"},{"location":"man3/BN_add/#return-values","title":"RETURN VALUES","text":"

The BN_mod_sqrt() returns the result (possibly incorrect if p is not a prime), or NULL.

For all remaining functions, 1 is returned for success, 0 on error. The return value should always be checked (e.g., if (!BN_add(r,a,b)) goto err;). The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_add/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_CTX_new(3), BN_add_word(3), BN_set_bit(3)

"},{"location":"man3/BN_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_add_word/","title":"BN_add_word","text":""},{"location":"man3/BN_add_word/#name","title":"NAME","text":"

BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic functions on BIGNUMs with integers

"},{"location":"man3/BN_add_word/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_add_word(BIGNUM *a, BN_ULONG w);\n\nint BN_sub_word(BIGNUM *a, BN_ULONG w);\n\nint BN_mul_word(BIGNUM *a, BN_ULONG w);\n\nBN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);\n\nBN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);\n
"},{"location":"man3/BN_add_word/#description","title":"DESCRIPTION","text":"

These functions perform arithmetic operations on BIGNUMs with unsigned integers. They are much more efficient than the normal BIGNUM arithmetic operations.

BN_add_word() adds w to a (a+=w).

BN_sub_word() subtracts w from a (a-=w).

BN_mul_word() multiplies a and w (a*=w).

BN_div_word() divides a by w (a/=w) and returns the remainder.

BN_mod_word() returns the remainder of a divided by w (a%w).

For BN_div_word() and BN_mod_word(), w must not be 0.

"},{"location":"man3/BN_add_word/#return-values","title":"RETURN VALUES","text":"

BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

BN_mod_word() and BN_div_word() return a%w on success and (BN_ULONG)-1 if an error occurred.

"},{"location":"man3/BN_add_word/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3)

"},{"location":"man3/BN_add_word/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_bn2bin/","title":"BN_bn2bin","text":""},{"location":"man3/BN_bn2bin/#name","title":"NAME","text":"

BN_bn2binpad, BN_signed_bn2bin, BN_bn2bin, BN_bin2bn, BN_signed_bin2bn, BN_bn2lebinpad, BN_signed_bn2lebin, BN_lebin2bn, BN_signed_lebin2bn, BN_bn2nativepad, BN_signed_bn2native, BN_native2bn, BN_signed_native2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions

"},{"location":"man3/BN_bn2bin/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_bn2bin(const BIGNUM *a, unsigned char *to);\nint BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);\nint BN_signed_bn2bin(const BIGNUM *a, unsigned char *to, int tolen);\nBIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);\nBIGNUM *BN_signed_bin2bn(const unsigned char *s, int len, BIGNUM *ret);\n\nint BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);\nint BN_signed_bn2lebin(const BIGNUM *a, unsigned char *to, int tolen);\nBIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);\nBIGNUM *BN_signed_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);\n\nint BN_bn2nativepad(const BIGNUM *a, unsigned char *to, int tolen);\nint BN_signed_bn2native(const BIGNUM *a, unsigned char *to, int tolen);\nBIGNUM *BN_native2bn(const unsigned char *s, int len, BIGNUM *ret);\nBIGNUM *BN_signed_native2bn(const unsigned char *s, int len, BIGNUM *ret);\n\nchar *BN_bn2hex(const BIGNUM *a);\nchar *BN_bn2dec(const BIGNUM *a);\nint BN_hex2bn(BIGNUM **a, const char *str);\nint BN_dec2bn(BIGNUM **a, const char *str);\n\nint BN_print(BIO *fp, const BIGNUM *a);\nint BN_print_fp(FILE *fp, const BIGNUM *a);\n\nint BN_bn2mpi(const BIGNUM *a, unsigned char *to);\nBIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);\n
"},{"location":"man3/BN_bn2bin/#description","title":"DESCRIPTION","text":"

BN_bn2bin() converts the absolute value of a into big-endian form and stores it at to. to must point to BN_num_bytes(a) bytes of memory.

BN_bn2binpad() also converts the absolute value of a into big-endian form and stores it at to. tolen indicates the length of the output buffer to. The result is padded with zeros if necessary. If tolen is less than BN_num_bytes(a) an error is returned.

BN_signed_bn2bin() converts the value of a into big-endian signed 2's complements form and stores it at to. tolen indicates the length of the output buffer to. The result is signed extended (padded with 0x00 for positive numbers or with 0xff for negative numbers) if necessary. If tolen is smaller than the necessary size (which may be <BN_num_bytes(**a**) + 1>), an error is returned.

BN_bin2bn() converts the positive integer in big-endian form of length len at s into a BIGNUM and places it in ret. If ret is NULL, a new BIGNUM is created.

BN_signed_bin2bn() converts the integer in big-endian signed 2's complement form of length len at s into a BIGNUM and places it in ret. If ret is NULL, a new BIGNUM is created.

BN_bn2lebinpad(), BN_signed_bn2lebin() and BN_lebin2bn() are identical to BN_bn2binpad(), BN_signed_bn2bin() and BN_bin2bn() except the buffer is in little-endian format.

BN_bn2nativepad(), BN_signed_bn2native() and BN_native2bn() are identical to BN_bn2binpad(), BN_signed_bn2bin() and BN_bin2bn() except the buffer is in native format, i.e. most significant byte first on big-endian platforms, and least significant byte first on little-endian platforms.

BN_bn2hex() and BN_bn2dec() return printable strings containing the hexadecimal and decimal encoding of a respectively. For negative numbers, the string is prefaced with a leading '-'. The string must be freed later using OPENSSL_free().

BN_hex2bn() takes as many characters as possible from the string str, including the leading character '-' which means negative, to form a valid hexadecimal number representation and converts them to a BIGNUM and stores it in **a. If *a is NULL, a new BIGNUM is created. If a is NULL, it only computes the length of valid representation. A \"negative zero\" is converted to zero. BN_dec2bn() is the same using the decimal system.

BN_print() and BN_print_fp() write the hexadecimal encoding of a, with a leading '-' for negative numbers, to the BIO or FILE fp.

BN_bn2mpi() and BN_mpi2bn() convert BIGNUMs from and to a format that consists of the number's length in bytes represented as a 4-byte big-endian number, and the number itself in big-endian format, where the most significant bit signals a negative number (the representation of numbers with the MSB set is prefixed with null byte).

BN_bn2mpi() stores the representation of a at to, where to must be large enough to hold the result. The size can be determined by calling BN_bn2mpi(a, NULL).

BN_mpi2bn() converts the len bytes long representation at s to a BIGNUM and stores it at ret, or in a newly allocated BIGNUM if ret is NULL.

"},{"location":"man3/BN_bn2bin/#return-values","title":"RETURN VALUES","text":"

BN_bn2bin() returns the length of the big-endian number placed at to. BN_bin2bn() returns the BIGNUM, NULL on error.

BN_bn2binpad(), BN_signed_bn2bin(), BN_bn2lebinpad(), BN_signed_bn2lebin(), BN_bn2nativepad(), and_signed BN_bn2native() return the number of bytes written or -1 if the supplied buffer is too small.

BN_bn2hex() and BN_bn2dec() return a NUL-terminated string, or NULL on error. BN_hex2bn() and BN_dec2bn() return the number of characters used in parsing, or 0 on error, in which case no new BIGNUM will be created.

BN_print_fp() and BN_print() return 1 on success, 0 on write errors.

BN_bn2mpi() returns the length of the representation. BN_mpi2bn() returns the BIGNUM, and NULL on error.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_bn2bin/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_zero(3), ASN1_INTEGER_to_BN(3), BN_num_bytes(3)

"},{"location":"man3/BN_bn2bin/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_cmp/","title":"BN_cmp","text":""},{"location":"man3/BN_cmp/#name","title":"NAME","text":"

BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_abs_is_word, BN_is_odd, BN_are_coprime - BIGNUM comparison and test functions

"},{"location":"man3/BN_cmp/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_cmp(const BIGNUM *a, const BIGNUM *b);\nint BN_ucmp(const BIGNUM *a, const BIGNUM *b);\n\nint BN_is_zero(const BIGNUM *a);\nint BN_is_one(const BIGNUM *a);\nint BN_is_word(const BIGNUM *a, const BN_ULONG w);\nint BN_abs_is_word(const BIGNUM *a, const BN_ULONG w);\nint BN_is_odd(const BIGNUM *a);\n\nint BN_are_coprime(BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\n
"},{"location":"man3/BN_cmp/#description","title":"DESCRIPTION","text":"

BN_cmp() compares the numbers a and b. BN_ucmp() compares their absolute values.

BN_is_zero(), BN_is_one(), BN_is_word() and BN_abs_is_word() test if a equals 0, 1, w, or |w| respectively. BN_is_odd() tests if a is odd.

BN_are_coprime() determines if a and b are coprime. ctx is used internally for storing temporary variables. The values of a and b and ctx must not be NULL.

"},{"location":"man3/BN_cmp/#return-values","title":"RETURN VALUES","text":"

BN_cmp() returns -1 if a < b, 0 if a == b and 1 if a > b. BN_ucmp() is the same using the absolute values of a and b.

BN_is_zero(), BN_is_one() BN_is_word(), BN_abs_is_word() and BN_is_odd() return 1 if the condition is true, 0 otherwise.

BN_are_coprime() returns 1 if the BIGNUM's are coprime, otherwise it returns 0.

"},{"location":"man3/BN_cmp/#history","title":"HISTORY","text":"

Prior to OpenSSL 1.1.0, BN_is_zero(), BN_is_one(), BN_is_word(), BN_abs_is_word() and BN_is_odd() were macros.

The function BN_are_coprime() was added in OpenSSL 3.1.

"},{"location":"man3/BN_cmp/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_copy/","title":"BN_copy","text":""},{"location":"man3/BN_copy/#name","title":"NAME","text":"

BN_copy, BN_dup, BN_with_flags - copy BIGNUMs

"},{"location":"man3/BN_copy/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from);\n\nBIGNUM *BN_dup(const BIGNUM *from);\n\nvoid BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);\n
"},{"location":"man3/BN_copy/#description","title":"DESCRIPTION","text":"

BN_copy() copies from to to. BN_dup() creates a new BIGNUM containing the value from.

BN_with_flags creates a temporary shallow copy of b in dest. It places significant restrictions on the copied data. Applications that do no adhere to these restrictions may encounter unexpected side effects or crashes. For that reason use of this function is discouraged. Any flags provided in flags will be set in dest in addition to any flags already set in b. For example this might commonly be used to create a temporary copy of a BIGNUM with the BN_FLG_CONSTTIME flag set for constant time operations. The temporary copy in dest will share some internal state with b. For this reason the following restrictions apply to the use of dest:

"},{"location":"man3/BN_copy/#return-values","title":"RETURN VALUES","text":"

BN_copy() returns to on success, NULL on error. BN_dup() returns the new BIGNUM, and NULL on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_copy/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/BN_copy/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_generate_prime/","title":"BN_generate_prime","text":""},{"location":"man3/BN_generate_prime/#name","title":"NAME","text":"

BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex, BN_check_prime, BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality

"},{"location":"man3/BN_generate_prime/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe,\n                          const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb,\n                          BN_CTX *ctx);\n\nint BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,\n                         const BIGNUM *rem, BN_GENCB *cb);\n\nint BN_check_prime(const BIGNUM *p, BN_CTX *ctx, BN_GENCB *cb);\n\nint BN_GENCB_call(BN_GENCB *cb, int a, int b);\n\nBN_GENCB *BN_GENCB_new(void);\n\nvoid BN_GENCB_free(BN_GENCB *cb);\n\nvoid BN_GENCB_set_old(BN_GENCB *gencb,\n                      void (*callback)(int, int, void *), void *cb_arg);\n\nvoid BN_GENCB_set(BN_GENCB *gencb,\n                  int (*callback)(int, int, BN_GENCB *), void *cb_arg);\n\nvoid *BN_GENCB_get_arg(BN_GENCB *cb);\n

The following functions have been deprecated since OpenSSL 0.9.8, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,\n                          BIGNUM *rem, void (*callback)(int, int, void *),\n                          void *cb_arg);\n\nint BN_is_prime(const BIGNUM *p, int nchecks,\n                void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg);\n\nint BN_is_prime_fasttest(const BIGNUM *p, int nchecks,\n                         void (*callback)(int, int, void *), BN_CTX *ctx,\n                         void *cb_arg, int do_trial_division);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);\n\nint BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,\n                            int do_trial_division, BN_GENCB *cb);\n
"},{"location":"man3/BN_generate_prime/#description","title":"DESCRIPTION","text":"

BN_generate_prime_ex2() generates a pseudo-random prime number of at least bit length bits using the BN_CTX provided in ctx. The value of ctx must not be NULL.

The returned number is probably prime with a negligible error. The maximum error rate is 2^-128. It's 2^-287 for a 512 bit prime, 2^-435 for a 1024 bit prime, 2^-648 for a 2048 bit prime, and lower than 2^-882 for primes larger than 2048 bit.

If add is NULL the returned prime number will have exact bit length bits with the top most two bits set.

If ret is not NULL, it will be used to store the number.

If cb is not NULL, it is used as follows:

The prime may have to fulfill additional requirements for use in Diffie-Hellman key exchange:

If add is not NULL, the prime will fulfill the condition p % add == rem (p % add == 1 if rem == NULL) in order to suit a given generator.

If safe is true, it will be a safe prime (i.e. a prime p so that (p-1)/2 is also prime). If safe is true, and rem == NULL the condition will be p % add == 3. It is recommended that add is a multiple of 4.

The random generator must be seeded prior to calling BN_generate_prime_ex(). If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail. The random number generator configured for the OSSL_LIB_CTX associated with ctx will be used.

BN_generate_prime_ex() is the same as BN_generate_prime_ex2() except that no ctx parameter is passed. In this case the random number generator associated with the default OSSL_LIB_CTX will be used.

BN_check_prime(), BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and BN_is_prime_fasttest() test if the number p is prime. The functions tests until one of the tests shows that p is composite, or all the tests passed. If p passes all these tests, it is considered a probable prime.

The test performed on p are trial division by a number of small primes and rounds of the of the Miller-Rabin probabilistic primality test.

The functions do at least 64 rounds of the Miller-Rabin test giving a maximum false positive rate of 2^-128. If the size of p is more than 2048 bits, they do at least 128 rounds giving a maximum false positive rate of 2^-256.

If nchecks is larger than the minimum above (64 or 128), nchecks rounds of the Miller-Rabin test will be done.

If do_trial_division set to 0, the trial division will be skipped. BN_is_prime_ex() and BN_is_prime() always skip the trial division.

BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and BN_is_prime_fasttest() are deprecated.

BN_is_prime_fasttest() and BN_is_prime() behave just like BN_is_prime_fasttest_ex() and BN_is_prime_ex() respectively, but with the old style call back.

ctx is a preallocated BN_CTX (to save the overhead of allocating and freeing the structure in a loop), or NULL.

If the trial division is done, and no divisors are found and cb is not NULL, BN_GENCB_call(cb, 1, -1) is called.

After each round of the Miller-Rabin probabilistic primality test, if cb is not NULL, BN_GENCB_call(cb, 1, j) is called with j the iteration (j = 0, 1, ...).

BN_GENCB_call() calls the callback function held in the BN_GENCB structure and passes the ints a and b as arguments. There are two types of BN_GENCB structure that are supported: \"new\" style and \"old\" style. New programs should prefer the \"new\" style, whilst the \"old\" style is provided for backwards compatibility purposes.

A BN_GENCB structure should be created through a call to BN_GENCB_new(), and freed through a call to BN_GENCB_free(). If the argument is NULL, nothing is done.

For \"new\" style callbacks a BN_GENCB structure should be initialised with a call to BN_GENCB_set(), where gencb is a BN_GENCB *, callback is of type int (*callback)(int, int, BN_GENCB *) and cb_arg is a void *. \"Old\" style callbacks are the same except they are initialised with a call to BN_GENCB_set_old() and callback is of type void (*callback)(int, int, void *).

A callback is invoked through a call to BN_GENCB_call. This will check the type of the callback and will invoke callback(a, b, gencb) for new style callbacks or callback(a, b, cb_arg) for old style.

It is possible to obtain the argument associated with a BN_GENCB structure (set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.

BN_generate_prime() (deprecated) works in the same way as BN_generate_prime_ex() but expects an old-style callback function directly in the callback parameter, and an argument to pass to it in the cb_arg. BN_is_prime() and BN_is_prime_fasttest() can similarly be compared to BN_is_prime_ex() and BN_is_prime_fasttest_ex(), respectively.

"},{"location":"man3/BN_generate_prime/#return-values","title":"RETURN VALUES","text":"

BN_generate_prime_ex() return 1 on success or 0 on error.

BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime(), BN_is_prime_fasttest() and BN_check_prime return 0 if the number is composite, 1 if it is prime with an error probability of less than 0.25^nchecks, and -1 on error.

BN_generate_prime() returns the prime number on success, NULL otherwise.

BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or NULL otherwise.

BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB structure.

Callback functions should return 1 on success or 0 on error.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_generate_prime/#removed-functionality","title":"REMOVED FUNCTIONALITY","text":"

As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure directly, as in:

BN_GENCB callback;\n

Instead applications should create a BN_GENCB structure using BN_GENCB_new:

BN_GENCB *callback;\ncallback = BN_GENCB_new();\nif (!callback)\n    /* error */\n...\nBN_GENCB_free(callback);\n
"},{"location":"man3/BN_generate_prime/#see-also","title":"SEE ALSO","text":"

DH_generate_parameters(3), DSA_generate_parameters(3), RSA_generate_key(3), ERR_get_error(3), RAND_bytes(3), RAND(7)

"},{"location":"man3/BN_generate_prime/#history","title":"HISTORY","text":"

The BN_is_prime_ex() and BN_is_prime_fasttest_ex() functions were deprecated in OpenSSL 3.0.

The BN_GENCB_new(), BN_GENCB_free(), and BN_GENCB_get_arg() functions were added in OpenSSL 1.1.0.

BN_check_prime() was added in OpenSSL 3.0.

"},{"location":"man3/BN_generate_prime/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_mod_exp_mont/","title":"BN_mod_exp_mont","text":""},{"location":"man3/BN_mod_exp_mont/#name","title":"NAME","text":"

BN_mod_exp_mont, BN_mod_exp_mont_consttime, BN_mod_exp_mont_consttime_x2 - Montgomery exponentiation

"},{"location":"man3/BN_mod_exp_mont/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_mod_exp_mont(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p,\n                    const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont);\n\nint BN_mod_exp_mont_consttime(BIGNUM *rr, const BIGNUM *a, const BIGNUM *p,\n                              const BIGNUM *m, BN_CTX *ctx,\n                              BN_MONT_CTX *in_mont);\n\nint BN_mod_exp_mont_consttime_x2(BIGNUM *rr1, const BIGNUM *a1,\n                                 const BIGNUM *p1, const BIGNUM *m1,\n                                 BN_MONT_CTX *in_mont1, BIGNUM *rr2,\n                                 const BIGNUM *a2, const BIGNUM *p2,\n                                 const BIGNUM *m2, BN_MONT_CTX *in_mont2,\n                                 BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_exp_mont/#description","title":"DESCRIPTION","text":"

BN_mod_exp_mont() computes a to the p-th power modulo m (rr=a^p % m) using Montgomery multiplication. in_mont is a Montgomery context and can be NULL. In the case in_mont is NULL, it will be initialized within the function, so you can save time on initialization if you provide it in advance.

BN_mod_exp_mont_consttime() computes a to the p-th power modulo m (rr=a^p % m) using Montgomery multiplication. It is a variant of BN_mod_exp_mont(3) that uses fixed windows and the special precomputation memory layout to limit data-dependency to a minimum to protect secret exponents. It is called automatically when BN_mod_exp_mont(3) is called with parameters a, p, m, any of which have BN_FLG_CONSTTIME flag.

BN_mod_exp_mont_consttime_x2() computes two independent exponentiations a1 to the p1-th power modulo m1 (rr1=a1^p1 % m1) and a2 to the p2-th power modulo m2 (rr2=a2^p2 % m2) using Montgomery multiplication. For some fixed and equal modulus sizes m1 and m2 it uses optimizations that allow to speedup two exponentiations. In all other cases the function reduces to two calls of BN_mod_exp_mont_consttime(3).

"},{"location":"man3/BN_mod_exp_mont/#return-values","title":"RETURN VALUES","text":"

For all functions 1 is returned for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_exp_mont/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_mod_exp_mont(3)

"},{"location":"man3/BN_mod_exp_mont/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_mod_inverse/","title":"BN_mod_inverse","text":""},{"location":"man3/BN_mod_inverse/#name","title":"NAME","text":"

BN_mod_inverse - compute inverse modulo n

"},{"location":"man3/BN_mod_inverse/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,\n                       BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_inverse/#description","title":"DESCRIPTION","text":"

BN_mod_inverse() computes the inverse of a modulo n places the result in r ((a*r)%n==1). If r is NULL, a new BIGNUM is created.

ctx is a previously allocated BN_CTX used for temporary variables. r may be the same BIGNUM as a.

"},{"location":"man3/BN_mod_inverse/#notes","title":"NOTES","text":"

It is an error to use the same BIGNUM as n.

"},{"location":"man3/BN_mod_inverse/#return-values","title":"RETURN VALUES","text":"

BN_mod_inverse() returns the BIGNUM containing the inverse, and NULL on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_inverse/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3)

"},{"location":"man3/BN_mod_inverse/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_mod_mul_montgomery/","title":"BN_mod_mul_montgomery","text":""},{"location":"man3/BN_mod_mul_montgomery/#name","title":"NAME","text":"

BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, BN_from_montgomery, BN_to_montgomery - Montgomery multiplication

"},{"location":"man3/BN_mod_mul_montgomery/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_MONT_CTX *BN_MONT_CTX_new(void);\nvoid BN_MONT_CTX_free(BN_MONT_CTX *mont);\n\nint BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);\nBN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);\n\nint BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,\n                          BN_MONT_CTX *mont, BN_CTX *ctx);\n\nint BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,\n                       BN_CTX *ctx);\n\nint BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,\n                     BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_mul_montgomery/#description","title":"DESCRIPTION","text":"

These functions implement Montgomery multiplication. They are used automatically when BN_mod_exp(3) is called with suitable input, but they may be useful when several operations are to be performed using the same modulus.

BN_MONT_CTX_new() allocates and initializes a BN_MONT_CTX structure.

BN_MONT_CTX_set() sets up the mont structure from the modulus m by precomputing its inverse and a value R.

BN_MONT_CTX_copy() copies the BN_MONT_CTX from to to.

BN_MONT_CTX_free() frees the components of the BN_MONT_CTX, and, if it was created by BN_MONT_CTX_new(), also the structure itself. If mont is NULL, nothing is done.

BN_mod_mul_montgomery() computes Mont(a,b):=a*b*R^-1 and places the result in r.

BN_from_montgomery() performs the Montgomery reduction r = a*R^-1.

BN_to_montgomery() computes Mont(a,R^2), i.e. a*R. Note that a must be nonnegative and smaller than the modulus.

For all functions, ctx is a previously allocated BN_CTX used for temporary variables.

"},{"location":"man3/BN_mod_mul_montgomery/#return-values","title":"RETURN VALUES","text":"

BN_MONT_CTX_new() returns the newly allocated BN_MONT_CTX, and NULL on error.

BN_MONT_CTX_free() has no return value.

For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_mul_montgomery/#warnings","title":"WARNINGS","text":"

The inputs must be reduced modulo m, otherwise the result will be outside the expected range.

"},{"location":"man3/BN_mod_mul_montgomery/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3), BN_CTX_new(3)

"},{"location":"man3/BN_mod_mul_montgomery/#history","title":"HISTORY","text":"

BN_MONT_CTX_init() was removed in OpenSSL 1.1.0

"},{"location":"man3/BN_mod_mul_montgomery/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_mod_mul_reciprocal/","title":"BN_mod_mul_reciprocal","text":""},{"location":"man3/BN_mod_mul_reciprocal/#name","title":"NAME","text":"

BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using reciprocal

"},{"location":"man3/BN_mod_mul_reciprocal/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBN_RECP_CTX *BN_RECP_CTX_new(void);\nvoid BN_RECP_CTX_free(BN_RECP_CTX *recp);\n\nint BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);\n\nint BN_div_recp(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, BN_RECP_CTX *recp,\n                BN_CTX *ctx);\n\nint BN_mod_mul_reciprocal(BIGNUM *r, const BIGNUM *a, const BIGNUM *b,\n                          BN_RECP_CTX *recp, BN_CTX *ctx);\n
"},{"location":"man3/BN_mod_mul_reciprocal/#description","title":"DESCRIPTION","text":"

BN_mod_mul_reciprocal() can be used to perform an efficient BN_mod_mul(3) operation when the operation will be performed repeatedly with the same modulus. It computes r=(a*b)%m using recp=1/m, which is set as described below. ctx is a previously allocated BN_CTX used for temporary variables.

BN_RECP_CTX_new() allocates and initializes a BN_RECP structure.

BN_RECP_CTX_free() frees the components of the BN_RECP, and, if it was created by BN_RECP_CTX_new(), also the structure itself. If recp is NULL, nothing is done.

BN_RECP_CTX_set() stores m in recp and sets it up for computing 1/m and shifting it left by BN_num_bits(m)+1 to make it an integer. The result and the number of bits it was shifted left will later be stored in recp.

BN_div_recp() divides a by m using recp. It places the quotient in dv and the remainder in rem.

The BN_RECP_CTX structure cannot be shared between threads.

"},{"location":"man3/BN_mod_mul_reciprocal/#return-values","title":"RETURN VALUES","text":"

BN_RECP_CTX_new() returns the newly allocated BN_RECP_CTX, and NULL on error.

BN_RECP_CTX_free() has no return value.

For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_mod_mul_reciprocal/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), BN_add(3), BN_CTX_new(3)

"},{"location":"man3/BN_mod_mul_reciprocal/#history","title":"HISTORY","text":"

BN_RECP_CTX_init() was removed in OpenSSL 1.1.0

"},{"location":"man3/BN_mod_mul_reciprocal/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_new/","title":"BN_new","text":""},{"location":"man3/BN_new/#name","title":"NAME","text":"

BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs

"},{"location":"man3/BN_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nBIGNUM *BN_new(void);\n\nBIGNUM *BN_secure_new(void);\n\nvoid BN_clear(BIGNUM *a);\n\nvoid BN_free(BIGNUM *a);\n\nvoid BN_clear_free(BIGNUM *a);\n
"},{"location":"man3/BN_new/#description","title":"DESCRIPTION","text":"

BN_new() allocates and initializes a BIGNUM structure. BN_secure_new() does the same except that the secure heap OPENSSL_secure_malloc(3) is used to store the value.

BN_clear() is used to destroy sensitive data such as keys when they are no longer needed. It erases the memory used by a and sets it to the value 0. If a is NULL, nothing is done.

BN_free() frees the components of the BIGNUM, and if it was created by BN_new(), also the structure itself. BN_clear_free() additionally overwrites the data before the memory is returned to the system. If a is NULL, nothing is done.

"},{"location":"man3/BN_new/#return-values","title":"RETURN VALUES","text":"

BN_new() and BN_secure_new() return a pointer to the BIGNUM initialised to the value 0. If the allocation fails, they return NULL and set an error code that can be obtained by ERR_get_error(3).

BN_clear(), BN_free() and BN_clear_free() have no return values.

"},{"location":"man3/BN_new/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), OPENSSL_secure_malloc(3)

"},{"location":"man3/BN_new/#history","title":"HISTORY","text":"

BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.

"},{"location":"man3/BN_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_num_bytes/","title":"BN_num_bytes","text":""},{"location":"man3/BN_num_bytes/#name","title":"NAME","text":"

BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size

"},{"location":"man3/BN_num_bytes/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_num_bytes(const BIGNUM *a);\n\nint BN_num_bits(const BIGNUM *a);\n\nint BN_num_bits_word(BN_ULONG w);\n
"},{"location":"man3/BN_num_bytes/#description","title":"DESCRIPTION","text":"

BN_num_bytes() returns the size of a BIGNUM in bytes.

BN_num_bits_word() returns the number of significant bits in a word. If we take 0x00000432 as an example, it returns 11, not 16, not 32. Basically, except for a zero, it returns floor(log2(w))+1.

BN_num_bits() returns the number of significant bits in a BIGNUM, following the same principle as BN_num_bits_word().

BN_num_bytes() is a macro.

"},{"location":"man3/BN_num_bytes/#return-values","title":"RETURN VALUES","text":"

The size.

"},{"location":"man3/BN_num_bytes/#notes","title":"NOTES","text":"

Some have tried using BN_num_bits() on individual numbers in RSA keys, DH keys and DSA keys, and found that they don't always come up with the number of bits they expected (something like 512, 1024, 2048, ...). This is because generating a number with some specific number of bits doesn't always set the highest bits, thereby making the number of significant bits a little lower. If you want to know the \"key size\" of such a key, either use functions like RSA_size(), DH_size() and DSA_size(), or use BN_num_bytes() and multiply with 8 (although there's no real guarantee that will match the \"key size\", just a lot more probability).

"},{"location":"man3/BN_num_bytes/#see-also","title":"SEE ALSO","text":"

DH_size(3), DSA_size(3), RSA_size(3)

"},{"location":"man3/BN_num_bytes/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_rand/","title":"BN_rand","text":""},{"location":"man3/BN_rand/#name","title":"NAME","text":"

BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand, BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range, BN_pseudo_rand_range - generate pseudo-random number

"},{"location":"man3/BN_rand/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,\n               unsigned int strength, BN_CTX *ctx);\nint BN_rand(BIGNUM *rnd, int bits, int top, int bottom);\n\nint BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,\n                    unsigned int strength, BN_CTX *ctx);\nint BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);\n\nint BN_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,\n                     BN_CTX *ctx);\nint BN_rand_range(BIGNUM *rnd, const BIGNUM *range);\n\nint BN_priv_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,\n                          BN_CTX *ctx);\nint BN_priv_rand_range(BIGNUM *rnd, const BIGNUM *range);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);\nint BN_pseudo_rand_range(BIGNUM *rnd, const BIGNUM *range);\n
"},{"location":"man3/BN_rand/#description","title":"DESCRIPTION","text":"

BN_rand_ex() generates a cryptographically strong pseudo-random number of bits in length and security strength at least strength bits using the random number generator for the library context associated with ctx. The function stores the generated data in rnd. The parameter ctx may be NULL in which case the default library context is used. If bits is less than zero, or too small to accommodate the requirements specified by the top and bottom parameters, an error is returned. The top parameters specifies requirements on the most significant bit of the generated number. If it is BN_RAND_TOP_ANY, there is no constraint. If it is BN_RAND_TOP_ONE, the top bit must be one. If it is BN_RAND_TOP_TWO, the two most significant bits of the number will be set to 1, so that the product of two such random numbers will always have 2*bits length. If bottom is BN_RAND_BOTTOM_ODD, the number will be odd; if it is BN_RAND_BOTTOM_ANY it can be odd or even. If bits is 1 then top cannot also be BN_RAND_TOP_TWO.

BN_rand() is the same as BN_rand_ex() except that the default library context is always used.

BN_rand_range_ex() generates a cryptographically strong pseudo-random number rnd, of security strength at least strength bits, in the range 0 <= rnd < range using the random number generator for the library context associated with ctx. The parameter ctx may be NULL in which case the default library context is used.

BN_rand_range() is the same as BN_rand_range_ex() except that the default library context is always used.

BN_priv_rand_ex(), BN_priv_rand(), BN_priv_rand_rand_ex() and BN_priv_rand_range() have the same semantics as BN_rand_ex(), BN_rand(), BN_rand_range_ex() and BN_rand_range() respectively. They are intended to be used for generating values that should remain private, and mirror the same difference between RAND_bytes(3) and RAND_priv_bytes(3).

"},{"location":"man3/BN_rand/#notes","title":"NOTES","text":"

Always check the error return value of these functions and do not take randomness for granted: an error occurs if the CSPRNG has not been seeded with enough randomness to ensure an unpredictable byte sequence.

"},{"location":"man3/BN_rand/#return-values","title":"RETURN VALUES","text":"

The functions return 1 on success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_rand/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), RAND_add(3), RAND_bytes(3), RAND_priv_bytes(3), RAND(7), EVP_RAND(7)

"},{"location":"man3/BN_rand/#history","title":"HISTORY","text":""},{"location":"man3/BN_rand/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_security_bits/","title":"BN_security_bits","text":""},{"location":"man3/BN_security_bits/#name","title":"NAME","text":"

BN_security_bits - returns bits of security based on given numbers

"},{"location":"man3/BN_security_bits/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_security_bits(int L, int N);\n
"},{"location":"man3/BN_security_bits/#description","title":"DESCRIPTION","text":"

BN_security_bits() returns the number of bits of security provided by a specific algorithm and a particular key size. The bits of security is defined in NIST SP800-57. Currently, BN_security_bits() support two types of asymmetric algorithms: the FFC (Finite Field Cryptography) and IFC (Integer Factorization Cryptography). For FFC, e.g., DSA and DH, both parameters L and N are used to decide the bits of security, where L is the size of the public key and N is the size of the private key. For IFC, e.g., RSA, only L is used and it's commonly considered to be the key size (modulus).

"},{"location":"man3/BN_security_bits/#return-values","title":"RETURN VALUES","text":"

Number of security bits.

"},{"location":"man3/BN_security_bits/#notes","title":"NOTES","text":"

ECC (Elliptic Curve Cryptography) is not covered by the BN_security_bits() function. The symmetric algorithms are not covered neither.

"},{"location":"man3/BN_security_bits/#see-also","title":"SEE ALSO","text":"

DH_security_bits(3), DSA_security_bits(3), RSA_security_bits(3)

"},{"location":"man3/BN_security_bits/#history","title":"HISTORY","text":"

The BN_security_bits() function was added in OpenSSL 1.1.0.

"},{"location":"man3/BN_security_bits/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_set_bit/","title":"BN_set_bit","text":""},{"location":"man3/BN_set_bit/#name","title":"NAME","text":"

BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift, BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs

"},{"location":"man3/BN_set_bit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nint BN_set_bit(BIGNUM *a, int n);\nint BN_clear_bit(BIGNUM *a, int n);\n\nint BN_is_bit_set(const BIGNUM *a, int n);\n\nint BN_mask_bits(BIGNUM *a, int n);\n\nint BN_lshift(BIGNUM *r, const BIGNUM *a, int n);\nint BN_lshift1(BIGNUM *r, BIGNUM *a);\n\nint BN_rshift(BIGNUM *r, BIGNUM *a, int n);\nint BN_rshift1(BIGNUM *r, BIGNUM *a);\n
"},{"location":"man3/BN_set_bit/#description","title":"DESCRIPTION","text":"

BN_set_bit() sets bit n in a to 1 (a|=(1<<n)). The number is expanded if necessary.

BN_clear_bit() sets bit n in a to 0 (a&=~(1<<n)). An error occurs if a is shorter than n bits.

BN_is_bit_set() tests if bit n in a is set.

BN_mask_bits() truncates a to an n bit number (a&=~((~0)<<n)). An error occurs if n is negative. An error is also returned if the internal representation of a is already shorter than n bits. The internal representation depends on the platform's word size, and this error can be safely ignored. Use BN_num_bits(3) to determine the exact number of bits if needed.

BN_lshift() shifts a left by n bits and places the result in r (r=a*2^n). Note that n must be nonnegative. BN_lshift1() shifts a left by one and places the result in r (r=2*a).

BN_rshift() shifts a right by n bits and places the result in r (r=a/2^n). Note that n must be nonnegative. BN_rshift1() shifts a right by one and places the result in r (r=a/2).

For the shift functions, r and a may be the same variable.

"},{"location":"man3/BN_set_bit/#return-values","title":"RETURN VALUES","text":"

BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.

All other functions return 1 for success, 0 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/BN_set_bit/#see-also","title":"SEE ALSO","text":"

BN_num_bytes(3), BN_add(3)

"},{"location":"man3/BN_set_bit/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_swap/","title":"BN_swap","text":""},{"location":"man3/BN_swap/#name","title":"NAME","text":"

BN_swap - exchange BIGNUMs

"},{"location":"man3/BN_swap/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nvoid BN_swap(BIGNUM *a, BIGNUM *b);\n
"},{"location":"man3/BN_swap/#description","title":"DESCRIPTION","text":"

BN_swap() exchanges the values of a and b.

"},{"location":"man3/BN_swap/#return-values","title":"RETURN VALUES","text":"

BN_swap() does not return a value.

"},{"location":"man3/BN_swap/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BN_zero/","title":"BN_zero","text":""},{"location":"man3/BN_zero/#name","title":"NAME","text":"

BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment operations

"},{"location":"man3/BN_zero/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/bn.h>\n\nvoid BN_zero(BIGNUM *a);\nint BN_one(BIGNUM *a);\n\nconst BIGNUM *BN_value_one(void);\n\nint BN_set_word(BIGNUM *a, BN_ULONG w);\nunsigned BN_ULONG BN_get_word(BIGNUM *a);\n
"},{"location":"man3/BN_zero/#description","title":"DESCRIPTION","text":"

BN_ULONG is a macro that will be an unsigned integral type optimized for the most efficient implementation on the local platform.

BN_zero(), BN_one() and BN_set_word() set a to the values 0, 1 and w respectively. BN_zero() and BN_one() are macros.

BN_value_one() returns a BIGNUM constant of value 1. This constant is useful for use in comparisons and assignment.

BN_get_word() returns a, if it can be represented as a BN_ULONG.

"},{"location":"man3/BN_zero/#return-values","title":"RETURN VALUES","text":"

BN_get_word() returns the value a, or all-bits-set if a cannot be represented as a single integer.

BN_one() and BN_set_word() return 1 on success, 0 otherwise. BN_value_one() returns the constant. BN_zero() never fails and returns no value.

"},{"location":"man3/BN_zero/#bugs","title":"BUGS","text":"

If a BIGNUM is equal to the value of all-bits-set, it will collide with the error condition returned by BN_get_word() which uses that as an error value.

BN_ULONG should probably be a typedef.

"},{"location":"man3/BN_zero/#see-also","title":"SEE ALSO","text":"

BN_bn2bin(3)

"},{"location":"man3/BN_zero/#history","title":"HISTORY","text":"

In OpenSSL 0.9.8, BN_zero() was changed to not return a value; previous versions returned an int.

"},{"location":"man3/BN_zero/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/BUF_MEM_new/","title":"BUF_MEM_new","text":""},{"location":"man3/BUF_MEM_new/#name","title":"NAME","text":"

BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow, BUF_MEM_grow_clean, BUF_reverse - simple character array structure

"},{"location":"man3/BUF_MEM_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/buffer.h>\n\nBUF_MEM *BUF_MEM_new(void);\n\nBUF_MEM *BUF_MEM_new_ex(unsigned long flags);\n\nvoid BUF_MEM_free(BUF_MEM *a);\n\nint BUF_MEM_grow(BUF_MEM *str, int len);\nsize_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len);\n\nvoid BUF_reverse(unsigned char *out, const unsigned char *in, size_t size);\n
"},{"location":"man3/BUF_MEM_new/#description","title":"DESCRIPTION","text":"

The buffer library handles simple character arrays. Buffers are used for various purposes in the library, most notably memory BIOs.

BUF_MEM_new() allocates a new buffer of zero size.

BUF_MEM_new_ex() allocates a buffer with the specified flags. The flag BUF_MEM_FLAG_SECURE specifies that the data pointer should be allocated on the secure heap; see CRYPTO_secure_malloc(3).

BUF_MEM_free() frees up an already existing buffer. The data is zeroed before freeing up in case the buffer contains sensitive data. If the argument is NULL, nothing is done.

BUF_MEM_grow() changes the size of an already existing buffer to len. Any data already in the buffer is preserved if it increases in size.

BUF_MEM_grow_clean() is similar to BUF_MEM_grow() but it sets any free'd or additionally-allocated memory to zero.

BUF_reverse() reverses size bytes at in into out. If in is NULL, the array is reversed in-place.

"},{"location":"man3/BUF_MEM_new/#return-values","title":"RETURN VALUES","text":"

BUF_MEM_new() returns the buffer or NULL on error.

BUF_MEM_free() has no return value.

BUF_MEM_grow() and BUF_MEM_grow_clean() return zero on error or the new size (i.e., len).

"},{"location":"man3/BUF_MEM_new/#see-also","title":"SEE ALSO","text":"

bio(7), CRYPTO_secure_malloc(3).

"},{"location":"man3/BUF_MEM_new/#history","title":"HISTORY","text":"

The BUF_MEM_new_ex() function was added in OpenSSL 1.1.0.

"},{"location":"man3/BUF_MEM_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMAC_CTX/","title":"CMAC_CTX","text":""},{"location":"man3/CMAC_CTX/#name","title":"NAME","text":"

CMAC_CTX, CMAC_CTX_new, CMAC_CTX_cleanup, CMAC_CTX_free, CMAC_CTX_get0_cipher_ctx, CMAC_CTX_copy, CMAC_Init, CMAC_Update, CMAC_Final, CMAC_resume - create cipher-based message authentication codes

"},{"location":"man3/CMAC_CTX/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cmac.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be disabled entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7).

typedef struct CMAC_CTX_st CMAC_CTX;\n\nCMAC_CTX *CMAC_CTX_new(void);\nvoid CMAC_CTX_cleanup(CMAC_CTX *ctx);\nvoid CMAC_CTX_free(CMAC_CTX *ctx);\nEVP_CIPHER_CTX *CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx);\nint CMAC_CTX_copy(CMAC_CTX *out, const CMAC_CTX *in);\nint CMAC_Init(CMAC_CTX *ctx, const void *key, size_t keylen,\n              const EVP_CIPHER *cipher, ENGINE *impl);\nint CMAC_Update(CMAC_CTX *ctx, const void *data, size_t dlen);\nint CMAC_Final(CMAC_CTX *ctx, unsigned char *out, size_t *poutlen);\nint CMAC_resume(CMAC_CTX *ctx);\n
"},{"location":"man3/CMAC_CTX/#description","title":"DESCRIPTION","text":"

The low-level MAC functions documented on this page are deprecated. Applications should use the new EVP_MAC(3) interface. Specifically, utilize the following functions for MAC operations:

Alternatively, for a single-step MAC computation, use the EVP_Q_mac(3) function.

The CMAC_CTX type is a structure used for the provision of CMAC (Cipher-based Message Authentication Code) operations.

CMAC_CTX_new() creates a new CMAC_CTX structure and returns a pointer to it.

CMAC_CTX_cleanup() resets the CMAC_CTX structure, clearing any internal data but not freeing the structure itself.

CMAC_CTX_free() frees the CMAC_CTX structure and any associated resources. If the argument is NULL, no action is taken.

CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal EVP_CIPHER_CTX structure within the CMAC_CTX.

CMAC_CTX_copy() copies the state from one CMAC_CTX structure to another.

CMAC_Init() initializes the CMAC_CTX structure for a new CMAC calculation with the specified key, key length, and cipher type. Optionally, an ENGINE can be provided.

CMAC_Update() processes data to be included in the CMAC calculation. This function can be called multiple times to update the context with additional data.

CMAC_Final() finalizes the CMAC calculation and retrieves the resulting MAC value. The output is stored in the provided buffer, and the length is stored in the variable pointed to by poutlen. To determine the required buffer size, call with out set to NULL, which stores only the length in poutlen. Allocate a buffer of this size and call CMAC_Final() again with the allocated buffer to retrieve the MAC.

CMAC_resume() resumes a previously finalized CMAC calculation, allowing additional data to be processed and a new MAC to be generated.

"},{"location":"man3/CMAC_CTX/#return-values","title":"RETURN VALUES","text":"

CMAC_CTX_new() returns a pointer to a new CMAC_CTX structure or NULL if an error occurs.

CMAC_CTX_get0_cipher_ctx() returns a pointer to the internal EVP_CIPHER_CTX structure, or NULL if an error occurs.

CMAC_CTX_copy(), CMAC_Init(), CMAC_Update(), CMAC_Final() and CMAC_resume() return 1 for success or 0 if an error occurs.

"},{"location":"man3/CMAC_CTX/#history","title":"HISTORY","text":"

All functions described here were deprecated in OpenSSL 3.0. For replacements, see EVP_MAC_CTX_new(3), EVP_MAC_CTX_free(3), EVP_MAC_init(3), EVP_MAC_update(3), and EVP_MAC_final(3).

"},{"location":"man3/CMAC_CTX/#copyright","title":"COPYRIGHT","text":"

Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_EncryptedData_decrypt/","title":"CMS_EncryptedData_decrypt","text":""},{"location":"man3/CMS_EncryptedData_decrypt/#name","title":"NAME","text":"

CMS_EncryptedData_decrypt, CMS_EnvelopedData_decrypt - Decrypt CMS EncryptedData or EnvelopedData

"},{"location":"man3/CMS_EncryptedData_decrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_EncryptedData_decrypt(CMS_ContentInfo *cms,\n                              const unsigned char *key, size_t keylen,\n                              BIO *dcont, BIO *out, unsigned int flags);\n\nBIO *CMS_EnvelopedData_decrypt(CMS_EnvelopedData *env, BIO *detached_data,\n                               EVP_PKEY *pkey, X509 *cert,\n                               ASN1_OCTET_STRING *secret, unsigned int flags,\n                               OSSL_LIB_CTX *libctx, const char *propq);\n
"},{"location":"man3/CMS_EncryptedData_decrypt/#description","title":"DESCRIPTION","text":"

CMS_EncryptedData_decrypt() decrypts a cms EncryptedData object using the symmetric key of size keylen bytes. out is a BIO to write the content to and flags is an optional set of flags. dcont is used in the rare case where the encrypted content is detached. It will normally be set to NULL.

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

CMS_EnvelopedData_decrypt() decrypts, similarly to CMS_decrypt(3), a CMS EnvelopedData object env using the symmetric key secret if it is not NULL, otherwise the private key of the recipient pkey. If pkey is given, it is recommended to provide also the associated certificate in cert - see CMS_decrypt(3) and the NOTES on cert there. The optional parameters flags and dcont are used as described above. The optional parameters library context libctx and property query propq are used when retrieving algorithms from providers.

"},{"location":"man3/CMS_EncryptedData_decrypt/#return-values","title":"RETURN VALUES","text":"

CMS_EncryptedData_decrypt() returns 0 if an error occurred otherwise returns 1.

CMS_EnvelopedData_decrypt() returns NULL if an error occurred, otherwise a BIO containing the decypted content.

"},{"location":"man3/CMS_EncryptedData_decrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_EncryptedData_encrypt(3), CMS_decrypt(3)

"},{"location":"man3/CMS_EncryptedData_decrypt/#history","title":"HISTORY","text":"

CMS_EnvelopedData_decrypt() was added in OpenSSL 3.2.

"},{"location":"man3/CMS_EncryptedData_decrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_EncryptedData_encrypt/","title":"CMS_EncryptedData_encrypt","text":""},{"location":"man3/CMS_EncryptedData_encrypt/#name","title":"NAME","text":"

CMS_EncryptedData_encrypt_ex, CMS_EncryptedData_encrypt - Create CMS EncryptedData

"},{"location":"man3/CMS_EncryptedData_encrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_EncryptedData_encrypt_ex(BIO *in,\n                                              const EVP_CIPHER *cipher,\n                                              const unsigned char *key,\n                                              size_t keylen,\n                                              unsigned int flags,\n                                              OSSL_LIB_CTX *ctx,\n                                              const char *propq);\n\nCMS_ContentInfo *CMS_EncryptedData_encrypt(BIO *in,\n    const EVP_CIPHER *cipher, const unsigned char *key, size_t keylen,\n    unsigned int flags);\n
"},{"location":"man3/CMS_EncryptedData_encrypt/#description","title":"DESCRIPTION","text":"

CMS_EncryptedData_encrypt_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_encrypted. in is a BIO containing the data to encrypt using cipher and the encryption key key of size keylen bytes. The library context libctx and the property query propq are used when retrieving algorithms from providers. flags is a set of optional flags.

The flags field supports the options CMS_DETACHED, CMS_STREAM and CMS_PARTIAL. Internally CMS_final() is called unless CMS_STREAM and/or CMS_PARTIAL is specified.

The algorithm passed in the cipher parameter must support ASN1 encoding of its parameters.

The CMS_ContentInfo structure can be freed using CMS_ContentInfo_free(3).

CMS_EncryptedData_encrypt() is similar to CMS_EncryptedData_encrypt_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_EncryptedData_encrypt/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_EncryptedData_encrypt_ex() and CMS_EncryptedData_encrypt() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_EncryptedData_encrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_final(3), CMS_EncryptedData_decrypt(3)

"},{"location":"man3/CMS_EncryptedData_encrypt/#history","title":"HISTORY","text":"

The CMS_EncryptedData_encrypt_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_EncryptedData_encrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_EnvelopedData_create/","title":"CMS_EnvelopedData_create","text":""},{"location":"man3/CMS_EnvelopedData_create/#name","title":"NAME","text":"

CMS_EnvelopedData_create_ex, CMS_EnvelopedData_create, CMS_AuthEnvelopedData_create, CMS_AuthEnvelopedData_create_ex - Create CMS envelope

"},{"location":"man3/CMS_EnvelopedData_create/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *\nCMS_EnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,\n                            const char *propq);\nCMS_ContentInfo *CMS_EnvelopedData_create(const EVP_CIPHER *cipher);\n\nCMS_ContentInfo *\nCMS_AuthEnvelopedData_create_ex(const EVP_CIPHER *cipher, OSSL_LIB_CTX *libctx,\n                                const char *propq);\nCMS_ContentInfo *CMS_AuthEnvelopedData_create(const EVP_CIPHER *cipher);\n
"},{"location":"man3/CMS_EnvelopedData_create/#description","title":"DESCRIPTION","text":"

CMS_EnvelopedData_create_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_enveloped. cipher is the symmetric cipher to use. The library context libctx and the property query propq are used when retrieving algorithms from providers.

CMS_AuthEnvelopedData_create_ex() creates a CMS_ContentInfo structure with a type NID_id_smime_ct_authEnvelopedData. cipher is the symmetric AEAD cipher to use. Currently only AES variants with GCM mode are supported. The library context libctx and the property query propq are used when retrieving algorithms from providers.

The algorithm passed in the cipher parameter must support ASN1 encoding of its parameters.

The recipients can be added later using CMS_add1_recipient_cert(3) or CMS_add0_recipient_key(3).

The CMS_ContentInfo structure needs to be finalized using CMS_final(3) and then freed using CMS_ContentInfo_free(3).

CMS_EnvelopedData_create() and CMS_AuthEnvelopedData_create() are similar to CMS_EnvelopedData_create_ex() and CMS_AuthEnvelopedData_create_ex() but use default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_EnvelopedData_create/#notes","title":"NOTES","text":"

Although CMS_EnvelopedData_create_ex(), and CMS_EnvelopedData_create(), CMS_AuthEnvelopedData_create_ex(), and CMS_AuthEnvelopedData_create() allocate a new CMS_ContentInfo structure, they are not usually used in applications. The wrappers CMS_encrypt(3) and CMS_decrypt(3) are often used instead.

"},{"location":"man3/CMS_EnvelopedData_create/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_EnvelopedData_create_ex(), CMS_EnvelopedData_create(), CMS_AuthEnvelopedData_create_ex(), and CMS_AuthEnvelopedData_create() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_EnvelopedData_create/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_encrypt(3), CMS_decrypt(3), CMS_final(3)

"},{"location":"man3/CMS_EnvelopedData_create/#history","title":"HISTORY","text":"

The CMS_EnvelopedData_create_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_EnvelopedData_create/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_add0_cert/","title":"CMS_add0_cert","text":""},{"location":"man3/CMS_add0_cert/#name","title":"NAME","text":"

CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls - CMS certificate and CRL utility functions

"},{"location":"man3/CMS_add0_cert/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert);\nint CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert);\nSTACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms);\n\nint CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl);\nint CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl);\nSTACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms);\n
"},{"location":"man3/CMS_add0_cert/#description","title":"DESCRIPTION","text":"

CMS_add0_cert() and CMS_add1_cert() add certificate cert to cms unless it is already present. This is used by CMS_sign_ex(3) and CMS_sign(3) and may be used before calling CMS_verify(3) to help chain building in certificate validation. As the 0 implies, CMS_add0_cert() adds cert internally to cms and on success it must not be freed up by the caller. In contrast, the caller of CMS_add1_cert() must free cert. cms must be of type signed data or (authenticated) enveloped data. For signed data, such a certificate can be used when signing or verifying to fill in the signer certificate or to provide an extra CA certificate that may be needed for chain building in certificate validation.

CMS_get1_certs() returns all certificates in cms.

CMS_add0_crl() and CMS_add1_crl() add CRL crl to cms. cms must be of type signed data or (authenticated) enveloped data. For signed data, such a CRL may be used in certificate validation with CMS_verify(3). It may be given both for inclusion when signing a CMS message and when verifying a signed CMS message.

CMS_get1_crls() returns all CRLs in cms.

"},{"location":"man3/CMS_add0_cert/#notes","title":"NOTES","text":"

The CMS_ContentInfo structure cms must be of type signed data or enveloped data or authenticated enveloped data or an error will be returned.

For signed data, certificates and CRLs are added to the certificates and crls fields of SignedData structure. For enveloped data they are added to OriginatorInfo.

"},{"location":"man3/CMS_add0_cert/#return-values","title":"RETURN VALUES","text":"

CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return 1 for success and 0 for failure.

CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs or NULL if there are none or an error occurs. The only error which will occur in practice is if the cms type is invalid.

"},{"location":"man3/CMS_add0_cert/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_sign_ex(3), CMS_verify(3), CMS_encrypt(3)

"},{"location":"man3/CMS_add0_cert/#history","title":"HISTORY","text":"

CMS_add0_cert() and CMS_add1_cert() have been changed in OpenSSL 3.2 not to throw an error if a certificate to be added is already present.

"},{"location":"man3/CMS_add0_cert/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_add1_recipient_cert/","title":"CMS_add1_recipient_cert","text":""},{"location":"man3/CMS_add1_recipient_cert/#name","title":"NAME","text":"

CMS_add1_recipient, CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure

"},{"location":"man3/CMS_add1_recipient_cert/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_RecipientInfo *CMS_add1_recipient(CMS_ContentInfo *cms, X509 *recip,\n                                      EVP_PKEY *originatorPrivKey,\n                                      X509 *originator, unsigned int flags);\n\nCMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,\n                                           X509 *recip, unsigned int flags);\n\nCMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,\n                                          unsigned char *key, size_t keylen,\n                                          unsigned char *id, size_t idlen,\n                                          ASN1_GENERALIZEDTIME *date,\n                                          ASN1_OBJECT *otherTypeId,\n                                          ASN1_TYPE *otherType);\n
"},{"location":"man3/CMS_add1_recipient_cert/#description","title":"DESCRIPTION","text":"

CMS_add1_recipient() adds recipient recip and provides the originator pkey originatorPrivKey and originator certificate originator to CMS_ContentInfo. The originator-related fields are relevant only in case when the keyAgreement method of providing of the shared key is in use.

CMS_add1_recipient_cert() adds recipient recip to CMS_ContentInfo enveloped data structure cms as a KeyTransRecipientInfo structure.

CMS_add0_recipient_key() adds symmetric key key of length keylen using wrapping algorithm nid, identifier id of length idlen and optional values date, otherTypeId and otherType to CMS_ContentInfo enveloped data structure cms as a KEKRecipientInfo structure.

The CMS_ContentInfo structure should be obtained from an initial call to CMS_encrypt() with the flag CMS_PARTIAL set.

"},{"location":"man3/CMS_add1_recipient_cert/#notes","title":"NOTES","text":"

The main purpose of this function is to provide finer control over a CMS enveloped data structure where the simpler CMS_encrypt() function defaults are not appropriate. For example if one or more KEKRecipientInfo structures need to be added. New attributes can also be added using the returned CMS_RecipientInfo structure and the CMS attribute utility functions.

OpenSSL will by default identify recipient certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if all recipient certificates do not have a subject key identifier extension.

Currently only AES based key wrapping algorithms are supported for nid, specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. If nid is set to NID_undef then an AES wrap algorithm will be used consistent with keylen.

"},{"location":"man3/CMS_add1_recipient_cert/#return-values","title":"RETURN VALUES","text":"

CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal pointer to the CMS_RecipientInfo structure just added or NULL if an error occurs.

"},{"location":"man3/CMS_add1_recipient_cert/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_decrypt(3), CMS_final(3),

"},{"location":"man3/CMS_add1_recipient_cert/#history","title":"HISTORY","text":"

CMS_add1_recipient_cert and CMS_add0_recipient_key were added in OpenSSL 3.0.

"},{"location":"man3/CMS_add1_recipient_cert/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_add1_signer/","title":"CMS_add1_signer","text":""},{"location":"man3/CMS_add1_signer/#name","title":"NAME","text":"

CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure

"},{"location":"man3/CMS_add1_signer/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert,\n                                EVP_PKEY *pkey, const EVP_MD *md,\n                                unsigned int flags);\n\nint CMS_SignerInfo_sign(CMS_SignerInfo *si);\n
"},{"location":"man3/CMS_add1_signer/#description","title":"DESCRIPTION","text":"

CMS_add1_signer() adds a signer with certificate signcert and private key pkey using message digest md to CMS_ContentInfo SignedData structure cms.

The CMS_ContentInfo structure should be obtained from an initial call to CMS_sign() with the flag CMS_PARTIAL set or in the case or re-signing a valid CMS_ContentInfo SignedData structure.

If the md parameter is NULL then the default digest for the public key algorithm will be used.

Unless the CMS_REUSE_DIGEST flag is set the returned CMS_ContentInfo structure is not complete and must be finalized either by streaming (if applicable) or a call to CMS_final().

The CMS_SignerInfo_sign() function explicitly signs a CMS_SignerInfo structure, its main use is when the CMS_REUSE_DIGEST and CMS_PARTIAL flags are both set.

"},{"location":"man3/CMS_add1_signer/#notes","title":"NOTES","text":"

The main purpose of CMS_add1_signer() is to provide finer control over a CMS signed data structure where the simpler CMS_sign() function defaults are not appropriate. For example if multiple signers or non default digest algorithms are needed. New attributes can also be added using the returned CMS_SignerInfo structure and the CMS attribute utility functions or the CMS signed receipt request functions.

Any of the following flags (ored together) can be passed in the flags parameter.

If CMS_REUSE_DIGEST is set then an attempt is made to copy the content digest value from the CMS_ContentInfo structure: to add a signer to an existing structure. An error occurs if a matching digest value cannot be found to copy. The returned CMS_ContentInfo structure will be valid and finalized when this flag is set.

If CMS_PARTIAL is set in addition to CMS_REUSE_DIGEST then the CMS_SignerInfo structure will not be finalized so additional attributes can be added. In this case an explicit call to CMS_SignerInfo_sign() is needed to finalize it.

If CMS_NOCERTS is set the signer's certificate will not be included in the CMS_ContentInfo structure, the signer's certificate must still be supplied in the signcert parameter though. This can reduce the size of the signature if the signers certificate can be obtained by other means: for example a previously signed message.

The SignedData structure includes several CMS signedAttributes including the signing time, the CMS content type and the supported list of ciphers in an SMIMECapabilities attribute. If CMS_NOATTR is set then no signedAttributes will be used. If CMS_NOSMIMECAP is set then just the SMIMECapabilities are omitted.

OpenSSL will by default identify signing certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if the signing certificate does not have a subject key identifier extension.

If present the SMIMECapabilities attribute indicates support for the following algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is not loaded.

CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added, this can be used to set additional attributes before it is finalized.

"},{"location":"man3/CMS_add1_signer/#return-values","title":"RETURN VALUES","text":"

CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added or NULL if an error occurs.

CMS_SignerInfo_sign() returns 1 on success, 0 on failure.

"},{"location":"man3/CMS_add1_signer/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_final(3),

"},{"location":"man3/CMS_add1_signer/#copyright","title":"COPYRIGHT","text":"

Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_compress/","title":"CMS_compress","text":""},{"location":"man3/CMS_compress/#name","title":"NAME","text":"

CMS_compress - create a CMS CompressedData structure

"},{"location":"man3/CMS_compress/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);\n
"},{"location":"man3/CMS_compress/#description","title":"DESCRIPTION","text":"

CMS_compress() creates and returns a CMS CompressedData structure. comp_nid is the compression algorithm to use or NID_undef to use the default algorithm (zlib compression). in is the content to be compressed. flags is an optional set of flags.

The only currently supported compression algorithm is zlib using the NID NID_zlib_compression.

If zlib support is not compiled into OpenSSL then CMS_compress() will return an error.

If the CMS_TEXT flag is set MIME headers for type text/plain are prepended to the data.

Normally the supplied content is translated into MIME canonical format (as required by the S/MIME specifications) if CMS_BINARY is set no translation occurs. This option should be used if the supplied data is in binary format otherwise the translation will corrupt it. If CMS_BINARY is set then CMS_TEXT is ignored.

If the CMS_STREAM flag is set a partial CMS_ContentInfo structure is returned suitable for streaming I/O: no data is read from the BIO in.

The compressed data is included in the CMS_ContentInfo structure, unless CMS_DETACHED is set in which case it is omitted. This is rarely used in practice and is not supported by SMIME_write_CMS().

If the flag CMS_STREAM is set the returned CMS_ContentInfo structure is not complete and outputting its contents via a function that does not properly finalize the CMS_ContentInfo structure will give unpredictable results.

Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_CMS().

Additional compression parameters such as the zlib compression level cannot currently be set.

"},{"location":"man3/CMS_compress/#return-values","title":"RETURN VALUES","text":"

CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_compress/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_uncompress(3)

"},{"location":"man3/CMS_compress/#history","title":"HISTORY","text":"

The CMS_STREAM flag was added in OpenSSL 1.0.0.

"},{"location":"man3/CMS_compress/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_data_create/","title":"CMS_data_create","text":""},{"location":"man3/CMS_data_create/#name","title":"NAME","text":"

CMS_data_create_ex, CMS_data_create - Create CMS Data object

"},{"location":"man3/CMS_data_create/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_data_create_ex(BIO *in, unsigned int flags,\n                                    OSSL_LIB_CTX *libctx, const char *propq);\nCMS_ContentInfo *CMS_data_create(BIO *in, unsigned int flags);\n
"},{"location":"man3/CMS_data_create/#description","title":"DESCRIPTION","text":"

CMS_data_create_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_data. The data is supplied via the in BIO. The library context libctx and the property query propq are used when retrieving algorithms from providers. The flags field supports the CMS_STREAM flag. Internally CMS_final() is called unless CMS_STREAM is specified.

The CMS_ContentInfo structure can be freed using CMS_ContentInfo_free(3).

CMS_data_create() is similar to CMS_data_create_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_data_create/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_data_create_ex() and CMS_data_create() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_data_create/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_final(3)

"},{"location":"man3/CMS_data_create/#history","title":"HISTORY","text":"

The CMS_data_create_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_data_create/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_decrypt/","title":"CMS_decrypt","text":""},{"location":"man3/CMS_decrypt/#name","title":"NAME","text":"

CMS_decrypt, CMS_decrypt_set1_pkey_and_peer, CMS_decrypt_set1_pkey, CMS_decrypt_set1_password - decrypt content from a CMS envelopedData structure

"},{"location":"man3/CMS_decrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert,\n                BIO *dcont, BIO *out, unsigned int flags);\nint CMS_decrypt_set1_pkey_and_peer(CMS_ContentInfo *cms,\n                EVP_PKEY *pk, X509 *cert, X509 *peer);\nint CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert);\nint CMS_decrypt_set1_password(CMS_ContentInfo *cms,\n                              unsigned char *pass, ossl_ssize_t passlen);\n
"},{"location":"man3/CMS_decrypt/#description","title":"DESCRIPTION","text":"

CMS_decrypt() extracts the decrypted content from a CMS EnvelopedData or AuthEnvelopedData structure. It uses CMS_decrypt_set1_pkey() to decrypt the content with the recipient private key pkey if pkey is not NULL. In this case, the associated certificate is recommended to provide in cert - see the NOTES below. out is a BIO to write the content to and flags is an optional set of flags. If pkey is NULL the function assumes that decryption was already done (e.g., using CMS_decrypt_set1_pkey() or CMS_decrypt_set1_password()) and just provides the content unless cert, dcont, and out are NULL as well. The dcont parameter is used in the rare case where the encrypted content is detached. It will normally be set to NULL.

CMS_decrypt_set1_pkey_and_peer() decrypts the CMS_ContentInfo structure cms using the private key pkey, the corresponding certificate cert, which is recommended but may be NULL, and the (optional) originator certificate peer. On success, it also records in cms the decryption key pkey, and then should be followed by CMS_decrypt(cms, NULL, NULL, dcont, out, flags). This call deallocates any decryption key stored in cms.

CMS_decrypt_set1_pkey() is the same as CMS_decrypt_set1_pkey_and_peer() with peer being NULL.

CMS_decrypt_set1_password() decrypts the CMS_ContentInfo structure cms using the secret pass of length passlen. On success, it also records in cms the decryption key used, and then should be followed by CMS_decrypt(cms, NULL, NULL, dcont, out, flags). This call deallocates any decryption key stored in cms.

"},{"location":"man3/CMS_decrypt/#notes","title":"NOTES","text":"

Although the recipients certificate is not needed to decrypt the data it is needed to locate the appropriate (of possible several) recipients in the CMS structure.

If cert is set to NULL all possible recipients are tried. This case however is problematic. To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or not. If no recipient succeeds then a random symmetric key is used to decrypt the content: this will typically output garbage and may (but is not guaranteed to) ultimately return a padding error only. If CMS_decrypt() just returned an error when all recipient encrypted keys failed to decrypt an attacker could use this in a timing attack. If the special flag CMS_DEBUG_DECRYPT is set then the above behaviour is modified and an error is returned if no recipient encrypted key can be decrypted without generating a random content encryption key. Applications should use this flag with extreme caution especially in automated gateways as it can leave them open to attack.

It is possible to determine the correct recipient key by other means (for example looking them up in a database) and setting them in the CMS structure in advance using the CMS utility functions such as CMS_set1_pkey(), or use CMS_decrypt_set1_password() if the recipient has a symmetric key. In these cases both cert and pkey should be set to NULL.

To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() and CMS_RecipientInfo_decrypt() should be called before CMS_decrypt() and cert and pkey set to NULL.

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

"},{"location":"man3/CMS_decrypt/#return-values","title":"RETURN VALUES","text":"

CMS_decrypt(), CMS_decrypt_set1_pkey_and_peer(), CMS_decrypt_set1_pkey(), and CMS_decrypt_set1_password() return either 1 for success or 0 for failure. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_decrypt/#bugs","title":"BUGS","text":"

The set1_ part of these function names is misleading and should better read: with_.

The lack of single pass processing and the need to hold all data in memory as mentioned in CMS_verify() also applies to CMS_decrypt().

"},{"location":"man3/CMS_decrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_encrypt(3)

"},{"location":"man3/CMS_decrypt/#history","title":"HISTORY","text":"

CMS_decrypt_set1_pkey_and_peer() and CMS_decrypt_set1_password() were added in OpenSSL 3.0.

"},{"location":"man3/CMS_decrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_digest_create/","title":"CMS_digest_create","text":""},{"location":"man3/CMS_digest_create/#name","title":"NAME","text":"

CMS_digest_create_ex, CMS_digest_create - Create CMS DigestedData object

"},{"location":"man3/CMS_digest_create/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_digest_create_ex(BIO *in, const EVP_MD *md,\n                                      unsigned int flags, OSSL_LIB_CTX *ctx,\n                                      const char *propq);\n\nCMS_ContentInfo *CMS_digest_create(BIO *in, const EVP_MD *md,\n                                   unsigned int flags);\n
"},{"location":"man3/CMS_digest_create/#description","title":"DESCRIPTION","text":"

CMS_digest_create_ex() creates a CMS_ContentInfo structure with a type NID_pkcs7_digest. The data supplied via the in BIO is digested using md. The library context libctx and the property query propq are used when retrieving algorithms from providers. The flags field supports the CMS_DETACHED and CMS_STREAM flags, Internally CMS_final() is called unless CMS_STREAM is specified.

The CMS_ContentInfo structure can be freed using CMS_ContentInfo_free(3).

CMS_digest_create() is similar to CMS_digest_create_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_digest_create/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, CMS_digest_create_ex() and CMS_digest_create() return NULL and set an error code that can be obtained by ERR_get_error(3). Otherwise they return a pointer to the newly allocated structure.

"},{"location":"man3/CMS_digest_create/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_final(3)>

"},{"location":"man3/CMS_digest_create/#history","title":"HISTORY","text":"

The CMS_digest_create_ex() method was added in OpenSSL 3.0.

"},{"location":"man3/CMS_digest_create/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_encrypt/","title":"CMS_encrypt","text":""},{"location":"man3/CMS_encrypt/#name","title":"NAME","text":"

CMS_encrypt_ex, CMS_encrypt - create a CMS envelopedData structure

"},{"location":"man3/CMS_encrypt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_encrypt_ex(STACK_OF(X509) *certs, BIO *in,\n                                const EVP_CIPHER *cipher, unsigned int flags,\n                                OSSL_LIB_CTX *libctx, const char *propq);\nCMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in,\n                             const EVP_CIPHER *cipher, unsigned int flags);\n
"},{"location":"man3/CMS_encrypt/#description","title":"DESCRIPTION","text":"

CMS_encrypt_ex() creates and returns a CMS EnvelopedData or AuthEnvelopedData structure. certs is a list of recipient certificates. in is the content to be encrypted. cipher is the symmetric cipher to use. flags is an optional set of flags. The library context libctx and the property query propq are used internally when retrieving algorithms from providers.

Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this function.

EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because most clients will support it.

The algorithm passed in the cipher parameter must support ASN1 encoding of its parameters. If the cipher mode is GCM, then an AuthEnvelopedData structure containing MAC is used. Otherwise an EnvelopedData structure is used. Currently the AES variants with GCM mode are the only supported AEAD algorithms.

Many browsers implement a \"sign and encrypt\" option which is simply an S/MIME envelopedData containing an S/MIME signed message. This can be readily produced by storing the S/MIME signed message in a memory BIO and passing it to CMS_encrypt().

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are prepended to the data.

Normally the supplied content is translated into MIME canonical format (as required by the S/MIME specifications) if CMS_BINARY is set no translation occurs. This option should be used if the supplied data is in binary format otherwise the translation will corrupt it. If CMS_BINARY is set then CMS_TEXT is ignored.

OpenSSL will by default identify recipient certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if all recipient certificates do not have a subject key identifier extension.

If the CMS_STREAM flag is set a partial CMS_ContentInfo structure is returned suitable for streaming I/O: no data is read from the BIO in.

If the CMS_PARTIAL flag is set a partial CMS_ContentInfo structure is returned to which additional recipients and attributes can be added before finalization.

The data being encrypted is included in the CMS_ContentInfo structure, unless CMS_DETACHED is set in which case it is omitted. This is rarely used in practice and is not supported by SMIME_write_CMS().

If the flag CMS_STREAM is set the returned CMS_ContentInfo structure is not complete and outputting its contents via a function that does not properly finalize the CMS_ContentInfo structure will give unpredictable results.

Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_CMS().

The recipients specified in certs use a CMS KeyTransRecipientInfo info structure. KEKRecipientInfo is also supported using the flag CMS_PARTIAL and CMS_add0_recipient_key().

The parameter certs may be NULL if CMS_PARTIAL is set and recipients added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key().

CMS_encrypt() is similar to CMS_encrypt_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_encrypt/#return-values","title":"RETURN VALUES","text":"

CMS_encrypt_ex() and CMS_encrypt() return either a CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_encrypt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_decrypt(3)

"},{"location":"man3/CMS_encrypt/#history","title":"HISTORY","text":"

The function CMS_encrypt_ex() was added in OpenSSL 3.0.

The CMS_STREAM flag was first supported in OpenSSL 1.0.0.

"},{"location":"man3/CMS_encrypt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_final/","title":"CMS_final","text":""},{"location":"man3/CMS_final/#name","title":"NAME","text":"

CMS_final, CMS_final_digest - finalise a CMS_ContentInfo structure

"},{"location":"man3/CMS_final/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);\nint CMS_final_digest(CMS_ContentInfo *cms, const unsigned char *md,\n                     unsigned int mdlen, BIO *dcont, unsigned int flags);\n
"},{"location":"man3/CMS_final/#description","title":"DESCRIPTION","text":"

CMS_final() finalises the structure cms. Its purpose is to perform any operations necessary on cms (digest computation for example) and set the appropriate fields. The parameter data contains the content to be processed. The dcont parameter contains a BIO to write content to after processing: this is only used with detached data and will usually be set to NULL.

CMS_final_digest() finalises the structure cms using a pre-computed digest, rather than computing the digest from the original data.

"},{"location":"man3/CMS_final/#notes","title":"NOTES","text":"

These functions will normally be called when the CMS_PARTIAL flag is used. It should only be used when streaming is not performed because the streaming I/O functions perform finalisation operations internally.

To sign a pre-computed digest, CMS_sign(3) or CMS_sign_ex() is called with the data parameter set to NULL before the CMS structure is finalised with the digest provided to CMS_final_digest() in binary form. When signing a pre-computed digest, the security relies on the digest and its computation from the original message being trusted.

"},{"location":"man3/CMS_final/#return-values","title":"RETURN VALUES","text":"

CMS_final() and CMS_final_digest() return 1 for success or 0 for failure.

"},{"location":"man3/CMS_final/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_encrypt(3)

"},{"location":"man3/CMS_final/#history","title":"HISTORY","text":"

CMS_final_digest() was added in OpenSSL 3.2.

"},{"location":"man3/CMS_final/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_get0_RecipientInfos/","title":"CMS_get0_RecipientInfos","text":""},{"location":"man3/CMS_get0_RecipientInfos/#name","title":"NAME","text":"

CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kari_set0_pkey_and_peer, CMS_RecipientInfo_kari_set0_pkey, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines

"},{"location":"man3/CMS_get0_RecipientInfos/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nSTACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms);\nint CMS_RecipientInfo_type(CMS_RecipientInfo *ri);\n\nint CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,\n                                          ASN1_OCTET_STRING **keyid,\n                                          X509_NAME **issuer,\n                                          ASN1_INTEGER **sno);\nint CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);\nint CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);\nint CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,\n                                              EVP_PKEY *pk, X509 *peer);\nint CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);\nint CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,\n                                    ASN1_OCTET_STRING **pid,\n                                    ASN1_GENERALIZEDTIME **pdate,\n                                    ASN1_OBJECT **potherid,\n                                    ASN1_TYPE **pothertype);\nint CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,\n                                   const unsigned char *id, size_t idlen);\nint CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri,\n                               unsigned char *key, size_t keylen);\n\nint CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);\nint CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);\n
"},{"location":"man3/CMS_get0_RecipientInfos/#description","title":"DESCRIPTION","text":"

The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo structures associated with a CMS EnvelopedData structure.

CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure ri. It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER.

CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient identifier associated with a specific CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in keyid or both issuer name and serial number in issuer and sno.

CMS_RecipientInfo_ktri_cert_cmp() compares the certificate cert against the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. It returns zero if the comparison is successful and non zero if not.

CMS_RecipientInfo_set0_pkey() associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS.

CMS_RecipientInfo_kari_set0_pkey_and_peer() associates the private key pkey and peer certificate peer with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_AGREE.

CMS_RecipientInfo_kari_set0_pkey() associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_AGREE.

CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the CMS_RecipientInfo structure ri which must be of type CMS_RECIPINFO_KEK. Any of the remaining parameters can be NULL if the application is not interested in the value of a field. Where a field is optional and absent NULL will be written to the corresponding parameter. The keyEncryptionAlgorithm field is written to palg, the keyIdentifier field is written to pid, the date field if present is written to pdate, if the other field is present the components keyAttrId and keyAttr are written to parameters potherid and pothertype.

CMS_RecipientInfo_kekri_id_cmp() compares the ID in the id and idlen parameters against the keyIdentifier CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is successful and non zero if not.

CMS_RecipientInfo_set0_key() associates the symmetric key key of length keylen with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK.

CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure ri in structure cms. A key must have been associated with the structure first.

CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure ri in structure cms. A key must have been associated with the structure first and the content encryption key must be available: for example by a previous call to CMS_RecipientInfo_decrypt().

"},{"location":"man3/CMS_get0_RecipientInfos/#notes","title":"NOTES","text":"

The main purpose of these functions is to enable an application to lookup recipient keys using any appropriate technique when the simpler method of CMS_decrypt() is not appropriate.

In typical usage and application will retrieve all CMS_RecipientInfo structures using CMS_get0_RecipientInfos() and check the type of each using CMS_RecipientInfo_type(). Depending on the type the CMS_RecipientInfo structure can be ignored or its key identifier data retrieved using an appropriate function. Then if the corresponding secret or private key can be obtained by any appropriate means it can then associated with the structure and CMS_RecipientInfo_decrypt() called. If successful CMS_decrypt() can be called with a NULL key to decrypt the enveloped content.

The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an existing enveloped data structure. Typically an application will first decrypt an appropriate CMS_RecipientInfo structure to make the content encrypt key available, it will then add a new recipient using a function such as CMS_add1_recipient_cert() and finally encrypt the content encryption key using CMS_RecipientInfo_encrypt().

"},{"location":"man3/CMS_get0_RecipientInfos/#return-values","title":"RETURN VALUES","text":"

CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if an error occurs.

CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.

CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 for a successful comparison and non zero otherwise.

Any error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_get0_RecipientInfos/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_decrypt(3)

"},{"location":"man3/CMS_get0_RecipientInfos/#history","title":"HISTORY","text":"

CMS_RecipientInfo_kari_set0_pkey_and_peer and CMS_RecipientInfo_kari_set0_pkey were added in OpenSSL 3.0.

"},{"location":"man3/CMS_get0_RecipientInfos/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_get0_SignerInfos/","title":"CMS_get0_SignerInfos","text":""},{"location":"man3/CMS_get0_SignerInfos/#name","title":"NAME","text":"

CMS_SignerInfo_set1_signer_cert, CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp - CMS signedData signer functions

"},{"location":"man3/CMS_get0_SignerInfos/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nSTACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);\n\nint CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid,\n                                  X509_NAME **issuer, ASN1_INTEGER **sno);\nASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);\nint CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);\nvoid CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);\n
"},{"location":"man3/CMS_get0_SignerInfos/#description","title":"DESCRIPTION","text":"

The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures associated with a CMS signedData structure.

CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier associated with a specific CMS_SignerInfo structure si. Either the keyidentifier will be set in keyid or both issuer name and serial number in issuer and sno.

CMS_SignerInfo_get0_signature() retrieves the signature associated with si in a pointer to an ASN1_OCTET_STRING structure. This pointer returned corresponds to the internal signature value if si so it may be read or modified.

CMS_SignerInfo_cert_cmp() compares the certificate cert against the signer identifier si. It returns zero if the comparison is successful and non zero if not.

CMS_SignerInfo_set1_signer_cert() sets the signers certificate of si to signer.

"},{"location":"man3/CMS_get0_SignerInfos/#notes","title":"NOTES","text":"

The main purpose of these functions is to enable an application to lookup signers certificates using any appropriate technique when the simpler method of CMS_verify() is not appropriate.

In typical usage and application will retrieve all CMS_SignerInfo structures using CMS_get0_SignerInfo() and retrieve the identifier information using CMS. It will then obtain the signer certificate by some unspecified means (or return and error if it cannot be found) and set it using CMS_SignerInfo_set1_signer_cert().

Once all signer certificates have been set CMS_verify() can be used.

Although CMS_get0_SignerInfos() can return NULL if an error occurs or if there are no signers this is not a problem in practice because the only error which can occur is if the cms structure is not of type signedData due to application error.

"},{"location":"man3/CMS_get0_SignerInfos/#return-values","title":"RETURN VALUES","text":"

CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there are no signers or an error occurs.

CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure.

CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non zero otherwise.

CMS_SignerInfo_set1_signer_cert() does not return a value.

Any error can be obtained from ERR_get_error(3)

"},{"location":"man3/CMS_get0_SignerInfos/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_verify(3)

"},{"location":"man3/CMS_get0_SignerInfos/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_get0_type/","title":"CMS_get0_type","text":""},{"location":"man3/CMS_get0_type/#name","title":"NAME","text":"

CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content

"},{"location":"man3/CMS_get0_type/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nconst ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms);\nint CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);\nconst ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);\nASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);\n
"},{"location":"man3/CMS_get0_type/#description","title":"DESCRIPTION","text":"

CMS_get0_type() returns the content type of a CMS_ContentInfo structure as an ASN1_OBJECT pointer. An application can then decide how to process the CMS_ContentInfo structure based on this value.

CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo structure. It should be called with CMS functions (such as CMS_sign(3), CMS_encrypt(3)) with the CMS_PARTIAL flag and before the structure is finalised, otherwise the results are undefined.

ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded content type.

CMS_get0_content() returns a pointer to the ASN1_OCTET_STRING pointer containing the embedded content.

"},{"location":"man3/CMS_get0_type/#notes","title":"NOTES","text":"

As the 0 implies CMS_get0_type(), CMS_get0_eContentType() and CMS_get0_content() return internal pointers which should not be freed up. CMS_set1_eContentType() copies the supplied OID and it should be freed up after use.

The ASN1_OBJECT values returned can be converted to an integer NID value using OBJ_obj2nid(). For the currently supported content types the following values are returned:

NID_pkcs7_data\nNID_pkcs7_signed\nNID_pkcs7_digest\nNID_id_smime_ct_compressedData:\nNID_pkcs7_encrypted\nNID_pkcs7_enveloped\n

The return value of CMS_get0_content() is a pointer to the ASN1_OCTET_STRING content pointer. That means that for example:

ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);\n

*pconf could be NULL if there is no embedded content. Applications can access, modify or create the embedded content in a CMS_ContentInfo structure using this function. Applications usually will not need to modify the embedded content as it is normally set by higher level functions.

"},{"location":"man3/CMS_get0_type/#return-values","title":"RETURN VALUES","text":"

CMS_get0_type() and CMS_get0_eContentType() return an ASN1_OBJECT structure.

CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_get0_type/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/CMS_get0_type/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_get1_ReceiptRequest/","title":"CMS_get1_ReceiptRequest","text":""},{"location":"man3/CMS_get1_ReceiptRequest/#name","title":"NAME","text":"

CMS_ReceiptRequest_create0_ex, CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions

"},{"location":"man3/CMS_get1_ReceiptRequest/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ReceiptRequest *CMS_ReceiptRequest_create0_ex(\n    unsigned char *id, int idlen, int allorfirst,\n    STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo,\n    OSSL_LIB_CTX *libctx);\nCMS_ReceiptRequest *CMS_ReceiptRequest_create0(\n    unsigned char *id, int idlen, int allorfirst,\n    STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo);\nint CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr);\nint CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr);\nvoid CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid,\n                                    int *pallorfirst,\n                                    STACK_OF(GENERAL_NAMES) **plist,\n                                    STACK_OF(GENERAL_NAMES) **prto);\n
"},{"location":"man3/CMS_get1_ReceiptRequest/#description","title":"DESCRIPTION","text":"

CMS_ReceiptRequest_create0_ex() creates a signed receipt request structure. The signedContentIdentifier field is set using id and idlen, or it is set to 32 bytes of pseudo random data if id is NULL. If receiptList is NULL the allOrFirstTier option in receiptsFrom is used and set to the value of the allorfirst parameter. If receiptList is not NULL the receiptList option in receiptsFrom is used. The receiptsTo parameter specifies the receiptsTo field value. The library context libctx is used to find the public random generator.

CMS_ReceiptRequest_create0() is similar to CMS_ReceiptRequest_create0_ex() but uses default values of NULL for the library context libctx.

The CMS_add1_ReceiptRequest() function adds a signed receipt request rr to SignerInfo structure si.

int CMS_get1_ReceiptRequest() looks for a signed receipt request in si, if any is found it is decoded and written to prr.

CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. The signedContentIdentifier is copied to pcid. If the allOrFirstTier option of receiptsFrom is used its value is copied to pallorfirst otherwise the receiptList field is copied to plist. The receiptsTo parameter is copied to prto.

"},{"location":"man3/CMS_get1_ReceiptRequest/#notes","title":"NOTES","text":"

For more details of the meaning of the fields see RFC2634.

The contents of a signed receipt should only be considered meaningful if the corresponding CMS_ContentInfo structure can be successfully verified using CMS_verify().

"},{"location":"man3/CMS_get1_ReceiptRequest/#return-values","title":"RETURN VALUES","text":"

CMS_ReceiptRequest_create0_ex() and CMS_ReceiptRequest_create0() return a signed receipt request structure or NULL if an error occurred.

CMS_add1_ReceiptRequest() returns 1 for success or 0 if an error occurred.

CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and decoded. It returns 0 if a signed receipt request is not present and -1 if it is present but malformed.

"},{"location":"man3/CMS_get1_ReceiptRequest/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign(3), CMS_sign_receipt(3), CMS_verify(3) CMS_verify_receipt(3)

"},{"location":"man3/CMS_get1_ReceiptRequest/#history","title":"HISTORY","text":"

The function CMS_ReceiptRequest_create0_ex() was added in OpenSSL 3.0.

"},{"location":"man3/CMS_get1_ReceiptRequest/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_sign/","title":"CMS_sign","text":""},{"location":"man3/CMS_sign/#name","title":"NAME","text":"

CMS_sign, CMS_sign_ex - create a CMS SignedData structure

"},{"location":"man3/CMS_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_sign_ex(X509 *signcert, EVP_PKEY *pkey,\n                             STACK_OF(X509) *certs, BIO *data,\n                             unsigned int flags, OSSL_LIB_CTX *ctx,\n                             const char *propq);\nCMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,\n                          BIO *data, unsigned int flags);\n
"},{"location":"man3/CMS_sign/#description","title":"DESCRIPTION","text":"

CMS_sign_ex() creates and returns a CMS SignedData structure. signcert is the certificate to sign with, pkey is the corresponding private key. certs is an optional additional set of certificates to include in the CMS structure (for example any intermediate CAs in the chain). The library context libctx and the property query propq are used when retrieving algorithms from providers. Any or all of these parameters can be NULL, see NOTES below.

The data to be signed is read from BIO data.

flags is an optional set of flags.

CMS_sign() is similar to CMS_sign_ex() but uses default values of NULL for the library context libctx and the property query propq.

"},{"location":"man3/CMS_sign/#notes","title":"NOTES","text":"

Any of the following flags (ored together) can be passed in the flags parameter.

Many S/MIME clients expect the signed content to include valid MIME headers. If the CMS_TEXT flag is set MIME headers for type text/plain are prepended to the data.

If CMS_NOCERTS is set the signer's certificate will not be included in the CMS_ContentInfo structure, the signer's certificate must still be supplied in the signcert parameter though. This can reduce the size of the signature if the signers certificate can be obtained by other means: for example a previously signed message.

The data being signed is included in the CMS_ContentInfo structure, unless CMS_DETACHED is set in which case it is omitted. This is used for CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed messages for example.

Normally the supplied content is translated into MIME canonical format (as required by the S/MIME specifications) if CMS_BINARY is set no translation occurs. This option should be used if the supplied data is in binary format otherwise the translation will corrupt it.

The SignedData structure includes several CMS signedAttributes including the signing time, the CMS content type and the supported list of ciphers in an SMIMECapabilities attribute. If CMS_NOATTR is set then no signedAttributes will be used. If CMS_NOSMIMECAP is set then just the SMIMECapabilities are omitted.

If present the SMIMECapabilities attribute indicates support for the following algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is not loaded.

OpenSSL will by default identify signing certificates using issuer name and serial number. If CMS_USE_KEYID is set it will use the subject key identifier value instead. An error occurs if the signing certificate does not have a subject key identifier extension.

If the flags CMS_STREAM is set then the returned CMS_ContentInfo structure is just initialized ready to perform the signing operation. The signing is however not performed and the data to be signed is not read from the data parameter. Signing is deferred until after the data has been written. In this way data can be signed in a single pass.

If the CMS_PARTIAL flag is set a partial CMS_ContentInfo structure is output to which additional signers and capabilities can be added before finalization.

If the flag CMS_STREAM is set the returned CMS_ContentInfo structure is not complete and outputting its contents via a function that does not properly finalize the CMS_ContentInfo structure will give unpredictable results.

Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_CMS().

If a signer is specified it will use the default digest for the signing algorithm. This is SHA1 for both RSA and DSA keys.

If signcert and pkey are NULL then a certificates only CMS structure is output.

The function CMS_sign() is a basic CMS signing function whose output will be suitable for many purposes. For finer control of the output format the certs, signcert and pkey parameters can all be NULL and the CMS_PARTIAL flag set. Then one or more signers can be added using the function CMS_add1_signer(), non default digests can be used and custom attributes added. CMS_final() must then be called to finalize the structure if streaming is not enabled.

"},{"location":"man3/CMS_sign/#bugs","title":"BUGS","text":"

Some attributes such as counter signatures are not supported.

"},{"location":"man3/CMS_sign/#return-values","title":"RETURN VALUES","text":"

CMS_sign_ex() and CMS_sign() return either a valid CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_sign/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_verify(3)

"},{"location":"man3/CMS_sign/#history","title":"HISTORY","text":"

The CMS_STREAM flag is only supported for detached data in OpenSSL 0.9.8, it is supported for embedded data in OpenSSL 1.0.0 and later.

The CMS_sign_ex() method was added in OpenSSL 3.0.

Since OpenSSL 3.2, CMS_sign_ex() and CMS_sign() ignore any duplicate certificates in their certs argument and no longer throw an error for them.

"},{"location":"man3/CMS_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_sign_receipt/","title":"CMS_sign_receipt","text":""},{"location":"man3/CMS_sign_receipt/#name","title":"NAME","text":"

CMS_sign_receipt - create a CMS signed receipt

"},{"location":"man3/CMS_sign_receipt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nCMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert,\n                                  EVP_PKEY *pkey, STACK_OF(X509) *certs,\n                                  unsigned int flags);\n
"},{"location":"man3/CMS_sign_receipt/#description","title":"DESCRIPTION","text":"

CMS_sign_receipt() creates and returns a CMS signed receipt structure. si is the CMS_SignerInfo structure containing the signed receipt request. signcert is the certificate to sign with, pkey is the corresponding private key. certs is an optional additional set of certificates to include in the CMS structure (for example any intermediate CAs in the chain).

flags is an optional set of flags.

"},{"location":"man3/CMS_sign_receipt/#notes","title":"NOTES","text":"

This functions behaves in a similar way to CMS_sign() except the flag values CMS_DETACHED, CMS_BINARY, CMS_NOATTR, CMS_TEXT and CMS_STREAM are not supported since they do not make sense in the context of signed receipts.

"},{"location":"man3/CMS_sign_receipt/#return-values","title":"RETURN VALUES","text":"

CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_sign_receipt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_verify_receipt(3), CMS_sign(3)

"},{"location":"man3/CMS_sign_receipt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_signed_get_attr/","title":"CMS_signed_get_attr","text":""},{"location":"man3/CMS_signed_get_attr/#name","title":"NAME","text":"

CMS_signed_get_attr_count, CMS_signed_get_attr_by_NID, CMS_signed_get_attr_by_OBJ, CMS_signed_get_attr, CMS_signed_delete_attr, CMS_signed_add1_attr, CMS_signed_add1_attr_by_OBJ, CMS_signed_add1_attr_by_NID, CMS_signed_add1_attr_by_txt, CMS_signed_get0_data_by_OBJ, CMS_unsigned_get_attr_count, CMS_unsigned_get_attr_by_NID, CMS_unsigned_get_attr_by_OBJ, CMS_unsigned_get_attr, CMS_unsigned_delete_attr, CMS_unsigned_add1_attr, CMS_unsigned_add1_attr_by_OBJ, CMS_unsigned_add1_attr_by_NID, CMS_unsigned_add1_attr_by_txt, CMS_unsigned_get0_data_by_OBJ - CMS signed and unsigned attribute functions

"},{"location":"man3/CMS_signed_get_attr/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_signed_get_attr_count(const CMS_SignerInfo *si);\nint CMS_signed_get_attr_by_NID(const CMS_SignerInfo *si, int nid,\n                               int lastpos);\nint CMS_signed_get_attr_by_OBJ(const CMS_SignerInfo *si, const ASN1_OBJECT *obj,\n                               int lastpos);\nX509_ATTRIBUTE *CMS_signed_get_attr(const CMS_SignerInfo *si, int loc);\nX509_ATTRIBUTE *CMS_signed_delete_attr(CMS_SignerInfo *si, int loc);\nint CMS_signed_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);\nint CMS_signed_add1_attr_by_OBJ(CMS_SignerInfo *si,\n                                const ASN1_OBJECT *obj, int type,\n                                const void *bytes, int len);\nint CMS_signed_add1_attr_by_NID(CMS_SignerInfo *si,\n                                int nid, int type,\n                                const void *bytes, int len);\nint CMS_signed_add1_attr_by_txt(CMS_SignerInfo *si,\n                                const char *attrname, int type,\n                                const void *bytes, int len);\nvoid *CMS_signed_get0_data_by_OBJ(const CMS_SignerInfo *si,\n                                  const ASN1_OBJECT *oid,\n                                  int lastpos, int type);\n\nint CMS_unsigned_get_attr_count(const CMS_SignerInfo *si);\nint CMS_unsigned_get_attr_by_NID(const CMS_SignerInfo *si, int nid,\n                                 int lastpos);\nint CMS_unsigned_get_attr_by_OBJ(const CMS_SignerInfo *si,\n                                 const ASN1_OBJECT *obj, int lastpos);\nX509_ATTRIBUTE *CMS_unsigned_get_attr(const CMS_SignerInfo *si, int loc);\nX509_ATTRIBUTE *CMS_unsigned_delete_attr(CMS_SignerInfo *si, int loc);\nint CMS_unsigned_add1_attr(CMS_SignerInfo *si, X509_ATTRIBUTE *attr);\nint CMS_unsigned_add1_attr_by_OBJ(CMS_SignerInfo *si,\n                                  const ASN1_OBJECT *obj, int type,\n                                  const void *bytes, int len);\nint CMS_unsigned_add1_attr_by_NID(CMS_SignerInfo *si,\n                                  int nid, int type,\n                                  const void *bytes, int len);\nint CMS_unsigned_add1_attr_by_txt(CMS_SignerInfo *si,\n                                  const char *attrname, int type,\n                                  const void *bytes, int len);\nvoid *CMS_unsigned_get0_data_by_OBJ(CMS_SignerInfo *si, ASN1_OBJECT *oid,\n                                    int lastpos, int type);\n
"},{"location":"man3/CMS_signed_get_attr/#description","title":"DESCRIPTION","text":"

CMS_signerInfo contains separate attribute lists for signed and unsigned attributes. Each CMS_signed_XXX() function is used for signed attributes, and each CMS_unsigned_XXX() function is used for unsigned attributes. Since the CMS_unsigned_XXX() functions work in the same way as the CMS_signed_XXX() equivalents, only the CMS_signed_XXX() functions are described below.

CMS_signed_get_attr_by_OBJ() finds the location of the first matching object obj in the SignerInfo's si signed attribute list. The search starts at the position after lastpos. If the returned value is positive then it can be used on the next call to CMS_signed_get_attr_by_OBJ() as the value of lastpos in order to iterate through the remaining attributes. lastpos can be set to any negative value on the first call, in order to start searching from the start of the signed attribute list.

CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except that it passes the numerical identifier (NID) nid associated with the object. See <openssl/obj_mac.h> for a list of NID_*.

CMS_signed_get_attr() returns the X509_ATTRIBUTE object at index loc in the si signed attribute list. loc should be in the range from 0 to CMS_signed_get_attr_count() - 1.

CMS_signed_delete_attr() removes the X509_ATTRIBUTE object at index loc in the si signed attribute list. An error occurs if the si attribute list is NULL.

CMS_signed_add1_attr() pushes a copy of the passed in X509_ATTRIBUTE object to the si signed attribute list. A new signed attribute list is created if required. An error occurs if attr is NULL.

CMS_signed_add1_attr_by_OBJ() creates a new signed X509_ATTRIBUTE using X509_ATTRIBUTE_set1_object() and X509_ATTRIBUTE_set1_data() to assign a new obj with type type and data bytes of length len and then pushes it to the key object's attribute list.

CMS_signed_add1_attr_by_NID() is similar to CMS_signed_add1_attr_by_OBJ() except that it passes the numerical identifier (NID) nid associated with the object. See <openssl/obj_mac.h> for a list of NID_*.

CMS_signed_add1_attr_by_txt() is similar to CMS_signed_add1_attr_by_OBJ() except that it passes a name attrname associated with the object. See <openssl/obj_mac.h> for a list of SN_* names.

CMS_signed_get0_data_by_OBJ() finds the first attribute in a si signed attributes list that matches the obj starting at index lastpos and returns the data retrieved from the found attributes first ASN1_TYPE object. An error will occur if the attribute type type does not match the type of the ASN1_TYPE object OR if type is either V_ASN1_BOOLEAN or V_ASN1_NULL OR the attribute is not found. If lastpos is less than -1 then an error will occur if there are multiple objects in the signed attribute list that match obj. If lastpos is less than -2 then an error will occur if there is more than one ASN1_TYPE object in the found signed attribute.

Refer to X509_ATTRIBUTE(3) for information related to attributes.

"},{"location":"man3/CMS_signed_get_attr/#return-values","title":"RETURN VALUES","text":"

The CMS_unsigned_XXX() functions return values are similar to those of the equivalent CMS_signed_XXX() functions.

CMS_signed_get_attr_count() returns the number of signed attributes in the SignerInfo si, or -1 if the signed attribute list is NULL.

CMS_signed_get_attr_by_OBJ() returns -1 if either the signed attribute list of si is empty OR if obj is not found, otherwise it returns the location of the obj in the SignerInfo's si signed attribute list.

CMS_signed_get_attr_by_NID() is similar to CMS_signed_get_attr_by_OBJ() except that it returns -2 if the nid is not known by OpenSSL.

CMS_signed_get_attr() returns either a signed X509_ATTRIBUTE or NULL on error.

CMS_signed_delete_attr() returns either the removed signed X509_ATTRIBUTE or NULL if there is a error.

CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt(), return 1 on success or 0 on error.

CMS_signed_get0_data_by_OBJ() returns the data retrieved from the found signed attributes first ASN1_TYPE object, or NULL if an error occurs.

"},{"location":"man3/CMS_signed_get_attr/#notes","title":"NOTES","text":"

Some attributes are added automatically during the signing process.

Calling CMS_SignerInfo_sign() adds the NID_pkcs9_signingTime signed attribute.

Calling CMS_final(), CMS_final_digest() or CMS_dataFinal() adds the NID_pkcs9_messageDigest signed attribute.

The NID_pkcs9_contentType signed attribute is always added if the NID_pkcs9_signingTime attribute is added.

Calling CMS_sign_ex(), CMS_sign_receipt() or CMS_add1_signer() may add attributes depending on the flags parameter. See CMS_add1_signer(3) for more information.

OpenSSL applies special rules for the following attribute NIDs:

CMS_signed_add1_attr(), CMS_signed_add1_attr_by_OBJ(), CMS_signed_add1_attr_by_NID(), CMS_signed_add1_attr_by_txt() and the equivalent CMS_unsigned_add1_attrXXX() functions allow duplicate attributes to be added. The attribute rules are not checked during these function calls, and are deferred until the sign or verify process (i.e. during calls to any of CMS_sign_ex(), CMS_sign(), CMS_sign_receipt(), CMS_add1_signer(), CMS_Final(), CMS_dataFinal(), CMS_final_digest(), CMS_verify(), CMS_verify_receipt() or CMS_SignedData_verify()).

For CMS attribute rules see RFC 5652 Section 11. For ESS attribute rules see RFC 2634 Section 1.3.4 and RFC 5035 Section 5.4.

"},{"location":"man3/CMS_signed_get_attr/#see-also","title":"SEE ALSO","text":"

X509_ATTRIBUTE(3)

"},{"location":"man3/CMS_signed_get_attr/#copyright","title":"COPYRIGHT","text":"

Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_uncompress/","title":"CMS_uncompress","text":""},{"location":"man3/CMS_uncompress/#name","title":"NAME","text":"

CMS_uncompress - uncompress a CMS CompressedData structure

"},{"location":"man3/CMS_uncompress/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags);\n
"},{"location":"man3/CMS_uncompress/#description","title":"DESCRIPTION","text":"

CMS_uncompress() extracts and uncompresses the content from a CMS CompressedData structure cms. data is a BIO to write the content to and flags is an optional set of flags.

The dcont parameter is used in the rare case where the compressed content is detached. It will normally be set to NULL.

"},{"location":"man3/CMS_uncompress/#notes","title":"NOTES","text":"

The only currently supported compression algorithm is zlib: if the structure indicates the use of any other algorithm an error is returned.

If zlib support is not compiled into OpenSSL then CMS_uncompress() will always return an error.

The following flags can be passed in the flags parameter.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

"},{"location":"man3/CMS_uncompress/#return-values","title":"RETURN VALUES","text":"

CMS_uncompress() returns either 1 for success or 0 for failure. The error can be obtained from ERR_get_error(3)

"},{"location":"man3/CMS_uncompress/#bugs","title":"BUGS","text":"

The lack of single pass processing and the need to hold all data in memory as mentioned in CMS_verify() also applies to CMS_decompress().

"},{"location":"man3/CMS_uncompress/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_compress(3)

"},{"location":"man3/CMS_uncompress/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_verify/","title":"CMS_verify","text":""},{"location":"man3/CMS_verify/#name","title":"NAME","text":"

CMS_verify, CMS_SignedData_verify, CMS_get0_signers - verify a CMS SignedData structure

"},{"location":"man3/CMS_verify/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store,\n               BIO *detached_data, BIO *out, unsigned int flags);\nBIO *CMS_SignedData_verify(CMS_SignedData *sd, BIO *detached_data,\n                           STACK_OF(X509) *scerts, X509_STORE *store,\n                           STACK_OF(X509) *extra, STACK_OF(X509_CRL) *crls,\n                           unsigned int flags,\n                           OSSL_LIB_CTX *libctx, const char *propq);\n\nSTACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);\n
"},{"location":"man3/CMS_verify/#description","title":"DESCRIPTION","text":"

CMS_verify() is very similar to PKCS7_verify(3). It verifies a CMS SignedData structure contained in a structure of type CMS_ContentInfo. cms points to the CMS_ContentInfo structure to verify. The optional certs parameter refers to a set of certificates in which to search for signing certificates. cms may contain extra untrusted CA certificates that may be used for chain building as well as CRLs that may be used for certificate validation. store may be NULL or point to the trusted certificate store to use for chain verification. detached_data refers to the signed data if the content is detached from cms. Otherwise detached_data should be NULL and the signed data must be in cms. The content is written to the BIO out unless it is NULL. flags is an optional set of flags, which can be used to modify the operation.

CMS_SignedData_verify() is like CMS_verify() except that it operates on CMS SignedData input in the sd argument, it has some additional parameters described next, and on success it returns the verified content as a memory BIO. The optional extra parameter may be used to provide untrusted CA certificates that may be helpful for chain building in certificate validation. This list of certificates must not contain duplicates. The optional crls parameter may be used to provide extra CRLs. Also the list of CRLs must not contain duplicates. The optional parameters library context libctx and property query propq are used when retrieving algorithms from providers.

CMS_get0_signers() retrieves the signing certificate(s) from cms; it may only be called after a successful CMS_verify() or CMS_SignedData_verify() operation.

"},{"location":"man3/CMS_verify/#verify-process","title":"VERIFY PROCESS","text":"

Normally the verify process proceeds as follows.

Initially some sanity checks are performed on cms. The type of cms must be SignedData. There must be at least one signature on the data and if the content is detached detached_data cannot be NULL.

An attempt is made to locate all the signing certificate(s), first looking in the certs parameter (if it is not NULL) and then looking in any certificates contained in the cms structure unless CMS_NOINTERN is set. If any signing certificate cannot be located the operation fails.

Each signing certificate is chain verified using the smimesign purpose and using the trusted certificate store store if supplied. Any internal certificates in the message, which may have been added using CMS_add1_cert(3), are used as untrusted CAs. If CRL checking is enabled in store and CMS_NOCRL is not set, any internal CRLs, which may have been added using CMS_add1_crl(3), are used in addition to attempting to look them up in store. If store is not NULL and any chain verify fails an error code is returned.

Finally the signed content is read (and written to out unless it is NULL) and the signature is checked.

If all signatures verify correctly then the function is successful.

Any of the following flags (ored together) can be passed in the flags parameter to change the default verify behaviour.

If CMS_NOINTERN is set the certificates in the message itself are not searched when locating the signing certificate(s). This means that all the signing certificates must be in the certs parameter.

If CMS_NOCRL is set and CRL checking is enabled in store then any CRLs in the message itself and provided via the crls parameter are ignored.

If the CMS_TEXT flag is set MIME headers for type text/plain are deleted from the content. If the content is not of type text/plain then an error is returned.

If CMS_NO_SIGNER_CERT_VERIFY is set the signing certificates are not chain verified, unless CMS_CADES flag is also set.

If CMS_NO_ATTR_VERIFY is set the signed attributes signature is not verified, unless CMS_CADES flag is also set.

If CMS_CADES is set, each signer certificate is checked against the ESS signingCertificate or ESS signingCertificateV2 extension that is required in the signed attributes of the signature.

If CMS_NO_CONTENT_VERIFY is set then the content digest is not checked.

"},{"location":"man3/CMS_verify/#notes","title":"NOTES","text":"

One application of CMS_NOINTERN is to only accept messages signed by a small number of certificates. The acceptable certificates would be passed in the certs parameter. In this case if the signer certificate is not one of the certificates supplied in certs then the verify will fail because the signer cannot be found.

In some cases the standard techniques for looking up and validating certificates are not appropriate: for example an application may wish to lookup certificates in a database or perform customised verification. This can be achieved by setting and verifying the signer certificates manually using the signed data utility functions.

Care should be taken when modifying the default verify behaviour, for example setting CMS_NO_CONTENT_VERIFY will totally disable all content verification and any modified content will be considered valid. This combination is however useful if one merely wishes to write the content to out and its validity is not considered important.

Chain verification should arguably be performed using the signing time rather than the current time. However, since the signing time is supplied by the signer it cannot be trusted without additional evidence (such as a trusted timestamp).

"},{"location":"man3/CMS_verify/#return-values","title":"RETURN VALUES","text":"

CMS_verify() returns 1 for a successful verification and 0 if an error occurred.

CMS_SignedData_verify() returns a memory BIO containing the verified content, or NULL on error.

CMS_get0_signers() returns all signers or NULL if an error occurred.

The error can be obtained from ERR_get_error(3).

"},{"location":"man3/CMS_verify/#bugs","title":"BUGS","text":"

The trusted certificate store is not searched for the signing certificate. This is primarily due to the inadequacies of the current X509_STORE functionality.

The lack of single pass processing means that the signed content must all be held in memory if it is not detached.

"},{"location":"man3/CMS_verify/#see-also","title":"SEE ALSO","text":"

PKCS7_verify(3), CMS_add1_cert(3), CMS_add1_crl(3), OSSL_ESS_check_signing_certs(3), ERR_get_error(3), CMS_sign(3)

"},{"location":"man3/CMS_verify/#history","title":"HISTORY","text":"

CMS_SignedData_verify() was added in OpenSSL 3.2.

"},{"location":"man3/CMS_verify/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CMS_verify_receipt/","title":"CMS_verify_receipt","text":""},{"location":"man3/CMS_verify_receipt/#name","title":"NAME","text":"

CMS_verify_receipt - verify a CMS signed receipt

"},{"location":"man3/CMS_verify_receipt/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/cms.h>\n\nint CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms,\n                       STACK_OF(X509) *certs, X509_STORE *store,\n                       unsigned int flags);\n
"},{"location":"man3/CMS_verify_receipt/#description","title":"DESCRIPTION","text":"

CMS_verify_receipt() verifies a CMS signed receipt. rcms is the signed receipt to verify. ocms is the original SignedData structure containing the receipt request. certs is a set of certificates in which to search for the signing certificate. store is a trusted certificate store (used for chain verification).

flags is an optional set of flags, which can be used to modify the verify operation.

"},{"location":"man3/CMS_verify_receipt/#notes","title":"NOTES","text":"

This functions behaves in a similar way to CMS_verify() except the flag values CMS_DETACHED, CMS_BINARY, CMS_TEXT and CMS_STREAM are not supported since they do not make sense in the context of signed receipts.

"},{"location":"man3/CMS_verify_receipt/#return-values","title":"RETURN VALUES","text":"

CMS_verify_receipt() returns 1 for a successful verification and zero if an error occurred.

The error can be obtained from ERR_get_error(3)

"},{"location":"man3/CMS_verify_receipt/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), CMS_sign_receipt(3), CMS_verify(3),

"},{"location":"man3/CMS_verify_receipt/#copyright","title":"COPYRIGHT","text":"

Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/COMP_CTX_new/","title":"COMP_CTX_new","text":""},{"location":"man3/COMP_CTX_new/#name","title":"NAME","text":"

COMP_CTX_new, COMP_CTX_get_method, COMP_CTX_get_type, COMP_get_type, COMP_get_name, COMP_CTX_free, COMP_compress_block, COMP_expand_block, COMP_zlib, COMP_zlib_oneshot, COMP_brotli, COMP_brotli_oneshot, COMP_zstd, COMP_zstd_oneshot, BIO_f_zlib, BIO_f_brotli, BIO_f_zstd - Compression support

"},{"location":"man3/COMP_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/comp.h>\n\nCOMP_CTX *COMP_CTX_new(COMP_METHOD *meth);\nvoid COMP_CTX_free(COMP_CTX *ctx);\nconst COMP_METHOD *COMP_CTX_get_method(const COMP_CTX *ctx);\nint COMP_CTX_get_type(const COMP_CTX* comp);\nint COMP_get_type(const COMP_METHOD *meth);\nconst char *COMP_get_name(const COMP_METHOD *meth);\n\nint COMP_compress_block(COMP_CTX *ctx, unsigned char *out, int olen,\n                        unsigned char *in, int ilen);\nint COMP_expand_block(COMP_CTX *ctx, unsigned char *out, int olen,\n                      unsigned char *in, int ilen);\n\nCOMP_METHOD *COMP_zlib(void);\nCOMP_METHOD *COMP_zlib_oneshot(void);\nCOMP_METHOD *COMP_brotli(void);\nCOMP_METHOD *COMP_brotli_oneshot(void);\nCOMP_METHOD *COMP_zstd(void);\nCOMP_METHOD *COMP_zstd_oneshot(void);\n\nconst BIO_METHOD *BIO_f_zlib(void);\nconst BIO_METHOD *BIO_f_brotli(void);\nconst BIO_METHOD *BIO_f_zstd(void);\n
"},{"location":"man3/COMP_CTX_new/#description","title":"DESCRIPTION","text":"

These functions provide compression support for OpenSSL. Compression is used within the OpenSSL library to support TLS record and certificate compression.

COMP_CTX_new() is used to create a new COMP_CTX structure used to compress data.

COMP_CTX_free() is used to free the returned COMP_CTX. If the argument is NULL, nothing is done.

COMP_CTX_get_method() returns the COMP_METHOD of the given ctx.

COMP_CTX_get_type() and COMP_get_type() return the NID for the COMP_CTX and COMP_METHOD, respectively. COMP_get_name() returns the name of the algorithm of the given COMP_METHOD.

COMP_compress_block() compresses b<ilen> bytes from the buffer in into the buffer b<out> of size olen using the algorithm specified by ctx.

COMP_expand_block() expands ilen bytes from the buffer in into the buffer out of size olen using the algorithm specified by ctx.

Methods (COMP_METHOD) may be specified by one of these functions. These functions will be available even if their corresponding compression algorithm is not configured into the OpenSSL library. In such a case, NULL will be returned.

BIO_f_zlib(), BIO_f_brotli() BIO_f_zstd() each return a BIO_METHOD that may be used to create a BIO via BIO_new(3) to read and write compressed files or streams. The functions are only available if the corresponding algorithm is compiled into the OpenSSL library. NULL may be returned if the algorithm fails to load dynamically.

"},{"location":"man3/COMP_CTX_new/#notes","title":"NOTES","text":"

While compressing non-compressible data, the output may be larger than the input. Care should be taken to size output buffers appropriate for both compression and expansion.

Compression support and compression algorithms must be enabled and built into the library before use. Refer to the INSTALL.md file when configuring OpenSSL.

ZLIB may be found at https://zlib.net

Brotli may be found at https://github.com/google/brotli.

Zstandard may be found at https://github.com/facebook/zstd.

Compression of SSL/TLS records is not recommended, as it has been shown to lead to the CRIME attack https://en.wikipedia.org/wiki/CRIME. It is disabled by default, and may be enabled by clearing the SSL_OP_NO_COMPRESSION option and setting the security level as appropriate. See the documentation for the SSL_CTX_set_options(3) and SSL_set_options(3) functions.

Compression is also used to support certificate compression as described in RFC8879 https://datatracker.ietf.org/doc/html/rfc8879. It may be disabled via the SSL_OP_NO_TX_CERTIFICATE_COMPRESSION and SSL_OP_NO_RX_CERTIFICATE_COMPRESSION options of the SSL_CTX_set_options(3) or SSL_set_options(3) functions.

COMP_zlib(), COMP_brotli() and COMP_zstd() are stream-based compression methods. Internal state (including compression dictionary) is maintained between calls. If an error is returned, the stream is corrupted, and should be closed.

COMP_zlib_oneshot(), COMP_brotli_oneshot() and COMP_zstd_oneshot() are not stream-based. These methods do not maintain state between calls. An error in one call does not affect future calls.

"},{"location":"man3/COMP_CTX_new/#return-values","title":"RETURN VALUES","text":"

COMP_CTX_new() returns a COMP_CTX on success, or NULL on failure.

COMP_CTX_get_method(), COMP_zlib(), COMP_zlib_oneshot(), COMP_brotli(), COMP_brotli_oneshot(), COMP_zstd(), and COMP_zstd_oneshot() return a COMP_METHOD on success, or NULL on failure.

COMP_CTX_get_type() and COMP_get_type() return a NID value. On failure, NID_undef is returned.

COMP_compress_block() and COMP_expand_block() return the number of bytes stored in the output buffer out. This may be 0. On failure, -1 is returned.

COMP_get_name() returns a const char * that must not be freed on success, or NULL on failure.

BIO_f_zlib(), BIO_f_brotli() and BIO_f_zstd() return NULL on error, and a BIO_METHOD on success.

"},{"location":"man3/COMP_CTX_new/#see-also","title":"SEE ALSO","text":"

BIO_new(3), SSL_CTX_set_options(3), SSL_set_options(3)

"},{"location":"man3/COMP_CTX_new/#history","title":"HISTORY","text":"

Brotli and Zstandard functions were added in OpenSSL 3.2.

"},{"location":"man3/COMP_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CONF_modules_free/","title":"CONF_modules_free","text":""},{"location":"man3/CONF_modules_free/#name","title":"NAME","text":"

CONF_modules_free, CONF_modules_finish, CONF_modules_unload - OpenSSL configuration cleanup functions

"},{"location":"man3/CONF_modules_free/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/conf.h>\n\nvoid CONF_modules_finish(void);\nvoid CONF_modules_unload(int all);\n

The following functions have been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void CONF_modules_free(void);\n
"},{"location":"man3/CONF_modules_free/#description","title":"DESCRIPTION","text":"

CONF_modules_free() closes down and frees up all memory allocated by all configuration modules. Normally, in versions of OpenSSL prior to 1.1.0, applications called CONF_modules_free() at exit to tidy up any configuration performed.

CONF_modules_finish() calls each configuration modules finish handler to free up any configuration that module may have performed.

CONF_modules_unload() finishes and unloads configuration modules. If all is set to 0 only modules loaded from DSOs will be unloads. If all is 1 all modules, including built-in modules will be unloaded.

"},{"location":"man3/CONF_modules_free/#return-values","title":"RETURN VALUES","text":"

None of the functions return a value.

"},{"location":"man3/CONF_modules_free/#see-also","title":"SEE ALSO","text":"

config(5), OPENSSL_config(3), CONF_modules_load_file_ex(3)

"},{"location":"man3/CONF_modules_free/#history","title":"HISTORY","text":"

CONF_modules_free() was deprecated in OpenSSL 1.1.0; do not use it. For more information see OPENSSL_init_crypto(3).

"},{"location":"man3/CONF_modules_free/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CONF_modules_load_file/","title":"CONF_modules_load_file","text":""},{"location":"man3/CONF_modules_load_file/#name","title":"NAME","text":"

CONF_get1_default_config_file, CONF_modules_load_file_ex, CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions

"},{"location":"man3/CONF_modules_load_file/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/conf.h>\n\nchar *CONF_get1_default_config_file(void);\nint CONF_modules_load_file_ex(OSSL_LIB_CTX *libctx, const char *filename,\n                              const char *appname, unsigned long flags);\nint CONF_modules_load_file(const char *filename, const char *appname,\n                           unsigned long flags);\nint CONF_modules_load(const CONF *cnf, const char *appname,\n                      unsigned long flags);\n
"},{"location":"man3/CONF_modules_load_file/#description","title":"DESCRIPTION","text":"

The function CONF_get1_default_config_file() determines the default configuration file pathname as follows. If the OPENSSL_CONF environment variable is set its value is returned. Else the function returns the path obtained using X509_get_default_cert_area(3) with the filename \"openssl.cnf\" appended. The caller is responsible for freeing any string returned.

The function CONF_modules_load_file_ex() configures OpenSSL using library context libctx file filename and application name appname. If filename is NULL the standard OpenSSL configuration file is used as determined by calling CONF_get1_default_config_file(). If appname is NULL the standard OpenSSL application name openssl_conf is used. The behaviour can be customized using flags. Note that, the error suppressing can be overridden by config_diagnostics as described in config(5).

CONF_modules_load_file() is the same as CONF_modules_load_file_ex() but has a NULL library context.

CONF_modules_load() is identical to CONF_modules_load_file() except it reads configuration information from cnf.

"},{"location":"man3/CONF_modules_load_file/#notes","title":"NOTES","text":"

The following flags are currently recognized:

If CONF_MFLAGS_IGNORE_ERRORS is set errors returned by individual configuration modules are ignored. If not set the first module error is considered fatal and no further modules are loaded.

Normally any modules errors will add error information to the error queue. If CONF_MFLAGS_SILENT is set no error information is added.

If CONF_MFLAGS_IGNORE_RETURN_CODES is set the function unconditionally returns success. This is used by default in OPENSSL_init_crypto(3) to ignore any errors in the default system-wide configuration file, as having all OpenSSL applications fail to start when there are potentially minor issues in the file is too risky. Applications calling CONF_modules_load_file_ex explicitly should not generally set this flag.

If CONF_MFLAGS_NO_DSO is set configuration module loading from DSOs is disabled.

CONF_MFLAGS_IGNORE_MISSING_FILE if set will make CONF_load_modules_file() ignore missing configuration files. Normally a missing configuration file return an error.

CONF_MFLAGS_DEFAULT_SECTION if set and appname is not NULL will use the default section pointed to by openssl_conf if appname does not exist.

By using CONF_modules_load_file_ex() with appropriate flags an application can customise application configuration to best suit its needs. In some cases the use of a configuration file is optional and its absence is not an error: in this case CONF_MFLAGS_IGNORE_MISSING_FILE would be set.

Errors during configuration may also be handled differently by different applications. For example in some cases an error may simply print out a warning message and the application continue. In other cases an application might consider a configuration file error as fatal and exit immediately.

Applications can use the CONF_modules_load() function if they wish to load a configuration file themselves and have finer control over how errors are treated.

"},{"location":"man3/CONF_modules_load_file/#return-values","title":"RETURN VALUES","text":"

These functions return 1 for success and a zero or negative value for failure. If module errors are not ignored the return code will reflect the return value of the failing module (this will always be zero or negative).

"},{"location":"man3/CONF_modules_load_file/#examples","title":"EXAMPLES","text":"

Load a configuration file and print out any errors and exit (missing file considered fatal):

if (CONF_modules_load_file_ex(libctx, NULL, NULL, 0) <= 0) {\n    fprintf(stderr, \"FATAL: error loading configuration file\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n

Load default configuration file using the section indicated by \"myapp\", tolerate missing files, but exit on other errors:

if (CONF_modules_load_file_ex(NULL, NULL, \"myapp\",\n                              CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {\n    fprintf(stderr, \"FATAL: error loading configuration file\\n\");\n    ERR_print_errors_fp(stderr);\n    exit(1);\n}\n

Load custom configuration file and section, only print warnings on error, missing configuration file ignored:

if (CONF_modules_load_file_ex(NULL, \"/something/app.cnf\", \"myapp\",\n                              CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {\n    fprintf(stderr, \"WARNING: error loading configuration file\\n\");\n    ERR_print_errors_fp(stderr);\n}\n

Load and parse configuration file manually, custom error handling:

FILE *fp;\nCONF *cnf = NULL;\nlong eline;\n\nfp = fopen(\"/somepath/app.cnf\", \"r\");\nif (fp == NULL) {\n    fprintf(stderr, \"Error opening configuration file\\n\");\n    /* Other missing configuration file behaviour */\n} else {\n    cnf = NCONF_new_ex(libctx, NULL);\n    if (NCONF_load_fp(cnf, fp, &eline) == 0) {\n        fprintf(stderr, \"Error on line %ld of configuration file\\n\", eline);\n        ERR_print_errors_fp(stderr);\n        /* Other malformed configuration file behaviour */\n    } else if (CONF_modules_load(cnf, \"appname\", 0) <= 0) {\n        fprintf(stderr, \"Error configuring application\\n\");\n        ERR_print_errors_fp(stderr);\n        /* Other configuration error behaviour */\n    }\n    fclose(fp);\n    NCONF_free(cnf);\n}\n
"},{"location":"man3/CONF_modules_load_file/#see-also","title":"SEE ALSO","text":"

config(5), OPENSSL_config(3), NCONF_new_ex(3)

"},{"location":"man3/CONF_modules_load_file/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CRYPTO_THREAD_run_once/","title":"CRYPTO_THREAD_run_once","text":""},{"location":"man3/CRYPTO_THREAD_run_once/#name","title":"NAME","text":"

CRYPTO_THREAD_run_once, CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock, CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add, CRYPTO_atomic_add64, CRYPTO_atomic_and, CRYPTO_atomic_or, CRYPTO_atomic_load, CRYPTO_atomic_store, CRYPTO_atomic_load_int, OSSL_set_max_threads, OSSL_get_max_threads, OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL, OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support

"},{"location":"man3/CRYPTO_THREAD_run_once/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nCRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;\nint CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));\n\nCRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);\nint CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);\nint CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);\nint CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);\nvoid CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);\n\nint CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_add64(uint64_t *val, uint64_t op, uint64_t *ret,\n                        CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_and(uint64_t *val, uint64_t op, uint64_t *ret,\n                      CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret,\n                     CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_store(uint64_t *dst, uint64_t val, CRYPTO_RWLOCK *lock);\nint CRYPTO_atomic_load_int(int *val, int *ret, CRYPTO_RWLOCK *lock);\n\nint OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads);\nuint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);\nuint32_t OSSL_get_thread_support_flags(void);\n\n#define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL\n#define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN\n
"},{"location":"man3/CRYPTO_THREAD_run_once/#description","title":"DESCRIPTION","text":"

OpenSSL can be safely used in multi-threaded applications provided that support for the underlying OS threading API is built-in. Currently, OpenSSL supports the pthread and Windows APIs. OpenSSL can also be built without any multi-threading support, for example on platforms that don't provide any threading support or that provide a threading API that is not yet supported by OpenSSL.

The following multi-threading function are provided:

"},{"location":"man3/CRYPTO_THREAD_run_once/#return-values","title":"RETURN VALUES","text":"

CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.

CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.

CRYPTO_THREAD_lock_free() returns no value.

OSSL_set_max_threads() returns 1 on success and 0 on failure. Returns failure if OpenSSL-managed thread pooling is not supported (for example, if it is not supported on the current platform, or because OpenSSL is not built with the necessary support).

OSSL_get_max_threads() returns the maximum number of threads currently allowed to be used by the thread pool. If thread pooling is disabled or not available, returns 0.

OSSL_get_thread_support_flags() returns zero or more OSSL_THREAD_SUPPORT_FLAG values.

The other functions return 1 on success, or 0 on error.

"},{"location":"man3/CRYPTO_THREAD_run_once/#notes","title":"NOTES","text":"

On Windows platforms the CRYPTO_THREAD_* types and functions in the <openssl/crypto.h> header are dependent on some of the types customarily made available by including <windows.h>. The application developer is likely to require control over when the latter is included, commonly as one of the first included headers. Therefore, it is defined as an application developer's responsibility to include <windows.h> prior to <openssl/crypto.h> where use of CRYPTO_THREAD_* types and functions is required.

"},{"location":"man3/CRYPTO_THREAD_run_once/#examples","title":"EXAMPLES","text":"

You can find out if OpenSSL was configured with thread support:

#include <openssl/opensslconf.h>\n#if defined(OPENSSL_THREADS)\n    /* thread support enabled */\n#else\n    /* no thread support */\n#endif\n

This example safely initializes and uses a lock.

#ifdef _WIN32\n

# # include #endif #include 

static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;\nstatic CRYPTO_RWLOCK *lock;\n\nstatic void myinit(void)\n{\n    lock = CRYPTO_THREAD_lock_new();\n}\n\nstatic int mylock(void)\n{\n    if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)\n        return 0;\n    return CRYPTO_THREAD_write_lock(lock);\n}\n\nstatic int myunlock(void)\n{\n    return CRYPTO_THREAD_unlock(lock);\n}\n\nint serialized(void)\n{\n    int ret = 0;\n\n    if (!mylock()) {\n       /* Do not unlock unless the lock was successfully acquired. */\n       return 0;\n    }\n\n    /* Your code here, do not return without releasing the lock! */\n    ret = ... ;\n    myunlock();\n    return ret;\n}\n

Finalization of locks is an advanced topic, not covered in this example. This can only be done at process exit or when a dynamically loaded library is no longer in use and is unloaded. The simplest solution is to just \"leak\" the lock in applications and not repeatedly load/unload shared libraries that allocate locks.

"},{"location":"man3/CRYPTO_THREAD_run_once/#see-also","title":"SEE ALSO","text":"

crypto(7), openssl-threads(7).

"},{"location":"man3/CRYPTO_THREAD_run_once/#history","title":"HISTORY","text":"

CRYPTO_atomic_store() was added in OpenSSL 3.4.0

"},{"location":"man3/CRYPTO_THREAD_run_once/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CRYPTO_get_ex_new_index/","title":"CRYPTO_get_ex_new_index","text":""},{"location":"man3/CRYPTO_get_ex_new_index/#name","title":"NAME","text":"

CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup, CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data - functions supporting application-specific data

"},{"location":"man3/CRYPTO_get_ex_new_index/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint CRYPTO_get_ex_new_index(int class_index,\n                            long argl, void *argp,\n                            CRYPTO_EX_new *new_func,\n                            CRYPTO_EX_dup *dup_func,\n                            CRYPTO_EX_free *free_func);\n\ntypedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,\n                           int idx, long argl, void *argp);\ntypedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,\n                            int idx, long argl, void *argp);\ntypedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,\n                          void **from_d, int idx, long argl, void *argp);\n\nint CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad);\n\nint CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad,\n                         int idx);\n\nint CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);\n\nvoid *CRYPTO_get_ex_data(const CRYPTO_EX_DATA *r, int idx);\n\nvoid CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);\n\nint CRYPTO_free_ex_index(int class_index, int idx);\n
"},{"location":"man3/CRYPTO_get_ex_new_index/#description","title":"DESCRIPTION","text":"

Several OpenSSL structures can have application-specific data attached to them, known as \"exdata.\" The specific structures are:

BIO\nDH\nDSA\nEC_KEY\nENGINE\nEVP_PKEY\nRSA\nSSL\nSSL_CTX\nSSL_SESSION\nUI\nUI_METHOD\nX509\nX509_STORE\nX509_STORE_CTX\n

In addition, the APP name is reserved for use by application code.

Each is identified by an CRYPTO_EX_INDEX_xxx define in the header file <openssl/crypto.h>. In addition, CRYPTO_EX_INDEX_APP is reserved for applications to use this facility for their own structures.

The API described here is used by OpenSSL to manipulate exdata for specific structures. Since the application data can be anything at all it is passed and retrieved as a void * type.

The CRYPTO_EX_DATA type is opaque. To initialize the exdata part of a structure, call CRYPTO_new_ex_data(). This is only necessary for CRYPTO_EX_INDEX_APP objects.

Exdata types are identified by an index, an integer guaranteed to be unique within structures for the lifetime of the program. Applications using exdata typically call CRYPTO_get_ex_new_index at startup, and store the result in a global variable, or write a wrapper function to provide lazy evaluation. The class_index should be one of the CRYPTO_EX_INDEX_xxx values. The argl and argp parameters are saved to be passed to the callbacks but are otherwise not used. In order to transparently manipulate exdata, three callbacks must be provided. The semantics of those callbacks are described below.

When copying or releasing objects with exdata, the callback functions are called in increasing order of their index value.

If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index() when this is done. This will replace the callbacks with no-ops so that applications don't crash. Any existing exdata will be leaked.

To set or get the exdata on an object, the appropriate type-specific routine must be used. This is because the containing structure is opaque and the CRYPTO_EX_DATA field is not accessible. In both API's, the idx parameter should be an already-created index value.

When setting exdata, the pointer specified with a particular index is saved, and returned on a subsequent \"get\" call. If the application is going to release the data, it must make sure to set a NULL value at the index, to avoid likely double-free crashes.

The function CRYPTO_free_ex_data is used to free all exdata attached to a structure. The appropriate type-specific routine must be used. The class_index identifies the structure type, the obj is a pointer to the actual structure, and r is a pointer to the structure's exdata field.

"},{"location":"man3/CRYPTO_get_ex_new_index/#callback-functions","title":"Callback Functions","text":"

This section describes how the callback functions are used. Applications that are defining their own exdata using CYPRTO_EX_INDEX_APP must call them as described here.

When a structure is initially allocated (such as RSA_new()) then the new_func() is called for every defined index. There is no requirement that the entire parent, or containing, structure has been set up. The new_func() is typically used only to allocate memory to store the exdata, and perhaps an \"initialized\" flag within that memory. The exdata value may be allocated later on with CRYPTO_alloc_ex_data(), or may be set by calling CRYPTO_set_ex_data().

When a structure is free'd (such as SSL_CTX_free()) then the free_func() is called for every defined index. Again, the state of the parent structure is not guaranteed. The free_func() may be called with a NULL pointer.

Both new_func() and free_func() take the same parameters. The parent is the pointer to the structure that contains the exdata. The ptr is the current exdata item; for new_func() this will typically be NULL. The r parameter is a pointer to the exdata field of the object. The idx is the index and is the value returned when the callbacks were initially registered via CRYPTO_get_ex_new_index() and can be used if the same callback handles different types of exdata.

dup_func() is called when a structure is being copied. This is only done for SSL, SSL_SESSION, EC_KEY objects and BIO chains via BIO_dup_chain(). The to and from parameters are pointers to the destination and source CRYPTO_EX_DATA structures, respectively. The *from_d parameter is a pointer to the source exdata. When the dup_func() returns, the value in *from_d is copied to the destination ex_data. If the pointer contained in *pptr is not modified by the dup_func(), then both to and from will point to the same data. The idx, argl and argp parameters are as described for the other two callbacks. If the dup_func() returns 0 the whole CRYPTO_dup_ex_data() will fail.

"},{"location":"man3/CRYPTO_get_ex_new_index/#return-values","title":"RETURN VALUES","text":"

CRYPTO_get_ex_new_index() returns a new index or -1 on failure.

CRYPTO_free_ex_index(), CRYPTO_alloc_ex_data() and CRYPTO_set_ex_data() return 1 on success or 0 on failure.

CRYPTO_get_ex_data() returns the application data or NULL on failure; note that NULL may be a valid value.

dup_func() should return 0 for failure and 1 for success.

"},{"location":"man3/CRYPTO_get_ex_new_index/#history","title":"HISTORY","text":"

CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.

The signature of the dup_func() callback was changed in OpenSSL 3.0 to use the type void ** for from_d. Previously this parameter was of type void *.

Support for ENGINE \"exdata\" was deprecated in OpenSSL 3.0.

"},{"location":"man3/CRYPTO_get_ex_new_index/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CRYPTO_memcmp/","title":"CRYPTO_memcmp","text":""},{"location":"man3/CRYPTO_memcmp/#name","title":"NAME","text":"

CRYPTO_memcmp - Constant time memory comparison

"},{"location":"man3/CRYPTO_memcmp/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/crypto.h>\n\nint CRYPTO_memcmp(const void *a, const void *b, size_t len);\n
"},{"location":"man3/CRYPTO_memcmp/#description","title":"DESCRIPTION","text":"

The CRYPTO_memcmp function compares the len bytes pointed to by a and b for equality. It takes an amount of time dependent on len, but independent of the contents of the memory regions pointed to by a and b.

"},{"location":"man3/CRYPTO_memcmp/#return-values","title":"RETURN VALUES","text":"

CRYPTO_memcmp() returns 0 if the memory regions are equal and nonzero otherwise.

"},{"location":"man3/CRYPTO_memcmp/#notes","title":"NOTES","text":"

Unlike memcmp(2), this function cannot be used to order the two memory regions as the return value when they differ is undefined, other than being nonzero.

"},{"location":"man3/CRYPTO_memcmp/#copyright","title":"COPYRIGHT","text":"

Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/","title":"CTLOG_STORE_get0_log_by_id","text":""},{"location":"man3/CTLOG_STORE_get0_log_by_id/#name","title":"NAME","text":"

CTLOG_STORE_get0_log_by_id - Get a Certificate Transparency log from a CTLOG_STORE

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nconst CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store,\n                                        const uint8_t *log_id,\n                                        size_t log_id_len);\n
"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#description","title":"DESCRIPTION","text":"

A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency (CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2). Therefore, it is useful to be able to look up more information about a log (e.g. its public key) using this LogID.

CTLOG_STORE_get0_log_by_id() provides a way to do this. It will find a CTLOG in a CTLOG_STORE that has a given LogID.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#return-values","title":"RETURN VALUES","text":"

CTLOG_STORE_get0_log_by_id returns a CTLOG with the given LogID, if it exists in the given CTLOG_STORE, otherwise it returns NULL.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#see-also","title":"SEE ALSO","text":"

ct(7), CTLOG_STORE_new(3)

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#history","title":"HISTORY","text":"

The CTLOG_STORE_get0_log_by_id() function was added in OpenSSL 1.1.0.

"},{"location":"man3/CTLOG_STORE_get0_log_by_id/#copyright","title":"COPYRIGHT","text":"

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CTLOG_STORE_new/","title":"CTLOG_STORE_new","text":""},{"location":"man3/CTLOG_STORE_new/#name","title":"NAME","text":"

CTLOG_STORE_new_ex, CTLOG_STORE_new, CTLOG_STORE_free, CTLOG_STORE_load_default_file, CTLOG_STORE_load_file - Create and populate a Certificate Transparency log list

"},{"location":"man3/CTLOG_STORE_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nCTLOG_STORE *CTLOG_STORE_new_ex(OSSL_LIB_CTX *libctx, const char *propq);\nCTLOG_STORE *CTLOG_STORE_new(void);\nvoid CTLOG_STORE_free(CTLOG_STORE *store);\n\nint CTLOG_STORE_load_default_file(CTLOG_STORE *store);\nint CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file);\n
"},{"location":"man3/CTLOG_STORE_new/#description","title":"DESCRIPTION","text":"

A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency logs). The list can be loaded from one or more files and then searched by LogID (see RFC 6962, Section 3.2, for the definition of a LogID).

CTLOG_STORE_new_ex() creates an empty list of CT logs associated with the library context libctx and the property query string propq.

CTLOG_STORE_new() does the same thing as CTLOG_STORE_new_ex() but with the default library context and property query string.

The CTLOG_STORE is then populated by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file(). CTLOG_STORE_load_default_file() loads from the default file, which is named ct_log_list.cnf in OPENSSLDIR (see the output of openssl-version(1)). This can be overridden using an environment variable named CTLOG_FILE. CTLOG_STORE_load_file() loads from a caller-specified file path instead. Both of these functions append any loaded CT logs to the CTLOG_STORE.

The expected format of the file is:

enabled_logs=foo,bar\n\n[foo]\ndescription = Log 1\nkey = <base64-encoded DER SubjectPublicKeyInfo here>\n\n[bar]\ndescription = Log 2\nkey = <base64-encoded DER SubjectPublicKeyInfo here>\n

Once a CTLOG_STORE is no longer required, it should be passed to CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along with the CTLOG_STORE itself. If the argument is NULL, nothing is done.

"},{"location":"man3/CTLOG_STORE_new/#notes","title":"NOTES","text":"

If there are any invalid CT logs in a file, they are skipped and the remaining valid logs will still be added to the CTLOG_STORE. A CT log will be considered invalid if it is missing a \"key\" or \"description\" field.

"},{"location":"man3/CTLOG_STORE_new/#return-values","title":"RETURN VALUES","text":"

Both CTLOG_STORE_load_default_file and CTLOG_STORE_load_file return 1 if all CT logs in the file are successfully parsed and loaded, 0 otherwise.

"},{"location":"man3/CTLOG_STORE_new/#see-also","title":"SEE ALSO","text":"

ct(7), CTLOG_STORE_get0_log_by_id(3), SSL_CTX_set_ctlog_list_file(3)

"},{"location":"man3/CTLOG_STORE_new/#history","title":"HISTORY","text":"

CTLOG_STORE_new_ex was added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0.

"},{"location":"man3/CTLOG_STORE_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CTLOG_new/","title":"CTLOG_new","text":""},{"location":"man3/CTLOG_new/#name","title":"NAME","text":"

CTLOG_new_ex, CTLOG_new, CTLOG_new_from_base64, CTLOG_new_from_base64_ex, CTLOG_free, CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key - encapsulates information about a Certificate Transparency log

"},{"location":"man3/CTLOG_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nCTLOG *CTLOG_new_ex(EVP_PKEY *public_key, const char *name,\n                    OSSL_LIB_CTX *libctx, const char *propq);\nCTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);\n\nint CTLOG_new_from_base64_ex(CTLOG **ct_log, const char *pkey_base64,\n                             const char *name, OSSL_LIB_CTX *libctx,\n                             const char *propq);\nint CTLOG_new_from_base64(CTLOG ** ct_log,\n                          const char *pkey_base64, const char *name);\nvoid CTLOG_free(CTLOG *log);\nconst char *CTLOG_get0_name(const CTLOG *log);\nvoid CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id,\n                       size_t *log_id_len);\nEVP_PKEY *CTLOG_get0_public_key(const CTLOG *log);\n
"},{"location":"man3/CTLOG_new/#description","title":"DESCRIPTION","text":"

CTLOG_new_ex() returns a new CTLOG that represents the Certificate Transparency (CT) log with the given public key and associates it with the library context libctx and property query string propq. A name must also be provided that can be used to help users identify this log. Ownership of the public key is transferred.

CTLOG_new() does the same thing as CTLOG_new_ex() but with the default library context and the default property query string.

CTLOG_new_from_base64_ex() also creates a new CTLOG, but takes the public key in base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG. The base64 will be decoded and the public key parsed. The CTLOG will be associated with the given library context libctx and property query string propq.

CTLOG_new_from_base64() does the same thing as CTLOG_new_from_base64_ex() except that the default library context and property query string are used.

Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that was passed to it. If the argument to CTLOG_free() is NULL, nothing is done.

CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was created. Ownership of the string remains with the CTLOG.

CTLOG_get0_log_id() sets *log_id to point to a string containing that log's LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of the string remains with the CTLOG.

CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the EVP_PKEY remains with the CTLOG.

"},{"location":"man3/CTLOG_new/#return-values","title":"RETURN VALUES","text":"

CTLOG_new() will return NULL if an error occurs.

CTLOG_new_from_base64() will return 1 on success, 0 otherwise.

"},{"location":"man3/CTLOG_new/#see-also","title":"SEE ALSO","text":"

ct(7)

"},{"location":"man3/CTLOG_new/#history","title":"HISTORY","text":"

The functions CTLOG_new_ex() and CTLOG_new_from_base64_ex() were added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0.

"},{"location":"man3/CTLOG_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/","title":"CT_POLICY_EVAL_CTX_new","text":""},{"location":"man3/CT_POLICY_EVAL_CTX_new/#name","title":"NAME","text":"

CT_POLICY_EVAL_CTX_new_ex, CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time - Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ct.h>\n\nCT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new_ex(OSSL_LIB_CTX *libctx,\n                                              const char *propq);\nCT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);\nvoid CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);\nX509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);\nint CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert);\nX509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);\nint CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);\nconst CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);\nvoid CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx,\n                                               CTLOG_STORE *log_store);\nuint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx);\nvoid CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms);\n
"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#description","title":"DESCRIPTION","text":"

A CT_POLICY_EVAL_CTX is used by functions that evaluate whether Signed Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. This policy may be, for example, that at least one valid SCT is available. To determine this, an SCT's timestamp and signature must be verified. This requires:

The above requirements are met using the setters described below.

CT_POLICY_EVAL_CTX_new_ex() creates an empty policy evaluation context and associates it with the given library context libctx and property query string propq.

CT_POLICY_EVAL_CTX_new() does the same thing as CT_POLICY_EVAL_CTX_new_ex() except that it uses the default library context and property query string.

The CT_POLICY_EVAL_CTX should then be populated using:

Each setter has a matching getter for accessing the current value.

When no longer required, the CT_POLICY_EVAL_CTX should be passed to CT_POLICY_EVAL_CTX_free() to delete it. If the argument to CT_POLICY_EVAL_CTX_free() is NULL, nothing is done.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#notes","title":"NOTES","text":"

The issuer certificate only needs to be provided if at least one of the SCTs was issued for a pre-certificate. This will be the case for SCTs embedded in a certificate (i.e. those in an X.509 extension), but may not be the case for SCTs found in the TLS SCT extension or OCSP response.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#return-values","title":"RETURN VALUES","text":"

CT_POLICY_EVAL_CTX_new_ex() and CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#see-also","title":"SEE ALSO","text":"

ct(7)

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#history","title":"HISTORY","text":"

CT_POLICY_EVAL_CTX_new_ex was added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0.

"},{"location":"man3/CT_POLICY_EVAL_CTX_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DEFINE_STACK_OF/","title":"DEFINE_STACK_OF","text":""},{"location":"man3/DEFINE_STACK_OF/#name","title":"NAME","text":"

DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF, DEFINE_SPECIAL_STACK_OF_CONST, sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_reserve, sk_TYPE_free, sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push, sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free, sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_find_all, sk_TYPE_sort, sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve, OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr, OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_find_all, OPENSSL_sk_free, OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null, OPENSSL_sk_new_reserve, OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push, OPENSSL_sk_reserve, OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort, OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero - stack container

"},{"location":"man3/DEFINE_STACK_OF/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/safestack.h>\n\nSTACK_OF(TYPE)\nDEFINE_STACK_OF(TYPE)\nDEFINE_STACK_OF_CONST(TYPE)\nDEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)\nDEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)\n\ntypedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);\ntypedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);\ntypedef void (*sk_TYPE_freefunc)(TYPE *a);\n\nint sk_TYPE_num(const STACK_OF(TYPE) *sk);\nTYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx);\nSTACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare);\nSTACK_OF(TYPE) *sk_TYPE_new_null(void);\nint sk_TYPE_reserve(STACK_OF(TYPE) *sk, int n);\nvoid sk_TYPE_free(STACK_OF(TYPE) *sk);\nvoid sk_TYPE_zero(STACK_OF(TYPE) *sk);\nTYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i);\nTYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr);\nint sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr);\nint sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr);\nTYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk);\nTYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk);\nvoid sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc);\nint sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx);\nTYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr);\nint sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr);\nint sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr);\nint sk_TYPE_find_all(STACK_OF(TYPE) *sk, TYPE *ptr, int *pnum);\nvoid sk_TYPE_sort(const STACK_OF(TYPE) *sk);\nint sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk);\nSTACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk);\nSTACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk,\n                                  sk_TYPE_copyfunc copyfunc,\n                                  sk_TYPE_freefunc freefunc);\nsk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk,\n                                        sk_TYPE_compfunc compare));\nSTACK_OF(TYPE) *sk_TYPE_new_reserve(sk_TYPE_compfunc compare, int n);\n
"},{"location":"man3/DEFINE_STACK_OF/#description","title":"DESCRIPTION","text":"

Applications can create and use their own stacks by placing any of the macros described below in a header file. These macros define typesafe inline functions that wrap around the utility OPENSSL_sk_ API. In the description here, TYPE is used as a placeholder for any of the OpenSSL datatypes, such as X509.

The STACK_OF() macro returns the name for a stack of the specified TYPE. This is an opaque pointer to a structure declaration. This can be used in every header file that references the stack. There are several DEFINE... macros that create static inline functions for all of the functions described on this page. This should normally be used in one source file, and the stack manipulation is wrapped with application-specific functions.

DEFINE_STACK_OF() creates set of functions for a stack of TYPE elements. The type is referenced by STACK_OF(TYPE) and each function name begins with sk_TYPE_. DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except each element is constant.

/* DEFINE_STACK_OF(TYPE) */\nTYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);\n/* DEFINE_STACK_OF_CONST(TYPE) */\nconst TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);\n

DEFINE_SPECIAL_STACK_OF() and DEFINE_SPECIAL_STACK_OF_CONST() are similar except FUNCNAME is used in the function names:

/* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */\nTYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);\n/* DEFINE_SPECIAL_STACK_OF(TYPE, FUNCNAME) */\nconst TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);\n

sk_TYPE_num() returns the number of elements in sk or -1 if sk is NULL.

sk_TYPE_value() returns element idx in sk, where idx starts at zero. If idx is out of range then NULL is returned.

sk_TYPE_new() allocates a new empty stack using comparison function compare. If compare is NULL then no comparison function is used. This function is equivalent to sk_TYPE_new_reserve(compare, 0).

sk_TYPE_new_null() allocates a new empty stack with no comparison function. This function is equivalent to sk_TYPE_new_reserve(NULL, 0).

sk_TYPE_reserve() allocates additional memory in the sk structure such that the next n calls to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause memory to be allocated or reallocated. If n is zero, any excess space allocated in the sk structure is freed. On error sk is unchanged.

sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional memory allocated to hold n elements if n is positive. The next n calls to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause memory to be allocated or reallocated. If n is zero or less than zero, no memory is allocated. sk_TYPE_new_reserve() also sets the comparison function compare to the newly created stack. If compare is NULL then no comparison function is used.

sk_TYPE_set_cmp_func() sets the comparison function of sk to compare. The previous comparison function is returned or NULL if there was no previous comparison function.

sk_TYPE_free() frees up the sk structure. It does not free up any elements of sk. After this call sk is no longer valid.

sk_TYPE_zero() sets the number of elements in sk to zero. It does not free sk so after this call sk is still valid.

sk_TYPE_pop_free() frees up all elements of sk and sk itself. The free function freefunc() is called on each element to free it.

sk_TYPE_delete() deletes element i from sk. It returns the deleted element or NULL if i is out of range.

sk_TYPE_delete_ptr() deletes element matching ptr from sk. It returns the deleted element or NULL if no element matching ptr was found.

sk_TYPE_insert() inserts ptr into sk at position idx. Any existing elements at or after idx are moved downwards. If idx is out of range the new element is appended to sk. sk_TYPE_insert() either returns the number of elements in sk after the new element is inserted or zero if an error (such as memory allocation failure) occurred.

sk_TYPE_push() appends ptr to sk it is equivalent to:

sk_TYPE_insert(sk, ptr, -1);\n

sk_TYPE_unshift() inserts ptr at the start of sk it is equivalent to:

sk_TYPE_insert(sk, ptr, 0);\n

sk_TYPE_pop() returns and removes the last element from sk.

sk_TYPE_shift() returns and removes the first element from sk.

sk_TYPE_set() sets element idx of sk to ptr replacing the current element. The new element value is returned or NULL if an error occurred: this will only happen if sk is NULL or idx is out of range.

sk_TYPE_find() searches sk for the element ptr. In the case where no comparison function has been specified, the function performs a linear search for a pointer equal to ptr. The index of the first matching element is returned or -1 if there is no match. In the case where a comparison function has been specified, sk is sorted and sk_TYPE_find() returns the index of a matching element or -1 if there is no match. Note that, in this case the comparison function will usually compare the values pointed to rather than the pointers themselves and the order of elements in sk can change.

sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison function has been specified and no matching element is found. Instead of returning -1, sk_TYPE_find_ex() returns the index of the element either before or after the location where ptr would be if it were present in sk. The function also does not guarantee that the first matching element in the sorted stack is returned.

sk_TYPE_find_all() operates like sk_TYPE_find() but it also sets the *pnum to number of matching elements in the stack. In case no comparison function has been specified the *pnum will be always set to 1 if matching element was found, 0 otherwise.

sk_TYPE_sort() sorts sk using the supplied comparison function.

sk_TYPE_is_sorted() returns 1 if sk is sorted and 0 otherwise.

sk_TYPE_dup() returns a shallow copy of sk or an empty stack if the passed stack is NULL. Note the pointers in the copy are identical to the original.

sk_TYPE_deep_copy() returns a new stack where each element has been copied or an empty stack if the passed stack is NULL. Copying is performed by the supplied copyfunc() and freeing by freefunc(). The function freefunc() is only called if an error occurs.

"},{"location":"man3/DEFINE_STACK_OF/#notes","title":"NOTES","text":"

Care should be taken when accessing stacks in multi-threaded environments. Any operation which increases the size of a stack such as sk_TYPE_insert() or sk_TYPE_push() can \"grow\" the size of an internal array and cause race conditions if the same stack is accessed in a different thread. Operations such as sk_TYPE_find() and sk_TYPE_sort() can also reorder the stack.

Any comparison function supplied should use a metric suitable for use in a binary search operation. That is it should return zero, a positive or negative value if a is equal to, greater than or less than b respectively.

Care should be taken when checking the return values of the functions sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the matching element. In particular 0 indicates a matching first element. A failed search is indicated by a -1 return value.

STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and DEFINE_SPECIAL_STACK_OF() are implemented as macros.

It is not an error to call sk_TYPE_num(), sk_TYPE_value(), sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free(), sk_TYPE_delete(), sk_TYPE_delete_ptr(), sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_find(), sk_TYPE_find_ex(), and sk_TYPE_find_all() on a NULL stack, empty stack, or with an invalid index. An error is not raised in these conditions.

The underlying utility OPENSSL_sk_ API should not be used directly. It defines these functions: OPENSSL_sk_deep_copy(), OPENSSL_sk_delete(), OPENSSL_sk_delete_ptr(), OPENSSL_sk_dup(), OPENSSL_sk_find(), OPENSSL_sk_find_ex(), OPENSSL_sk_find_all(), OPENSSL_sk_free(), OPENSSL_sk_insert(), OPENSSL_sk_is_sorted(), OPENSSL_sk_new(), OPENSSL_sk_new_null(), OPENSSL_sk_new_reserve(), OPENSSL_sk_num(), OPENSSL_sk_pop(), OPENSSL_sk_pop_free(), OPENSSL_sk_push(), OPENSSL_sk_reserve(), OPENSSL_sk_set(), OPENSSL_sk_set_cmp_func(), OPENSSL_sk_shift(), OPENSSL_sk_sort(), OPENSSL_sk_unshift(), OPENSSL_sk_value(), OPENSSL_sk_zero().

"},{"location":"man3/DEFINE_STACK_OF/#return-values","title":"RETURN VALUES","text":"

sk_TYPE_num() returns the number of elements in the stack or -1 if the passed stack is NULL.

sk_TYPE_value() returns a pointer to a stack element or NULL if the index is out of range.

sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty stack or NULL if an error occurs.

sk_TYPE_reserve() returns 1 on successful allocation of the required memory or 0 on error.

sk_TYPE_set_cmp_func() returns the old comparison function or NULL if there was no old comparison function.

sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do not return values.

sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr() return a pointer to the deleted element or NULL on error.

sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total number of elements in the stack and 0 if an error occurred.

sk_TYPE_set() returns a pointer to the replacement element or NULL on error.

sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element or -1 on error.

sk_TYPE_is_sorted() returns 1 if the stack is sorted and 0 if it is not.

sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the stack or NULL on error.

"},{"location":"man3/DEFINE_STACK_OF/#history","title":"HISTORY","text":"

Before OpenSSL 1.1.0, this was implemented via macros and not inline functions and was not a public API.

sk_TYPE_reserve() and sk_TYPE_new_reserve() were added in OpenSSL 1.1.1.

From OpenSSL 3.2.0, the sk_TYPE_find(), sk_TYPE_find_ex() and sk_TYPE_find_all() calls are read-only and do not sort the stack. To avoid any performance implications this change introduces, sk_TYPE_sort() should be called before these find operations.

Before OpenSSL 3.3.0 sk_TYPE_push() returned -1 if sk was NULL. It was changed to return 0 in this condition as for other errors.

"},{"location":"man3/DEFINE_STACK_OF/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DES_random_key/","title":"DES_random_key","text":""},{"location":"man3/DES_random_key/#name","title":"NAME","text":"

DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, DES_fcrypt, DES_crypt - DES encryption

"},{"location":"man3/DES_random_key/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/des.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DES_random_key(DES_cblock *ret);\n\nint DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);\nint DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);\nint DES_set_key_checked(const_DES_cblock *key, DES_key_schedule *schedule);\nvoid DES_set_key_unchecked(const_DES_cblock *key, DES_key_schedule *schedule);\n\nvoid DES_set_odd_parity(DES_cblock *key);\nint DES_is_weak_key(const_DES_cblock *key);\n\nvoid DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,\n                     DES_key_schedule *ks, int enc);\nvoid DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,\n                      DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);\nvoid DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,\n                      DES_key_schedule *ks1, DES_key_schedule *ks2,\n                      DES_key_schedule *ks3, int enc);\n\nvoid DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,\n                      long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                      int enc);\nvoid DES_cfb_encrypt(const unsigned char *in, unsigned char *out,\n                     int numbits, long length, DES_key_schedule *schedule,\n                     DES_cblock *ivec, int enc);\nvoid DES_ofb_encrypt(const unsigned char *in, unsigned char *out,\n                     int numbits, long length, DES_key_schedule *schedule,\n                     DES_cblock *ivec);\nvoid DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,\n                      long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                      int enc);\nvoid DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                       long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                       int *num, int enc);\nvoid DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                       long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                       int *num);\n\nvoid DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,\n                      long length, DES_key_schedule *schedule, DES_cblock *ivec,\n                      const_DES_cblock *inw, const_DES_cblock *outw, int enc);\n\nvoid DES_ede2_cbc_encrypt(const unsigned char *input, unsigned char *output,\n                          long length, DES_key_schedule *ks1,\n                          DES_key_schedule *ks2, DES_cblock *ivec, int enc);\nvoid DES_ede2_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_cblock *ivec,\n                            int *num, int enc);\nvoid DES_ede2_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_cblock *ivec, int *num);\n\nvoid DES_ede3_cbc_encrypt(const unsigned char *input, unsigned char *output,\n                          long length, DES_key_schedule *ks1,\n                          DES_key_schedule *ks2, DES_key_schedule *ks3,\n                          DES_cblock *ivec, int enc);\nvoid DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_key_schedule *ks3,\n                            DES_cblock *ivec, int *num, int enc);\nvoid DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,\n                            long length, DES_key_schedule *ks1,\n                            DES_key_schedule *ks2, DES_key_schedule *ks3,\n                            DES_cblock *ivec, int *num);\n\nDES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,\n                       long length, DES_key_schedule *schedule,\n                       const_DES_cblock *ivec);\nDES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],\n                        long length, int out_count, DES_cblock *seed);\nvoid DES_string_to_key(const char *str, DES_cblock *key);\nvoid DES_string_to_2keys(const char *str, DES_cblock *key1, DES_cblock *key2);\n\nchar *DES_fcrypt(const char *buf, const char *salt, char *ret);\nchar *DES_crypt(const char *buf, const char *salt);\n
"},{"location":"man3/DES_random_key/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3) and EVP_EncryptFinal_ex(3) or the equivalently named decrypt functions.

This library contains a fast implementation of the DES encryption algorithm.

There are two phases to the use of DES encryption. The first is the generation of a DES_key_schedule from a key, the second is the actual encryption. A DES key is of type DES_cblock. This type consists of 8 bytes with odd parity. The least significant bit in each byte is the parity bit. The key schedule is an expanded form of the key; it is used to speed the encryption process.

DES_random_key() generates a random key. The random generator must be seeded when calling this function. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail. If the function fails, 0 is returned.

Before a DES key can be used, it must be converted into the architecture dependent DES_key_schedule via the DES_set_key_checked() or DES_set_key_unchecked() function.

DES_set_key_checked() will check that the key passed is of odd parity and is not a weak or semi-weak key. If the parity is wrong, then -1 is returned. If the key is a weak key, then -2 is returned. If an error is returned, the key schedule is not generated.

DES_set_key() works like DES_set_key_checked() and remains for backward compatibility.

DES_set_odd_parity() sets the parity of the passed key to odd.

DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it is ok.

The following routines mostly operate on an input and output stream of _DES_cblock_s.

DES_ecb_encrypt() is the basic DES encryption routine that encrypts or decrypts a single 8-byte DES_cblock in electronic code book (ECB) mode. It always transforms the input data, pointed to by input, into the output data, pointed to by the output argument. If the encrypt argument is nonzero (DES_ENCRYPT), the input (cleartext) is encrypted in to the output (ciphertext) using the key_schedule specified by the schedule argument, previously set via DES_set_key. If encrypt is zero (DES_DECRYPT), the input (now ciphertext) is decrypted into the output (now cleartext). Input and output may overlap. DES_ecb_encrypt() does not return a value.

DES_ecb3_encrypt() encrypts/decrypts the input block by using three-key Triple-DES encryption in ECB mode. This involves encrypting the input with ks1, decrypting with the key schedule ks2, and then encrypting with ks3. This routine greatly reduces the chances of brute force breaking of DES and has the advantage of if ks1, ks2 and ks3 are the same, it is equivalent to just encryption using ECB mode and ks1 as the key.

The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES encryption by using ks1 for the final encryption.

DES_ncbc_encrypt() encrypts/decrypts using the cipher-block-chaining (CBC) mode of DES. If the encrypt argument is nonzero, the routine cipher-block-chain encrypts the cleartext data pointed to by the input argument into the ciphertext pointed to by the output argument, using the key schedule provided by the schedule argument, and initialization vector provided by the ivec argument. If the length argument is not an integral multiple of eight bytes, the last block is copied to a temporary area and zero filled. The output is always an integral multiple of eight bytes.

DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses inw and outw to 'whiten' the encryption. inw and outw are secret (unlike the iv) and are as such, part of the key. So the key is sort of 24 bytes. This is much better than CBC DES.

DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with three keys. This means that each DES operation inside the CBC mode is C=E(ks3,D(ks2,E(ks1,M))). This mode is used by SSL.

The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by reusing ks1 for the final encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of Triple-DES is used by the RSAREF library.

DES_pcbc_encrypt() encrypts/decrypts using the propagating cipher block chaining mode used by Kerberos v4. Its parameters are the same as DES_ncbc_encrypt().

DES_cfb_encrypt() encrypts/decrypts using cipher feedback mode. This method takes an array of characters as input and outputs an array of characters. It does not require any padding to 8 character groups. Note: the ivec variable is changed and the new changed value needs to be passed to the next call to this function. Since this function runs a complete DES ECB encryption per numbits, this function is only suggested for use when sending a small number of characters.

DES_cfb64_encrypt() implements CFB mode of DES with 64-bit feedback. Why is this useful you ask? Because this routine will allow you to encrypt an arbitrary number of bytes, without 8 byte padding. Each call to this routine will encrypt the input bytes to output and then update ivec and num. num contains 'how far' we are though ivec. If this does not make much sense, read more about CFB mode of DES.

DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as DES_cfb64_encrypt() except that Triple-DES is used.

DES_ofb_encrypt() encrypts using output feedback mode. This method takes an array of characters as input and outputs an array of characters. It does not require any padding to 8 character groups. Note: the ivec variable is changed and the new changed value needs to be passed to the next call to this function. Since this function runs a complete DES ECB encryption per numbits, this function is only suggested for use when sending a small number of characters.

DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output Feed Back mode.

DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as DES_ofb64_encrypt(), using Triple-DES.

The following functions are included in the DES library for compatibility with the MIT Kerberos library.

DES_cbc_cksum() produces an 8 byte checksum based on the input stream (via CBC encryption). The last 4 bytes of the checksum are returned and the complete 8 bytes are placed in output. This function is used by Kerberos v4. Other applications should use EVP_DigestInit(3) etc. instead.

DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte checksum from the input bytes. The algorithm can be iterated over the input, depending on out_count, 1, 2, 3 or 4 times. If output is non-NULL, the 8 bytes generated by each pass are written into output.

The following are DES-based transformations:

DES_fcrypt() is a fast version of the Unix crypt(3) function. This version takes only a small amount of space relative to other fast crypt() implementations. This is different to the normal crypt() in that the third parameter is the buffer that the return value is written into. It needs to be at least 14 bytes long. This function is thread safe, unlike the normal crypt().

DES_crypt() is a faster replacement for the normal system crypt(). This function calls DES_fcrypt() with a static array passed as the third parameter. This mostly emulates the normal non-thread-safe semantics of crypt(3). The salt must be two ASCII characters.

The values returned by DES_fcrypt() and DES_crypt() are terminated by NUL character.

DES_enc_write() writes len bytes to file descriptor fd from buffer buf. The data is encrypted via pcbc_encrypt (default) using sched for the key and iv as a starting vector. The actual data send down fd consists of 4 bytes (in network byte order) containing the length of the following encrypted data. The encrypted data then follows, padded with random data out to a multiple of 8 bytes.

"},{"location":"man3/DES_random_key/#bugs","title":"BUGS","text":"

DES_cbc_encrypt() does not modify ivec; use DES_ncbc_encrypt() instead.

DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits. What this means is that if you set numbits to 12, and length to 2, the first 12 bits will come from the 1st input byte and the low half of the second input byte. The second 12 bits will have the low 8 bits taken from the 3rd input byte and the top 4 bits taken from the 4th input byte. The same holds for output. This function has been implemented this way because most people will be using a multiple of 8 and because once you get into pulling bytes input bytes apart things get ugly!

DES_string_to_key() is available for backward compatibility with the MIT library. New applications should use a cryptographic hash function. The same applies for DES_string_to_2key().

"},{"location":"man3/DES_random_key/#notes","title":"NOTES","text":"

The des library was written to be source code compatible with the MIT Kerberos library.

Applications should use the higher level functions EVP_EncryptInit(3) etc. instead of calling these functions directly.

Single-key DES is insecure due to its short key size. ECB mode is not suitable for most applications; see des_modes(7).

"},{"location":"man3/DES_random_key/#return-values","title":"RETURN VALUES","text":"

DES_set_key(), DES_key_sched(), and DES_set_key_checked() return 0 on success or negative values on error.

DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it is ok.

DES_cbc_cksum() and DES_quad_cksum() return 4-byte integer representing the last 4 bytes of the checksum of the input.

DES_fcrypt() returns a pointer to the caller-provided buffer and DES_crypt() - to a static buffer on success; otherwise they return NULL.

"},{"location":"man3/DES_random_key/#see-also","title":"SEE ALSO","text":"

des_modes(7), EVP_EncryptInit(3)

"},{"location":"man3/DES_random_key/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The requirement that the salt parameter to DES_crypt() and DES_fcrypt() be two ASCII characters was first enforced in OpenSSL 1.1.0. Previous versions tried to use the letter uppercase A if both character were not present, and could crash when given non-ASCII on some platforms.

"},{"location":"man3/DES_random_key/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_generate_key/","title":"DH_generate_key","text":""},{"location":"man3/DH_generate_key/#name","title":"NAME","text":"

DH_generate_key, DH_compute_key, DH_compute_key_padded - perform Diffie-Hellman key exchange

"},{"location":"man3/DH_generate_key/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_generate_key(DH *dh);\n\nint DH_compute_key(unsigned char *key, const BIGNUM *pub_key, DH *dh);\n\nint DH_compute_key_padded(unsigned char *key, const BIGNUM *pub_key, DH *dh);\n
"},{"location":"man3/DH_generate_key/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_derive_init(3) and EVP_PKEY_derive(3).

DH_generate_key() performs the first step of a Diffie-Hellman key exchange by generating private and public DH values. By calling DH_compute_key() or DH_compute_key_padded(), these are combined with the other party's public value to compute the shared key.

DH_generate_key() expects dh to contain the shared parameters dh->p and dh->g. It generates a random private DH value unless dh->priv_key is already set, and computes the corresponding public value dh->pub_key, which can then be published.

DH_compute_key() computes the shared secret from the private DH value in dh and the other party's public value in pub_key and stores it in key. key must point to DH_size(dh) bytes of memory. The padding style is RFC 5246 (8.1.2) that strips leading zero bytes. It is not constant time due to the leading zero bytes being stripped. The return value should be considered public.

DH_compute_key_padded() is similar but stores a fixed number of bytes. The padding style is NIST SP 800-56A (C.1) that retains leading zero bytes. It is constant time due to the leading zero bytes being retained. The return value should be considered public.

"},{"location":"man3/DH_generate_key/#return-values","title":"RETURN VALUES","text":"

DH_generate_key() returns 1 on success, 0 otherwise.

DH_compute_key() returns the size of the shared secret on success, -1 on error.

DH_compute_key_padded() returns DH_size(dh) on success, -1 on error.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DH_generate_key/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_derive(3), DH_new(3), ERR_get_error(3), RAND_bytes(3), DH_size(3)

"},{"location":"man3/DH_generate_key/#history","title":"HISTORY","text":"

DH_compute_key_padded() was added in OpenSSL 1.0.2.

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_generate_key/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_generate_parameters/","title":"DH_generate_parameters","text":""},{"location":"man3/DH_generate_parameters/#name","title":"NAME","text":"

DH_generate_parameters_ex, DH_generate_parameters, DH_check, DH_check_params, DH_check_ex, DH_check_params_ex, DH_check_pub_key_ex - generate and check Diffie-Hellman parameters

"},{"location":"man3/DH_generate_parameters/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);\n\nint DH_check(DH *dh, int *codes);\nint DH_check_params(DH *dh, int *codes);\n\nint DH_check_ex(const DH *dh);\nint DH_check_params_ex(const DH *dh);\nint DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key);\n

The following functions have been deprecated since OpenSSL 0.9.8, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH *DH_generate_parameters(int prime_len, int generator,\n                           void (*callback)(int, int, void *), void *cb_arg);\n
"},{"location":"man3/DH_generate_parameters/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_check(3), EVP_PKEY_public_check(3), EVP_PKEY_private_check(3) and EVP_PKEY_param_check(3).

DH_generate_parameters_ex() generates Diffie-Hellman parameters that can be shared among a group of users, and stores them in the provided DH structure. The pseudo-random number generator must be seeded before calling it. The parameters generated by DH_generate_parameters_ex() should not be used in signature schemes.

prime_len is the length in bits of the safe prime to be generated. generator is a small number > 1, typically 2 or 5.

A callback function may be used to provide feedback about the progress of the key generation. If cb is not NULL, it will be called as described in BN_generate_prime(3) while a random prime number is generated, and when a prime has been found, BN_GENCB_call(cb, 3, 0) is called. See BN_generate_prime_ex(3) for information on the BN_GENCB_call() function.

DH_generate_parameters() is similar to DH_generate_prime_ex() but expects an old-style callback function; see BN_generate_prime(3) for information on the old-style callback.

DH_check_params() confirms that the p and g are likely enough to be valid. This is a lightweight check, if a more thorough check is needed, use DH_check(). The value of *codes is updated with any problems found. If *codes is zero then no problems were found, otherwise the following bits may be set:

DH_check() confirms that the Diffie-Hellman parameters dh are valid. The value of *codes is updated with any problems found. If *codes is zero then no problems were found, otherwise the following bits may be set:

If 0 is returned or *codes is set to a nonzero value the supplied parameters should not be used for Diffie-Hellman operations otherwise the security properties of the key exchange are not guaranteed.

DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() are similar to DH_check() and DH_check_params() respectively, but the error reasons are added to the thread's error queue instead of provided as return values from the function.

"},{"location":"man3/DH_generate_parameters/#return-values","title":"RETURN VALUES","text":"

DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1 if the check could be performed, 0 otherwise.

DH_generate_parameters() returns a pointer to the DH structure or NULL if the parameter generation fails.

DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() return 1 if the check is successful, 0 for failed.

The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DH_generate_parameters/#see-also","title":"SEE ALSO","text":"

DH_new(3), ERR_get_error(3), RAND_bytes(3), DH_free(3)

"},{"location":"man3/DH_generate_parameters/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

DH_generate_parameters() was deprecated in OpenSSL 0.9.8; use DH_generate_parameters_ex() instead.

"},{"location":"man3/DH_generate_parameters/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_get0_pqg/","title":"DH_get0_pqg","text":""},{"location":"man3/DH_get0_pqg/#name","title":"NAME","text":"

DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_get0_p, DH_get0_q, DH_get0_g, DH_get0_priv_key, DH_get0_pub_key, DH_clear_flags, DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length, DH_set_length - Routines for getting and setting data in a DH object

"},{"location":"man3/DH_get0_pqg/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DH_get0_pqg(const DH *dh,\n                 const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);\nint DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);\nvoid DH_get0_key(const DH *dh,\n                 const BIGNUM **pub_key, const BIGNUM **priv_key);\nint DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key);\nconst BIGNUM *DH_get0_p(const DH *dh);\nconst BIGNUM *DH_get0_q(const DH *dh);\nconst BIGNUM *DH_get0_g(const DH *dh);\nconst BIGNUM *DH_get0_priv_key(const DH *dh);\nconst BIGNUM *DH_get0_pub_key(const DH *dh);\nvoid DH_clear_flags(DH *dh, int flags);\nint DH_test_flags(const DH *dh, int flags);\nvoid DH_set_flags(DH *dh, int flags);\n\nlong DH_get_length(const DH *dh);\nint DH_set_length(DH *dh, long length);\n\nENGINE *DH_get0_engine(DH *d);\n
"},{"location":"man3/DH_get0_pqg/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bn_param(3) for any methods that return a BIGNUM. Refer to EVP_PKEY-DH(7) for more information.

A DH object contains the parameters p, q and g. Note that the q parameter is optional. It also contains a public key (pub_key) and (optionally) a private key (priv_key).

The p, q and g parameters can be obtained by calling DH_get0_pqg(). If the parameters have not yet been set then *p, *q and *g will be set to NULL. Otherwise they are set to pointers to their respective values. These point directly to the internal representations of the values and therefore should not be freed directly. Any of the out parameters p, q, and g can be NULL, in which case no value will be returned for that parameter.

The p, q and g values can be set by calling DH_set0_pqg() and passing the new values for p, q and g as parameters to the function. Calling this function transfers the memory management of the values to the DH object, and therefore the values that have been passed in should not be freed directly after this function has been called. The q parameter may be NULL. DH_set0_pqg() also checks if the parameters associated with p and g and optionally q are associated with known safe prime groups. If it is a safe prime group then the value of q will be set to q = (p - 1) / 2 if q is NULL. The optional length parameter will be set to BN_num_bits(q) if q is not NULL.

To get the public and private key values use the DH_get0_key() function. A pointer to the public key will be stored in *pub_key, and a pointer to the private key will be stored in *priv_key. Either may be NULL if they have not been set yet, although if the private key has been set then the public key must be. The values point to the internal representation of the public key and private key values. This memory should not be freed directly. Any of the out parameters pub_key and priv_key can be NULL, in which case no value will be returned for that parameter.

The public and private key values can be set using DH_set0_key(). Either parameter may be NULL, which means the corresponding DH field is left untouched. As with DH_set0_pqg() this function transfers the memory management of the key values to the DH object, and therefore they should not be freed directly after this function has been called.

Any of the values p, q, g, priv_key, and pub_key can also be retrieved separately by the corresponding function DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_priv_key(), and DH_get0_pub_key(), respectively.

DH_set_flags() sets the flags in the flags parameter on the DH object. Multiple flags can be passed in one go (bitwise ORed together). Any flags that are already set are left set. DH_test_flags() tests to see whether the flags passed in the flags parameter are currently set in the DH object. Multiple flags can be tested in one go. All flags that are currently set are returned, or zero if none of the flags are set. DH_clear_flags() clears the specified flags within the DH object.

DH_get0_engine() returns a handle to the ENGINE that has been set for this DH object, or NULL if no such ENGINE has been set. This function is deprecated. All engines should be replaced by providers.

The DH_get_length() and DH_set_length() functions get and set the optional length parameter associated with this DH object. If the length is nonzero then it is used, otherwise it is ignored. The length parameter indicates the length of the secret exponent (private key) in bits. For safe prime groups the optional length parameter length can be set to a value greater or equal to 2 * maximum_target_security_strength(BN_num_bits(p)) as listed in SP800-56Ar3 Table(s) 25 & 26. These functions are deprecated and should be replaced with EVP_PKEY_CTX_set_params() and EVP_PKEY_get_int_param() using the parameter key OSSL_PKEY_PARAM_DH_PRIV_LEN as described in EVP_PKEY-DH(7).

"},{"location":"man3/DH_get0_pqg/#notes","title":"NOTES","text":"

Values retrieved with DH_get0_key() are owned by the DH object used in the call and may therefore not be passed to DH_set0_key(). If needed, duplicate the received value using BN_dup() and pass the duplicate. The same applies to DH_get0_pqg() and DH_set0_pqg().

"},{"location":"man3/DH_get0_pqg/#return-values","title":"RETURN VALUES","text":"

DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure.

DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_priv_key(), and DH_get0_pub_key() return the respective value, or NULL if it is unset.

DH_test_flags() returns the current state of the flags in the DH object.

DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE has been set.

DH_get_length() returns the length of the secret exponent (private key) in bits, or zero if no such length has been explicitly set.

"},{"location":"man3/DH_get0_pqg/#see-also","title":"SEE ALSO","text":"

DH_new(3), DH_new(3), DH_generate_parameters(3), DH_generate_key(3), DH_set_method(3), DH_size(3), DH_meth_new(3)

"},{"location":"man3/DH_get0_pqg/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0.

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_get0_pqg/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_get_1024_160/","title":"DH_get_1024_160","text":""},{"location":"man3/DH_get_1024_160/#name","title":"NAME","text":"

DH_get_1024_160, DH_get_2048_224, DH_get_2048_256, BN_get0_nist_prime_192, BN_get0_nist_prime_224, BN_get0_nist_prime_256, BN_get0_nist_prime_384, BN_get0_nist_prime_521, BN_get_rfc2409_prime_768, BN_get_rfc2409_prime_1024, BN_get_rfc3526_prime_1536, BN_get_rfc3526_prime_2048, BN_get_rfc3526_prime_3072, BN_get_rfc3526_prime_4096, BN_get_rfc3526_prime_6144, BN_get_rfc3526_prime_8192 - Create standardized public primes or DH pairs

"},{"location":"man3/DH_get_1024_160/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n\nconst BIGNUM *BN_get0_nist_prime_192(void);\nconst BIGNUM *BN_get0_nist_prime_224(void);\nconst BIGNUM *BN_get0_nist_prime_256(void);\nconst BIGNUM *BN_get0_nist_prime_384(void);\nconst BIGNUM *BN_get0_nist_prime_521(void);\n\nBIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn);\nBIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn);\nBIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/dh.h>\n\nDH *DH_get_1024_160(void);\nDH *DH_get_2048_224(void);\nDH *DH_get_2048_256(void);\n
"},{"location":"man3/DH_get_1024_160/#description","title":"DESCRIPTION","text":"

DH_get_1024_160(), DH_get_2048_224(), and DH_get_2048_256() each return a DH object for the IETF RFC 5114 value. These functions are deprecated. Applications should instead use EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() as described in EVP_PKEY_CTX_ctrl(3) or by setting the OSSL_PKEY_PARAM_GROUP_NAME as specified in \"DH parameters\" in EVP_PKEY-DH(7)) to one of \"dh_1024_160\", \"dh_2048_224\" or \"dh_2048_256\".

BN_get0_nist_prime_192(), BN_get0_nist_prime_224(), BN_get0_nist_prime_256(), BN_get0_nist_prime_384(), and BN_get0_nist_prime_521() functions return a BIGNUM for the specific NIST prime curve (e.g., P-256).

BN_get_rfc2409_prime_768(), BN_get_rfc2409_prime_1024(), BN_get_rfc3526_prime_1536(), BN_get_rfc3526_prime_2048(), BN_get_rfc3526_prime_3072(), BN_get_rfc3526_prime_4096(), BN_get_rfc3526_prime_6144(), and BN_get_rfc3526_prime_8192() functions return a BIGNUM for the specified size from IETF RFC 2409. If bn is not NULL, the BIGNUM will be set into that location as well.

"},{"location":"man3/DH_get_1024_160/#return-values","title":"RETURN VALUES","text":"

Defined above.

"},{"location":"man3/DH_get_1024_160/#history","title":"HISTORY","text":"

The functions DH_get_1024_160(), DH_get_2048_224() and DH_get_2048_256() were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_get_1024_160/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_meth_new/","title":"DH_meth_new","text":""},{"location":"man3/DH_meth_new/#name","title":"NAME","text":"

DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name, DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data, DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key, DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp, DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish, DH_meth_set_finish, DH_meth_get_generate_params, DH_meth_set_generate_params - Routines to build up DH methods

"},{"location":"man3/DH_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH_METHOD *DH_meth_new(const char *name, int flags);\n\nvoid DH_meth_free(DH_METHOD *dhm);\n\nDH_METHOD *DH_meth_dup(const DH_METHOD *dhm);\n\nconst char *DH_meth_get0_name(const DH_METHOD *dhm);\nint DH_meth_set1_name(DH_METHOD *dhm, const char *name);\n\nint DH_meth_get_flags(const DH_METHOD *dhm);\nint DH_meth_set_flags(DH_METHOD *dhm, int flags);\n\nvoid *DH_meth_get0_app_data(const DH_METHOD *dhm);\nint DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data);\n\nint (*DH_meth_get_generate_key(const DH_METHOD *dhm))(DH *);\nint DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key)(DH *));\n\nint (*DH_meth_get_compute_key(const DH_METHOD *dhm))\n    (unsigned char *key, const BIGNUM *pub_key, DH *dh);\nint DH_meth_set_compute_key(DH_METHOD *dhm,\n    int (*compute_key)(unsigned char *key, const BIGNUM *pub_key, DH *dh));\n\nint (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm))\n    (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p,\n     const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);\nint DH_meth_set_bn_mod_exp(DH_METHOD *dhm,\n    int (*bn_mod_exp)(const DH *dh, BIGNUM *r, const BIGNUM *a,\n                      const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,\n                      BN_MONT_CTX *m_ctx));\n\nint (*DH_meth_get_init(const DH_METHOD *dhm))(DH *);\nint DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *));\n\nint (*DH_meth_get_finish(const DH_METHOD *dhm))(DH *);\nint DH_meth_set_finish(DH_METHOD *dhm, int (*finish)(DH *));\n\nint (*DH_meth_get_generate_params(const DH_METHOD *dhm))\n    (DH *, int, int, BN_GENCB *);\nint DH_meth_set_generate_params(DH_METHOD *dhm,\n    int (*generate_params)(DH *, int, int, BN_GENCB *));\n
"},{"location":"man3/DH_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the provider APIs.

The DH_METHOD type is a structure used for the provision of custom DH implementations. It provides a set of functions used by OpenSSL for the implementation of the various DH capabilities.

DH_meth_new() creates a new DH_METHOD structure. It should be given a unique name and a set of flags. The name should be a NULL terminated string, which will be duplicated and stored in the DH_METHOD object. It is the callers responsibility to free the original string. The flags will be used during the construction of a new DH object based on this DH_METHOD. Any new DH object will have those flags set by default.

DH_meth_dup() creates a duplicate copy of the DH_METHOD object passed as a parameter. This might be useful for creating a new DH_METHOD based on an existing one, but with some differences.

DH_meth_free() destroys a DH_METHOD structure and frees up any memory associated with it. If the argument is NULL, nothing is done.

DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This is a pointer to the internal name string and so should not be freed by the caller. DH_meth_set1_name() sets the name of the DH_METHOD to name. The string is duplicated and the copy is stored in the DH_METHOD structure, so the caller remains responsible for freeing the memory associated with the name.

DH_meth_get_flags() returns the current value of the flags associated with this DH_METHOD. DH_meth_set_flags() provides the ability to set these flags.

The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the ability to associate implementation specific data with the DH_METHOD. It is the application's responsibility to free this data before the DH_METHOD is freed via a call to DH_meth_free().

DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the function used for generating a new DH key pair respectively. This function will be called in response to the application calling DH_generate_key(). The parameter for the function has the same meaning as for DH_generate_key().

DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the function used for computing a new DH shared secret respectively. This function will be called in response to the application calling DH_compute_key(). The parameters for the function have the same meaning as for DH_compute_key().

DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function used for computing the following value:

r = a ^ p mod m\n

This function will be called by the default OpenSSL function for DH_generate_key(). The result is stored in the r parameter. This function may be NULL unless using the default generate key function, in which case it must be present.

DH_meth_get_init() and DH_meth_set_init() get and set the function used for creating a new DH instance respectively. This function will be called in response to the application calling DH_new() (if the current default DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method() functions will allocate the memory for the new DH object, and a pointer to this newly allocated structure will be passed as a parameter to the function. This function may be NULL.

DH_meth_get_finish() and DH_meth_set_finish() get and set the function used for destroying an instance of a DH object respectively. This function will be called in response to the application calling DH_free(). A pointer to the DH to be destroyed is passed as a parameter. The destroy function should be used for DH implementation specific clean up. The memory for the DH itself should not be freed by this function. This function may be NULL.

DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the function used for generating DH parameters respectively. This function will be called in response to the application calling DH_generate_parameters_ex() (or DH_generate_parameters()). The parameters for the function have the same meaning as for DH_generate_parameters_ex(). This function may be NULL.

"},{"location":"man3/DH_meth_new/#return-values","title":"RETURN VALUES","text":"

DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object or NULL on failure.

DH_meth_get0_name() and DH_meth_get_flags() return the name and flags associated with the DH_METHOD respectively.

All other DH_meth_get_*() functions return the appropriate function pointer that has been set in the DH_METHOD, or NULL if no such pointer has yet been set.

DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or 0 on failure.

"},{"location":"man3/DH_meth_new/#see-also","title":"SEE ALSO","text":"

DH_new(3), DH_new(3), DH_generate_parameters(3), DH_generate_key(3), DH_set_method(3), DH_size(3), DH_get0_pqg(3)

"},{"location":"man3/DH_meth_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/DH_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_new/","title":"DH_new","text":""},{"location":"man3/DH_new/#name","title":"NAME","text":"

DH_new, DH_free - allocate and free DH objects

"},{"location":"man3/DH_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH* DH_new(void);\n\nvoid DH_free(DH *dh);\n
"},{"location":"man3/DH_new/#description","title":"DESCRIPTION","text":"

DH_new() allocates and initializes a DH structure.

DH_free() frees the DH structure and its components. The values are erased before the memory is returned to the system. If dh is NULL nothing is done.

"},{"location":"man3/DH_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, DH_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

DH_free() returns no value.

"},{"location":"man3/DH_new/#see-also","title":"SEE ALSO","text":"

DH_new(3), ERR_get_error(3), DH_generate_parameters(3), DH_generate_key(3), EVP_PKEY-DH(7)

"},{"location":"man3/DH_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

For replacement see EVP_PKEY-DH(7).

"},{"location":"man3/DH_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_new_by_nid/","title":"DH_new_by_nid","text":""},{"location":"man3/DH_new_by_nid/#name","title":"NAME","text":"

DH_new_by_nid, DH_get_nid - create or get DH named parameters

"},{"location":"man3/DH_new_by_nid/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH *DH_new_by_nid(int nid);\n\nint DH_get_nid(const DH *dh);\n
"},{"location":"man3/DH_new_by_nid/#description","title":"DESCRIPTION","text":"

DH_new_by_nid() creates and returns a DH structure containing named parameters nid. Currently nid must be NID_ffdhe2048, NID_ffdhe3072, NID_ffdhe4096, NID_ffdhe6144, NID_ffdhe8192, NID_modp_1536, NID_modp_2048, NID_modp_3072, NID_modp_4096, NID_modp_6144 or NID_modp_8192.

DH_get_nid() determines if the parameters contained in dh match any named safe prime group. It returns the NID corresponding to the matching parameters or NID_undef if there is no match. This function is deprecated.

"},{"location":"man3/DH_new_by_nid/#return-values","title":"RETURN VALUES","text":"

DH_new_by_nid() returns a set of DH parameters or NULL if an error occurred.

DH_get_nid() returns the NID of the matching set of parameters for p and g and optionally q, otherwise it returns NID_undef if there is no match.

"},{"location":"man3/DH_new_by_nid/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_new_by_nid/#copyright","title":"COPYRIGHT","text":"

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_set_method/","title":"DH_set_method","text":""},{"location":"man3/DH_set_method/#name","title":"NAME","text":"

DH_set_default_method, DH_get_default_method, DH_set_method, DH_new_method, DH_OpenSSL - select DH method

"},{"location":"man3/DH_set_method/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DH_set_default_method(const DH_METHOD *meth);\n\nconst DH_METHOD *DH_get_default_method(void);\n\nint DH_set_method(DH *dh, const DH_METHOD *meth);\n\nDH *DH_new_method(ENGINE *engine);\n\nconst DH_METHOD *DH_OpenSSL(void);\n
"},{"location":"man3/DH_set_method/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the provider APIs.

A DH_METHOD specifies the functions that OpenSSL uses for Diffie-Hellman operations. By modifying the method, alternative implementations such as hardware accelerators may be used. IMPORTANT: See the NOTES section for important information about how these DH API functions are affected by the use of ENGINE API calls.

Initially, the default DH_METHOD is the OpenSSL internal implementation, as returned by DH_OpenSSL().

DH_set_default_method() makes meth the default method for all DH structures created later. NB: This is true only whilst no ENGINE has been set as a default for DH, so this function is no longer recommended. This function is not thread-safe and should not be called at the same time as other OpenSSL functions.

DH_get_default_method() returns a pointer to the current default DH_METHOD. However, the meaningfulness of this result is dependent on whether the ENGINE API is being used, so this function is no longer recommended.

DH_set_method() selects meth to perform all operations using the key dh. This will replace the DH_METHOD used by the DH key and if the previous method was supplied by an ENGINE, the handle to that ENGINE will be released during the change. It is possible to have DH keys that only work with certain DH_METHOD implementations (e.g. from an ENGINE module that supports embedded hardware-protected keys), and in such cases attempting to change the DH_METHOD for the key can have unexpected results.

DH_new_method() allocates and initializes a DH structure so that engine will be used for the DH operations. If engine is NULL, the default ENGINE for DH operations is used, and if no default ENGINE is set, the DH_METHOD controlled by DH_set_default_method() is used.

A new DH_METHOD object may be constructed using DH_meth_new() (see DH_meth_new(3)).

"},{"location":"man3/DH_set_method/#return-values","title":"RETURN VALUES","text":"

DH_OpenSSL() and DH_get_default_method() return pointers to the respective DH_METHODs.

DH_set_default_method() returns no value.

DH_set_method() returns nonzero if the provided meth was successfully set as the method for dh (including unloading the ENGINE handle if the previous method was supplied by an ENGINE).

DH_new_method() returns NULL and sets an error code that can be obtained by ERR_get_error(3) if the allocation fails. Otherwise it returns a pointer to the newly allocated structure.

"},{"location":"man3/DH_set_method/#see-also","title":"SEE ALSO","text":"

DH_new(3), DH_new(3), DH_meth_new(3)

"},{"location":"man3/DH_set_method/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_set_method/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DH_size/","title":"DH_size","text":""},{"location":"man3/DH_size/#name","title":"NAME","text":"

DH_size, DH_bits, DH_security_bits - get Diffie-Hellman prime size and security bits

"},{"location":"man3/DH_size/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dh.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DH_bits(const DH *dh);\n\nint DH_size(const DH *dh);\n\nint DH_security_bits(const DH *dh);\n
"},{"location":"man3/DH_size/#description","title":"DESCRIPTION","text":"

The functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and EVP_PKEY_get_size(3).

DH_bits() returns the number of significant bits.

dh and dh->p must not be NULL.

DH_size() returns the Diffie-Hellman prime size in bytes. It can be used to determine how much memory must be allocated for the shared secret computed by DH_compute_key(3).

DH_security_bits() returns the number of security bits of the given dh key. See BN_security_bits(3).

"},{"location":"man3/DH_size/#return-values","title":"RETURN VALUES","text":"

DH_bits() returns the number of bits in the key, or -1 if dh doesn't hold any key parameters.

DH_size() returns the prime size of Diffie-Hellman in bytes, or -1 if dh doesn't hold any key parameters.

DH_security_bits() returns the number of security bits, or -1 if dh doesn't hold any key parameters.

"},{"location":"man3/DH_size/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_get_bits(3), DH_new(3), DH_generate_key(3), BN_num_bits(3)

"},{"location":"man3/DH_size/#history","title":"HISTORY","text":"

All functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DH_size/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_SIG_new/","title":"DSA_SIG_new","text":""},{"location":"man3/DSA_SIG_new/#name","title":"NAME","text":"

DSA_SIG_get0, DSA_SIG_set0, DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects

"},{"location":"man3/DSA_SIG_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n\nDSA_SIG *DSA_SIG_new(void);\nvoid DSA_SIG_free(DSA_SIG *a);\nvoid DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);\nint DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s);\n
"},{"location":"man3/DSA_SIG_new/#description","title":"DESCRIPTION","text":"

DSA_SIG_new() allocates an empty DSA_SIG structure.

DSA_SIG_free() frees the DSA_SIG structure and its components. The values are erased before the memory is returned to the system. If the argument is NULL, nothing is done.

DSA_SIG_get0() returns internal pointers to the r and s values contained in sig.

The r and s values can be set by calling DSA_SIG_set0() and passing the new values for r and s as parameters to the function. Calling this function transfers the memory management of the values to the DSA_SIG object, and therefore the values that have been passed in should not be freed directly after this function has been called.

"},{"location":"man3/DSA_SIG_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, DSA_SIG_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

DSA_SIG_free() returns no value.

DSA_SIG_set0() returns 1 on success or 0 on failure.

"},{"location":"man3/DSA_SIG_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3), EVP_PKEY_free(3), EVP_PKEY_get_bn_param(3), ERR_get_error(3)

"},{"location":"man3/DSA_SIG_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_do_sign/","title":"DSA_do_sign","text":""},{"location":"man3/DSA_do_sign/#name","title":"NAME","text":"

DSA_do_sign, DSA_do_verify - raw DSA signature operations

"},{"location":"man3/DSA_do_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);\n\nint DSA_do_verify(const unsigned char *dgst, int dgst_len,\n                  DSA_SIG *sig, DSA *dsa);\n
"},{"location":"man3/DSA_do_sign/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_sign_init(3), EVP_PKEY_sign(3), EVP_PKEY_verify_init(3) and EVP_PKEY_verify(3).

DSA_do_sign() computes a digital signature on the len byte message digest dgst using the private key dsa and returns it in a newly allocated DSA_SIG structure.

DSA_sign_setup(3) may be used to precompute part of the signing operation in case signature generation is time-critical.

DSA_do_verify() verifies that the signature sig matches a given message digest dgst of size len. dsa is the signer's public key.

"},{"location":"man3/DSA_do_sign/#return-values","title":"RETURN VALUES","text":"

DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() returns 1 for a valid signature, 0 for an incorrect signature and -1 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_do_sign/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_SIG_new(3), DSA_sign(3)

"},{"location":"man3/DSA_do_sign/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_do_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_dup_DH/","title":"DSA_dup_DH","text":""},{"location":"man3/DSA_dup_DH/#name","title":"NAME","text":"

DSA_dup_DH - create a DH structure out of DSA structure

"},{"location":"man3/DSA_dup_DH/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DH *DSA_dup_DH(const DSA *r);\n
"},{"location":"man3/DSA_dup_DH/#description","title":"DESCRIPTION","text":"

The function described on this page is deprecated. There is no direct replacement, applications should use the EVP_PKEY APIs for Diffie-Hellman operations.

DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q is lost during that conversion, but the resulting DH parameters contain its length.

"},{"location":"man3/DSA_dup_DH/#return-values","title":"RETURN VALUES","text":"

DSA_dup_DH() returns the new DH structure, and NULL on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_dup_DH/#note","title":"NOTE","text":"

Be careful to avoid small subgroup attacks when using this.

"},{"location":"man3/DSA_dup_DH/#see-also","title":"SEE ALSO","text":"

DH_new(3), DSA_new(3), ERR_get_error(3)

"},{"location":"man3/DSA_dup_DH/#history","title":"HISTORY","text":"

This function was deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_dup_DH/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_generate_key/","title":"DSA_generate_key","text":""},{"location":"man3/DSA_generate_key/#name","title":"NAME","text":"

DSA_generate_key - generate DSA key pair

"},{"location":"man3/DSA_generate_key/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_generate_key(DSA *a);\n
"},{"location":"man3/DSA_generate_key/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_keygen_init(3) and EVP_PKEY_keygen(3) as described in EVP_PKEY-DSA(7).

DSA_generate_key() expects a to contain DSA parameters. It generates a new key pair and stores it in a->pub_key and a->priv_key.

The random generator must be seeded prior to calling DSA_generate_key(). If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

"},{"location":"man3/DSA_generate_key/#return-values","title":"RETURN VALUES","text":"

DSA_generate_key() returns 1 on success, 0 otherwise. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_generate_key/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_generate_parameters_ex(3)

"},{"location":"man3/DSA_generate_key/#history","title":"HISTORY","text":"

This function was deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_generate_key/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_generate_parameters/","title":"DSA_generate_parameters","text":""},{"location":"man3/DSA_generate_parameters/#name","title":"NAME","text":"

DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters

"},{"location":"man3/DSA_generate_parameters/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_generate_parameters_ex(DSA *dsa, int bits,\n                               const unsigned char *seed, int seed_len,\n                               int *counter_ret, unsigned long *h_ret,\n                               BN_GENCB *cb);\n

The following functions have been deprecated since OpenSSL 0.9.8, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len,\n                             int *counter_ret, unsigned long *h_ret,\n                             void (*callback)(int, int, void *), void *cb_arg);\n
"},{"location":"man3/DSA_generate_parameters/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_paramgen_init(3) and EVP_PKEY_keygen(3) as described in EVP_PKEY-DSA(7).

DSA_generate_parameters_ex() generates primes p and q and a generator g for use in the DSA and stores the result in dsa.

bits is the length of the prime p to be generated. For lengths under 2048 bits, the length of q is 160 bits; for lengths greater than or equal to 2048 bits, the length of q is set to 256 bits.

If seed is NULL, the primes will be generated at random. If seed_len is less than the length of q, an error is returned.

DSA_generate_parameters_ex() places the iteration count in *counter_ret and a counter used for finding a generator in *h_ret, unless these are NULL.

A callback function may be used to provide feedback about the progress of the key generation. If cb is not NULL, it will be called as shown below. For information on the BN_GENCB structure and the BN_GENCB_call function discussed below, refer to BN_generate_prime(3).

DSA_generate_parameters() is similar to DSA_generate_parameters_ex() but expects an old-style callback function; see BN_generate_prime(3) for information on the old-style callback.

"},{"location":"man3/DSA_generate_parameters/#return-values","title":"RETURN VALUES","text":"

DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. The error codes can be obtained by ERR_get_error(3).

DSA_generate_parameters() returns a pointer to the DSA structure or NULL if the parameter generation fails.

"},{"location":"man3/DSA_generate_parameters/#bugs","title":"BUGS","text":"

Seed lengths greater than 20 are not supported.

"},{"location":"man3/DSA_generate_parameters/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_free(3), BN_generate_prime(3)

"},{"location":"man3/DSA_generate_parameters/#history","title":"HISTORY","text":"

DSA_generate_parameters_ex() was deprecated in OpenSSL 3.0.

DSA_generate_parameters() was deprecated in OpenSSL 0.9.8; use DSA_generate_parameters_ex() instead.

"},{"location":"man3/DSA_generate_parameters/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_get0_pqg/","title":"DSA_get0_pqg","text":""},{"location":"man3/DSA_get0_pqg/#name","title":"NAME","text":"

DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, DSA_get0_p, DSA_get0_q, DSA_get0_g, DSA_get0_pub_key, DSA_get0_priv_key, DSA_clear_flags, DSA_test_flags, DSA_set_flags, DSA_get0_engine - Routines for getting and setting data in a DSA object

"},{"location":"man3/DSA_get0_pqg/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DSA_get0_pqg(const DSA *d,\n                  const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);\nint DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g);\nvoid DSA_get0_key(const DSA *d,\n                  const BIGNUM **pub_key, const BIGNUM **priv_key);\nint DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key);\nconst BIGNUM *DSA_get0_p(const DSA *d);\nconst BIGNUM *DSA_get0_q(const DSA *d);\nconst BIGNUM *DSA_get0_g(const DSA *d);\nconst BIGNUM *DSA_get0_pub_key(const DSA *d);\nconst BIGNUM *DSA_get0_priv_key(const DSA *d);\nvoid DSA_clear_flags(DSA *d, int flags);\nint DSA_test_flags(const DSA *d, int flags);\nvoid DSA_set_flags(DSA *d, int flags);\nENGINE *DSA_get0_engine(DSA *d);\n
"},{"location":"man3/DSA_get0_pqg/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bn_param(3).

A DSA object contains the parameters p, q and g. It also contains a public key (pub_key) and (optionally) a private key (priv_key).

The p, q and g parameters can be obtained by calling DSA_get0_pqg(). If the parameters have not yet been set then *p, *q and *g will be set to NULL. Otherwise they are set to pointers to their respective values. These point directly to the internal representations of the values and therefore should not be freed directly.

The p, q and g values can be set by calling DSA_set0_pqg() and passing the new values for p, q and g as parameters to the function. Calling this function transfers the memory management of the values to the DSA object, and therefore the values that have been passed in should not be freed directly after this function has been called.

To get the public and private key values use the DSA_get0_key() function. A pointer to the public key will be stored in *pub_key, and a pointer to the private key will be stored in *priv_key. Either may be NULL if they have not been set yet, although if the private key has been set then the public key must be. The values point to the internal representation of the public key and private key values. This memory should not be freed directly.

The public and private key values can be set using DSA_set0_key(). The public key must be non-NULL the first time this function is called on a given DSA object. The private key may be NULL. On subsequent calls, either may be NULL, which means the corresponding DSA field is left untouched. As for DSA_set0_pqg() this function transfers the memory management of the key values to the DSA object, and therefore they should not be freed directly after this function has been called.

Any of the values p, q, g, priv_key, and pub_key can also be retrieved separately by the corresponding function DSA_get0_p(), DSA_get0_q(), DSA_get0_g(), DSA_get0_priv_key(), and DSA_get0_pub_key(), respectively.

DSA_set_flags() sets the flags in the flags parameter on the DSA object. Multiple flags can be passed in one go (bitwise ORed together). Any flags that are already set are left set. DSA_test_flags() tests to see whether the flags passed in the flags parameter are currently set in the DSA object. Multiple flags can be tested in one go. All flags that are currently set are returned, or zero if none of the flags are set. DSA_clear_flags() clears the specified flags within the DSA object.

DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA object, or NULL if no such ENGINE has been set.

"},{"location":"man3/DSA_get0_pqg/#notes","title":"NOTES","text":"

Values retrieved with DSA_get0_key() are owned by the DSA object used in the call and may therefore not be passed to DSA_set0_key(). If needed, duplicate the received value using BN_dup() and pass the duplicate. The same applies to DSA_get0_pqg() and DSA_set0_pqg().

"},{"location":"man3/DSA_get0_pqg/#return-values","title":"RETURN VALUES","text":"

DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure.

DSA_test_flags() returns the current state of the flags in the DSA object.

DSA_get0_engine() returns the ENGINE set for the DSA object or NULL if no ENGINE has been set.

"},{"location":"man3/DSA_get0_pqg/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_get_bn_param(3), DSA_new(3), DSA_new(3), DSA_generate_parameters(3), DSA_generate_key(3), DSA_dup_DH(3), DSA_do_sign(3), DSA_set_method(3), DSA_SIG_new(3), DSA_sign(3), DSA_size(3), DSA_meth_new(3)

"},{"location":"man3/DSA_get0_pqg/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 1.1.0 and deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_get0_pqg/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_meth_new/","title":"DSA_meth_new","text":""},{"location":"man3/DSA_meth_new/#name","title":"NAME","text":"

DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name, DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags, DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign, DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup, DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp, DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp, DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish, DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen, DSA_meth_set_keygen - Routines to build up DSA methods

"},{"location":"man3/DSA_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA_METHOD *DSA_meth_new(const char *name, int flags);\n\nvoid DSA_meth_free(DSA_METHOD *dsam);\n\nDSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth);\n\nconst char *DSA_meth_get0_name(const DSA_METHOD *dsam);\nint DSA_meth_set1_name(DSA_METHOD *dsam, const char *name);\n\nint DSA_meth_get_flags(const DSA_METHOD *dsam);\nint DSA_meth_set_flags(DSA_METHOD *dsam, int flags);\n\nvoid *DSA_meth_get0_app_data(const DSA_METHOD *dsam);\nint DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data);\n\nDSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))(const unsigned char *,\n                                                      int, DSA *);\nint DSA_meth_set_sign(DSA_METHOD *dsam, DSA_SIG *(*sign)(const unsigned char *,\n                                                         int, DSA *));\n\nint (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))(DSA *, BN_CTX *,$\n                                                       BIGNUM **, BIGNUM **);\nint DSA_meth_set_sign_setup(DSA_METHOD *dsam, int (*sign_setup)(DSA *, BN_CTX *,\n                                                                BIGNUM **, BIGNUM **));\n\nint (*DSA_meth_get_verify(const DSA_METHOD *dsam))(const unsigned char *,\n                                                   int, DSA_SIG *, DSA *);\nint DSA_meth_set_verify(DSA_METHOD *dsam, int (*verify)(const unsigned char *,\n                                                        int, DSA_SIG *, DSA *));\n\nint (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *rr, BIGNUM *a1,\n                                                    BIGNUM *p1, BIGNUM *a2, BIGNUM *p2,\n                                                    BIGNUM *m, BN_CTX *ctx,\n                                                    BN_MONT_CTX *in_mont);\nint DSA_meth_set_mod_exp(DSA_METHOD *dsam, int (*mod_exp)(DSA *dsa, BIGNUM *rr,\n                                                          BIGNUM *a1, BIGNUM *p1,\n                                                          BIGNUM *a2, BIGNUM *p2,\n                                                          BIGNUM *m, BN_CTX *ctx,\n                                                          BN_MONT_CTX *mont));\n\nint (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *r, BIGNUM *a,\n                                                       const BIGNUM *p, const BIGNUM *m,\n                                                       BN_CTX *ctx, BN_MONT_CTX *mont);\nint DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam, int (*bn_mod_exp)(DSA *dsa,\n                                                                BIGNUM *r,\n                                                                BIGNUM *a,\n                                                                const BIGNUM *p,\n                                                                const BIGNUM *m,\n                                                                BN_CTX *ctx,\n                                                                BN_MONT_CTX *mont));\n\nint (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *);\nint DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *));\n\nint (*DSA_meth_get_finish(const DSA_METHOD *dsam))(DSA *);\nint DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish)(DSA *));\n\nint (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))(DSA *, int,\n                                                     const unsigned char *,\n                                                     int, int *, unsigned long *,\n                                                     BN_GENCB *);\nint DSA_meth_set_paramgen(DSA_METHOD *dsam,\n                          int (*paramgen)(DSA *, int, const unsigned char *,\n                                          int, int *, unsigned long *, BN_GENCB *));\n\nint (*DSA_meth_get_keygen(const DSA_METHOD *dsam))(DSA *);\nint DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen)(DSA *));\n
"},{"location":"man3/DSA_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications and extension implementations should instead use the OSSL_PROVIDER APIs.

The DSA_METHOD type is a structure used for the provision of custom DSA implementations. It provides a set of functions used by OpenSSL for the implementation of the various DSA capabilities.

DSA_meth_new() creates a new DSA_METHOD structure. It should be given a unique name and a set of flags. The name should be a NULL terminated string, which will be duplicated and stored in the DSA_METHOD object. It is the callers responsibility to free the original string. The flags will be used during the construction of a new DSA object based on this DSA_METHOD. Any new DSA object will have those flags set by default.

DSA_meth_dup() creates a duplicate copy of the DSA_METHOD object passed as a parameter. This might be useful for creating a new DSA_METHOD based on an existing one, but with some differences.

DSA_meth_free() destroys a DSA_METHOD structure and frees up any memory associated with it. If the argument is NULL, nothing is done.

DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This is a pointer to the internal name string and so should not be freed by the caller. DSA_meth_set1_name() sets the name of the DSA_METHOD to name. The string is duplicated and the copy is stored in the DSA_METHOD structure, so the caller remains responsible for freeing the memory associated with the name.

DSA_meth_get_flags() returns the current value of the flags associated with this DSA_METHOD. DSA_meth_set_flags() provides the ability to set these flags.

The functions DSA_meth_get0_app_data() and DSA_meth_set0_app_data() provide the ability to associate implementation specific data with the DSA_METHOD. It is the application's responsibility to free this data before the DSA_METHOD is freed via a call to DSA_meth_free().

DSA_meth_get_sign() and DSA_meth_set_sign() get and set the function used for creating a DSA signature respectively. This function will be called in response to the application calling DSA_do_sign() (or DSA_sign()). The parameters for the function have the same meaning as for DSA_do_sign().

DSA_meth_get_sign_setup() and DSA_meth_set_sign_setup() get and set the function used for precalculating the DSA signature values k^-1 and r. This function will be called in response to the application calling DSA_sign_setup(). The parameters for the function have the same meaning as for DSA_sign_setup().

DSA_meth_get_verify() and DSA_meth_set_verify() get and set the function used for verifying a DSA signature respectively. This function will be called in response to the application calling DSA_do_verify() (or DSA_verify()). The parameters for the function have the same meaning as for DSA_do_verify().

DSA_meth_get_mod_exp() and DSA_meth_set_mod_exp() get and set the function used for computing the following value:

rr = a1^p1 * a2^p2 mod m\n

This function will be called by the default OpenSSL method during verification of a DSA signature. The result is stored in the rr parameter. This function may be NULL.

DSA_meth_get_bn_mod_exp() and DSA_meth_set_bn_mod_exp() get and set the function used for computing the following value:

r = a ^ p mod m\n

This function will be called by the default OpenSSL function for DSA_sign_setup(). The result is stored in the r parameter. This function may be NULL.

DSA_meth_get_init() and DSA_meth_set_init() get and set the function used for creating a new DSA instance respectively. This function will be called in response to the application calling DSA_new() (if the current default DSA_METHOD is this one) or DSA_new_method(). The DSA_new() and DSA_new_method() functions will allocate the memory for the new DSA object, and a pointer to this newly allocated structure will be passed as a parameter to the function. This function may be NULL.

DSA_meth_get_finish() and DSA_meth_set_finish() get and set the function used for destroying an instance of a DSA object respectively. This function will be called in response to the application calling DSA_free(). A pointer to the DSA to be destroyed is passed as a parameter. The destroy function should be used for DSA implementation specific clean up. The memory for the DSA itself should not be freed by this function. This function may be NULL.

DSA_meth_get_paramgen() and DSA_meth_set_paramgen() get and set the function used for generating DSA parameters respectively. This function will be called in response to the application calling DSA_generate_parameters_ex() (or DSA_generate_parameters()). The parameters for the function have the same meaning as for DSA_generate_parameters_ex().

DSA_meth_get_keygen() and DSA_meth_set_keygen() get and set the function used for generating a new DSA key pair respectively. This function will be called in response to the application calling DSA_generate_key(). The parameter for the function has the same meaning as for DSA_generate_key().

"},{"location":"man3/DSA_meth_new/#return-values","title":"RETURN VALUES","text":"

DSA_meth_new() and DSA_meth_dup() return the newly allocated DSA_METHOD object or NULL on failure.

DSA_meth_get0_name() and DSA_meth_get_flags() return the name and flags associated with the DSA_METHOD respectively.

All other DSA_meth_get_*() functions return the appropriate function pointer that has been set in the DSA_METHOD, or NULL if no such pointer has yet been set.

DSA_meth_set1_name() and all DSA_meth_set_*() functions return 1 on success or 0 on failure.

"},{"location":"man3/DSA_meth_new/#see-also","title":"SEE ALSO","text":"

DSA_new(3), DSA_new(3), DSA_generate_parameters(3), DSA_generate_key(3), DSA_dup_DH(3), DSA_do_sign(3), DSA_set_method(3), DSA_SIG_new(3), DSA_sign(3), DSA_size(3), DSA_get0_pqg(3)

"},{"location":"man3/DSA_meth_new/#history","title":"HISTORY","text":"

The functions described here were deprecated in OpenSSL 3.0.

The functions described here were added in OpenSSL 1.1.0.

"},{"location":"man3/DSA_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_new/","title":"DSA_new","text":""},{"location":"man3/DSA_new/#name","title":"NAME","text":"

DSA_new, DSA_free - allocate and free DSA objects

"},{"location":"man3/DSA_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

DSA* DSA_new(void);\n\nvoid DSA_free(DSA *dsa);\n
"},{"location":"man3/DSA_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_new(3) and EVP_PKEY_free(3).

DSA_new() allocates and initializes a DSA structure. It is equivalent to calling DSA_new_method(NULL).

DSA_free() frees the DSA structure and its components. The values are erased before the memory is returned to the system. If dsa is NULL nothing is done.

"},{"location":"man3/DSA_new/#return-values","title":"RETURN VALUES","text":"

If the allocation fails, DSA_new() returns NULL and sets an error code that can be obtained by ERR_get_error(3). Otherwise it returns a pointer to the newly allocated structure.

DSA_free() returns no value.

"},{"location":"man3/DSA_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_new(3), EVP_PKEY_free(3), DSA_new(3), ERR_get_error(3), DSA_generate_parameters(3), DSA_generate_key(3)

"},{"location":"man3/DSA_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_set_method/","title":"DSA_set_method","text":""},{"location":"man3/DSA_set_method/#name","title":"NAME","text":"

DSA_set_default_method, DSA_get_default_method, DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method

"},{"location":"man3/DSA_set_method/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void DSA_set_default_method(const DSA_METHOD *meth);\n\nconst DSA_METHOD *DSA_get_default_method(void);\n\nint DSA_set_method(DSA *dsa, const DSA_METHOD *meth);\n\nDSA *DSA_new_method(ENGINE *engine);\n\nconst DSA_METHOD *DSA_OpenSSL(void);\n
"},{"location":"man3/DSA_set_method/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should providers instead of method overrides.

A DSA_METHOD specifies the functions that OpenSSL uses for DSA operations. By modifying the method, alternative implementations such as hardware accelerators may be used. IMPORTANT: See the NOTES section for important information about how these DSA API functions are affected by the use of ENGINE API calls.

Initially, the default DSA_METHOD is the OpenSSL internal implementation, as returned by DSA_OpenSSL().

DSA_set_default_method() makes meth the default method for all DSA structures created later. NB: This is true only whilst no ENGINE has been set as a default for DSA, so this function is no longer recommended. This function is not thread-safe and should not be called at the same time as other OpenSSL functions.

DSA_get_default_method() returns a pointer to the current default DSA_METHOD. However, the meaningfulness of this result is dependent on whether the ENGINE API is being used, so this function is no longer recommended.

DSA_set_method() selects meth to perform all operations using the key rsa. This will replace the DSA_METHOD used by the DSA key and if the previous method was supplied by an ENGINE, the handle to that ENGINE will be released during the change. It is possible to have DSA keys that only work with certain DSA_METHOD implementations (e.g. from an ENGINE module that supports embedded hardware-protected keys), and in such cases attempting to change the DSA_METHOD for the key can have unexpected results. See DSA_meth_new(3) for information on constructing custom DSA_METHOD objects;

DSA_new_method() allocates and initializes a DSA structure so that engine will be used for the DSA operations. If engine is NULL, the default engine for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD controlled by DSA_set_default_method() is used.

"},{"location":"man3/DSA_set_method/#return-values","title":"RETURN VALUES","text":"

DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective DSA_METHODs.

DSA_set_default_method() returns no value.

DSA_set_method() returns nonzero if the provided meth was successfully set as the method for dsa (including unloading the ENGINE handle if the previous method was supplied by an ENGINE).

DSA_new_method() returns NULL and sets an error code that can be obtained by ERR_get_error(3) if the allocation fails. Otherwise it returns a pointer to the newly allocated structure.

"},{"location":"man3/DSA_set_method/#see-also","title":"SEE ALSO","text":"

DSA_new(3), DSA_new(3), DSA_meth_new(3)

"},{"location":"man3/DSA_set_method/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_set_method/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_sign/","title":"DSA_sign","text":""},{"location":"man3/DSA_sign/#name","title":"NAME","text":"

DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures

"},{"location":"man3/DSA_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_sign(int type, const unsigned char *dgst, int len,\n             unsigned char *sigret, unsigned int *siglen, DSA *dsa);\n\nint DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, BIGNUM **rp);\n\nint DSA_verify(int type, const unsigned char *dgst, int len,\n               unsigned char *sigbuf, int siglen, DSA *dsa);\n
"},{"location":"man3/DSA_sign/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_sign_init(3), EVP_PKEY_sign(3), EVP_PKEY_verify_init(3) and EVP_PKEY_verify(3).

DSA_sign() computes a digital signature on the len byte message digest dgst using the private key dsa and places its ASN.1 DER encoding at sigret. The length of the signature is places in *siglen. sigret must point to DSA_size(dsa) bytes of memory.

DSA_sign_setup() is defined only for backward binary compatibility and should not be used. Since OpenSSL 1.1.0 the DSA type is opaque and the output of DSA_sign_setup() cannot be used anyway: calling this function will only cause overhead, and does not affect the actual signature (pre-)computation.

DSA_verify() verifies that the signature sigbuf of size siglen matches a given message digest dgst of size len. dsa is the signer's public key.

The type parameter is ignored.

The random generator must be seeded when DSA_sign() (or DSA_sign_setup()) is called. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to external circumstances (see RAND(7)), the operation will fail.

"},{"location":"man3/DSA_sign/#return-values","title":"RETURN VALUES","text":"

DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. DSA_verify() returns 1 for a valid signature, 0 for an incorrect signature and -1 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/DSA_sign/#conforming-to","title":"CONFORMING TO","text":"

US Federal Information Processing Standard FIPS186-4 (Digital Signature Standard, DSS), ANSI X9.30

"},{"location":"man3/DSA_sign/#see-also","title":"SEE ALSO","text":"

DSA_new(3), ERR_get_error(3), RAND_bytes(3), DSA_do_sign(3), RAND(7)

"},{"location":"man3/DSA_sign/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DSA_size/","title":"DSA_size","text":""},{"location":"man3/DSA_size/#name","title":"NAME","text":"

DSA_size, DSA_bits, DSA_security_bits - get DSA signature size, key bits or security bits

"},{"location":"man3/DSA_size/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/dsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int DSA_bits(const DSA *dsa);\n\nint DSA_size(const DSA *dsa);\n\nint DSA_security_bits(const DSA *dsa);\n
"},{"location":"man3/DSA_size/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3) and EVP_PKEY_get_size(3).

DSA_bits() returns the number of bits in key dsa: this is the number of bits in the p parameter.

DSA_size() returns the maximum size of an ASN.1 encoded DSA signature for key dsa in bytes. It can be used to determine how much memory must be allocated for a DSA signature.

DSA_security_bits() returns the number of security bits of the given dsa key. See BN_security_bits(3).

"},{"location":"man3/DSA_size/#return-values","title":"RETURN VALUES","text":"

DSA_security_bits() returns the number of security bits in the key, or -1 if dsa doesn't hold any key parameters.

DSA_bits() returns the number of bits in the key, or -1 if dsa doesn't hold any key parameters.

DSA_size() returns the signature size in bytes, or -1 if dsa doesn't hold any key parameters.

"},{"location":"man3/DSA_size/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3), EVP_PKEY_get_size(3), DSA_new(3), DSA_sign(3)

"},{"location":"man3/DSA_size/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/DSA_size/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DTLS_get_data_mtu/","title":"DTLS_get_data_mtu","text":""},{"location":"man3/DTLS_get_data_mtu/#name","title":"NAME","text":"

DTLS_get_data_mtu - Get maximum data payload size

"},{"location":"man3/DTLS_get_data_mtu/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nsize_t DTLS_get_data_mtu(const SSL *ssl);\n
"},{"location":"man3/DTLS_get_data_mtu/#description","title":"DESCRIPTION","text":"

This function obtains the maximum data payload size for the established DTLS connection ssl, based on the DTLS record MTU and the overhead of the DTLS record header, encryption and authentication currently in use.

"},{"location":"man3/DTLS_get_data_mtu/#return-values","title":"RETURN VALUES","text":"

Returns the maximum data payload size on success, or 0 on failure.

"},{"location":"man3/DTLS_get_data_mtu/#history","title":"HISTORY","text":"

The DTLS_get_data_mtu() function was added in OpenSSL 1.1.1.

"},{"location":"man3/DTLS_get_data_mtu/#copyright","title":"COPYRIGHT","text":"

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DTLS_set_timer_cb/","title":"DTLS_set_timer_cb","text":""},{"location":"man3/DTLS_set_timer_cb/#name","title":"NAME","text":"

DTLS_timer_cb, DTLS_set_timer_cb - Set callback for controlling DTLS timer duration

"},{"location":"man3/DTLS_set_timer_cb/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\ntypedef unsigned int (*DTLS_timer_cb)(SSL *s, unsigned int timer_us);\n\nvoid DTLS_set_timer_cb(SSL *s, DTLS_timer_cb cb);\n
"},{"location":"man3/DTLS_set_timer_cb/#description","title":"DESCRIPTION","text":"

This function sets an optional callback function for controlling the timeout interval on the DTLS protocol. The callback function will be called by DTLS for every new DTLS packet that is sent.

"},{"location":"man3/DTLS_set_timer_cb/#return-values","title":"RETURN VALUES","text":"

Returns void.

"},{"location":"man3/DTLS_set_timer_cb/#history","title":"HISTORY","text":"

The DTLS_set_timer_cb() function was added in OpenSSL 1.1.1.

"},{"location":"man3/DTLS_set_timer_cb/#copyright","title":"COPYRIGHT","text":"

Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DTLSv1_get_timeout/","title":"DTLSv1_get_timeout","text":""},{"location":"man3/DTLSv1_get_timeout/#name","title":"NAME","text":"

DTLSv1_get_timeout - determine when a DTLS or QUIC SSL object next needs a timeout event to be handled

"},{"location":"man3/DTLSv1_get_timeout/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nint DTLSv1_get_timeout(SSL *s, struct timeval *tv);\n
"},{"location":"man3/DTLSv1_get_timeout/#description","title":"DESCRIPTION","text":"

DTLSv1_get_timeout() can be used on a DTLS or QUIC SSL object to determine when the SSL object next needs to perform internal processing due to the passage of time.

Calling DTLSv1_get_timeout() results in *tv being written with an amount of time left before the SSL object needs have DTLSv1_handle_timeout() called on it. If the SSL object needs to be ticked immediately, *tv is zeroed and the function succeeds, returning 1. If no timeout is currently active, this function returns 0.

This function is only applicable to DTLS and QUIC objects. It fails if called on any other kind of SSL object.

Note that the value output by a call to DTLSv1_get_timeout() may change as a result of other calls to the SSL object.

Once the timeout expires, DTLSv1_handle_timeout() should be called to handle any internal processing which is due; for more information, see DTLSv1_handle_timeout(3).

SSL_get_event_timeout(3) supersedes all use cases for this this function and may be used instead of it.

"},{"location":"man3/DTLSv1_get_timeout/#return-values","title":"RETURN VALUES","text":"

On success, writes a duration to *tv and returns 1.

Returns 0 on failure, or if no timeout is currently active.

"},{"location":"man3/DTLSv1_get_timeout/#see-also","title":"SEE ALSO","text":"

DTLSv1_handle_timeout(3), SSL_get_event_timeout(3), ssl(7)

"},{"location":"man3/DTLSv1_get_timeout/#copyright","title":"COPYRIGHT","text":"

Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DTLSv1_handle_timeout/","title":"DTLSv1_handle_timeout","text":""},{"location":"man3/DTLSv1_handle_timeout/#name","title":"NAME","text":"

DTLSv1_handle_timeout - handle a pending timeout event for a DTLS or QUIC SSL object

"},{"location":"man3/DTLSv1_handle_timeout/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nint DTLSv1_handle_timeout(SSL *ssl);\n
"},{"location":"man3/DTLSv1_handle_timeout/#description","title":"DESCRIPTION","text":"

DTLSv1_handle_timeout() handles any timeout events which have become pending on a DTLS or QUIC SSL object.

Use DTLSv1_get_timeout(3) or SSL_get_event_timeout(3) to determine when to call DTLSv1_handle_timeout().

This function is only applicable to DTLS or QUIC SSL objects. It returns 0 if called on any other kind of SSL object.

SSL_handle_events(3) supersedes all use cases for this function and may be used instead of it.

"},{"location":"man3/DTLSv1_handle_timeout/#return-values","title":"RETURN VALUES","text":"

Returns 1 if there was a pending timeout event and it was handled successfully.

Returns 0 if there was no pending timeout event, or if the SSL object is not a DTLS or QUIC object.

Returns -1 if there was a pending timeout event but it could not be handled successfully.

"},{"location":"man3/DTLSv1_handle_timeout/#see-also","title":"SEE ALSO","text":"

DTLSv1_get_timeout(3), SSL_handle_events(3), ssl(7)

"},{"location":"man3/DTLSv1_handle_timeout/#copyright","title":"COPYRIGHT","text":"

Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/DTLSv1_listen/","title":"DTLSv1_listen","text":""},{"location":"man3/DTLSv1_listen/#name","title":"NAME","text":"

SSL_stateless, DTLSv1_listen - Statelessly listen for incoming connections

"},{"location":"man3/DTLSv1_listen/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ssl.h>\n\nint SSL_stateless(SSL *s);\nint DTLSv1_listen(SSL *ssl, BIO_ADDR *peer);\n
"},{"location":"man3/DTLSv1_listen/#description","title":"DESCRIPTION","text":"

SSL_stateless() statelessly listens for new incoming TLSv1.3 connections. DTLSv1_listen() statelessly listens for new incoming DTLS connections. If a ClientHello is received that does not contain a cookie, then they respond with a request for a new ClientHello that does contain a cookie. If a ClientHello is received with a cookie that is verified then the function returns in order to enable the handshake to be completed (for example by using SSL_accept()).

"},{"location":"man3/DTLSv1_listen/#notes","title":"NOTES","text":"

Some transport protocols (such as UDP) can be susceptible to amplification attacks. Unlike TCP there is no initial connection setup in UDP that validates that the client can actually receive messages on its advertised source address. An attacker could forge its source IP address and then send handshake initiation messages to the server. The server would then send its response to the forged source IP. If the response messages are larger than the original message then the amplification attack has succeeded.

If DTLS is used over UDP (or any datagram based protocol that does not validate the source IP) then it is susceptible to this type of attack. TLSv1.3 is designed to operate over a stream-based transport protocol (such as TCP). If TCP is being used then there is no need to use SSL_stateless(). However, some stream-based transport protocols (e.g. QUIC) may not validate the source address. In this case a TLSv1.3 application would be susceptible to this attack.

As a countermeasure to this issue TLSv1.3 and DTLS include a stateless cookie mechanism. The idea is that when a client attempts to connect to a server it sends a ClientHello message. The server responds with a HelloRetryRequest (in TLSv1.3) or a HelloVerifyRequest (in DTLS) which contains a unique cookie. The client then resends the ClientHello, but this time includes the cookie in the message thus proving that the client is capable of receiving messages sent to that address. All of this can be done by the server without allocating any state, and thus without consuming expensive resources.

OpenSSL implements this capability via the SSL_stateless() and DTLSv1_listen() functions. The ssl parameter should be a newly allocated SSL object with its read and write BIOs set, in the same way as might be done for a call to SSL_accept(). Typically, for DTLS, the read BIO will be in an \"unconnected\" state and thus capable of receiving messages from any peer.

When a ClientHello is received that contains a cookie that has been verified, then these functions will return with the ssl parameter updated into a state where the handshake can be continued by a call to (for example) SSL_accept(). Additionally, for DTLSv1_listen(), the BIO_ADDR pointed to by peer will be filled in with details of the peer that sent the ClientHello. If the underlying BIO is unable to obtain the BIO_ADDR of the peer (for example because the BIO does not support this), then *peer will be cleared and the family set to AF_UNSPEC. Typically user code is expected to \"connect\" the underlying socket to the peer and continue the handshake in a connected state.

Warning: It is essential that the calling code connects the underlying socket to the peer after making use of DTLSv1_listen(). In the typical case where BIO_s_datagram(3) is used, the peer address is updated when receiving a datagram on an unconnected socket. If the socket is not connected, it can receive datagrams from any host on the network, which will cause subsequent outgoing datagrams transmitted by DTLS to be transmitted to that host. In other words, failing to call BIO_connect() or a similar OS-specific function on a socket means that any host on the network can cause outgoing DTLS traffic to be redirected to it by sending a datagram to the socket in question. This does not break the cryptographic protections of DTLS but may facilitate a denial-of-service attack or allow unencrypted information in the DTLS handshake to be learned by an attacker. This is due to the historical design of BIO_s_datagram(3); see BIO_s_datagram(3) for details on this issue.

Once a socket has been connected, BIO_ctrl_set_connected(3) should be used to inform the BIO that the socket is to be used in connected mode.

Prior to calling DTLSv1_listen() user code must ensure that cookie generation and verification callbacks have been set up using SSL_CTX_set_cookie_generate_cb(3) and SSL_CTX_set_cookie_verify_cb(3) respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb(3) and SSL_CTX_set_stateless_cookie_verify_cb(3) must be used instead.

Since DTLSv1_listen() operates entirely statelessly whilst processing incoming ClientHellos it is unable to process fragmented messages (since this would require the allocation of state). An implication of this is that DTLSv1_listen() only supports ClientHellos that fit inside a single datagram.

For SSL_stateless() if an entire ClientHello message cannot be read without the \"read\" BIO becoming empty then the SSL_stateless() call will fail. It is the application's responsibility to ensure that data read from the \"read\" BIO during a single SSL_stateless() call is all from the same peer.

SSL_stateless() will fail (with a 0 return value) if some TLS version less than TLSv1.3 is used.

Both SSL_stateless() and DTLSv1_listen() will clear the error queue when they start.

SSL_stateless() cannot be used with QUIC SSL objects and returns an error if called on such an object.

"},{"location":"man3/DTLSv1_listen/#return-values","title":"RETURN VALUES","text":"

For SSL_stateless() a return value of 1 indicates success and the ssl object will be set up ready to continue the handshake. A return value of 0 or -1 indicates failure. If the value is 0 then a HelloRetryRequest was sent. A value of -1 indicates any other error. User code may retry the SSL_stateless() call.

For DTLSv1_listen() a return value of >= 1 indicates success. The ssl object will be set up ready to continue the handshake. the peer value will also be filled in.

A return value of 0 indicates a non-fatal error. This could (for example) be because of nonblocking IO, or some invalid message having been received from a peer. Errors may be placed on the OpenSSL error queue with further information if appropriate. Typically user code is expected to retry the call to DTLSv1_listen() in the event of a non-fatal error.

A return value of <0 indicates a fatal error. This could (for example) be because of a failure to allocate sufficient memory for the operation.

For DTLSv1_listen(), prior to OpenSSL 1.1.0, fatal and non-fatal errors both produce return codes <= 0 (in typical implementations user code treats all errors as non-fatal), whilst return codes >0 indicate success.

"},{"location":"man3/DTLSv1_listen/#see-also","title":"SEE ALSO","text":"

SSL_CTX_set_cookie_generate_cb(3), SSL_CTX_set_cookie_verify_cb(3), SSL_CTX_set_stateless_cookie_generate_cb(3), SSL_CTX_set_stateless_cookie_verify_cb(3), SSL_get_error(3), SSL_accept(3), ssl(7), bio(7)

"},{"location":"man3/DTLSv1_listen/#history","title":"HISTORY","text":"

The SSL_stateless() function was added in OpenSSL 1.1.1.

The DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of \"peer\" also changed in OpenSSL 1.1.0.

"},{"location":"man3/DTLSv1_listen/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ECDSA_SIG_new/","title":"ECDSA_SIG_new","text":""},{"location":"man3/ECDSA_SIG_new/#name","title":"NAME","text":"

ECDSA_SIG_new, ECDSA_SIG_free, ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0 - Functions for creating, destroying and manipulating ECDSA_SIG objects

"},{"location":"man3/ECDSA_SIG_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ecdsa.h>\n\nECDSA_SIG *ECDSA_SIG_new(void);\nvoid ECDSA_SIG_free(ECDSA_SIG *sig);\nvoid ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps);\nconst BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig);\nconst BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig);\nint ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);\n
"},{"location":"man3/ECDSA_SIG_new/#description","title":"DESCRIPTION","text":"

ECDSA_SIG is an opaque structure consisting of two BIGNUMs for the r and s value of an Elliptic Curve Digital Signature Algorithm (ECDSA) signature (see FIPS186-4 or X9.62). The ECDSA_SIG object was mainly used by the deprecated low level functions described in ECDSA_sign(3), it is still required in order to be able to set or get the values of r and s into or from a signature. This is mainly used for testing purposes as shown in the \"EXAMPLES\".

ECDSA_SIG_new() allocates an empty ECDSA_SIG structure. Note: before OpenSSL 1.1.0, the r and s components were initialised.

ECDSA_SIG_free() frees the ECDSA_SIG structure sig. If the argument is NULL, nothing is done.

ECDSA_SIG_get0() returns internal pointers the r and s values contained in sig and stores them in *pr and *ps, respectively. The pointer pr or ps can be NULL, in which case the corresponding value is not returned.

The values r, s can also be retrieved separately by the corresponding function ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s(), respectively.

Non-NULL r and s values can be set on the sig by calling ECDSA_SIG_set0(). Calling this function transfers the memory management of the values to the ECDSA_SIG object, and therefore the values that have been passed in should not be freed by the caller.

See i2d_ECDSA_SIG(3) and d2i_ECDSA_SIG(3) for information about encoding and decoding ECDSA signatures to/from DER.

"},{"location":"man3/ECDSA_SIG_new/#return-values","title":"RETURN VALUES","text":"

ECDSA_SIG_new() returns NULL if the allocation fails.

ECDSA_SIG_set0() returns 1 on success or 0 on failure.

ECDSA_SIG_get0_r() and ECDSA_SIG_get0_s() return the corresponding value, or NULL if it is unset.

"},{"location":"man3/ECDSA_SIG_new/#examples","title":"EXAMPLES","text":"

Extract signature r and s values from a ECDSA signature of size signaturelen:

ECDSA_SIG *obj;\nconst BIGNUM *r, *s;\n\n/* Load a signature into the ECDSA_SIG object */\nobj = d2i_ECDSA_SIG(NULL, &signature, signaturelen);\nif (obj == NULL)\n    /* error */\n\nr = ECDSA_SIG_get0_r(obj);\ns = ECDSA_SIG_get0_s(obj);\nif (r == NULL || s == NULL)\n    /* error */\n\n/* Use BN_bn2binpad() here to convert to r and s into byte arrays */\n\n/*\n * Do not try to access I<r> or I<s> after calling ECDSA_SIG_free(),\n * as they are both freed by this call.\n */\nECDSA_SIG_free(obj);\n

Convert r and s byte arrays into an ECDSA_SIG signature of size signaturelen:

ECDSA_SIG *obj = NULL;\nunsigned char *signature = NULL;\nsize_t signaturelen;\nBIGNUM *rbn = NULL, *sbn = NULL;\n\nobj = ECDSA_SIG_new();\nif (obj == NULL)\n    /* error */\nrbn = BN_bin2bn(r, rlen, NULL);\nsbn = BN_bin2bn(s, slen, NULL);\nif (rbn == NULL || sbn == NULL)\n    /* error */\n\nif (!ECDSA_SIG_set0(obj, rbn, sbn))\n    /* error */\n/* Set these to NULL since they are now owned by obj */\nrbn = sbn = NULL;\n\nsignaturelen = i2d_ECDSA_SIG(obj, &signature);\nif (signaturelen <= 0)\n    /* error */\n\n/*\n * This signature could now be passed to L<EVP_DigestVerify(3)>\n * or L<EVP_DigestVerifyFinal(3)>\n */\n\nBN_free(rbn);\nBN_free(sbn);\nOPENSSL_free(signature);\nECDSA_SIG_free(obj);\n
"},{"location":"man3/ECDSA_SIG_new/#conforming-to","title":"CONFORMING TO","text":"

ANSI X9.62, US Federal Information Processing Standard FIPS186-4 (Digital Signature Standard, DSS)

"},{"location":"man3/ECDSA_SIG_new/#see-also","title":"SEE ALSO","text":"

EC_KEY_new(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3), EVP_PKEY_sign(3) i2d_ECDSA_SIG(3), d2i_ECDSA_SIG(3), ECDSA_sign(3)

"},{"location":"man3/ECDSA_SIG_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ECDSA_sign/","title":"ECDSA_sign","text":""},{"location":"man3/ECDSA_sign/#name","title":"NAME","text":"

ECDSA_size, ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex, ECDSA_do_sign_ex - deprecated low-level elliptic curve digital signature algorithm (ECDSA) functions

"},{"location":"man3/ECDSA_sign/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ecdsa.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int ECDSA_size(const EC_KEY *eckey);\n\nint ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,\n               unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);\nECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len,\n                         EC_KEY *eckey);\n\nint ECDSA_verify(int type, const unsigned char *dgst, int dgstlen,\n                 const unsigned char *sig, int siglen, EC_KEY *eckey);\nint ECDSA_do_verify(const unsigned char *dgst, int dgst_len,\n                    const ECDSA_SIG *sig, EC_KEY* eckey);\n\nECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,\n                            const BIGNUM *kinv, const BIGNUM *rp,\n                            EC_KEY *eckey);\nint ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp);\nint ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,\n                  unsigned char *sig, unsigned int *siglen,\n                  const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);\n
"},{"location":"man3/ECDSA_sign/#description","title":"DESCRIPTION","text":"

See ECDSA_SIG_new(3) for a description of the ECDSA_SIG object.

See i2d_ECDSA_SIG(3) and d2i_ECDSA_SIG(3) for information about encoding and decoding ECDSA signatures to/from DER.

All of the functions described below are deprecated. Applications should use the higher level EVP interface such as EVP_DigestSignInit(3) or EVP_DigestVerifyInit(3) instead.

ECDSA_size() returns the maximum length of a DER encoded ECDSA signature created with the private EC key eckey. To obtain the actual signature size use EVP_PKEY_sign(3) with a NULL sig parameter.

ECDSA_sign() computes a digital signature of the dgstlen bytes hash value dgst using the private EC key eckey. The DER encoded signatures is stored in sig and its length is returned in sig_len. Note: sig must point to ECDSA_size(eckey) bytes of memory. The parameter type is currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with kinv and rp set to NULL.

ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned as a newly allocated ECDSA_SIG structure (or NULL on error). ECDSA_do_sign() is a wrapper function for ECDSA_do_sign_ex() with kinv and rp set to NULL.

ECDSA_verify() verifies that the signature in sig of size siglen is a valid ECDSA signature of the hash value dgst of size dgstlen using the public key eckey. The parameter type is ignored.

ECDSA_do_verify() is similar to ECDSA_verify() except the signature is presented in the form of a pointer to an ECDSA_SIG structure.

The remaining functions utilise the internal kinv and r values used during signature computation. Most applications will never need to call these and some external ECDSA ENGINE implementations may not support them at all if either kinv or r is not NULL.

ECDSA_sign_setup() may be used to precompute parts of the signing operation. eckey is the private EC key and ctx is a pointer to BN_CTX structure (or NULL). The precomputed values or returned in kinv and rp and can be used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().

ECDSA_sign_ex() computes a digital signature of the dgstlen bytes hash value dgst using the private EC key eckey and the optional pre-computed values kinv and rp. The DER encoded signature is stored in sig and its length is returned in sig_len. Note: sig must point to ECDSA_size(eckey) bytes of memory. The parameter type is ignored.

ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is returned as a newly allocated ECDSA_SIG structure (or NULL on error).

"},{"location":"man3/ECDSA_sign/#return-values","title":"RETURN VALUES","text":"

ECDSA_size() returns the maximum length signature or 0 on error.

ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful or 0 on error.

ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated ECDSA_SIG structure or NULL on error.

ECDSA_verify() and ECDSA_do_verify() return 1 for a valid signature, 0 for an invalid signature and -1 on error. The error codes can be obtained by ERR_get_error(3).

"},{"location":"man3/ECDSA_sign/#examples","title":"EXAMPLES","text":"

Creating an ECDSA signature of a given SHA-256 hash value using the named curve prime256v1 (aka P-256). This example uses deprecated functionality. See \"DESCRIPTION\".

First step: create an EC_KEY object (note: this part is not ECDSA specific)

int ret;\nECDSA_SIG *sig;\nEC_KEY *eckey;\n\neckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);\nif (eckey == NULL)\n    /* error */\nif (EC_KEY_generate_key(eckey) == 0)\n    /* error */\n

Second step: compute the ECDSA signature of a SHA-256 hash value using ECDSA_do_sign():

sig = ECDSA_do_sign(digest, 32, eckey);\nif (sig == NULL)\n    /* error */\n

or using ECDSA_sign():

unsigned char *buffer, *pp;\nint buf_len;\n\nbuf_len = ECDSA_size(eckey);\nbuffer = OPENSSL_malloc(buf_len);\npp = buffer;\nif (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0)\n    /* error */\n

Third step: verify the created ECDSA signature using ECDSA_do_verify():

ret = ECDSA_do_verify(digest, 32, sig, eckey);\n

or using ECDSA_verify():

ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey);\n

and finally evaluate the return value:

if (ret == 1)\n    /* signature ok */\nelse if (ret == 0)\n    /* incorrect signature */\nelse\n    /* error */\n
"},{"location":"man3/ECDSA_sign/#conforming-to","title":"CONFORMING TO","text":"

ANSI X9.62, US Federal Information Processing Standard FIPS186-2 (Digital Signature Standard, DSS)

"},{"location":"man3/ECDSA_sign/#see-also","title":"SEE ALSO","text":"

EC_KEY_new(3), EVP_DigestSignInit(3), EVP_DigestVerifyInit(3), EVP_PKEY_sign(3) i2d_ECDSA_SIG(3), d2i_ECDSA_SIG(3)

"},{"location":"man3/ECDSA_sign/#history","title":"HISTORY","text":"

All functionality described here was deprecated in OpenSSL 3.0.

"},{"location":"man3/ECDSA_sign/#copyright","title":"COPYRIGHT","text":"

Copyright 2004-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ECPKParameters_print/","title":"ECPKParameters_print","text":""},{"location":"man3/ECPKParameters_print/#name","title":"NAME","text":"

ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities

"},{"location":"man3/ECPKParameters_print/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off);\nint ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off);\n
"},{"location":"man3/ECPKParameters_print/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use EVP_PKEY_print_params(3)

The ECPKParameters represent the public parameters for an EC_GROUP structure, which represents a curve.

The ECPKParameters_print() and ECPKParameters_print_fp() functions print a human-readable output of the public parameters of the EC_GROUP to bp or fp. The output lines are indented by off spaces.

"},{"location":"man3/ECPKParameters_print/#return-values","title":"RETURN VALUES","text":"

ECPKParameters_print() and ECPKParameters_print_fp() return 1 for success and 0 if an error occurs.

"},{"location":"man3/ECPKParameters_print/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3),

"},{"location":"man3/ECPKParameters_print/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

"},{"location":"man3/ECPKParameters_print/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EC_GFp_simple_method/","title":"EC_GFp_simple_method","text":""},{"location":"man3/EC_GFp_simple_method/#name","title":"NAME","text":"

EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining EC_METHOD objects

"},{"location":"man3/EC_GFp_simple_method/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EC_METHOD *EC_GFp_simple_method(void);\nconst EC_METHOD *EC_GFp_mont_method(void);\nconst EC_METHOD *EC_GFp_nist_method(void);\nconst EC_METHOD *EC_GFp_nistp224_method(void);\nconst EC_METHOD *EC_GFp_nistp256_method(void);\nconst EC_METHOD *EC_GFp_nistp521_method(void);\n\nconst EC_METHOD *EC_GF2m_simple_method(void);\n\nint EC_METHOD_get_field_type(const EC_METHOD *meth);\n
"},{"location":"man3/EC_GFp_simple_method/#description","title":"DESCRIPTION","text":"

All const EC_METHOD *EC_GF* functions were deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.

The Elliptic Curve library provides a number of different implementations through a single common interface. When constructing a curve using EC_GROUP_new (see EC_GROUP_new(3)) an implementation method must be provided. The functions described here all return a const pointer to an EC_METHOD structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation type for the form of curve selected is used.

For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method.

For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the use of montgomery multiplication (see BN_mod_mul_montgomery(3)). EC_GFp_nist_method offers an implementation optimised for use with NIST recommended curves (NIST curves are available through EC_GROUP_new_by_curve_name as described in EC_GROUP_new(3)).

The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these implementations are not available on all platforms.

EC_METHOD_get_field_type() was deprecated in OpenSSL 3.0. Applications should use EC_GROUP_get_field_type() as a replacement (see EC_GROUP_copy(3)).

"},{"location":"man3/EC_GFp_simple_method/#return-values","title":"RETURN VALUES","text":"

All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure.

EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports.

"},{"location":"man3/EC_GFp_simple_method/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), d2i_ECPKParameters(3), BN_mod_mul_montgomery(3)

"},{"location":"man3/EC_GFp_simple_method/#history","title":"HISTORY","text":"

EC_GFp_simple_method(), EC_GFp_mont_method(void), EC_GFp_nist_method(), EC_GFp_nistp224_method(), EC_GFp_nistp256_method(), EC_GFp_nistp521_method(), EC_GF2m_simple_method(), and EC_METHOD_get_field_type() were deprecated in OpenSSL 3.0.

"},{"location":"man3/EC_GFp_simple_method/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EC_GROUP_copy/","title":"EC_GROUP_copy","text":""},{"location":"man3/EC_GROUP_copy/#name","title":"NAME","text":"

EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor, EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_named_curve, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field, EC_GROUP_get_field_type - Functions for manipulating EC_GROUP objects

"},{"location":"man3/EC_GROUP_copy/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nint EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);\nEC_GROUP *EC_GROUP_dup(const EC_GROUP *src);\n\nint EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator,\n                           const BIGNUM *order, const BIGNUM *cofactor);\nconst EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);\n\nint EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);\nconst BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);\nint EC_GROUP_order_bits(const EC_GROUP *group);\nint EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);\nconst BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group);\nconst BIGNUM *EC_GROUP_get0_field(const EC_GROUP *group);\n\nvoid EC_GROUP_set_curve_name(EC_GROUP *group, int nid);\nint EC_GROUP_get_curve_name(const EC_GROUP *group);\n\nvoid EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);\nint EC_GROUP_get_asn1_flag(const EC_GROUP *group);\n\nvoid EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);\npoint_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *group);\n\nunsigned char *EC_GROUP_get0_seed(const EC_GROUP *group);\nsize_t EC_GROUP_get_seed_len(const EC_GROUP *group);\nsize_t EC_GROUP_set_seed(EC_GROUP *group, const unsigned char *, size_t len);\n\nint EC_GROUP_get_degree(const EC_GROUP *group);\n\nint EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);\nint EC_GROUP_check_named_curve(const EC_GROUP *group, int nist_only,\n                               BN_CTX *ctx);\n\nint EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);\n\nint EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);\n\nint EC_GROUP_get_basis_type(const EC_GROUP *group);\nint EC_GROUP_get_trinomial_basis(const EC_GROUP *group, unsigned int *k);\nint EC_GROUP_get_pentanomial_basis(const EC_GROUP *group, unsigned int *k1,\n                                   unsigned int *k2, unsigned int *k3);\n\nint EC_GROUP_get_field_type(const EC_GROUP *group);\n

The following function has been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);\n
"},{"location":"man3/EC_GROUP_copy/#description","title":"DESCRIPTION","text":"

EC_GROUP_copy() copies the curve src into dst. Both src and dst must use the same EC_METHOD.

EC_GROUP_dup() creates a new EC_GROUP object and copies the content from src to the newly created EC_GROUP object.

EC_GROUP_method_of() obtains the EC_METHOD of group. This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.

EC_GROUP_set_generator() sets curve parameters that must be agreed by all participants using the curve. These parameters include the generator, the order and the cofactor. The generator is a well defined point on the curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and n-1 where n is the order. The order multiplied by the cofactor gives the number of points on the curve.

EC_GROUP_get0_generator() returns the generator for the identified group.

EC_GROUP_get_order() retrieves the order of group and copies its value into order. It fails in case group is not fully initialized (i.e., its order is not set or set to zero).

EC_GROUP_get_cofactor() retrieves the cofactor of group and copies its value into cofactor. It fails in case group is not fully initialized or if the cofactor is not set (or set to zero).

The functions EC_GROUP_set_curve_name() and EC_GROUP_get_curve_name(), set and get the NID for the curve respectively (see EC_GROUP_new(3)). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name will return NID_undef.

The asn1_flag value is used to determine whether the curve encoding uses explicit parameters or a named curve using an ASN1 OID: many applications only support the latter form. If asn1_flag is OPENSSL_EC_NAMED_CURVE then the named curve form is used and the parameters must have a corresponding named curve NID set. If asn1_flags is OPENSSL_EC_EXPLICIT_CURVE the parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag() and EC_GROUP_set_asn1_flag() get and set the status of the asn1_flag for the curve. Note: OPENSSL_EC_EXPLICIT_CURVE was added in OpenSSL 1.1.0, for previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL 1.1.0 the default form was to use explicit parameters (meaning that applications would have to explicitly set the named curve form) in OpenSSL 1.1.0 and later the named curve form is the default.

The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). point_conversion_form_t is an enum defined as follows:

typedef enum {\n       /** the point is encoded as z||x, where the octet z specifies\n        *   which solution of the quadratic equation y is  */\n       POINT_CONVERSION_COMPRESSED = 2,\n       /** the point is encoded as z||x||y, where z is the octet 0x04  */\n       POINT_CONVERSION_UNCOMPRESSED = 4,\n       /** the point is encoded as z||x||y, where the octet z specifies\n        *  which solution of the quadratic equation y is  */\n       POINT_CONVERSION_HYBRID = 6\n} point_conversion_form_t;\n

For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by the octets for x, followed by the octets for y.

For any given x coordinate for a point on a curve it is possible to derive two possible y values. For POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of the two possible solutions for y has been used, followed by the octets for x.

For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two possible solutions for y has been used, followed by the octets for x, followed by the octets for y.

The functions EC_GROUP_set_point_conversion_form() and EC_GROUP_get_point_conversion_form(), set and get the point_conversion_form for the curve respectively.

ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed(). This returns a pointer to a memory block containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len(). A number of the built-in curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using EC_GROUP_set_seed() and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use this seed value, although it will be preserved in any ASN1 based communications.

EC_GROUP_get_degree() gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be the value m.

EC_GROUP_get_field_type() identifies what type of field the EC_GROUP structure supports, which will be either F2^m or Fp.

The function EC_GROUP_check_discriminant() calculates the discriminant for the curve and verifies that it is valid. For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is simply b. In either case for the curve to be valid the discriminant must be non zero.

The function EC_GROUP_check() behaves in the following way: For the OpenSSL default provider it performs a number of checks on a curve to verify that it is valid. Checks performed include verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has the correct order. For the OpenSSL FIPS provider it uses EC_GROUP_check_named_curve() to conform to SP800-56Ar3.

The function EC_GROUP_check_named_curve() determines if the group's domain parameters match one of the built-in curves supported by the library. The curve name is returned as a NID if it matches. If the group's domain parameters have been modified then no match will be found. If the curve name of the given group is NID_undef (e.g. it has been created by using explicit parameters with no curve name), then this method can be used to lookup the name of the curve that matches the group domain parameters. The built-in curves contain aliases, so that multiple NID's can map to the same domain parameters. For such curves it is unspecified which of the aliases will be returned if the curve name of the given group is NID_undef. If nist_only is 1 it will only look for NIST approved curves, otherwise it searches all built-in curves. This function may be passed a BN_CTX object in the ctx parameter. The ctx parameter may be NULL.

EC_GROUP_cmp() compares a and b to determine whether they represent the same curve or not.

The functions EC_GROUP_get_basis_type(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis() should only be called for curves defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial function f(x). This function is either a trinomial of the form:

f(x) = x^m + x^k + 1 with m > k >= 1

or a pentanomial of the form:

f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1

The function EC_GROUP_get_basis_type() returns a NID identifying whether a trinomial or pentanomial is in use for the field. The function EC_GROUP_get_trinomial_basis() must only be called where f(x) is of the trinomial form, and returns the value of k. Similarly the function EC_GROUP_get_pentanomial_basis() must only be called where f(x) is of the pentanomial form, and returns the values of k1, k2 and k3 respectively.

"},{"location":"man3/EC_GROUP_copy/#return-values","title":"RETURN VALUES","text":"

The following functions return 1 on success or 0 on error: EC_GROUP_copy(), EC_GROUP_set_generator(), EC_GROUP_check(), EC_GROUP_check_discriminant(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis().

EC_GROUP_dup() returns a pointer to the duplicated curve, or NULL on error.

EC_GROUP_method_of() returns the EC_METHOD implementation in use for the given curve or NULL on error.

EC_GROUP_get0_generator() returns the generator for the given curve or NULL on error.

EC_GROUP_get_order() returns 0 if the order is not set (or set to zero) for group or if copying into order fails, 1 otherwise.

EC_GROUP_get_cofactor() returns 0 if the cofactor is not set (or is set to zero) for group or if copying into cofactor fails, 1 otherwise.

EC_GROUP_get_curve_name() returns the curve name (NID) for group or will return NID_undef if no curve name is associated.

EC_GROUP_get_asn1_flag() returns the ASN1 flag for the specified group .

EC_GROUP_get_point_conversion_form() returns the point_conversion_form for group.

EC_GROUP_get_degree() returns the degree for group or 0 if the operation is not supported by the underlying group implementation.

EC_GROUP_get_field_type() returns either NID_X9_62_prime_field for prime curves or NID_X9_62_characteristic_two_field for binary curves; these values are defined in the <openssl/obj_mac.h> header file.

EC_GROUP_check_named_curve() returns the nid of the matching named curve, otherwise it returns 0 for no match, or -1 on error.

EC_GROUP_get0_order() returns an internal pointer to the group order. EC_GROUP_order_bits() returns the number of bits in the group order. EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor. EC_GROUP_get0_field() returns an internal pointer to the group field. For curves over GF(p), this is the modulus; for curves over GF(2^m), this is the irreducible polynomial defining the field.

EC_GROUP_get0_seed() returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not specified. EC_GROUP_get_seed_len() returns the length of the seed or 0 if the seed is not specified.

EC_GROUP_set_seed() returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is 0, the return value will be 1. On error 0 is returned.

EC_GROUP_cmp() returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.

EC_GROUP_get_basis_type() returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.

"},{"location":"man3/EC_GROUP_copy/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

"},{"location":"man3/EC_GROUP_copy/#history","title":"HISTORY","text":"

EC_GROUP_method_of() was deprecated in OpenSSL 3.0. EC_GROUP_get0_field(), EC_GROUP_check_named_curve() and EC_GROUP_get_field_type() were added in OpenSSL 3.0. EC_GROUP_get0_order(), EC_GROUP_order_bits() and EC_GROUP_get0_cofactor() were added in OpenSSL 1.1.0.

"},{"location":"man3/EC_GROUP_copy/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EC_GROUP_new/","title":"EC_GROUP_new","text":""},{"location":"man3/EC_GROUP_new/#name","title":"NAME","text":"

EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, EC_GROUP_new_from_params, EC_GROUP_to_params, EC_GROUP_new_from_ecparameters, EC_GROUP_new_from_ecpkparameters, EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name_ex, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve, EC_GROUP_get_curve, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves, OSSL_EC_curve_nid2name - Functions for creating and destroying EC_GROUP objects

"},{"location":"man3/EC_GROUP_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nEC_GROUP *EC_GROUP_new_from_params(const OSSL_PARAM params[],\n                                   OSSL_LIB_CTX *libctx, const char *propq);\nOSSL_PARAM *EC_GROUP_to_params(const EC_GROUP *group, OSSL_LIB_CTX *libctx,\n                               const char *propq, BN_CTX *bnctx);\nEC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params);\nEC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params);\nvoid EC_GROUP_free(EC_GROUP *group);\n\nEC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,\n                                 const BIGNUM *b, BN_CTX *ctx);\nEC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,\n                                  const BIGNUM *b, BN_CTX *ctx);\nEC_GROUP *EC_GROUP_new_by_curve_name_ex(OSSL_LIB_CTX *libctx, const char *propq,\n                                        int nid);\nEC_GROUP *EC_GROUP_new_by_curve_name(int nid);\n\nint EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,\n                       const BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b,\n                       BN_CTX *ctx);\n\nECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group,\n                                        ECPARAMETERS *params);\nECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group,\n                                            ECPKPARAMETERS *params);\n\nsize_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);\nconst char *OSSL_EC_curve_nid2name(int nid);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);\nvoid EC_GROUP_clear_free(EC_GROUP *group);\n\nint EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p,\n                           const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p,\n                           BIGNUM *a, BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p,\n                            const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);\nint EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p,\n                            BIGNUM *a, BIGNUM *b, BN_CTX *ctx);\n
"},{"location":"man3/EC_GROUP_new/#description","title":"DESCRIPTION","text":"

Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised elliptic curve equation as follows:

y^2 mod p = x^3 +ax + b mod p

The second form is those defined over a binary field F2^m where the elements of the field are integers of length at most m bits. For this form the elliptic curve equation is modified to:

y^2 + xy = x^3 + ax^2 + b (where b != 0)

Operations in a binary field are performed relative to an irreducible polynomial. All such curves with OpenSSL use a trinomial or a pentanomial for this parameter.

Although deprecated since OpenSSL 3.0 and should no longer be used, a new curve can be constructed by calling EC_GROUP_new(), using the implementation provided by meth (see EC_GFp_simple_method(3)) and associated with the library context ctx (see OSSL_LIB_CTX(3)). The ctx parameter may be NULL in which case the default library context is used. It is then necessary to call EC_GROUP_set_curve() to set the curve parameters. Applications should instead use one of the other EC_GROUP_new_* constructors.

EC_GROUP_new_from_params() creates a group with parameters specified by params. The library context libctx (see OSSL_LIB_CTX(3)) and property query string propq are used to fetch algorithms from providers. params may be either a list of explicit params or a named group, The values for ctx and propq may be NULL. The params that can be used are described in EVP_PKEY-EC(7).

EC_GROUP_to_params creates an OSSL_PARAM array with the corresponding parameters describing the given EC_GROUP. The resulting parameters may contain parameters describing a named or explicit curve depending on the EC_GROUP. The library context libctx (see OSSL_LIB_CTX(3)) and property query string propq are used to fetch algorithms from providers. bnctx is an optional preallocated BN_CTX (to save the overhead of allocating and freeing the structure in a loop). The values for libctx, propq and bnctx may be NULL. The caller is responsible for freeing the OSSL_PARAM pointer returned.

EC_GROUP_new_from_ecparameters() will create a group from the specified params and EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK params.

EC_GROUP_set_curve() sets the curve parameters p, a and b. For a curve over Fp p is the prime for the field. For a curve over F2^m p represents the irreducible polynomial - each bit represents a term in the polynomial. Therefore, there will either be three or five bits set dependent on whether the polynomial is a trinomial or a pentanomial. In either case, a and b represents the coefficients a and b from the relevant equation introduced above.

EC_group_get_curve() obtains the previously set curve parameters.

EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for EC_GROUP_set_curve(). They are defined for backwards compatibility only and should not be used.

EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for EC_GROUP_get_curve(). They are defined for backwards compatibility only and should not be used.

The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m() are shortcuts for calling EC_GROUP_new() and then the EC_GROUP_set_curve() function. An appropriate default implementation method will be used.

Whilst the library can be used to create any curve using the functions described above, there are also a number of predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function EC_get_builtin_curves(). The parameter r should be an array of EC_builtin_curve structures of size nitems. The function will populate the r array with information about the built-in curves. If nitems is less than the total number of curves available, then the first nitems curves will be returned. Otherwise the total number of curves will be provided. The return value is the total number of curves available (whether that number has been populated in r or not). Passing a NULL r, or setting nitems to 0 will do nothing other than return the total number of curves available. The EC_builtin_curve structure is defined as follows:

typedef struct {\n       int nid;\n       const char *comment;\n       } EC_builtin_curve;\n

Each EC_builtin_curve item has a unique integer id (nid), and a human readable comment string describing the curve.

In order to construct a built-in curve use the function EC_GROUP_new_by_curve_name_ex() and provide the nid of the curve to be constructed, the associated library context to be used in ctx (see OSSL_LIB_CTX(3)) and any property query string in propq. The ctx value may be NULL in which case the default library context is used. The propq value may also be NULL.

EC_GROUP_new_by_curve_name() is the same as EC_GROUP_new_by_curve_name_ex() except that the default library context is always used along with a NULL property query string.

EC_GROUP_free() frees the memory associated with the EC_GROUP. If group is NULL nothing is done.

EC_GROUP_clear_free() is deprecated: it was meant to destroy any sensitive data held within the EC_GROUP and then free its memory, but since all the data stored in the EC_GROUP is public anyway, this function is unnecessary. Its use can be safely replaced with EC_GROUP_free(). If group is NULL nothing is done.

OSSL_EC_curve_nid2name() converts a curve nid into the corresponding name.

"},{"location":"man3/EC_GROUP_new/#return-values","title":"RETURN VALUES","text":"

All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.

EC_get_builtin_curves() returns the number of built-in curves that are available.

EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(), EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error.

OSSL_EC_curve_nid2name() returns a character string constant, or NULL on error.

"},{"location":"man3/EC_GROUP_new/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3), OSSL_LIB_CTX(3), EVP_PKEY-EC(7)

"},{"location":"man3/EC_GROUP_new/#history","title":"HISTORY","text":""},{"location":"man3/EC_GROUP_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EC_KEY_get_enc_flags/","title":"EC_KEY_get_enc_flags","text":""},{"location":"man3/EC_KEY_get_enc_flags/#name","title":"NAME","text":"

EC_KEY_get_enc_flags, EC_KEY_set_enc_flags - Get and set flags for encoding EC_KEY structures

"},{"location":"man3/EC_KEY_get_enc_flags/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nunsigned int EC_KEY_get_enc_flags(const EC_KEY *key);\nvoid EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags);\n
"},{"location":"man3/EC_KEY_get_enc_flags/#description","title":"DESCRIPTION","text":"

The format of the external representation of the public key written by i2d_ECPrivateKey() (such as whether it is stored in a compressed form or not) is described by the point_conversion_form. See EC_GROUP_copy(3) for a description of point_conversion_form.

When reading a private key encoded without an associated public key (e.g. if EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey() generates the missing public key automatically. Private keys encoded without parameters (e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using d2i_ECPrivateKey().

The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the value of the encoding flags for the key. There are two encoding flags currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags define the behaviour of how the key is converted into ASN1 in a call to i2d_ECPrivateKey(). If EC_PKEY_NO_PARAMETERS is set then the public parameters for the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is set then the public key is not encoded along with the private key.

"},{"location":"man3/EC_KEY_get_enc_flags/#return-values","title":"RETURN VALUES","text":"

EC_KEY_get_enc_flags() returns the value of the current encoding flags for the EC_KEY.

"},{"location":"man3/EC_KEY_get_enc_flags/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3), d2i_ECPrivateKey(3)

"},{"location":"man3/EC_KEY_get_enc_flags/#copyright","title":"COPYRIGHT","text":"

Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EC_KEY_new/","title":"EC_KEY_new","text":""},{"location":"man3/EC_KEY_new/#name","title":"NAME","text":"

EVP_EC_gen, EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex, EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_engine, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_decoded_from_explicit_params, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates, EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct, EC_KEY_priv2buf - Functions for creating, destroying and manipulating EC_KEY objects

"},{"location":"man3/EC_KEY_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nEVP_PKEY *EVP_EC_gen(const char *curve);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EC_KEY *EC_KEY_new_ex(OSSL_LIB_CTX *ctx, const char *propq);\nEC_KEY *EC_KEY_new(void);\nint EC_KEY_get_flags(const EC_KEY *key);\nvoid EC_KEY_set_flags(EC_KEY *key, int flags);\nvoid EC_KEY_clear_flags(EC_KEY *key, int flags);\nEC_KEY *EC_KEY_new_by_curve_name_ex(OSSL_LIB_CTX *ctx, const char *propq,\n                                    int nid);\nEC_KEY *EC_KEY_new_by_curve_name(int nid);\nvoid EC_KEY_free(EC_KEY *key);\nEC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);\nEC_KEY *EC_KEY_dup(const EC_KEY *src);\nint EC_KEY_up_ref(EC_KEY *key);\nENGINE *EC_KEY_get0_engine(const EC_KEY *eckey);\nconst EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);\nint EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);\nconst BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);\nint EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *priv_key);\nconst EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);\nint EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);\npoint_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);\nvoid EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);\nvoid EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);\nint EC_KEY_decoded_from_explicit_params(const EC_KEY *key);\nint EC_KEY_generate_key(EC_KEY *key);\nint EC_KEY_check_key(const EC_KEY *key);\nint EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y);\nconst EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key);\nint EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth);\n\nint EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len, BN_CTX *ctx);\nsize_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form,\n                      unsigned char **pbuf, BN_CTX *ctx);\n\nint EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len);\nsize_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len);\n\nsize_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf);\nint EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);\n
"},{"location":"man3/EC_KEY_new/#description","title":"DESCRIPTION","text":"

EVP_EC_gen() generates a new EC key pair on the given curve.

All of the functions described below are deprecated. Applications should instead use EVP_EC_gen(), EVP_PKEY_Q_keygen(3), or EVP_PKEY_keygen_init(3) and EVP_PKEY_keygen(3).

An EC_KEY represents a public key and, optionally, the associated private key. A new EC_KEY with no associated curve can be constructed by calling EC_KEY_new_ex() and specifying the associated library context in ctx (see OSSL_LIB_CTX(3)) and property query string propq. The ctx parameter may be NULL in which case the default library context is used. The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling EC_KEY_set_group().

EC_KEY_new() is the same as EC_KEY_new_ex() except that the default library context is always used.

Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name_ex() and supplying the nid of the associated curve, the library context to be used ctx (see OSSL_LIB_CTX(3)) and any property query string propq. The ctx parameter may be NULL in which case the default library context is used. The propq value may also be NULL. See EC_GROUP_new(3) for a description of curve names. This function simply wraps calls to EC_KEY_new_ex() and EC_GROUP_new_by_curve_name_ex().

EC_KEY_new_by_curve_name() is the same as EC_KEY_new_by_curve_name_ex() except that the default library context is always used and a NULL property query string.

Calling EC_KEY_free() decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated with it. If key is NULL nothing is done.

EC_KEY_copy() copies the contents of the EC_KEY in src into dest.

EC_KEY_dup() creates a new EC_KEY object and copies ec_key into it.

EC_KEY_up_ref() increments the reference count associated with the EC_KEY object.

EC_KEY_get0_engine() returns a handle to the ENGINE that has been set for this EC_KEY object.

EC_KEY_generate_key() generates a new public and private key for the supplied eckey object. eckey must have an EC_GROUP object associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the private key.

EC_KEY_check_key() performs various sanity checks on the EC_KEY object to confirm that it is valid.

EC_KEY_set_public_key_affine_coordinates() sets the public key for key based on its affine coordinates; i.e., it constructs an EC_POINT object based on the supplied x and y values and sets the public key to be this EC_POINT. It also performs certain sanity checks on the key to confirm that it is valid.

The functions EC_KEY_get0_group(), EC_KEY_set_group(), EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(), and EC_KEY_set_public_key() get and set the EC_GROUP object, the private key, and the EC_POINT public key for the key respectively. The function EC_KEY_set_private_key() accepts NULL as the priv_key argument to securely clear the private key component from the EC_KEY.

The functions EC_KEY_get_conv_form() and EC_KEY_set_conv_form() get and set the point_conversion_form for the key. For a description of point_conversion_forms please see EC_POINT_new(3).

EC_KEY_set_flags() sets the flags in the flags parameter on the EC_KEY object. Any flags that are already set are left set. The flags currently defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH. EC_KEY_get_flags() returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags() clears the flags indicated by the flags parameter; all other flags are left in their existing state.

EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to EC_GROUP_copy(3) for further information on the asn1_flag.

EC_KEY_decoded_from_explicit_params() returns 1 if the group of the key was decoded from data with explicitly encoded group parameters, -1 if the key is NULL or the group parameters are missing, and 0 otherwise.

EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also EC_POINT_add(3). Modern versions should instead switch to named curves which OpenSSL has hardcoded lookup tables for.

EC_KEY_oct2key() and EC_KEY_key2buf() are identical to the functions EC_POINT_oct2point() and EC_POINT_point2buf() except they use the public key EC_POINT in eckey.

EC_KEY_oct2priv() and EC_KEY_priv2oct() convert between the private key component of eckey and octet form. The octet form consists of the content octets of the privateKey OCTET STRING in an ECPrivateKey ASN.1 structure.

The function EC_KEY_priv2oct() must be supplied with a buffer long enough to store the octet form. The return value provides the number of octets stored. Calling the function with a NULL buffer will not perform the conversion but will just return the required buffer length.

The function EC_KEY_priv2buf() allocates a buffer of suitable length and writes an EC_KEY to it in octet format. The allocated buffer is written to *pbuf and its length is returned. The caller must free up the allocated buffer with a call to OPENSSL_free(). Since the allocated buffer value is written to *pbuf the pbuf parameter MUST NOT be NULL.

EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer.

"},{"location":"man3/EC_KEY_new/#return-values","title":"RETURN VALUES","text":"

EC_KEY_new_ex(), EC_KEY_new(), EC_KEY_new_by_curve_name_ex(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to the newly created EC_KEY object, or NULL on error.

EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an integer.

EC_KEY_copy() returns a pointer to the destination key, or NULL on error.

EC_KEY_get0_engine() returns a pointer to an ENGINE, or NULL if it wasn't set.

EC_KEY_up_ref(), EC_KEY_set_group(), EC_KEY_set_public_key(), EC_KEY_precompute_mult(), EC_KEY_generate_key(), EC_KEY_check_key(), EC_KEY_set_public_key_affine_coordinates(), EC_KEY_oct2key() and EC_KEY_oct2priv() return 1 on success or 0 on error.

EC_KEY_set_private_key() returns 1 on success or 0 on error except when the priv_key argument is NULL, in that case it returns 0, for legacy compatibility, and should not be treated as an error.

EC_KEY_get0_group() returns the EC_GROUP associated with the EC_KEY.

EC_KEY_get0_private_key() returns the private key associated with the EC_KEY.

EC_KEY_get_conv_form() return the point_conversion_form for the EC_KEY.

EC_KEY_key2buf(), EC_KEY_priv2oct() and EC_KEY_priv2buf() return the length of the buffer or 0 on error.

"},{"location":"man3/EC_KEY_new/#see-also","title":"SEE ALSO","text":"

EVP_PKEY_Q_keygen(3) crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3), OSSL_LIB_CTX(3)

"},{"location":"man3/EC_KEY_new/#history","title":"HISTORY","text":"

EVP_EC_gen() was added in OpenSSL 3.0. All other functions described here were deprecated in OpenSSL 3.0. For replacement see EVP_PKEY-EC(7).

"},{"location":"man3/EC_KEY_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EC_POINT_add/","title":"EC_POINT_add","text":""},{"location":"man3/EC_POINT_add/#name","title":"NAME","text":"

EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on EC_POINT objects

"},{"location":"man3/EC_POINT_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nint EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a,\n                 const EC_POINT *b, BN_CTX *ctx);\nint EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);\nint EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);\nint EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);\nint EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);\nint EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);\nint EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n,\n                 const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);\nint EC_POINTs_make_affine(const EC_GROUP *group, size_t num,\n                          EC_POINT *points[], BN_CTX *ctx);\nint EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num,\n                  const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);\nint EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);\nint EC_GROUP_have_precompute_mult(const EC_GROUP *group);\n
"},{"location":"man3/EC_POINT_add/#description","title":"DESCRIPTION","text":"

EC_POINT_add adds the two points a and b and places the result in r. Similarly EC_POINT_dbl doubles the point a and places the result in r. In both cases it is valid for r to be one of a or b.

EC_POINT_invert calculates the inverse of the supplied point a. The result is placed back in a.

The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.

EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.

EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.

The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine coordinate system. In the case of EC_POINTs_make_affine the value num provides the number of points in the array points to be forced. These functions were deprecated in OpenSSL 3.0 and should no longer be used. Modern versions automatically perform this conversion when needed.

EC_POINT_mul calculates the value generator * n + q * m and stores the result in r. The value n may be NULL in which case the result is just q * m (variable point multiplication). Alternatively, both q and m may be NULL, and n non-NULL, in which case the result is just generator * n (fixed point multiplication). When performing a single fixed or variable point multiplication, the underlying implementation uses a constant time algorithm, when the input scalar (either n or m) is in the range [0, ec_group_order).

Although deprecated in OpenSSL 3.0 and should no longer be used, EC_POINTs_mul calculates the value generator * n + q[0] * m[0] + ... + q[num-1] * m[num-1]. As for EC_POINT_mul the value n may be NULL or num may be zero. When performing a fixed point multiplication (n is non-NULL and num is 0) or a variable point multiplication (n is NULL and num is 1), the underlying implementation uses a constant time algorithm, when the input scalar (either n or m[0]) is in the range [0, ec_group_order). Modern versions should instead use EC_POINT_mul(), combined (if needed) with EC_POINT_add() in such rare circumstances.

The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See EC_GROUP_copy(3) for information about the generator. Precomputation functionality was deprecated in OpenSSL 3.0. Users of EC_GROUP_precompute_mult() and EC_GROUP_have_precompute_mult() should switch to named curves which OpenSSL has hardcoded lookup tables for.

"},{"location":"man3/EC_POINT_add/#return-values","title":"RETURN VALUES","text":"

The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.

EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.

EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.

EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.

EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.

"},{"location":"man3/EC_POINT_add/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_new(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

"},{"location":"man3/EC_POINT_add/#history","title":"HISTORY","text":"

EC_POINT_make_affine(), EC_POINTs_make_affine(), EC_POINTs_mul(), EC_GROUP_precompute_mult(), and EC_GROUP_have_precompute_mult() were deprecated in OpenSSL 3.0.

"},{"location":"man3/EC_POINT_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EC_POINT_new/","title":"EC_POINT_new","text":""},{"location":"man3/EC_POINT_new/#name","title":"NAME","text":"

EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates, EC_POINT_get_affine_coordinates, EC_POINT_set_compressed_coordinates, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating EC_POINT objects

"},{"location":"man3/EC_POINT_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/ec.h>\n\nEC_POINT *EC_POINT_new(const EC_GROUP *group);\nvoid EC_POINT_free(EC_POINT *point);\nvoid EC_POINT_clear_free(EC_POINT *point);\nint EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);\nEC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);\nint EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);\nint EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,\n                                    const BIGNUM *x, const BIGNUM *y,\n                                    BN_CTX *ctx);\nint EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p,\n                                    BIGNUM *x, BIGNUM *y, BN_CTX *ctx);\nint EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p,\n                                        const BIGNUM *x, int y_bit,\n                                        BN_CTX *ctx);\nsize_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,\n                          point_conversion_form_t form,\n                          unsigned char *buf, size_t len, BN_CTX *ctx);\nsize_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point,\n                          point_conversion_form_t form,\n                          unsigned char **pbuf, BN_CTX *ctx);\nint EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,\n                       const unsigned char *buf, size_t len, BN_CTX *ctx);\nchar *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p,\n                         point_conversion_form_t form, BN_CTX *ctx);\nEC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex,\n                             EC_POINT *p, BN_CTX *ctx);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);\nint EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,\n                                             EC_POINT *p,\n                                             const BIGNUM *x, const BIGNUM *y,\n                                             const BIGNUM *z, BN_CTX *ctx);\nint EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,\n                                             const EC_POINT *p,\n                                             BIGNUM *x, BIGNUM *y, BIGNUM *z,\n                                             BN_CTX *ctx);\nint EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,\n                                        const BIGNUM *x, const BIGNUM *y,\n                                        BN_CTX *ctx);\nint EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,\n                                        const EC_POINT *p,\n                                        BIGNUM *x, BIGNUM *y, BN_CTX *ctx);\nint EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group,\n                                            EC_POINT *p,\n                                            const BIGNUM *x, int y_bit,\n                                            BN_CTX *ctx);\nint EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,\n                                         const BIGNUM *x, const BIGNUM *y,\n                                         BN_CTX *ctx);\nint EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,\n                                         const EC_POINT *p,\n                                         BIGNUM *x, BIGNUM *y, BN_CTX *ctx);\nint EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group,\n                                             EC_POINT *p,\n                                             const BIGNUM *x, int y_bit,\n                                             BN_CTX *ctx);\nBIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p,\n                          point_conversion_form_t form, BIGNUM *bn,\n                          BN_CTX *ctx);\nEC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn,\n                            EC_POINT *p, BN_CTX *ctx);\n
"},{"location":"man3/EC_POINT_new/#description","title":"DESCRIPTION","text":"

An EC_POINT structure represents a point on a curve. A new point is constructed by calling the function EC_POINT_new() and providing the group object that the point relates to.

EC_POINT_free() frees the memory associated with the EC_POINT. if point is NULL nothing is done.

EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and then frees its memory. If point is NULL nothing is done.

EC_POINT_copy() copies the point src into dst. Both src and dst must use the same EC_METHOD.

EC_POINT_dup() creates a new EC_POINT object and copies the content from src to the newly created EC_POINT object.

EC_POINT_method_of() obtains the EC_METHOD associated with point. This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.

A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity().

The affine coordinates for a point describe a point in terms of its x and y position. The function EC_POINT_set_affine_coordinates() sets the x and y coordinates for the point p defined over the curve given in group. The function EC_POINT_get_affine_coordinates() sets x and y, either of which may be NULL, to the corresponding coordinates of p.

The functions EC_POINT_set_affine_coordinates_GFp() and EC_POINT_set_affine_coordinates_GF2m() are synonyms for EC_POINT_set_affine_coordinates(). They are defined for backwards compatibility only and should not be used.

The functions EC_POINT_get_affine_coordinates_GFp() and EC_POINT_get_affine_coordinates_GF2m() are synonyms for EC_POINT_get_affine_coordinates(). They are defined for backwards compatibility only and should not be used.

As well as the affine coordinates, a point can alternatively be described in terms of its Jacobian projective coordinates (for Fp curves only). Jacobian projective coordinates are expressed as three values x, y and z. Working in this coordinate system provides more efficient point multiplication operations. A mapping exists between Jacobian projective coordinates and affine coordinates. A Jacobian projective coordinate (x, y, z) can be written as an affine coordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective from affine coordinates is simple. The coordinate (x, y) is mapped to (x, y, 1). Although deprecated in OpenSSL 3.0 and should no longer be used, to set or get the projective coordinates in older versions use EC_POINT_set_Jprojective_coordinates_GFp() and EC_POINT_get_Jprojective_coordinates_GFp() respectively. Modern versions should instead use EC_POINT_set_affine_coordinates() and EC_POINT_get_affine_coordinates(), performing the conversion manually using the above maps in such rare circumstances.

Points can also be described in terms of their compressed coordinates. For a point (x, y), for any given value for x such that the point is on the curve there will only ever be two possible values for y. Therefore, a point can be set using the EC_POINT_set_compressed_coordinates() function where x is the x coordinate and y_bit is a value 0 or 1 to identify which of the two possible values for y should be used.

The functions EC_POINT_set_compressed_coordinates_GFp() and EC_POINT_set_compressed_coordinates_GF2m() are synonyms for EC_POINT_set_compressed_coordinates(). They are defined for backwards compatibility only and should not be used.

In addition EC_POINT can be converted to and from various external representations. The octet form is the binary encoding of the ECPoint structure (as defined in RFC5480 and used in certificates and TLS records): only the content octets are present, the OCTET STRING tag and length are not included. BIGNUM form is the octet form interpreted as a big endian integer converted to a BIGNUM structure. Hexadecimal form is the octet form converted to a NULL terminated character string where each character is one of the printable values 0-9 or A-F (or a-f).

The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(), EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively.

The function EC_POINT_point2oct() encodes the given curve point p as an octet string into the buffer buf of size len, using the specified conversion form form. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 (\"Elliptic Curve Cryptography\") standard. Similarly the function EC_POINT_oct2point() decodes a curve point into p from the octet string contained in the given buffer buf of size len, conforming to Sec. 2.3.4 of the SECG SEC 1 (\"Elliptic Curve Cryptography\") standard.

The functions EC_POINT_point2hex() and EC_POINT_point2bn() convert a point p, respectively, to the hexadecimal or BIGNUM representation of the same encoding of the function EC_POINT_point2oct(). Vice versa, similarly to the function EC_POINT_oct2point(), the functions EC_POINT_hex2point() and EC_POINT_point2bn() decode the hexadecimal or BIGNUM representation into the EC_POINT p.

Notice that, according to the standard, the octet string encoding of the point at infinity for a given curve is fixed to a single octet of value zero and that, vice versa, a single octet of size zero is decoded as the point at infinity.

The function EC_POINT_point2oct() must be supplied with a buffer long enough to store the octet form. The return value provides the number of octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length.

The function EC_POINT_point2buf() allocates a buffer of suitable length and writes an EC_POINT to it in octet format. The allocated buffer is written to *pbuf and its length is returned. The caller must free up the allocated buffer with a call to OPENSSL_free(). Since the allocated buffer value is written to *pbuf the pbuf parameter MUST NOT be NULL.

The function EC_POINT_point2hex() will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free this memory with a subsequent call to OPENSSL_free().

"},{"location":"man3/EC_POINT_new/#return-values","title":"RETURN VALUES","text":"

EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL on error.

The following functions return 1 on success or 0 on error: EC_POINT_copy(), EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(), EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), EC_POINT_set_compressed_coordinates_GFp(), EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point().

EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.

EC_POINT_point2oct() and EC_POINT_point2buf() return the length of the required buffer or 0 on error.

EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on error.

EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on error.

EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error.

EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on error.

"},{"location":"man3/EC_POINT_new/#see-also","title":"SEE ALSO","text":"

crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

"},{"location":"man3/EC_POINT_new/#history","title":"HISTORY","text":"

EC_POINT_method_of(), EC_POINT_set_Jprojective_coordinates_GFp(), EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), EC_POINT_set_compressed_coordinates_GFp(), EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_point2bn(), and EC_POINT_bn2point() were deprecated in OpenSSL 3.0.

EC_POINT_set_affine_coordinates, EC_POINT_get_affine_coordinates, and EC_POINT_set_compressed_coordinates were added in OpenSSL 1.1.1.

"},{"location":"man3/EC_POINT_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2013-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ENGINE_add/","title":"ENGINE_add","text":""},{"location":"man3/ENGINE_add/#name","title":"NAME","text":"

ENGINE_get_DH, ENGINE_get_DSA, ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH, ENGINE_get_default_DSA, ENGINE_get_default_RAND, ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first, ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new, ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests, ENGINE_get_destroy_function, ENGINE_get_finish_function, ENGINE_get_init_function, ENGINE_get_load_privkey_function, ENGINE_get_load_pubkey_function, ENGINE_load_private_key, ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, ENGINE_register_DH, ENGINE_register_DSA, ENGINE_register_RAND, ENGINE_register_RSA, ENGINE_register_all_complete, ENGINE_register_ciphers, ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove, ENGINE_set_DH, ENGINE_set_DSA, ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers, ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default, ENGINE_set_default_DH, ENGINE_set_default_DSA, ENGINE_set_default_RAND, ENGINE_set_default_RSA, ENGINE_set_default_ciphers, ENGINE_set_default_digests, ENGINE_set_default_string, ENGINE_set_destroy_function, ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags, ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function, ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref, ENGINE_get_table_flags, ENGINE_cleanup, ENGINE_load_builtin_engines, ENGINE_register_all_DH, ENGINE_register_all_DSA, ENGINE_register_all_RAND, ENGINE_register_all_RSA, ENGINE_register_all_ciphers, ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH, ENGINE_unregister_DSA, ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers, ENGINE_unregister_digests - ENGINE cryptographic module support

"},{"location":"man3/ENGINE_add/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/engine.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

ENGINE *ENGINE_get_first(void);\nENGINE *ENGINE_get_last(void);\nENGINE *ENGINE_get_next(ENGINE *e);\nENGINE *ENGINE_get_prev(ENGINE *e);\n\nint ENGINE_add(ENGINE *e);\nint ENGINE_remove(ENGINE *e);\n\nENGINE *ENGINE_by_id(const char *id);\n\nint ENGINE_init(ENGINE *e);\nint ENGINE_finish(ENGINE *e);\n\nvoid ENGINE_load_builtin_engines(void);\n\nENGINE *ENGINE_get_default_RSA(void);\nENGINE *ENGINE_get_default_DSA(void);\nENGINE *ENGINE_get_default_DH(void);\nENGINE *ENGINE_get_default_RAND(void);\nENGINE *ENGINE_get_cipher_engine(int nid);\nENGINE *ENGINE_get_digest_engine(int nid);\n\nint ENGINE_set_default_RSA(ENGINE *e);\nint ENGINE_set_default_DSA(ENGINE *e);\nint ENGINE_set_default_DH(ENGINE *e);\nint ENGINE_set_default_RAND(ENGINE *e);\nint ENGINE_set_default_ciphers(ENGINE *e);\nint ENGINE_set_default_digests(ENGINE *e);\nint ENGINE_set_default_string(ENGINE *e, const char *list);\n\nint ENGINE_set_default(ENGINE *e, unsigned int flags);\n\nunsigned int ENGINE_get_table_flags(void);\nvoid ENGINE_set_table_flags(unsigned int flags);\n\nint ENGINE_register_RSA(ENGINE *e);\nvoid ENGINE_unregister_RSA(ENGINE *e);\nvoid ENGINE_register_all_RSA(void);\nint ENGINE_register_DSA(ENGINE *e);\nvoid ENGINE_unregister_DSA(ENGINE *e);\nvoid ENGINE_register_all_DSA(void);\nint ENGINE_register_DH(ENGINE *e);\nvoid ENGINE_unregister_DH(ENGINE *e);\nvoid ENGINE_register_all_DH(void);\nint ENGINE_register_RAND(ENGINE *e);\nvoid ENGINE_unregister_RAND(ENGINE *e);\nvoid ENGINE_register_all_RAND(void);\nint ENGINE_register_ciphers(ENGINE *e);\nvoid ENGINE_unregister_ciphers(ENGINE *e);\nvoid ENGINE_register_all_ciphers(void);\nint ENGINE_register_digests(ENGINE *e);\nvoid ENGINE_unregister_digests(ENGINE *e);\nvoid ENGINE_register_all_digests(void);\nint ENGINE_register_complete(ENGINE *e);\nint ENGINE_register_all_complete(void);\n\nint ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));\nint ENGINE_cmd_is_executable(ENGINE *e, int cmd);\nint ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,\n                    long i, void *p, void (*f)(void), int cmd_optional);\nint ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,\n                           int cmd_optional);\n\nENGINE *ENGINE_new(void);\nint ENGINE_free(ENGINE *e);\nint ENGINE_up_ref(ENGINE *e);\n\nint ENGINE_set_id(ENGINE *e, const char *id);\nint ENGINE_set_name(ENGINE *e, const char *name);\nint ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);\nint ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);\nint ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);\nint ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);\nint ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);\nint ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);\nint ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);\nint ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);\nint ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);\nint ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);\nint ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);\nint ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);\nint ENGINE_set_flags(ENGINE *e, int flags);\nint ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);\n\nconst char *ENGINE_get_id(const ENGINE *e);\nconst char *ENGINE_get_name(const ENGINE *e);\nconst RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);\nconst DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);\nconst DH_METHOD *ENGINE_get_DH(const ENGINE *e);\nconst RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);\nENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);\nENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);\nENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);\nENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);\nENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);\nENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);\nENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);\nENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);\nconst EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);\nconst EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);\nint ENGINE_get_flags(const ENGINE *e);\nconst ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);\n\nEVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,\n                                  UI_METHOD *ui_method, void *callback_data);\nEVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,\n                                 UI_METHOD *ui_method, void *callback_data);\n

The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ENGINE_cleanup(void);\n
"},{"location":"man3/ENGINE_add/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the provider APIs.

These functions create, manipulate, and use cryptographic modules in the form of ENGINE objects. These objects act as containers for implementations of cryptographic algorithms, and support a reference-counted mechanism to allow them to be dynamically loaded in and out of the running application.

The cryptographic functionality that can be provided by an ENGINE implementation includes the following abstractions;

RSA_METHOD - for providing alternative RSA implementations\nDSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD,\n      - similarly for other OpenSSL APIs\nEVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid')\nEVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid')\nkey-loading - loading public and/or private EVP_PKEY keys\n
"},{"location":"man3/ENGINE_add/#reference-counting-and-handles","title":"Reference counting and handles","text":"

Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be treated as handles - i.e. not only as pointers, but also as references to the underlying ENGINE object. Ie. one should obtain a new reference when making copies of an ENGINE pointer if the copies will be used (and released) independently.

ENGINE objects have two levels of reference-counting to match the way in which the objects are used. At the most basic level, each ENGINE pointer is inherently a structural reference - a structural reference is required to use the pointer value at all, as this kind of reference is a guarantee that the structure can not be deallocated until the reference is released.

However, a structural reference provides no guarantee that the ENGINE is initialised and able to use any of its cryptographic implementations. Indeed it's quite possible that most ENGINEs will not initialise at all in typical environments, as ENGINEs are typically used to support specialised hardware. To use an ENGINE's functionality, you need a functional reference. This kind of reference can be considered a specialised form of structural reference, because each functional reference implicitly contains a structural reference as well - however to avoid difficult-to-find programming bugs, it is recommended to treat the two kinds of reference independently. If you have a functional reference to an ENGINE, you have a guarantee that the ENGINE has been initialised and is ready to perform cryptographic operations, and will remain initialised until after you have released your reference.

Structural references

This basic type of reference is used for instantiating new ENGINEs, iterating across OpenSSL's internal linked-list of loaded ENGINEs, reading information about an ENGINE, etc. Essentially a structural reference is sufficient if you only need to query or manipulate the data of an ENGINE implementation rather than use its functionality.

The ENGINE_new() function returns a structural reference to a new (empty) ENGINE object. There are other ENGINE API functions that return structural references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next(), ENGINE_get_prev(). All structural references should be released by a corresponding to call to the ENGINE_free() function - the ENGINE object itself will only actually be cleaned up and deallocated when the last structural reference is released. If the argument to ENGINE_free() is NULL, nothing is done.

It should also be noted that many ENGINE API function calls that accept a structural reference will internally obtain another reference - typically this happens whenever the supplied ENGINE will be needed by OpenSSL after the function has returned. Eg. the function to add a new ENGINE to OpenSSL's internal list is ENGINE_add() - if this function returns success, then OpenSSL will have stored a new structural reference internally so the caller is still responsible for freeing their own reference with ENGINE_free() when they are finished with it. In a similar way, some functions will automatically release the structural reference passed to it if part of the function's job is to do so. Eg. the ENGINE_get_next() and ENGINE_get_prev() functions are used for iterating across the internal ENGINE list - they will return a new structural reference to the next (or previous) ENGINE in the list or NULL if at the end (or beginning) of the list, but in either case the structural reference passed to the function is released on behalf of the caller.

To clarify a particular function's handling of references, one should always consult that function's documentation \"man\" page, or failing that the <openssl/engine.h> header file includes some hints.

Functional references

As mentioned, functional references exist when the cryptographic functionality of an ENGINE is required to be available. A functional reference can be obtained in one of two ways; from an existing structural reference to the required ENGINE, or by asking OpenSSL for the default operational ENGINE for a given cryptographic purpose.

To obtain a functional reference from an existing structural reference, call the ENGINE_init() function. This returns zero if the ENGINE was not already operational and couldn't be successfully initialised (e.g. lack of system drivers, no special hardware attached, etc), otherwise it will return nonzero to indicate that the ENGINE is now operational and will have allocated a new functional reference to the ENGINE. All functional references are released by calling ENGINE_finish() (which removes the implicit structural reference as well).

The second way to get a functional reference is by asking OpenSSL for a default implementation for a given task, e.g. by ENGINE_get_default_RSA(), ENGINE_get_default_cipher_engine(), etc. These are discussed in the next section, though they are not usually required by application programmers as they are used automatically when creating and using the relevant algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc.

"},{"location":"man3/ENGINE_add/#default-implementations","title":"Default implementations","text":"

For each supported abstraction, the ENGINE code maintains an internal table of state to control which implementations are available for a given abstraction and which should be used by default. These implementations are registered in the tables and indexed by an 'nid' value, because abstractions like EVP_CIPHER and EVP_DIGEST support many distinct algorithms and modes, and ENGINEs can support arbitrarily many of them. In the case of other abstractions like RSA, DSA, etc, there is only one \"algorithm\" so all implementations implicitly register using the same 'nid' index.

When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g. when calling RSA_new_method(NULL)), a \"get_default\" call will be made to the ENGINE subsystem to process the corresponding state table and return a functional reference to an initialised ENGINE whose implementation should be used. If no ENGINE should (or can) be used, it will return NULL and the caller will operate with a NULL ENGINE handle - this usually equates to using the conventional software implementation. In the latter case, OpenSSL will from then on behave the way it used to before the ENGINE API existed.

Each state table has a flag to note whether it has processed this \"get_default\" query since the table was last modified, because to process this question it must iterate across all the registered ENGINEs in the table trying to initialise each of them in turn, in case one of them is operational. If it returns a functional reference to an ENGINE, it will also cache another reference to speed up processing future queries (without needing to iterate across the table). Likewise, it will cache a NULL response if no ENGINE was available so that future queries won't repeat the same iteration unless the state table changes. This behaviour can also be changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using ENGINE_set_table_flags()), no attempted initialisations will take place, instead the only way for the state table to return a non-NULL ENGINE to the \"get_default\" query will be if one is expressly set in the table. Eg. ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except that it also sets the state table's cached response for the \"get_default\" query. In the case of abstractions like EVP_CIPHER, where implementations are indexed by 'nid', these flags and cached-responses are distinct for each 'nid' value.

"},{"location":"man3/ENGINE_add/#application-requirements","title":"Application requirements","text":"

This section will explain the basic things an application programmer should support to make the most useful elements of the ENGINE functionality available to the user. The first thing to consider is whether the programmer wishes to make alternative ENGINE modules available to the application and user. OpenSSL maintains an internal linked list of \"visible\" ENGINEs from which it has to operate - at start-up, this list is empty and in fact if an application does not call any ENGINE API calls and it uses static linking against openssl, then the resulting application binary will not contain any alternative ENGINE code at all. So the first consideration is whether any/all available ENGINE implementations should be made visible to OpenSSL - this is controlled by calling the various \"load\" functions.

The fact that ENGINEs are made visible to OpenSSL (and thus are linked into the program and loaded into memory at run-time) does not mean they are \"registered\" or called into use by OpenSSL automatically - that behaviour is something for the application to control. Some applications will want to allow the user to specify exactly which ENGINE they want used if any is to be used at all. Others may prefer to load all support and have OpenSSL automatically use at run-time any ENGINE that is able to successfully initialise - i.e. to assume that this corresponds to acceleration hardware attached to the machine or some such thing. There are probably numerous other ways in which applications may prefer to handle things, so we will simply illustrate the consequences as they apply to a couple of simple cases and leave developers to consider these and the source code to openssl's built-in utilities as guides.

If no ENGINE API functions are called within an application, then OpenSSL will not allocate any internal resources. Prior to OpenSSL 1.1.0, however, if any ENGINEs are loaded, even if not registered or used, it was necessary to call ENGINE_cleanup() before the program exits.

Using a specific ENGINE implementation

Here we'll assume an application has been configured by its user or admin to want to use the \"ACME\" ENGINE if it is available in the version of OpenSSL the application was compiled with. If it is available, it should be used by default for all RSA, DSA, and symmetric cipher operations, otherwise OpenSSL should use its built-in software as per usual. The following code illustrates how to approach this;

ENGINE *e;\nconst char *engine_id = \"ACME\";\nENGINE_load_builtin_engines();\ne = ENGINE_by_id(engine_id);\nif (!e)\n    /* the engine isn't available */\n    return;\nif (!ENGINE_init(e)) {\n    /* the engine couldn't initialise, release 'e' */\n    ENGINE_free(e);\n    return;\n}\nif (!ENGINE_set_default_RSA(e))\n    /*\n     * This should only happen when 'e' can't initialise, but the previous\n     * statement suggests it did.\n     */\n    abort();\nENGINE_set_default_DSA(e);\nENGINE_set_default_ciphers(e);\n/* Release the functional reference from ENGINE_init() */\nENGINE_finish(e);\n/* Release the structural reference from ENGINE_by_id() */\nENGINE_free(e);\n

Automatically using built-in ENGINE implementations

Here we'll assume we want to load and register all ENGINE implementations bundled with OpenSSL, such that for any cryptographic algorithm required by OpenSSL - if there is an ENGINE that implements it and can be initialised, it should be used. The following code illustrates how this can work;

/* Load all bundled ENGINEs into memory and make them visible */\nENGINE_load_builtin_engines();\n/* Register all of them for every algorithm they collectively implement */\nENGINE_register_all_complete();\n

That's all that's required. Eg. the next time OpenSSL tries to set up an RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to ENGINE_init() and if any of those succeed, that ENGINE will be set as the default for RSA use from then on.

"},{"location":"man3/ENGINE_add/#advanced-configuration-support","title":"Advanced configuration support","text":"

There is a mechanism supported by the ENGINE framework that allows each ENGINE implementation to define an arbitrary set of configuration \"commands\" and expose them to OpenSSL and any applications based on OpenSSL. This mechanism is entirely based on the use of name-value pairs and assumes ASCII input (no unicode or UTF for now!), so it is ideal if applications want to provide a transparent way for users to provide arbitrary configuration \"directives\" directly to such ENGINEs. It is also possible for the application to dynamically interrogate the loaded ENGINE implementations for the names, descriptions, and input flags of their available \"control commands\", providing a more flexible configuration scheme. However, if the user is expected to know which ENGINE device he/she is using (in the case of specialised hardware, this goes without saying) then applications may not need to concern themselves with discovering the supported control commands and simply prefer to pass settings into ENGINEs exactly as they are provided by the user.

Before illustrating how control commands work, it is worth mentioning what they are typically used for. Broadly speaking there are two uses for control commands; the first is to provide the necessary details to the implementation (which may know nothing at all specific to the host system) so that it can be initialised for use. This could include the path to any driver or config files it needs to load, required network addresses, smart-card identifiers, passwords to initialise protected devices, logging information, etc etc. This class of commands typically needs to be passed to an ENGINE before attempting to initialise it, i.e. before calling ENGINE_init(). The other class of commands consist of settings or operations that tweak certain behaviour or cause certain operations to take place, and these commands may work either before or after ENGINE_init(), or in some cases both. ENGINE implementations should provide indications of this in the descriptions attached to built-in control commands and/or in external product documentation.

Issuing control commands to an ENGINE

Let's illustrate by example; a function for which the caller supplies the name of the ENGINE it wishes to use, a table of string-pairs for use before initialisation, and another table for use after initialisation. Note that the string-pairs used for control commands consist of a command \"name\" followed by the command \"parameter\" - the parameter could be NULL in some cases but the name can not. This function should initialise the ENGINE (issuing the \"pre\" commands beforehand and the \"post\" commands afterwards) and set it as the default for everything except RAND and then return a boolean success or failure.

int generic_load_engine_fn(const char *engine_id,\n                           const char **pre_cmds, int pre_num,\n                           const char **post_cmds, int post_num)\n{\n    ENGINE *e = ENGINE_by_id(engine_id);\n    if (!e) return 0;\n    while (pre_num--) {\n        if (!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {\n            fprintf(stderr, \"Failed command (%s - %s:%s)\\n\", engine_id,\n                    pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : \"(NULL)\");\n            ENGINE_free(e);\n            return 0;\n        }\n        pre_cmds += 2;\n    }\n    if (!ENGINE_init(e)) {\n        fprintf(stderr, \"Failed initialisation\\n\");\n        ENGINE_free(e);\n        return 0;\n    }\n    /*\n     * ENGINE_init() returned a functional reference, so free the structural\n     * reference from ENGINE_by_id().\n     */\n    ENGINE_free(e);\n    while (post_num--) {\n        if (!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {\n            fprintf(stderr, \"Failed command (%s - %s:%s)\\n\", engine_id,\n                    post_cmds[0], post_cmds[1] ? post_cmds[1] : \"(NULL)\");\n            ENGINE_finish(e);\n            return 0;\n        }\n        post_cmds += 2;\n    }\n    ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);\n    /* Success */\n    return 1;\n}\n

Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can relax the semantics of the function - if set nonzero it will only return failure if the ENGINE supported the given command name but failed while executing it, if the ENGINE doesn't support the command name it will simply return success without doing anything. In this case we assume the user is only supplying commands specific to the given ENGINE so we set this to FALSE.

Discovering supported control commands

It is possible to discover at run-time the names, numerical-ids, descriptions and input parameters of the control commands supported by an ENGINE using a structural reference. Note that some control commands are defined by OpenSSL itself and it will intercept and handle these control commands on behalf of the ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command. <openssl/engine.h> defines an index, ENGINE_CMD_BASE, that all control commands implemented by ENGINEs should be numbered from. Any command value lower than this symbol is considered a \"generic\" command is handled directly by the OpenSSL core routines.

It is using these \"core\" control commands that one can discover the control commands implemented by a given ENGINE, specifically the commands:

ENGINE_HAS_CTRL_FUNCTION\nENGINE_CTRL_GET_FIRST_CMD_TYPE\nENGINE_CTRL_GET_NEXT_CMD_TYPE\nENGINE_CTRL_GET_CMD_FROM_NAME\nENGINE_CTRL_GET_NAME_LEN_FROM_CMD\nENGINE_CTRL_GET_NAME_FROM_CMD\nENGINE_CTRL_GET_DESC_LEN_FROM_CMD\nENGINE_CTRL_GET_DESC_FROM_CMD\nENGINE_CTRL_GET_CMD_FLAGS\n

Whilst these commands are automatically processed by the OpenSSL framework code, they use various properties exposed by each ENGINE to process these queries. An ENGINE has 3 properties it exposes that can affect how this behaves; it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in the ENGINE's flags, and it can expose an array of control command descriptions. If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will simply pass all these \"core\" control commands directly to the ENGINE's ctrl() handler (and thus, it must have supplied one), so it is up to the ENGINE to reply to these \"discovery\" commands itself. If that flag is not set, then the OpenSSL framework code will work with the following rules:

if no ctrl() handler supplied;\n    ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),\n    all other commands fail.\nif a ctrl() handler was supplied but no array of control commands;\n    ENGINE_HAS_CTRL_FUNCTION returns TRUE,\n    all other commands fail.\nif a ctrl() handler and array of control commands was supplied;\n    ENGINE_HAS_CTRL_FUNCTION returns TRUE,\n    all other commands proceed processing ...\n

If the ENGINE's array of control commands is empty then all other commands will fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the identifier of a command supported by the ENGINE and returns the next command identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string name for a command and returns the corresponding identifier or fails if no such command name exists, and the remaining commands take a command identifier and return properties of the corresponding commands. All except ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, or populate a supplied character buffer with a copy of the command name or description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following possible values:

ENGINE_CMD_FLAG_NUMERIC\nENGINE_CMD_FLAG_STRING\nENGINE_CMD_FLAG_NO_INPUT\nENGINE_CMD_FLAG_INTERNAL\n

If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely informational to the caller - this flag will prevent the command being usable for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). \"INTERNAL\" commands are not intended to be exposed to text-based configuration by applications, administrations, users, etc. These can support arbitrary operations via ENGINE_ctrl(), including passing to and/or from the control commands data of any arbitrary type. These commands are supported in the discovery mechanisms simply to allow applications to determine if an ENGINE supports certain specific commands it might want to use (e.g. application \"foo\" might query various ENGINEs to see if they implement \"FOO_GET_VENDOR_LOGO_GIF\" - and ENGINE could therefore decide whether or not to support this \"foo\"-specific extension).

"},{"location":"man3/ENGINE_add/#environment","title":"ENVIRONMENT","text":""},{"location":"man3/ENGINE_add/#return-values","title":"RETURN VALUES","text":"

ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next() and ENGINE_get_prev() return a valid ENGINE structure or NULL if an error occurred.

ENGINE_add() and ENGINE_remove() return 1 on success or 0 on error.

ENGINE_by_id() returns a valid ENGINE structure or NULL if an error occurred.

ENGINE_init() and ENGINE_finish() return 1 on success or 0 on error.

All ENGINE_get_default_TYPE() functions, ENGINE_get_cipher_engine() and ENGINE_get_digest_engine() return a valid ENGINE structure on success or NULL if an error occurred.

All ENGINE_set_default_TYPE() functions return 1 on success or 0 on error.

ENGINE_set_default() returns 1 on success or 0 on error.

ENGINE_get_table_flags() returns an unsigned integer value representing the global table flags which are used to control the registration behaviour of ENGINE implementations.

All ENGINE_register_TYPE() functions return 1 on success or 0 on error.

ENGINE_register_complete() and ENGINE_register_all_complete() always return 1.

ENGINE_ctrl() returns a positive value on success or others on error.

ENGINE_cmd_is_executable() returns 1 if cmd is executable or 0 otherwise.

ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() return 1 on success or 0 on error.

ENGINE_new() returns a valid ENGINE structure on success or NULL if an error occurred.

ENGINE_free() always returns 1.

ENGINE_up_ref() returns 1 on success or 0 on error.

ENGINE_set_id() and ENGINE_set_name() return 1 on success or 0 on error.

All other ENGINE_set_* functions return 1 on success or 0 on error.

ENGINE_get_id() and ENGINE_get_name() return a string representing the identifier and the name of the ENGINE e respectively.

ENGINE_get_RSA(), ENGINE_get_DSA(), ENGINE_get_DH() and ENGINE_get_RAND() return corresponding method structures for each algorithms.

ENGINE_get_destroy_function(), ENGINE_get_init_function(), ENGINE_get_finish_function(), ENGINE_get_ctrl_function(), ENGINE_get_load_privkey_function(), ENGINE_get_load_pubkey_function(), ENGINE_get_ciphers() and ENGINE_get_digests() return corresponding function pointers of the callbacks.

ENGINE_get_cipher() returns a valid EVP_CIPHER structure on success or NULL if an error occurred.

ENGINE_get_digest() returns a valid EVP_MD structure on success or NULL if an error occurred.

ENGINE_get_flags() returns an integer representing the ENGINE flags which are used to control various behaviours of an ENGINE.

ENGINE_get_cmd_defns() returns an ENGINE_CMD_DEFN structure or NULL if it's not set.

ENGINE_load_private_key() and ENGINE_load_public_key() return a valid EVP_PKEY structure on success or NULL if an error occurred.

"},{"location":"man3/ENGINE_add/#see-also","title":"SEE ALSO","text":"

OPENSSL_init_crypto(3), RSA_new_method(3), DSA_new(3), DH_new(3), RAND_bytes(3), config(5)

"},{"location":"man3/ENGINE_add/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

ENGINE_cleanup() was deprecated in OpenSSL 1.1.0 by the automatic cleanup done by OPENSSL_cleanup() and should not be used.

"},{"location":"man3/ENGINE_add/#copyright","title":"COPYRIGHT","text":"

Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_GET_LIB/","title":"ERR_GET_LIB","text":""},{"location":"man3/ERR_GET_LIB/#name","title":"NAME","text":"

ERR_GET_LIB, ERR_GET_REASON, ERR_FATAL_ERROR - get information from error codes

"},{"location":"man3/ERR_GET_LIB/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nint ERR_GET_LIB(unsigned long e);\n\nint ERR_GET_REASON(unsigned long e);\n\nint ERR_FATAL_ERROR(unsigned long e);\n
"},{"location":"man3/ERR_GET_LIB/#description","title":"DESCRIPTION","text":"

The error code returned by ERR_get_error() consists of a library number and reason code. ERR_GET_LIB() and ERR_GET_REASON() can be used to extract these.

ERR_FATAL_ERROR() indicates whether a given error code is a fatal error.

The library number describes where the error occurred, the reason code is the information about what went wrong.

Each sub-library of OpenSSL has a unique library number; the reason code is unique within each sub-library. Note that different libraries may use the same value to signal different reasons.

ERR_R_... reason codes such as ERR_R_MALLOC_FAILURE are globally unique. However, when checking for sub-library specific reason codes, be sure to also compare the library number.

ERR_GET_LIB(), ERR_GET_REASON(), and ERR_FATAL_ERROR() are macros.

"},{"location":"man3/ERR_GET_LIB/#return-values","title":"RETURN VALUES","text":"

The library number, reason code, and whether the error is fatal, respectively. Starting with OpenSSL 3.0.0, the function code is always set to zero.

"},{"location":"man3/ERR_GET_LIB/#notes","title":"NOTES","text":"

Applications should not make control flow decisions based on specific error codes. Error codes are subject to change at any time (even in patch releases of OpenSSL). A particular error code can only be considered meaningful for control flow decisions if it is explicitly documented as such. New failure codes may still appear at any time.

"},{"location":"man3/ERR_GET_LIB/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ERR_GET_LIB/#history","title":"HISTORY","text":"

ERR_GET_LIB() and ERR_GET_REASON() are available in all versions of OpenSSL.

ERR_GET_FUNC() was removed in OpenSSL 3.0.

"},{"location":"man3/ERR_GET_LIB/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_clear_error/","title":"ERR_clear_error","text":""},{"location":"man3/ERR_clear_error/#name","title":"NAME","text":"

ERR_clear_error - clear the error queue

"},{"location":"man3/ERR_clear_error/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_clear_error(void);\n
"},{"location":"man3/ERR_clear_error/#description","title":"DESCRIPTION","text":"

ERR_clear_error() empties the current thread's error queue.

"},{"location":"man3/ERR_clear_error/#return-values","title":"RETURN VALUES","text":"

ERR_clear_error() has no return value.

"},{"location":"man3/ERR_clear_error/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3)

"},{"location":"man3/ERR_clear_error/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_error_string/","title":"ERR_error_string","text":""},{"location":"man3/ERR_error_string/#name","title":"NAME","text":"

ERR_error_string, ERR_error_string_n, ERR_lib_error_string, ERR_func_error_string, ERR_reason_error_string - obtain human-readable error message

"},{"location":"man3/ERR_error_string/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nchar *ERR_error_string(unsigned long e, char *buf);\nvoid ERR_error_string_n(unsigned long e, char *buf, size_t len);\n\nconst char *ERR_lib_error_string(unsigned long e);\nconst char *ERR_reason_error_string(unsigned long e);\n

Deprecated in OpenSSL 3.0:

const char *ERR_func_error_string(unsigned long e);\n
"},{"location":"man3/ERR_error_string/#description","title":"DESCRIPTION","text":"

ERR_error_string() generates a human-readable string representing the error code e, and places it at buf. buf must be at least 256 bytes long. If buf is NULL, the error string is placed in a static buffer. Note that this function is not thread-safe and does no checks on the size of the buffer; use ERR_error_string_n() instead.

ERR_error_string_n() is a variant of ERR_error_string() that writes at most len characters (including the terminating 0) and truncates the string if necessary. For ERR_error_string_n(), buf may not be NULL.

The string will have the following format:

error:[error code]:[library name]::[reason string]\n

error code is an 8 digit hexadecimal number, library name and reason string are ASCII text.

ERR_lib_error_string() and ERR_reason_error_string() return the library name and reason string respectively.

If there is no text string registered for the given error code, the error string will contain the numeric code.

ERR_print_errors(3) can be used to print all error codes currently in the queue.

"},{"location":"man3/ERR_error_string/#return-values","title":"RETURN VALUES","text":"

ERR_error_string() returns a pointer to a static buffer containing the string if buf == NULL, buf otherwise.

ERR_lib_error_string() and ERR_reason_error_string() return the strings, and NULL if none is registered for the error code.

ERR_func_error_string() returns NULL.

"},{"location":"man3/ERR_error_string/#see-also","title":"SEE ALSO","text":"

ERR_get_error(3), ERR_print_errors(3)

"},{"location":"man3/ERR_error_string/#history","title":"HISTORY","text":"

ERR_func_error_string() became deprecated in OpenSSL 3.0.

"},{"location":"man3/ERR_error_string/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_get_error/","title":"ERR_get_error","text":""},{"location":"man3/ERR_get_error/#name","title":"NAME","text":"

ERR_get_error, ERR_peek_error, ERR_peek_last_error, ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, ERR_peek_error_func, ERR_peek_last_error_func, ERR_peek_error_data, ERR_peek_last_error_data, ERR_get_error_all, ERR_peek_error_all, ERR_peek_last_error_all, ERR_get_error_line_data, ERR_peek_error_line_data, ERR_peek_last_error_line_data - obtain error code and data

"},{"location":"man3/ERR_get_error/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nunsigned long ERR_get_error(void);\nunsigned long ERR_peek_error(void);\nunsigned long ERR_peek_last_error(void);\n\nunsigned long ERR_peek_error_line(const char **file, int *line);\nunsigned long ERR_peek_last_error_line(const char **file, int *line);\n\nunsigned long ERR_peek_error_func(const char **func);\nunsigned long ERR_peek_last_error_func(const char **func);\n\nunsigned long ERR_peek_error_data(const char **data, int *flags);\nunsigned long ERR_peek_last_error_data(const char **data, int *flags);\n\nunsigned long ERR_get_error_all(const char **file, int *line,\n                                const char **func,\n                                const char **data, int *flags);\nunsigned long ERR_peek_error_all(const char **file, int *line,\n                                 const char **func,\n                                 const char **data, int *flags);\nunsigned long ERR_peek_last_error_all(const char **file, int *line,\n                                      const char *func,\n                                      const char **data, int *flags);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

unsigned long ERR_get_error_line(const char **file, int *line);\nunsigned long ERR_get_error_line_data(const char **file, int *line,\n                                      const char **data, int *flags);\nunsigned long ERR_peek_error_line_data(const char **file, int *line,\n                                       const char **data, int *flags);\nunsigned long ERR_peek_last_error_line_data(const char **file, int *line,\n                                            const char **data, int *flags);\n
"},{"location":"man3/ERR_get_error/#description","title":"DESCRIPTION","text":"

ERR_get_error() returns the earliest error code from the thread's error queue and removes the entry. This function can be called repeatedly until there are no more error codes to return.

ERR_peek_error() returns the earliest error code from the thread's error queue without modifying it.

ERR_peek_last_error() returns the latest error code from the thread's error queue without modifying it.

See ERR_GET_LIB(3) for obtaining further specific information such as the reason of the error, and ERR_error_string(3) for human-readable error messages.

ERR_get_error_all() is the same as ERR_get_error(), but on success it additionally stores the filename, line number and function where the error occurred in *file, *line and *func, and also extra text and flags in *data, *flags. If any of those parameters are NULL, it will not be changed. An unset filename is indicated as \"\", i.e. an empty string. An unset line number is indicated as 0. An unset function name is indicated as \"\", i.e. an empty string.

A pointer returned this way by these functions and the ones below is valid until the respective entry is overwritten in the error queue.

ERR_peek_error_line() and ERR_peek_last_error_line() are the same as ERR_peek_error() and ERR_peek_last_error(), but on success they additionally store the filename and line number where the error occurred in *file and *line, as far as they are not NULL. An unset filename is indicated as \"\", i.e., an empty string. An unset line number is indicated as 0.

ERR_peek_error_func() and ERR_peek_last_error_func() are the same as ERR_peek_error() and ERR_peek_last_error(), but on success they additionally store the name of the function where the error occurred in *func, unless it is NULL. An unset function name is indicated as \"\".

ERR_peek_error_data() and ERR_peek_last_error_data() are the same as ERR_peek_error() and ERR_peek_last_error(), but on success they additionally store additional data and flags associated with the error code in *data and *flags, as far as they are not NULL. Unset data is indicated as \"\". In this case the value given for the flag is irrelevant (and equals 0). *data contains a string if *flags&ERR_TXT_STRING is true.

ERR_peek_error_all() and ERR_peek_last_error_all() are combinations of all of the above.

ERR_get_error_line(), ERR_get_error_line_data(), ERR_peek_error_line_data() and ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(), ERR_peek_error_all() and ERR_peek_last_error_all(), and may give confusing results. They should no longer be used and are therefore deprecated.

An application MUST NOT free the *data pointer (or any other pointers returned by these functions) with OPENSSL_free() as freeing is handled automatically by the error library.

"},{"location":"man3/ERR_get_error/#return-values","title":"RETURN VALUES","text":"

The error code, or 0 if there is no error in the queue.

"},{"location":"man3/ERR_get_error/#see-also","title":"SEE ALSO","text":"

ERR_error_string(3), ERR_GET_LIB(3)

"},{"location":"man3/ERR_get_error/#history","title":"HISTORY","text":"

ERR_peek_error_func(), ERR_peek_last_error_func(), ERR_peek_error_data(), ERR_peek_last_error_data(), ERR_peek_error_all() and ERR_peek_last_error_all() were added in OpenSSL 3.0.

ERR_get_error_line(), ERR_get_error_line_data(), ERR_peek_error_line_data() and ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0.

"},{"location":"man3/ERR_get_error/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_load_crypto_strings/","title":"ERR_load_crypto_strings","text":""},{"location":"man3/ERR_load_crypto_strings/#name","title":"NAME","text":"

ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - load and free error strings

"},{"location":"man3/ERR_load_crypto_strings/#synopsis","title":"SYNOPSIS","text":"

The following functions have been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

#include <openssl/err.h>\n\nvoid ERR_load_crypto_strings(void);\nvoid ERR_free_strings(void);\n\n#include <openssl/ssl.h>\n\nvoid SSL_load_error_strings(void);\n
"},{"location":"man3/ERR_load_crypto_strings/#description","title":"DESCRIPTION","text":"

ERR_load_crypto_strings() registers the error strings for all libcrypto functions. SSL_load_error_strings() does the same, but also registers the libssl error strings.

In versions prior to OpenSSL 1.1.0, ERR_free_strings() releases any resources created by the above functions.

"},{"location":"man3/ERR_load_crypto_strings/#return-values","title":"RETURN VALUES","text":"

ERR_load_crypto_strings(), SSL_load_error_strings() and ERR_free_strings() return no values.

"},{"location":"man3/ERR_load_crypto_strings/#see-also","title":"SEE ALSO","text":"

ERR_error_string(3)

"},{"location":"man3/ERR_load_crypto_strings/#history","title":"HISTORY","text":"

The ERR_load_crypto_strings(), SSL_load_error_strings(), and ERR_free_strings() functions were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto() and OPENSSL_init_ssl() and should not be used.

"},{"location":"man3/ERR_load_crypto_strings/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_load_strings/","title":"ERR_load_strings","text":""},{"location":"man3/ERR_load_strings/#name","title":"NAME","text":"

ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load arbitrary error strings

"},{"location":"man3/ERR_load_strings/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nint ERR_load_strings(int lib, ERR_STRING_DATA *str);\n\nint ERR_get_next_error_library(void);\n\nunsigned long ERR_PACK(int lib, int func, int reason);\n
"},{"location":"man3/ERR_load_strings/#description","title":"DESCRIPTION","text":"

ERR_load_strings() registers error strings for library number lib.

str is an array of error string data:

typedef struct ERR_string_data_st\n{\n    unsigned long error;\n    char *string;\n} ERR_STRING_DATA;\n

The error code is generated from the library number and a function and reason code: error = ERR_PACK(lib, func, reason). ERR_PACK() is a macro.

The last entry in the array is {0,0}.

ERR_get_next_error_library() can be used to assign library numbers to user libraries at run time.

"},{"location":"man3/ERR_load_strings/#return-values","title":"RETURN VALUES","text":"

ERR_load_strings() returns 1 for success and 0 for failure. ERR_PACK() returns the error code. ERR_get_next_error_library() returns zero on failure, otherwise a new library number.

"},{"location":"man3/ERR_load_strings/#see-also","title":"SEE ALSO","text":"

ERR_load_strings(3)

"},{"location":"man3/ERR_load_strings/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_new/","title":"ERR_new","text":""},{"location":"man3/ERR_new/#name","title":"NAME","text":"

ERR_new, ERR_set_debug, ERR_set_error, ERR_vset_error - Error recording building blocks

"},{"location":"man3/ERR_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_new(void);\nvoid ERR_set_debug(const char *file, int line, const char *func);\nvoid ERR_set_error(int lib, int reason, const char *fmt, ...);\nvoid ERR_vset_error(int lib, int reason, const char *fmt, va_list args);\n
"},{"location":"man3/ERR_new/#description","title":"DESCRIPTION","text":"

The functions described here are generally not used directly, but rather through macros such as ERR_raise(3). They can still be useful for anyone that wants to make their own macros.

ERR_new() allocates a new slot in the thread's error queue.

ERR_set_debug() sets the debug information related to the current error in the thread's error queue. The values that can be given are the filename file, line in the file line and the name of the function func where the error occurred. The names must be constant, this function will only save away the pointers, not copy the strings.

ERR_set_error() sets the error information, which are the library number lib and the reason code reason, and additional data as a format string fmt and an arbitrary number of arguments. The additional data is processed with BIO_snprintf(3) to form the additional data string, which is allocated and store in the error record.

ERR_vset_error() works like ERR_set_error(), but takes a va_list argument instead of a variable number of arguments.

"},{"location":"man3/ERR_new/#return-values","title":"RETURN VALUES","text":"

ERR_new, ERR_set_debug, ERR_set_error and ERR_vset_error do not return any values.

"},{"location":"man3/ERR_new/#notes","title":"NOTES","text":"

The library number is unique to each unit that records errors. OpenSSL has a number of preallocated ones for its own uses, but others may allocate their own library number dynamically with ERR_get_next_error_library(3).

Reason codes are unique within each library, and may have an associated set of strings as a short description of the reason. For dynamically allocated library numbers, reason strings are recorded with ERR_load_strings(3).

Provider authors are supplied with core versions of these functions, see provider-base(7).

"},{"location":"man3/ERR_new/#see-also","title":"SEE ALSO","text":"

ERR_raise(3), ERR_get_next_error_library(3), ERR_load_strings(3), BIO_snprintf(3), provider-base(7)

"},{"location":"man3/ERR_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_print_errors/","title":"ERR_print_errors","text":""},{"location":"man3/ERR_print_errors/#name","title":"NAME","text":"

ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb - print error messages

"},{"location":"man3/ERR_print_errors/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_print_errors(BIO *bp);\nvoid ERR_print_errors_fp(FILE *fp);\nvoid ERR_print_errors_cb(int (*cb)(const char *str, size_t len, void *u),\n                         void *u);\n
"},{"location":"man3/ERR_print_errors/#description","title":"DESCRIPTION","text":"

ERR_print_errors() is a convenience function that prints the error strings for all errors that OpenSSL has recorded to bp, thus emptying the error queue.

ERR_print_errors_fp() is the same, except that the output goes to a FILE.

ERR_print_errors_cb() is the same, except that the callback function, cb, is called for each error line with the string, length, and userdata u as the callback parameters.

The error strings will have the following format:

[pid]:error:[error code]:[library name]:[function name]:[reason string]:[filename]:[line]:[optional text message]\n

error code is an 8 digit hexadecimal number. library name, function name and reason string are ASCII text, as is optional text message if one was set for the respective error code.

If there is no text string registered for the given error code, the error string will contain the numeric code.

"},{"location":"man3/ERR_print_errors/#return-values","title":"RETURN VALUES","text":"

ERR_print_errors() and ERR_print_errors_fp() return no values.

"},{"location":"man3/ERR_print_errors/#see-also","title":"SEE ALSO","text":"

ERR_error_string(3), ERR_get_error(3)

"},{"location":"man3/ERR_print_errors/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_put_error/","title":"ERR_put_error","text":""},{"location":"man3/ERR_put_error/#name","title":"NAME","text":"

ERR_raise, ERR_raise_data, ERR_put_error, ERR_add_error_data, ERR_add_error_vdata, ERR_add_error_txt, ERR_add_error_mem_bio - record an error

"},{"location":"man3/ERR_put_error/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nvoid ERR_raise(int lib, int reason);\nvoid ERR_raise_data(int lib, int reason, const char *fmt, ...);\n\nvoid ERR_add_error_data(int num, ...);\nvoid ERR_add_error_vdata(int num, va_list arg);\nvoid ERR_add_error_txt(const char *sep, const char *txt);\nvoid ERR_add_error_mem_bio(const char *sep, BIO *bio);\n

The following function has been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ERR_put_error(int lib, int func, int reason, const char *file, int line);\n
"},{"location":"man3/ERR_put_error/#description","title":"DESCRIPTION","text":"

ERR_raise() adds a new error to the thread's error queue. The error occurred in the library lib for the reason given by the reason code. Furthermore, the name of the file, the line, and name of the function where the error occurred is saved with the error record.

ERR_raise_data() does the same thing as ERR_raise(), but also lets the caller specify additional information as a format string fmt and an arbitrary number of values, which are processed with BIO_snprintf(3).

ERR_put_error() adds an error code to the thread's error queue. It signals that the error of reason code reason occurred in function func of library lib, in line number line of file. This function is usually called by a macro.

ERR_add_error_data() associates the concatenation of its num string arguments as additional data with the error code added last. ERR_add_error_vdata() is similar except the argument is a va_list. Multiple calls to these functions append to the current top of the error queue. The total length of the string data per error is limited to 4096 characters.

ERR_add_error_txt() appends the given text string as additional data to the last error queue entry, after inserting the optional separator string if it is not NULL and the top error entry does not yet have additional data. In case the separator is at the end of the text it is not appended to the data. The sep argument may be for instance \"\\n\" to insert a line break when needed. If the associated data would become more than 4096 characters long (which is the limit given above) it is split over sufficiently many new copies of the last error queue entry.

ERR_add_error_mem_bio() is the same as ERR_add_error_txt() except that the text string is taken from the given memory BIO. It appends '\\0' to the BIO contents if not already NUL-terminated.

ERR_load_strings(3) can be used to register error strings so that the application can a generate human-readable error messages for the error code.

"},{"location":"man3/ERR_put_error/#reporting-errors","title":"Reporting errors","text":""},{"location":"man3/ERR_put_error/#openssl-library-reports","title":"OpenSSL library reports","text":"

Each OpenSSL sub-library has library code ERR_LIB_XXX and has its own set of reason codes XXX_R_.... These are both passed in combination to ERR_raise() and ERR_raise_data(), and the combination ultimately produces the correct error text for the reported error.

All these macros and the numbers they have as values are specific to OpenSSL's libraries. OpenSSL reason codes normally consist of textual error descriptions. For example, the function ssl3_read_bytes() reports a \"handshake failure\" as follows:

ERR_raise(ERR_LIB_SSL, SSL_R_SSL_HANDSHAKE_FAILURE);\n

There are two exceptions:

"},{"location":"man3/ERR_put_error/#other-pieces-of-software","title":"Other pieces of software","text":"

Other pieces of software that may want to use OpenSSL's error reporting system, such as engines or applications, must normally get their own numbers.

The exceptions mentioned in \"OpenSSL library reports\" above are valid for other pieces of software, i.e. they may use ERR_LIB_SYS to report system errors:

ERR_raise(ERR_LIB_SYS, errno);\n

... and they may use ERR_R_XXX macros together with their own \"library\" code.

int app_lib_code = ERR_get_next_error_library();\n\n/* ... */\n\nERR_raise(app_lib_code, ERR_R_PASSED_INVALID_ARGUMENT);\n
"},{"location":"man3/ERR_put_error/#return-values","title":"RETURN VALUES","text":"

ERR_raise(), ERR_raise_data(), ERR_put_error(), ERR_add_error_data(), ERR_add_error_vdata() ERR_add_error_txt(), and ERR_add_error_mem_bio() return no values.

"},{"location":"man3/ERR_put_error/#notes","title":"NOTES","text":"

ERR_raise(), ERR_raise() and ERR_put_error() are implemented as macros.

"},{"location":"man3/ERR_put_error/#see-also","title":"SEE ALSO","text":"

ERR_load_strings(3), ERR_get_next_error_library(3)

"},{"location":"man3/ERR_put_error/#history","title":"HISTORY","text":"

ERR_raise, ERR_raise_data, ERR_add_error_txt() and ERR_add_error_mem_bio() were added in OpenSSL 3.0.

"},{"location":"man3/ERR_put_error/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_remove_state/","title":"ERR_remove_state","text":""},{"location":"man3/ERR_remove_state/#name","title":"NAME","text":"

ERR_remove_thread_state, ERR_remove_state - DEPRECATED

"},{"location":"man3/ERR_remove_state/#synopsis","title":"SYNOPSIS","text":"

The following function has been deprecated since OpenSSL 1.0.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ERR_remove_state(unsigned long tid);\n

The following function has been deprecated since OpenSSL 1.1.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

void ERR_remove_thread_state(void *tid);\n
"},{"location":"man3/ERR_remove_state/#description","title":"DESCRIPTION","text":"

ERR_remove_state() frees the error queue associated with the specified thread, identified by tid. ERR_remove_thread_state() does the same thing, except the identifier is an opaque pointer.

"},{"location":"man3/ERR_remove_state/#return-values","title":"RETURN VALUES","text":"

ERR_remove_state() and ERR_remove_thread_state() return no value.

"},{"location":"man3/ERR_remove_state/#see-also","title":"SEE ALSO","text":"

LOPENSSL_init_crypto(3)

"},{"location":"man3/ERR_remove_state/#history","title":"HISTORY","text":"

ERR_remove_state() was deprecated in OpenSSL 1.0.0 and ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0; these functions and should not be used.

"},{"location":"man3/ERR_remove_state/#copyright","title":"COPYRIGHT","text":"

Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/ERR_set_mark/","title":"ERR_set_mark","text":""},{"location":"man3/ERR_set_mark/#name","title":"NAME","text":"

ERR_set_mark, ERR_clear_last_mark, ERR_pop_to_mark, ERR_count_to_mark, ERR_pop - set mark, clear mark, pop errors until mark and pop last error

"},{"location":"man3/ERR_set_mark/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/err.h>\n\nint ERR_set_mark(void);\nint ERR_pop_to_mark(void);\nint ERR_clear_last_mark(void);\nint ERR_count_to_mark(void);\nint ERR_pop(void);\n
"},{"location":"man3/ERR_set_mark/#description","title":"DESCRIPTION","text":"

ERR_set_mark() sets a mark on the current topmost error record if there is one.

ERR_pop_to_mark() will pop the top of the error stack until a mark is found. The mark is then removed. If there is no mark, the whole stack is removed.

ERR_clear_last_mark() removes the last mark added if there is one.

ERR_count_to_mark() returns the number of entries on the error stack above the most recently marked entry, not including that entry. If there is no mark in the error stack, the number of entries in the error stack is returned.

ERR_pop() unconditionally pops a single error entry from the top of the error stack (which is the entry obtainable via ERR_peek_last_error(3)).

"},{"location":"man3/ERR_set_mark/#return-values","title":"RETURN VALUES","text":"

ERR_set_mark() returns 0 if the error stack is empty, otherwise 1.

ERR_clear_last_mark() and ERR_pop_to_mark() return 0 if there was no mark in the error stack, which implies that the stack became empty, otherwise 1.

ERR_count_to_mark() returns the number of error stack entries found above the most recent mark, if any, or the total number of error stack entries.

ERR_pop() returns 1 if an error was popped or 0 if the error stack was empty.

"},{"location":"man3/ERR_set_mark/#history","title":"HISTORY","text":"

ERR_pop() was added in OpenSSL 3.3.

"},{"location":"man3/ERR_set_mark/#copyright","title":"COPYRIGHT","text":"

Copyright 2003-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EVP_ASYM_CIPHER_free/","title":"EVP_ASYM_CIPHER_free","text":""},{"location":"man3/EVP_ASYM_CIPHER_free/#name","title":"NAME","text":"

EVP_ASYM_CIPHER_fetch, EVP_ASYM_CIPHER_free, EVP_ASYM_CIPHER_up_ref, EVP_ASYM_CIPHER_is_a, EVP_ASYM_CIPHER_get0_provider, EVP_ASYM_CIPHER_do_all_provided, EVP_ASYM_CIPHER_names_do_all, EVP_ASYM_CIPHER_get0_name, EVP_ASYM_CIPHER_get0_description, EVP_ASYM_CIPHER_gettable_ctx_params, EVP_ASYM_CIPHER_settable_ctx_params - Functions to manage EVP_ASYM_CIPHER algorithm objects

"},{"location":"man3/EVP_ASYM_CIPHER_free/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_ASYM_CIPHER *EVP_ASYM_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                                       const char *properties);\nvoid EVP_ASYM_CIPHER_free(EVP_ASYM_CIPHER *cipher);\nint EVP_ASYM_CIPHER_up_ref(EVP_ASYM_CIPHER *cipher);\nconst char *EVP_ASYM_CIPHER_get0_name(const EVP_ASYM_CIPHER *cipher);\nint EVP_ASYM_CIPHER_is_a(const EVP_ASYM_CIPHER *cipher, const char *name);\nOSSL_PROVIDER *EVP_ASYM_CIPHER_get0_provider(const EVP_ASYM_CIPHER *cipher);\nvoid EVP_ASYM_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,\n                                     void (*fn)(EVP_ASYM_CIPHER *cipher,\n                                                void *arg),\n                                     void *arg);\nint EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher,\n                                 void (*fn)(const char *name, void *data),\n                                 void *data);\nconst char *EVP_ASYM_CIPHER_get0_description(const EVP_ASYM_CIPHER *cipher);\nconst OSSL_PARAM *EVP_ASYM_CIPHER_gettable_ctx_params(const EVP_ASYM_CIPHER *cip);\nconst OSSL_PARAM *EVP_ASYM_CIPHER_settable_ctx_params(const EVP_ASYM_CIPHER *cip);\n
"},{"location":"man3/EVP_ASYM_CIPHER_free/#description","title":"DESCRIPTION","text":"

EVP_ASYM_CIPHER_fetch() fetches the implementation for the given algorithm from any provider offering it, within the criteria given by the properties and in the scope of the given library context ctx (see OSSL_LIB_CTX(3)). The algorithm will be one offering functions for performing asymmetric cipher related tasks such as asymmetric encryption and decryption. See \"ALGORITHM FETCHING\" in crypto(7) for further information.

The returned value must eventually be freed with EVP_ASYM_CIPHER_free().

EVP_ASYM_CIPHER_free() decrements the reference count for the EVP_ASYM_CIPHER structure. Typically this structure will have been obtained from an earlier call to EVP_ASYM_CIPHER_fetch(). If the reference count drops to 0 then the structure is freed. If the argument is NULL, nothing is done.

EVP_ASYM_CIPHER_up_ref() increments the reference count for an EVP_ASYM_CIPHER structure.

EVP_ASYM_CIPHER_is_a() returns 1 if cipher is an implementation of an algorithm that's identifiable with name, otherwise 0.

EVP_ASYM_CIPHER_get0_provider() returns the provider that cipher was fetched from.

EVP_ASYM_CIPHER_do_all_provided() traverses all EVP_ASYM_CIPHERs implemented by all activated providers in the given library context libctx, and for each of the implementations, calls the given function fn with the implementation method and the given arg as argument.

EVP_ASYM_CIPHER_get0_name() returns the algorithm name from the provided implementation for the given cipher. Note that the cipher may have multiple synonyms associated with it. In this case the first name from the algorithm definition is returned. Ownership of the returned string is retained by the cipher object and should not be freed by the caller.

EVP_ASYM_CIPHER_names_do_all() traverses all names for cipher, and calls fn with each name and data.

EVP_ASYM_CIPHER_get0_description() returns a description of the cipher, meant for display and human consumption. The description is at the discretion of the cipher implementation.

EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() return a constant OSSL_PARAM(3) array that describes the names and types of key parameters that can be retrieved or set by a key encryption algorithm using EVP_PKEY_CTX_get_params(3) and EVP_PKEY_CTX_set_params(3).

"},{"location":"man3/EVP_ASYM_CIPHER_free/#return-values","title":"RETURN VALUES","text":"

EVP_ASYM_CIPHER_fetch() returns a pointer to an EVP_ASYM_CIPHER for success or NULL for failure.

EVP_ASYM_CIPHER_up_ref() returns 1 for success or 0 otherwise.

EVP_ASYM_CIPHER_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names.

EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() return a constant OSSL_PARAM(3) array or NULL on error.

"},{"location":"man3/EVP_ASYM_CIPHER_free/#see-also","title":"SEE ALSO","text":"

\"ALGORITHM FETCHING\" in crypto(7), OSSL_PROVIDER(3)

"},{"location":"man3/EVP_ASYM_CIPHER_free/#history","title":"HISTORY","text":"

The functions described here were added in OpenSSL 3.0.

"},{"location":"man3/EVP_ASYM_CIPHER_free/#copyright","title":"COPYRIGHT","text":"

Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EVP_BytesToKey/","title":"EVP_BytesToKey","text":""},{"location":"man3/EVP_BytesToKey/#name","title":"NAME","text":"

EVP_BytesToKey - password based encryption routine

"},{"location":"man3/EVP_BytesToKey/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,\n                   const unsigned char *salt,\n                   const unsigned char *data, int datal, int count,\n                   unsigned char *key, unsigned char *iv);\n
"},{"location":"man3/EVP_BytesToKey/#description","title":"DESCRIPTION","text":"

EVP_BytesToKey() derives a key and IV from various parameters. type is the cipher to derive the key and IV for. md is the message digest to use. The salt parameter is used as a salt in the derivation: it should point to an 8 byte buffer or NULL if no salt is used. data is a buffer containing datal bytes which is used to derive the keying data. count is the iteration count to use. The derived key and IV will be written to key and iv respectively.

"},{"location":"man3/EVP_BytesToKey/#notes","title":"NOTES","text":"

A typical application of this function is to derive keying material for an encryption algorithm from a password in the data parameter.

Increasing the count parameter slows down the algorithm which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords.

If the total key and IV length is less than the digest length and MD5 is used then the derivation algorithm is compatible with PKCS#5 v1.5 otherwise a non standard extension is used to derive the extra data.

Newer applications should use a more modern algorithm such as PBKDF2 as defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC.

"},{"location":"man3/EVP_BytesToKey/#key-derivation-algorithm","title":"KEY DERIVATION ALGORITHM","text":"

The key and IV is derived by concatenating D_1, D_2, etc until enough data is available for the key and IV. D_i is defined as:

    D_i = HASH^count(D_(i-1) || data || salt)\n

where || denotes concatenation, D_0 is empty, HASH is the digest algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) is HASH(HASH(data)) and so on.

The initial bytes are used for the key and the subsequent bytes for the IV.

"},{"location":"man3/EVP_BytesToKey/#return-values","title":"RETURN VALUES","text":"

If data is NULL, then EVP_BytesToKey() returns the number of bytes needed to store the derived key. Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes, or 0 on error.

"},{"location":"man3/EVP_BytesToKey/#see-also","title":"SEE ALSO","text":"

evp(7), RAND_bytes(3), PKCS5_PBKDF2_HMAC(3), EVP_EncryptInit(3)

"},{"location":"man3/EVP_BytesToKey/#copyright","title":"COPYRIGHT","text":"

Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/","title":"EVP_CIPHER_CTX_get_cipher_data","text":""},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#name","title":"NAME","text":"

EVP_CIPHER_CTX_get_cipher_data, EVP_CIPHER_CTX_set_cipher_data - Routines to inspect and modify EVP_CIPHER_CTX objects

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nvoid *EVP_CIPHER_CTX_get_cipher_data(const EVP_CIPHER_CTX *ctx);\nvoid *EVP_CIPHER_CTX_set_cipher_data(EVP_CIPHER_CTX *ctx, void *cipher_data);\n
"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#description","title":"DESCRIPTION","text":"

The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the cipher data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the particular implementation of the cipher. For example this data can be used by engines to store engine specific information. The data is automatically allocated and freed by OpenSSL, so applications and engines should not normally free this directly (but see below).

The EVP_CIPHER_CTX_set_cipher_data() function allows an application or engine to replace the cipher data with new data. A pointer to any existing cipher data is returned from this function. If the old data is no longer required then it should be freed through a call to OPENSSL_free().

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#return-values","title":"RETURN VALUES","text":"

The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the current cipher data for the EVP_CIPHER_CTX.

The EVP_CIPHER_CTX_set_cipher_data() function returns a pointer to the old cipher data for the EVP_CIPHER_CTX.

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#history","title":"HISTORY","text":"

The EVP_CIPHER_CTX_get_cipher_data() and EVP_CIPHER_CTX_set_cipher_data() functions were added in OpenSSL 1.1.0.

"},{"location":"man3/EVP_CIPHER_CTX_get_cipher_data/#copyright","title":"COPYRIGHT","text":"

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/","title":"EVP_CIPHER_CTX_get_original_iv","text":""},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#name","title":"NAME","text":"

EVP_CIPHER_CTX_get_original_iv, EVP_CIPHER_CTX_get_updated_iv, EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv, EVP_CIPHER_CTX_iv_noconst - Routines to inspect EVP_CIPHER_CTX IV data

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nint EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);\nint EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx);\nconst unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx);\nunsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx);\n
"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#description","title":"DESCRIPTION","text":"

EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() copy initialization vector (IV) information from the EVP_CIPHER_CTX into the caller-supplied buffer. EVP_CIPHER_CTX_get_iv_length(3) can be used to determine an appropriate buffer size, and if the supplied buffer is too small, an error will be returned (and no data copied). EVP_CIPHER_CTX_get_original_iv() accesses the (\"original\") IV that was supplied when the EVP_CIPHER_CTX was initialized, and EVP_CIPHER_CTX_get_updated_iv() accesses the current \"IV state\" of the cipher, which is updated during cipher operation for certain cipher modes (e.g., CBC and OFB).

The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and EVP_CIPHER_CTX_iv_noconst() are deprecated functions that provide similar (at a conceptual level) functionality. EVP_CIPHER_CTX_iv() returns a pointer to the beginning of the \"IV state\" as maintained internally in the EVP_CIPHER_CTX; EVP_CIPHER_CTX_original_iv() returns a pointer to the beginning of the (\"original\") IV, as maintained by the EVP_CIPHER_CTX, that was provided when the EVP_CIPHER_CTX was initialized; and EVP_CIPHER_CTX_get_iv_noconst() is the same as EVP_CIPHER_CTX_iv() but has a different return type for the pointer.

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#return-values","title":"RETURN VALUES","text":"

EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() return 1 on success and 0 on failure.

The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and EVP_CIPHER_CTX_iv_noconst() return a pointer to an IV as an array of bytes on success, and NULL on failure.

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#history","title":"HISTORY","text":"

EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() were added in OpenSSL 3.0.0.

EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and EVP_CIPHER_CTX_iv_noconst() were added in OpenSSL 1.1.0, and were deprecated in OpenSSL 3.0.0.

"},{"location":"man3/EVP_CIPHER_CTX_get_original_iv/#copyright","title":"COPYRIGHT","text":"

Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EVP_CIPHER_meth_new/","title":"EVP_CIPHER_meth_new","text":""},{"location":"man3/EVP_CIPHER_meth_new/#name","title":"NAME","text":"

EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods

"},{"location":"man3/EVP_CIPHER_meth_new/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len);\nEVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher);\nvoid EVP_CIPHER_meth_free(EVP_CIPHER *cipher);\n\nint EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len);\nint EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags);\nint EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size);\nint EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher,\n                             int (*init)(EVP_CIPHER_CTX *ctx,\n                                         const unsigned char *key,\n                                         const unsigned char *iv,\n                                         int enc));\nint EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher,\n                                  int (*do_cipher)(EVP_CIPHER_CTX *ctx,\n                                                   unsigned char *out,\n                                                   const unsigned char *in,\n                                                   size_t inl));\nint EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher,\n                                int (*cleanup)(EVP_CIPHER_CTX *));\nint EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher,\n                                        int (*set_asn1_parameters)(EVP_CIPHER_CTX *,\n                                                                   ASN1_TYPE *));\nint EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher,\n                                        int (*get_asn1_parameters)(EVP_CIPHER_CTX *,\n                                                                   ASN1_TYPE *));\nint EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher,\n                             int (*ctrl)(EVP_CIPHER_CTX *, int type,\n                                         int arg, void *ptr));\n\nint (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,\n                                                          const unsigned char *key,\n                                                          const unsigned char *iv,\n                                                          int enc);\nint (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx,\n                                                               unsigned char *out,\n                                                               const unsigned char *in,\n                                                               size_t inl);\nint (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *);\nint (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,\n                                                                     ASN1_TYPE *);\nint (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,\n                                                                     ASN1_TYPE *);\nint (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *,\n                                                          int type, int arg,\n                                                          void *ptr);\n
"},{"location":"man3/EVP_CIPHER_meth_new/#description","title":"DESCRIPTION","text":"

All of the functions described on this page are deprecated. Applications should instead use the OSSL_PROVIDER APIs.

The EVP_CIPHER type is a structure for symmetric cipher method implementation.

EVP_CIPHER_meth_new() creates a new EVP_CIPHER structure.

EVP_CIPHER_meth_dup() creates a copy of cipher.

EVP_CIPHER_meth_free() destroys a EVP_CIPHER structure. If the argument is NULL, nothing is done.

EVP_CIPHER_meth_set_iv_length() sets the length of the IV. This is only needed when the implemented cipher mode requires it.

EVP_CIPHER_meth_set_flags() sets the flags to describe optional behaviours in the particular cipher. With the exception of cipher modes, of which only one may be present, several flags can be or'd together. The available flags are:

EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's implementation context so that it can be automatically allocated.

EVP_CIPHER_meth_set_init() sets the cipher init function for cipher. The cipher init function is called by EVP_CipherInit(), EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(), EVP_DecryptInit(), EVP_DecryptInit_ex().

EVP_CIPHER_meth_set_do_cipher() sets the cipher function for cipher. The cipher function is called by EVP_CipherUpdate(), EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(), EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and EVP_DecryptFinal_ex().

EVP_CIPHER_meth_set_cleanup() sets the function for cipher to do extra cleanup before the method's private data structure is cleaned out and freed. Note that the cleanup function is passed a EVP_CIPHER_CTX *, the private data structure is then available with EVP_CIPHER_CTX_get_cipher_data(). This cleanup function is called by EVP_CIPHER_CTX_reset() and EVP_CIPHER_CTX_free().

EVP_CIPHER_meth_set_set_asn1_params() sets the function for cipher to set the AlgorithmIdentifier \"parameter\" based on the passed cipher. This function is called by EVP_CIPHER_param_to_asn1(). EVP_CIPHER_meth_set_get_asn1_params() sets the function for cipher that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier \"parameter\". Both these functions are needed when there is a need for custom data (more or other than the cipher IV). They are called by EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() respectively if defined.

EVP_CIPHER_meth_set_ctrl() sets the control function for cipher.

EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_do_cipher(), EVP_CIPHER_meth_get_cleanup(), EVP_CIPHER_meth_get_set_asn1_params(), EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl() are all used to retrieve the method data given with the EVP_CIPHER_meth_set_*() functions above.

"},{"location":"man3/EVP_CIPHER_meth_new/#return-values","title":"RETURN VALUES","text":"

EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a newly created EVP_CIPHER, or NULL on failure. All EVP_CIPHER_meth_set_*() functions return 1. All EVP_CIPHER_meth_get_*() functions return pointers to their respective cipher function.

"},{"location":"man3/EVP_CIPHER_meth_new/#see-also","title":"SEE ALSO","text":"

EVP_EncryptInit(3)

"},{"location":"man3/EVP_CIPHER_meth_new/#history","title":"HISTORY","text":"

All of these functions were deprecated in OpenSSL 3.0.

The functions described here were added in OpenSSL 1.1.0. The EVP_CIPHER structure created with these functions became reference counted in OpenSSL 3.0.

"},{"location":"man3/EVP_CIPHER_meth_new/#copyright","title":"COPYRIGHT","text":"

Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \"License\"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

"},{"location":"man3/EVP_DigestInit/","title":"EVP_DigestInit","text":""},{"location":"man3/EVP_DigestInit/#name","title":"NAME","text":"

EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free, EVP_MD_get_params, EVP_MD_gettable_params, EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_dup, EVP_MD_CTX_copy, EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, EVP_DigestSqueeze, EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md, EVP_MD_CTX_get_type, EVP_MD_CTX_get_size, EVP_MD_CTX_get_block_size, EVP_MD_CTX_get0_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, EVP_md_null, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, EVP_MD_CTX_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, EVP_MD_do_all_provided, EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data - EVP digest routines

"},{"location":"man3/EVP_DigestInit/#synopsis","title":"SYNOPSIS","text":"
#include <openssl/evp.h>\n\nEVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,\n                     const char *properties);\nint EVP_MD_up_ref(EVP_MD *md);\nvoid EVP_MD_free(EVP_MD *md);\nint EVP_MD_get_params(const EVP_MD *digest, OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_MD_gettable_params(const EVP_MD *digest);\nEVP_MD_CTX *EVP_MD_CTX_new(void);\nint EVP_MD_CTX_reset(EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_free(EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2);\nint EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]);\nint EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]);\nconst OSSL_PARAM *EVP_MD_settable_ctx_params(const EVP_MD *md);\nconst OSSL_PARAM *EVP_MD_gettable_ctx_params(const EVP_MD *md);\nconst OSSL_PARAM *EVP_MD_CTX_settable_params(EVP_MD_CTX *ctx);\nconst OSSL_PARAM *EVP_MD_CTX_gettable_params(EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);\nvoid EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);\nint EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);\n\nint EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name, const char *propq,\n                 const void *data, size_t datalen,\n                 unsigned char *md, size_t *mdlen);\nint EVP_Digest(const void *data, size_t count, unsigned char *md,\n               unsigned int *size, const EVP_MD *type, ENGINE *impl);\nint EVP_DigestInit_ex2(EVP_MD_CTX *ctx, const EVP_MD *type,\n                       const OSSL_PARAM params[]);\nint EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);\nint EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);\nint EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);\nint EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen);\nint EVP_DigestSqueeze(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen);\n\nEVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in);\nint EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);\n\nint EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);\nint EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);\n\nint EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);\n\nconst char *EVP_MD_get0_name(const EVP_MD *md);\nconst char *EVP_MD_get0_description(const EVP_MD *md);\nint EVP_MD_is_a(const EVP_MD *md, const char *name);\nint EVP_MD_names_do_all(const EVP_MD *md,\n                        void (*fn)(const char *name, void *data),\n                        void *data);\nconst OSSL_PROVIDER *EVP_MD_get0_provider(const EVP_MD *md);\nint EVP_MD_get_type(const EVP_MD *md);\nint EVP_MD_get_pkey_type(const EVP_MD *md);\nint EVP_MD_get_size(const EVP_MD *md);\nint EVP_MD_get_block_size(const EVP_MD *md);\nunsigned long EVP_MD_get_flags(const EVP_MD *md);\n\nconst EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx);\nEVP_MD *EVP_MD_CTX_get1_md(EVP_MD_CTX *ctx);\nconst char *EVP_MD_CTX_get0_name(const EVP_MD_CTX *ctx);\nint EVP_MD_CTX_get_size(const EVP_MD_CTX *ctx);\nint EVP_MD_CTX_get_block_size(const EVP_MD_CTX *ctx);\nint EVP_MD_CTX_get_type(const EVP_MD_CTX *ctx);\nvoid *EVP_MD_CTX_get0_md_data(const EVP_MD_CTX *ctx);\n\nconst EVP_MD *EVP_md_null(void);\n\nconst EVP_MD *EVP_get_digestbyname(const char *name);\nconst EVP_MD *EVP_get_digestbynid(int type);\nconst EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);\n\nEVP_PKEY_CTX *EVP_MD_CTX_get_pkey_ctx(const EVP_MD_CTX *ctx);\nvoid EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);\n\nvoid EVP_MD_do_all_provided(OSSL_LIB_CTX *libctx,\n                            void (*fn)(EVP_MD *mac, void *arg),\n                            void *arg);\n\n#define EVP_MD_type EVP_MD_get_type\n#define EVP_MD_nid EVP_MD_get_type\n#define EVP_MD_name EVP_MD_get0_name\n#define EVP_MD_pkey_type EVP_MD_get_pkey_type\n#define EVP_MD_size EVP_MD_get_size\n#define EVP_MD_block_size EVP_MD_get_block_size\n#define EVP_MD_flags EVP_MD_get_flags\n#define EVP_MD_CTX_size EVP_MD_CTX_get_size\n#define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size\n#define EVP_MD_CTX_type EVP_MD_CTX_get_type\n#define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx\n#define EVP_MD_CTX_md_data EVP_MD_CTX_get0_md_data\n

The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);\n\nint (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx,\n                                             const void *data, size_t count);\n\nvoid EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx,\n                              int (*update)(EVP_MD_CTX *ctx,\n                                            const void *data, size_t count));\n
"},{"location":"man3/EVP_DigestInit/#description","title":"DESCRIPTION","text":"

The EVP digest routines are a high-level interface to message digests, and should be used instead of the digest-specific functions.

The EVP_MD type is a structure for digest method implementation.

"},{"location":"man3/EVP_DigestInit/#parameters","title":"PARAMETERS","text":"

See OSSL_PARAM(3) for information about passing parameters.

EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys:

EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys: