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

Latest update

Browse Source
This commit is contained in:
Hakase
2019-07-13 19:13:22 +09:00
parent 9a23f88dc2
commit 2e57f602ae
542 changed files with 17287 additions and 6184 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/HOWTO/proxy_certificates.txt
+1 -1
View File
@@ -255,7 +255,7 @@ Here is some skeleton code you can fill in:
/*
* process_rights() is supposed to be a procedure
* that takes a string and it's length, interprets
* that takes a string and its length, interprets
* it and sets the bits in the YOUR_RIGHTS pointed
* at by the third argument.
*/
doc/internal/man3/evp_generic_fetch.pod
+6 -6
View File
@@ -13,7 +13,7 @@ evp_generic_fetch - generic algorithm fetcher and method creator for EVP
const char *name, const char *properties,
void *(*new_method)(const OSSL_DISPATCH *fns,
OSSL_PROVIDER *prov),
int (*upref_method)(void *),
int (*up_ref_method)(void *),
void (*free_method)(void *));
=head1 DESCRIPTION
@@ -21,7 +21,7 @@ evp_generic_fetch - generic algorithm fetcher and method creator for EVP
evp_generic_fetch() calls ossl_method_construct() with the given
C<libctx>, C<operation_id>, C<name>, and C<properties> and uses
it to create an EVP method with the help of the functions
C<new_method>, C<upref_method>, and C<free_method>.
C<new_method>, C<up_ref_method>, and C<free_method>.
The three functions are supposed to:
@@ -32,7 +32,7 @@ The three functions are supposed to:
creates an internal method from function pointers found in the
dispatch table C<fns>.
=item upref_method()
=item up_ref_method()
increments the reference counter for the given method, if there is
one.
@@ -116,7 +116,7 @@ And here's the implementation of the FOO method fetcher:
}
foo->prov = prov;
if (prov)
ossl_provider_upref(prov);
ossl_provider_up_ref(prov);
return foo;
}
@@ -137,7 +137,7 @@ And here's the implementation of the FOO method fetcher:
return EVP_FOO_meth_from_dispatch(fns, prov);
}
static int foo_upref(void *vfoo)
static int foo_up_ref(void *vfoo)
{
EVP_FOO *foo = vfoo;
int ref = 0;
@@ -157,7 +157,7 @@ And here's the implementation of the FOO method fetcher:
{
EVP_FOO *foo =
evp_generic_fetch(ctx, OSSL_OP_FOO, name, properties,
foo_from_dispatch, foo_upref, foo_free);
foo_from_dispatch, foo_up_ref, foo_free);
/*
* If this method exists in legacy form, with a constant NID for the
doc/internal/man3/openssl_ctx_get_data.pod
+1 -1
View File
@@ -29,7 +29,7 @@ as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the
library to be added and removed dynamically.
Each such data item must have a corresponding CRYPTO_EX_DATA index
associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes
to identify data items. These are mapped transparetnly to CRYPTO_EX_DATA dynamic
to identify data items. These are mapped transparently to CRYPTO_EX_DATA dynamic
indexes internally to the implementation.
See the example further down to see how that's done.
doc/internal/man3/ossl_init_thread_deregister.pod
+66
View File
@@ -0,0 +1,66 @@
=pod
=head1 NAME
OSSL_thread_stop_handler_fn,
ossl_init_thread_start,
ossl_init_thread_deregister
- internal thread routines
=head1 SYNOPSIS
#include "internal/cryptlib_int.h"
#include <openssl/core.h>
typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
int ossl_init_thread_start(const void *index, void *arg,
OSSL_thread_stop_handler_fn handfn);
int ossl_init_thread_deregister(void *index);
=head1 DESCRIPTION
Thread aware code may be informed about when a thread is stopping, typically to
perform some cleanup operation.
Thread stop events may be detected by OpenSSL either automatically (using the
capabilities of the underlying threading library) where possible or explicitly
by the application calling OPENSSL_thread_stop() or OPENSSL_thread_stop_ex().
Thread aware code registers a "stop handler" for each new thread that it uses.
Typically, when a new thread is being used, code will add a new value to some
thread local variable and then register a stop handler. When the thread is
stopping the stop handler is called (while on that thread) and the code can
clean up the value stored in the thread local variable.
A new stop handler is registerd using the function ossl_init_thread_start().
The B<index> parameter should be a unique value that can be used to identify a
set of common stop handlers and is passed in a later call to
ossl_init_thread_deregister. If no later call to ossl_init_thread_deregister is
made then NULL can be passed for this parameter. The B<arg> parameter is passed
back as an argument to the stop handler when it is later invoked. Finally the
B<handfn> is a function pointer to the stop handler itself.
In the event that previously registered stop handlers need to be deregistered
then this can be done using the function ossl_init_thread_deregister().
This will deregister all stop handlers (no matter which thread they were
registered for) which the same B<index> value.
=head1 RETURN VALUES
ossl_init_thread_start() and ossl_init_thread_deregister() return 1 for success
or 0 on error.
=head1 HISTORY
The functions described here were all added in OpenSSL 3.0.
=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/internal/man3/ossl_method_construct.pod
+42 -27
View File
@@ -15,11 +15,13 @@ OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
/* Remove a store */
void (*dealloc_tmp_store)(void *store);
/* Get an already existing method from a store */
void *(*get)(OPENSSL_CTX *libctx, void *store, const char *name,
const char *propquery, void *data);
void *(*get)(OPENSSL_CTX *libctx, void *store,
int operation_id, const char *name, const char *propquery,
void *data);
/* Store a method in a store */
int (*put)(OPENSSL_CTX *libctx, void *store, void *method,
const char *name, const char *propdef, void *data);
int operation_id, const char *name, const char *propdef,
void *data);
/* Construct a new method */
void *(*construct)(const char *name, const OSSL_DISPATCH *fns,
OSSL_PROVIDER *prov, void *data);
@@ -41,13 +43,25 @@ on provider dispatch tables need to do so in exactly the same way.
ossl_method_construct() does this while leaving it to the sub-systems
to define more precisely how the methods are created, stored, etc.
It's important to keep in mind that a method is identified by three things:
=over 4
=item The operation identity
=item The name of the algorithm
=item The properties associated with the algorithm implementation
=back
=head2 Functions
ossl_method_construct() creates a method by asking all available
providers for a dispatch table given an C<operation_id>, an algorithm
C<name> and a set of C<properties>, and then calling appropriate
providers for a dispatch table given an I<operation_id>, an algorithm
I<name> and a set of I<properties>, and then calling the appropriate
functions given by the sub-system specific method creator through
C<mcm> and the data in C<mcm_data> (which is passed by
I<mcm> and the data in I<mcm_data> (which is passed by
ossl_method_construct()).
This function assumes that the sub-system method creator implements
@@ -59,14 +73,14 @@ appropriate).
A central part of constructing a sub-system specific method is to give
ossl_method_construct a set of functions, all in the
C<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
B<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following
function pointers:
=over 4
=item alloc_tmp_store()
Create a temporary method store in the scope of the library context C<ctx>.
Create a temporary method store in the scope of the library context I<ctx>.
This store is used to temporarily store methods for easier lookup, for
when the provider doesn't want its dispatch table stored in a longer
term cache.
@@ -79,50 +93,51 @@ Remove a temporary store.
Look up an already existing method from a store by name.
The store may be given with C<store>.
The store may be given with I<store>.
B<NULL> is a valid value and means that a sub-system default store
must be used.
This default store should be stored in the library context C<libctx>.
This default store should be stored in the library context I<libctx>.
The method to be looked up should be identified with the given C<name> and
data from C<data>
(which is the C<mcm_data> that was passed to ossl_construct_method())
and the provided property query C<propquery>.
The method to be looked up should be identified with the given
I<operation_id>, I<name>, the provided property query I<propquery>
and data from I<data> (which is the I<mcm_data> that was passed to
ossl_construct_method()).
This function is expected to increment the method's reference count.
=item put()
Places the C<method> created by the construct() function (see below)
Places the I<method> created by the construct() function (see below)
in a store.
The store may be given with C<store>.
The store may be given with I<store>.
B<NULL> is a valid value and means that a sub-system default store
must be used.
This default store should be stored in the library context C<libctx>.
This default store should be stored in the library context I<libctx>.
The method should be associated with the given C<name> and property definition
C<propdef> as well as any identification data given through C<data> (which is
the C<mcm_data> that was passed to ossl_construct_method()).
The method should be associated with the given I<operation_id>,
I<name> and property definition I<propdef> as well as any
identification data given through I<data> (which is the I<mcm_data>
that was passed to ossl_construct_method()).
This function is expected to increment the C<method>'s reference count.
This function is expected to increment the I<method>'s reference count.
=item construct()
Constructs a sub-system method for the given C<name> and the given
dispatch table C<fns>.
Constructs a sub-system method for the given I<name> and the given
dispatch table I<fns>.
The associated I<provider object> C<prov> is passed as well, to make
The associated provider object I<prov> is passed as well, to make
it possible for the sub-system constructor to keep a reference, which
is recommended.
If such a reference is kept, the I<provider object> reference counter
must be incremented, using ossl_provider_upref().
must be incremented, using ossl_provider_up_ref().
This function is expected to set the method's reference count to 1.
=item desctruct()
=item destruct()
Decrement the C<method>'s reference count, and destruct it when
Decrement the I<method>'s reference count, and destruct it when
the reference count reaches zero.
=back
doc/internal/man3/ossl_namemap_new.pod
+33 -13
View File
@@ -3,7 +3,7 @@
=head1 NAME
ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored,
ossl_namemap_add, ossl_namemap_name, ossl_namemap_number
ossl_namemap_add, ossl_namemap_name2num, ossl_namemap_doall_names
- internal number E<lt>-E<gt> name map
=head1 SYNOPSIS
@@ -15,15 +15,18 @@ ossl_namemap_add, ossl_namemap_name, ossl_namemap_number
OSSL_NAMEMAP *ossl_namemap_new(void);
void ossl_namemap_free(OSSL_NAMEMAP *namemap);
int ossl_namemap_add(OSSL_NAMEMAP *namemap, const char *name);
const char *ossl_namemap_name(const OSSL_NAMEMAP *namemap, int number);
int ossl_namemap_number(const OSSL_NAMEMAP *namemap, const char *name);
int ossl_namemap_add(OSSL_NAMEMAP *namemap, int number, const char *name);
int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name);
void ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
void (*fn)(const char *name, void *data),
void *data);
=head1 DESCRIPTION
A B<OSSL_NAMEMAP> is a simple number E<lt>-E<gt> name map, which can
be used to give any arbitrary name (any string) a unique dynamic
identity that is valid throughout the lifetime of the associated
A B<OSSL_NAMEMAP> is a one-to-many number E<lt>-E<gt> names map, which
can be used to give any arbitrary set of names (any string) a unique
dynamic identity that is valid throughout the lifetime of the associated
library context.
ossl_namemap_new() and ossl_namemap_free() construct and destruct a
@@ -38,11 +41,19 @@ ossl_namemap_free().
ossl_namemap_add() adds a new name to the namemap if it's not already
present.
If the given I<number> is zero, a new number will be allocated to
identify this I<name>.
If the given I<number> is non-zero, the I<name> is added to the set of
names already associated with that number.
ossl_namemap_name() finds the name corresponding to the given number.
ossl_namemap_name2num() finds the number corresponding to the given
I<name>.
ossl_namemap_number() finds the number corresponding to the given
name.
ossl_namemap_doall_names() walks through all names associated with
I<number> in the given I<namemap> and calls the function I<fn> for
each of them.
I<fn> is also passed the I<data> argument, which allows any caller to
pass extra data for that function to use.
=head1 RETURN VALUES
@@ -52,12 +63,21 @@ B<OSSL_NAMEMAP>, or NULL on error.
ossl_namemap_add() returns the number associated with the added
string, or zero on error.
ossl_namemap_name() returns a pointer to the name corresponding to the
given number, or NULL if it's undefined in the given B<OSSL_NAMEMAP>.
ossl_namemap_num2names() returns a pointer to a NULL-terminated list of
pointers to the names corresponding to the given number, or NULL if
it's undefined in the given B<OSSL_NAMEMAP>.
ossl_namemap_number() returns the number corresponding to the given
ossl_namemap_name2num() returns the number corresponding to the given
name, or 0 if it's undefined in the given B<OSSL_NAMEMAP>.
=head1 NOTES
The result from ossl_namemap_num2names() isn't thread safe, other threads
dealing with the same namemap may cause the list of names to change
location.
It is therefore strongly recommended to only use the result in code
guarded by a thread lock.
=head1 HISTORY
The functions described here were all added in OpenSSL 3.0.
doc/internal/man3/ossl_prov_util_nid_to_name.pod
+35
View File
@@ -0,0 +1,35 @@
=pod
=head1 NAME
ossl_prov_util_nid_to_name
- provider utility functions
=head1 SYNOPSIS
#include "internal/providercommon.h"
const char *ossl_prov_util_nid_to_name(int nid);
=head1 DESCRIPTION
The ossl_prov_util_nid_to_name() returns the name of an algorithm given a NID
in the B<nid> parameter. For the default and legacy providers it is equivalent
to calling OBJ_nid2sn(). The FIPS provider does not have the object database
code available to it (because that code relies on the ASN.1 code), so this
function is a static lookup of all known FIPS algorithm NIDs.
=head1 RETURN VALUES
Returns a pointer to the algorithm name, or NULL on error.
=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/internal/man3/ossl_provider_add_conf_module.pod
+41
View File
@@ -0,0 +1,41 @@
=pod
=head1 NAME
ossl_provider_add_conf_module - internal standard configuration module
=head1 SYNOPSIS
#include "internal/provider.h"
/* Configuration */
void ossl_provider_add_conf_module(void);
=head1 DESCRIPTION
ossl_provider_add_conf_module() adds the standard configuration module
for providers.
This allows providers to be configured with an OpenSSL L<config(5)> file.
=head1 RETURN VALUES
ossl_provider_add_conf_module() doesn't return any value.
=head1 SEE ALSO
L<OSSL_PROVIDER(3)>, L<ossl_provider_new(3)>
=head1 HISTORY
The functions described here were all added in OpenSSL 3.0.
=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/internal/man3/ossl_provider_new.pod
+96 -66
View File
@@ -2,10 +2,13 @@
=head1 NAME
ossl_provider_find, ossl_provider_new, ossl_provider_upref,
ossl_provider_free, ossl_provider_add_module_location,
ossl_provider_set_fallback, ossl_provider_activate,
ossl_provider_ctx, ossl_provider_forall_loaded,
ossl_provider_find, ossl_provider_new, ossl_provider_up_ref,
ossl_provider_free,
ossl_provider_set_fallback, ossl_provider_set_module_path,
ossl_provider_add_parameter,
ossl_provider_activate,
ossl_provider_ctx,
ossl_provider_forall_loaded,
ossl_provider_name, ossl_provider_dso,
ossl_provider_module_name, ossl_provider_module_path,
ossl_provider_teardown, ossl_provider_get_param_types,
@@ -19,12 +22,14 @@ ossl_provider_get_params, ossl_provider_query_operation
OSSL_PROVIDER *ossl_provider_find(OPENSSL_CTX *libctx, const char *name);
OSSL_PROVIDER *ossl_provider_new(OPENSSL_CTX *libctx, const char *name,
ossl_provider_init_fn *init_function);
int ossl_provider_upref(OSSL_PROVIDER *prov);
int ossl_provider_up_ref(OSSL_PROVIDER *prov);
void ossl_provider_free(OSSL_PROVIDER *prov);
/* Setters */
int ossl_provider_add_module_location(OSSL_PROVIDER *prov, const char *loc);
int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
int ossl_provider_set_module_path(OSSL_PROVIDER *prov, const char *path);
int ossl_provider_add_parameter(OSSL_PROVIDER *prov, const char *name,
const char *value);
/* Load and initialize the Provider */
int ossl_provider_activate(OSSL_PROVIDER *prov);
@@ -47,65 +52,84 @@ ossl_provider_get_params, ossl_provider_query_operation
/* Thin wrappers around calls to the provider */
void ossl_provider_teardown(const OSSL_PROVIDER *prov);
const OSSL_ITEM *ossl_provider_get_param_types(const OSSL_PROVIDER *prov);
int ossl_provider_get_params(const OSSL_PROVIDER *prov,
const OSSL_PARAM params[]);
int ossl_provider_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
int operation_id,
int *no_cache);
=head1 DESCRIPTION
C<OSSL_PROVIDER> is a type that holds all the necessary information
I<OSSL_PROVIDER> is a type that holds all the necessary information
to handle a provider, regardless of if it's built in to the
application or the OpenSSL libraries, or if it's a loadable provider
module.
Instances of this type are commonly refered to as I<provider object>s.
Instances of this type are commonly referred to as "provider objects".
A I<provider object> is always stored in a set of I<provider object>s
A provider object is always stored in a set of provider objects
in the library context.
I<provider object>s are reference counted.
Provider objects are reference counted.
I<provider object>s are initially inactive, i.e. they are only
recorded in the store, but are not used.
Provider objects are initially inactive, i.e. they are only recorded
in the store, but are not used.
They are activated with the first call to ossl_provider_activate(),
and are inactivated when ossl_provider_free() has been called as many
times as ossl_provider_activate() has.
=head2 Functions
ossl_provider_find() finds an existing I<provider object> in the
I<provider object> store by C<name>.
The I<provider object> it finds gets its reference count
incremented.
ossl_provider_find() finds an existing provider object in the provider
object store by I<name>.
The provider object it finds has its reference count incremented.
ossl_provider_new() creates a new I<provider object> and stores it in
the I<provider object> store, unless there already is one there with
the same name.
The reference counter of a newly created I<provider object> will
always be 2; one for being added to the store, and one for the
returned reference.
To indicate a built-in provider, the C<init_function> argument must
point at the provider initialization function for that provider.
ossl_provider_new() creates a new provider object named I<name> and
stores it in the provider object store, unless there already is one
there with the same name.
If there already is one with the same name, it's returned with its
reference count incremented.
The reference count of a newly created provider object will always
be 2; one for being added to the store, and one for the returned
reference.
If I<init_function> is NULL, the provider is assumed to be a
dynamically loadable module, with the symbol B<OSSL_provider_init> as
its initialisation function.
If I<init_function> isn't NULL, the provider is assumed to be built
in, with I<init_function> being the pointer to its initialisation
function.
For further description of the initialisation function, see the
description of ossl_provider_activate() below.
ossl_provider_free() decrements a I<provider object>'s reference
counter; if it drops below 2, the I<provider object> is assumed to
have fallen out of use and will be inactivated (its teardown function
is called); if it drops down to zero, the I<provider object> is
assumed to have been taken out of the store, and the associated module
will be unloaded if one was loaded, and the I<provider object> will be
freed.
ossl_provider_up_ref() increments the provider object I<prov>'s
reference count.
ossl_provider_add_module_location() adds a location to look for a
provider module.
ossl_provider_free() decrements the provider object I<prov>'s
reference count; if it drops below 2, the provider object is assumed
to have fallen out of use and will be deactivated (its I<teardown>
function is called); if it drops down to zero, I<prov> is assumed to
have been taken out of the store, and the associated module will be
unloaded if one was loaded, and I<prov> itself will be freed.
ossl_provider_set_fallback() marks an available provider as fallback.
Note that after this call, the I<provider object> pointer that was
ossl_provider_set_fallback() marks an available provider I<prov> as
fallback.
Note that after this call, the provider object pointer that was
used can simply be dropped, but not freed.
ossl_provider_set_module_path() sets the module path to load the
provider module given the provider object I<prov>.
This will be used in preference to automatically trying to figure out
the path from the provider name and the default module directory (more
on this in L</NOTES>).
ossl_provider_add_parameter() adds a global parameter for the provider
to retrieve as it sees fit.
The parameters are a combination of I<name> and I<value>, and the
provider will use the name to find the value it wants.
Only text parameters can be given, and it's up to the provider to
interpret them.
ossl_provider_activate() "activates" the provider for the given
I<provider object>.
What "activates" means depends on what type of I<provider object> it
provider object I<prov>.
What "activates" means depends on what type of provider object it
is:
=over 4
@@ -117,9 +141,9 @@ function will get called.
=item *
If no intialization function was given with ossl_provider_new(), a
loadable module with the C<name> that was given to ossl_provider_new()
will be located and loaded, then the symbol C<OSSL_provider_init> will
If no initialization function was given with ossl_provider_new(), a
loadable module with the I<name> that was given to ossl_provider_new()
will be located and loaded, then the symbol B<OSSL_provider_init> will
be located in that module, and called.
=back
@@ -129,7 +153,7 @@ Outside of the provider, it's completely opaque, but it needs to be
passed back to some of the provider functions.
ossl_provider_forall_loaded() iterates over all the currently
"activated" providers, and calls C<cb> for each of them.
"activated" providers, and calls I<cb> for each of them.
If no providers have been "activated" yet, it tries to activate all
available fallback providers and tries another iteration.
@@ -145,23 +169,23 @@ providers that come in the form of loadable modules.
ossl_provider_module_path() returns the full path of the module file,
for providers that come in the form of loadable modules.
ossl_provider_teardown() calls the provider's C<teardown> function, if
ossl_provider_teardown() calls the provider's I<teardown> function, if
the provider has one.
ossl_provider_get_param_types() calls the provider's C<get_param_types>
ossl_provider_get_param_types() calls the provider's I<get_param_types>
function, if the provider has one.
It should return an array of C<OSSL_ITEM> to describe all the
parameters that the provider has for the I<provider object>.
It should return an array of I<OSSL_ITEM> to describe all the
parameters that the provider has for the provider object.
ossl_provider_get_params() calls the provider's parameter request
responder.
It should treat the given C<OSSL_PARAM> array as described in
It should treat the given I<OSSL_PARAM> array as described in
L<OSSL_PARAM(3)>.
ossl_provider_query_operation() calls the provider's
C<query_operation> function, if the provider has one.
It should return an array of C<OSSL_ALGORITHM> for the given
C<operation_id>.
I<query_operation> function, if the provider has one.
It should return an array of I<OSSL_ALGORITHM> for the given
I<operation_id>.
=head1 NOTES
@@ -171,50 +195,56 @@ Locating a provider module happens as follows:
=item 1.
Look in each directory given by ossl_provider_add_module_location().
If a path was given with ossl_provider_set_module_path(), use that as
module path.
Otherwise, use the provider object's name as module path, with
platform specific standard extensions added.
=item 2.
Look in the directory given by the environment variable
B<OPENSSL_MODULES>.
=item 3.
Look in the directory given by the OpenSSL built in macro
B<MODULESDIR>.
If the environment variable B<OPENSSL_MODULES> is defined, assume its
value is a directory specification and merge it with the module path.
Otherwise, merge the value of the OpenSSL built in macro B<MODULESDIR>
with the module path.
=back
When this process is done, the result is used when trying to load the
provider module.
The command C<openssl version -m> can be used to find out the value
of the built in macro B<MODULESDIR>.
=head1 RETURN VALUES
ossl_provider_find() and ossl_provider_new() return a pointer to a
I<provider object> (C<OSSL_PROVIDER>) on success, or B<NULL> on error.
provider object (I<OSSL_PROVIDER>) on success, or NULL on error.
ossl_provider_upref() returns the value of the reference counter after
ossl_provider_up_ref() returns the value of the reference count after
it has been incremented.
ossl_provider_free() doesn't return any value.
ossl_provider_add_module_location(), ossl_provider_set_fallback() and
ossl_provider_set_module_path(), ossl_provider_set_fallback() and
ossl_provider_activate() return 1 on success, or 0 on error.
ossl_provider_name(), ossl_provider_dso(),
ossl_provider_module_name(), and ossl_provider_module_path() return a
pointer to their respective data if it's available, otherwise B<NULL>
pointer to their respective data if it's available, otherwise NULL
is returned.
ossl_provider_teardown() doesnt't return any value.
ossl_provider_get_param_types() returns a pointer to an C<OSSL_ITEM>
ossl_provider_get_param_types() returns a pointer to an I<OSSL_ITEM>
array if this function is available in the provider, otherwise
B<NULL>.
NULL.
ossl_provider_get_params() returns 1 on success, or 0 on error.
If this function isn't available in the provider, 0 is returned.
=head1 SEE ALSO
L<OSSL_PROVIDER(3)>, L<provider(7)>
L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>
=head1 HISTORY
doc/internal/man3/rand_bytes_ex.pod
+41
View File
@@ -0,0 +1,41 @@
=pod
=head1 NAME
rand_bytes_ex, rand_priv_bytes_ex
- internal random number routines
=head1 SYNOPSIS
#include "internal/rand_int.h"
int rand_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
int rand_priv_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
=head1 DESCRIPTION
rand_bytes_ex() and rand_priv_bytes_ex() are the equivalent of RAND_bytes() and
RAND_priv_bytes() in the public API except that they both take an additional
B<ctx> parameter.
The DRBG used for the operation is the public or private DRBG associated with
the specified B<ctx>. The parameter can be NULL, in which case
the default library ctx is used.
If the default RAND_METHOD has been changed then for compatibility reasons the
RAND_METHOD will be used in preference and the DRBG of the library context
ignored.
=head1 RETURN VALUES
rand_bytes_ex() and rand_bytes_priv_ex() return 0 or less on error or 1 on
success.
=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/man1/ca.pod
+16
View File
@@ -57,6 +57,8 @@ B<openssl> B<ca>
[B<-multivalue-rdn>]
[B<-rand file...>]
[B<-writerand file>]
[B<-sm2-id string>]
[B<-sm2-hex-id hex-string>]
=head1 DESCRIPTION
@@ -303,6 +305,16 @@ all others.
Writes random data to the specified I<file> upon exit.
This can be used with a subsequent B<-rand> flag.
=item B<-sm2-id>
Specify the ID string to use when verifying an SM2 certificate. The ID string is
required by the SM2 signature algorithm for signing and verification.
=item B<-sm2-hex-id>
Specify a binary ID string to use when signing or verifying using an SM2
certificate. The argument for this option is string of hexadecimal digits.
=back
=head1 CRL OPTIONS
@@ -600,6 +612,10 @@ Sign a certificate request:
openssl ca -in req.pem -out newcert.pem
Sign an SM2 certificate request:
openssl ca -in sm2.csr -out sm2.crt -md sm3 -sigopt "sm2_id:1234567812345678" -sm2-id "1234567812345678"
Sign a certificate request, using CA extensions:
openssl ca -in req.pem -extensions v3_ca -out newcert.pem
doc/man1/kdf.pod
+1
View File
@@ -150,6 +150,7 @@ L<EVP_KDF_PBKDF2(7)>
L<EVP_KDF_HKDF(7)>
L<EVP_KDF_SS(7)>
L<EVP_KDF_SSHKDF(7)>
L<pkeyutl(1)>
=head1 HISTORY
doc/man1/mac.pod
+1 -1
View File
@@ -76,7 +76,7 @@ To see the list of supported digests, use the command I<list -digest-commands>.
=item B<cipher:string>
Used by CMAC and GMAC to specifiy the cipher algorithm.
Used by CMAC and GMAC to specify the cipher algorithm.
For CMAC it must be one of AES-128-CBC, AES-192-CBC, AES-256-CBC or
DES-EDE3-CBC.
For GMAC it should be a GCM mode cipher e.g. AES-128-GCM.
doc/man1/pkeyutl.pod
+2 -1
View File
@@ -395,7 +395,8 @@ Verify some data using an L<SM2(7)> certificate and a specific ID:
L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)>,
L<kdf(1)>
=head1 COPYRIGHT
doc/man1/req.pod
+21
View File
@@ -50,6 +50,8 @@ B<openssl> B<req>
[B<-batch>]
[B<-verbose>]
[B<-engine id>]
[B<-sm2-id string>]
[B<-sm2-hex-id hex-string>]
=head1 DESCRIPTION
@@ -339,6 +341,16 @@ for all available algorithms.
Specifies an engine (by its unique B<id> string) which would be used
for key generation operations.
=item B<-sm2-id>
Specify the ID string to use when verifying an SM2 certificate. The ID string is
required by the SM2 signature algorithm for signing and verification.
=item B<-sm2-hex-id>
Specify a binary ID string to use when signing or verifying using an SM2
certificate. The argument for this option is string of hexadecimal digits.
=back
=head1 CONFIGURATION FILE FORMAT
@@ -534,6 +546,15 @@ Generate a self signed root certificate:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
Create an SM2 private key and then generate a certificate request from it:
openssl ecparam -genkey -name SM2 -out sm2.key
openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "sm2_id:1234567812345678"
Examine and verify an SM2 certificate request:
openssl req -verify -in sm2.csr -sm3 -sm2-id 1234567812345678
Example of a file pointed to by the B<oid_file> option:
1.2.3.4 shortName A longer Name
doc/man1/ts.pod
+8 -7
View File
@@ -170,7 +170,7 @@ in use. (Optional)
The message digest to apply to the data file.
Any digest supported by the OpenSSL B<dgst> command can be used.
The default is SHA-1. (Optional)
The default is SHA-256. (Optional)
=item B<-tspolicy> object_id
@@ -518,7 +518,7 @@ included. Default is no. (Optional)
=item B<ess_cert_id_alg>
This option specifies the hash function to be used to calculate the TSA's
public key certificate identifier. Default is sha1. (Optional)
public key certificate identifier. Default is sha256. (Optional)
=back
@@ -530,8 +530,9 @@ openssl/apps/openssl.cnf will do.
=head2 Time Stamp Request
To create a time stamp request for design1.txt with SHA-1
without nonce and policy and no certificate is required in the response:
To create a time stamp request for design1.txt with SHA-256 digest,
without nonce and policy, and without requirement for a certificate
in the response:
openssl ts -query -data design1.txt -no_nonce \
-out design1.tsq
@@ -546,12 +547,12 @@ To print the content of the previous request in human readable format:
openssl ts -query -in design1.tsq -text
To create a time stamp request which includes the MD-5 digest
of design2.txt, requests the signer certificate and nonce,
To create a time stamp request which includes the SHA-512 digest
of design2.txt, requests the signer certificate and nonce, and
specifies a policy id (assuming the tsa_policy1 name is defined in the
OID section of the config file):
openssl ts -query -data design2.txt -md5 \
openssl ts -query -data design2.txt -sha512 \
-tspolicy tsa_policy1 -cert -out design2.tsq
=head2 Time Stamp Response
doc/man3/ADMISSIONS.pod
+1 -1
View File
@@ -130,7 +130,7 @@ ADMISSION_SYNTAX_set0_contentsOfAdmissions()
functions free any existing value and set the pointer to the specified value.
The B<ADMISSION> type has an authority name, authority object, and a
stack of B<PROFSSION_INFO> items.
stack of B<PROFESSION_INFO> items.
The ADMISSIONS_get0_admissionAuthority(), ADMISSIONS_get0_namingAuthority(),
and ADMISSIONS_get0_professionInfos()
functions return pointers to those values within the object.
doc/man3/BIO_connect.pod
+1 -1
View File
@@ -24,7 +24,7 @@ but is present for future use.
BIO_bind() binds the source address and service to a socket and
may be useful before calling BIO_connect(). The options may include
B<BIO_SOCK_REUSADDR>, which is described in L</FLAGS> below.
B<BIO_SOCK_REUSEADDR>, which is described in L</FLAGS> below.
BIO_connect() connects B<sock> to the address and service given by
B<addr>. Connection B<options> may be zero or any combination of
doc/man3/BIO_s_mem.pod
+18 -8
View File
@@ -41,9 +41,10 @@ If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
BUF_MEM structure is also freed.
Calling BIO_reset() on a read write memory BIO clears any data in it if the
flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag
BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and
the data can be read again.
flag BIO_FLAGS_NONCLEAR_RST is not set, otherwise it just restores the read
pointer to the state it was just after the last write was performed and the
data can be read again. On a read only BIO it similarly restores the BIO to
its original state and the read only data can be read again.
BIO_eof() is true if no data is in the BIO.
@@ -79,11 +80,11 @@ first, so the supplied area of memory must be unchanged until the BIO is freed.
Writes to memory BIOs will always succeed if memory is available: that is
their size can grow indefinitely.
Every read from a read write memory BIO will remove the data just read with
an internal copy operation, if a BIO contains a lot of data and it is
read in small chunks the operation can be very slow. The use of a read only
memory BIO avoids this problem. If the BIO must be read write then adding
a buffering BIO to the chain will speed up the process.
Every write after partial read (not all data in the memory buffer was read)
to a read write memory BIO will have to move the unread data with an internal
copy operation, if a BIO contains a lot of data and it is read in small
chunks intertwined with writes the operation can be very slow. Adding
a buffering BIO to the chain can speed up the process.
Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
give undefined results, including perhaps a program crash.
@@ -104,6 +105,15 @@ BIO is set to BIO_NOCLOSE, before freeing the BUF_MEM the data pointer
in it must be set to NULL as the data pointer does not point to an
allocated memory.
Calling BIO_reset() on a read write memory BIO with BIO_FLAGS_NONCLEAR_RST
flag set can have unexpected outcome when the reads and writes to the
BIO are intertwined. As documented above the BIO will be reset to the
state after the last completed write operation. The effects of reads
preceding that write operation cannot be undone.
Calling BIO_get_mem_ptr() prior to a BIO_reset() call with
BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation.
=head1 BUGS
There should be an option to set the maximum size of a memory BIO.
doc/man3/BN_CTX_new.pod
+14 -4
View File
@@ -2,14 +2,17 @@
=head1 NAME
BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX_new_ex, BN_CTX_new, BN_CTX_secure_new_ex, BN_CTX_secure_new, BN_CTX_free
- allocate and free BN_CTX structures
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_CTX *BN_CTX_new_ex(OPENSSL_CTX *ctx);
BN_CTX *BN_CTX_new(void);
BN_CTX *BN_CTX_secure_new_ex(OPENSSL_CTX *ctx);
BN_CTX *BN_CTX_secure_new(void);
void BN_CTX_free(BN_CTX *c);
@@ -21,10 +24,17 @@ library functions. Since dynamic memory allocation to create B<BIGNUM>s
is rather expensive when used in conjunction with repeated subroutine
calls, the B<BN_CTX> structure is used.
BN_CTX_new() allocates and initializes a B<BN_CTX> structure.
BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure
BN_CTX_new_ex() allocates and initializes a B<BN_CTX> structure for the given
library context B<ctx>. The <ctx> value may be NULL in which case the default
library context will be used. BN_CTX_new() is the same as BN_CTX_new_ex() except
that the default library context is always used.
BN_CTX_secure_new_ex() allocates and initializes a B<BN_CTX> structure
but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the
B<BIGNUM>s.
B<BIGNUM>s for the given library context B<ctx>. The <ctx> value may be NULL in
which case the default library context will be used. BN_CTX_secure_new() is the
same as BN_CTX_secure_new_ex() except that the default library context is always
used.
BN_CTX_free() frees the components of the B<BN_CTX> and the structure itself.
Since BN_CTX_start() is required in order to obtain B<BIGNUM>s from the
doc/man3/BN_generate_prime.pod
+8 -4
View File
@@ -51,7 +51,9 @@ L<openssl_user_macros(7)>:
=head1 DESCRIPTION
BN_generate_prime_ex() generates a pseudo-random prime number of
at least bit length B<bits>.
at least bit length B<bits>. The returned number is probably prime
with a negligible error.
If B<ret> is not B<NULL>, it will be used to store the number.
If B<cb> is not B<NULL>, it is used as follows:
@@ -89,8 +91,9 @@ generator.
If B<safe> is true, it will be a safe prime (i.e. a prime p so
that (p-1)/2 is also prime).
The PRNG must be seeded prior to calling BN_generate_prime_ex().
The prime number generation has a negligible error probability.
The random generator must be seeded prior to calling BN_generate_prime_ex().
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
prime. The following tests are performed until one of them shows that
@@ -193,7 +196,8 @@ Instead applications should create a BN_GENCB structure using BN_GENCB_new:
=head1 SEE ALSO
L<DH_generate_parameters(3)>, L<DSA_generate_parameters(3)>,
L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>
L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
L<RAND(7)>
=head1 HISTORY
doc/man3/BN_rand.pod
+29 -8
View File
@@ -2,30 +2,37 @@
=head1 NAME
BN_rand, BN_priv_rand, BN_pseudo_rand,
BN_rand_range, BN_priv_rand_range, BN_pseudo_rand_range
BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand,
BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range,
BN_pseudo_rand_range
- generate pseudo-random number
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx);
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx);
int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
int BN_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx);
int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
int BN_priv_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx);
int BN_priv_rand_range(BIGNUM *rnd, BIGNUM *range);
int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range);
=head1 DESCRIPTION
BN_rand() generates a cryptographically strong pseudo-random number of
B<bits> in length and stores it in B<rnd>.
BN_rand_ex() generate a cryptographically strong pseudo-random
number of B<bits> in length and stores it in B<rnd> using the random number
generator for the library context associated with B<ctx>. The parameter B<ctx>
may be NULL in which case the default library context is used.
If B<bits> is less than zero, or too small to
accommodate the requirements specified by the B<top> and B<bottom>
parameters, an error is returned.
@@ -40,11 +47,20 @@ If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
BN_rand_range() generates a cryptographically strong pseudo-random
number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
BN_rand() is the same as BN_rand_ex() except that the default library context
is always used.
BN_priv_rand() and BN_priv_rand_range() have the same semantics as
BN_rand() and BN_rand_range() respectively. They are intended to be
BN_rand_range_ex() generates a cryptographically strong pseudo-random
number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range> using the random number
generator for the library context associated with B<ctx>. The parameter B<ctx>
may be NULL in which case the default library context is used.
BN_rand_range() is the same as BN_rand_range_ex() except that the default
library context is always used.
BN_priv_rand_ex(), BN_priv_rand(), BN_priv_rand_rand_ex() and
BN_priv_rand_range() have the same semantics as BN_rand_ex(), BN_rand(),
BN_rand_range_ex() and BN_rand_range() respectively. They are intended to be
used for generating values that should remain private, and mirror the
same difference between L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>.
@@ -85,6 +101,11 @@ a future release.
The
BN_priv_rand() and BN_priv_rand_range() functions were added in OpenSSL 1.1.1.
=item *
The BN_rand_ex(), BN_priv_rand_ex(), BN_rand_range_ex() and
BN_priv_rand_range_ex() functions were added in OpenSSL 3.0.
=back
=head1 COPYRIGHT
doc/man3/CMS_final.pod
+1 -1
View File
@@ -12,7 +12,7 @@ CMS_final - finalise a CMS_ContentInfo structure
=head1 DESCRIPTION
CMS_final() finalises the structure B<cms>. It's purpose is to perform any
CMS_final() finalises the structure B<cms>. Its purpose is to perform any
operations necessary on B<cms> (digest computation for example) and set the
appropriate fields. The parameter B<data> contains the content to be
processed. The B<dcont> parameter contains a BIO to write content to after
doc/man3/CRYPTO_memcmp.pod
+39
View File
@@ -0,0 +1,39 @@
=pod
=head1 NAME
CRYPTO_memcmp - Constant time memory comparison
=head1 SYNOPSIS
#include <openssl/crypto.h>
int CRYPTO_memcmp(const void *a, const void *b, size_t len);
=head1 DESCRIPTION
The CRYPTO_memcmp function compares the B<len> bytes pointed to by B<a> and B<b>
for equality.
It takes an amount of time dependent on B<len>, but independent of the
contents of the memory regions pointed to by B<a> and B<b>.
=head1 RETURN VALUES
CRYPTO_memcmp() returns 0 if the memory regions are equal and non-zero
otherwise.
=head1 NOTES
Unlike memcmp(2), this function cannot be used to order the two memory regions
as the return value when they differ is undefined, other than being non-zero.
=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/DES_random_key.pod
+7 -8
View File
@@ -104,9 +104,11 @@ consists of 8 bytes with odd parity. The least significant bit in
each byte is the parity bit. The key schedule is an expanded form of
the key; it is used to speed the encryption process.
DES_random_key() generates a random key. The PRNG must be seeded
prior to using this function (see L<RAND_bytes(3)>). If the PRNG
could not generate a secure key, 0 is returned.
DES_random_key() generates a random key. The random generator must be
seeded when calling this function.
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
If the function fails, 0 is returned.
Before a DES key can be used, it must be converted into the
architecture dependent I<DES_key_schedule> via the
@@ -117,11 +119,8 @@ and is not a weak or semi-weak key. If the parity is wrong, then -1
is returned. If the key is a weak key, then -2 is returned. If an
error is returned, the key schedule is not generated.
DES_set_key() works like
DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
otherwise like DES_set_key_unchecked(). These functions are available
for compatibility; it is recommended to use a function that does not
depend on a global variable.
DES_set_key() works like DES_set_key_checked() and remains for
backward compatibility.
DES_set_odd_parity() sets the parity of the passed I<key> to odd.
doc/man3/DSA_generate_key.pod
+3 -1
View File
@@ -15,7 +15,9 @@ DSA_generate_key - generate DSA key pair
DSA_generate_key() expects B<a> to contain DSA parameters. It generates
a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
The PRNG must be seeded prior to calling DSA_generate_key().
The random generator must be seeded prior to calling DSA_generate_key().
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
=head1 RETURN VALUES
doc/man3/DSA_sign.pod
+5 -2
View File
@@ -36,8 +36,10 @@ B<dsa> is the signer's public key.
The B<type> parameter is ignored.
The PRNG must be seeded before DSA_sign() (or DSA_sign_setup())
The random generator must be seeded when DSA_sign() (or DSA_sign_setup())
is called.
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
=head1 RETURN VALUES
@@ -54,7 +56,8 @@ Standard, DSS), ANSI X9.30
=head1 SEE ALSO
L<DSA_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
L<DSA_do_sign(3)>
L<DSA_do_sign(3)>,
L<RAND(7)>
=head1 COPYRIGHT
doc/man3/ERR_put_error.pod
+1
View File
@@ -23,6 +23,7 @@ This function is usually called by a macro.
ERR_add_error_data() associates the concatenation of its B<num> string
arguments with the error code added last.
ERR_add_error_vdata() is similar except the argument is a B<va_list>.
Multiple calls to these functions append to the current top of the error queue.
L<ERR_load_strings(3)> can be used to register
error strings so that the application can a generate human-readable
doc/man3/EVP_CIPHER_meth_new.pod
+8 -1
View File
@@ -10,7 +10,8 @@ EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params,
EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init,
EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup,
EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params,
EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods
EVP_CIPHER_meth_get_ctrl, EVP_CIPHER_up_ref
- Routines to build up EVP_CIPHER methods
=head1 SYNOPSIS
@@ -62,6 +63,8 @@ EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods
int type, int arg,
void *ptr);
int EVP_CIPHER_up_ref(EVP_CIPHER *cipher);
=head1 DESCRIPTION
The B<EVP_CIPHER> type is a structure for symmetric cipher method
@@ -223,6 +226,8 @@ EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl()
are all used to retrieve the method data given with the
EVP_CIPHER_meth_set_*() functions above.
EVP_CIPHER_up_ref() increments the reference count for an EVP_CIPHER structure.
=head1 RETURN VALUES
EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a
@@ -231,6 +236,8 @@ All EVP_CIPHER_meth_set_*() functions return 1.
All EVP_CIPHER_meth_get_*() functions return pointers to their
respective B<cipher> function.
EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.
=head1 SEE ALSO
L<EVP_EncryptInit>
doc/man3/EVP_DigestInit.pod
+61 -4
View File
@@ -3,8 +3,8 @@
=head1 NAME
EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags,
EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_params, EVP_MD_CTX_get_params,
EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags,
@@ -22,6 +22,8 @@ EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2);
int EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]);
int EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]);
void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);
void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);
int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);
@@ -88,12 +90,25 @@ Cleans up digest context B<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()
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>.
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.
=item EVP_MD_CTX_get_params
Retrieves the requested list of B<params> from a MD context B<ctx>.
See L</PARAMS> below for more information.
=item EVP_MD_CTX_set_params
Sets the list of <params> into a MD context B<ctx>.
See L</PARAMS> below for more information.
=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.
@@ -239,6 +254,38 @@ depends on how the B<EVP_PKEY_CTX> is created.
=back
=head1 PARAMS
See L<OSSL_PARAM(3)> for information about passing parameters.
EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys:
=over 4
=item OSSL_PARAM_DIGEST_KEY_XOFLEN <size_t>
Sets the digest length for extendable output functions.
It is used by the SHAKE algorithm.
=item OSSL_PARAM_DIGEST_KEY_PAD_TYPE <int>
Sets the pad type.
It is used by the MDC2 algorithm.
=back
EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys:
=over 4
=item OSSL_PARAM_DIGEST_KEY_MICALG <utf8string>.
Gets the digest Message Integrity Check algorithm string. This is used when
creating S/MIME multipart/signed messages, as specified in RFC 3851.
It may be used by external engines or providers.
=back
=head1 CONTROLS
EVP_MD_CTX_ctrl() can be used to send the following standard controls:
@@ -307,6 +354,11 @@ success and 0 for failure.
Returns 1 if successful or 0 for failure.
=item EVP_MD_CTX_set_params(),
EVP_MD_CTX_get_params()
Returns 1 if successful or 0 for failure.
=item EVP_MD_CTX_copy_ex()
Returns 1 if successful or 0 for failure.
@@ -418,7 +470,9 @@ digest name passed on the command line.
L<EVP_MD_meth_new(3)>,
L<dgst(1)>,
L<evp(7)>
L<evp(7)>,
L<OSSL_PROVIDER(3)>,
L<OSSL_PARAM(3)>
The full list of digest algorithms are provided below.
@@ -446,9 +500,12 @@ The EVP_dss1() function was removed in OpenSSL 1.1.0.
The EVP_MD_CTX_set_pkey_ctx() function was added in 1.1.1.
The EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params() functions were
added in 3.0.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-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
doc/man3/EVP_DigestSignInit.pod
+6 -4
View File
@@ -35,7 +35,7 @@ EVP_MD_CTX is freed).
The digest B<type> may be NULL if the signing algorithm supports it.
No B<EVP_PKEY_CTX> will be created by EVP_DigsetSignInit() if the passed B<ctx>
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
Only EVP_PKEY types that support signing can be used with these functions. This
@@ -125,8 +125,9 @@ and public key algorithms. This meant that "clone" digests such as EVP_dss1()
needed to be used to sign using SHA1 and DSA. This is no longer necessary and
the use of clone digest is now discouraged.
For some key types and parameters the random number generator must be seeded
or the operation will fail.
For some key types and parameters the random number generator must be seeded.
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
context. This means that calls to EVP_DigestSignUpdate() and
@@ -147,7 +148,8 @@ L<EVP_DigestVerifyInit(3)>,
L<EVP_DigestInit(3)>,
L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
L<SHA1(3)>, L<dgst(1)>
L<SHA1(3)>, L<dgst(1)>,
L<RAND(7)>
=head1 HISTORY
doc/man3/EVP_DigestVerifyInit.pod
+6 -4
View File
@@ -32,7 +32,7 @@ being passed to EVP_DigestVerifyInit() (which means the EVP_PKEY_CTX is created
inside EVP_DigestVerifyInit() and it will be freed automatically when the
EVP_MD_CTX is freed).
No B<EVP_PKEY_CTX> will be created by EVP_DigsetSignInit() if the passed B<ctx>
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
@@ -76,8 +76,9 @@ and public key algorithms. This meant that "clone" digests such as EVP_dss1()
needed to be used to sign using SHA1 and DSA. This is no longer necessary and
the use of clone digest is now discouraged.
For some key types and parameters the random number generator must be seeded
or the operation will fail.
For some key types and parameters the random number generator must be seeded.
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
@@ -93,7 +94,8 @@ L<EVP_DigestSignInit(3)>,
L<EVP_DigestInit(3)>,
L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
L<SHA1(3)>, L<dgst(1)>
L<SHA1(3)>, L<dgst(1)>,
L<RAND(7)>
=head1 HISTORY
doc/man3/EVP_KDF_CTX.pod
+1
View File
@@ -278,6 +278,7 @@ L<EVP_KDF_HKDF(7)>
L<EVP_KDF_SS(7)>
L<EVP_KDF_SSHKDF(7)>
L<EVP_KDF_X963(7)>
L<EVP_KDF_X942KDF(7)>
=head1 HISTORY
doc/man3/EVP_MAC.pod
+11 -10
View File
@@ -3,7 +3,7 @@
=head1 NAME
EVP_MAC, EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_new_id, EVP_MAC_CTX_free,
EVP_MAC_CTX_copy, EVP_MAC_CTX_mac, EVP_MAC_size, EVP_MAC_init, EVP_MAC_update,
EVP_MAC_CTX_dup, EVP_MAC_CTX_mac, EVP_MAC_size, EVP_MAC_init, EVP_MAC_update,
EVP_MAC_final, EVP_MAC_ctrl, EVP_MAC_vctrl, EVP_MAC_ctrl_str,
EVP_MAC_str2ctrl, EVP_MAC_hex2ctrl, EVP_MAC_nid, EVP_MAC_name,
EVP_get_macbyname, EVP_get_macbynid, EVP_get_macbyobj - EVP MAC routines
@@ -18,7 +18,7 @@ EVP_get_macbyname, EVP_get_macbynid, EVP_get_macbyobj - EVP MAC routines
EVP_MAC_CTX *EVP_MAC_CTX_new(const EVP_MAC *mac);
EVP_MAC_CTX *EVP_MAC_CTX_new_id(int nid);
void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
int EVP_MAC_CTX_copy(EVP_MAC_CTX *dest, EVP_MAC_CTX *src);
EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);
const EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
int EVP_MAC_init(EVP_MAC_CTX *ctx);
@@ -72,10 +72,8 @@ EVP_MAC_CTX_free() frees the contents of the context, including an
underlying context if there is one, as well as the context itself.
B<NULL> is a valid parameter, for which this function is a no-op.
EVP_MAC_CTX_copy() makes a deep copy of the C<src> context to the
C<dest> context.
The C<dest> context I<must> have been created before calling this
function.
EVP_MAC_CTX_dup() duplicates the C<src> context and returns a newly allocated
context.
EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
C<ctx>.
@@ -231,13 +229,12 @@ implemented as a macro.
=head1 RETURN VALUES
EVP_MAC_CTX_new() and EVP_MAC_CTX_new_id() return a pointer to a newly
created EVP_MAC_CTX, or NULL if allocation failed.
EVP_MAC_CTX_new(), EVP_MAC_CTX_new_id() and EVP_MAC_CTX_dup() return a pointer
to a newly created EVP_MAC_CTX, or NULL if allocation failed.
EVP_MAC_CTX_free() returns nothing at all.
EVP_MAC_CTX_copy(), EVP_MAC_init(), EVP_MAC_update(),
and EVP_MAC_final() return 1 on success, 0 on error.
EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0 on error.
EVP_MAC_ctrl(), EVP_MAC_ctrl_str(), EVP_MAC_str2ctrl() and
EVP_MAC_hex2ctrl() return 1 on success and 0 or a negative value on
@@ -359,6 +356,10 @@ L<EVP_MAC_KMAC(7)>,
L<EVP_MAC_SIPHASH(7)>,
L<EVP_MAC_POLY1305(7)>
=head1 HISTORY
These functions were added in OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/EVP_MD_fetch.pod
+96 -36
View File
@@ -2,7 +2,7 @@
=head1 NAME
EVP_MD_fetch
EVP_MD_fetch, EVP_CIPHER_fetch
- Functions to explicitly fetch algorithm implementations
=head1 SYNOPSIS
@@ -11,60 +11,106 @@ EVP_MD_fetch
EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm,
const char *properties);
EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
const char *properties);
=head1 DESCRIPTION
The B<EVP_MD> object is used for representing a digest method implementation.
Cryptographic algorithms are represented by different OpenSSL objects depending
on what type of algorithm it is. The following cryptographic algorithm types are
supported.
Having obtained a digest implementation as an B<EVP_MD> type it can be used to
calculate the digest of input data using functions such as
L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>.
=over 4
Digest implementations may be obtained in one of three ways, i.e. implicit
fetch, explicit fetch or user defined.
=item B<EVP_MD>
Represents a digest algorithm.
=item B<EVP_CIPHER>
Represents a symmetric cipher algorithm.
=item B<EVP_MAC>
Represents a Message Authentication Code algorithm.
=item B<EVP_KDF>
Represents a Key Derivation Function algorithm.
=back
The algorithm objects may or may not have an associated algorithm
implementation.
Cryptographic algorithms are implemented by providers.
Any algorithm may be supported by zero or more providers.
In order to use an algorithm an implementation must first be obtained.
This can happen in one of three ways, i.e. implicit fetch, explicit fetch or
user defined.
=over 4
=item Implicit Fetch
With implicit fetch an application can use functions such as L<EVP_sha256(3)>,
L<EVP_sha512(3)> or L<EVP_blake2b512(3)> to obtain an B<EVP_MD> object. When
used in a function like L<EVP_DigestInit_ex(3)> the actual implementation to
be used will be fetched implicitly using default search criteria. Typically,
(unless the default search criteria have been changed and/or different providers
have been loaded), this will return an implementation of the appropriate
algorithm from the default provider.
L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)> to obtain an algorithm object with
no associated implementation.
When used in a function like L<EVP_DigestInit_ex(3)> or L<EVP_CipherInit_ex(3)>
the actual implementation to be used will be fetched implicitly using default
search criteria.
Typically, this will return an implementation of the appropriate algorithm from
the default provider unless the default search criteria have been changed and/or
different providers have been loaded.
=item Explicit Fetch
With explicit fetch an application uses the EVP_MD_fetch() function to obtain
an algorithm implementation. An implementation with the given name and
satisfying the search criteria specified in the B<properties> parameter
combined with the default search criteria will be looked for within the
available providers and returned.
With explicit fetch an application uses one of the "fetch" functions to obtain
an algorithm object with an associated implementation.
An implementation with the given name that satisfies the search criteria
specified in the B<properties> parameter combined with the default search
criteria will be looked for within the available providers and returned.
See L<EVP_set_default_properties(3)> for information on default search criteria
and L<OSSL_PROVIDER(3)> for information about providers.
=item User defined
Using the user defined approach an application constructs its own EVP_MD object.
See L<EVP_MD_meth_new(3)> for details.
Using the user defined approach an application constructs its own algorithm
object.
See L<EVP_MD_meth_new(3)> and L<EVP_CIPHER_meth_new(3)> for details.
=back
The EVP_MD_fetch() function will look for an algorithm within the providers that
have been loaded into the B<OPENSSL_CTX> given in the B<ctx> parameter. This
parameter may be NULL in which case the default B<OPENSSL_CTX> will be used. See
L<OPENSSL_CTX_new(3)> and L<OSSL_PROVIDER_load(3)> for further details.
Having obtained an algorithm implementation as an algorithm object it can then
be used to perform cryptographic operations.
For example to calculate the digest of input data with an B<EVP_MD> algorithm
object you can use functions such as L<EVP_DigestInit_ex(3)>,
L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>.
The fetch functions will look for an algorithm within the providers that
have been loaded into the B<OPENSSL_CTX> given in the B<ctx> parameter.
This parameter may be NULL in which case the default B<OPENSSL_CTX> will be
used.
See L<OPENSSL_CTX_new(3)> and L<OSSL_PROVIDER_load(3)> for further details.
The B<algorithm> parameter gives the name of the algorithm to be looked up.
Different algorithms can be made available by loading different providers. The
built-in default provider algorithm implementation names are: SHA1, SHA224,
SHA256, SHA384, SHA512, SHA512-224, SHA512-256,SHA3-224, SHA3-256, SHA3-384,
SHA3-512, SHAKE128, SHAKE256, SM3, BLAKE2b512, BLAKE2s256 and MD5-SHA1.
Different algorithms can be made available by loading different providers.
The built-in default provider digest algorithm implementation names are: SHA1,
SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256, SHA3-224, SHA3-256,
SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3, BLAKE2b512, BLAKE2s256 and
MD5-SHA1.
The built-in default provider cipher algorithm implementation names are:
AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC, AES-128-CBC,
AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB, AES-192-CFB, AES-128-CFB,
AES-256-CFB1, AES-192-CFB1, AES-128-CFB1, AES-256-CFB8, AES-192-CFB8,
AES-128-CFB8, AES-256-CTR, AES-192-CTR, AES-128-CTR, id-aes256-GCM,
id-aes192-GCM and id-aes128-GCM.
Additional algorithm implementations may be obtained by loading the "legacy"
provider. The names of these algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and
provider.
The legacy provider digest algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and
whirlpool.
The B<properties> parameter specifies the search criteria that will be used to
@@ -82,14 +128,19 @@ NULL in which case any implementation from the available providers with the
given algorithm name will be returned.
The return value from a call to EVP_MD_fetch() must be freed by the caller using
L<EVP_MD_meth_free(3)>. Note that EVP_MD objects are reference counted. See
L<EVP_MD_upref(3)>.
L<EVP_MD_meth_free(3)>.
Note that EVP_MD objects are reference counted. See L<EVP_MD_up_ref(3)>.
The return value from a call to EVP_CIPHER_fetch() must be freed by the caller
using L<EVP_CIPHER_meth_free(3)>.
Note that EVP_CIPHER objects are reference counted.
See L<EVP_CIPHER_up_ref(3)>.
=head1 NOTES
Where an application that previously used implicit fetch is converted to use
explicit fetch care should be taken with the L<EVP_MD_CTX_md(3)> function.
Specifically, this function returns the EVP_MD object orginally passed to
Specifically, this function returns the EVP_MD object originally passed to
EVP_DigestInit_ex() (or other similar function). With implicit fetch the
returned EVP_MD object is guaranteed to be available throughout the application
lifetime. However, with explicit fetch EVP_MD objects are reference counted.
@@ -107,6 +158,14 @@ an EVP_MD object, or NULL on error.
Fetch any available implementation of SHA256 in the default context:
EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
...
EVP_MD_meth_free(md);
Fetch any available implementation of AES-128-CBC in the default context:
EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
...
EVP_CIPHER_meth_free(cipher);
Fetch an implementation of SHA256 from the default provider in the default
context:
@@ -140,7 +199,7 @@ implementation of whirlpool from it:
EVP_MD_meth_free(md);
Note that in the above example the property string "legacy=yes" is optional
since, assuming no other providers have been loaded, the only implmentation of
since, assuming no other providers have been loaded, the only implementation of
the "whirlpool" algorithm is in the "legacy" provider. Also note that the
default provider should be explicitly loaded if it is required in addition to
other providers:
@@ -157,9 +216,10 @@ other providers:
=head1 SEE ALSO
L<EVP_DigestInit(3)>, L<EVP_MD_meth_new(3)>, L<EVP_MD_meth_free(3)>,
L<EVP_MD_upref(3)>, L<OSSL_PROVIDER_load(3)>, L<OPENSSL_CTX(3)>,
L<EVP_set_default_properties(3)>
L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>, L<EVP_MD_meth_new(3)>,
L<EVP_MD_meth_free(3)>, L<EVP_CIPHER_meth_new(3)>, L<EVP_CIPHER_meth_free(3)>,
L<EVP_MD_up_ref(3)>, L<EVP_CIPHER_up_ref(3)>, L<OSSL_PROVIDER_load(3)>,
L<OPENSSL_CTX(3)>, L<EVP_set_default_properties(3)>
=head1 HISTORY
doc/man3/EVP_MD_meth_new.pod
+5 -5
View File
@@ -11,7 +11,7 @@ EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
EVP_MD_meth_get_ctrl, EVP_MD_upref
EVP_MD_meth_get_ctrl, EVP_MD_up_ref
- Routines to build up EVP_MD methods
=head1 SYNOPSIS
@@ -54,7 +54,7 @@ EVP_MD_meth_get_ctrl, EVP_MD_upref
int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
int p1, void *p2);
int EVP_MD_upref(EVP_MD *md);
int EVP_MD_up_ref(EVP_MD *md);
=head1 DESCRIPTION
@@ -162,7 +162,7 @@ EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
to retrieve the method data given with the EVP_MD_meth_set_*()
functions above.
EVP_MD_upref() increments the reference count for an EVP_MD structure.
EVP_MD_up_ref() increments the reference count for an EVP_MD structure.
=head1 RETURN VALUES
@@ -175,7 +175,7 @@ indicated sizes or flags.
All other EVP_CIPHER_meth_get_*() functions return pointers to their
respective B<md> function.
EVP_MD_upref() returns 1 for success or 0 otherwise.
EVP_MD_up_ref() returns 1 for success or 0 otherwise.
=head1 SEE ALSO
@@ -184,7 +184,7 @@ L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
=head1 HISTORY
The B<EVP_MD> structure was openly available in OpenSSL before version
1.1. EVP_MD_upref() was added in OpenSSL 3.0. All other functions described
1.1. EVP_MD_up_ref() was added in OpenSSL 3.0. All other functions described
here were added in OpenSSL 1.1.
=head1 COPYRIGHT
doc/man3/EVP_SealInit.pod
+5 -2
View File
@@ -55,7 +55,9 @@ failure.
=head1 NOTES
Because a random secret key is generated the random number generator
must be seeded before calling EVP_SealInit().
must be seeded when EVP_SealInit() is called.
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
The public key must be RSA because it is the only OpenSSL public key
algorithm that supports key transport.
@@ -75,7 +77,8 @@ with B<type> set to NULL.
L<evp(7)>, L<RAND_bytes(3)>,
L<EVP_EncryptInit(3)>,
L<EVP_OpenInit(3)>
L<EVP_OpenInit(3)>,
L<RAND(7)>
=head1 COPYRIGHT
doc/man3/EVP_SignInit.pod
+4 -3
View File
@@ -66,9 +66,10 @@ The B<EVP> interface to digital signatures should almost always be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.
When signing with DSA private keys the random number generator must be seeded
or the operation will fail. The random number generator does not need to be
seeded for RSA signatures.
When signing with DSA private keys the random number generator must be seeded.
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
This requirement does not hold for RSA signatures.
The call to EVP_SignFinal() internally finalizes a copy of the digest context.
This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called
doc/man3/EVP_VerifyInit.pod
+1 -1
View File
@@ -72,7 +72,7 @@ data have been passed through EVP_SignUpdate().
It is not possible to change the signing parameters using these function.
The previous two bugs are fixed in the newer EVP_VerifyDigest*() function.
The previous two bugs are fixed in the newer EVP_DigestVerify*() function.
=head1 SEE ALSO
doc/man3/EVP_aria.pod
+2 -2
View File
@@ -32,7 +32,7 @@ EVP_aria_256_ccm,
EVP_aria_128_gcm,
EVP_aria_192_gcm,
EVP_aria_256_gcm,
- EVP AES cipher
- EVP ARIA cipher
=head1 SYNOPSIS
@@ -106,7 +106,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
doc/man3/EVP_md5.pod
+1 -1
View File
@@ -29,7 +29,7 @@ The MD5 algorithm which produces a 128-bit output from a given input.
=item EVP_md5_sha1()
A hash algorithm of SSL v3 that combines MD5 with SHA-1 as decirbed in RFC
A hash algorithm of SSL v3 that combines MD5 with SHA-1 as described in RFC
6101.
WARNING: this algorithm is not intended for non-SSL usage.
doc/man3/EVP_rc5_32_12_16_cbc.pod
+20 -5
View File
@@ -33,7 +33,26 @@ EVP_rc5_32_12_16_ofb()
RC5 encryption algorithm in CBC, CFB, ECB and OFB modes respectively. This is a
variable key length cipher with an additional "number of rounds" parameter. By
default the key length is set to 128 bits and 12 rounds.
default the key length is set to 128 bits and 12 rounds. Alternative key lengths
can be set using L<EVP_CIPHER_CTX_set_key_length(3)>. The maximum key length is
2040 bits.
The following rc5 specific I<ctrl>s are supported (see
L<EVP_CIPHER_CTX_ctrl(3)>).
=over 4
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, rounds, NULL)
Sets the number of rounds to B<rounds>. This must be one of RC5_8_ROUNDS,
RC5_12_ROUNDS or RC5_16_ROUNDS.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &rounds)
Stores the number of rounds currently configured in B<*rounds> where B<*rounds>
is an int.
=back
=back
@@ -43,10 +62,6 @@ These functions return an B<EVP_CIPHER> structure that contains the
implementation of the symmetric cipher. See L<EVP_CIPHER_meth_new(3)> for
details of the B<EVP_CIPHER> structure.
=head1 BUGS
Currently the number of rounds in RC5 can only be set to 8, 12 or 16.
This is a limitation of the current RC5 code rather than the EVP interface.
=head1 SEE ALSO
doc/man3/OPENSSL_CTX.pod
+4
View File
@@ -21,6 +21,10 @@ the internal default context with functions that take a C<OPENSSL_CTX>
argument.
OPENSSL_CTX_new() creates a new OpenSSL library context.
When a non default library context is in use care should be taken with
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_free() frees the given C<ctx>.
doc/man3/OPENSSL_fork_prepare.pod
+2 -2
View File
@@ -24,7 +24,7 @@ The OPENSSL_fork_prepare(), OPENSSL_fork_parent(), and OPENSSL_fork_child()
functions are used to reset this internal state.
Platforms without fork(2) will probably not need to use these functions.
Platforms with fork(2) but without pthreads_atfork(3) will probably need
Platforms with fork(2) but without pthread_atfork(3) will probably need
to call them manually, as described in the following paragraph. Platforms
such as Linux that have both functions will normally not need to call these
functions as the OpenSSL library will do so automatically.
@@ -32,7 +32,7 @@ functions as the OpenSSL library will do so automatically.
L<OPENSSL_init_crypto(3)> will register these functions with the appropriate
handler, when the B<OPENSSL_INIT_ATFORK> flag is used. For other
applications, these functions can be called directly. They should be used
according to the calling sequence described by the pthreads_atfork(3)
according to the calling sequence described by the pthread_atfork(3)
documentation, which is summarized here. OPENSSL_fork_prepare() should
be called before a fork() is done. After the fork() returns, the parent
process should call OPENSSL_fork_parent() and the child process should
doc/man3/OPENSSL_init_crypto.pod
+21 -6
View File
@@ -5,7 +5,7 @@
OPENSSL_INIT_new, OPENSSL_INIT_set_config_filename,
OPENSSL_INIT_set_config_appname, OPENSSL_INIT_set_config_file_flags,
OPENSSL_INIT_free, OPENSSL_init_crypto, OPENSSL_cleanup, OPENSSL_atexit,
OPENSSL_thread_stop - OpenSSL initialisation
OPENSSL_thread_stop_ex, OPENSSL_thread_stop - OpenSSL initialisation
and deinitialisation functions
=head1 SYNOPSIS
@@ -15,6 +15,7 @@ and deinitialisation functions
void OPENSSL_cleanup(void);
int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
int OPENSSL_atexit(void (*handler)(void));
void OPENSSL_thread_stop_ex(OPENSSL_CTX *ctx);
void OPENSSL_thread_stop(void);
OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);
@@ -202,11 +203,25 @@ called after deinitialisation of resources local to a thread, but before other
process wide resources are freed. In the event that multiple stop handlers are
registered, no guarantees are made about the order of execution.
The OPENSSL_thread_stop() function deallocates resources associated
with the current thread. Typically this function will be called automatically by
the library when the thread exits. This should only be called directly if
resources should be freed at an earlier time, or under the circumstances
described in the NOTES section below.
The OPENSSL_thread_stop_ex() function deallocates resources associated
with the current thread for the given OPENSSL_CTX B<ctx>. The B<ctx> parameter
can be NULL in which case the default OPENSSL_CTX is used.
Typically, this function will be called automatically by the library when
the thread exits as long as the OPENSSL_CTX has not been freed before the thread
exits. If OPENSSL_CTX_free() is called OPENSSL_thread_stop_ex will be called
automatically for the current thread (but not any other threads that may have
used this OPENSSL_CTX).
OPENSSL_thread_stop_ex should be called on all threads that will exit after the
OPENSSL_CTX is freed.
Typically this is not necessary for the default OPENSSL_CTX (because all
resources are cleaned up on library exit) except if thread local resources
should be freed before library exit, or under the circumstances described in
the NOTES section below.
OPENSSL_thread_stop() is the same as OPENSSL_thread_stop_ex() except that the
default OPENSSL_CTX is always used.
The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a configuration file, as with
L<CONF_modules_load_file(3)> with NULL filename and application name and the
doc/man3/OPENSSL_s390xcap.pod
+18 -3
View File
@@ -34,14 +34,14 @@ There are three types of tokens:
The name of a processor generation. A bit in the environment variable's
mask is set to one if and only if the specified processor generation
implements the corresponding instruction set extension. Possible values
are z900, z990, z9, z10, z196, zEC12, z13 and z14.
are z900, z990, z9, z10, z196, zEC12, z13, z14 and z15.
=item <string>:<mask>:<mask>
The name of an instruction followed by two 64-bit masks. The part of the
environment variable's mask corresponding to the specified instruction is
set to the specified 128-bit mask. Possible values are kimd, klmd, km, kmc,
kmac, kmctr, kmo, kmf, prno and kma.
kmac, kmctr, kmo, kmf, prno, kma, pcc and kdsa.
=item stfle:<mask>:<mask>:<mask>
@@ -139,6 +139,21 @@ the numbering is continuous across 64-bit mask boundaries.
# 20 1<<43 KMA-GCM-AES-256
:
pcc :
:
# 64 1<<63 PCC-Scalar-Multiply-P256
# 65 1<<62 PCC-Scalar-Multiply-P384
# 66 1<<61 PCC-Scalar-Multiply-P521
kdsa :
# 1 1<<62 KDSA-ECDSA-Verify-P256
# 2 1<<61 KDSA-ECDSA-Verify-P384
# 3 1<<60 KDSA-ECDSA-Verify-P521
# 9 1<<54 KDSA-ECDSA-Sign-P256
# 10 1<<53 KDSA-ECDSA-Sign-P384
# 11 1<<52 KDSA-ECDSA-Sign-P521
:
=head1 RETURN VALUES
Not available.
@@ -159,7 +174,7 @@ Disables the KM-XTS-AES and and the KIMD-SHAKE function codes:
=head1 SEE ALSO
[1] z/Architecture Principles of Operation, SA22-7832-11
[1] z/Architecture Principles of Operation, SA22-7832-12
=head1 COPYRIGHT
doc/man3/OSSL_CMP_ITAV_set0.pod
+105
View File
@@ -0,0 +1,105 @@
=pod
=head1 NAME
OSSL_CMP_ITAV_create,
OSSL_CMP_ITAV_set0,
OSSL_CMP_ITAV_get0_type,
OSSL_CMP_ITAV_get0_value,
OSSL_CMP_ITAV_push0_stack_item
- OSSL_CMP_ITAV utility functions
=head1 SYNOPSIS
#include <openssl/cmp.h>
OSSL_CMP_ITAV *OSSL_CMP_ITAV_create(ASN1_OBJECT *type, ASN1_TYPE *value);
void OSSL_CMP_ITAV_set0(OSSL_CMP_ITAV *itav, ASN1_OBJECT *type,
ASN1_TYPE *value);
ASN1_OBJECT *OSSL_CMP_ITAV_get0_type(const OSSL_CMP_ITAV *itav);
ASN1_TYPE *OSSL_CMP_ITAV_get0_value(const OSSL_CMP_ITAV *itav);
int OSSL_CMP_ITAV_push0_stack_item(STACK_OF(OSSL_CMP_ITAV) **itav_sk_p,
OSSL_CMP_ITAV *itav);
=head1 DESCRIPTION
ITAV is short for InfoTypeAndValue. This type is defined in RFC 4210
section 5.3.19 and Appendix F. It is used at various places in CMP messages,
e.g., in the generalInfo PKIHeader field, to hold a key-value pair.
OSSL_CMP_ITAV_create() creates a new OSSL_CMP_ITAV structure and fills it in.
It combines B<OSSL_CMP_ITAV_new()> and B<OSSL_CMP_ITAV_set0>.
OSSL_CMP_ITAV_set0() sets the B<itav> with an infoType of B<type> and an
infoValue of B<value>. This function uses the pointers B<type> and B<value>
internally, so they must B<not> be freed up after the call.
OSSL_CMP_ITAV_get0_type() returns a direct pointer to the infoType in the
B<itav>.
OSSL_CMP_ITAV_get0_value() returns a direct pointer to the infoValue in
the B<itav> as generic ASN1_TYPE*.
OSSL_CMP_ITAV_push0_stack_item() pushes B<itav> to the stack pointed to
by B<*itav_sk_p>. It creates a new stack if B<*itav_sk_p> points to NULL.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
=head1 RETURN VALUES
OSSL_CMP_ITAV_create() returns a pointer to the ITAV structure on success,
or NULL on error.
OSSL_CMP_ITAV_set0() does not return a value.
OSSL_CMP_ITAV_get0_type() and OSSL_CMP_ITAV_get0_value()
return the respective pointer or NULL if their input is NULL.
OSSL_CMP_ITAV_push0_stack_item() returns 1 on success, 0 on error.
=head1 EXAMPLE
The following code creates and sets a structure representing a generic
InfoTypeAndValue sequence, using an OID created from text as type, and an
integer as value. Afterwards, it is pushed to the OSSL_CMP_CTX to be later
included in the requests' PKIHeader's genInfo field.
ASN1_OBJECT *type = OBJ_txt2obj("1.2.3.4.5", 1);
if (type == NULL) ...
ASN1_INTEGER *asn1int = ASN1_INTEGER_new();
if (asn1int == NULL || !ASN1_INTEGER_set(asn1int, 12345)) ...
ASN1_TYPE *val = ASN1_TYPE_new();
if (val == NULL) ...
ASN1_TYPE_set(val, V_ASN1_INTEGER, asn1int);
OSSL_CMP_ITAV *itav = OSSL_CMP_ITAV_create(type, val);
if (itav == NULL) ...
OSSL_CMP_CTX *ctx = OSSL_CMP_CTX_new();
if (ctx == NULL || !OSSL_CMP_CTX_geninfo_push0_ITAV(ctx, itav)) {
OSSL_CMP_ITAV_free(itav); /* also frees type and val */
goto err;
}
...
OSSL_CMP_CTX_free(ctx); /* also frees itav */
=head1 SEE ALSO
L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_CTX_free(3)>, L<ASN1_TYPE_set(3)>
=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_CRMF_MSG_get0_tmpl.pod
+1 -1
View File
@@ -56,7 +56,7 @@ B<RFC 4211>
=head1 COPYRIGHT
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.pod
+1 -1
View File
@@ -96,7 +96,7 @@ RFC 4211
=head1 COPYRIGHT
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/OSSL_CRMF_MSG_set1_regInfo_certReq.pod
+1 -1
View File
@@ -39,7 +39,7 @@ RFC 4211
=head1 COPYRIGHT
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/OSSL_CRMF_MSG_set_validity.pod
+1 -1
View File
@@ -95,7 +95,7 @@ RFC 4211
=head1 COPYRIGHT
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/OSSL_CRMF_pbmp_new.pod
+2 -2
View File
@@ -22,7 +22,7 @@ OSSL_CRMF_pbmp_new
OSSL_CRMF_pbm_new() generates a PBM (Password-Based MAC) based on given PBM
parameters B<pbmp>, message B<msg>, and secret B<sec>, along with the respective
lengths B<msglen> and B<seclen>. On success writes the adddress of the newly
lengths B<msglen> and B<seclen>. On success writes the address of the newly
allocated MAC via the B<mac> reference parameter and writes the length via the
B<maclen> reference parameter unless it its NULL.
@@ -68,7 +68,7 @@ RFC 4211 section 4.4
=head1 COPYRIGHT
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
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
doc/man3/OSSL_PARAM.pod
+18 -17
View File
@@ -14,7 +14,7 @@ OSSL_PARAM - a structure to pass or request object parameters
unsigned char data_type; /* declare what kind of content is in data */
void *data; /* value being passed in or out */
size_t data_size; /* data size */
size_t *return_size; /* OPTIONAL: address to content size */
size_t return_size; /* returned size */
};
=head1 DESCRIPTION
@@ -143,7 +143,7 @@ C<data_size> must be set to the size of the data, not the size of the
pointer to the data.
If this is used in a parameter request,
C<data_size> is not relevant. However, the I<responder> will set
C<*return_size> to the size of the data.
C<return_size> to the size of the data.
Note that the use of this type is B<fragile> and can only be safely
used for data that remains constant and in a constant location for a
@@ -166,7 +166,7 @@ C<data_size> must be set to the size of the data, not the size of the
pointer to the data.
If this is used in a parameter request,
C<data_size> is not relevant. However, the I<responder> will set
C<*return_size> to the size of the data.
C<return_size> to the size of the data.
Note that the use of this type is B<fragile> and can only be safely
used for data that remains constant and in a constant location for a
@@ -196,9 +196,10 @@ enough set of data, that call should succeed.
=item *
A I<responder> must never change the fields of an C<OSSL_PARAM>, it
may only change the contents of the memory that C<data> and
C<return_size> point at.
Apart from the C<return_size>, a I<responder> must never change the fields
of an C<OSSL_PARAM>.
To return a value, it should change the contents of the memory that
C<data> points at.
=item *
@@ -214,7 +215,7 @@ C<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory.
=item *
If a I<responder> finds that some data sizes are too small for the
requested data, it must set C<*return_size> for each such
requested data, it must set C<return_size> for each such
C<OSSL_PARAM> item to the required size, and eventually return an
error.
@@ -244,9 +245,9 @@ This example is for setting parameters on some object:
const char *foo = "some string";
size_t foo_l = strlen(foo) + 1;
const char bar[] = "some other string";
const OSSL_PARAM set[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, NULL },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), NULL },
OSSL_PARAM set[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, 0 },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
{ NULL, 0, NULL, 0, NULL }
};
@@ -258,26 +259,26 @@ This example is for requesting parameters on some object:
size_t foo_l;
char bar[1024];
size_t bar_l;
const OSSL_PARAM request[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, &foo_l },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), &bar_l },
OSSL_PARAM request[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, 0 },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
{ NULL, 0, NULL, 0, NULL }
};
A I<responder> that receives this array (as C<params> in this example)
could fill in the parameters like this:
/* const OSSL_PARAM *params */
/* OSSL_PARAM *params */
int i;
for (i = 0; params[i].key != NULL; i++) {
if (strcmp(params[i].key, "foo") == 0) {
*(char **)params[i].data = "foo value";
*params[i].return_size = 10; /* size of "foo value" */
params[i].return_size = 10; /* size of "foo value" */
} else if (strcmp(params[i].key, "bar") == 0) {
memcpy(params[1].data, "bar value", 10);
*params[1].return_size = 10; /* size of "bar value" */
memcpy(params[i].data, "bar value", 10);
params[i].return_size = 10; /* size of "bar value" */
}
/* Ignore stuff we don't know */
}
doc/man3/OSSL_PARAM_TYPE.pod → doc/man3/OSSL_PARAM_int.pod
+52 -59
View File
@@ -2,18 +2,27 @@
=head1 NAME
OSSL_PARAM_TYPE, OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string,
OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, OSSL_PARAM_SIZED_TYPE,
OSSL_PARAM_SIZED_BN, OSSL_PARAM_SIZED_utf8_string,
OSSL_PARAM_SIZED_octet_string, OSSL_PARAM_SIZED_utf8_ptr,
OSSL_PARAM_SIZED_octet_ptr, OSSL_PARAM_END, OSSL_PARAM_construct_TYPE,
OSSL_PARAM_END,
OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string,
OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string,
OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end,
OSSL_PARAM_locate, OSSL_PARAM_get_TYPE,
OSSL_PARAM_set_TYPE, OSSL_PARAM_get_BN, OSSL_PARAM_set_BN,
OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string,
OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_uint, OSSL_PARAM_uint32,
OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string,
OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr,
OSSL_PARAM_END, OSSL_PARAM_construct_BN, OSSL_PARAM_construct_double,
OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32,
OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long,
OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_uint,
OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64,
OSSL_PARAM_construct_ulong, OSSL_PARAM_END, OSSL_PARAM_construct_BN,
OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr,
OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr,
OSSL_PARAM_construct_end, OSSL_PARAM_locate, OSSL_PARAM_locate_const,
OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64,
OSSL_PARAM_get_ulong, OSSL_PARAM_set_double, OSSL_PARAM_set_int,
OSSL_PARAM_set_int32, OSSL_PARAM_set_int64, OSSL_PARAM_set_long,
OSSL_PARAM_set_size_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32,
OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_get_BN,
OSSL_PARAM_set_BN, OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string,
OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string,
OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr,
OSSL_PARAM_set_octet_ptr
@@ -21,6 +30,8 @@ OSSL_PARAM_set_octet_ptr
=head1 SYNOPSIS
=for comment generic
#include <openssl/params.h>
#define OSSL_PARAM_TYPE(key, address)
@@ -28,50 +39,46 @@ OSSL_PARAM_set_octet_ptr
#define OSSL_PARAM_octet_string(key, address, size)
#define OSSL_PARAM_utf8_ptr(key, address, size)
#define OSSL_PARAM_octet_ptr(key, address, size)
#define OSSL_PARAM_SIZED_TYPE(key, address, return_size)
#define OSSL_PARAM_SIZED_BN(key, address, size, return_size)
#define OSSL_PARAM_SIZED_utf8_string(key, address, size, return_size)
#define OSSL_PARAM_SIZED_octet_string(key, address, size, return_size)
#define OSSL_PARAM_SIZED_utf8_ptr(key, address, size, return_size)
#define OSSL_PARAM_SIZED_octet_ptr(key, address, size, return_size)
#define OSSL_PARAM_BN(key, address, size)
#define OSSL_PARAM_END
OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf, size_t *ret);
OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
size_t bsize, size_t *rsize);
size_t bsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
size_t bsize, size_t *rsize);
size_t bsize);
OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
size_t bsize, size_t *rsize);
size_t bsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
size_t bsize, size_t *rsize);
size_t bsize);
OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
size_t bsize, size_t *rsize);
size_t bsize);
OSSL_PARAM OSSL_PARAM_construct_end(void);
OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array,
const char *key);
int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val);
int OSSL_PARAM_set_TYPE(const OSSL_PARAM *p, const char *key, TYPE val);
int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, const char *key, TYPE val);
int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val);
int OSSL_PARAM_set_BN(const OSSL_PARAM *p, const char *key, const BIGNUM *val);
int OSSL_PARAM_set_BN(OSSL_PARAM *p, const char *key, const BIGNUM *val);
int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
size_t max_len);
int OSSL_PARAM_set_utf8_string(const OSSL_PARAM *p, const char *val);
int OSSL_PARAM_set_utf8_string(OSSL_PARAM *p, const char *val);
int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val,
size_t max_len, size_t *used_len);
int OSSL_PARAM_set_octet_string(const OSSL_PARAM *p, const void *val,
size_t len);
int OSSL_PARAM_set_octet_string(OSSL_PARAM *p, const void *val, size_t len);
int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val);
int OSSL_PARAM_set_utf8_ptr(const OSSL_PARAM *p, char *val);
int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, char *val);
int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val,
size_t *used_len);
int OSSL_PARAM_set_octet_ptr(const OSSL_PARAM *p, void *val, size_t used_len);
int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, void *val, size_t used_len);
=head1 DESCRIPTION
@@ -128,26 +135,11 @@ Each of these macros defines a parameter of the specified B<TYPE> with the
provided B<key> and parameter variable B<address>.
OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(),
OSSL_PARAM_octet_ptr() are macros that provide support for defining UTF8
strings and OCTET strings.
OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support
for defining UTF8 strings, OCTET strings and big numbers.
A parameter with name B<key> is defined.
The storage for this parameter is at B<address> and is of B<size> bytes.
OSSL_PARAM_SIZED_TYPE() are a second series of macros designed to assist with
the initialisation of OSSL_PARAM structures.
They are similar to the OSSL_PARAM_TYPE() macros but also include a
B<return_size> argument which contains the address of a size_t variable which
will be populated with the actual size of the parameter upon return from a
OSSL_PARAM_set_TYPE() call.
OSSL_PARAM_SIZED_BN(), OSSL_PARAM_SIZED_utf8_string(),
OSSL_PARAM_SIZED_octet_string(), OSSL_PARAM_SIZED_utf8_ptr(),
OSSL_PARAM_SIZED_octet_ptr() are macros that provide support for defining large
integers, UTF8 string and OCTET strings in an OSSL_PARAM array.
A parameter with name B<key> is defined.
The storage for this parameter is at B<address> and is of B<size> bytes.
The size used by the parameter value, in bytes, is written to B<return_size>.
OSSL_PARAM_END provides an end of parameter list marker.
This should terminate all OSSL_PARAM arrays.
@@ -187,11 +179,14 @@ OSSL_PARAM structure.
OSSL_PARAM_locate() is a function that searches an B<array> of parameters for
the one matching the B<key> name.
OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for
the presence of I<const> for the B<array> argument and its return value.
OSSL_PARAM_get_TYPE() retrieves a value of type B<TYPE> from the parameter B<p>.
The value is copied to the address B<val>.
Type coercion takes place as discussed in the NOTES section.
OSSL_PARAM_set_TYPE() stores a value B<val> of type B<TYPE> into the paramter
OSSL_PARAM_set_TYPE() stores a value B<val> of type B<TYPE> into the parameter
B<p>.
Type coercion takes place as discussed in the NOTES section.
@@ -199,7 +194,7 @@ OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B<p>.
The BIGNUM referenced by B<val> is updated and is allocated if B<*val> is
B<NULL>.
OSSL_PARAM_set_BN() stores the BIGNUM B<val> into the paramater B<p>.
OSSL_PARAM_set_BN() stores the BIGNUM B<val> into the parameter B<p>.
OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
pointed to by B<p>.
@@ -242,9 +237,9 @@ OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(),
OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr()
return a populated OSSL_PARAM structure.
OSSL_PARAM_locate() returns a pointer to the matching OSSL_PARAM object.
It returns B<NULL> on error or when no object matching B<key> exists in
the B<array>.
OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to
the matching OSSL_PARAM object. They return B<NULL> on error or when
no object matching B<key> exists in the B<array>.
All other functions return B<1> on success and B<0> on failure.
@@ -290,21 +285,19 @@ demonstrates that the requestor isn't obligated to request all
available parameters:
const char *foo = NULL;
size_t foo_l;
char bar[1024];
size_t bar_l;
const OSSL_PARAM request[] = {
OSSL_PARAM_UTF8_PTR("foo", foo, 0, foo_l),
OSSL_PARAM_UTF8_STRING("bar", bar, sizeof(bar), bar_l),
OSSL_PARAM request[] = {
OSSL_PARAM_utf8_ptr("foo", foo, 0),
OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
OSSL_PARAM_END
};
A I<responder> that receives this array (as C<params> in this example)
could fill in the parameters like this:
/* const OSSL_PARAM *params */
/* OSSL_PARAM *params */
const OSSL_PARAM *p;
OSSL_PARAM *p;
if ((p = OSSL_PARAM_locate(params, "foo")) == NULL)
OSSL_PARAM_set_utf8_ptr(p, "foo value");
doc/man3/OSSL_PROVIDER.pod
+2 -2
View File
@@ -16,7 +16,7 @@ OSSL_PROVIDER_add_builtin - provider routines
int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov);
const OSSL_ITEM *OSSL_PROVIDER_get_param_types(OSSL_PROVIDER *prov);
int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, const OSSL_PARAM params[]);
int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]);
int OSSL_PROVIDER_add_builtin(OPENSSL_CTX *, const char *name,
ossl_provider_init_fn *init_fn);
@@ -81,7 +81,7 @@ its build number.
OSSL_PROVIDER *prov = NULL;
const char *build = NULL;
size_t built_l = 0;
const OSSL_PARAM request[] = {
OSSL_PARAM request[] = {
{ "build", OSSL_PARAM_UTF8_STRING_PTR, &build, 0, &build_l },
{ NULL, 0, NULL, 0, NULL }
};
doc/man3/OSSL_STORE_LOADER.pod
+1 -1
View File
@@ -95,7 +95,7 @@ manner possible according to the scheme the loader implements, it also
takes a B<UI_METHOD> and associated data, to be used any time
something needs to be prompted for.
Furthermore, this function is expected to initialize what needs to be
initialized, to create a privata data store (B<OSSL_STORE_LOADER_CTX>, see
initialized, to create a private data store (B<OSSL_STORE_LOADER_CTX>, see
above), and to return it.
If something goes wrong, this function is expected to return NULL.
doc/man3/OSSL_STORE_expect.pod
+1 -1
View File
@@ -32,7 +32,7 @@ grained search of objects.
OSSL_STORE_supports_search() checks if the loader of the given OSSL_STORE
context supports the given search type.
See L<OSSL_STORE_SEARCH/SUPPORED CRITERION TYPES> for information on the
See L<OSSL_STORE_SEARCH/SUPPORTED CRITERION TYPES> for information on the
supported search criterion types.
OSSL_STORE_expect() and OSSL_STORE_find I<must> be called before the first
doc/man3/OSSL_trace_enabled.pod
+79 -18
View File
@@ -3,11 +3,17 @@
=head1 NAME
OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9
OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL,
OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4,
OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9,
OSSL_TRACEV,
OSSL_TRACE_ENABLED
- OpenSSL Tracing API
=head1 SYNOPSIS
=for comment generic
#include <openssl/trace.h>
int OSSL_trace_enabled(int category);
@@ -17,7 +23,13 @@ OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9
/* trace group macros */
OSSL_TRACE_BEGIN(category) {
...
...
if (some_error) {
/* Leave trace group prematurely in case of an error */
OSSL_TRACE_CANCEL(category);
goto err;
}
...
} OSSL_TRACE_END(category);
/* one-shot trace macros */
@@ -26,6 +38,10 @@ OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9
...
OSSL_TRACE9(category, format, arg1, ..., arg9)
/* check whether a trace category is enabled */
if (OSSL_TRACE_ENABLED(category)) {
...
}
=head1 DESCRIPTION
@@ -113,7 +129,7 @@ jumping out of a trace section:
OSSL_TRACE_BEGIN(TLS) {
if (condition) {
if (some_error) {
OSSL_TRACE_CANCEL(TLS);
goto err;
}
@@ -126,7 +142,7 @@ This will normally expand to:
do {
BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
if (trc_out != NULL) {
if (condition) {
if (some_error) {
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
goto err;
}
@@ -136,26 +152,71 @@ This will normally expand to:
} while (0);
C<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> are one-shot macros which essentially wrap
a single BIO_printf() into a tracing group.
C<OSSL_TRACE()> and C<OSSL_TRACE1()>, C<OSSL_TRACE2()>, ... C<OSSL_TRACE9()> are
so-called one-shot macros:
The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to:
The macro call C<OSSL_TRACE(category, text)>, produces literal text trace output.
OSSL_TRACE_BEGIN(category) {
BIO_printf(trc_out, format, arg1, ..., argN)
} OSSL_TRACE_END(category)
The macro call C<OSSL_TRACEn(category, format, arg1, ..., argn)> produces
printf-style trace output with n format field arguments (n=1,...,9).
It expands to:
OSSL_TRACE_BEGIN(category) {
BIO_printf(trc_out, format, arg1, ..., argN)
} OSSL_TRACE_END(category)
Internally, all one-shot macros are implemented using a generic C<OSSL_TRACEV()>
macro, since C90 does not support variadic macros. This helper macro has a rather
weird synopsis and should not be used directly.
The C<OSSL_TRACE_ENABLED(category)> macro can be used to conditionally execute
some code only if a specific trace category is enabled.
In some situations this is simpler than entering a trace section using
C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)>.
For example, the code
if (OSSL_TRACE_ENABLED(TLS)) {
...
}
expands to
if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
...
}
=head1 NOTES
It is advisable to always check that a trace type is enabled with
OSSL_trace_enabled() before generating any output, for example:
If producing the trace output requires carrying out auxiliary calculations,
this auxiliary code should be placed inside a conditional block which is
executed only if the trace category is enabled.
if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS)) {
BIO *trace = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
BIO_printf(trace, "FOO %d\n", somevalue);
BIO_dump(trace, somememory, somememory_l);
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
}
The most natural way to do this is to place the code inside the trace section
itself because it already introduces such a conditional block.
OSSL_TRACE_BEGIN(TLS) {
int var = do_some_auxiliary_calculation();
BIO_printf(trc_out, "var = %d\n", var);
} OSSL_TRACE_END(TLS);
In some cases it is more advantageous to use a simple conditional group instead
of a trace section. This is the case if calculations and tracing happen in
different locations of the code, or if the calculations are so time consuming
that placing them inside a (critical) trace section would create too much
contention.
if (OSSL_TRACE_ENABLED(TLS)) {
int var = do_some_auxiliary_calculation();
OSSL_TRACE1("var = %d\n", var);
}
Note however that premature optimization of tracing code is in general futile
and it's better to keep the tracing code as simple as possible.
Because most often the limiting factor for the application's speed is the time
it takes to print the trace output, not to calculate it.
=head2 Configure Tracing
doc/man3/RAND_DRBG_get0_master.pod
+26 -8
View File
@@ -2,6 +2,9 @@
=head1 NAME
OPENSSL_CTX_get0_master_drbg,
OPENSSL_CTX_get0_public_drbg,
OPENSSL_CTX_get0_private_drbg,
RAND_DRBG_get0_master,
RAND_DRBG_get0_public,
RAND_DRBG_get0_private
@@ -11,6 +14,9 @@ RAND_DRBG_get0_private
#include <openssl/rand_drbg.h>
RAND_DRBG *OPENSSL_CTX_get0_master_drbg(OPENSSL_CTX *ctx);
RAND_DRBG *OPENSSL_CTX_get0_public_drbg(OPENSSL_CTX *ctx);
RAND_DRBG *OPENSSL_CTX_get0_private_drbg(OPENSSL_CTX *ctx);
RAND_DRBG *RAND_DRBG_get0_master(void);
RAND_DRBG *RAND_DRBG_get0_public(void);
RAND_DRBG *RAND_DRBG_get0_private(void);
@@ -21,26 +27,35 @@ RAND_DRBG_get0_private
The default RAND API implementation (RAND_OpenSSL()) utilizes three
shared DRBG instances which are accessed via the RAND API:
The <public> and <private> DRBG are thread-local instances, which are used
The I<public> and I<private> DRBG are thread-local instances, which are used
by RAND_bytes() and RAND_priv_bytes(), respectively.
The <master> DRBG is a global instance, which is not intended to be used
The I<master> DRBG is a global instance, which is not intended to be used
directly, but is used internally to reseed the other two instances.
These functions here provide access to the shared DRBG instances.
=head1 RETURN VALUES
RAND_DRBG_get0_master() returns a pointer to the <master> DRBG instance.
OPENSSL_CTX_get0_master_drbg() returns a pointer to the I<master> DRBG instance
for the given OPENSSL_CTX B<ctx>.
RAND_DRBG_get0_public() returns a pointer to the <public> DRBG instance.
OPENSSL_CTX_get0_public_drbg() returns a pointer to the I<public> DRBG instance
for the given OPENSSL_CTX B<ctx>.
RAND_DRBG_get0_private() returns a pointer to the <private> DRBG instance.
OPENSSL_CTX_get0_private_drbg() returns a pointer to the I<private> DRBG instance
for the given OPENSSL_CTX B<ctx>.
In all the above cases the B<ctx> parameter can
be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_get0_master(),
RAND_DRBG_get0_public() and RAND_DRBG_get0_private() are the same as
OPENSSL_CTX_get0_master_drbg(), OPENSSL_CTX_get0_public_drbg() and
OPENSSL_CTX_get0_private_drbg() respectively except that the default OPENSSL_CTX
is always used.
=head1 NOTES
It is not thread-safe to access the <master> DRBG instance.
The <public> and <private> DRBG instance can be accessed safely, because
It is not thread-safe to access the I<master> DRBG instance.
The I<public> and I<private> DRBG instance can be accessed safely, because
they are thread-local. Note however, that changes to these two instances
apply only to the current thread.
@@ -65,7 +80,10 @@ L<RAND_DRBG(7)>
=head1 HISTORY
The RAND_DRBG functions were added in OpenSSL 1.1.1.
The OPENSSL_CTX_get0_master_drbg(), OPENSSL_CTX_get0_public_drbg() and
OPENSSL_CTX_get0_private_drbg() functions were added in OpenSSL 3.0.
All other RAND_DRBG functions were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
doc/man3/RAND_DRBG_new.pod
+20 -5
View File
@@ -2,7 +2,9 @@
=head1 NAME
RAND_DRBG_new_ex,
RAND_DRBG_new,
RAND_DRBG_secure_new_ex,
RAND_DRBG_secure_new,
RAND_DRBG_set,
RAND_DRBG_set_defaults,
@@ -15,11 +17,20 @@ RAND_DRBG_free
#include <openssl/rand_drbg.h>
RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx,
int type,
unsigned int flags,
RAND_DRBG *parent);
RAND_DRBG *RAND_DRBG_new(int type,
unsigned int flags,
RAND_DRBG *parent);
RAND_DRBG *RAND_DRBG_secure_new_ex(OPENSSL_CTX *ctx,
int type,
unsigned int flags,
RAND_DRBG *parent);
RAND_DRBG *RAND_DRBG_secure_new(int type,
unsigned int flags,
RAND_DRBG *parent);
@@ -39,10 +50,13 @@ RAND_DRBG_free
=head1 DESCRIPTION
RAND_DRBG_new() and RAND_DRBG_secure_new()
RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex()
create a new DRBG instance of the given B<type>, allocated from the heap resp.
the secure heap
(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
the secure heap, for the given OPENSSL_CTX <ctx>
(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). The <ctx> parameter can
be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_new() and
RAND_DRBG_secure_new() are the same as RAND_DRBG_new_ex() and
RAND_DRBG_secure_new_ex() except that the default OPENSSL_CTX is always used.
RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
@@ -108,8 +122,9 @@ uninstantiated state.
=head1 RETURN VALUES
RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
instance allocated on the heap, resp. secure heap.
RAND_DRBG_new_ex(), RAND_DRBG_new(), RAND_DRBG_secure_new_ex() and
RAND_DRBG_secure_new() return a pointer to a DRBG instance allocated on the
heap, resp. secure heap.
RAND_DRBG_set(),
RAND_DRBG_instantiate(), and
doc/man3/RAND_DRBG_set_callbacks.pod
+1 -1
View File
@@ -111,7 +111,7 @@ and is being used.
The derivation function is disabled during initialization by calling the
RAND_DRBG_set() function with the RAND_DRBG_FLAG_CTR_NO_DF flag.
For more information on the derivation function and when it can be omitted,
see [NIST SP 800-90A Rev. 1]. Roughly speeking it can be omitted if the random
see [NIST SP 800-90A Rev. 1]. Roughly speaking it can be omitted if the random
source has "full entropy", i.e., contains 8 bits of entropy per byte.
Even if a nonce is required, the B<get_nonce>() and B<cleanup_nonce>()
doc/man3/RSA_blinding_on.pod
+1 -2
View File
@@ -20,8 +20,7 @@ must be used to protect the RSA operation from that attack.
RSA_blinding_on() turns blinding on for key B<rsa> and generates a
random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
initialized B<BN_CTX>. The random number generator must be seeded
prior to calling RSA_blinding_on().
initialized B<BN_CTX>.
RSA_blinding_off() turns blinding off and frees the memory used for
the blinding factor.
doc/man3/RSA_generate_key.pod
+8 -5
View File
@@ -16,7 +16,7 @@ Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:
RSA *RSA_generate_key(int num, unsigned long e,
RSA *RSA_generate_key(int bits, unsigned long e,
void (*callback)(int, int, void *), void *cb_arg);
=head1 DESCRIPTION
@@ -27,8 +27,10 @@ be seeded prior to calling RSA_generate_key_ex().
RSA_generate_multi_prime_key() generates a multi-prime RSA key pair and stores
it in the B<RSA> structure provided in B<rsa>. The number of primes is given by
the B<primes> parameter. The pseudo-random number generator must be seeded prior
to calling RSA_generate_multi_prime_key().
the B<primes> parameter. The random number generator must be seeded when
calling RSA_generate_multi_prime_key().
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
The modulus size will be of length B<bits>, the number of primes to form the
modulus will be B<primes>, and the public exponent will be B<e>. Key sizes
@@ -47,7 +49,7 @@ progress of the key generation. If B<cb> is not B<NULL>, it
will be called as follows using the BN_GENCB_call() function
described on the L<BN_generate_prime(3)> page.
RSA_generate_prime() is similar to RSA_generate_prime_ex() but
RSA_generate_key() is similar to RSA_generate_key_ex() but
expects an old-style callback function; see
L<BN_generate_prime(3)> for information on the old-style callback.
@@ -88,7 +90,8 @@ B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<BN_generate_prime(3)>
L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<BN_generate_prime(3)>,
L<RAND(7)>
=head1 HISTORY
doc/man3/RSA_padding_add_PKCS1_type_1.pod
+4 -1
View File
@@ -100,6 +100,8 @@ simply copy the data
The random number generator must be seeded prior to calling
RSA_padding_add_xxx().
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
a valid encoding for a B<rsa_len> byte RSA key in the respective
@@ -143,7 +145,8 @@ including PKCS1_OAEP.
L<RSA_public_encrypt(3)>,
L<RSA_private_decrypt(3)>,
L<RSA_sign(3)>, L<RSA_verify(3)>
L<RSA_sign(3)>, L<RSA_verify(3)>,
L<RAND(7)>
=head1 COPYRIGHT
doc/man3/RSA_sign_ASN1_OCTET_STRING.pod
+6 -2
View File
@@ -26,7 +26,10 @@ memory.
B<dummy> is ignored.
The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING().
The random number generator must be seeded when calling
RSA_sign_ASN1_OCTET_STRING().
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf>
of size B<siglen> is the DER representation of a given octet string
@@ -49,7 +52,8 @@ These functions serve no recognizable purpose.
L<ERR_get_error(3)>,
L<RAND_bytes(3)>, L<RSA_sign(3)>,
L<RSA_verify(3)>
L<RSA_verify(3)>,
L<RAND(7)>
=head1 COPYRIGHT
doc/man3/SSL_CONF_cmd.pod
+14 -6
View File
@@ -79,9 +79,13 @@ B<ClientHello>.
The B<value> argument is a colon separated list of groups. The group can be
either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). Group
names are case sensitive. The list should be in order of preference with the
most preferred group first.
applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
(e.g B<prime256v1>). Group names are case sensitive. The list should be in
order of preference with the most preferred group first.
Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
B<ffdhe8192>.
=item B<-curves>
@@ -356,9 +360,13 @@ B<ClientHello>.
The B<value> argument is a colon separated list of groups. The group can be
either the B<NIST> name (e.g. B<P-256>), some other commonly used name where
applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). Group
names are case sensitive. The list should be in order of preference with the
most preferred group first.
applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
(e.g B<prime256v1>). Group names are case sensitive. The list should be in
order of preference with the most preferred group first.
Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
B<ffdhe8192>.
=item B<Curves>
doc/man3/SSL_CTX_new.pod
+12 -7
View File
@@ -94,28 +94,31 @@ The actual protocol version used will be negotiated to the highest version
mutually supported by the client and the server.
The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
Applications should use these methods, and avoid the version-specific
methods described below.
methods described below, which are deprecated.
=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
Use of these functions is deprecated. They have been replaced with the above
TLS_method(), TLS_server_method() and TLS_client_method() respectively. New
code should use those functions instead.
These functions do not exist anymore, they have been renamed to
TLS_method(), TLS_server_method() and TLS_client_method() respectively.
Currently, the old function calls are renamed to the corresponding new
ones by preprocessor macros, to ensure that existing code which uses the
old function names still compiles. However, using the old function names
is deprecated and new code should call the new functions instead.
=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
A TLS/SSL connection established with these methods will only understand the
TLSv1.2 protocol.
TLSv1.2 protocol. These methods are deprecated.
=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
A TLS/SSL connection established with these methods will only understand the
TLSv1.1 protocol.
TLSv1.1 protocol. These methods are deprecated.
=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
A TLS/SSL connection established with these methods will only understand the
TLSv1 protocol.
TLSv1 protocol. These methods are deprecated.
=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
@@ -131,10 +134,12 @@ Currently supported protocols are DTLS 1.0 and DTLS 1.2.
=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
These are the version-specific methods for DTLSv1.2.
These methods are deprecated.
=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
These are the version-specific methods for DTLSv1.
These methods are deprecated.
=back
doc/man3/SSL_CTX_set1_curves.pod
+7 -2
View File
@@ -39,11 +39,16 @@ SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen>
groups in the array B<glist>. The array consist of all NIDs of groups in
preference order. For a TLS client the groups are used directly in the
supported groups extension. For a TLS server the groups are used to
determine the set of shared groups.
determine the set of shared groups. Currently supported groups for
B<TLSv1.3> are B<NID_X9_62_prime256v1>, B<NID_secp384r1>, B<NID_secp521r1>,
B<NID_X25519>, B<NID_X448>, B<NID_ffdhe2048>, B<NID_ffdhe3072>,
B<NID_ffdhe4096>, B<NID_ffdhe6144> and B<NID_ffdhe8192>.
SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to
string B<list>. The string is a colon separated list of group NIDs or
names, for example "P-521:P-384:P-256".
names, for example "P-521:P-384:P-256:X25519:ffdhe2048". Currently supported
groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>, B<X25519>, B<X448>,
B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>, B<ffdhe8192>.
SSL_set1_groups() and SSL_set1_groups_list() are similar except they set
supported groups for the SSL structure B<ssl>.
doc/man3/SSL_CTX_set_cipher_list.pod
+19 -2
View File
@@ -5,7 +5,9 @@
SSL_CTX_set_cipher_list,
SSL_set_cipher_list,
SSL_CTX_set_ciphersuites,
SSL_set_ciphersuites
SSL_set_ciphersuites,
OSSL_default_cipher_list,
OSSL_default_ciphersuites
- choose list of available SSL_CIPHERs
=head1 SYNOPSIS
@@ -18,6 +20,9 @@ SSL_set_ciphersuites
int SSL_CTX_set_ciphersuites(SSL_CTX *ctx, const char *str);
int SSL_set_ciphersuites(SSL *s, const char *str);
const char *OSSL_default_cipher_list(void);
const char *OSSL_default_ciphersuites(void);
=head1 DESCRIPTION
SSL_CTX_set_cipher_list() sets the list of available ciphers (TLSv1.2 and below)
@@ -31,7 +36,7 @@ B<ssl>.
SSL_CTX_set_ciphersuites() is used to configure the available TLSv1.3
ciphersuites for B<ctx>. This is a simple colon (":") separated list of TLSv1.3
ciphersuite names in order of perference. Valid TLSv1.3 ciphersuite names are:
ciphersuite names in order of preference. Valid TLSv1.3 ciphersuite names are:
=over 4
@@ -54,6 +59,10 @@ An empty list is permissible. The default value for the this setting is:
SSL_set_ciphersuites() is the same as SSL_CTX_set_ciphersuites() except it
configures the ciphersuites for B<ssl>.
OSSL_default_cipher_list() returns the default cipher string for TLSv1.2
(and earlier) ciphers. OSSL_default_ciphersuites() returns the default
cipher string for TLSv1.3 ciphersuites.
=head1 NOTES
The control string B<str> for SSL_CTX_set_cipher_list() and
@@ -85,6 +94,10 @@ of 512 bits and the server is not configured to use temporary RSA
keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
and the handshake will fail.
OSSL_default_cipher_list() and OSSL_default_ciphersuites() replace
SSL_DEFAULT_CIPHER_LIST and TLS_DEFAULT_CIPHERSUITES, respectively. The
cipher list defines are deprecated as of 3.0.0.
=head1 RETURN VALUES
SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
@@ -100,6 +113,10 @@ L<SSL_CTX_use_certificate(3)>,
L<SSL_CTX_set_tmp_dh_callback(3)>,
L<ciphers(1)>
=head1 HISTORY
OSSL_default_cipher_list() and OSSL_default_ciphersites() are new in 3.0.0.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/SSL_CTX_set_generate_session_id.pod
+2 -2
View File
@@ -10,7 +10,7 @@ SSL_has_matching_session_id, GEN_SESSION_CB
#include <openssl/ssl.h>
typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id,
typedef int (*GEN_SESSION_CB)(SSL *ssl, unsigned char *id,
unsigned int *id_len);
int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb);
@@ -98,7 +98,7 @@ server id given, and will fill the rest with pseudo random bytes:
const char session_id_prefix = "www-18";
#define MAX_SESSION_ID_ATTEMPTS 10
static int generate_session_id(const SSL *ssl, unsigned char *id,
static int generate_session_id(SSL *ssl, unsigned char *id,
unsigned int *id_len)
{
unsigned int count = 0;
doc/man3/SSL_CTX_set_srp_password.pod
+1 -1
View File
@@ -111,7 +111,7 @@ user salt, B<v> the password verifier and B<info> is the optional user info.
The SSL_set_srp_server_param_pw() function sets all SRP parameters for the
connection B<s> by generating a random salt and a password verifier.
B<user> is the username, B<pass> the password and B<grp> the SRP group paramters
B<user> is the username, B<pass> the password and B<grp> the SRP group parameters
identifier for L<SRP_get_default_gN(3)>.
The SSL_get_srp_g() function returns the SRP group generator for B<s>, or from
doc/man3/SSL_CTX_set_verify.pod
+5 -5
View File
@@ -102,7 +102,7 @@ B<Server mode:> if the client did not return a certificate, the TLS/SSL
handshake is immediately terminated with a "handshake failure" alert.
This flag must be used together with SSL_VERIFY_PEER.
B<Client mode:> ignored
B<Client mode:> ignored (see BUGS)
=item SSL_VERIFY_CLIENT_ONCE
@@ -112,7 +112,7 @@ renegotiation or post-authentication if a certificate was requested
during the initial handshake. This flag must be used together with
SSL_VERIFY_PEER.
B<Client mode:> ignored
B<Client mode:> ignored (see BUGS)
=item SSL_VERIFY_POST_HANDSHAKE
@@ -123,7 +123,7 @@ to be configured for post-handshake peer verification before the
handshake occurs. This flag must be used together with
SSL_VERIFY_PEER. TLSv1.3 only; no effect on pre-TLSv1.3 connections.
B<Client mode:> ignored
B<Client mode:> ignored (see BUGS)
=back
@@ -203,8 +203,8 @@ message is sent to the client.
=head1 BUGS
In client mode, it is not checked whether the SSL_VERIFY_PEER flag
is set, but whether any flags are set. This can lead to
unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as
is set, but whether any flags other than SSL_VERIFY_NONE are set. This can
lead to unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as
required.
=head1 RETURN VALUES
doc/man3/SSL_SESSION_get0_hostname.pod
+1 -1
View File
@@ -6,7 +6,7 @@ SSL_SESSION_get0_hostname,
SSL_SESSION_set1_hostname,
SSL_SESSION_get0_alpn_selected,
SSL_SESSION_set1_alpn_selected
- get and set SNI and ALPN data ssociated with a session
- get and set SNI and ALPN data associated with a session
=head1 SYNOPSIS
doc/man3/SSL_get_error.pod
+3 -3
View File
@@ -14,9 +14,9 @@ SSL_get_error - obtain result code for TLS/SSL I/O operation
SSL_get_error() returns a result code (suitable for the C "switch"
statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(),
SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_write_ex() or
SSL_write() on B<ssl>. The value returned by that TLS/SSL I/O function must be
passed to SSL_get_error() in parameter B<ret>.
SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_shutdown(),
SSL_write_ex() or SSL_write() on B<ssl>. The value returned by that TLS/SSL I/O
function must be passed to SSL_get_error() in parameter B<ret>.
In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
current thread's OpenSSL error queue. Thus, SSL_get_error() must be
doc/man3/SSL_write.pod
+1 -1
View File
@@ -125,7 +125,7 @@ of bytes of the file written to the TLS/SSL connection.
=item E<lt> 0
The write operation was not successful, because either the connection was
closed, an error occured or action must be taken by the calling process.
closed, an error occurred or action must be taken by the calling process.
Call SSL_get_error() with the return value to find out the reason.
=back
doc/man3/X509_STORE_new.pod
+1 -1
View File
@@ -23,7 +23,7 @@ X509_STORE_up_ref() increments the reference count associated with the
X509_STORE object.
X509_STORE_lock() locks the store from modification by other threads,
X509_STORE_unlock() locks it.
X509_STORE_unlock() unlocks it.
X509_STORE_free() frees up a single X509_STORE object.
doc/man3/X509_cmp.pod
+80
View File
@@ -0,0 +1,80 @@
=pod
=head1 NAME
X509_cmp, X509_NAME_cmp,
X509_issuer_and_serial_cmp, X509_issuer_name_cmp, X509_subject_name_cmp,
X509_CRL_cmp, X509_CRL_match
- compare X509 certificates and related values
=head1 SYNOPSIS
#include <openssl/x509.h>
int X509_cmp(const X509 *a, const X509 *b);
int X509_NAME_cmp(const X509_NAME *a, const X509_NAME *b);
int X509_issuer_and_serial_cmp(const X509 *a, const X509 *b);
int X509_issuer_name_cmp(const X509 *a, const X509 *b);
int X509_subject_name_cmp(const X509 *a, const X509 *b);
int X509_CRL_cmp(const X509_CRL *a, const X509_CRL *b);
int X509_CRL_match(const X509_CRL *a, const X509_CRL *b);
=head1 DESCRIPTION
This set of functions are used to compare X509 objects, including X509
certificates, X509 CRL objects and various values in an X509 certificate.
The X509_cmp() function compares two B<X509> objects indicated by parameters
B<a> and B<b>. The comparison is based on the B<memcmp> result of the hash
values of two B<X509> objects and the canonical (DER) encoding values.
The X509_NAME_cmp() function compares two B<X509_NAME> objects indicated by
parameters B<a> and B<b>. The comparison is based on the B<memcmp> result of
the canonical (DER) encoding values of the two objects. L<i2d_X509_NAME(3)>
has a more detailed description of the DER encoding of the B<X509_NAME> structure.
The X509_issuer_and_serial_cmp() function compares the serial number and issuer
values in the given B<X509> objects B<a> and B<b>.
The X509_issuer_name_cmp(), X509_subject_name_cmp() and X509_CRL_cmp() functions
are effectively wrappers of the X509_NAME_cmp() function. These functions compare
issuer names and subject names of the X<509> objects, or issuers of B<X509_CRL>
objects, respectively.
The X509_CRL_match() function compares two B<X509_CRL> objects. Unlike the
X509_CRL_cmp() function, this function compares the whole CRL content instead
of just the issuer name.
=head1 RETURN VALUES
Like common memory comparison functions, the B<X509> comparison functions return
an integer less than, equal to, or greater than zero if object B<a> is found to
be less than, to match, or be greater than object B<b>, respectively.
X509_NAME_cmp(), X509_issuer_and_serial_cmp(), X509_issuer_name_cmp(),
X509_subject_name_cmp() and X509_CRL_cmp() may return B<-2> to indicate an error.
=head1 NOTES
These functions in fact utilize the underlying B<memcmp> of the C library to do
the comparison job. Data to be compared varies from DER encoding data, hash
value or B<ASN1_STRING>. The sign of the comparison can be used to order the
objects but it does not have a special meaning in some cases.
X509_NAME_cmp() and wrappers utilize the value B<-2> to indicate errors in some
circumstances, which could cause confusion for the applications.
=head1 SEE ALSO
L<i2d_X509_NAME(3)>, L<i2d_X509(3)>
=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_dup.pod
+21 -2
View File
@@ -116,20 +116,39 @@ OCSP_SIGNATURE_free,
OCSP_SIGNATURE_new,
OCSP_SINGLERESP_free,
OCSP_SINGLERESP_new,
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_free,
OSSL_CMP_PKISTATUS_it,
OSSL_CRMF_CERTID_free,
OSSL_CRMF_CERTID_it,
OSSL_CRMF_CERTID_new,
OSSL_CRMF_CERTTEMPLATE_free,
OSSL_CRMF_CERTTEMPLATE_it,
OSSL_CRMF_CERTTEMPLATE_new,
OSSL_CRMF_ENCRYPTEDVALUE_free,
OSSL_CRMF_ENCRYPTEDVALUE_it,
OSSL_CRMF_ENCRYPTEDVALUE_new,
OSSL_CRMF_MSGS_free,
OSSL_CRMF_MSGS_it,
OSSL_CRMF_MSGS_new,
OSSL_CRMF_MSG_free,
OSSL_CRMF_MSG_it,
OSSL_CRMF_MSG_new,
OSSL_CRMF_PBMPARAMETER_free,
OSSL_CRMF_PBMPARAMETER_it,
OSSL_CRMF_PBMPARAMETER_new,
OSSL_CRMF_PKIPUBLICATIONINFO_free,
OSSL_CRMF_PKIPUBLICATIONINFO_it,
OSSL_CRMF_PKIPUBLICATIONINFO_new,
OSSL_CRMF_MSGS_free,
OSSL_CRMF_MSGS_new,
OSSL_CRMF_SINGLEPUBINFO_free,
OSSL_CRMF_SINGLEPUBINFO_it,
OSSL_CRMF_SINGLEPUBINFO_new,
OTHERNAME_free,
OTHERNAME_new,
PBE2PARAM_free,
doc/man3/X509_get0_sm2_id.pod
+10 -2
View File
@@ -2,7 +2,9 @@
=head1 NAME
X509_get0_sm2_id, X509_set0_sm2_id - get or set SM2 ID for certificate operations
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
@@ -10,6 +12,8 @@ X509_get0_sm2_id, X509_set0_sm2_id - get or set SM2 ID for certificate operation
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
@@ -21,6 +25,10 @@ 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
@@ -29,7 +37,7 @@ ability to set and retrieve the SM2 ID value.
=head1 RETURN VALUES
X509_set0_sm2_id() does not return a value.
X509_set0_sm2_id() and X509_REQ_set0_sm2_id() do not return a value.
=head1 SEE ALSO
doc/man3/d2i_X509.pod
+29 -6
View File
@@ -93,6 +93,16 @@ d2i_OCSP_REVOKEDINFO,
d2i_OCSP_SERVICELOC,
d2i_OCSP_SIGNATURE,
d2i_OCSP_SINGLERESP,
d2i_OSSL_CMP_MSG,
d2i_OSSL_CMP_PKIHEADER,
d2i_OSSL_CRMF_CERTID,
d2i_OSSL_CRMF_CERTTEMPLATE,
d2i_OSSL_CRMF_ENCRYPTEDVALUE,
d2i_OSSL_CRMF_MSG,
d2i_OSSL_CRMF_MSGS,
d2i_OSSL_CRMF_PBMPARAMETER,
d2i_OSSL_CRMF_PKIPUBLICATIONINFO,
d2i_OSSL_CRMF_SINGLEPUBINFO,
d2i_OTHERNAME,
d2i_PBE2PARAM,
d2i_PBEPARAM,
@@ -269,6 +279,16 @@ i2d_OCSP_REVOKEDINFO,
i2d_OCSP_SERVICELOC,
i2d_OCSP_SIGNATURE,
i2d_OCSP_SINGLERESP,
i2d_OSSL_CMP_MSG,
i2d_OSSL_CMP_PKIHEADER,
i2d_OSSL_CRMF_CERTID,
i2d_OSSL_CRMF_CERTTEMPLATE,
i2d_OSSL_CRMF_ENCRYPTEDVALUE,
i2d_OSSL_CRMF_MSG,
i2d_OSSL_CRMF_MSGS,
i2d_OSSL_CRMF_PBMPARAMETER,
i2d_OSSL_CRMF_PKIPUBLICATIONINFO,
i2d_OSSL_CRMF_SINGLEPUBINFO,
i2d_OTHERNAME,
i2d_PBE2PARAM,
i2d_PBEPARAM,
@@ -305,7 +325,6 @@ i2d_POLICYQUALINFO,
i2d_PROFESSION_INFO,
i2d_PROXY_CERT_INFO_EXTENSION,
i2d_PROXY_POLICY,
i2d_PublicKey,
i2d_RSAPrivateKey,
i2d_RSAPrivateKey_bio,
i2d_RSAPrivateKey_fp,
@@ -503,8 +522,8 @@ Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
or B<NULL> if an error occurs. If the "reuse" capability has been used with
a valid structure being passed in via B<a>, then the object is not freed in
the event of error but may be in a potentially invalid or inconsistent state.
a valid structure being passed in via B<a>, then the object is freed in
the event of error and B<*a> is set to NULL.
i2d_TYPE() returns the number of bytes successfully encoded or a negative
value if an error occurs.
@@ -585,9 +604,13 @@ happen.
=head1 BUGS
In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
B<*px> is valid is broken and some parts of the reused structure may
persist if they are not present in the new one. As a result the use
of this "reuse" behaviour is strongly discouraged.
B<*a> is valid is broken and some parts of the reused structure may
persist if they are not present in the new one. Additionally, in versions of
OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
the behaviour is inconsistent. Some functions behaved as described here, while
some did not free B<*a> on error and did not set B<*a> to NULL.
As a result of the above issues the "reuse" behaviour is strongly discouraged.
i2d_TYPE() will not return an error in many versions of OpenSSL,
if mandatory fields are not initialized due to a programming error
doc/man7/EVP_KDF_PBKDF2.pod
+35 -6
View File
@@ -10,7 +10,7 @@ Support for computing the B<PBKDF2> password-based KDF through the B<EVP_KDF>
API.
The EVP_KDF_PBKDF2 algorithm implements the PBKDF2 password-based key
derivation function, as described in RFC 2898; it derives a key from a password
derivation function, as described in SP800-132; it derives a key from a password
using a salt and iteration count.
=head2 Numeric identity
@@ -30,13 +30,38 @@ The supported controls are:
=item B<EVP_KDF_CTRL_SET_ITER>
This control has a default value of 2048.
=item B<EVP_KDF_CTRL_SET_MD>
These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
B<iter> is the iteration count and its value should be greater than or equal to
1. RFC 2898 suggests an iteration count of at least 1000. The default value is
2048. Any B<iter> less than 1 is treated as a single iteration.
=item B<EVP_KDF_CTRL_SET_PBKDF2_PKCS5_MODE>
This control expects one argument: C<int mode>
This control can be used to enable or disable SP800-132 compliance checks.
Setting the mode to 0 enables the compliance checks.
The checks performed are:
=over 4
=item - the iteration count is at least 1000.
=item - the salt length is at least 128 bits.
=item - the derived key length is at least 112 bits.
=back
The default provider uses a default mode of 1 for backwards compatibility,
and the fips provider uses a default mode of 0.
EVP_KDF_ctrl_str() type string: "pkcs5"
The value string is expected to be a decimal number 0 or 1.
=back
@@ -55,7 +80,7 @@ byte sequence.
=head1 CONFORMING TO
RFC 2898
SP800-132
=head1 SEE ALSO
@@ -66,9 +91,13 @@ L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.0.
=head1 COPYRIGHT
Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2018-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
doc/man7/EVP_KDF_SS.pod
+1 -1
View File
@@ -11,7 +11,7 @@ SSKDF derives a key using input such as a shared secret key (that was generated
during the execution of a key establishment scheme) and fixedinfo.
SSKDF is also informally referred to as 'Concat KDF'.
=head2 Auxilary function
=head2 Auxiliary function
The implementation uses a selectable auxiliary function H, which can be one of:
doc/man7/EVP_KDF_SSHKDF.pod
+4 -4
View File
@@ -68,12 +68,12 @@ Sets the type for the SSHHKDF operation. There are six supported types:
=over 4
=item EVP_KDF_SSHKDF_TYPE_ININITAL_IV_CLI_TO_SRV
=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
The Initial IV from client to server.
A single char of value 65 (ASCII char 'A').
=item EVP_KDF_SSHKDF_TYPE_ININITAL_IV_SRV_TO_CLI
=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
The Initial IV from server to client
A single char of value 66 (ASCII char 'B').
@@ -103,7 +103,7 @@ A single char of value 70 (ASCII char 'F').
EVP_KDF_ctrl_str() type string: "type"
The value is a string of length one character. The only valid values
are the numerical values of the ASCII caracters: "A" (65) to "F" (70).
are the numerical values of the ASCII characters: "A" (65) to "F" (70).
=back
@@ -142,7 +142,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
if (EVP_KDF_CTX_set1_sshkdf_session_id(kctx, session_id, 32) <= 0)
/* Error */
if (EVP_KDF_CTX_set_sshkdf_type(kctx,
EVP_KDF_SSHKDF_TYPE_ININITAL_IV_CLI_TO_SRV) <= 0)
EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV) <= 0)
/* Error */
if (EVP_KDF_derive(kctx, out, &outlen) <= 0)
/* Error */
doc/man7/EVP_KDF_X942.pod
+150
View File
@@ -0,0 +1,150 @@
=pod
=head1 NAME
EVP_KDF_X942 - The X9.42-2001 asn1 EVP_KDF implementation
=head1 DESCRIPTION
The EVP_KDF_X942 algorithm implements the key derivation function (X942KDF).
X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
derive a key using input such as a shared secret key and other info. The other
info is DER encoded data that contains a 32 bit counter.
=head2 Numeric identity
B<EVP_KDF_X942> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.
=head2 Supported controls
The supported controls are:
=over 4
=item B<EVP_KDF_CTRL_SET_MD>
This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
=item B<EVP_KDF_CTRL_SET_KEY>
This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
The shared secret used for key derivation. This control sets the secret.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "secret"
The value string is used as is.
=item "hexsecret"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_UKM>
This control expects two arguments: C<unsigned char *ukm>, C<size_t ukmlen>
An optional random string that is provided by the sender called "partyAInfo".
In CMS this is the user keying material.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "ukm"
The value string is used as is.
=item "hexukm"
The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.
=back
=item B<EVP_KDF_CTRL_SET_CEK_ALG>
This control expects one argument: C<char *alg>
The CEK wrapping algorithm name.
EVP_KDF_ctrl_str() type string: "cekalg"
The value string is used as is.
=back
=head1 NOTES
A context for X942KDF can be obtained by calling:
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
The output length of an X942KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
=head1 EXAMPLE
This example derives 24 bytes, with the secret key "secret" and a random user
keying material:
EVP_KDF_CTX *kctx;
unsigned char out[192/8];
unsignred char ukm[64];
if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
error("RAND_bytes");
kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
if (kctx == NULL)
error("EVP_KDF_CTX_new_id");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0)
error("EVP_KDF_CTRL_SET_MD");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0)
error("EVP_KDF_CTRL_SET_KEY");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_UKM, ukm, sizeof(ukm)) <= 0)
error("EVP_KDF_CTRL_SET_UKM");
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_CEK_ALG,
SN_id_smime_alg_CMS3DESwrap) <= 0)
error("EVP_KDF_CTRL_SET_CEK_ALG");
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
error("EVP_KDF_derive");
EVP_KDF_CTX_free(kctx);
=head1 CONFORMING TO
RFC 2631
=head1 SEE ALSO
L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>
=head1 HISTORY
This functionality was added to OpenSSL 3.0.0.
=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/man7/EVP_KDF_X963.pod
+1 -1
View File
@@ -71,7 +71,7 @@ decoded before being passed on as the control value.
=head1 NOTES
X963KDF is very similar to the SSKDF that uses a digest as the auxilary function,
X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function,
X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.
A context for X963KDF can be obtained by calling:
doc/man7/RAND.pod
+6
View File
@@ -28,6 +28,12 @@ As a normal application developer, you do not have to worry about any details,
just use L<RAND_bytes(3)> to obtain random data.
Having said that, there is one important rule to obey: Always check the error
return value of L<RAND_bytes(3)> and do not take randomness for granted.
Although (re-)seeding is automatic, it can fail because no trusted random source
is available or the trusted source(s) temporarily fail to provide sufficient
random seed material.
In this case the CSPRNG enters an error state and ceases to provide output,
until it is able to recover from the error by reseeding itself.
For more details on reseeding and error recovery, see L<RAND_DRBG(7)>.
For values that should remain secret, you can use L<RAND_priv_bytes(3)>
instead.
doc/man7/property.pod
+172
View File
@@ -0,0 +1,172 @@
=pod
=head1 NAME
property - Properties, a selection mechanism for algorithm implementations
=head1 DESCRIPTION
As of OpenSSL 3.0, a new method has been introduced to decide which of
multiple implementations of an algorithm will be used.
The method is centered around the concept of properties.
Each implementation defines a number of properties and when an algorithm
is being selected, filters based on these properties can be used to
choose the most appropriate implementation of the algorithm.
Properties are like variables, they are referenced by name and have a value
assigned.
=head2 Property Names
Property names fall into two categories: those reserved by the OpenSSL
project and user defined names.
A I<reserved> property name consists of a single C-style identifier
(except for leading underscores not being permitted), which begins
with a letter and can be followed by any number of letters, numbers
and underscores.
Property names are case-insensitive, but OpenSSL will only use lowercase
letters.
A I<user defined> property name is similar, but it B<must> consist of
two or more C-style identifiers, separated by periods.
The last identifier in the name can be considered the 'true' property
name, which is prefixed by some sort of 'namespace'.
Providers for example could include their name in the prefix and use
property names like
<provider_name>.<property_name>
<provider_name>.<algorithm_name>.<property_name>
=head2 Properties
A I<property> is a I<name=value> pair.
A I<property definition> is a sequence of comma separated properties.
There can be any number of properties in a definition.
For example: "" defines a null property definition; "my.foo=bar"
defines a property named I<my.foo> which has a string value I<bar> and
"iteration.count=3" defines a property named I<iteration.count> which
has a numeric value of I<3>.
The full syntax for property definitions appears below.
=head2 Implementations
Each implementation of an algorithm can define any number of
properties.
For example, the default provider defines the property I<default=yes>
for all of its algorithms.
Likewise, the FIPS provider defines I<fips=yes> and the legacy provider
defines I<legacy=yes> for all of their algorithms.
=head2 Queries
A I<property query clause> is a single conditional test.
For example, "fips=yes", "default!=yes" or "?iteration.count!=3".
The first two represent mandatory clauses, such clauses B<must> match
for any algorithm to even be under consideration.
The third clause represents an optional clause.
Matching such clauses is not a requirement, but any additional optional
match counts in favor of the algorithm.
More details about that in the B<Lookups> section.
A I<property query> is a sequence of comma separated property query clauses.
The full syntax for property queries appears below, but the available syntactic
features are:
=over 4
=item *
B<=> is an infix operator providing an equality test.
=item *
B<!=> is an infix operator providing an inequality test.
=item *
B<?> is a prefix operator that means that the following clause is optional
but preferred.
=item *
B<-> is a prefix operator that means any global query clause involving the
following property name should be ignored.
=item *
B<"..."> is a quoted string.
The quotes are not included in the body of the string.
=item *
B<'...'> is a quoted string.
The quotes are not included in the body of the string.
=back
=head2 Lookups
When an algorithm is looked up, a property query is used to determine
the best matching algorithm.
All mandatory query clauses B<must> be present and the implementation
that additionally has the largest number of matching optional query
clauses will be used.
If there is more than one such optimal candidate, the result will be
chosen from amongst those in an indeterminate way.
Ordering of optional clauses is not significant.
=head2 Shortcut
In order to permit a more concise expression of boolean properties, there
is one short cut: a property name alone (e.g. "default") is
exactly equivalent to "default=yes" in both definitions and queries.
=head2 Global and Local
Two levels of property query are supported.
A context based property query that applies to all fetch operations and a local
property query.
Where both the context and local queries include a clause with the same name,
the local clause overrides the context clause.
It is possible for a local property query to remove a clause in the context
property query by preceding the property name with a '-'.
For example, a context property query that contains "fips=yes" would normally
result in implementations that have "fips=yes".
However, if the setting of the "fips" property is irrelevant to the
operations being performed, the local property query can include the
clause "-fips".
Note that the local property query could not use "fips=no" because that would
disallow any implementations with "fips=yes" rather than not caring about the
setting.
=head1 SYNTAX
The lexical syntax in EBNF is given by:
Definition ::= PropertyName ( '=' Value )?
( ',' PropertyName ( '=' Value )? )*
Query ::= PropertyQuery ( ',' PropertyQuery )*
PropertyQuery ::= '-' PropertyName
| '?'? ( PropertyName (( '=' | '!=' ) Value)?)
Value ::= NumberLiteral | StringLiteral
StringLiteral ::= QuotedString | UnquotedString
QuotedString ::= '"' [^"]* '"' | "'" [^']* "'"
UnquotedString ::= [^{space},]+
NumberLiteral ::= '0' ( [0-7]* | 'x' [0-9A-Fa-f]+ ) | '-'? [1-9] [0-9]+
PropertyName ::= [A-Z] [A-Z0-9_]* ( '.' [A-Z] [A-Z0-9_]* )*
=head1 HISTORY
Properties were added in OpenSSL 3.0
=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