Hakase/openssl-custom
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

Latest update.

Browse Source
This commit is contained in:
Hakase
2020-04-15 18:45:34 +09:00
parent be29e7bcc6
commit 2015c00c43
573 changed files with 22943 additions and 6714 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man3/BIO_get_ex_new_index.pod
+4 -3
View File
@@ -9,6 +9,7 @@ DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_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,
RAND_DRBG_set_ex_data, RAND_DRBG_get_ex_data, RAND_DRBG_get_ex_new_index,
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data,
RSA_set_app_data, RSA_get_app_data,
@@ -39,7 +40,7 @@ X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data
int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
void *TYPE_get_ex_data(TYPE *d, int idx);
void *TYPE_get_ex_data(const TYPE *d, int idx);
#define TYPE_set_app_data(TYPE *d, void *arg)
#define TYPE_get_app_data(TYPE *d)
@@ -53,7 +54,7 @@ L<CRYPTO_get_ex_new_index(3)>.
These functions handle application-specific data for OpenSSL data
structures.
TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
TYPE_get_ex_new_index() is a macro that calls CRYPTO_get_ex_new_index()
with the correct B<index> value.
TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
@@ -74,7 +75,7 @@ there are no backward compatibility concerns.
=head1 RETURN VALUES
TYPE_get_new_ex_index() returns a new index on success or -1 on error.
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.
doc/man3/CONF_modules_free.pod
+1 -1
View File
@@ -39,7 +39,7 @@ None of the functions return a value.
=head1 SEE ALSO
L<config(5)>, L<OPENSSL_config(3)>,
L<CONF_modules_load_file(3)>
L<CONF_modules_load_file_with_libctx(3)>
=head1 HISTORY
doc/man3/CONF_modules_load_file.pod
+29 -19
View File
@@ -2,12 +2,16 @@
=head1 NAME
CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
CONF_modules_load_file_with_libctx, CONF_modules_load_file, CONF_modules_load
- OpenSSL configuration functions
=head1 SYNOPSIS
#include <openssl/conf.h>
int CONF_modules_load_file_with_libctx(OPENSSL_CTX *libctx,
const char *filename,
const char *appname, unsigned long flags);
int CONF_modules_load_file(const char *filename, const char *appname,
unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
@@ -15,12 +19,16 @@ CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
=head1 DESCRIPTION
The function CONF_modules_load_file() configures OpenSSL using file
B<filename> and application name B<appname>. If B<filename> is NULL
the standard OpenSSL configuration file is used. If B<appname> is
NULL the standard OpenSSL application name B<openssl_conf> is used.
The function CONF_modules_load_file_with_libctx() configures OpenSSL using
library context B<libctx> file B<filename> and application name B<appname>.
If B<filename> is NULL the standard OpenSSL configuration file is used.
If B<appname> is NULL the standard OpenSSL application name B<openssl_conf> is
used.
The behaviour can be customized using B<flags>.
CONF_modules_load_file() is the same as CONF_modules_load_file_with_libctx() but
has a NULL library context.
CONF_modules_load() is identical to CONF_modules_load_file() except it
reads configuration information from B<cnf>.
@@ -40,8 +48,8 @@ returns success.
This is used by default in L<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 B<CONF_modules_load_file> explicitly should not generally
set this flag.
Applications calling B<CONF_modules_load_file_with_libctx> explicitly should not
generally set this flag.
If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
disabled.
@@ -53,10 +61,10 @@ return an error.
B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
default section pointed to by B<openssl_conf> if B<appname> does not exist.
By using CONF_modules_load_file() 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 B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
By using CONF_modules_load_file_with_libctx() 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 B<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
@@ -78,7 +86,7 @@ return value of the failing module (this will always be zero or negative).
Load a configuration file and print out any errors and exit (missing file
considered fatal):
if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
if (CONF_modules_load_file_with_libctx(libctx, NULL, NULL, 0) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
@@ -87,8 +95,8 @@ considered fatal):
Load default configuration file using the section indicated by "myapp",
tolerate missing files, but exit on other errors:
if (CONF_modules_load_file(NULL, "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
if (CONF_modules_load_file_with_libctx(NULL, NULL, "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
@@ -97,8 +105,8 @@ tolerate missing files, but exit on other errors:
Load custom configuration file and section, only print warnings on error,
missing configuration file ignored:
if (CONF_modules_load_file("/something/app.cnf", "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
if (CONF_modules_load_file_with_libctx(NULL, "/something/app.cnf", "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "WARNING: error loading configuration file\n");
ERR_print_errors_fp(stderr);
}
@@ -114,7 +122,7 @@ Load and parse configuration file manually, custom error handling:
fprintf(stderr, "Error opening configuration file\n");
/* Other missing configuration file behaviour */
} else {
cnf = NCONF_new(NULL);
cnf = NCONF_new_with_libctx(libctx, NULL);
if (NCONF_load_fp(cnf, fp, &eline) == 0) {
fprintf(stderr, "Error on line %ld of configuration file\n", eline);
ERR_print_errors_fp(stderr);
@@ -130,11 +138,13 @@ Load and parse configuration file manually, custom error handling:
=head1 SEE ALSO
L<config(5)>, L<OPENSSL_config(3)>
L<config(5)>,
L<OPENSSL_config(3)>,
L<NCONF_new_with_libctx(3)>
=head1 COPYRIGHT
Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/CRYPTO_get_ex_new_index.pod
+1
View File
@@ -49,6 +49,7 @@ The specific structures are:
DSA
EC_KEY
ENGINE
EVP_PKEY
RAND_DRBG
RSA
SSL
doc/man3/CTLOG_STORE_new.pod
+18 -8
View File
@@ -2,6 +2,7 @@
=head1 NAME
CTLOG_STORE_new_with_libctx,
CTLOG_STORE_new, CTLOG_STORE_free,
CTLOG_STORE_load_default_file, CTLOG_STORE_load_file -
Create and populate a Certificate Transparency log list
@@ -10,6 +11,8 @@ Create and populate a Certificate Transparency log list
#include <openssl/ct.h>
CTLOG_STORE *CTLOG_STORE_new_with_libctx(OPENSSL_CTX *libctx,
const char *propq);
CTLOG_STORE *CTLOG_STORE_new(void);
void CTLOG_STORE_free(CTLOG_STORE *store);
@@ -22,13 +25,19 @@ 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() creates an empty list of CT logs. This 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
F<ct_log_list.cnf> in OPENSSLDIR (see the output of L<openssl-version(1)>).
This can be overridden using an environment variable named B<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.
CTLOG_STORE_new_with_libctx() creates an empty list of CT logs associated with
the library context I<libctx> and the property query string I<propq>.
CTLOG_STORE_new() does the same thing as CTLOG_STORE_new_with_libctx() 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 F<ct_log_list.cnf> in OPENSSLDIR (see the output of
L<openssl-version(1)>). This can be overridden using an environment variable
named B<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:
@@ -65,7 +74,8 @@ L<SSL_CTX_set_ctlog_list_file(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.1.0.
CTLOG_STORE_new_with_libctx was added in OpenSSL 3.0. All other functions were
added in OpenSSL 1.1.0.
=head1 COPYRIGHT
doc/man3/CTLOG_new.pod
+27 -9
View File
@@ -2,7 +2,8 @@
=head1 NAME
CTLOG_new, CTLOG_new_from_base64, CTLOG_free,
CTLOG_new_with_libctx, CTLOG_new, CTLOG_new_from_base64,
CTLOG_new_from_base64_with_libctx, CTLOG_free,
CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key -
encapsulates information about a Certificate Transparency log
@@ -10,7 +11,13 @@ encapsulates information about a Certificate Transparency log
#include <openssl/ct.h>
CTLOG *CTLOG_new_with_libctx(EVP_PKEY *public_key, const char *name,
OPENSSL_CTX *libctx, const char *propq);
CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);
int CTLOG_new_from_base64_with_libctx(CTLOG **ct_log, const char *pkey_base64,
const char *name, OPENSSL_CTX *libctx,
const char *propq);
int CTLOG_new_from_base64(CTLOG ** ct_log,
const char *pkey_base64, const char *name);
void CTLOG_free(CTLOG *log);
@@ -21,14 +28,24 @@ encapsulates information about a Certificate Transparency log
=head1 DESCRIPTION
CTLOG_new() returns a new CTLOG that represents the Certificate Transparency
(CT) log with the given public key. 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_with_libctx() returns a new CTLOG that represents the Certificate
Transparency (CT) log with the given public key and associates it with the
library context I<libctx> and property query string I<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_from_base64() 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.
CTLOG_new() does the same thing as CTLOG_new_with_libctx() but with the default
library context and the default property query string.
CTLOG_new_from_base64_with_libctx() 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 I<libctx> and property query
string I<propq>.
CTLOG_new_from_base64() does the same thing as
CTLOG_new_from_base64_with_libctx() 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
@@ -58,7 +75,8 @@ L<ct(7)>
=head1 HISTORY
These functions were added in OpenSSL 1.1.0.
The functions CTLOG_new_with_libctx() and CTLOG_new_from_base64_with_libctx()
were added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
doc/man3/CT_POLICY_EVAL_CTX_new.pod
+16 -4
View File
@@ -2,6 +2,7 @@
=head1 NAME
CT_POLICY_EVAL_CTX_new_with_libctx,
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,
@@ -13,6 +14,8 @@ Encapsulates the data required to evaluate whether SCTs meet a Certificate Trans
#include <openssl/ct.h>
CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new_with_libctx(OPENSSL_CTX *libctx,
const char *propq);
CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);
void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);
X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);
@@ -55,8 +58,15 @@ the current time
The above requirements are met using the setters described below.
CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This
should then be populated using:
CT_POLICY_EVAL_CTX_new_with_libctx() creates an empty policy evaluation context
and associates it with the given library context I<libctx> and property query
string I<propq>.
CT_POLICY_EVAL_CTX_new() does the same thing as
CT_POLICY_EVAL_CTX_new_with_libctx() except that it uses the default library
context and property query string.
The CT_POLICY_EVAL_CTX should then be populated using:
=over 2
@@ -106,7 +116,8 @@ found in the TLS SCT extension or OCSP response.
=head1 RETURN VALUES
CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails.
CT_POLICY_EVAL_CTX_new_with_libctx() and CT_POLICY_EVAL_CTX_new() will return
NULL if malloc fails.
=head1 SEE ALSO
@@ -114,7 +125,8 @@ L<ct(7)>
=head1 HISTORY
These functions were added in OpenSSL 1.1.0.
CT_POLICY_EVAL_CTX_new_with_libctx was added in OpenSSL 3.0. All other
functions were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
doc/man3/EVP_DigestInit.pod
+53 -39
View File
@@ -110,8 +110,8 @@ The B<EVP_MD> type is a structure for digest method implementation.
=item EVP_MD_fetch()
Fetches the digest implementation for the given B<algorithm> from any
provider offering it, within the criteria given by the B<properties>.
Fetches the digest implementation for the given I<algorithm> from any
provider offering it, within the criteria given by the I<properties>.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with EVP_MD_free().
@@ -133,37 +133,45 @@ Allocates and returns a digest context.
=item EVP_MD_CTX_reset()
Resets the digest context B<ctx>. This can be used to reuse an already
Resets the digest context I<ctx>. This can be used to reuse an already
existing context.
=item EVP_MD_CTX_free()
Cleans up digest context B<ctx> and frees up the space allocated to it.
Cleans up digest context I<ctx> and frees up the space allocated to it.
=item EVP_MD_CTX_ctrl()
This is a legacy method. EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params()
I<This is a legacy method. EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params()
is the mechanism that should be used to set and get parameters that are used by
providers.
Performs digest-specific control actions on context B<ctx>. The control command
is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>.
providers.>
Performs digest-specific control actions on context I<ctx>. The control command
is indicated in I<cmd> and any additional arguments in I<p1> and I<p2>.
EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions
may apply depending on the control type and digest implementation.
See L</CONTROLS> below for more information.
If this function happens to be used with a fetched B<EVP_MD>, it will
translate the controls that are known to OpenSSL into L<OSSL_PARAM(3)>
parameters with keys defined by OpenSSL and call EVP_MD_CTX_get_params() or
EVP_MD_CTX_set_params() as is appropriate for each control command.
See L</CONTROLS> below for more information, including what translations are
being done.
=item EVP_MD_get_params()
Retrieves the requested list of B<params> from a MD B<md>.
Retrieves the requested list of I<params> from a MD I<md>.
See L</PARAMETERS> below for more information.
=item EVP_MD_CTX_get_params()
Retrieves the requested list of B<params> from a MD context B<ctx>.
Retrieves the requested list of I<params> from a MD context I<ctx>.
See L</PARAMETERS> below for more information.
=item EVP_MD_CTX_set_params()
Sets the list of B<params> into a MD context B<ctx>.
Sets the list of I<params> into a MD context I<ctx>.
See L</PARAMETERS> below for more information.
=item EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(),
@@ -181,36 +189,36 @@ See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()
Sets, clears and tests B<ctx> flags. See L</FLAGS> below for more information.
Sets, clears and tests I<ctx> flags. See L</FLAGS> below for more information.
=item EVP_Digest()
A wrapper around the Digest Init_ex, Update and Final_ex functions.
Hashes B<count> bytes of data at B<data> using a digest B<type> from ENGINE
B<impl>. The digest value is placed in B<md> and its length is written at B<size>
Hashes I<count> bytes of data at I<data> using a digest I<type> from ENGINE
I<impl>. The digest value is placed in I<md> and its length is written at I<size>
if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written.
If B<impl> is NULL the default implementation of digest B<type> is used.
If I<impl> is NULL the default implementation of digest I<type> is used.
=item EVP_DigestInit_ex()
Sets up digest context B<ctx> to use a digest B<type>.
B<type> is typically supplied by a function such as EVP_sha1(), or a
Sets up digest context I<ctx> to use a digest I<type>.
I<type> is typically supplied by a function such as EVP_sha1(), or a
value explicitly fetched with EVP_MD_fetch().
If B<impl> is non-NULL, its implementation of the digest B<type> is used if
If I<impl> is non-NULL, its implementation of the digest I<type> is used if
there is one, and if not, the default implementation is used.
=item EVP_DigestUpdate()
Hashes B<cnt> bytes of data at B<d> into the digest context B<ctx>. This
function can be called several times on the same B<ctx> to hash additional
Hashes I<cnt> bytes of data at I<d> into the digest context I<ctx>. This
function can be called several times on the same I<ctx> to hash additional
data.
=item EVP_DigestFinal_ex()
Retrieves the digest value from B<ctx> and places it in B<md>. If the B<s>
Retrieves the digest value from I<ctx> and places it in I<md>. If the I<s>
parameter is not NULL then the number of bytes of data written (i.e. the
length of the digest) will be written to the integer at B<s>, at most
length of the digest) will be written to the integer at I<s>, at most
B<EVP_MAX_MD_SIZE> bytes will be written. After calling EVP_DigestFinal_ex()
no additional calls to EVP_DigestUpdate() can be made, but
EVP_DigestInit_ex() can be called to initialize a new digest operation.
@@ -218,13 +226,13 @@ EVP_DigestInit_ex() can be called to initialize a new digest operation.
=item EVP_DigestFinalXOF()
Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256.
It retrieves the digest value from B<ctx> and places it in B<len>-sized <B>md.
It retrieves the digest value from I<ctx> and places it in I<len>-sized <B>md.
After calling this function no additional calls to EVP_DigestUpdate() can be
made, but EVP_DigestInit_ex() can be called to initialize a new operation.
=item EVP_MD_CTX_copy_ex()
Can be used to copy the message digest state from B<in> to B<out>. This is
Can be used to copy the message digest state from I<in> to I<out>. This is
useful if large amounts of data are to be hashed which only differ in the last
few bytes.
@@ -235,12 +243,12 @@ default digest implementation and calls EVP_MD_CTX_reset().
=item EVP_DigestFinal()
Similar to EVP_DigestFinal_ex() except the digest context B<ctx> is
Similar to EVP_DigestFinal_ex() except the digest context I<ctx> is
automatically cleaned up.
=item EVP_MD_CTX_copy()
Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to
Similar to EVP_MD_CTX_copy_ex() except the destination I<out> does not have to
be initialized.
=item EVP_MD_is_a()
@@ -311,17 +319,17 @@ should not be used after the EVP_MD_CTX is freed.
=item EVP_MD_CTX_set_update_fn()
Sets the update function for B<ctx> to B<update>.
Sets the update function for I<ctx> to I<update>.
This is the function that is called by EVP_DigestUpdate. If not set, the
update function from the B<EVP_MD> type specified at initialization is used.
=item EVP_MD_CTX_update_fn()
Returns the update function for B<ctx>.
Returns the update function for I<ctx>.
=item EVP_MD_flags()
Returns the B<md> flags. Note that these are different from the B<EVP_MD_CTX>
Returns the I<md> flags. Note that these are different from the B<EVP_MD_CTX>
ones. See L<EVP_MD_meth_set_flags(3)> for more information.
=item EVP_MD_pkey_type()
@@ -345,16 +353,16 @@ B<ASN1_OBJECT> structure respectively.
=item EVP_MD_CTX_pkey_ctx()
Returns the B<EVP_PKEY_CTX> assigned to B<ctx>. The returned pointer should not
Returns the B<EVP_PKEY_CTX> assigned to I<ctx>. The returned pointer should not
be freed by the caller.
=item EVP_MD_CTX_set_pkey_ctx()
Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide
a customized B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or
L<EVP_DigestVerifyInit(3)>. The B<pctx> passed to this function should be freed
by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX>
assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
L<EVP_DigestVerifyInit(3)>. The I<pctx> passed to this function should be freed
by the caller. A NULL I<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX>
assigned to I<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
depends on how the B<EVP_PKEY_CTX> is created.
=item EVP_MD_do_all_provided()
@@ -382,7 +390,7 @@ using a B<size_t>.
=item "pad_type" (B<OSSL_PARAM_DIGEST_KEY_PAD_TYPE>) <integer>
Sets the pad type.
Sets the padding type.
It is used by the MDC2 algorithm.
=back
@@ -409,15 +417,21 @@ EVP_MD_CTX_ctrl() can be used to send the following standard controls:
Gets the digest Message Integrity Check algorithm string. This is used when
creating S/MIME multipart/signed messages, as specified in RFC 3851.
The string value is written to B<p2>.
The string value is written to I<p2>.
When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with
an L<OSSL_PARAM(3)> item with the key "micalg" (B<OSSL_DIGEST_PARAM_MICALG>).
=item EVP_MD_CTRL_XOF_LEN
This control sets the digest length for extendable output functions to B<p1>.
This control sets the digest length for extendable output functions to I<p1>.
Sending this control directly should not be necessary, the use of
C<EVP_DigestFinalXOF()> is preferred.
EVP_DigestFinalXOF() is preferred.
Currently used by SHAKE.
When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with
an L<OSSL_PARAM(3)> item with the key "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>).
=back
=head1 FLAGS
@@ -529,7 +543,7 @@ New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3
digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms
are still in common use.
For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
For most applications the I<impl> parameter to EVP_DigestInit_ex() will be
set to NULL to use the default digest implementation.
The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
doc/man3/EVP_DigestSignInit.pod
+4 -2
View File
@@ -11,7 +11,7 @@ EVP_DigestSignFinal, EVP_DigestSign - EVP signing functions
int EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const char *mdname, const char *props,
EVP_PKEY *pkey);
EVP_PKEY *pkey, OPENSSL_CTX *libctx);
int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
@@ -51,7 +51,9 @@ existing value in I<*pctx> is overwritten. The EVP_PKEY_CTX value returned must
not be freed directly by the application if I<ctx> is not assigned an
EVP_PKEY_CTX value before being passed to EVP_DigestSignInit_ex() (which means
the EVP_PKEY_CTX is created inside EVP_DigestSignInit_ex() and it will be freed
automatically when the EVP_MD_CTX is freed).
automatically when the EVP_MD_CTX is freed). If the EVP_PKEY_CTX to be used is
created by EVP_DigestSignInit_ex then it will use the B<OPENSSL_CTX> specified
in I<libctx> and the property query string specified in I<props>.
The digest I<mdname> may be NULL if the signing algorithm supports it. The
I<props> argument can always be NULL.
doc/man3/EVP_DigestVerifyInit.pod
+14 -15
View File
@@ -11,7 +11,7 @@ EVP_DigestVerifyFinal, EVP_DigestVerify - EVP signature verification functions
int EVP_DigestVerifyInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const char *mdname, const char *props,
EVP_PKEY *pkey, EVP_SIGNATURE *signature);
EVP_PKEY *pkey, OPENSSL_CTX *libctx);
int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
@@ -26,20 +26,17 @@ The EVP signature routines are a high level interface to digital signatures.
Input data is digested first before the signature verification takes place.
EVP_DigestVerifyInit_ex() sets up verification context B<ctx> to use a digest
with the name B<mdname> and public key B<pkey>. The signature algorithm
B<signature> will be used for the actual signature verification which must be
compatible with the public key. The name of the digest to be used is passed to
the provider of the signature algorithm in use. How that provider interprets the
digest name is provider specific. The provider may implement that digest
directly itself or it may (optionally) choose to fetch it (which could result in
a digest from a different provider being selected). If the provider supports
fetching the digest then it may use the B<props> argument for the properties to
be used during the fetch.
with the name B<mdname> and public key B<pkey>. The name of the digest to be
used is passed to the provider of the signature algorithm in use. How that
provider interprets the digest name is provider specific. The provider may
implement that digest directly itself or it may (optionally) choose to fetch it
(which could result in a digest from a different provider being selected). If
the provider supports fetching the digest then it may use the B<props> argument
for the properties to be used during the fetch.
The B<signature> parameter may be NULL in which case a suitable signature
algorithm implementation will be implicitly fetched based on the type of key in
use. See L<provider(7)> for further information about providers and fetching
algorithms.
The I<pkey> algorithm is used to fetch a B<EVP_SIGNATURE> method implicitly, to
be used for the actual signing. See L<provider(7)/Implicit fetch> for
more information about implict fetches.
The OpenSSL default and legacy providers support fetching digests and can fetch
those digests from any available provider. The OpenSSL fips provider also
@@ -53,7 +50,9 @@ Note that any existing value in B<*pctx> is overwritten. The EVP_PKEY_CTX value
returned must not be freed directly by the application if B<ctx> is not assigned
an EVP_PKEY_CTX value before being passed to EVP_DigestVerifyInit_ex() (which
means the EVP_PKEY_CTX is created inside EVP_DigestVerifyInit_ex() and it will
be freed automatically when the EVP_MD_CTX is freed).
be freed automatically when the EVP_MD_CTX is freed). If the EVP_PKEY_CTX to be
used is created by EVP_DigestVerifyInit_ex then it will use the B<OPENSSL_CTX>
specified in I<libctx> and the property query string specified in I<props>.
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit_ex() if the passed
B<ctx> has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>. See also
doc/man3/EVP_PKEY_CTX_ctrl.pod
+22 -4
View File
@@ -51,6 +51,8 @@ EVP_PKEY_CTX_set_dh_kdf_outlen,
EVP_PKEY_CTX_get_dh_kdf_outlen,
EVP_PKEY_CTX_set0_dh_kdf_ukm,
EVP_PKEY_CTX_get0_dh_kdf_ukm,
EVP_PKEY_CTX_set_ec_paramgen_curve_name,
EVP_PKEY_CTX_get_ec_paramgen_curve_name,
EVP_PKEY_CTX_set_ec_paramgen_curve_nid,
EVP_PKEY_CTX_set_ec_param_enc,
EVP_PKEY_CTX_set_ecdh_cofactor_mode,
@@ -143,6 +145,10 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
#include <openssl/ec.h>
int EVP_PKEY_CTX_set_ec_paramgen_curve_name(EVP_PKEY_CTX *ctx,
const char *name);
int EVP_PKEY_CTX_get_ec_paramgen_curve_name(EVP_PKEY_CTX *ctx,
char *name, size_t namelen);
int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode);
@@ -513,12 +519,24 @@ by the library and should not be freed by the caller.
=head2 EC parameters
The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
generation to I<nid>. For EC parameter generation this macro must be called
or an error occurs because there is no default curve.
This function can also be called to set the curve explicitly when
EVP_PKEY_CTX_set_ec_paramgen_curve_name() sets the EC curve to I<name> for EC
parameter generation.
EVP_PKEY_CTX_set_ec_paramgen_curve_nid() does the same as
EVP_PKEY_CTX_set_ec_paramgen_curve_name(), but uses a I<nid> rather than a
name string.
For EC parameter generation, one of EVP_PKEY_CTX_set_ec_paramgen_curve_name()
or EVP_PKEY_CTX_set_ec_paramgen_curve_nid() must be called or an error occurs
because there is no default curve.
These function can also be called to set the curve explicitly when
generating an EC key.
EVP_PKEY_CTX_get_ec_paramgen_curve_name() finds the curve name that's currently
set with I<ctx>, and writes it to the location that I<name> points at, as long
as its size I<namelen> is large enough to store that name, including a
terminating NUL byte.
The EVP_PKEY_CTX_set_ec_param_enc() macro sets the EC parameter encoding to
I<param_enc> when generating EC parameters or an EC key. The encoding can be
B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions
doc/man3/EVP_PKEY_fromdata.pod
+1 -1
View File
@@ -52,7 +52,7 @@ not supported by the public key algorithm.
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)>, L<provider(7)>
L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>
=head1 HISTORY
doc/man3/EVP_PKEY_keygen.pod → doc/man3/EVP_PKEY_gen.pod
+57 -22
View File
@@ -2,11 +2,12 @@
=head1 NAME
EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
EVP_PKEY_keygen_init, EVP_PKEY_paramgen_init, EVP_PKEY_gen,
EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
EVP_PKEY_CTX_get_app_data,
EVP_PKEY_gen_cb
EVP_PKEY_gen_cb,
EVP_PKEY_paramgen, EVP_PKEY_keygen
- key and parameter generation and check functions
=head1 SYNOPSIS
@@ -14,9 +15,10 @@ EVP_PKEY_gen_cb
#include <openssl/evp.h>
int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_gen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
@@ -30,24 +32,51 @@ EVP_PKEY_gen_cb
=head1 DESCRIPTION
The EVP_PKEY_keygen_init() function initializes a public key algorithm
context using key B<pkey> for a key generation operation.
Generating keys is sometimes straight forward, just generate the key's
numbers and be done with it. However, there are certain key types that need
key parameters, often called domain parameters but not necessarily limited
to that, that also need to be generated. In addition to this, the caller
may want to set user provided generation parameters that further affect key
parameter or key generation, such as the desired key size.
The EVP_PKEY_keygen() function performs a key generation operation, the
generated key is written to B<ppkey>.
To flexibly allow all that's just been described, key parameter and key
generation is divided into an initialization of a key algorithm context,
functions to set user provided parameters, and finally the key parameter or
key generation function itself.
The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar
except parameters are generated.
The key algorithm context must be created using L<EVP_PKEY_CTX_new(3)> or
variants thereof, see that manual for details.
EVP_PKEY_keygen_init() initializes a public key algorithm context using key
I<pkey> for a key generation operation.
EVP_PKEY_paramgen_init() is similar to EVP_PKEY_keygen_init() except key
parameters are generated.
After initialization, generation parameters may be provided with
L<EVP_PKEY_CTX_ctrl(3)> or L<EVP_PKEY_CTX_set_params(3)>, or any other
function described in those manuals.
EVP_PKEY_gen() performs the generation operation, the resulting key
parameters or key are written to I<*ppkey>. If I<*ppkey> is NULL when this
function is called, it will be allocated, and should be freed by the caller
when no longer useful, using L<EVP_PKEY_free(3)>.
EVP_PKEY_paramgen() and EVP_PKEY_keygen() do exactly the same thing as
EVP_PKEY_gen(), after checking that the corresponding EVP_PKEY_paramgen_init()
or EVP_PKEY_keygen_init() was used to initialize I<ctx>.
These are older functions that are kept for backward compatibility.
It is safe to use EVP_PKEY_gen() instead.
The function EVP_PKEY_set_cb() sets the key or parameter generation callback
to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
to I<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
generation callback.
The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated
with the generation operation. If B<idx> is -1 the total number of
with the generation operation. If I<idx> is -1 the total number of
parameters available is returned. Any non negative value returns the value of
that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
B<idx> should only be called within the generation callback.
I<idx> should only be called within the generation callback.
If the callback returns 0 then the key generation operation is aborted and an
error occurs. This might occur during a time consuming operation where
@@ -58,6 +87,13 @@ and retrieve an opaque pointer. This can be used to set some application
defined value which can be retrieved in the callback: for example a handle
which is used to update a "progress dialog".
=head1 RETURN VALUES
EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
=head1 NOTES
After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
@@ -82,13 +118,6 @@ public key components and parameters (if any). An OpenSSL private key is
equivalent to what some libraries call a "key pair". A private key can be used
in functions which require the use of a public key or parameters.
=head1 RETURN VALUES
EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
=head1 EXAMPLES
Generate a 2048 bit RSA key:
@@ -168,11 +197,17 @@ L<EVP_PKEY_derive(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.0.0.
EVP_PKEY_keygen_init(), int EVP_PKEY_paramgen_init(), EVP_PKEY_keygen(),
EVP_PKEY_paramgen(), EVP_PKEY_gen_cb(), EVP_PKEY_CTX_set_cb(),
EVP_PKEY_CTX_get_cb(), EVP_PKEY_CTX_get_keygen_info(),
EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() were added in
OpenSSL 1.0.0.
EVP_PKEY_gen() was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/EVP_PKEY_gettable_params.pod
+108
View File
@@ -0,0 +1,108 @@
=pod
=head1 NAME
EVP_PKEY_gettable_params, EVP_PKEY_get_int_param, EVP_PKEY_get_size_t_param,
EVP_PKEY_get_bn_param, EVP_PKEY_get_utf8_string_param,
EVP_PKEY_get_octet_string_param
- retrieve key parameters from a key
=head1 SYNOPSIS
#include <openssl/evp.h>
const OSSL_PARAM *EVP_PKEY_gettable_params(EVP_PKEY *pkey);
int EVP_PKEY_get_int_param(EVP_PKEY *pkey, const char *key_name, int *out);
int EVP_PKEY_get_size_t_param(EVP_PKEY *pkey, const char *key_name, size_t *out);
int EVP_PKEY_get_bn_param(EVP_PKEY *pkey, const char *key_name, BIGNUM **bn);
int EVP_PKEY_get_utf8_string_param(EVP_PKEY *pkey, const char *key_name,
char *str, size_t max_buf_sz, size_t *out_sz);
int EVP_PKEY_get_octet_string_param(EVP_PKEY *pkey, const char *key_name,
unsigned char *buf, size_t max_buf_sz,
size_t *out_sz);
=head1 DESCRIPTION
EVP_PKEY_gettable_params() returns a constant list of I<params> indicating
the names and types of key parameters that can be retrieved.
See L<OSSL_PARAM(3)> for information about parameters.
EVP_PKEY_get_int_param() retrieves a key I<pkey> integer value I<*out>
associated with a name of I<key_name>.
EVP_PKEY_get_size_t_param() retrieves a key I<pkey> size_t value I<*out>
associated with a name of I<key_name>.
EVP_PKEY_get_bn_param() retrieves a key I<pkey> BIGNUM value I<**bn>
associated with a name of I<key_name>. If I<*bn> is NULL then the BIGNUM
is allocated by the method.
EVP_PKEY_get_utf8_string_param() get a key I<pkey> UTF8 string value int a buffer
I<str> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
I<*out_sz> is the returned size of the string if it is not NULL.
EVP_PKEY_get_octet_string_param() copy a I<pkey>'s octet string value into a buffer
I<buf> of maximum size I<max_buf_sz> associated with a name of I<key_name>.
I<*out_sz> is the returned size of the buffer if it is not NULL.
=head1 NOTES
These functions only work for B<EVP_PKEY>s that contain a provider side key.
=head1 RETURN VALUES
EVP_PKEY_gettable_params() returns NULL on error or if it is not supported,
All other methods return 1 if a value associated with the key's I<key_name> was
successfully returned, or 0 if there was an error.
An error may be returned by methods EVP_PKEY_get_utf8_string_param() and
EVP_PKEY_get_octet_string_param() if I<max_buf_sz> is not big enough to hold the
value.
=head1 EXAMPLES
#include <openssl/evp.h>
char *curve_name[64];
unsigned char pub[256];
BIGNUM *bn_priv = NULL;
/*
* NB: assumes 'key' is set up before the next step. In this example the key
* is an EC key.
*/
if (!EVP_PKEY_get_utf8_string_param(key, OSSL_PKEY_PARAM_EC_NAME,
curve_name, sizeof(curve_name), &len)) {
/* Error */
}
if (!EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY,
pub, sizeof(pub), &len)) {
/* Error */
}
if (!EVP_PKEY_get_bn_param(key, OSSL_PKEY_PARAM_PRIV_KEY, &bn_priv)) {
/* Error */
}
BN_clear_free(bn_priv);
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)>, L<provider-keymgmt(7)>, L<OSSL_PARAM(3)>
=head1 HISTORY
These functions were added in OpenSSL 3.0.
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/EVP_PKEY_is_a.pod
+72
View File
@@ -0,0 +1,72 @@
=pod
=head1 NAME
EVP_PKEY_is_a, EVP_PKEY_can_sign
- key type and capabilities functions
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_is_a(const EVP_PKEY *pkey, const char *name);
int EVP_PKEY_can_sign(const EVP_PKEY *pkey);
=head1 DESCRIPTION
EVP_PKEY_is_a() checks if the key type of I<pkey> is I<name>.
EVP_PKEY_can_sign() checks if the functionality for the key type of
I<pkey> supports signing. No other check is done, such as whether
I<pkey> contains a private key.
=head1 RETURN VALUES
EVP_PKEY_is_a() returns 1 if I<pkey> has the key type I<name>,
otherwise 0.
EVP_PKEY_can_sign() returns 1 if the I<pkey> key type functionality
supports signing, otherwise 0.
=head1 EXAMPLES
=head2 EVP_PKEY_is_a()
The loaded providers and what key types they support will ultimately
determine what I<name> is possible to use with EVP_PKEY_is_a(). We do know
that the default provider supports RSA, DH, DSA and EC keys, so we can use
this as an crude example:
#include <openssl/evp.h>
...
/* |pkey| is an EVP_PKEY* */
if (EVP_PKEY_is_a(pkey, "RSA")) {
BIGNUM *modulus = NULL;
if (EVP_PKEY_get_bn_param(pkey, "n", &modulus))
/* do whatever with the modulus */
BN_free(modulus);
}
=head2 EVP_PKEY_can_sign()
#include <openssl/evp.h>
...
/* |pkey| is an EVP_PKEY* */
if (!EVP_PKEY_can_sign(pkey)) {
fprintf(stderr, "Not a signing key!");
exit(1);
}
/* Sign something... */
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/EVP_PKEY_set1_RSA.pod
+25 -16
View File
@@ -51,52 +51,61 @@ EVP_PKEY_set1_engine, EVP_PKEY_get0_engine - EVP_PKEY assignment functions
=head1 DESCRIPTION
EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>.
EVP_PKEY_set1_EC_KEY() set the key referenced by I<pkey> to I<key>.
EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
B<NULL> if the key is not of the correct type.
EVP_PKEY_get1_EC_KEY() return the referenced key in I<pkey> or
NULL if the key is not of the correct type.
EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(),
EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH()
and EVP_PKEY_get0_EC_KEY() also return the referenced key in B<pkey> or B<NULL>
and EVP_PKEY_get0_EC_KEY() also return the referenced key in I<pkey> or NULL
if the key is not of the correct type but the reference count of the
returned key is B<not> incremented and so must not be freed up after use.
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and
EVP_PKEY_assign_SIPHASH() also set the referenced key to B<key>
however these use the supplied B<key> internally and so B<key>
will be freed when the parent B<pkey> is freed.
EVP_PKEY_assign_SIPHASH() also set the referenced key to I<key>
however these use the supplied I<key> internally and so I<key>
will be freed when the parent I<pkey> is freed.
EVP_PKEY_base_id() returns the type of B<pkey>. For example
EVP_PKEY_base_id() returns the type of I<pkey>. For example
an RSA key will return B<EVP_PKEY_RSA>.
EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys
EVP_PKEY_id() returns the actual OID associated with I<pkey>. Historically keys
using the same algorithm could use different OIDs. For example an RSA key could
use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to
B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of
alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not
often seen in practice.
EVP_PKEY_type() returns the underlying type of the NID B<type>. For example
EVP_PKEY_type() returns the underlying type of the NID I<type>. For example
EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
EVP_PKEY_get0_engine() returns a reference to the ENGINE handling B<pkey>.
EVP_PKEY_get0_engine() returns a reference to the ENGINE handling I<pkey>.
EVP_PKEY_set1_engine() sets the ENGINE handling B<pkey> to B<engine>. It
EVP_PKEY_set1_engine() sets the ENGINE handling I<pkey> to I<engine>. It
must be called after the key algorithm and components are set up.
If B<engine> does not include an B<EVP_PKEY_METHOD> for B<pkey> an
If I<engine> does not include an B<EVP_PKEY_METHOD> for I<pkey> an
error occurs.
EVP_PKEY_set_alias_type() allows modifying a EVP_PKEY to use a
different set of algorithms than the default.
=head1 WARNINGS
The following functions are only reliable with B<EVP_PKEY>s that have
been assigned an internal key with EVP_PKEY_assign_*():
EVP_PKEY_id(), EVP_PKEY_base_id(), EVP_PKEY_type(), EVP_PKEY_set_alias_type()
For EVP_PKEY key type checking purposes, L<EVP_PKEY_is_a(3)> is more generic.
=head1 NOTES
In accordance with the OpenSSL naming convention the key obtained
from or assigned to the B<pkey> using the B<1> functions must be
freed as well as B<pkey>.
from or assigned to the I<pkey> using the B<1> functions must be
freed as well as I<pkey>.
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305()
@@ -129,7 +138,7 @@ EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
EVP_PKEY_get1_EC_KEY() return the referenced key or NULL if
an error occurred.
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
doc/man3/EVP_PKEY_set_type.pod
+68
View File
@@ -0,0 +1,68 @@
=pod
=head1 NAME
EVP_PKEY_set_type, EVP_PKEY_set_type_str, EVP_PKEY_set_type_by_keymgmt
- functions to change the EVP_PKEY type
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_set_type(EVP_PKEY *pkey, int type);
int EVP_PKEY_set_type_str(EVP_PKEY *pkey, const char *str, int len);
int EVP_PKEY_set_type_by_keymgmt(EVP_PKEY *pkey, EVP_KEYMGMT *keymgmt);
=head1 DESCRIPTION
All the functions described here behave the same in so far that they
clear all the previous key data and methods from I<pkey>, and reset it
to be of the type of key given by the different arguments. If
I<pkey> is NULL, these functions will still return the same return
values as if it wasn't.
EVP_PKEY_set_type() initialises I<pkey> to contain an internal legacy
key. When doing this, it finds a L<EVP_PKEY_ASN1_METHOD(3)>
corresponding to I<type>, and associates I<pkey> with the findings.
It is an error if no L<EVP_PKEY_ASN1_METHOD(3)> could be found for
I<type>.
EVP_PKEY_set_type_str() initialises I<pkey> to contain an internal legacy
key. When doing this, it finds a L<EVP_PKEY_ASN1_METHOD(3)>
corresponding to I<str> that has then length I<len>, and associates
I<pkey> with the findings.
It is an error if no L<EVP_PKEY_ASN1_METHOD(3)> could be found for
I<type>.
For both EVP_PKEY_set_type() and EVP_PKEY_set_type_str(), I<pkey> gets
a numeric type, which can be retrieved with L<EVP_PKEY_id(3)>. This
numeric type is taken from the L<EVP_PKEY_ASN1_METHOD(3)> that was
found, and is equal to or closely related to I<type> in the case of
EVP_PKEY_set_type(), or related to I<str> in the case of
EVP_PKEY_set_type_str().
EVP_PKEY_set_type_by_keymgmt() initialises I<pkey> to contain an
internal provider side key. When doing this, it associates I<pkey>
with I<keymgmt>. For keys initialised like this, the numeric type
retrieved with L<EVP_PKEY_id(3)> will always be B<EVP_PKEY_NONE>.
=head1 RETURN VALUES
All functions described here return 1 if successful, or 0 on error.
=head1 SEE ALSO
L<EVP_PKEY_assign(3)>, L<EVP_PKEY_id(3)>, L<EVP_PKEY_get0_RSA(3)>,
L<EVP_PKEY_copy_parameters(3)>, L<EVP_PKEY_ASN1_METHOD(3)>,
L<EVP_KEYMGMT(3)>
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/EVP_aes_128_gcm.pod
+7
View File
@@ -160,6 +160,13 @@ In particular, XTS-AES-128 (B<EVP_aes_128_xts>) takes input of a 256-bit key to
achieve AES 128-bit security, and XTS-AES-256 (B<EVP_aes_256_xts>) takes input
of a 512-bit key to achieve AES 256-bit security.
The XTS implementation in OpenSSL does not support streaming. That is there must
only be one L<EVP_EncryptUpdate(3)> call per L<EVP_EncryptInit_ex(3)> call (and
similarly with the "Decrypt" functions).
The I<iv> parameter to L<EVP_EncryptInit_ex(3)> or L<EVP_DecryptInit_ex(3)> is
the XTS "tweak" value.
=back
=head1 RETURN VALUES
doc/man3/ISSUER_SIGN_TOOL_new.pod
+51
View File
@@ -0,0 +1,51 @@
=pod
=head1 NAME
ISSUER_SIGN_TOOL_new, ISSUER_SIGN_TOOL_free,ISSUER_SIGN_TOOL_it,
d2i_ISSUER_SIGN_TOOL, i2d_ISSUER_SIGN_TOOL
=head1 SYNOPSIS
=for openssl generic
#include <openssl/x509v3.h>
extern const ISSUER_SIGN_TOOL_it;
ISSUER_SIGN_TOOL *ISSUER_SIGN_TOOL_new(void);
void ISSUER_SIGN_TOOL_free(ISSUER_SIGN_TOOL *v);
ISSUER_SIGN_TOOL *d2i_ISSUER_SIGN_TOOL(ISSUER_SIGN_TOOL **a, const unsigned char **pp, long length);
int i2d_ISSUER_SIGN_TOOL(const ISSUER_SIGN_TOOL *a, unsigned char **pp);
=head1 DESCRIPTION
The ISSUER_SIGN_TOOL_new() function returns a new ISSUER_SIGN_TOOL.
ISSUER_SIGN_TOOL_free() frees up a single ISSUER_SIGN_TOOL object.
=head1 RETURN VALUES
ISSUER_SIGN_TOOL_new() returns a newly created ISSUER_SIGN_TOOL or NULL if the call fails.
ISSUER_SIGN_TOOL_free() does not return values.
d2i_ISSUER_SIGN_TOOL() and i2d_ISSUER_SIGN_TOOL() decode and encode an B<ISSUER_SIGN_TOOL>
structure. They otherwise follow the conventions of other ASN.1 functions such as d2i_X509().
=head1 HISTORY
The ISSUER_SIGN_TOOL_up_ref(), ISSUER_SIGN_TOOL_lock() and ISSUER_SIGN_TOOL_unlock()
functions were added in OpenSSL 3.0.
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/NCONF_new_with_libctx.pod
+59
View File
@@ -0,0 +1,59 @@
=pod
=head1 NAME
NCONF_new_with_libctx, NCONF_new, NCONF_free, NCONF_default, NCONF_load
- functionality to Load and parse configuration files manually
=head1 SYNOPSIS
#include <openssl/conf.h>
CONF *NCONF_new_with_libctx(OPENSSL_CTX *libctx, CONF_METHOD *meth);
CONF *NCONF_new(CONF_METHOD *meth);
void NCONF_free(CONF *conf);
CONF_METHOD *NCONF_default(void);
int NCONF_load(CONF *conf, const char *file, long *eline);
=head1 DESCRIPTION
NCONF_new_with_libctx() creates a new CONF object in heap memory and assigns to
it a context I<libctx> that can be used during loading. If the method table
I<meth> is set to NULL then the default value of NCONF_default() is used.
NCONF_new() is similar to NCONF_new_with_libctx() but sets the I<libctx> to NULL.
NCONF_free() frees the data associated with I<conf> and then frees the I<conf>
object.
NCONF_load() parses the file named I<filename> and adds the values found to
I<conf>. If an error occurs I<file> and I<eline> list the file and line that
the load failed on if they are not NULL.
NCONF_default() gets the default method table for processing a configuration file.
=head1 RETURN VALUES
NCONF_load() returns 1 on success or 0 on error.
NCONF_new_with_libctx() and NCONF_new() return a newly created I<CONF> object
or NULL if an error occurs.
=head1 SEE ALSO
L<CONF_modules_load_file(3)>,
=head1 HISTORY
NCONF_new_with_libctx() was added in OpenSSL 3.0.
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OCSP_response_status.pod
+44 -28
View File
@@ -4,8 +4,9 @@
OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create,
OCSP_RESPONSE_free, OCSP_RESPID_set_by_name,
OCSP_RESPID_set_by_key, OCSP_RESPID_match,
OCSP_basic_sign, OCSP_basic_sign_ctx - OCSP response functions
OCSP_RESPID_set_by_key_ex, OCSP_RESPID_set_by_key, OCSP_RESPID_match_ex,
OCSP_RESPID_match, OCSP_basic_sign, OCSP_basic_sign_ctx
- OCSP response functions
=head1 SYNOPSIS
@@ -17,7 +18,11 @@ OCSP_basic_sign, OCSP_basic_sign_ctx - OCSP response functions
void OCSP_RESPONSE_free(OCSP_RESPONSE *resp);
int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert);
int OCSP_RESPID_set_by_key_ex(OCSP_RESPID *respid, X509 *cert,
OPENSSL_CTX *libctx, const char *propq);
int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert);
int OCSP_RESPID_match_ex(OCSP_RESPID *respid, X509 *cert, OPENSSL_CTX *libctx,
const char *propq);
int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert);
int OCSP_basic_sign(OCSP_BASICRESP *brsp, X509 *signer, EVP_PKEY *key,
@@ -28,49 +33,60 @@ OCSP_basic_sign, OCSP_basic_sign_ctx - OCSP response functions
=head1 DESCRIPTION
OCSP_response_status() returns the OCSP response status of B<resp>. It returns
one of the values: B<OCSP_RESPONSE_STATUS_SUCCESSFUL>,
B<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>,
B<OCSP_RESPONSE_STATUS_INTERNALERROR>, B<OCSP_RESPONSE_STATUS_TRYLATER>
B<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or B<OCSP_RESPONSE_STATUS_UNAUTHORIZED>.
OCSP_response_status() returns the OCSP response status of I<resp>. It returns
one of the values: I<OCSP_RESPONSE_STATUS_SUCCESSFUL>,
I<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>,
I<OCSP_RESPONSE_STATUS_INTERNALERROR>, I<OCSP_RESPONSE_STATUS_TRYLATER>
I<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or I<OCSP_RESPONSE_STATUS_UNAUTHORIZED>.
OCSP_response_get1_basic() decodes and returns the B<OCSP_BASICRESP> structure
contained in B<resp>.
OCSP_response_get1_basic() decodes and returns the I<OCSP_BASICRESP> structure
contained in I<resp>.
OCSP_response_create() creates and returns an B<OCSP_RESPONSE> structure for
B<status> and optionally including basic response B<bs>.
OCSP_response_create() creates and returns an I<OCSP_RESPONSE> structure for
I<status> and optionally including basic response I<bs>.
OCSP_RESPONSE_free() frees up OCSP response B<resp>.
OCSP_RESPONSE_free() frees up OCSP response I<resp>.
OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the
subject name in the supplied X509 certificate B<cert> for the OCSP responder.
subject name in the supplied X509 certificate I<cert> for the OCSP responder.
OCSP_RESPID_set_by_key() sets the key of the OCSP_RESPID to be the same as the
key in the supplied X509 certificate B<cert> for the OCSP responder. The key is
stored as a SHA1 hash.
OCSP_RESPID_set_by_key_ex() sets the key of the OCSP_RESPID to be the same as the
key in the supplied X509 certificate I<cert> for the OCSP responder. The key is
stored as a SHA1 hash. To calculate the hash the SHA1 algorithm is fetched using
the library ctx I<libctx> and the property query string I<propq> (see
L<provider(7)/Fetching algorithms> for further information).
OCSP_RESPID_set_by_key() does the same as OCSP_RESPID_set_by_key_ex() except
that the default library context is used with an empty property query string.
Note that an OCSP_RESPID can only have one of the name, or the key set. Calling
OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing
setting.
OCSP_RESPID_match() tests whether the OCSP_RESPID given in B<respid> matches
with the X509 certificate B<cert>.
OCSP_RESPID_match_ex() tests whether the OCSP_RESPID given in I<respid> matches
with the X509 certificate I<cert> based on the SHA1 hash. To calculate the hash
the SHA1 algorithm is fetched using the library ctx I<libctx> and the property
query string I<propq> (see L<provider(7)/Fetching algorithms> for further
information).
OCSP_basic_sign() signs OCSP response B<brsp> using certificate B<signer>, private key
B<key>, digest B<dgst> and additional certificates B<certs>. If the B<flags> option
B<OCSP_NOCERTS> is set then no certificates will be included in the response. If the
B<flags> option B<OCSP_RESPID_KEY> is set then the responder is identified by key ID
rather than by name. OCSP_basic_sign_ctx() also signs OCSP response B<brsp> but
uses the parameters contained in digest context B<ctx>.
OCSP_RESPID_match() does the same as OCSP_RESPID_match_ex() except that the
default library context is used with an empty property query string.
OCSP_basic_sign() signs OCSP response I<brsp> using certificate I<signer>, private key
I<key>, digest I<dgst> and additional certificates I<certs>. If the I<flags> option
I<OCSP_NOCERTS> is set then no certificates will be included in the response. If the
I<flags> option I<OCSP_RESPID_KEY> is set then the responder is identified by key ID
rather than by name. OCSP_basic_sign_ctx() also signs OCSP response I<brsp> but
uses the parameters contained in digest context I<ctx>.
=head1 RETURN VALUES
OCSP_RESPONSE_status() returns a status value.
OCSP_response_get1_basic() returns an B<OCSP_BASICRESP> structure pointer or
B<NULL> if an error occurred.
OCSP_response_get1_basic() returns an I<OCSP_BASICRESP> structure pointer or
I<NULL> if an error occurred.
OCSP_response_create() returns an B<OCSP_RESPONSE> structure pointer or B<NULL>
OCSP_response_create() returns an I<OCSP_RESPONSE> structure pointer or I<NULL>
if an error occurred.
OCSP_RESPONSE_free() does not return a value.
@@ -85,7 +101,7 @@ or 0 otherwise.
=head1 NOTES
OCSP_response_get1_basic() is only called if the status of a response is
B<OCSP_RESPONSE_STATUS_SUCCESSFUL>.
I<OCSP_RESPONSE_STATUS_SUCCESSFUL>.
=head1 SEE ALSO
doc/man3/OPENSSL_CTX.pod
+9 -3
View File
@@ -2,7 +2,8 @@
=head1 NAME
OPENSSL_CTX, OPENSSL_CTX_new, OPENSSL_CTX_free - OpenSSL library context
OPENSSL_CTX, OPENSSL_CTX_new, OPENSSL_CTX_free, OPENSSL_CTX_load_config
- OpenSSL library context
=head1 SYNOPSIS
@@ -11,6 +12,7 @@ OPENSSL_CTX, OPENSSL_CTX_new, OPENSSL_CTX_free - OpenSSL library context
typedef struct openssl_ctx_st OPENSSL_CTX;
OPENSSL_CTX *OPENSSL_CTX_new(void);
int OPENSSL_CTX_load_config(OPENSSL_CTX *ctx, const char *config_file);
void OPENSSL_CTX_free(OPENSSL_CTX *ctx);
=head1 DESCRIPTION
@@ -26,6 +28,10 @@ multi-threaded applications to properly clean up thread local resources before
the OPENSSL_CTX is freed.
See L<OPENSSL_thread_stop_ex(3)> for more information.
OPENSSL_CTX_load_config() loads a configuration file using the given C<ctx>.
This can be used to associate a libctx with providers that are loaded from
a configuration.
OPENSSL_CTX_free() frees the given C<ctx>.
=head1 RETURN VALUES
@@ -37,12 +43,12 @@ OPENSSL_CTX_free() doesn't return any value.
=head1 HISTORY
OPENSSL_CTX, OPENSSL_CTX_new() and OPENSSL_CTX_free()
OPENSSL_CTX, OPENSSL_CTX_new(), OPENSSL_CTX_load_config() and OPENSSL_CTX_free()
were added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/OSSL_CMP_CTX_new.pod
+95 -71
View File
@@ -11,15 +11,14 @@ OSSL_CMP_CTX_set_log_cb,
OSSL_CMP_CTX_set_log_verbosity,
OSSL_CMP_CTX_print_errors,
OSSL_CMP_CTX_set1_serverPath,
OSSL_CMP_CTX_set1_serverName,
OSSL_CMP_CTX_set1_server,
OSSL_CMP_CTX_set_serverPort,
OSSL_CMP_CTX_set1_proxyName,
OSSL_CMP_CTX_set_proxyPort,
OSSL_CMP_DEFAULT_PORT,
OSSL_CMP_CTX_set1_proxy,
OSSL_CMP_CTX_set1_no_proxy,
OSSL_CMP_CTX_set_http_cb,
OSSL_CMP_CTX_set_http_cb_arg,
OSSL_CMP_CTX_get_http_cb_arg,
OSSL_cmp_transfer_cb_t,
OSSL_CMP_transfer_cb_t,
OSSL_CMP_CTX_set_transfer_cb,
OSSL_CMP_CTX_set_transfer_cb_arg,
OSSL_CMP_CTX_get_transfer_cb_arg,
@@ -47,7 +46,7 @@ OSSL_CMP_CTX_push0_policy,
OSSL_CMP_CTX_set1_oldCert,
OSSL_CMP_CTX_set1_p10CSR,
OSSL_CMP_CTX_push0_genm_ITAV,
OSSL_cmp_certConf_cb_t,
OSSL_CMP_certConf_cb_t,
OSSL_CMP_CTX_set_certConf_cb,
OSSL_CMP_CTX_set_certConf_cb_arg,
OSSL_CMP_CTX_get_certConf_cb_arg,
@@ -72,24 +71,23 @@ OSSL_CMP_CTX_set1_senderNonce
int OSSL_CMP_CTX_get_option(const OSSL_CMP_CTX *ctx, int opt);
/* logging and error reporting: */
int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_log_cb_t cb);
int OSSL_CMP_CTX_set_log_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_log_cb_t cb);
#define OSSL_CMP_CTX_set_log_verbosity(ctx, level)
void OSSL_CMP_CTX_print_errors(OSSL_CMP_CTX *ctx);
/* message transfer: */
int OSSL_CMP_CTX_set1_serverPath(OSSL_CMP_CTX *ctx, const char *path);
int OSSL_CMP_CTX_set1_serverName(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set1_server(OSSL_CMP_CTX *ctx, const char *address);
int OSSL_CMP_CTX_set_serverPort(OSSL_CMP_CTX *ctx, int port);
int OSSL_CMP_CTX_set1_proxyName(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set_proxyPort(OSSL_CMP_CTX *ctx, int port);
#define OSSL_CMP_DEFAULT_PORT 80
int OSSL_CMP_CTX_set1_proxy(OSSL_CMP_CTX *ctx, const char *name);
int OSSL_CMP_CTX_set1_no_proxy(OSSL_CMP_CTX *ctx, const char *names);
int OSSL_CMP_CTX_set_http_cb(OSSL_CMP_CTX *ctx, HTTP_bio_cb_t cb);
int OSSL_CMP_CTX_set_http_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_http_cb_arg(const OSSL_CMP_CTX *ctx);
typedef OSSL_CMP_MSG *(*OSSL_cmp_transfer_cb_t)(OSSL_CMP_CTX *ctx,
typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t)(OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req);
int OSSL_CMP_CTX_set_transfer_cb(OSSL_CMP_CTX *ctx,
OSSL_cmp_transfer_cb_t cb);
OSSL_CMP_transfer_cb_t cb);
int OSSL_CMP_CTX_set_transfer_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_transfer_cb_arg(const OSSL_CMP_CTX *ctx);
@@ -134,9 +132,9 @@ OSSL_CMP_CTX_set1_senderNonce
int OSSL_CMP_CTX_push0_genm_ITAV(OSSL_CMP_CTX *ctx, OSSL_CMP_ITAV *itav);
/* certificate confirmation: */
typedef int (*OSSL_cmp_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert,
typedef int (*OSSL_CMP_certConf_cb_t)(OSSL_CMP_CTX *ctx, X509 *cert,
int fail_info, const char **txt);
int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_cmp_certConf_cb_t cb);
int OSSL_CMP_CTX_set_certConf_cb(OSSL_CMP_CTX *ctx, OSSL_CMP_certConf_cb_t cb);
int OSSL_CMP_CTX_set_certConf_cb_arg(OSSL_CMP_CTX *ctx, void *arg);
void *OSSL_CMP_CTX_get_certConf_cb_arg(const OSSL_CMP_CTX *ctx);
@@ -149,7 +147,7 @@ OSSL_CMP_CTX_set1_senderNonce
STACK_OF(X509) *OSSL_CMP_CTX_get1_caPubs(const OSSL_CMP_CTX *ctx);
STACK_OF(X509) *OSSL_CMP_CTX_get1_extraCertsIn(const OSSL_CMP_CTX *ctx);
/* for test purposes only: */
/* for testing and debugging purposes: */
int OSSL_CMP_CTX_set1_transactionID(OSSL_CMP_CTX *ctx,
const ASN1_OCTET_STRING *id);
int OSSL_CMP_CTX_set1_senderNonce(OSSL_CMP_CTX *ctx,
@@ -172,7 +170,7 @@ from the last executed transaction.
All other field values (i.e., CMP options) are retained for potential re-use.
OSSL_CMP_CTX_set_option() sets the given value for the given option
(e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) in the given OSSL_CMP_CTX structure.
(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) in the given OSSL_CMP_CTX structure.
The following options can be set:
@@ -184,17 +182,17 @@ The following options can be set:
due to errors, warnings, general info, debugging, etc.
Default is OSSL_CMP_LOG_INFO. See also L<OSSL_CMP_log_open(3)>.
=item B<OSSL_CMP_OPT_MSGTIMEOUT>
=item B<OSSL_CMP_OPT_MSG_TIMEOUT>
Number of seconds (or 0 for infinite) a CMP message round trip is
allowed to take before a timeout error is returned. Default is 120.
=item B<OSSL_CMP_OPT_TOTALTIMEOUT>
=item B<OSSL_CMP_OPT_TOTAL_TIMEOUT>
Maximum total number of seconds an enrollment (including polling)
may take. Default is 0 (infinite).
=item B<OSSL_CMP_OPT_VALIDITYDAYS>
=item B<OSSL_CMP_OPT_VALIDITY_DAYS>
Number of days new certificates are asked to be valid for.
@@ -211,7 +209,7 @@ The following options can be set:
Demand that the given policies are flagged as critical.
=item B<OSSL_CMP_OPT_POPOMETHOD>
=item B<OSSL_CMP_OPT_POPO_METHOD>
Select the proof of possession method to use. Possible values are:
@@ -239,7 +237,7 @@ The following options can be set:
OSSL_CMP_OPT_MAC_ALGNID
The MAC algorithm NID to be used in RFC 4210's MSG_MAC_ALG,
if applicable used for message protection.
if applicable used for message protection.
Default is HMAC-SHA1 as per RFC 4210.
=item B<OSSL_CMP_OPT_REVOCATION_REASON>
@@ -247,14 +245,14 @@ The following options can be set:
The reason code to be included in a Revocation Request (RR);
values: 0..10 (RFC 5210, 5.3.1) or -1 for none, which is the default.
=item B<OSSL_CMP_OPT_IMPLICITCONFIRM>
=item B<OSSL_CMP_OPT_IMPLICIT_CONFIRM>
Request server to enable implicit confirm mode, where the client
does not need to send confirmation upon receiving the
certificate. If the server does not enable implicit confirmation
in the return message, then confirmation is sent anyway.
=item B<OSSL_CMP_OPT_DISABLECONFIRM>
=item B<OSSL_CMP_OPT_DISABLE_CONFIRM>
Do not confirm enrolled certificates, to cope with broken servers
not supporting implicit confirmation correctly.
@@ -290,7 +288,7 @@ RFC 4210.
=back
OSSL_CMP_CTX_get_option() reads the current value of the given option
(e.g., OSSL_CMP_OPT_IMPLICITCONFIRM) from the given OSSL_CMP_CTX structure.
(e.g., OSSL_CMP_OPT_IMPLICIT_CONFIRM) from the given OSSL_CMP_CTX structure.
OSSL_CMP_CTX_set_log_cb() sets in B<ctx> the callback function C<cb>
for handling error queue entries and logging messages.
@@ -306,19 +304,30 @@ It is similar to B<ERR_print_errors_cb()> but uses the CMP log callback function
if set in the C<ctx> for uniformity with CMP logging if given. Otherwise it uses
B<ERR_print_errors(3)> to print to STDERR (unless OPENSSL_NO_STDIO is defined).
OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host.
OSSL_CMP_CTX_set1_serverPath() sets the HTTP path of the CMP server on the host,
also known as "CMP alias".
The default is "/".
OSSL_CMP_CTX_set1_serverName() sets the given server Address (as IP or name)
in the given OSSL_CMP_CTX structure.
OSSL_CMP_CTX_set1_server() sets the given server B<address>
(which may be a hostname or IP address or NULL) in the given B<ctx>.
OSSL_CMP_CTX_set_serverPort() sets the port of the CMP server to connect to.
Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly.
If not used or the B<port> argument is 0
the default port applies, which is 80 for HTTP and 443 for HTTPS.
OSSL_CMP_CTX_set1_proxyName() sets the hostname of the HTTP proxy to be used
for connecting to the CA server.
OSSL_CMP_CTX_set1_proxy() sets the HTTP proxy to be used for connecting to
the given CMP server unless overruled by any "no_proxy" settings (see below).
If TLS is not used this defaults to the value of
the environment variable B<http_proxy> if set, else B<HTTP_PROXY>.
Otherwise defaults to the value of B<https_proxy> if set, else B<HTTPS_PROXY>.
An empty proxy string specifies not to use a proxy.
Else the format is I<[http[s]://]address[:port][/path]>,
where any path given is ignored.
The default port number is 80, or 443 in case "https:" is given.
OSSL_CMP_CTX_set_proxyPort() sets the port of the HTTP proxy.
Port defaults to OSSL_CMP_DEFAULT_PORT = 80 if not set explicitly.
OSSL_CMP_CTX_set1_no_proxy() sets the list of server hostnames not to use
an HTTP proxy for. The names may be separated by commas and/or whitespace.
Defaults to the environment variable B<no_proxy> if set, else B<NO_PROXY>.
OSSL_CMP_CTX_set_http_cb() sets the optional BIO connect/disconnect callback
function, which has the prototype
@@ -350,19 +359,18 @@ OSSL_CMP_CTX_set_http_cb_arg() or NULL if unset.
OSSL_CMP_CTX_set_transfer_cb() sets the message transfer callback function,
which has the type
typedef OSSL_CMP_MSG *(*OSSL_cmp_transfer_cb_t) (OSSL_CMP_CTX *ctx,
typedef OSSL_CMP_MSG *(*OSSL_CMP_transfer_cb_t) (OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req);
Returns 1 on success, 0 on error.
Default is NULL, which implies the use of L<OSSL_CMP_MSG_http_perform(3)>.
The callback should send the CMP request message it obtains via the B<req>
parameter and on success return the response.
parameter and on success return the response, else it must return NULL.
The transfer callback may make use of a custom defined argument stored in
the ctx by means of OSSL_CMP_CTX_set_transfer_cb_arg(), which may be retrieved
again through OSSL_CMP_CTX_get_transfer_cb_arg().
OSSL_CMP_CTX_set_transfer_cb_arg() sets an argument, respectively a pointer to a
structure containing arguments, optionally to be used by the transfer callback.
B<arg> is not consumed, and it must therefore explicitly be freed when not
@@ -372,9 +380,9 @@ OSSL_CMP_CTX_get_transfer_cb_arg() gets the argument, respectively the pointer
to a structure containing arguments, previously set by
OSSL_CMP_CTX_set_transfer_cb_arg() or NULL if unset.
OSSL_CMP_CTX_set1_srvCert() pins the server certificate to be directly trusted
(even if it is expired) for verifying response messages.
The cert pointer is not consumed. It may be NULL to clear the entry.
OSSL_CMP_CTX_set1_srvCert() pins the given server certificate B<srvCert>
directly trusts it (even if it is expired) for verifying response messages.
The B<cert> argument may be NULL to clear the entry.
OSSL_CMP_CTX_set1_expected_sender() sets the Distinguished Name (DN) expected to
be given in the sender response for messages protected with MSG_SIG_ALG. This
@@ -384,8 +392,7 @@ identify the server certificate.
This can be used to ensure that only a particular entity is accepted to act as
CMP server, and attackers are not able to use arbitrary certificates of a
trusted PKI hierarchy to fraudulently pose as server.
This defaults to the subject DN of the certificate set via
OSSL_CMP_CTX_set1_srvCert(), if any.
This defaults to the subject of the B<srvCert>, if any.
OSSL_CMP_CTX_set0_trustedStore() sets the X509_STORE type certificate store
containing trusted (root) CA certificates. The certificate store may also hold
@@ -404,32 +411,52 @@ The reference counts of those certificates handled successfully are increased.
OSSL_CMP_CTX_get0_untrusted_certs(OSSL_CMP_CTX *ctx) returns a pointer to the
list of untrusted certs, which my be empty if unset.
OSSL_CMP_CTX_set1_clCert() sets the client certificate in the given
OSSL_CMP_CTX structure. The client certificate will then be used by the
functions to set the "sender" field for outgoing messages and it will be
included in the extraCerts field.
OSSL_CMP_CTX_set1_clCert() sets the client certificate in the given B<ctx>.
The public key of this B<clCert> must correspond to
the private key set via B<OSSL_CMP_CTX_set1_pkey()>.
When using signature-based protection of CMP request messages
this "protection certificate" will be included first in the extraCerts field.
The subject of this B<clCert> will be used as the "sender" field
of outgoing CMP messages, with the fallback being
the B<subjectName> set via B<OSSL_CMP_CTX_set1_subjectName()>.
The B<cert> argument may be NULL to clear the entry.
OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to the client
certificate set with B<OSSL_CMP_CTX_set1_clCert()> in the given CMP context.
Used to create the protection in case of MSG_SIG_ALG.
OSSL_CMP_CTX_set1_pkey() sets the private key corresponding to
the client certificate B<clCert> set via B<OSSL_CMP_CTX_set1_clCert()>.
This key is used create signature-based protection (protectionAlg = MSG_SIG_ALG)
of outgoing messages
unless a PBM secret has been set via B<OSSL_CMP_CTX_set1_secretValue()>.
The B<pkey> argument may be NULL to clear the entry.
OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue in the given
B<ctx> or clears it if the B<ref> argument is NULL.
OSSL_CMP_CTX_set1_secretValue() sets the byte string B<sec> with length B<len>
as PBM secret in the given B<ctx> or clears it if the B<sec> argument is NULL.
If present, this secret is used to create PBM-based protection of outgoing
messages and to verify any PBM-based protection of incoming messages
(protectionAlg = MSG_MAC_ALG). PBM stands for Password-Based MAC.
PBM-based protection takes precedence over signature-based protection.
OSSL_CMP_CTX_set1_secretValue() sets the B<sec> with the length B<len> in the
given B<ctx> or clears it if the B<sec> argument is NULL.
OSSL_CMP_CTX_set1_referenceValue() sets the given referenceValue B<ref> with
length B<len> in the given B<ctx> or clears it if the B<ref> argument is NULL.
According to RFC 4210 section 5.1.1, if no value for the "sender" field in
CMP message headers can be determined (i.e., no B<clCert> and no B<subjectName>
is given) then the "sender" field will contain the NULL-DN
and the senderKID field of the CMP message header must be set.
When signature-based protection is used the senderKID will be set to
the subjectKeyIdentifier of the <clCert> as far as present.
If not present or when PBM-based protection is used
the B<ref> value is taken as the fallback value for the senderKID.
OSSL_CMP_CTX_set1_recipient() sets the recipient name that will be used in the
PKIHeader of a request message, i.e. the X509 name of the (CA) server.
Setting is overruled by subject of srvCert if set.
If neither srvCert nor recipient are set, the recipient of the PKI message is
Setting is overruled by subject of B<srvCert> if set.
If neither B<srvCert> nor recipient are set, the recipient of the PKI message is
determined in the following order: issuer, issuer of old cert (oldCert),
issuer of client cert (clCert), else NULL-DN.
issuer of client cert (B<clCert>), else NULL-DN.
When a response is received, its sender must match the recipient of the request.
OSSL_CMP_CTX_push0_geninfo_ITAV() adds B<itav> to the stack in the B<ctx> to be
added to the GeneralInfo field of the CMP PKIMessage header of a request
message sent with this context. Consumes the pointer to B<itav>.
message sent with this context.
OSSL_CMP_CTX_set1_extraCertsOut() sets the stack of extraCerts that will be
sent to remote.
@@ -450,24 +477,22 @@ will be set in the CertTemplate, i.e., the X509 name of the CA server.
OSSL_CMP_CTX_set1_subjectName() sets the subject DN that will be used in
the CertTemplate structure when requesting a new cert. For Key Update Requests
(KUR), it defaults to the subject DN of the reference certificate,
(KUR), it defaults to the subject DN of the B<reference certificate>,
see B<OSSL_CMP_CTX_set1_oldCert()>. This default is used for Initialization
Requests (IR) and Certification Requests (CR) only if no SANs are set.
If clCert is not set (e.g. in case of IR with MSG_MAC_ALG), the subject DN
is also used as sender of the PKI message.
The B<subjectName> is also used as the "sender" field for outgoing CMP messages
if no B<clCert> has been set (e.g., in case requests are protected using PBM).
OSSL_CMP_CTX_push1_subjectAltName() adds the given X509 name to the list of
alternate names on the certificate template request. This cannot be used if
any Subject Alternative Name extension is set via
OSSL_CMP_CTX_set0_reqExtensions().
By default, unless OSSL_CMP_OPT_SUBJECTALTNAME_NODEFAULT has been set,
the Subject Alternative Names are copied from the reference certificate,
see OSSL_CMP_CTX_set1_oldCert().
the Subject Alternative Names are copied from the B<reference certificate>,
see B<OSSL_CMP_CTX_set1_oldCert()>.
If set and the subject DN is not set with OSSL_CMP_CTX_set1_subjectName(), then
the certificate template of an IR and CR will not be filled with the default
subject DN from the reference certificate (see OSSL_CMP_CTX_set1_oldCert().
subject DN from the B<reference certificate>.
If a subject DN is desired it needs to be set explicitly with
OSSL_CMP_CTX_set1_subjectName().
@@ -483,7 +508,7 @@ to the X509_EXTENSIONS of the requested certificate template.
OSSL_CMP_CTX_set1_oldCert() sets the old certificate to be updated in
Key Update Requests (KUR) or to be revoked in Revocation Requests (RR).
It must be given for RR, else it defaults to B<clCert>.
The reference certificate determined in this way, if any, is also used for
The B<reference certificate> determined in this way, if any, is also used for
deriving default subject DN and Subject Alternative Names for IR, CR, and KUR.
Its issuer, if any, is used as default recipient in the CMP message header.
@@ -491,13 +516,12 @@ OSSL_CMP_CTX_set1_p10CSR() sets the PKCS#10 CSR to be used in P10CR.
OSSL_CMP_CTX_push0_genm_ITAV() adds B<itav> to the stack in the B<ctx> which
will be the body of a General Message sent with this context.
Consumes the pointer to B<itav>.
OSSL_CMP_CTX_set_certConf_cb() sets the callback used for evaluating the newly
enrolled certificate before the library sends, depending on its result,
a positive or negative certConf message to the server. The callback has type
typedef int (*OSSL_cmp_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert,
typedef int (*OSSL_CMP_certConf_cb_t) (OSSL_CMP_CTX *ctx, X509 *cert,
int fail_info, const char **txt);
and should inspect the certificate it obtains via the B<cert> parameter and may
@@ -587,7 +611,7 @@ All other functions return 1 on success, 0 on error.
The following code does an Initialization Request:
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, opt_serverName);
OSSL_CMP_CTX_set1_server(cmp_ctx, address);
OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
@@ -599,7 +623,7 @@ The following code does an Initialization Request using an
external identity certificate (RFC 4210, Appendix E.7):
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
OSSL_CMP_CTX_set1_server(cmp_ctx, sname);
OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
@@ -614,7 +638,7 @@ which is trusted by the current CA the code will connect to.
The following code does a Key Update Request:
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
OSSL_CMP_CTX_set1_server(cmp_ctx, url);
OSSL_CMP_CTX_set1_pkey(cmp_ctx, pkey);
OSSL_CMP_CTX_set0_newPkey(cmp_ctx, new_pkey, 1);
OSSL_CMP_CTX_set1_clCert(cmp_ctx, cl_cert);
@@ -627,7 +651,7 @@ including, as an example, the id-it-signKeyPairTypes OID and prints info on
the General Response contents.
cmp_ctx = OSSL_CMP_CTX_new();
OSSL_CMP_CTX_set1_serverName(cmp_ctx, sname);
OSSL_CMP_CTX_set1_server(cmp_ctx, sname);
OSSL_CMP_CTX_set1_referenceValue(cmp_ctx, ref, ref_len);
OSSL_CMP_CTX_set1_secretValue(cmp_ctx, sec, sec_len);
doc/man3/OSSL_CMP_CTX_snprint_PKIStatus.pod
-46
View File
@@ -1,46 +0,0 @@
=pod
=head1 NAME
OSSL_CMP_CTX_snprint_PKIStatus
- function(s) for managing the CMP PKIStatus
=head1 SYNOPSIS
#include <openssl/cmp.h>
char *OSSL_CMP_CTX_snprint_PKIStatus(OSSL_CMP_CTX *ctx, char *buf, int bufsize);
=head1 DESCRIPTION
This is the PKIStatus API for using CMP (Certificate Management Protocol) with
OpenSSL.
OSSL_CMP_CTX_snprint_PKIStatus() takes the PKIStatusInfo components contained
in the given CMP context and places a human-readable string created from them
in the given buffer, with the given maximal length.
On success it returns a copy of the buffer pointer containing the string.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
=head1 RETURN VALUES
OSSL_CMP_CTX_snprint_PKIStatus()
returns the intended pointer value as described above or NULL on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_CMP_MSG_get0_header.pod
+16 -2
View File
@@ -2,7 +2,9 @@
=head1 NAME
OSSL_CMP_MSG_get0_header
OSSL_CMP_MSG_get0_header,
d2i_OSSL_CMP_MSG_bio,
i2d_OSSL_CMP_MSG_bio
- function(s) manipulating CMP messages
=head1 SYNOPSIS
@@ -10,20 +12,32 @@ OSSL_CMP_MSG_get0_header
#include <openssl/cmp.h>
OSSL_CMP_PKIHEADER *OSSL_CMP_MSG_get0_header(const OSSL_CMP_MSG *msg);
OSSL_CMP_MSG *d2i_OSSL_CMP_MSG_bio(BIO *bio, OSSL_CMP_MSG **msg);
int i2d_OSSL_CMP_MSG_bio(BIO *bio, const OSSL_CMP_MSG *msg);
=head1 DESCRIPTION
OSSL_CMP_MSG_get0_header returns the header of the given CMP message.
d2i_OSSL_CMP_MSG_bio parses an ASN.1-encoded OSSL_CMP_MSG from the BIO I<bio>.
It assigns a pointer to the new structure to I<*msg> if I<msg> is not NULL.
i2d_OSSL_CMP_MSG_bio writes the OSSL_CMP_MSG I<msg> in ASN.1 encoding
to BIO I<bio>.
=head1 NOTES
CMP is defined in RFC 4210.
=head1 RETURN VALUES
CMP_MSG_get0_header() returns the intended pointer value as described above
OSSL_CMP_MSG_get0_header() returns the intended pointer value as described above
or NULL if the respective entry does not exist and on error.
d2i_OSSL_CMP_MSG_bio() returns the parsed message or NULL on error.
i2d_OSSL_CMP_MSG_bio() returns 1 on success or 0 on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
doc/man3/OSSL_CMP_MSG_http_perform.pod
+60
View File
@@ -0,0 +1,60 @@
=pod
=head1 NAME
OSSL_CMP_MSG_http_perform
- client-side HTTP(S) transfer of a CMP request-response pair
=head1 SYNOPSIS
#include <openssl/cmp.h>
OSSL_CMP_MSG *OSSL_CMP_MSG_http_perform(OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *req);
=head1 DESCRIPTION
OSSL_CMP_MSG_http_perform() sends the given PKIMessage B<req>
to the CMP server specified in B<ctx> via L<OSSL_CMP_CTX_set1_server(3)>
and optionally L<OSSL_CMP_CTX_set_serverPort(3)>, using
any "CMP alias" optionally specified via L<OSSL_CMP_CTX_set1_serverPath(3)>.
The default port is 80 for HTTP and 443 for HTTPS; the default path is "/".
On success the function returns the server's response PKIMessage.
The function makes use of any HTTP callback function
set via L<OSSL_CMP_CTX_set_http_cb(3)>.
It respects any timeout value set via L<OSSL_CMP_CTX_set_option(3)>
with an B<OSSL_CMP_OPT_MSG_TIMEOUT> argument.
It also respects any HTTP(S) proxy options set via L<OSSL_CMP_CTX_set1_proxy(3)>
and L<OSSL_CMP_CTX_set1_no_proxy(3)> and the respective environment variables.
Proxying plain HTTP is supported directly,
while using a proxy for HTTPS connections requires a suitable callback function
such as L<OSSL_HTTP_proxy_connect(3)>.
=head1 NOTES
CMP is defined in RFC 4210.
HTTP transfer for CMP is defined in RFC 6712.
=head1 RETURN VALUES
OSSL_CMP_MSG_http_perform() returns a CMP message on success, else NULL.
=head1 SEE ALSO
L<OSSL_CMP_CTX_new(3)>, L<OSSL_HTTP_proxy_connect(3)>.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_CMP_SRV_CTX_new.pod
+162
View File
@@ -0,0 +1,162 @@
=pod
=head1 NAME
OSSL_CMP_SRV_process_request,
OSSL_CMP_CTX_server_perform,
OSSL_CMP_SRV_CTX_new,
OSSL_CMP_SRV_CTX_free,
OSSL_CMP_SRV_cert_request_cb_t,
OSSL_CMP_SRV_rr_cb_t,
OSSL_CMP_SRV_certConf_cb_t,
OSSL_CMP_SRV_genm_cb_t,
OSSL_CMP_SRV_error_cb_t,
OSSL_CMP_SRV_pollReq_cb_t,
OSSL_CMP_SRV_CTX_init,
OSSL_CMP_SRV_CTX_get0_cmp_ctx,
OSSL_CMP_SRV_CTX_get0_custom_ctx,
OSSL_CMP_SRV_CTX_set_send_unprotected_errors,
OSSL_CMP_SRV_CTX_set_accept_unprotected,
OSSL_CMP_SRV_CTX_set_accept_raverified,
OSSL_CMP_SRV_CTX_set_grant_implicit_confirm
- generic functions to set up and control a CMP server
=head1 SYNOPSIS
#include <openssl/cmp.h>
OSSL_CMP_MSG *OSSL_CMP_SRV_process_request(OSSL_CMP_SRV_CTX *srv_ctx,
const OSSL_CMP_MSG *req);
OSSL_CMP_MSG *OSSL_CMP_CTX_server_perform(OSSL_CMP_CTX *client_ctx,
const OSSL_CMP_MSG *req);
OSSL_CMP_SRV_CTX *OSSL_CMP_SRV_CTX_new(void);
void OSSL_CMP_SRV_CTX_free(OSSL_CMP_SRV_CTX *srv_ctx);
typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_cert_request_cb_t)(
OSSL_CMP_SRV_CTX *srv_ctx,
const OSSL_CMP_MSG *req,
int certReqId,
const OSSL_CRMF_MSG *crm,
const X509_REQ *p10cr,
X509 **certOut,
STACK_OF(X509) **chainOut,
STACK_OF(X509) **caPubs);
typedef OSSL_CMP_PKISI *(*OSSL_CMP_SRV_rr_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
const OSSL_CMP_MSG *req,
const X509_NAME *issuer,
const ASN1_INTEGER *serial);
typedef int (*OSSL_CMP_SRV_genm_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
const OSSL_CMP_MSG *req,
STACK_OF(OSSL_CMP_ITAV) *in,
STACK_OF(OSSL_CMP_ITAV) **out);
typedef void (*OSSL_CMP_SRV_error_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
const OSSL_CMP_MSG *req,
const OSSL_CMP_PKISI *statusInfo,
const ASN1_INTEGER *errorCode,
const OSSL_CMP_PKIFREETEXT *errorDetails);
typedef int (*OSSL_CMP_SRV_certConf_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
const OSSL_CMP_MSG *req,
int certReqId,
const ASN1_OCTET_STRING *certHash,
const OSSL_CMP_PKISI *si);
typedef int (*OSSL_CMP_SRV_pollReq_cb_t)(OSSL_CMP_SRV_CTX *srv_ctx,
const OSSL_CMP_MSG *req,
int certReqId,
OSSL_CMP_MSG **certReq,
int64_t *check_after);
int OSSL_CMP_SRV_CTX_init(OSSL_CMP_SRV_CTX *srv_ctx, void *custom_ctx,
OSSL_CMP_SRV_cert_request_cb_t process_cert_request,
OSSL_CMP_SRV_rr_cb_t process_rr,
OSSL_CMP_SRV_genm_cb_t process_genm,
OSSL_CMP_SRV_error_cb_t process_error,
OSSL_CMP_SRV_certConf_cb_t process_certConf,
OSSL_CMP_SRV_pollReq_cb_t process_pollReq);
OSSL_CMP_CTX *OSSL_CMP_SRV_CTX_get0_cmp_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);
void *OSSL_CMP_SRV_CTX_get0_custom_ctx(const OSSL_CMP_SRV_CTX *srv_ctx);
int OSSL_CMP_SRV_CTX_set_send_unprotected_errors(OSSL_CMP_SRV_CTX *srv_ctx,
int val);
int OSSL_CMP_SRV_CTX_set_accept_unprotected(OSSL_CMP_SRV_CTX *srv_ctx, int val);
int OSSL_CMP_SRV_CTX_set_accept_raverified(OSSL_CMP_SRV_CTX *srv_ctx, int val);
int OSSL_CMP_SRV_CTX_set_grant_implicit_confirm(OSSL_CMP_SRV_CTX *srv_ctx,
int val);
=head1 DESCRIPTION
OSSL_CMP_SRV_process_request() implements the generic aspects of a CMP server.
It does the typical generic checks on the given request message, calls
the respective callback function (if present) for more specific processing,
and then assembles a result message, which may be a CMP error message.
OSSL_CMP_CTX_server_perform() is an interface to
B<OSSL_CMP_SRV_process_request()> that can be used by a CMP client
in the same way as B<OSSL_CMP_MSG_http_perform()>.
The B<OSSL_CMP_SRV_CTX> must be set as B<transfer_cb_arg> of B<client_ctx>.
OSSL_CMP_SRV_CTX_new() creates and initializes an OSSL_CMP_SRV_CTX structure
and returns a pointer to it on success, NULL on error.
OSSL_CMP_SRV_CTX_free() deletes the given B<srv_ctx>.
OSSL_CMP_SRV_CTX_init() sets in the given B<srv_ctx> a custom server context
pointer as well as callback functions performing the specific processing of CMP
certificate requests, revocation requests, certificate confirmation requests,
general messages, error messages, and poll requests.
All arguments except B<srv_ctx> may be NULL.
If a callback for some message type is not given this means that the respective
type of CMP message is not supported by the server.
OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns the B<OSSL_CMP_CTX> from the B<srv_ctx>.
OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context from
B<srv_ctx> that has been set using B<OSSL_CMP_SRV_CTX_init>.
OSSL_CMP_SRV_CTX_set_send_unprotected_errors() enables sending error messages
and other forms of negative responses unprotected.
OSSL_CMP_SRV_CTX_set_accept_unprotected() enables acceptance of requests
without protection of with invalid protection.
OSSL_CMP_SRV_CTX_set_accept_raverified() enables acceptance of ir/cr/kur
messages with POPO 'RAVerified'.
OSSL_CMP_SRV_CTX_set_grant_implicit_confirm() enables granting implicit
confirmation of newly enrolled certificates if requested.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
So far the CMP server implementation is limited to one request per CMP message
(and consequently to at most one response component per CMP message).
=head1 RETURN VALUES
OSSL_CMP_SRV_CTX_new() returns a B<OSSL_CMP_SRV_CTX> structure on success,
NULL on error.
OSSL_CMP_SRV_CTX_free() does not return a value.
OSSL_CMP_SRV_CTX_get0_cmp_ctx() returns a B<OSSL_CMP_CTX> structure on success,
NULL on error.
OSSL_CMP_SRV_CTX_get0_custom_ctx() returns the custom server context
that has been set using B<OSSL_CMP_SRV_CTX_init>.
All other functions return 1 on success, 0 on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_CMP_STATUSINFO_new.pod
+66
View File
@@ -0,0 +1,66 @@
=pod
=head1 NAME
OSSL_CMP_STATUSINFO_new,
OSSL_CMP_snprint_PKIStatusInfo,
OSSL_CMP_CTX_snprint_PKIStatus
- function(s) for managing the CMP PKIStatus
=head1 SYNOPSIS
#include <openssl/cmp.h>
OSSL_CMP_PKISI *OSSL_CMP_STATUSINFO_new(int status, int fail_info,
const char *text);
char *OSSL_CMP_snprint_PKIStatusInfo(const OSSL_CMP_PKISI *statusInfo,
char *buf, size_t bufsize);
char *OSSL_CMP_CTX_snprint_PKIStatus(const OSSL_CMP_CTX *ctx, char *buf,
size_t bufsize);
=head1 DESCRIPTION
This is the PKIStatus API for using CMP (Certificate Management Protocol) with
OpenSSL.
OSSL_CMP_STATUSINFO_new() creates a new PKIStatusInfo structure
and fills in the given values.
It sets the status field to B<status>,
copies B<text> (unless it is NULL) to statusString,
and interprets B<fail_info> as bit pattern for the failInfo field.
OSSL_CMP_snprint_PKIStatusInfo() places a human-readable string
representing the given statusInfo
in the given buffer, with the given maximal length.
OSSL_CMP_CTX_snprint_PKIStatus() places a human-readable string
representing the PKIStatusInfo components of the CMP context B<ctx>
in the given buffer, with the given maximal length.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
=head1 RETURN VALUES
OSSL_CMP_STATUSINFO_new()
returns a pointer to the structure on success, or NULL on error.
OSSL_CMP_snprint_PKIStatusInfo() and
OSSL_CMP_CTX_snprint_PKIStatus()
return a copy of the buffer pointer containing the string or NULL on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_CMP_exec_IR_ses.pod
+172
View File
@@ -0,0 +1,172 @@
=pod
=head1 NAME
OSSL_CMP_exec_IR_ses,
OSSL_CMP_exec_CR_ses,
OSSL_CMP_exec_P10CR_ses,
OSSL_CMP_exec_KUR_ses,
OSSL_CMP_IR,
OSSL_CMP_CR,
OSSL_CMP_P10CR,
OSSL_CMP_KUR,
OSSL_CMP_try_certreq,
OSSL_CMP_exec_RR_ses,
OSSL_CMP_exec_GENM_ses,
OSSL_CMP_certConf_cb
- functions implementing CMP client transactions
=head1 SYNOPSIS
#include <openssl/cmp.h>
X509 *OSSL_CMP_exec_IR_ses(OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_exec_CR_ses(OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_exec_P10CR_ses(OSSL_CMP_CTX *ctx);
X509 *OSSL_CMP_exec_KUR_ses(OSSL_CMP_CTX *ctx);
#define OSSL_CMP_IR
#define OSSL_CMP_CR
#define OSSL_CMP_P10CR
#define OSSL_CMP_KUR
int OSSL_CMP_try_certreq(OSSL_CMP_CTX *ctx, int req_type, int *checkAfter);
int OSSL_CMP_certConf_cb(OSSL_CMP_CTX *ctx, X509 *cert, int fail_info,
const char **text);
X509 *OSSL_CMP_exec_RR_ses(OSSL_CMP_CTX *ctx);
STACK_OF(OSSL_CMP_ITAV) *OSSL_CMP_exec_GENM_ses(OSSL_CMP_CTX *ctx);
=head1 DESCRIPTION
This is the OpenSSL API for doing CMP (Certificate Management Protocol)
client-server transactions, i.e., sequences of CMP requests and responses.
All functions take a populated OSSL_CMP_CTX structure as their first argument.
Usually the server name, port, and path ("CMP alias") need to be set, as well as
credentials the client can use for authenticating itself to the client.
In order to authenticate the server the client typically needs a trust store.
For performing certificate enrollment requests the certificate template needs
to be sufficiently filled in, giving at least the subject name and key.
The functions return their respective main results directly, while there are
also accessor functions for retrieving various results and status information
from the B<ctx>. See L<OSSL_CMP_CTX_new(3)> etc. for details.
The default conveying protocol is HTTP.
Timeout values may be given per request-response pair and per transaction.
See L<OSSL_CMP_MSG_http_perform(3)> for details.
OSSL_CMP_exec_IR_ses() requests an initial certificate from the given PKI.
OSSL_CMP_exec_CR_ses() requests an additional certificate.
OSSL_CMP_exec_P10CR_ses() conveys a legacy PKCS#10 CSR requesting a certificate.
OSSL_CMP_exec_KUR_ses() obtains an updated certificate.
All these four types of certificate enrollment may be blocked by sleeping until the
CAs or an intermedate PKI component can fully process and answer the request.
OSSL_CMP_try_certreq() is an alternative to these four functions that is
more uniform regarding the type of the certificate request to use and
more flexible regarding what to do after receiving a checkAfter value.
When called for the first time (with no certificate request in progress for
the given B<ctx>) it starts a new transaction by sending a certificate request
of the given type,
which may be IR, CR, P10CR, or KUR as specified by the B<req_type> parameter.
Otherwise (when according to B<ctx> a 'waiting' status has been received before)
it continues polling for the pending request
unless the B<req_type> argument is < 0, which aborts the request.
If the requested certificate is available the function returns 1 and the
caller can use B<OSSL_CMP_CTX_get0_newCert()> to retrieve the new certificate.
If no error occurred but no certificate is available yet then
OSSL_CMP_try_certreq() remembers in the CMP context that it should be retried
and returns -1 after assigning the received checkAfter value
via the output pointer argument (unless it is NULL).
The checkAfter value indicates the number of seconds the caller should let pass
before trying again. The caller is free to sleep for the given number of seconds
or for some other time and/or to do anything else before retrying by calling
OSSL_CMP_try_certreq() again with the same parameter values as before.
OSSL_CMP_try_certreq() then polls
to see whether meanwhile the requested certificate is available.
If the caller decides to abort the pending certificate request and provides
a negative value as the B<req_type> argument then OSSL_CMP_try_certreq()
aborts the CMP transaction by sending an error message to the server.
OSSL_CMP_certConf_cb() is a basic certificate confirmation callback validating
that the new certificate can be verified with the trusted/untrusted certificates
in B<ctx>.
As there is no requirement in RFC 4210 that the certificate can be
validated by the client, this callback is not set by default in the context.
OSSL_CMP_exec_RR_ses() requests the revocation of the certificate
specified in the B<ctx> using L<OSSL_CMP_CTX_set1_oldCert(3)>.
RFC 4210 is vague in which PKIStatus should be returned by the server.
We take "accepted" and "grantedWithMods" as clear success and handle
"revocationWarning" and "revocationNotification" just as warnings because CAs
typically return them as an indication that the certificate was already revoked.
"rejection" is a clear error. The values "waiting" and "keyUpdateWarning"
make no sense for revocation and thus are treated as an error as well.
OSSL_CMP_exec_GENM_ses() sends a general message containing the sequence of
infoType and infoValue pairs (InfoTypeAndValue; short: B<ITAV>)
provided in the B<ctx> using L<OSSL_CMP_CTX_push0_genm_ITAV(3)>.
It returns the list of B<ITAV>s received in the GenRep.
This can be used, for instance, to poll for CRLs or CA Key Updates.
See RFC 4210 section 5.3.19 and appendix E.5 for details.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
So far the CMP client implementation is limited to one request per CMP message
(and consequently to at most one response component per CMP message).
=head1 RETURN VALUES
OSSL_CMP_exec_IR_ses(), OSSL_CMP_exec_CR_ses(),
OSSL_CMP_exec_P10CR_ses(), and OSSL_CMP_exec_KUR_ses() return a
pointer to the newly obtained X509 certificate on success, B<NULL> on error.
This pointer will be freed implicitly by OSSL_CMP_CTX_free() or
CSSL_CMP_CTX_reinit().
OSSL_CMP_try_certreq() returns 1 if the requested certificate is available
via B<OSSL_CMP_CTX_get0_newCert()>
or on successfully aborting a pending certificate request, 0 on error, and -1
in case a 'waiting' status has been received and checkAfter value is available.
In the latter case B<OSSL_CMP_CTX_get0_newCert()> yields NULL
and the output parameter B<checkAfter> has been used to
assign the received value unless B<checkAfter> is NULL.
OSSL_CMP_certConf_cb() returns B<fail_info> if it is not equal to B<0>,
else B<0> on successful validation,
or else a bit field with the B<OSSL_CMP_PKIFAILUREINFO_incorrectData> bit set.
OSSL_CMP_exec_RR_ses() returns the
pointer to the revoked certificate on success, B<NULL> on error.
This pointer will be freed implicitly by OSSL_CMP_CTX_free().
OSSL_CMP_exec_GENM_ses() returns a
pointer to the received B<ITAV> sequence on success, B<NULL> on error.
This pointer must be freed by the caller.
=head1 EXAMPLES
See OSSL_CMP_CTX for examples on how to prepare the context for these
functions.
=head1 SEE ALSO
L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_MSG_http_perform(3)>
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_CMP_log_open.pod
+4 -4
View File
@@ -13,7 +13,7 @@ OSSL_CMP_LOG_WARNING,
OSSL_CMP_LOG_NOTICE,
OSSL_CMP_LOG_INFO,
OSSL_CMP_LOG_DEBUG,
OSSL_cmp_log_cb_t,
OSSL_CMP_log_cb_t,
OSSL_CMP_print_to_bio,
OSSL_CMP_print_errors_cb
- functions for logging and error reporting
@@ -36,12 +36,12 @@ OSSL_CMP_print_errors_cb
#define OSSL_CMP_LOG_INFO 6
#define OSSL_CMP_LOG_DEBUG 7
typedef int (*OSSL_cmp_log_cb_t)(const char *component,
typedef int (*OSSL_CMP_log_cb_t)(const char *component,
const char *file, int line,
OSSL_CMP_severity level, const char *msg);
int OSSL_CMP_print_to_bio(BIO *bio, const char *component, const char *file,
int line, OSSL_CMP_severity level, const char *msg);
void OSSL_CMP_print_errors_cb(OSSL_cmp_log_cb_t log_fn);
void OSSL_CMP_print_errors_cb(OSSL_CMP_log_cb_t log_fn);
=head1 DESCRIPTION
@@ -56,7 +56,7 @@ should be provided for user information, debugging, and auditing purposes.
A CMP application can obtain this information by providing a callback function
with the following type:
typedef int (*OSSL_cmp_log_cb_t)(const char *component,
typedef int (*OSSL_CMP_log_cb_t)(const char *component,
const char *file, int line,
OSSL_CMP_severity level, const char *msg);
doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod
+1 -1
View File
@@ -21,7 +21,7 @@ OSSL_CRMF_MSG_get_certReqId
X509_NAME *OSSL_CRMF_CERTTEMPLATE_get0_issuer(OSSL_CRMF_CERTTEMPLATE *tmpl);
ASN1_INTEGER *OSSL_CRMF_CERTID_get0_serialNumber(const OSSL_CRMF_CERTID *cid);
X509_NAME *OSSL_CRMF_CERTID_get0_issuer(const OSSL_CRMF_CERTID *cid);
const X509_NAME *OSSL_CRMF_CERTID_get0_issuer(const OSSL_CRMF_CERTID *cid);
X509 *OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(OSSL_CRMF_ENCRYPTEDVALUE *ecert,
EVP_PKEY *pkey);
doc/man3/OSSL_HTTP_transfer.pod
+44 -21
View File
@@ -17,14 +17,14 @@ OSSL_HTTP_parse_url
typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg,
int connect, int detail);
BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *proxy_port,
BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
int maxline, unsigned long max_resp_len, int timeout,
const char *expected_content_type, int expect_asn1);
ASN1_VALUE *OSSL_HTTP_get_asn1(const char *url,
const char *proxy, const char *proxy_port,
const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
@@ -33,7 +33,7 @@ OSSL_HTTP_parse_url
const ASN1_ITEM *it);
ASN1_VALUE *OSSL_HTTP_post_asn1(const char *server, const char *port,
const char *path, int use_ssl,
const char *proxy, const char *proxy_port,
const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
@@ -43,7 +43,7 @@ OSSL_HTTP_parse_url
int timeout, const char *expected_ct,
const ASN1_ITEM *rsp_it);
BIO *OSSL_HTTP_transfer(const char *server, const char *port, const char *path,
int use_ssl, const char *proxy, const char *proxy_port,
int use_ssl, const char *proxy, const char *no_proxy,
BIO *bio, BIO *rbio,
OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
const STACK_OF(CONF_VALUE) *headers,
@@ -69,17 +69,18 @@ and returns it on success as a pointer to I<ASN1_VALUE>.
OSSL_HTTP_post_asn1() uses the HTTP POST method to send a request B<req>
with the ASN.1 structure defined in B<req_it> and the given B<content_type> to
the given B<server> and optional B<port> and B<path>, which defaults to "/".
the given B<server> and optional B<port> and B<path>.
If B<use_ssl> is nonzero a TLS connection is requested and the B<bio_update_fn>
parameter, described below, must be provided.
The optional list B<headers> may contain additional custom HTTP header lines.
The expected structure of the response is specified by B<rsp_it>.
On success it returns the response as a pointer to B<ASN1_VALUE>.
OSSL_HTTP_transfer() exchanges an HTTP request and response with
the given B<server> and optional B<port> and B<path>, which defaults to "/".
If B<use_ssl> is nonzero a TLS connection is requested and the B<bio_update_fn>
parameter, described below, must be provided.
OSSL_HTTP_transfer() exchanges any form of HTTP request and response.
It implements the core of the functions described above.
If B<path> parameter is NULL it defaults to "/".
If B<use_ssl> is nonzero a TLS connection is requested
and the B<bio_update_fn> parameter, described below, must be provided.
If B<req_mem> is NULL it uses the HTTP GET method, else it uses HTTP POST to
send a request with the contents of the memory BIO and optional B<content_type>.
The optional list B<headers> may contain additional custom HTTP header lines.
@@ -91,22 +92,36 @@ L<OPENSSL_free(3)>.
The above functions have the following parameters in common.
If the B<proxy> parameter is not NULL the HTTP client functions connect
via the given proxy and the optionally given B<proxy_port>.
Proxying plain HTTP is supported directly,
while using a proxy for HTTPS connections requires a suitable callback function
such as OSSL_HTTP_proxy_connect(), described below.
Typically the B<bio> and B<rbio> parameters are NULL and the client creates a
network BIO internally for connecting to the given server and port (optionally
via a proxy and its port), and uses it for exchanging the request and response.
If B<bio> is given and B<rbio> is NULL then the client uses this BIO instead.
Typically the OpenSSL build supports sockets
and the B<bio> and B<rbio> parameters are both NULL.
In this case the client creates a network BIO internally
for connecting to the given B<server>
at the specified B<port> (if any, defaulting to 80 for HTTP or 443 for HTTPS),
optionally via a B<proxy> (respecting B<no_proxy>) as described below.
Then the client uses this internal BIO for exchanging the request and response.
If B<bio> is given and B<rbio> is NULL then the client uses this B<bio> instead.
If both B<bio> and B<rbio> are given (which may be memory BIOs for instance)
then no explicit connection is attempted,
B<bio> is used for writing the request, and B<rbio> for reading the response.
As soon as the client has flushed B<bio> the server must be ready to provide
a response or indicate a waiting condition via B<rbio>.
The optional B<proxy> parameter can be used to set the address of the an
HTTP(S) proxy to use (unless overridden by "no_proxy" settings).
If TLS is not used this defaults to the environment variable B<http_proxy>
if set, else B<HTTP_PROXY>.
If B<use_ssl> != 0 it defaults to B<https_proxy> if set, else B<HTTPS_PROXY>.
An empty proxy string specifies not to use a proxy.
Else the format is I<[http[s]://]address[:port][/path]>,
where any path given is ignored.
The default proxy port number is 80, or 443 in case "https:" is given.
The HTTP client functions connect via the given proxy unless the B<server>
is found in the optional list B<no_proxy> of proxy hostnames (if not NULL;
default is the environment variable B<no_proxy> if set, else B<NO_PROXY>).
Proxying plain HTTP is supported directly,
while using a proxy for HTTPS connections requires a suitable callback function
such as B<OSSL_HTTP_proxy_connect()>, described below.
The B<maxline> parameter specifies the response header maximum line length,
where 0 indicates the default value, which currently is 4k.
The B<max_resp_len> parameter specifies the maximum response length,
@@ -115,7 +130,7 @@ where 0 indicates the default value, which currently is 100k.
An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and
OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer()
this is only the case if the B<expect_asn1> parameter is nonzero.
If the response header contains one or more Content-Length header lines and/or
If the response header contains one or more "Content-Length" header lines and/or
an ASN.1-encoded response is expected, which should include a total length,
the length indications received are checked for consistency
and for not exceeding the maximum response length.
@@ -164,11 +179,12 @@ Here is a simple example that supports TLS connections (but not via a proxy):
After disconnect the modified BIO will be deallocated using BIO_free_all().
OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function
to set up an SSL/TLS connection via an HTTP proxy.
to set up an SSL/TLS connection via an HTTPS proxy.
It promotes the given BIO B<bio> representing a connection
pre-established with a TLS proxy using the HTTP CONNECT method,
optionally using proxy client credentials B<proxyuser> and B<proxypass>,
to connect with TLS protection ultimately to B<server> and B<port>.
If the B<port> argument is NULL or the empty string it defaults to "443".
The B<timeout> parameter is used as described above.
Since this function is typically called by appplications such as
L<openssl-s_client(1)> it uses the B<bio_err> and B<prog> parameters (unless
@@ -184,6 +200,13 @@ them copies of the respective string components.
The strings returned this way must be deallocated by the caller using
L<OPENSSL_free(3)> unless they are NULL, which is their default value on error.
=head1 NOTES
The names of the environment variables used by this implementation:
B<http_proxy>, B<HTTP_PROXY>, B<https_proxy>, B<HTTPS_PROXY>, B<no_proxy>, and
B<NO_PROXY>, have been chosen for maximal compatibility with
other HTTP client implementations such as wget, curl, and git.
=head1 RETURN VALUES
OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
doc/man3/OSSL_PARAM.pod
+6
View File
@@ -159,6 +159,9 @@ The parameter data is a pointer to a printable string.
The difference between this and B<OSSL_PARAM_UTF8_STRING> is that I<data>
doesn't point directly at the data, but to a pointer that points to the data.
If there is any uncertainty about which to use, B<OSSL_PARAM_UTF8_STRING> is
almost certainly the correct choice.
This is used to indicate that constant data is or will be passed,
and there is therefore no need to copy the data that is passed, just
the pointer to it.
@@ -182,6 +185,9 @@ The difference between this and B<OSSL_PARAM_OCTET_STRING> is that
I<data> doesn't point directly at the data, but to a pointer that
points to the data.
If there is any uncertainty about which to use, B<OSSL_PARAM_OCTET_STRING> is
almost certainly the correct choice.
This is used to indicate that constant data is or will be passed, and
there is therefore no need to copy the data that is passed, just the
pointer to it.
doc/man3/OSSL_PARAM_BLD.pod
+195
View File
@@ -0,0 +1,195 @@
=pod
=head1 NAME
OSSL_PARAM_BLD, OSSL_PARAM_BLD_new, OSSL_PARAM_BLD_to_param,
OSSL_PARAM_BLD_free_params, OSSL_PARAM_BLD_free, OSSL_PARAM_BLD_push_int,
OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
OSSL_PARAM_BLD_push_double, OSSL_PARAM_BLD_push_BN,
OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string,
OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string,
OSSL_PARAM_BLD_push_octet_ptr
- functions to assist in the creation of OSSL_PARAM arrays
=head1 SYNOPSIS
=for openssl generic
#include "openssl/param_build.h"
typedef struct OSSL_PARAM_BLD;
OSSL_PARAM_BLD *OSSL_PARAM_BLD_new(void);
OSSL_PARAM *OSSL_PARAM_BLD_to_param(OSSL_PARAM_BLD *bld);
void OSSL_PARAM_BLD_free_params(OSSL_PARAM *params);
void OSSL_PARAM_BLD_free(OSSL_PARAM_BLD *bld);
int OSSL_PARAM_BLD_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
int OSSL_PARAM_BLD_push_BN(OSSL_PARAM_BLD *bld, const char *key,
const BIGNUM *bn);
int OSSL_PARAM_BLD_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
const BIGNUM *bn, size_t sz);
int OSSL_PARAM_BLD_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
const char *buf, size_t bsize);
int OSSL_PARAM_BLD_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
char *buf, size_t bsize);
int OSSL_PARAM_BLD_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
const void *buf, size_t bsize);
int OSSL_PARAM_BLD_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
void *buf, size_t bsize);
=head1 DESCRIPTION
A collection of utility functions that simplify the creation of OSSL_PARAM
arrays. The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>.
OSSL_PARAM_BLD_new() allocates and initialises a new OSSL_PARAM_BLD structure
so that values can be added.
Any existing values are cleared.
OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new().
OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
I<bld> into an allocated OSSL_PARAM array.
The OSSL_PARAM array and all associated storage must be freed by calling
OSSL_PARAM_BLD_free_params() with the functions return value.
OSSL_PARAM_BLD_free() can safely be called any time after this function is.
OSSL_PARAM_BLD_free_params() deallocates the memory allocated by
OSSL_PARAM_BLD_to_param().
=begin comment
POD is pretty good at recognising function names and making them appropriately
bold... however, when part of the function name is variable, we have to help
the processor along
=end comment
B<OSSL_PARAM_BLD_push_I<TYPE>>() are a series of functions which will create
OSSL_PARAM objects of the specified size and correct type for the I<val>
argument.
I<val> is stored by value and an expression or auto variable can be used.
OSSL_PARAM_BLD_push_BN() is a function that will create an OSSL_PARAM object
that holds the specified BIGNUM I<bn>.
If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
will also be securely allocated.
The I<bn> argument is stored by reference and the underlying BIGNUM object
must exist until after OSSL_PARAM_BLD_to_param() has been called.
OSSL_PARAM_BLD_push_BN_pad() is a function that will create an OSSL_PARAM object
that holds the specified BIGNUM I<bn>.
The object will be padded to occupy exactly I<sz> bytes, if insufficient space
is specified an error results.
If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
will also be securely allocated.
The I<bn> argument is stored by reference and the underlying BIGNUM object
must exist until after OSSL_PARAM_BLD_to_param() has been called.
OSSL_PARAM_BLD_push_utf8_string() is a function that will create an OSSL_PARAM
object that references the UTF8 string specified by I<buf>.
If the length of the string, I<bsize>, is zero then it will be calculated.
The string that I<buf> points to is stored by reference and must remain in
scope until after OSSL_PARAM_BLD_to_param() has been called.
OSSL_PARAM_BLD_push_octet_string() is a function that will create an OSSL_PARAM
object that references the octet string specified by I<buf> and <bsize>.
The memory that I<buf> points to is stored by reference and must remain in
scope until after OSSL_PARAM_BLD_to_param() has been called.
OSSL_PARAM_BLD_push_utf8_ptr() is a function that will create an OSSL_PARAM
object that references the UTF8 string specified by I<buf>.
If the length of the string, I<bsize>, is zero then it will be calculated.
The string I<buf> points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed.
OSSL_PARAM_BLD_push_octet_ptr() is a function that will create an OSSL_PARAM
object that references the octet string specified by I<buf>.
The memory I<buf> points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed.
=head1 RETURN VALUES
OSSL_PARAM_BLD_new() returns the allocated OSSL_PARAM_BLD structure, or NULL
on error.
OSSL_PARAM_BLD_to_param() returns the allocated OSSL_PARAM array, or NULL
on error.
All of the OSSL_PARAM_BLD_push_TYPE functions return 1 on success and 0
on error.
=head1 EXAMPLES
Both examples creating an OSSL_PARAM array that contains an RSA key.
For both, the predefined key variables are:
BIGNUM *p, *q; /* both prime */
BIGNUM *n; /* = p * q */
unsigned int e; /* exponent, usually 65537 */
BIGNUM *d; /* e^-1 */
=head2 Example 1
This example shows how to create an OSSL_PARAM array that contains an RSA
private key.
OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
OSSL_PARAM *params;
if (bld == NULL
|| !OSSL_PARAM_BLD_push_BN(&bld, "p", p)
|| !OSSL_PARAM_BLD_push_BN(&bld, "q", q)
|| !OSSL_PARAM_BLD_push_uint(&bld, "e", e)
|| !OSSL_PARAM_BLD_push_BN(&bld, "n", n)
|| !OSSL_PARAM_BLD_push_BN(&bld, "d", d)
|| (params = OSSL_PARAM_BLD_to_param(&bld)) == NULL)
goto err;
OSSL_PARAM_BLD_free(bld);
/* Use params */
...
OSSL_PARAM_BLD_free_params(params);
=head2 Example 2
This example shows how to create an OSSL_PARAM array that contains an RSA
public key.
OSSL_PARAM_BLD *bld = OSSL_PARAM_BLD_new();
OSSL_PARAM *params;
if (nld == NULL
|| !OSSL_PARAM_BLD_push_BN(bld, "n", n)
|| !OSSL_PARAM_BLD_push_BN(bld, "d", d)
|| (params = OSSL_PARAM_BLD_to_param(bld)) == NULL)
goto err;
OSSL_PARAM_BLD_free(bld);
/* Use params */
...
OSSL_PARAM_BLD_free_params(params);
=head1 SEE ALSO
L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>
=head1 HISTORY
The functions described here were all added in OpenSSL 3.0.
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/OSSL_PARAM_allocate_from_text.pod
+64 -24
View File
@@ -26,34 +26,74 @@ OpenSSL 3.0 introduces a new mechanism to do the same thing with an
array of parameters that contain name, value, value type and value
size (see L<OSSL_PARAM(3)> for more information).
OSSL_PARAM_allocate_from_text() takes a control I<key>, I<value> and
value size I<value_n>, and given a parameter descriptor array
I<paramdefs>, it converts the value to something suitable for
L<OSSL_PARAM(3)> and stores that in the buffer I<buf>, and modifies
the parameter I<to> to match.
I<buf_n>, if not NULL, will be assigned the number of bytes used in
I<buf>.
If I<buf> is NULL, only I<buf_n> will be modified, everything else is
left untouched, allowing a caller to find out how large the buffer
should be.
I<buf> needs to be correctly aligned for the type of the B<OSSL_PARAM>
I<key>.
If <found> is not NULL, it is set to 1 if the parameter can be located and
to 0 otherwise.
OSSL_PARAM_allocate_from_text() uses I<key> to look up an item in
I<paramdefs>. If an item was found, it converts I<value> to something
suitable for that item's I<data_type>, and stores the result in
I<< to->data >> as well as its size in I<< to->data_size >>.
I<< to->key >> and I<< to->data_type >> are assigned the corresponding
values from the item that was found, and I<< to->return_size >> is set
to zero.
The caller must remember to free the data of I<to> when it's not
useful any more.
I<< to->data >> is always allocated using L<OPENSSL_zalloc(3)> and
needs to be freed by the caller when it's not useful any more, using
L<OPENSSL_free(3)>.
For parameters having the type B<OSSL_PARAM_INTEGER>,
B<OSSL_PARAM_UNSIGNED_INTEGER>, or B<OSSL_PARAM_OCTET_STRING>, both
functions will interpret the I<value> differently if the key starts
with "hex".
In that case, the value is decoded first, and the result will be used
as parameter value.
If I<found> is not NULL, I<*found> is set to 1 if I<key> could be
located in I<paramdefs>, and to 0 otherwise.
=head2 The use of I<key> and I<value> in detail
OSSL_PARAM_allocate_from_text() takes note if I<key> starts with
"hex", and will only use the rest of I<key> to look up an item in
I<paramdefs> in that case. As an example, if I<key> is "hexid", "id"
will be looked up in I<paramdefs>.
When an item in I<paramdefs> has been found, I<value> is converted
depending on that item's I<data_type>, as follows:
=over 4
=item B<OSSL_PARAM_INTEGER> and B<OSSL_PARAM_UNSIGNED_INTEGER>
If I<key> started with "hex", I<value> is assumed to contain
I<value_n> hexadecimal characters, which are decoded, and the
resulting bytes become the number stored in the I<< to->data >>
storage.
If I<key> didn't start with "hex", I<value> is assumed to contain
I<value_n> decimal characters, which are decoded, and the resulting
bytes become the number stored in the I<< to->data >> storage.
If I<value> contains characters that couldn't be decoded as
hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text()
considers that an error.
=item B<OSSL_PARAM_UTF8_STRING>
If I<key> started with "hex", OSSL_PARAM_allocate_from_text()
considers that an error.
Otherwise, I<value> is considered a C string and is copied with no
further checks to the I<< to->data >> storage.
=item B<OSSL_PARAM_OCTET_STRING>
If I<key> started with "hex", I<value> is assumed to contain
I<value_n> hexadecimal characters, which are decoded, and the
resulting bytes are stored in the I<< to->data >> storage.
If I<value> contains characters that couldn't be decoded as
hexadecimal or decimal characters, OSSL_PARAM_allocate_from_text()
considers that an error.
If I<key> didn't start with "hex", I<value_n> bytes from I<value> are
copied to the I<< to->data >> storage.
=back
=head1 RETURN VALUES
OSSL_PARAM_allocate_from_text() returns 1 on success, and 0 on error.
OSSL_PARAM_allocate_from_text() returns 1 if I<key> was found in
I<paramdefs> and there was no other failure, otherwise 0.
=head1 NOTES
@@ -65,7 +105,7 @@ The following B<OSSL_PARAM> attributes are used:
=item I<key>
=item I<data>
=item I<data_type>
=item I<data_size>
doc/man3/OSSL_SELF_TEST_new.pod
+1 -1
View File
@@ -133,7 +133,7 @@ A single self test could be set up in the following way:
|| !EVP_DigestUpdate(ctx, pt, pt_len)
|| !EVP_DigestFinal(ctx, out, &out_len))
goto err;
/* Optional corruption - If the application callback returns 0 */
OSSL_SELF_TEST_oncorrupt_byte(st, out);
doc/man3/RAND_set_rand_method.pod
+2 -2
View File
@@ -33,10 +33,10 @@ RAND_get_rand_method() returns a pointer to the current B<RAND_METHOD>.
=head1 THE RAND_METHOD STRUCTURE
typedef struct rand_meth_st {
void (*seed)(const void *buf, int num);
int (*seed)(const void *buf, int num);
int (*bytes)(unsigned char *buf, int num);
void (*cleanup)(void);
void (*add)(const void *buf, int num, int randomness);
int (*add)(const void *buf, int num, double entropy);
int (*pseudorand)(unsigned char *buf, int num);
int (*status)(void);
} RAND_METHOD;
doc/man3/SRP_Calc_B.pod
+88
View File
@@ -0,0 +1,88 @@
=pod
=head1 NAME
SRP_Calc_server_key,
SRP_Calc_A,
SRP_Calc_B_ex,
SRP_Calc_B,
SRP_Calc_u_ex,
SRP_Calc_u,
SRP_Calc_x_ex,
SRP_Calc_x,
SRP_Calc_client_key_ex,
SRP_Calc_client_key
- SRP authentication primitives
=head1 SYNOPSIS
#include <openssl/srp.h>
/* server side .... */
BIGNUM *SRP_Calc_server_key(const BIGNUM *A, const BIGNUM *v, const BIGNUM *u,
const BIGNUM *b, const BIGNUM *N);
BIGNUM *SRP_Calc_B_ex(const BIGNUM *b, const BIGNUM *N, const BIGNUM *g,
const BIGNUM *v, OPENSSL_CTX *libctx, const char *propq);
BIGNUM *SRP_Calc_B(const BIGNUM *b, const BIGNUM *N, const BIGNUM *g,
const BIGNUM *v);
BIGNUM *SRP_Calc_u_ex(const BIGNUM *A, const BIGNUM *B, const BIGNUM *N,
OPENSSL_CTX *libctx, const char *propq);
BIGNUM *SRP_Calc_u(const BIGNUM *A, const BIGNUM *B, const BIGNUM *N);
/* client side .... */
BIGNUM *SRP_Calc_client_key_ex(const BIGNUM *N, const BIGNUM *B, const BIGNUM *g,
const BIGNUM *x, const BIGNUM *a, const BIGNUM *u,
OPENSSL_CTX *libctx, const char *propq);
BIGNUM *SRP_Calc_client_key(const BIGNUM *N, const BIGNUM *B, const BIGNUM *g,
const BIGNUM *x, const BIGNUM *a, const BIGNUM *u);
BIGNUM *SRP_Calc_x_ex(const BIGNUM *s, const char *user, const char *pass,
OPENSSL_CTX *libctx, const char *propq);
BIGNUM *SRP_Calc_x(const BIGNUM *s, const char *user, const char *pass);
BIGNUM *SRP_Calc_A(const BIGNUM *a, const BIGNUM *N, const BIGNUM *g);
=head1 DESCRIPTION
The SRP functions described on this page are used to calculate various
parameters and keys used by SRP as defined in RFC2945. The server key and I<B>
and I<u> parameters are used on the server side and are calculated via
SRP_Calc_server_key(), SRP_Calc_B_ex(), SRP_Calc_B(), SRP_Calc_u_ex() and
SRP_Calc_u(). The client key and B<x> and B<A> parameters are used on the
client side and are calculated via the functions SRP_Calc_client_key_ex(),
SRP_Calc_client_key(), SRP_Calc_x_ex(), SRP_Calc_x() and SRP_Calc_A(). See
RFC2945 for a detailed description of their usage and the meaning of the various
BIGNUM parameters to these functions.
Most of these functions come in two forms. Those that take a I<libctx> and
I<propq> parameter, and those that don't. Any cryptogrpahic functions that
are fetched and used during the calculation use the provided I<libctx> and
I<propq>. See L<provider(7)/Fetching algorithms> for more details. The variants
that do not take a I<libctx> and I<propq> parameter use the default library
context and property query string. The SRP_Calc_server_key() and SRP_Calc_A()
functions do not have a form that takes I<libctx> or I<propq> parameters because
they do not need to fetch any cryptographic algorithms.
=head1 RETURN VALUES
All these functions return the calculated key or parameter, or NULL on error.
=head1 SEE ALSO
L<openssl-srp(1)>,
L<SRP_VBASE_new(3)>,
L<SRP_user_pwd_new(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.0.1.
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/SRP_create_verifier.pod
+36 -17
View File
@@ -2,7 +2,9 @@
=head1 NAME
SRP_create_verifier_ex,
SRP_create_verifier,
SRP_create_verifier_BN_ex,
SRP_create_verifier_BN,
SRP_check_known_gN_param,
SRP_get_default_gN
@@ -12,8 +14,15 @@ SRP_get_default_gN
#include <openssl/srp.h>
int SRP_create_verifier_BN_ex(const char *user, const char *pass, BIGNUM **salt,
BIGNUM **verifier, const BIGNUM *N,
const BIGNUM *g, OPENSSL_CTX *libctx,
const char *propq);
char *SRP_create_verifier_BN(const char *user, const char *pass, BIGNUM **salt,
BIGNUM **verifier, const BIGNUM *N, const BIGNUM *g);
char *SRP_create_verifier_ex(const char *user, const char *pass, char **salt,
char **verifier, const char *N, const char *g,
OPENSSL_CTX *libctx, const char *propq);
char *SRP_create_verifier(const char *user, const char *pass, char **salt,
char **verifier, const char *N, const char *g);
@@ -22,46 +31,55 @@ SRP_get_default_gN
=head1 DESCRIPTION
The SRP_create_verifier_BN() function creates an SRP password verifier from
the supplied parameters as defined in section 2.4 of RFC 5054.
On successful exit B<*verifier> will point to a newly allocated BIGNUM containing
the verifier and (if a salt was not provided) B<*salt> will be populated with a
newly allocated BIGNUM containing a random salt. If B<*salt> is not NULL then
The SRP_create_verifier_BN_ex() function creates an SRP password verifier from
the supplied parameters as defined in section 2.4 of RFC 5054 using the library
context I<libctx> and property query string I<propq>. Any cryptographic
algorithms that need to be fetched will use the I<libctx> and I<propq>. See
L<provider(7)/Fetching algorithms>.
SRP_create_verifier_BN() is the same as SRP_create_verifier_BN_ex() except the
default library context and property query string is used.
On successful exit I<*verifier> will point to a newly allocated BIGNUM containing
the verifier and (if a salt was not provided) I<*salt> will be populated with a
newly allocated BIGNUM containing a random salt. If I<*salt> is not NULL then
the provided salt is used instead.
The caller is responsible for freeing the allocated B<*salt> and B<*verifier>
The caller is responsible for freeing the allocated I<*salt> and I<*verifier>
BIGNUMS (use L<BN_free(3)>).
The SRP_create_verifier() function is similar to SRP_create_verifier_BN() but
all numeric parameters are in a non-standard base64 encoding originally designed
for compatibility with libsrp. This is mainly present for historical compatibility
and its use is discouraged.
It is possible to pass NULL as B<N> and an SRP group id as B<g> instead to
It is possible to pass NULL as I<N> and an SRP group id as I<g> instead to
load the appropriate gN values (see SRP_get_default_gN()).
If both B<N> and B<g> are NULL the 8192-bit SRP group parameters are used.
The caller is responsible for freeing the allocated B<*salt> and B<*verifier>
If both I<N> and I<g> are NULL the 8192-bit SRP group parameters are used.
The caller is responsible for freeing the allocated I<*salt> and I<*verifier>
(use L<OPENSSL_free(3)>).
The SRP_check_known_gN_param() function checks that B<g> and B<N> are valid
The SRP_check_known_gN_param() function checks that I<g> and I<N> are valid
SRP group parameters from RFC 5054 appendix A.
The SRP_get_default_gN() function returns the gN parameters for the RFC 5054 B<id>
The SRP_get_default_gN() function returns the gN parameters for the RFC 5054 I<id>
SRP group size.
The known ids are "1024", "1536", "2048", "3072", "4096", "6144" and "8192".
=head1 RETURN VALUES
SRP_create_verifier_BN() returns 1 on success and 0 on failure.
SRP_create_verifier_BN_ex() and SRP_create_verifier_BN() return 1 on success and
0 on failure.
SRP_create_verifier() returns NULL on failure and a non-NULL value on success:
"*" if B<N> is not NULL, the selected group id otherwise. This value should
SRP_create_verifier_ex() and SRP_create_verifier() return NULL on failure and a
non-NULL value on success:
"*" if I<N> is not NULL, the selected group id otherwise. This value should
not be freed.
SRP_check_known_gN_param() returns the text representation of the group id
(ie. the prime bit size) or NULL if the arguments are not valid SRP group parameters.
This value should not be freed.
SRP_get_default_gN() returns NULL if B<id> is not a valid group size,
or the 8192-bit group parameters if B<id> is NULL.
SRP_get_default_gN() returns NULL if I<id> is not a valid group size,
or the 8192-bit group parameters if I<id> is NULL.
=head1 EXAMPLES
@@ -79,7 +97,8 @@ omitted for clarity):
SRP_gN *gN = SRP_get_default_gN("8192");
BIGNUM *salt = NULL, *verifier = NULL;
SRP_create_verifier_BN(username, password, &salt, &verifier, gN->N, gN->g);
SRP_create_verifier_BN_ex(username, password, &salt, &verifier, gN->N, gN->g,
NULL, NULL);
SRP_user_pwd *pwd = SRP_user_pwd_new();
SRP_user_pwd_set1_ids(pwd, username, NULL);
doc/man3/SSL_CTX_sess_set_get_cb.pod
+21 -18
View File
@@ -28,19 +28,19 @@ SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SS
=head1 DESCRIPTION
SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
SSL_CTX_sess_set_new_cb() sets the callback function that is
called whenever a new session was negotiated.
SSL_CTX_sess_set_remove_cb() sets the callback function, which is
automatically called whenever a session is removed by the SSL engine,
because it is considered faulty or the session has become obsolete because
of exceeding the timeout value.
SSL_CTX_sess_set_remove_cb() sets the callback function that is
called whenever a session is removed by the SSL engine. For example,
this can occur because a session is considered faulty or has become obsolete
because of exceeding the timeout value.
SSL_CTX_sess_set_get_cb() sets the callback function which is called,
whenever a SSL/TLS client proposed to resume a session but the session
SSL_CTX_sess_set_get_cb() sets the callback function that is called
whenever a TLS client proposed to resume a session but the session
could not be found in the internal session cache (see
L<SSL_CTX_set_session_cache_mode(3)>).
(SSL/TLS server only.)
(TLS server only.)
SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
SSL_CTX_sess_get_get_cb() retrieve the function pointers set by the
@@ -56,7 +56,8 @@ L<d2i_SSL_SESSION(3)> interface.
The new_session_cb() is called whenever a new session has been negotiated and
session caching is enabled (see L<SSL_CTX_set_session_cache_mode(3)>). The
new_session_cb() is passed the B<ssl> connection and the ssl session B<sess>.
new_session_cb() is passed the B<ssl> connection and the nascent
ssl session B<sess>.
Since sessions are reference-counted objects, the reference count on the
session is incremented before the callback, on behalf of the application. If
the callback returns B<0>, the session will be immediately removed from the
@@ -78,21 +79,23 @@ In TLSv1.3 it is recommended that each SSL_SESSION object is only used for
resumption once. One way of enforcing that is for applications to call
L<SSL_CTX_remove_session(3)> after a session has been used.
The remove_session_cb() is called, whenever the SSL engine removes a session
from the internal cache. This happens when the session is removed because
The remove_session_cb() is called whenever the SSL engine removes a session
from the internal cache. This can happen when the session is removed because
it is expired or when a connection was not shutdown cleanly. It also happens
for all sessions in the internal session cache when
L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed
the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
The get_session_cb() is only called on SSL/TLS servers with the session id
proposed by the client. The get_session_cb() is always called, also when
The get_session_cb() is only called on SSL/TLS servers, and is given
the session id
proposed by the client. The get_session_cb() is always called, even when
session caching was disabled. The get_session_cb() is passed the
B<ssl> connection, the session id of length B<length> at the memory location
B<data>. With the parameter B<copy> the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object,
Normally the reference count is not incremented and therefore the
session must not be explicitly freed with
B<ssl> connection and the session id of length B<length> at the memory location
B<data>. By setting the parameter B<copy> to B<1>, the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object;
setting B<copy> to B<0> causes the reference count to remain unchanged.
If the get_session_cb() does not write to B<copy>, the reference count
is incremented and the session must be explicitly freed with
L<SSL_SESSION_free(3)>.
=head1 RETURN VALUES
doc/man3/SSL_CTX_set_tmp_dh_callback.pod
-9
View File
@@ -62,15 +62,6 @@ generate their own DH parameters during the installation process using the
openssl L<openssl-dhparam(1)> application. This application
guarantees that "strong" primes are used.
Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current
version of the OpenSSL distribution contain the 'SKIP' DH parameters,
which use safe primes and were generated verifiably pseudo-randomly.
These files can be converted into C code using the B<-C> option of the
L<openssl-dhparam(1)> application. Generation of custom DH
parameters during installation should still be preferred to stop an
attacker from specializing on a commonly used group. File dh1024.pem
contains old parameters that must not be used by applications.
An application may either directly specify the DH parameters or
can supply the DH parameters via a callback function.
doc/man3/SSL_accept.pod
+2 -2
View File
@@ -56,7 +56,7 @@ established.
The TLS/SSL handshake was not successful because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
not clean. It can also occur of action is need to continue the operation
not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -72,7 +72,7 @@ L<SSL_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/SSL_connect.pod
+2 -2
View File
@@ -71,7 +71,7 @@ established.
The TLS/SSL handshake was not successful, because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
not clean. It can also occur of action is need to continue the operation
not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -87,7 +87,7 @@ L<SSL_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/SSL_do_handshake.pod
+2 -2
View File
@@ -57,7 +57,7 @@ established.
The TLS/SSL handshake was not successful because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
not clean. It can also occur of action is need to continue the operation
not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -71,7 +71,7 @@ L<SSL_set_connect_state(3)>
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/X509_CRL_get0_by_serial.pod
+1 -1
View File
@@ -13,7 +13,7 @@ functions
#include <openssl/x509.h>
int X509_CRL_get0_by_serial(X509_CRL *crl,
X509_REVOKED **ret, ASN1_INTEGER *serial);
X509_REVOKED **ret, const ASN1_INTEGER *serial);
int X509_CRL_get0_by_cert(X509_CRL *crl, X509_REVOKED **ret, X509 *x);
STACK_OF(X509_REVOKED) *X509_CRL_get_REVOKED(X509_CRL *crl);
doc/man3/X509_LOOKUP.pod
+3 -3
View File
@@ -40,10 +40,10 @@ X509_LOOKUP_by_alias
X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, X509_OBJECT *ret);
const X509_NAME *name, X509_OBJECT *ret);
int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, ASN1_INTEGER *serial,
X509_OBJECT *ret);
const X509_NAME *name,
const ASN1_INTEGER *serial, X509_OBJECT *ret);
int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
const unsigned char *bytes, int len,
X509_OBJECT *ret);
doc/man3/X509_LOOKUP_meth_new.pod
+3 -3
View File
@@ -57,7 +57,7 @@ X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
typedef int (*X509_LOOKUP_get_by_subject_fn)(X509_LOOKUP *ctx,
X509_LOOKUP_TYPE type,
X509_NAME *name,
const X509_NAME *name,
X509_OBJECT *ret);
int X509_LOOKUP_meth_set_get_by_subject(X509_LOOKUP_METHOD *method,
X509_LOOKUP_get_by_subject_fn fn);
@@ -66,8 +66,8 @@ X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
typedef int (*X509_LOOKUP_get_by_issuer_serial_fn)(X509_LOOKUP *ctx,
X509_LOOKUP_TYPE type,
X509_NAME *name,
ASN1_INTEGER *serial,
const X509_NAME *name,
const ASN1_INTEGER *serial,
X509_OBJECT *ret);
int X509_LOOKUP_meth_set_get_by_issuer_serial(
X509_LOOKUP_METHOD *method, X509_LOOKUP_get_by_issuer_serial_fn fn);
doc/man3/X509_NAME_get0_der.pod
+1 -1
View File
@@ -8,7 +8,7 @@ X509_NAME_get0_der - get X509_NAME DER encoding
#include <openssl/x509.h>
int X509_NAME_get0_der(X509_NAME *nm, const unsigned char **pder,
int X509_NAME_get0_der(const X509_NAME *nm, const unsigned char **pder,
size_t *pderlen)
doc/man3/X509_NAME_get_index_by_NID.pod
+7 -4
View File
@@ -10,14 +10,17 @@ X509_NAME lookup and enumeration functions
#include <openssl/x509.h>
int X509_NAME_get_index_by_NID(X509_NAME *name, int nid, int lastpos);
int X509_NAME_get_index_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int lastpos);
int X509_NAME_get_index_by_NID(const X509_NAME *name, int nid, int lastpos);
int X509_NAME_get_index_by_OBJ(const X509_NAME *name,
const ASN1_OBJECT *obj, int lastpos);
int X509_NAME_entry_count(const X509_NAME *name);
X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc);
int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf, int len);
int X509_NAME_get_text_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, char *buf, int len);
int X509_NAME_get_text_by_NID(const X509_NAME *name, int nid,
char *buf, int len);
int X509_NAME_get_text_by_OBJ(const X509_NAME *name, const ASN1_OBJECT *obj,
char *buf, int len);
=head1 DESCRIPTION
doc/man3/X509_STORE_CTX_get_error.pod
+5 -5
View File
@@ -13,15 +13,15 @@ information
#include <openssl/x509.h>
int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx);
int X509_STORE_CTX_get_error(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s);
int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx);
int X509_STORE_CTX_get_error_depth(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set_error_depth(X509_STORE_CTX *ctx, int depth);
X509 *X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx);
X509 *X509_STORE_CTX_get_current_cert(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x);
X509 *X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx);
X509 *X509_STORE_CTX_get0_cert(const X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_STORE_CTX_get1_chain(const X509_STORE_CTX *ctx);
const char *X509_verify_cert_error_string(long n);
doc/man3/X509_STORE_CTX_new.pod
+39 -29
View File
@@ -2,9 +2,9 @@
=head1 NAME
X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free,
X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert,
X509_STORE_CTX_set0_crls,
X509_STORE_CTX_new_with_libctx, X509_STORE_CTX_new, X509_STORE_CTX_cleanup,
X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack,
X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls,
X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param,
X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted,
@@ -18,6 +18,8 @@ X509_STORE_CTX_verify_fn
#include <openssl/x509_vfy.h>
X509_STORE_CTX *X509_STORE_CTX_new_with_libctx(OPENSSL_CTX *libctx,
const char *propq);
X509_STORE_CTX *X509_STORE_CTX_new(void);
void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
@@ -28,18 +30,18 @@ X509_STORE_CTX_verify_fn
void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);
STACK_OF(X509) *X509_STORE_CTX_get0_chain(X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx);
X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx);
STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
int X509_STORE_CTX_get_num_untrusted(X509_STORE_CTX *ctx);
int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx);
typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
@@ -49,61 +51,68 @@ X509_STORE_CTX_verify_fn
These functions initialise an B<X509_STORE_CTX> structure for subsequent use
by X509_verify_cert().
X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure.
X509_STORE_CTX_new_with_libctx() returns a newly initialised B<X509_STORE_CTX>
structure associated with the specified library context I<libctx> and property
query string I<propq>. Any cryptographic algorithms fetched while performing
processing with the X509_STORE_CTX will use that library context and property
query string.
X509_STORE_CTX_new() is the same as X509_STORE_CTX_new_with_libctx() except that
the default library context and a NULL property query string are used.
X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure.
The context can then be reused with an new call to X509_STORE_CTX_init().
X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx>
X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx>
is no longer valid.
If B<ctx> is NULL nothing is done.
If I<ctx> is NULL nothing is done.
X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation.
It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only
X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation.
It must be called before each call to X509_verify_cert(), i.e. a I<ctx> is only
good for one call to X509_verify_cert(); if you want to verify a second
certificate with the same B<ctx> then you must call X509_STORE_CTX_cleanup()
certificate with the same I<ctx> then you must call X509_STORE_CTX_cleanup()
and then X509_STORE_CTX_init() again before the second call to
X509_verify_cert(). The trusted certificate store is set to B<store>, the end
entity certificate to be verified is set to B<x509> and a set of additional
X509_verify_cert(). The trusted certificate store is set to I<store>, the end
entity certificate to be verified is set to I<x509> and a set of additional
certificates (which will be untrusted but may be used to build the chain) in
B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be
I<chain>. Any or all of the I<store>, I<x509> and I<chain> parameters can be
B<NULL>.
X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of
B<ctx> to B<sk>. This is an alternative way of specifying trusted certificates
I<ctx> to I<sk>. This is an alternative way of specifying trusted certificates
instead of using an B<X509_STORE>.
X509_STORE_CTX_set_cert() sets the certificate to be verified in B<ctx> to
B<x>.
X509_STORE_CTX_set_cert() sets the certificate to be verified in I<ctx> to
I<x>.
X509_STORE_CTX_set0_verified_chain() sets the validated chain used
by B<ctx> to be B<chain>.
Ownership of the chain is transferred to B<ctx> and should not be
by I<ctx> to be I<chain>.
Ownership of the chain is transferred to I<ctx> and should not be
free'd by the caller.
X509_STORE_CTX_get0_chain() returns a the internal pointer used by the
B<ctx> that contains the validated chain.
I<ctx> that contains the validated chain.
X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate
verification to B<sk>. These CRLs will only be used if CRL verification is
verification to I<sk>. These CRLs will only be used if CRL verification is
enabled in the associated B<X509_VERIFY_PARAM> structure. This might be
used where additional "useful" CRLs are supplied as part of a protocol,
for example in a PKCS#7 structure.
X509_STORE_CTX_get0_param() retrieves an internal pointer
to the verification parameters associated with B<ctx>.
to the verification parameters associated with I<ctx>.
X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the
stack of untrusted certificates associated with B<ctx>.
stack of untrusted certificates associated with I<ctx>.
X509_STORE_CTX_set0_untrusted() sets the internal point to the stack
of untrusted certificates associated with B<ctx> to B<sk>.
of untrusted certificates associated with I<ctx> to I<sk>.
X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
to B<param>. After this call B<param> should not be used.
to I<param>. After this call B<param> should not be used.
X509_STORE_CTX_set_default() looks up and sets the default verification
method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to
find an appropriate set of parameters from B<name>.
method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to
find an appropriate set of parameters from I<name>.
X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
that were used in building the chain following a call to X509_verify_cert().
@@ -161,6 +170,7 @@ L<X509_VERIFY_PARAM_set_flags(3)>
The X509_STORE_CTX_set0_crls() function was added in OpenSSL 1.0.0.
The X509_STORE_CTX_get_num_untrusted() function was added in OpenSSL 1.1.0.
The X509_STORE_CTX_new_with_libctx() function was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/X509_STORE_get0_param.pod
+3 -3
View File
@@ -10,9 +10,9 @@ X509_STORE_get0_objects, X509_STORE_get1_all_certs
#include <openssl/x509_vfy.h>
X509_VERIFY_PARAM *X509_STORE_get0_param(X509_STORE *ctx);
int X509_STORE_set1_param(X509_STORE *ctx, X509_VERIFY_PARAM *pm);
STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(X509_STORE *ctx);
X509_VERIFY_PARAM *X509_STORE_get0_param(const X509_STORE *ctx);
int X509_STORE_set1_param(X509_STORE *ctx, const X509_VERIFY_PARAM *pm);
STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(const X509_STORE *ctx);
STACK_OF(X509) *X509_STORE_get1_all_certs(X509_STORE *st);
=head1 DESCRIPTION
doc/man3/X509_STORE_set_verify_cb_func.pod
+23 -15
View File
@@ -51,57 +51,65 @@ X509_STORE_CTX_lookup_certs_fn, X509_STORE_CTX_lookup_crls_fn
X509_CRL *crl, X509 *x);
typedef int (*X509_STORE_CTX_check_policy_fn)(X509_STORE_CTX *ctx);
typedef STACK_OF(X509) *(*X509_STORE_CTX_lookup_certs_fn)(X509_STORE_CTX *ctx,
X509_NAME *nm);
typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(X509_STORE_CTX *ctx,
X509_NAME *nm);
const X509_NAME *nm);
typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(const
X509_STORE_CTX *ctx,
const X509_NAME *nm);
typedef int (*X509_STORE_CTX_cleanup_fn)(X509_STORE_CTX *ctx);
void X509_STORE_set_verify_cb(X509_STORE *ctx,
X509_STORE_CTX_verify_cb verify_cb);
X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(X509_STORE_CTX *ctx);
X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(const X509_STORE_CTX *ctx);
void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify_fn verify);
X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx);
X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(const X509_STORE_CTX *ctx);
void X509_STORE_set_get_issuer(X509_STORE *ctx,
X509_STORE_CTX_get_issuer_fn get_issuer);
X509_STORE_CTX_get_issuer_fn X509_STORE_get_get_issuer(X509_STORE_CTX *ctx);
X509_STORE_CTX_get_issuer_fn
X509_STORE_get_get_issuer(const X509_STORE_CTX *ctx);
void X509_STORE_set_check_issued(X509_STORE *ctx,
X509_STORE_CTX_check_issued_fn check_issued);
X509_STORE_CTX_check_issued_fn X509_STORE_get_check_issued(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_issued_fn
X509_STORE_get_check_issued(const X509_STORE_CTX *ctx);
void X509_STORE_set_check_revocation(X509_STORE *ctx,
X509_STORE_CTX_check_revocation_fn check_revocation);
X509_STORE_CTX_check_revocation_fn X509_STORE_get_check_revocation(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_revocation_fn
X509_STORE_get_check_revocation(const X509_STORE_CTX *ctx);
void X509_STORE_set_get_crl(X509_STORE *ctx,
X509_STORE_CTX_get_crl_fn get_crl);
X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(X509_STORE_CTX *ctx);
X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(const X509_STORE_CTX *ctx);
void X509_STORE_set_check_crl(X509_STORE *ctx,
X509_STORE_CTX_check_crl_fn check_crl);
X509_STORE_CTX_check_crl_fn X509_STORE_get_check_crl(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_crl_fn
X509_STORE_get_check_crl(const X509_STORE_CTX *ctx);
void X509_STORE_set_cert_crl(X509_STORE *ctx,
X509_STORE_CTX_cert_crl_fn cert_crl);
X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(X509_STORE_CTX *ctx);
X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(const X509_STORE_CTX *ctx);
void X509_STORE_set_check_policy(X509_STORE *ctx,
X509_STORE_CTX_check_policy_fn check_policy);
X509_STORE_CTX_check_policy_fn X509_STORE_get_check_policy(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_policy_fn
X509_STORE_get_check_policy(const X509_STORE_CTX *ctx);
void X509_STORE_set_lookup_certs(X509_STORE *ctx,
X509_STORE_CTX_lookup_certs_fn lookup_certs);
X509_STORE_CTX_lookup_certs_fn X509_STORE_get_lookup_certs(X509_STORE_CTX *ctx);
X509_STORE_CTX_lookup_certs_fn
X509_STORE_get_lookup_certs(const X509_STORE_CTX *ctx);
void X509_STORE_set_lookup_crls(X509_STORE *ctx,
X509_STORE_CTX_lookup_crls_fn lookup_crls);
X509_STORE_CTX_lookup_crls_fn X509_STORE_get_lookup_crls(X509_STORE_CTX *ctx);
X509_STORE_CTX_lookup_crls_fn
X509_STORE_get_lookup_crls(const X509_STORE_CTX *ctx);
void X509_STORE_set_cleanup(X509_STORE *ctx,
X509_STORE_CTX_cleanup_fn cleanup);
X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(X509_STORE_CTX *ctx);
X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(const X509_STORE_CTX *ctx);
/* Aliases */
void X509_STORE_set_verify_cb_func(X509_STORE *st,
doc/man3/X509_VERIFY_PARAM_set_flags.pod
+1 -1
View File
@@ -57,7 +57,7 @@ X509_VERIFY_PARAM_set1_ip_asc
void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
unsigned int flags);
unsigned int X509_VERIFY_PARAM_get_hostflags(const X509_VERIFY_PARAM *param);
char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
char *X509_VERIFY_PARAM_get0_peername(const X509_VERIFY_PARAM *param);
int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
const char *email, size_t emaillen);
int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
doc/man3/X509_check_ca.pod
+2
View File
@@ -24,6 +24,8 @@ B<keyUsage> extension with bit B<keyCertSign> set, but without
B<basicConstraints>, and 5 if it has outdated Netscape Certificate Type
extension telling that it is CA certificate.
This function will also return 0 on error.
Actually, any nonzero value means that this certificate could have been
used to sign other certificates.
doc/man3/X509_check_purpose.pod
+74
View File
@@ -0,0 +1,74 @@
=pod
=head1 NAME
X509_check_purpose - Check the purpose of a certificate
=head1 SYNOPSIS
#include <openssl/x509v3.h>
int X509_check_purpose(X509 *x, int id, int ca)
=head1 DESCRIPTION
This function checks if certificate I<x> was created with the purpose
represented by I<id>. If I<ca> is nonzero, then certificate I<x> is
checked to determine if it's a possible CA with various levels of certainty
possibly returned.
Below are the potential ID's that can be checked:
# define X509_PURPOSE_SSL_CLIENT 1
# define X509_PURPOSE_SSL_SERVER 2
# define X509_PURPOSE_NS_SSL_SERVER 3
# define X509_PURPOSE_SMIME_SIGN 4
# define X509_PURPOSE_SMIME_ENCRYPT 5
# define X509_PURPOSE_CRL_SIGN 6
# define X509_PURPOSE_ANY 7
# define X509_PURPOSE_OCSP_HELPER 8
# define X509_PURPOSE_TIMESTAMP_SIGN 9
=head1 RETURN VALUES
For non-CA checks
=over 4
=item -1 an error condition has occured
=item E<32>1 if the certificate was created to perform the purpose represented by I<id>
=item E<32>0 if the certificate was not created to perform the purpose represented by I<id>
=back
For CA checks the below integers could be returned with the following meanings:
=over 4
=item -1 an error condition has occured
=item E<32>0 not a CA or does not have the purpose represented by I<id>
=item E<32>1 is a CA.
=item E<32>2 Only possible in old versions of openSSL when basicConstraints are absent.
New versions will not return this value. May be a CA
=item E<32>3 basicConstraints absent but self signed V1.
=item E<32>4 basicConstraints absent but keyUsage present and keyCertSign asserted.
=item E<32>5 legacy Netscape specific CA Flags present
=back
=head1 COPYRIGHT
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 L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/X509_digest.pod
+15 -2
View File
@@ -2,7 +2,9 @@
=head1 NAME
X509_digest, X509_CRL_digest,
X509_digest,
X509_digest_sig,
X509_CRL_digest,
X509_pubkey_digest,
X509_NAME_digest,
X509_REQ_digest,
@@ -15,6 +17,7 @@ PKCS7_ISSUER_AND_SERIAL_digest
int X509_digest(const X509 *data, const EVP_MD *type, unsigned char *md,
unsigned int *len);
ASN1_OCTET_STRING *X509_digest_sig(const X509 *cert);
int X509_CRL_digest(const X509_CRL *data, const EVP_MD *type, unsigned char *md,
unsigned int *len);
@@ -36,8 +39,12 @@ PKCS7_ISSUER_AND_SERIAL_digest
=head1 DESCRIPTION
X509_digest_sig() calculates a digest of the given certificate
using the same hash algorithm as in its signature.
X509_pubkey_digest() returns a digest of the DER representation of the public
key in the specified X509 B<data> object.
All other functions described here return a digest of the DER representation
of their entire B<data> objects.
@@ -49,12 +56,18 @@ to a place where the digest size will be stored.
=head1 RETURN VALUES
All functions described here return 1 for success and 0 for failure.
X509_digest_sig() returns an ASN1_OCTET_STRING on success, else NULL.
All other functions described here return 1 for success and 0 for failure.
=head1 SEE ALSO
L<EVP_sha1(3)>
=head1 HISTORY
The X509_digest_sig() function was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/X509_dup.pod
+4
View File
@@ -122,13 +122,17 @@ OCSP_SIGNATURE_free,
OCSP_SIGNATURE_new,
OCSP_SINGLERESP_free,
OCSP_SINGLERESP_new,
OSSL_CMP_ITAV_dup,
OSSL_CMP_ITAV_free,
OSSL_CMP_MSG_dup,
OSSL_CMP_MSG_it,
OSSL_CMP_MSG_free,
OSSL_CMP_PKIHEADER_free,
OSSL_CMP_PKIHEADER_it,
OSSL_CMP_PKIHEADER_new,
OSSL_CMP_PKISI_dup,
OSSL_CMP_PKISI_free,
OSSL_CMP_PKISI_it,
OSSL_CMP_PKISI_new,
OSSL_CMP_PKISTATUS_it,
OSSL_CRMF_CERTID_free,
doc/man3/X509_get0_distinguishing_id.pod
+71
View File
@@ -0,0 +1,71 @@
=pod
=head1 NAME
X509_get0_distinguishing_id, X509_set0_distinguishing_id,
X509_REQ_get0_distinguishing_id, X509_REQ_set0_distinguishing_id
- get or set the Distinguishing ID for certificate operations
=head1 SYNOPSIS
#include <openssl/x509.h>
ASN1_OCTET_STRING *X509_get0_distinguishing_id(X509 *x);
void X509_set0_distinguishing_id(X509 *x, ASN1_OCTET_STRING *distid);
ASN1_OCTET_STRING *X509_REQ_get0_distinguishing_id(X509_REQ *x);
void X509_REQ_set0_distinguishing_id(X509_REQ *x, ASN1_OCTET_STRING *distid);
=head1 DESCRIPTION
The Distinguishing ID is defined in FIPS 196 as follows:
=over 4
I<Distinguishing identifier>: information which unambiguously distinguishes
an entity in the authentication process.
=back
The SM2 signature algorithm requires a Distinguishing ID value when generating
and verifying a signature, but the Ddistinguishing ID may also find other uses.
In the context of SM2, the Distinguishing ID is often referred to as the "SM2
ID".
For the purpose off verifying a certificate or a certification request, a
Distinguishing ID may be attached to it, so functions like L<X509_verify(3)>
or L<X509_REQ_verify(3)> have easy access to that identity for signature
verification.
X509_get0_distinguishing_id() gets the Distinguishing ID value of a certificate
B<x> by returning an B<ASN1_OCTET_STRING> object which should not be freed by
the caller.
X509_set0_distinguishing_id() assigns B<distid> to the certificate B<x>.
Calling this function transfers the memory management of the value to the X509
object, and therefore the value that has been passed in should not be freed by
the caller after this function has been called.
X509_REQ_get0_distinguishing_id() and X509_REQ_set0_distinguishing_id()
have the same functionality as X509_get0_distinguishing_id() and
X509_set0_distinguishing_id() except that they deal with B<X509_REQ>
objects instead of B<X509>.
=head1 RETURN VALUES
X509_set0_distinguishing_id() and X509_REQ_set0_distinguishing_id() do not
return a value.
=head1 SEE ALSO
L<X509_verify(3)>, L<SM2(7)>
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/X509_get0_sm2_id.pod
-55
View File
@@ -1,55 +0,0 @@
=pod
=head1 NAME
X509_get0_sm2_id, X509_set0_sm2_id,
X509_REQ_get0_sm2_id, X509_REQ_set0_sm2_id
- get or set SM2 ID for certificate operations
=head1 SYNOPSIS
#include <openssl/x509.h>
ASN1_OCTET_STRING *X509_get0_sm2_id(X509 *x);
void X509_set0_sm2_id(X509 *x, ASN1_OCTET_STRING *sm2_id);
ASN1_OCTET_STRING *X509_REQ_get0_sm2_id(X509_REQ *x);
void X509_REQ_set0_sm2_id(X509_REQ *x, ASN1_OCTET_STRING *sm2_id);
=head1 DESCRIPTION
X509_get0_sm2_id() gets the ID value of an SM2 certificate B<x> by returning an
B<ASN1_OCTET_STRING> object which should not be freed by the caller.
X509_set0_sm2_id() sets the B<sm2_id> value to an SM2 certificate B<x>. Calling
this function transfers the memory management of the value to the X509 object,
and therefore the value that has been passed in should not be freed by the
caller after this function has been called.
X509_REQ_get0_sm2_id() and X509_REQ_set0_sm2_id() have the same functionality
as X509_get0_sm2_id() and X509_set0_sm2_id() except that they deal with
B<X509_REQ> objects instead of B<X509>.
=head1 NOTES
SM2 signature algorithm requires an ID value when generating and verifying a
signature. The functions described in this manual provide the user with the
ability to set and retrieve the SM2 ID value.
=head1 RETURN VALUES
X509_set0_sm2_id() and X509_REQ_set0_sm2_id() do not return a value.
=head1 SEE ALSO
L<X509_verify(3)>, L<SM2(7)>
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/X509_get_extension_flags.pod
+12 -1
View File
@@ -80,6 +80,17 @@ The certificate contains an unhandled critical extension.
Some certificate extension values are invalid or inconsistent. The
certificate should be rejected.
This bit may also be raised after an out-of-memory error while
processing the X509 object, so it may not be related to the processed
ASN1 object itself.
=item B<EXFLAG_INVALID_POLICY>
The NID_certificate_policies certificate extension is invalid or
inconsistent. The certificate should be rejected.
This bit may also be raised after an out-of-memory error while
processing the X509 object, so it may not be related to the processed
ASN1 object itself.
=item B<EXFLAG_KUSAGE>
@@ -183,7 +194,7 @@ X509_get_proxy_pathlen() were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/X509_get_subject_name.pod
+4 -4
View File
@@ -12,16 +12,16 @@ subject names
#include <openssl/x509.h>
X509_NAME *X509_get_subject_name(const X509 *x);
int X509_set_subject_name(X509 *x, X509_NAME *name);
int X509_set_subject_name(X509 *x, const X509_NAME *name);
X509_NAME *X509_get_issuer_name(const X509 *x);
int X509_set_issuer_name(X509 *x, X509_NAME *name);
int X509_set_issuer_name(X509 *x, const X509_NAME *name);
X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req);
int X509_REQ_set_subject_name(X509_REQ *req, X509_NAME *name);
int X509_REQ_set_subject_name(X509_REQ *req, const X509_NAME *name);
X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl);
int X509_CRL_set_issuer_name(X509_CRL *x, X509_NAME *name);
int X509_CRL_set_issuer_name(X509_CRL *x, const X509_NAME *name);
=head1 DESCRIPTION
doc/man3/X509v3_cache_extensions.pod
+43
View File
@@ -0,0 +1,43 @@
=pod
=head1 NAME
X509v3_cache_extensions
- process any extensions in an X509 object
=head1 SYNOPSIS
#include <openssl/x509v3.h>
int X509v3_cache_extensions(X509 *x, OPENSSL_CTX *libctx, const char *propq);
=head1 DESCRIPTION
This function processes any X509v3 extensions that might be present in an X509
object and caches the result of that processing. Many OpenSSL functions that use
an X509 object will cause extensions to be processed and cached implicitly. If
this is done implicitly then the default library context and property query
string will be used. In some cases it may be desirable to use some other library
context and property query string. If so then an application can call
X509v3_cache_extensions() explicitly. This should be done before any function
that needs to use those extensions is called - otherwise calling
X509v3_cache_extensions() will have no effect. Typically this means calling this
soon after creation of the X509 object. The X509 object to be processed is
given in I<x> and the library context and property query string to use are given
in I<libctx> and I<propq>.
=head1 RETURN VALUES
This function returns 0 if the extensions are invalid or an error occurred.
Otherwise it returns 1.
=head1 COPYRIGHT
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
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/d2i_X509.pod
+2
View File
@@ -98,6 +98,7 @@ d2i_OCSP_SIGNATURE,
d2i_OCSP_SINGLERESP,
d2i_OSSL_CMP_MSG,
d2i_OSSL_CMP_PKIHEADER,
d2i_OSSL_CMP_PKISI,
d2i_OSSL_CRMF_CERTID,
d2i_OSSL_CRMF_CERTTEMPLATE,
d2i_OSSL_CRMF_ENCRYPTEDVALUE,
@@ -289,6 +290,7 @@ i2d_OCSP_SIGNATURE,
i2d_OCSP_SINGLERESP,
i2d_OSSL_CMP_MSG,
i2d_OSSL_CMP_PKIHEADER,
i2d_OSSL_CMP_PKISI,
i2d_OSSL_CRMF_CERTID,
i2d_OSSL_CRMF_CERTTEMPLATE,
i2d_OSSL_CRMF_ENCRYPTEDVALUE,