Fix crash and latest update.
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct
|
||||
- generic method constructor
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include "internal/core.h"
|
||||
|
||||
struct ossl_method_construct_method_st {
|
||||
/* Create store */
|
||||
void *(*alloc_tmp_store)(void);
|
||||
/* 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 *propquery,
|
||||
void *data);
|
||||
/* Store a method in a store */
|
||||
int (*put)(OPENSSL_CTX *libctx, void *store, const char *propdef,
|
||||
void *method, void *data);
|
||||
/* Construct a new method */
|
||||
void *(*construct)(const OSSL_DISPATCH *fns, OSSL_PROVIDER *prov,
|
||||
void *data);
|
||||
/* Destruct a method */
|
||||
void (*destruct)(void *method);
|
||||
};
|
||||
typedef struct ossl_method_construct_method OSSL_METHOD_CONSTRUCT_METHOD;
|
||||
|
||||
void *ossl_method_construct(OPENSSL_CTX *ctx, int operation_id,
|
||||
const char *name, const char *properties,
|
||||
int force_cache,
|
||||
OSSL_METHOD_CONSTRUCT_METHOD *mcm, void *mcm_data);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
All libcrypto sub-systems that want to create their own methods based
|
||||
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.
|
||||
|
||||
=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
|
||||
functions given by the sub-system specific method creator through
|
||||
C<mcm> and the data in C<mcm_data> (which is passed by
|
||||
ossl_method_construct()).
|
||||
|
||||
=head2 Structures
|
||||
|
||||
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
|
||||
function pointers:
|
||||
|
||||
=over 4
|
||||
|
||||
=item alloc_tmp_store()
|
||||
|
||||
Create a temporary method store.
|
||||
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.
|
||||
|
||||
=item dealloc_tmp_store()
|
||||
|
||||
Remove a temporary store.
|
||||
|
||||
=item get()
|
||||
|
||||
Look up an already existing method from a store.
|
||||
|
||||
The store may be given with C<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>.
|
||||
|
||||
The method to be looked up should be identified with data from C<data>
|
||||
(which is the C<mcm_data> that was passed to ossl_construct_method())
|
||||
and the provided property query C<propquery>.
|
||||
|
||||
=item put()
|
||||
|
||||
Places the C<method> created by the construct() function (see below)
|
||||
in a store.
|
||||
|
||||
The store may be given with C<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>.
|
||||
|
||||
The method should be associated with the given property definition
|
||||
C<propdef> and any identification data given through C<data> (which is
|
||||
the C<mcm_data> that was passed to ossl_construct_method()).
|
||||
|
||||
=item construct()
|
||||
|
||||
Constructs a sub-system method given a dispatch table C<fns>.
|
||||
|
||||
The associated I<provider object> C<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().
|
||||
|
||||
=item desctruct()
|
||||
|
||||
Destruct the given C<method>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ossl_method_construct() returns a constructed method on success, or
|
||||
B<NULL> on error.
|
||||
|
||||
=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
|
||||
@@ -0,0 +1,215 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ossl_provider_find, ossl_provider_new, ossl_provider_upref,
|
||||
ossl_provider_free, ossl_provider_add_module_location,
|
||||
ossl_provider_activate, 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,
|
||||
ossl_provider_get_params, ossl_provider_query_operation
|
||||
- internal provider routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include "internal/provider.h"
|
||||
|
||||
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);
|
||||
void ossl_provider_free(OSSL_PROVIDER *prov);
|
||||
|
||||
/* Setters */
|
||||
int ossl_provider_add_module_location(OSSL_PROVIDER *prov, const char *loc);
|
||||
|
||||
/* Load and initialize the Provider */
|
||||
int ossl_provider_activate(OSSL_PROVIDER *prov);
|
||||
|
||||
/* Iterate over all loaded providers */
|
||||
int ossl_provider_forall_loaded(OPENSSL_CTX *,
|
||||
int (*cb)(OSSL_PROVIDER *provider,
|
||||
void *cbdata),
|
||||
void *cbdata);
|
||||
|
||||
/* Getters for other library functions */
|
||||
const char *ossl_provider_name(OSSL_PROVIDER *prov);
|
||||
const DSO *ossl_provider_dso(OSSL_PROVIDER *prov);
|
||||
const char *ossl_provider_module_name(OSSL_PROVIDER *prov);
|
||||
const char *ossl_provider_module_path(OSSL_PROVIDER *prov);
|
||||
|
||||
/* 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[]);
|
||||
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
|
||||
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.
|
||||
|
||||
A I<provider object> is always stored in a set of I<provider object>s
|
||||
in the library context.
|
||||
|
||||
I<provider object>s are reference counted.
|
||||
|
||||
I<provider object>s 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 it's 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_free() decrements a I<provider object>'s reference
|
||||
counter; if it drops to one, the I<provider object> will be
|
||||
inactivated (it's teardown function is called) but kept in the store;
|
||||
if it drops down to zero, the associated module will be unloaded if
|
||||
one was loaded, and the I<provider object> will be freed.
|
||||
|
||||
ossl_provider_add_module_location() adds a location to look for a
|
||||
provider module.
|
||||
|
||||
ossl_provider_activate() "activates" the provider for the given
|
||||
I<provider object>.
|
||||
What "activates" means depends on what type of I<provider object> it
|
||||
is:
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
If an initialization function was given with ossl_provider_new(), that
|
||||
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
|
||||
be located in that module, and called.
|
||||
|
||||
=back
|
||||
|
||||
ossl_provider_forall_loaded() iterates over all the currently
|
||||
"activated" providers, and calls C<cb> for each of them.
|
||||
|
||||
ossl_provider_name() returns the name that was given with
|
||||
ossl_provider_new().
|
||||
|
||||
ossl_provider_dso() returns a reference to the module, for providers
|
||||
that come in the form of loadable modules.
|
||||
|
||||
ossl_provider_module_name() returns the file name of the module, for
|
||||
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
|
||||
the provider has one.
|
||||
|
||||
ossl_provider_get_param_types() calls the provider's C<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>.
|
||||
|
||||
ossl_provider_get_params() calls the provider's parameter request
|
||||
responder.
|
||||
It should treat the given C<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>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Locating a provider module happens as follows:
|
||||
|
||||
=over 4
|
||||
|
||||
=item 1.
|
||||
|
||||
Look in each directory given by ossl_provider_add_module_location().
|
||||
|
||||
=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>.
|
||||
|
||||
=back
|
||||
|
||||
=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.
|
||||
|
||||
ossl_provider_upref() returns the value of the reference counter after
|
||||
it has been incremented.
|
||||
|
||||
ossl_provider_free() doesn't return any value.
|
||||
|
||||
ossl_provider_add_module_location() 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>
|
||||
is returned.
|
||||
|
||||
ossl_provider_teardown() doesnt't return any value.
|
||||
|
||||
ossl_provider_get_param_types() returns a pointer to an C<OSSL_ITEM>
|
||||
array if this function is available in the provider, otherwise
|
||||
B<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)>
|
||||
|
||||
=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
|
||||
@@ -18,6 +18,7 @@ B<openssl list>
|
||||
[B<-cipher-algorithms>]
|
||||
[B<-public-key-algorithms>]
|
||||
[B<-public-key-methods>]
|
||||
[B<-engines>]
|
||||
[B<-disabled>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
@@ -80,6 +81,10 @@ a block of multiple lines, all but the first are indented.
|
||||
Display a list of public key method OIDs: this also includes public key methods
|
||||
without an associated ASN.1 method, for example, KDF algorithms.
|
||||
|
||||
=item B<-engines>
|
||||
|
||||
Display a list of loaded engines.
|
||||
|
||||
=item B<-disabled>
|
||||
|
||||
Display a list of disabled features, those that were compiled out
|
||||
|
||||
@@ -0,0 +1,163 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-mac,
|
||||
mac - perform Message Authentication Code operations
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl mac>
|
||||
[B<-help>]
|
||||
[B<-macopt>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-binary>]
|
||||
B<mac_name>
|
||||
|
||||
B<openssl> I<mac> [B<...>] B<mac_name>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The message authentication code functions output the MAC of a supplied input
|
||||
file.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Print a usage message.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
Input filename to calculate a MAC for, or standard input by default.
|
||||
Standard input is used if the filename is '-'.
|
||||
Files are expected to be in binary format, standard input uses hexadecimal text
|
||||
format.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
Filename to output to, or standard output by default.
|
||||
|
||||
=item B<-binary>
|
||||
|
||||
Output the MAC in binary form. Uses hexadecimal text format if not specified.
|
||||
|
||||
=item B<-macopt nm:v>
|
||||
|
||||
Passes options to the MAC algorithm.
|
||||
A comprehensive list of controls can be found in the EVP_MAC implementation
|
||||
documentation.
|
||||
Common control strings used by EVP_MAC_ctrl_str() are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<key:string>
|
||||
|
||||
Specifies the MAC key as an alphanumeric string (use if the key contains
|
||||
printable characters only).
|
||||
The string length must conform to any restrictions of the MAC algorithm.
|
||||
A key must be specified for every MAC algorithm.
|
||||
|
||||
=item B<hexkey:string>
|
||||
|
||||
Specifies the MAC key in hexadecimal form (two hex digits per byte).
|
||||
The key length must conform to any restrictions of the MAC algorithm.
|
||||
A key must be specified for every MAC algorithm.
|
||||
|
||||
=item B<digest:string>
|
||||
|
||||
Used by HMAC as an alphanumeric string (use if the key contains printable
|
||||
characters only).
|
||||
The string length must conform to any restrictions of the MAC algorithm.
|
||||
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.
|
||||
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.
|
||||
|
||||
=item B<iv:string>
|
||||
|
||||
Used by GMAC to specify an IV as an alphanumeric string (use if the IV contains
|
||||
printable characters only).
|
||||
|
||||
=item B<hexiv:string>
|
||||
|
||||
Used by GMAC to specify an IV in hexadecimal form (two hex digits per byte).
|
||||
|
||||
=item B<outlen:int>
|
||||
|
||||
Used by KMAC128 or KMAC256 to specify an output length.
|
||||
The default sizes are 32 or 64 bytes respectively.
|
||||
|
||||
=item B<custom:string>
|
||||
|
||||
Used by KMAC128 or KMAC256 to specify a customization string.
|
||||
The default is the empty string "".
|
||||
|
||||
=back
|
||||
|
||||
=item B<mac_name>
|
||||
|
||||
Specifies the name of a supported MAC algorithm which will be used.
|
||||
To see the list of supported MAC's use the command I<list -mac-algorithms>.
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To create a hex-encoded HMAC-SHA1 MAC of a file and write to stdout: \
|
||||
openssl mac -macopt digest:SHA1 \
|
||||
-macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \
|
||||
-in msg.bin HMAC
|
||||
|
||||
To create a SipHash MAC from a file with a binary file output: \
|
||||
openssl mac -macopt hexkey:000102030405060708090A0B0C0D0E0F \
|
||||
-in msg.bin -out out.bin -binary SipHash
|
||||
|
||||
To create a hex-encoded CMAC-AES-128-CBC MAC from a file:\
|
||||
openssl mac -macopt cipher:AES-128-CBC \
|
||||
-macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B \
|
||||
-in msg.bin CMAC
|
||||
|
||||
To create a hex-encoded KMAC128 MAC from a file with a Customisation String
|
||||
'Tag' and output length of 16: \
|
||||
openssl mac -macopt custom:Tag -macopt hexkey:40414243444546 \
|
||||
-macopt outlen:16 -in msg.bin KMAC128
|
||||
|
||||
To create a hex-encoded GMAC-AES-128-GCM with a IV from a file: \
|
||||
openssl mac -macopt cipher:AES-128-GCM -macopt hexiv:E0E00F19FED7BA0136A797F3 \
|
||||
-macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B -in msg.bin GMAC
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The MAC mechanisms that are available will depend on the options
|
||||
used when building OpenSSL.
|
||||
The B<list -mac-algorithms> command can be used to list them.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_MAC(3)>,
|
||||
L<EVP_MAC_CMAC(7)>,
|
||||
L<EVP_MAC_GMAC(7)>,
|
||||
L<EVP_MAC_HMAC(7)>,
|
||||
L<EVP_MAC_KMAC(7)>,
|
||||
L<EVP_MAC_SIPHASH(7)>,
|
||||
L<EVP_MAC_POLY1305(7)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
+12
-6
@@ -11,7 +11,7 @@ I<command>
|
||||
[ I<command_opts> ]
|
||||
[ I<command_args> ]
|
||||
|
||||
B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<public-key-algorithms>]
|
||||
B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<mac-algorithms> | B<public-key-algorithms>]
|
||||
|
||||
B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
|
||||
|
||||
@@ -28,7 +28,7 @@ It can be used for
|
||||
o Creation and management of private keys, public keys and parameters
|
||||
o Public key cryptographic operations
|
||||
o Creation of X.509 certificates, CSRs and CRLs
|
||||
o Calculation of Message Digests
|
||||
o Calculation of Message Digests and Message Authentication Codes
|
||||
o Encryption and Decryption with Ciphers
|
||||
o SSL/TLS Client and Server Tests
|
||||
o Handling of S/MIME signed or encrypted mail
|
||||
@@ -57,8 +57,9 @@ and B<cipher-commands> output a list (one entry per line) of the names
|
||||
of all standard commands, message digest commands, or cipher commands,
|
||||
respectively, that are available in the present B<openssl> utility.
|
||||
|
||||
The list parameters B<cipher-algorithms> and
|
||||
B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
|
||||
The list parameters B<cipher-algorithms>, B<digest-algorithms>,
|
||||
and B<mac-algorithms> list all cipher, message digest, and message
|
||||
authentication code names, one entry per line. Aliases are listed as:
|
||||
|
||||
from => to
|
||||
|
||||
@@ -106,7 +107,8 @@ CRL to PKCS#7 Conversion.
|
||||
|
||||
=item B<dgst>
|
||||
|
||||
Message Digest Calculation.
|
||||
Message Digest calculation. MAC calculations are superseded by
|
||||
L<mac(1)>.
|
||||
|
||||
=item B<dh>
|
||||
|
||||
@@ -165,6 +167,10 @@ Generation of Private Key or Parameters.
|
||||
|
||||
Generation of RSA Private Key. Superseded by L<genpkey(1)>.
|
||||
|
||||
=item B<mac>
|
||||
|
||||
Message Authentication Code Calculation.
|
||||
|
||||
=item B<nseq>
|
||||
|
||||
Create or examine a Netscape certificate sequence.
|
||||
@@ -606,7 +612,7 @@ L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
|
||||
L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
|
||||
L<ec(1)>, L<ecparam(1)>,
|
||||
L<enc(1)>, L<engine(1)>, L<errstr(1)>, L<gendsa(1)>, L<genpkey(1)>,
|
||||
L<genrsa(1)>, L<nseq(1)>, L<ocsp(1)>,
|
||||
L<genrsa(1)>, L<mac(1)>, L<nseq(1)>, L<ocsp(1)>,
|
||||
L<passwd(1)>,
|
||||
L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,
|
||||
L<pkey(1)>, L<pkeyparam(1)>, L<pkeyutl(1)>, L<prime(1)>,
|
||||
|
||||
+21
-12
@@ -62,7 +62,7 @@ if this option is not specified.
|
||||
This indicates that the input data is raw data, which is not hashed by any
|
||||
message digest algorithm. The user can specify a digest algorithm by using
|
||||
the B<-digest> option. This option can only be used with B<-sign> and
|
||||
B<-verify>.
|
||||
B<-verify> and must be used with the Ed25519 and Ed448 algorithms.
|
||||
|
||||
=item B<-digest algorithm>
|
||||
|
||||
@@ -216,21 +216,18 @@ hash the input data. It is used (by some algorithms) for sanity-checking the
|
||||
lengths of data passed in to the B<pkeyutl> and for creating the structures that
|
||||
make up the signature (e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
|
||||
|
||||
This utility does not hash the input data but rather it will use the data
|
||||
directly as input to the signature algorithm. Depending on the key type,
|
||||
signature type, and mode of padding, the maximum acceptable lengths of input
|
||||
data differ. The signed data can't be longer than the key modulus with RSA. In
|
||||
case of ECDSA and DSA the data shouldn't be longer than the field
|
||||
size, otherwise it will be silently truncated to the field size. In any event
|
||||
the input size must not be larger than the largest supported digest size.
|
||||
This utility does not hash the input data (except where -rawin is used) but
|
||||
rather it will use the data directly as input to the signature algorithm.
|
||||
Depending on the key type, signature type, and mode of padding, the maximum
|
||||
acceptable lengths of input data differ. The signed data can't be longer than
|
||||
the key modulus with RSA. In case of ECDSA and DSA the data shouldn't be longer
|
||||
than the field size, otherwise it will be silently truncated to the field size.
|
||||
In any event the input size must not be larger than the largest supported digest
|
||||
size.
|
||||
|
||||
In other words, if the value of digest is B<sha1> the input should be the 20
|
||||
bytes long binary encoding of the SHA-1 hash function output.
|
||||
|
||||
The Ed25519 and Ed448 signature algorithms are not supported by this utility.
|
||||
They accept non-hashed input, but this utility can only be used to sign hashed
|
||||
input.
|
||||
|
||||
=head1 RSA ALGORITHM
|
||||
|
||||
The RSA algorithm generally supports the encrypt, decrypt, sign,
|
||||
@@ -319,6 +316,18 @@ this digest is assumed by default.
|
||||
The X25519 and X448 algorithms support key derivation only. Currently there are
|
||||
no additional options.
|
||||
|
||||
=head1 Ed25519 and Ed448 ALGORITHMS
|
||||
|
||||
These algorithms only support signing and verifying. OpenSSL only implements the
|
||||
"pure" variants of these algorithms so raw data can be passed directly to them
|
||||
without hashing them first. The option "-rawin" must be used with these
|
||||
algorithms with no "-digest" specified. Additionally OpenSSL only supports
|
||||
"oneshot" operation with these algorithms. This means that the entire file to
|
||||
be signed/verified must be read into memory before processing it. Signing or
|
||||
Verifying very large files should be avoided. Additionally the size of the file
|
||||
must be known for this to work. If the size of the file cannot be determined
|
||||
(for example if the input is stdin) then the sign or verify operation will fail.
|
||||
|
||||
=head1 SM2
|
||||
|
||||
The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For
|
||||
|
||||
@@ -218,7 +218,7 @@ Even though SNI should normally be a DNS name and not an IP address, if
|
||||
B<-servername> is provided then that name will be sent, regardless of whether
|
||||
it is a DNS name or not.
|
||||
|
||||
This option cannot be used in conjuction with B<-noservername>.
|
||||
This option cannot be used in conjunction with B<-noservername>.
|
||||
|
||||
=item B<-noservername>
|
||||
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_CRMF_MSG_get0_tmpl,
|
||||
OSSL_CRMF_CERTTEMPLATE_get0_serialNumber,
|
||||
OSSL_CRMF_CERTTEMPLATE_get0_issuer,
|
||||
OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert,
|
||||
OSSL_CRMF_MSG_get_certReqId
|
||||
- functions reading from CRMF CertReqMsg structures
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/crmf.h>
|
||||
|
||||
OSSL_CRMF_CERTTEMPLATE *OSSL_CRMF_MSG_get0_tmpl(const OSSL_CRMF_MSG *crm);
|
||||
ASN1_INTEGER
|
||||
*OSSL_CRMF_CERTTEMPLATE_get0_serialNumber(OSSL_CRMF_CERTTEMPLATE *tmpl);
|
||||
X509_NAME *OSSL_CRMF_CERTTEMPLATE_get0_issuer(OSSL_CRMF_CERTTEMPLATE *tmpl);
|
||||
|
||||
X509 *OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert(OSSL_CRMF_ENCRYPTEDVALUE *ecert,
|
||||
EVP_PKEY *pkey);
|
||||
|
||||
int OSSL_CRMF_MSG_get_certReqId(OSSL_CRMF_MSG *crm);
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
OSSL_CRMF_MSG_get0_tmpl() retrieves the certificate template of B<crm>.
|
||||
|
||||
OSSL_CRMF_CERTTEMPLATE_get0_serialNumber() retrieves the serialNumber of the
|
||||
given certificate template B<tmpl>.
|
||||
|
||||
OSSL_CRMF_CERTTEMPLATE_get0_issuer() retrieves the issuer name of the
|
||||
given certificate template B<tmpl>.
|
||||
|
||||
OSSL_CRMF_ENCRYPTEDVALUE_get1_encCert() decrypts the certificate in the given
|
||||
encryptedValue B<ecert>, using the private key B<pkey>.
|
||||
This is needed for the indirect PoP method as in RFC 4210 section 5.2.8.2.
|
||||
The function returns the decrypted certificate as a copy, leaving its ownership
|
||||
with the caller, who is responsible for freeing it.
|
||||
|
||||
OSSL_CRMF_MSG_get_certReqId() retrieves the certReqId of B<crm>.
|
||||
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OSSL_CRMF_MSG_get_certReqId() returns the certificate request ID as a
|
||||
non-negative integer or -1 on error.
|
||||
|
||||
All other functions return a pointer with the intended result or NULL on error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
B<RFC 4211>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,106 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_CRMF_MSG_set1_regCtrl_regToken,
|
||||
OSSL_CRMF_MSG_set1_regCtrl_authenticator,
|
||||
OSSL_CRMF_MSG_PKIPublicationInfo_push0_SinglePubInfo,
|
||||
OSSL_CRMF_MSG_set0_SinglePubInfo,
|
||||
OSSL_CRMF_MSG_set_PKIPublicationInfo_action,
|
||||
OSSL_CRMF_MSG_set1_regCtrl_pkiPublicationInfo,
|
||||
OSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey,
|
||||
OSSL_CRMF_MSG_set1_regCtrl_oldCertID,
|
||||
OSSL_CRMF_CERTID_gen
|
||||
- functions setting CRMF Registration Controls
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/crmf.h>
|
||||
|
||||
int OSSL_CRMF_MSG_set1_regCtrl_regToken(OSSL_CRMF_MSG *msg,
|
||||
const ASN1_UTF8STRING *tok);
|
||||
int OSSL_CRMF_MSG_set1_regCtrl_authenticator(OSSL_CRMF_MSG *msg,
|
||||
const ASN1_UTF8STRING *auth);
|
||||
int OSSL_CRMF_MSG_PKIPublicationInfo_push0_SinglePubInfo(
|
||||
OSSL_CRMF_PKIPUBLICATIONINFO *pi,
|
||||
OSSL_CRMF_SINGLEPUBINFO *spi);
|
||||
int OSSL_CRMF_MSG_set0_SinglePubInfo(OSSL_CRMF_SINGLEPUBINFO *spi,
|
||||
int method, GENERAL_NAME *nm);
|
||||
int OSSL_CRMF_MSG_set_PKIPublicationInfo_action(
|
||||
OSSL_CRMF_PKIPUBLICATIONINFO *pi, int action);
|
||||
int OSSL_CRMF_MSG_set1_regCtrl_pkiPublicationInfo(OSSL_CRMF_MSG *msg,
|
||||
const OSSL_CRMF_PKIPUBLICATIONINFO *pi);
|
||||
int OSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey(OSSL_CRMF_MSG *msg,
|
||||
const X509_PUBKEY *pubkey);
|
||||
int OSSL_CRMF_MSG_set1_regCtrl_oldCertID(OSSL_CRMF_MSG *msg,
|
||||
const OSSL_CRMF_CERTID *cid);
|
||||
OSSL_CRMF_CERTID *OSSL_CRMF_CERTID_gen(const X509_NAME *issuer,
|
||||
const ASN1_INTEGER *serial);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
OSSL_CRMF_MSG_set1_regCtrl_regToken() sets the regToken control in the given
|
||||
B<msg> copying the given B<tok> as value. See RFC 4211, section 6.1.
|
||||
|
||||
OSSL_CRMF_MSG_set1_regCtrl_authenticator() sets the authenticator control in
|
||||
the given B<msg> copying the given B<auth> as value. See RFC 4211, section 6.2.
|
||||
|
||||
OSSL_CRMF_MSG_PKIPublicationInfo_push0_SinglePubInfo() pushes the given B<spi>
|
||||
to B<si>. Consumes the B<spi> pointer.
|
||||
|
||||
OSSL_CRMF_MSG_set0_SinglePubInfo() sets in the given SinglePubInfo B<spi>
|
||||
the B<method> and publication location, in the form of a GeneralName, B<nm>.
|
||||
The publication location is optional, and therefore B<nm> may be NULL.
|
||||
The function consumes the B<nm> pointer if present.
|
||||
Available methods are:
|
||||
# define OSSL_CRMF_PUB_METHOD_DONTCARE 0
|
||||
# define OSSL_CRMF_PUB_METHOD_X500 1
|
||||
# define OSSL_CRMF_PUB_METHOD_WEB 2
|
||||
# define OSSL_CRMF_PUB_METHOD_LDAP 3
|
||||
|
||||
OSSL_CRMF_MSG_set_PKIPublicationInfo_action() sets the action in the given B<pi>
|
||||
using the given B<action> as value. See RFC 4211, section 6.3.
|
||||
Available actions are:
|
||||
# define OSSL_CRMF_PUB_ACTION_DONTPUBLISH 0
|
||||
# define OSSL_CRMF_PUB_ACTION_PLEASEPUBLISH 1
|
||||
|
||||
OSSL_CRMF_MSG_set1_regCtrl_pkiPublicationInfo() sets the pkiPublicationInfo
|
||||
control in the given B<msg> copying the given B<tok> as value. See RFC 4211,
|
||||
section 6.3.
|
||||
|
||||
OSSL_CRMF_MSG_set1_regCtrl_protocolEncrKey() sets the protocolEncrKey control in
|
||||
the given B<msg> copying the given B<pubkey> as value. See RFC 4211, section 6.6.
|
||||
|
||||
OSSL_CRMF_MSG_set1_regCtrl_oldCertID() sets the oldCertID control in the given
|
||||
B<msg> copying the given B<cid> as value. See RFC 4211, section 6.5.
|
||||
|
||||
OSSL_CRMF_CERTID_gen produces an OSSL_CRMF_CERTID_gen structure copying the
|
||||
given B<issuer> name and B<serial> number.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OSSL_CRMF_CERTID_gen returns a pointer to the resulting structure
|
||||
or NULL on error.
|
||||
|
||||
All other functions return 1 on success, 0 on error.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A function OSSL_CRMF_MSG_set1_regCtrl_pkiArchiveOptions() for setting an
|
||||
Archive Options Control is not yet implemented due to missing features to
|
||||
create the needed OSSL_CRMF_PKIARCHIVEOPTINS content.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
RFC 4211
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,49 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_CRMF_MSG_set1_regInfo_utf8Pairs,
|
||||
OSSL_CRMF_MSG_set1_regInfo_certReq
|
||||
- functions setting CRMF Registration Info
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/crmf.h>
|
||||
|
||||
int OSSL_CRMF_MSG_set1_regInfo_utf8Pairs(OSSL_CRMF_MSG *msg,
|
||||
const ASN1_UTF8STRING *utf8pairs);
|
||||
int OSSL_CRMF_MSG_set1_regInfo_certReq(OSSL_CRMF_MSG *msg,
|
||||
const OSSL_CRMF_CERTREQUEST *cr);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
OSSL_CRMF_MSG_set1_regInfo_utf8Pairs() adds a copy of the given B<utf8pairs>
|
||||
value as utf8Pairs regInfo to the given B<msg>. See RFC 4211 section 7.1.
|
||||
|
||||
OSSL_CRMF_MSG_set1_regInfo_certReq() adds a copy of the given B<cr> value
|
||||
as certReq regInfo to the given B<msg>. See RFC 4211 section 7.2.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
All functions return 1 on success, 0 on error.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Calling these functions multiple times adds multiple instances of the respective
|
||||
control to the regInfo structure of the given B<msg>. While RFC 4211 expects
|
||||
multiple utf8Pairs in one regInfo structure, it does not allow multiple certReq.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
RFC 4211
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,105 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_CRMF_MSG_set_validity,
|
||||
OSSL_CRMF_MSG_set_certReqId,
|
||||
OSSL_CRMF_CERTTEMPLATE_fill,
|
||||
OSSL_CRMF_MSG_set0_extensions,
|
||||
OSSL_CRMF_MSG_push0_extension,
|
||||
OSSL_CRMF_MSG_create_popo,
|
||||
OSSL_CRMF_MSGS_verify_popo
|
||||
- functions populating and verifying CRMF CertReqMsg structures
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/crmf.h>
|
||||
|
||||
int OSSL_CRMF_MSG_set_validity(OSSL_CRMF_MSG *crm, time_t from, time_t to);
|
||||
|
||||
int OSSL_CRMF_MSG_set_certReqId(OSSL_CRMF_MSG *crm, int rid);
|
||||
|
||||
int OSSL_CRMF_CERTTEMPLATE_fill(OSSL_CRMF_CERTTEMPLATE *tmpl,
|
||||
EVP_PKEY *pubkey,
|
||||
const X509_NAME *subject,
|
||||
const X509_NAME *issuer,
|
||||
const ASN1_INTEGER *serial);
|
||||
|
||||
int OSSL_CRMF_MSG_set0_extensions(OSSL_CRMF_MSG *crm,
|
||||
X509_EXTENSIONS *exts);
|
||||
|
||||
int OSSL_CRMF_MSG_push0_extension(OSSL_CRMF_MSG *crm,
|
||||
const X509_EXTENSION *ext);
|
||||
|
||||
int OSSL_CRMF_MSG_create_popo(OSSL_CRMF_MSG *crm, EVP_PKEY *pkey,
|
||||
int dgst, int ppmtd);
|
||||
|
||||
int OSSL_CRMF_MSGS_verify_popo(const OSSL_CRMF_MSGS *reqs,
|
||||
int rid, int acceptRAVerified);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
OSSL_CRMF_MSG_set_validity() sets B<from> as notBefore and B<to> as notAfter
|
||||
as the validity in the certTemplate of B<crm>.
|
||||
|
||||
OSSL_CRMF_MSG_set_certReqId() sets B<rid> as the certReqId of B<crm>.
|
||||
|
||||
OSSL_CRMF_CERTTEMPLATE_fill() sets those fields of the certTemplate B<tmpl>
|
||||
for which non-NULL values are provided: B<pubkey>, B<subject>, B<issuer>,
|
||||
and/or B<serial>.
|
||||
On success the reference counter of the B<pubkey> (if given) is incremented,
|
||||
while the B<subject>, B<issuer>, and B<serial> structures (if given) are copied.
|
||||
|
||||
OSSL_CRMF_MSG_set0_extensions() sets B<exts> as the extensions in the
|
||||
certTemplate of B<crm>. Frees any pre-existing ones and consumes B<exts>.
|
||||
|
||||
OSSL_CRMF_MSG_push0_extension() pushes the X509 extension B<ext> to the
|
||||
extensions in the certTemplate of B<crm>. Consumes B<ext>.
|
||||
|
||||
OSSL_CRMF_MSG_create_popo() creates and sets the Proof-of-Possession (POP)
|
||||
according to the method B<ppmtd> for B<pkey> to B<crm>. In case the method is
|
||||
OSSL_CRMF_POPO_SIGNATURE, POP is calculated using the B<dgst>.
|
||||
|
||||
B<ppmtd> can be one of the following:
|
||||
|
||||
=over 8
|
||||
|
||||
=item * OSSL_CRMF_POPO_NONE - RFC 4211, section 4, POP field omitted.
|
||||
CA/RA uses out-of-band method to verify POP. Note that servers may fail in this
|
||||
case, resulting for instance in HTTP error code 500 (Internal error).
|
||||
|
||||
=item * OSSL_CRMF_POPO_RAVERIFIED - RFC 4211, section 4, explicit indication
|
||||
that the RA has already verified the POP.
|
||||
|
||||
=item * OSSL_CRMF_POPO_SIGNATURE - RFC 4211, section 4.1, only case 3 supported
|
||||
so far.
|
||||
|
||||
=item * OSSL_CRMF_POPO_KEYENC - RFC 4211, section 4.2, only indirect method
|
||||
(subsequentMessage/enccert) supported,
|
||||
challenge-response exchange (challengeResp) not yet supported.
|
||||
|
||||
=item * OSSL_CRMF_POPO_KEYAGREE - RFC 4211, section 4.3, not yet supported.
|
||||
|
||||
=back
|
||||
|
||||
OSSL_CRMF_MSGS_verify_popo verifies the Proof-of-Possession of the request with
|
||||
the given B<rid> in the list of B<reqs>. Optionally accepts RAVerified.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
All functions return 1 on success, 0 on error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
RFC 4211
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
@@ -0,0 +1,78 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_CRMF_pbm_new,
|
||||
OSSL_CRMF_pbmp_new
|
||||
- functions for producing Password-Based MAC (PBM)
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/crmf.h>
|
||||
|
||||
int OSSL_CRMF_pbm_new(const OSSL_CRMF_PBMPARAMETER *pbmp,
|
||||
const unsigned char *msg, size_t msglen,
|
||||
const unsigned char *sec, size_t seclen,
|
||||
unsigned char **mac, size_t *maclen);
|
||||
|
||||
OSSL_CRMF_PBMPARAMETER *OSSL_CRMF_pbmp_new(size_t saltlen, int owfnid,
|
||||
int itercnt, int macnid);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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
|
||||
allocated MAC via the B<mac> reference parameter and writes the length via the
|
||||
B<maclen> reference parameter unless it its NULL.
|
||||
|
||||
The iteration count must be at least 100, as stipulated by RFC 4211, and is
|
||||
limited to at most 100000 to avoid DoS through manipulated or otherwise
|
||||
malformed input.
|
||||
|
||||
OSSL_CRMF_pbmp_new() initializes and returns a new PBMParameter
|
||||
structure with a new random salt of given length B<saltlen>, OWF (one-way
|
||||
function) NID B<owfnid>, iteration count B<itercnt>, and MAC NID B<macnid>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The algorithms for the OWF (one-way function) and for the MAC (message
|
||||
authentication code) may be any with a NID defined in B<openssl/objects.h>.
|
||||
As specified by RFC 4210, these should include NID_hmac_sha1.
|
||||
|
||||
RFC 4210 recommends that the salt SHOULD be at least 8 bytes (64 bits) long.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OSSL_CRMF_pbm_new() returns 1 on success, 0 on error.
|
||||
|
||||
OSSL_CRMF_pbmp_new() returns a new and initialized OSSL_CRMF_PBMPARAMETER
|
||||
structure, or NULL on error.
|
||||
|
||||
=head1 EXAMPLE
|
||||
|
||||
OSSL_CRMF_PBMPARAMETER *pbm = NULL;
|
||||
unsigned char *msg = "Hello";
|
||||
unsigned char *sec = "SeCrEt";
|
||||
unsigned char *mac = NULL;
|
||||
size_t maclen;
|
||||
|
||||
if ((pbm = OSSL_CRMF_pbmp_new(16, NID_sha256, 500, NID_hmac_sha1) == NULL))
|
||||
goto err;
|
||||
if (!OSSL_CRMF_pbm_new(pbm, msg, 5, sec, 6, &mac, &maclen))
|
||||
goto err;
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
RFC 4211 section 4.4
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Licensed under the OpenSSL license (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
|
||||
+44
-44
@@ -11,9 +11,9 @@ OSSL_PARAM - a structure to pass or request object parameters
|
||||
typedef struct ossl_param_st OSSL_PARAM;
|
||||
struct ossl_param_st {
|
||||
const char *key; /* the name of the parameter */
|
||||
unsigned char data_type; /* declare what kind of content is in buffer */
|
||||
void *buffer; /* value being passed in or out */
|
||||
size_t buffer_size; /* buffer size */
|
||||
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 */
|
||||
};
|
||||
|
||||
@@ -45,8 +45,8 @@ Request parameters of some object.
|
||||
The caller (the I<requestor>) sets up the C<OSSL_PARAM> array and
|
||||
calls some function (the I<responder>) that has intimate knowledge
|
||||
about the object, which can take the internal data of the object and
|
||||
copy (possibly convert) that to the buffers prepared by the
|
||||
I<requestor>.
|
||||
copy (possibly convert) that to the memory prepared by the
|
||||
I<requestor> and pointed at with the C<OSSL_PARAM> C<data>.
|
||||
|
||||
=back
|
||||
|
||||
@@ -69,13 +69,13 @@ The C<data_type> is a value that describes the type and organization of
|
||||
the data.
|
||||
See L</Supported types> below for a description of the types.
|
||||
|
||||
=item C<buffer>
|
||||
=item C<data>
|
||||
|
||||
=item C<buffer_size>
|
||||
=item C<data_size>
|
||||
|
||||
C<buffer> is a pointer to the memory where the parameter data is (when
|
||||
C<data> is a pointer to the memory where the parameter data is (when
|
||||
setting parameters) or shall (when requesting parameters) be stored,
|
||||
and C<buffer_size> is its size in bytes.
|
||||
and C<data_size> is its size in bytes.
|
||||
The organization of the data depends on the parameter type and flag.
|
||||
|
||||
=item C<return_size>
|
||||
@@ -83,9 +83,8 @@ The organization of the data depends on the parameter type and flag.
|
||||
When an array of C<OSSL_PARAM> is used to request data, the
|
||||
I<responder> must set this field to indicate the actual size of the
|
||||
parameter data.
|
||||
In case the C<buffer_size> is too small for the data, the I<responder>
|
||||
must still set this field to indicate the minimum buffer size
|
||||
required.
|
||||
In case the C<data_size> is too small for the data, the I<responder>
|
||||
must still set this field to indicate the minimum data size required.
|
||||
|
||||
=back
|
||||
|
||||
@@ -119,8 +118,6 @@ systems.
|
||||
|
||||
=item C<OSSL_PARAM_REAL>
|
||||
|
||||
=for comment It's still debated if we need this or not.
|
||||
|
||||
The parameter data is a floating point value in native form.
|
||||
|
||||
=item C<OSSL_PARAM_UTF8_STRING>
|
||||
@@ -131,47 +128,50 @@ The parameter data is a printable string.
|
||||
|
||||
The parameter data is an arbitrary string of bytes.
|
||||
|
||||
=back
|
||||
=item C<OSSL_PARAM_UTF8_PTR>
|
||||
|
||||
Additionally, this flag can be added to any type:
|
||||
The parameter data is a pointer to a printable string.
|
||||
|
||||
=over 4
|
||||
The difference between this and C<OSSL_PARAM_UTF8_STRING> is that C<data>
|
||||
doesn't point directly at the data, but to a pointer that points to the data.
|
||||
|
||||
=item C<OSSL_PARAM_POINTER_FLAG>
|
||||
|
||||
With this flag, C<buffer> doesn't point directly at the data, but at a
|
||||
pointer that points at the data.
|
||||
|
||||
This can be used to indicate that constant data is or will be passed,
|
||||
This is used to indicate that constant data is or will be passed,
|
||||
and there is therefore no need to copy the data that is passed, just
|
||||
the pointer to it.
|
||||
|
||||
If an C<OSSL_PARAM> with this flag set is used to set a parameter,
|
||||
C<buffer_size> must be set to the size of the data, not the size of
|
||||
the pointer to the data.
|
||||
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.
|
||||
|
||||
If this C<OSSL_PARAM> is used in a parameter request, C<buffer_size>
|
||||
is not relevant.
|
||||
However, the I<responder> will set C<*return_size> to the size of the
|
||||
data (again, not the size of the pointer to the data).
|
||||
|
||||
Note that the use of this flag is B<fragile> and can only be safely
|
||||
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
|
||||
long enough duration (such as the life-time of the entity that
|
||||
offers these parameters).
|
||||
|
||||
=back
|
||||
=item C<OSSL_PARAM_OCTET_PTR>
|
||||
|
||||
For convenience, these types are provided:
|
||||
The parameter data is a pointer to an arbitrary string of bytes.
|
||||
|
||||
=over 4
|
||||
The difference between this and C<OSSL_PARAM_OCTET_STRING> is that
|
||||
C<data> doesn't point directly at the data, but to a pointer that
|
||||
points to the data.
|
||||
|
||||
=item C<OSSL_PARAM_UTF8_STRING_PTR>
|
||||
This is used to indicate that constant data is or will be passed, and
|
||||
there is therefore no need to copy the data that is passed, just the
|
||||
pointer to it.
|
||||
|
||||
=item C<OSSL_PARAM_OCTET_STRING_PTR>
|
||||
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.
|
||||
|
||||
These are combinations of C<OSSL_PARAM_UTF8_STRING> as well as
|
||||
C<OSSL_PARAM_OCTET_STRING> with C<OSSL_PARAM_POINTER_FLAG>.
|
||||
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
|
||||
long enough duration (such as the life-time of the entity that
|
||||
offers these parameters).
|
||||
|
||||
=back
|
||||
|
||||
@@ -197,7 +197,7 @@ 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 buffers that C<buffer> and
|
||||
may only change the contents of the memory that C<data> and
|
||||
C<return_size> point at.
|
||||
|
||||
=item *
|
||||
@@ -213,7 +213,7 @@ C<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory.
|
||||
|
||||
=item *
|
||||
|
||||
If a I<responder> finds that some buffers are too small for the
|
||||
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
|
||||
C<OSSL_PARAM> item to the required size, and eventually return an
|
||||
error.
|
||||
@@ -273,10 +273,10 @@ could fill in the parameters like this:
|
||||
|
||||
for (i = 0; params[i].key != NULL; i++) {
|
||||
if (strcmp(params[i].key, "foo") == 0) {
|
||||
*(char **)params[i].buffer = "foo value";
|
||||
*(char **)params[i].data = "foo value";
|
||||
*params[i].return_size = 10; /* size of "foo value" */
|
||||
} else if (strcmp(params[i].key, "bar") == 0) {
|
||||
memcpy(params[1].buffer, "bar value", 10);
|
||||
memcpy(params[1].data, "bar value", 10);
|
||||
*params[1].return_size = 10; /* size of "bar value" */
|
||||
}
|
||||
/* Ignore stuff we don't know */
|
||||
@@ -284,7 +284,7 @@ could fill in the parameters like this:
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl-core.h(7)>
|
||||
L<openssl-core.h(7)>, L<OSSL_PARAM_get_int32_t(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
||||
@@ -0,0 +1,312 @@
|
||||
=pod
|
||||
|
||||
=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_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_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
|
||||
- OSSL_PARAM helpers
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/params.h>
|
||||
|
||||
#define OSSL_PARAM_TYPE(key, address)
|
||||
#define OSSL_PARAM_utf8_string(key, address, size)
|
||||
#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_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);
|
||||
OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
|
||||
size_t bsize, size_t *rsize);
|
||||
OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
|
||||
size_t bsize, size_t *rsize);
|
||||
OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
|
||||
size_t *rsize);
|
||||
OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
|
||||
size_t *rsize);
|
||||
|
||||
OSSL_PARAM *OSSL_PARAM_locate(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_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_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_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_get_utf8_ptr(const OSSL_PARAM *p, char **val);
|
||||
int OSSL_PARAM_set_utf8_ptr(const 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);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
A collection of utility functions that simplify and add type safety to the
|
||||
OSSL_PARAM arrays. The following B<TYPE> names are supported:
|
||||
|
||||
=over 1
|
||||
|
||||
=item *
|
||||
|
||||
double
|
||||
|
||||
=item *
|
||||
|
||||
int
|
||||
|
||||
=item *
|
||||
|
||||
int32 (int32_t)
|
||||
|
||||
=item *
|
||||
|
||||
int64 (int64_t)
|
||||
|
||||
=item *
|
||||
|
||||
long int (long)
|
||||
|
||||
=item *
|
||||
|
||||
size_t
|
||||
|
||||
=item *
|
||||
|
||||
uint32 (uint32_t)
|
||||
|
||||
=item *
|
||||
|
||||
uint64 (uint64_t)
|
||||
|
||||
=item *
|
||||
|
||||
unsigned int (uint)
|
||||
|
||||
=item *
|
||||
|
||||
unsigned long int (ulong)
|
||||
|
||||
=back
|
||||
|
||||
OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an
|
||||
array of OSSL_PARAM structures.
|
||||
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.
|
||||
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.
|
||||
|
||||
OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM
|
||||
records dynamically.
|
||||
A parameter with name B<key> is created.
|
||||
The parameter will use storage pointed to by B<buf> and return size of B<ret>.
|
||||
|
||||
OSSL_PARAM_construct_BN() is a function that constructs a large integer
|
||||
OSSL_PARAM structure.
|
||||
A parameter with name B<key>, storage B<buf>, size B<bsize> and return
|
||||
size B<rsize> is created.
|
||||
|
||||
OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
|
||||
string OSSL_PARAM structure.
|
||||
A parameter with name B<key>, storage B<buf>, size B<bsize> and return
|
||||
size B<rsize> is created.
|
||||
|
||||
OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET
|
||||
string OSSL_PARAM structure.
|
||||
A parameter with name B<key>, storage B<buf>, size B<bsize> and return
|
||||
size B<rsize> is created.
|
||||
|
||||
OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string
|
||||
pointer OSSL_PARAM structure.
|
||||
A parameter with name B<key>, storage pointer B<*buf> and return size B<rsize>
|
||||
is created.
|
||||
|
||||
OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string
|
||||
pointer OSSL_PARAM structure.
|
||||
A parameter with name B<key>, storage pointer B<*buf> and return size B<rsize>
|
||||
is created.
|
||||
|
||||
OSSL_PARAM_locate() is a function that searches an B<array> of parameters for
|
||||
the one matching the B<key> name.
|
||||
|
||||
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
|
||||
B<p>.
|
||||
Type coercion takes place as discussed in the NOTES section.
|
||||
|
||||
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_get_utf8_string() retrieves a UTF8 string from the parameter
|
||||
pointed to by B<p>.
|
||||
The string is either stored into B<*val> with a length limit of B<max_len> or,
|
||||
in the case when B<*val> is B<NULL>, memory is allocated for the string and
|
||||
B<max_len> is ignored.
|
||||
If memory is allocated by this function, it must be freed by the caller.
|
||||
|
||||
OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to
|
||||
by B<p> to the value referenced by B<val>.
|
||||
|
||||
OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter
|
||||
pointed to by B<p>.
|
||||
The OCTETs are either stored into B<*val> with a length limit of B<max_len> or,
|
||||
in the case when B<*val> is B<NULL>, memory is allocated and
|
||||
B<max_len> is ignored.
|
||||
If memory is allocated by this function, it must be freed by the caller.
|
||||
|
||||
OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter
|
||||
pointed to by B<p> to the value referenced by B<val>.
|
||||
|
||||
OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter
|
||||
referenced by B<p> and stores it in B<*val>.
|
||||
|
||||
OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter
|
||||
referenced by B<p> to the values B<val>.
|
||||
|
||||
OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter
|
||||
referenced by B<p> and stores it in B<*val>.
|
||||
The length of the OCTET string is stored in B<*used_len>.
|
||||
|
||||
OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter
|
||||
referenced by B<p> to the values B<val>.
|
||||
The length of the OCTET string is provided by B<used_len>.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(),
|
||||
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>.
|
||||
|
||||
All other functions return B<1> on success and B<0> on failure.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Integral types will be widened and sign extended as required.
|
||||
Apart from that, the functions must be used appropriately for the
|
||||
expected type of the parameter.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Reusing the examples from L<OSSL_PARAM(3)> to just show how
|
||||
C<OSSL_PARAM> arrays can be handled using the macros and functions
|
||||
defined herein.
|
||||
|
||||
=head2 Example 1
|
||||
|
||||
This example is for setting parameters on some object:
|
||||
|
||||
#include <openssl/core.h>
|
||||
|
||||
const char *foo = "some string";
|
||||
size_t foo_l = strlen(foo) + 1;
|
||||
const char bar[] = "some other string";
|
||||
const OSSL_PARAM set[] = {
|
||||
OSSL_PARAM_utf8_ptr("foo", foo, foo_l),
|
||||
OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)),
|
||||
OSSL_PARAM_END
|
||||
};
|
||||
|
||||
=head2 Example 2
|
||||
|
||||
This example is for requesting parameters on some object:
|
||||
|
||||
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_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_set_utf8_ptr(OSSL_PARAM_locate(params, "foo"), "foo value");
|
||||
OSSL_PARAM_set_utf8_string(OSSL_PARAM_locate(params, "bar"), "bar value");
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl-core.h(7)>, L<OSSL_PARAM(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
These APIs were introduced in 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
|
||||
@@ -0,0 +1,112 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_unload,
|
||||
OSSL_PROVIDER_get_param_types, OSSL_PROVIDER_get_params,
|
||||
OSSL_PROVIDER_add_builtin - provider routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/provider.h>
|
||||
|
||||
typedef struct ossl_provider_st OSSL_PROVIDER;
|
||||
|
||||
OSSL_PROVIDER *OSSL_PROVIDER_load(OPENSSL_CTX *, const char *name);
|
||||
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_add_builtin(OPENSSL_CTX *, const char *name,
|
||||
ossl_provider_init_fn *init_fn);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
B<OSSL_PROVIDER> is a type that holds internal information about
|
||||
implementation providers (see L<provider(7)> for information on what a
|
||||
provider is).
|
||||
A provider can be built in to the application or the OpenSSL
|
||||
libraries, or can be a loadable module.
|
||||
The functions described here handle both forms.
|
||||
|
||||
=head2 Functions
|
||||
|
||||
OSSL_PROVIDER_add_builtin() is used to add a built in provider to
|
||||
B<OSSL_PROVIDER> store in the given library context, by associating a
|
||||
provider name with a provider initialization function.
|
||||
This name can then be used with OSSL_PROVIDER_load().
|
||||
|
||||
OSSL_PROVIDER_load() loads and initializes a provider.
|
||||
This may simply initialize a provider that was previously added with
|
||||
OSSL_PROVIDER_add_builtin() and run its given initialization function,
|
||||
or load a provider module with the given name and run its provider
|
||||
entry point, C<OSSL_provider_init>.
|
||||
|
||||
OSSL_PROVIDER_unload() unloads the given provider.
|
||||
For a provider added with OSSL_PROVIDER_add_builtin(), this simply
|
||||
runs its teardown function.
|
||||
|
||||
OSSL_PROVIDER_get_param_types() is used to get a provider parameter
|
||||
descriptor set as an B<OSSL_ITEM> array.
|
||||
Each element is a tuple of an B<OSSL_PARAM> parameter type and a name
|
||||
in form of a C string.
|
||||
See L<openssl-core.h(7)> for more information on B<OSSL_ITEM> and
|
||||
parameter types.
|
||||
|
||||
OSSL_PROVIDER_get_params() is used to get provider parameter values.
|
||||
The caller must prepare the B<OSSL_PARAM> array before calling this
|
||||
function, and the variables acting as buffers for this parameter array
|
||||
should be filled with data when it returns successfully.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OSSL_PROVIDER_add() returns 1 on success, or 0 on error.
|
||||
|
||||
OSSL_PROVIDER_load() returns a pointer to a provider object on
|
||||
success, or B<NULL> on error.
|
||||
|
||||
OSSL_PROVIDER_unload() returns 1 on success, or 0 on error.
|
||||
|
||||
OSSL_PROVIDER_get_param_types() returns a pointer to a constant array
|
||||
of B<OSSL_ITEM>, or NULL if none is provided.
|
||||
|
||||
OSSL_PROVIDER_get_params() returns 1 on success, or 0 on error.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
This demonstrates how to load the provider module "foo" and ask for
|
||||
its build number.
|
||||
|
||||
OSSL_PROVIDER *prov = NULL;
|
||||
const char *build = NULL;
|
||||
size_t built_l = 0;
|
||||
const OSSL_PARAM request[] = {
|
||||
{ "build", OSSL_PARAM_UTF8_STRING_PTR, &build, 0, &build_l },
|
||||
{ NULL, 0, NULL, 0, NULL }
|
||||
};
|
||||
|
||||
if ((prov = OSSL_PROVIDER_load(NULL, "foo")) != NULL
|
||||
&& OSSL_PROVIDER_get_params(prov, request))
|
||||
printf("Provider 'foo' build %s\n", build);
|
||||
else
|
||||
ERR_print_errors_fp(stderr);
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl-core.h(7)>, L<provider(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The type and functions described here 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
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
|
||||
OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
|
||||
OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9
|
||||
- OpenSSL Tracing API
|
||||
|
||||
=head1 SYNOPSIS
|
||||
@@ -14,13 +15,25 @@ OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
|
||||
BIO *OSSL_trace_begin(int category);
|
||||
void OSSL_trace_end(int category, BIO *channel);
|
||||
|
||||
/* trace group macros */
|
||||
OSSL_TRACE_BEGIN(category) {
|
||||
...
|
||||
} OSSL_TRACE_END(category);
|
||||
|
||||
/* one-shot trace macros */
|
||||
OSSL_TRACE1(category, format, arg1)
|
||||
OSSL_TRACE2(category, format, arg1, arg2)
|
||||
...
|
||||
OSSL_TRACE9(category, format, arg1, ..., arg9)
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The functions described here are mainly interesting for those who provide
|
||||
OpenSSL functionality, either in OpenSSL itself or in engine modules
|
||||
or similar.
|
||||
|
||||
If operational (see L</NOTES> below), these functions are used to
|
||||
If tracing is enabled (see L</NOTES> below), these functions are used to
|
||||
generate free text tracing output.
|
||||
|
||||
The tracing output is divided into types which are enabled
|
||||
@@ -30,6 +43,30 @@ L<OSSL_trace_set_callback(3)/Trace types>.
|
||||
The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
|
||||
with the functions described here.
|
||||
|
||||
Tracing for a specific category is enabled if a so called
|
||||
I<trace channel> is attached to it. A trace channel is simply a
|
||||
BIO object to which the application can write its trace output.
|
||||
|
||||
The application has two different ways of registering a trace channel,
|
||||
either by directly providing a BIO object using OSSL_trace_set_channel(),
|
||||
or by providing a callback routine using OSSL_trace_set_callback().
|
||||
The latter is wrapped internally by a dedicated BIO object, so for the
|
||||
tracing code both channel types are effectively indistinguishable.
|
||||
We call them a I<simple trace channel> and a I<callback trace channel>,
|
||||
respectively.
|
||||
|
||||
To produce trace output, it is necessary to obtain a pointer to the
|
||||
trace channel (i.e., the BIO object) using OSSL_trace_begin(), write
|
||||
to it using arbitrary BIO output routines, and finally releases the
|
||||
channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
|
||||
calls surrounding the trace output create a group, which acts as a
|
||||
critical section (guarded by a mutex) to ensure that the trace output
|
||||
of different threads does not get mixed up.
|
||||
|
||||
The tracing code normally does not call OSSL_trace_{begin,end}() directly,
|
||||
but rather uses a set of convenience macros, see the L</Macros> section below.
|
||||
|
||||
|
||||
=head2 Functions
|
||||
|
||||
OSSL_trace_enabled() can be used to check if tracing for the given
|
||||
@@ -46,7 +83,7 @@ is I<mandatory>.
|
||||
The result of trying to produce tracing output outside of such
|
||||
sections is undefined.
|
||||
|
||||
=head2 Convenience Macros
|
||||
=head2 Macros
|
||||
|
||||
There are a number of convenience macros defined, to make tracing
|
||||
easy and consistent.
|
||||
@@ -60,7 +97,7 @@ the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
|
||||
|
||||
} OSSL_TRACE_END(TLS);
|
||||
|
||||
This will normally expands to:
|
||||
This will normally expand to:
|
||||
|
||||
do {
|
||||
BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
|
||||
@@ -98,6 +135,16 @@ This will normally expand to:
|
||||
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
|
||||
} while (0);
|
||||
|
||||
|
||||
C<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> are one-shot macros which essentially wrap
|
||||
a single BIO_printf() into a tracing group.
|
||||
|
||||
The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to:
|
||||
|
||||
OSSL_TRACE_BEGIN(category) {
|
||||
BIO_printf(trc_out, format, arg1, ..., argN)
|
||||
} OSSL_TRACE_END(category)
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
It is advisable to always check that a trace type is enabled with
|
||||
@@ -110,10 +157,11 @@ OSSL_trace_enabled() before generating any output, for example:
|
||||
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
|
||||
}
|
||||
|
||||
=head2 Tracing disabled
|
||||
=head2 Configure Tracing
|
||||
|
||||
The OpenSSL library may be built with tracing disabled, which makes
|
||||
everything documented here inoperational.
|
||||
By default, the OpenSSL library is built with tracing disabled. To
|
||||
use the tracing functionality documented here, it is therefore
|
||||
necessary to configure and build OpenSSL with the 'enable-trace' option.
|
||||
|
||||
When the library is built with tracing disabled:
|
||||
|
||||
@@ -132,7 +180,7 @@ nothing.
|
||||
=item *
|
||||
|
||||
the convenience macros are defined to produce dead code.
|
||||
For example, take this example from L</Convenience Macros> above:
|
||||
For example, take this example from L</Macros> section above:
|
||||
|
||||
OSSL_TRACE_BEGIN(TLS) {
|
||||
|
||||
|
||||
@@ -25,14 +25,21 @@ This output comes in form of free text for humans to read.
|
||||
|
||||
The trace output is divided into categories which can be
|
||||
enabled individually.
|
||||
They are enabled by giving them a channel in form of a BIO, or a
|
||||
tracer callback, which is responsible for performing the actual
|
||||
output.
|
||||
Every category can be enabled individually by attaching a so called
|
||||
I<trace channel> to it, which in the simplest case is just a BIO object
|
||||
to which the application can write the tracing output for this category.
|
||||
Alternatively, the application can provide a tracer callback in order to
|
||||
get more finegrained trace information. This callback will be wrapped
|
||||
internally by a dedicated BIO object.
|
||||
|
||||
For the tracing code, both trace channel types are indistinguishable.
|
||||
These are called a I<simple trace channel> and a I<callback trace channel>,
|
||||
respectively.
|
||||
|
||||
=head2 Functions
|
||||
|
||||
OSSL_trace_set_channel() is used to enable the given trace C<category>
|
||||
by giving it the B<BIO> C<bio>.
|
||||
by attaching the B<BIO> C<bio> object as (simple) trace channel.
|
||||
|
||||
OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
|
||||
an extra line for each channel, to be output before and after group of
|
||||
@@ -46,7 +53,8 @@ OSSL_trace_set_callback() instead.
|
||||
OSSL_trace_set_callback() is used to enable the given trace
|
||||
C<category> by giving it the tracer callback C<cb> with the associated
|
||||
data C<data>, which will simply be passed through to C<cb> whenever
|
||||
it's called.
|
||||
it's called. The callback function is internally wrapped by a
|
||||
dedicated BIO object, the so called I<callback trace channel>.
|
||||
This should be used when it's desirable to do form the trace output to
|
||||
something suitable for application needs where a prefix and suffix
|
||||
line aren't enough.
|
||||
@@ -78,9 +86,13 @@ callback the possibility to output a dynamic starting line, or set a
|
||||
prefix that should be output at the beginning of each line, or
|
||||
something other.
|
||||
|
||||
=item C<OSSL_TRACE_CTRL_DURING>
|
||||
=item C<OSSL_TRACE_CTRL_WRITE>
|
||||
|
||||
The callback is called from any regular BIO output routine.
|
||||
This callback is called whenever data is written to the BIO by some
|
||||
regular BIO output routine.
|
||||
An arbitrary number of C<OSSL_TRACE_CTRL_WRITE> callbacks can occur
|
||||
inside a group marked by a pair of C<OSSL_TRACE_CTRL_BEGIN> and
|
||||
C<OSSL_TRACE_CTRL_END> calls, but never outside such a group.
|
||||
|
||||
=item C<OSSL_TRACE_CTRL_END>
|
||||
|
||||
@@ -177,8 +189,8 @@ success, or 0 on failure.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
In all examples below, we assume that the trace producing code is
|
||||
this:
|
||||
In all examples below, the trace producing code is assumed to be
|
||||
the following:
|
||||
|
||||
int foo = 42;
|
||||
const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7,
|
||||
@@ -261,10 +273,11 @@ The output is almost the same as for the simple example above.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
=head2 Tracing disabled
|
||||
=head2 Configure Tracing
|
||||
|
||||
The OpenSSL library may be built with tracing disabled, which makes
|
||||
everything documented here inoperational.
|
||||
By default, the OpenSSL library is built with tracing disabled. To
|
||||
use the tracing functionality documented here, it is therefore
|
||||
necessary to configure and build OpenSSL with the 'enable-trace' option.
|
||||
|
||||
When the library is built with tracing disabled, the macro
|
||||
C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1,
|
||||
RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2,
|
||||
RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP,
|
||||
RSA_padding_add_PKCS1_OAEP_mgf1, RSA_padding_check_PKCS1_OAEP_mgf1,
|
||||
RSA_padding_add_SSLv23, RSA_padding_check_SSLv23,
|
||||
RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
|
||||
padding
|
||||
@@ -14,35 +15,46 @@ padding
|
||||
#include <openssl/rsa.h>
|
||||
|
||||
int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl);
|
||||
const unsigned char *f, int fl);
|
||||
|
||||
int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl, int rsa_len);
|
||||
const unsigned char *f, int fl, int rsa_len);
|
||||
|
||||
int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl);
|
||||
const unsigned char *f, int fl);
|
||||
|
||||
int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl, int rsa_len);
|
||||
const unsigned char *f, int fl, int rsa_len);
|
||||
|
||||
int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl, unsigned char *p, int pl);
|
||||
const unsigned char *f, int fl,
|
||||
const unsigned char *p, int pl);
|
||||
|
||||
int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl, int rsa_len,
|
||||
unsigned char *p, int pl);
|
||||
const unsigned char *f, int fl, int rsa_len,
|
||||
const unsigned char *p, int pl);
|
||||
|
||||
int RSA_padding_add_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
|
||||
const unsigned char *f, int fl,
|
||||
const unsigned char *p, int pl,
|
||||
const EVP_MD *md, const EVP_MD *mgf1md);
|
||||
|
||||
int RSA_padding_check_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
|
||||
const unsigned char *f, int fl, int rsa_len,
|
||||
const unsigned char *p, int pl,
|
||||
const EVP_MD *md, const EVP_MD *mgf1md);
|
||||
|
||||
int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl);
|
||||
const unsigned char *f, int fl);
|
||||
|
||||
int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl, int rsa_len);
|
||||
const unsigned char *f, int fl, int rsa_len);
|
||||
|
||||
int RSA_padding_add_none(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl);
|
||||
const unsigned char *f, int fl);
|
||||
|
||||
int RSA_padding_check_none(unsigned char *to, int tlen,
|
||||
unsigned char *f, int fl, int rsa_len);
|
||||
const unsigned char *f, int fl, int rsa_len);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
@@ -98,6 +110,10 @@ at B<to>.
|
||||
For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
|
||||
of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
|
||||
|
||||
For RSA_padding_xxx_OAEP_mgf1(), B<md> points to the md hash,
|
||||
if B<md> is B<NULL> that means md=sha1, and B<mgf1md> points to
|
||||
the mgf1 hash, if B<mgf1md> is B<NULL> that means mgf1md=md.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
|
||||
@@ -107,15 +123,21 @@ L<ERR_get_error(3)>.
|
||||
|
||||
=head1 WARNING
|
||||
|
||||
The RSA_padding_check_PKCS1_type_2() padding check leaks timing
|
||||
The result of RSA_padding_check_PKCS1_type_2() is a very sensitive
|
||||
information which can potentially be used to mount a Bleichenbacher
|
||||
padding oracle attack. This is an inherent weakness in the PKCS #1
|
||||
v1.5 padding design. Prefer PKCS1_OAEP padding. Otherwise it can
|
||||
be recommended to pass zero-padded B<f>, so that B<fl> equals to
|
||||
B<rsa_len>, and if fixed by protocol, B<tlen> being set to the
|
||||
expected length. In such case leakage would be minimal, it would
|
||||
take attacker's ability to observe memory access pattern with byte
|
||||
granilarity as it occurs, post-factum timing analysis won't do.
|
||||
v1.5 padding design. Prefer PKCS1_OAEP padding. If that is not
|
||||
possible, the result of RSA_padding_check_PKCS1_type_2() should be
|
||||
checked in constant time if it matches the expected length of the
|
||||
plaintext and additionally some application specific consistency
|
||||
checks on the plaintext need to be performed in constant time.
|
||||
If the plaintext is rejected it must be kept secret which of the
|
||||
checks caused the application to reject the message.
|
||||
Do not remove the zero-padding from the decrypted raw RSA data
|
||||
which was computed by RSA_private_decrypt() with B<RSA_NO_PADDING>,
|
||||
as this would create a small timing side channel which could be
|
||||
used to mount a Bleichenbacher attack against any padding mode
|
||||
including PKCS1_OAEP.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
@@ -125,7 +147,7 @@ L<RSA_sign(3)>, L<RSA_verify(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2016 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
|
||||
|
||||
@@ -8,10 +8,10 @@ RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
|
||||
|
||||
#include <openssl/rsa.h>
|
||||
|
||||
int RSA_public_encrypt(int flen, unsigned char *from,
|
||||
int RSA_public_encrypt(int flen, const unsigned char *from,
|
||||
unsigned char *to, RSA *rsa, int padding);
|
||||
|
||||
int RSA_private_decrypt(int flen, unsigned char *from,
|
||||
int RSA_private_decrypt(int flen, const unsigned char *from,
|
||||
unsigned char *to, RSA *rsa, int padding);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
@@ -27,6 +27,8 @@ B<padding> denotes one of the following modes:
|
||||
=item RSA_PKCS1_PADDING
|
||||
|
||||
PKCS #1 v1.5 padding. This currently is the most widely used mode.
|
||||
However, it is highly recommended to use RSA_PKCS1_OAEP_PADDING in
|
||||
new applications. SEE WARNING BELOW.
|
||||
|
||||
=item RSA_PKCS1_OAEP_PADDING
|
||||
|
||||
@@ -46,23 +48,35 @@ Encrypting user data directly with RSA is insecure.
|
||||
|
||||
=back
|
||||
|
||||
B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
|
||||
based padding modes, less than RSA_size(B<rsa>) - 41 for
|
||||
B<flen> must not be more than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5
|
||||
based padding modes, not more than RSA_size(B<rsa>) - 42 for
|
||||
RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING.
|
||||
The random number generator must be seeded prior to calling
|
||||
RSA_public_encrypt().
|
||||
When a padding mode other than RSA_NO_PADDING is in use, then
|
||||
RSA_public_encrypt() will include some random bytes into the ciphertext
|
||||
and therefore the ciphertext will be different each time, even if the
|
||||
plaintext and the public key are exactly identical.
|
||||
The returned ciphertext in B<to> will always be zero padded to exactly
|
||||
RSA_size(B<rsa>) bytes.
|
||||
B<to> and B<from> may overlap.
|
||||
|
||||
RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the
|
||||
private key B<rsa> and stores the plaintext in B<to>. B<to> must point
|
||||
to a memory section large enough to hold the decrypted data (which is
|
||||
smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that
|
||||
was used to encrypt the data.
|
||||
private key B<rsa> and stores the plaintext in B<to>. B<flen> should
|
||||
be equal to RSA_size(B<rsa>) but may be smaller, when leading zero
|
||||
bytes are in the ciphertext. Those are not important and may be removed,
|
||||
but RSA_public_encrypt() does not do that. B<to> must point
|
||||
to a memory section large enough to hold the maximal possible decrypted
|
||||
data (which is equal to RSA_size(B<rsa>) for RSA_NO_PADDING,
|
||||
RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 based padding modes and
|
||||
RSA_size(B<rsa>) - 42 for RSA_PKCS1_OAEP_PADDING).
|
||||
B<padding> is the padding mode that was used to encrypt the data.
|
||||
B<to> and B<from> may overlap.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
RSA_public_encrypt() returns the size of the encrypted data (i.e.,
|
||||
RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the
|
||||
recovered plaintext.
|
||||
recovered plaintext. A return value of 0 is not an error and
|
||||
means only that the plaintext was empty.
|
||||
|
||||
On error, -1 is returned; the error codes can be
|
||||
obtained by L<ERR_get_error(3)>.
|
||||
@@ -85,7 +99,7 @@ L<RSA_size(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2016 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
|
||||
|
||||
@@ -46,7 +46,7 @@ records, and SSL_has_pending() can't tell the difference between processed and
|
||||
unprocessed data, it's recommended that if read ahead is turned on that
|
||||
B<SSL_MODE_AUTO_RETRY> is not turned off using SSL_CTX_clear_mode().
|
||||
That will prevent getting B<SSL_ERROR_WANT_READ> when there is still a complete
|
||||
record availale that hasn't been processed.
|
||||
record available that hasn't been processed.
|
||||
|
||||
If the application wants to continue to use the underlying transport (e.g. TCP
|
||||
connection) after the SSL connection is finished using SSL_shutdown() reading
|
||||
|
||||
@@ -116,6 +116,20 @@ OCSP_SIGNATURE_free,
|
||||
OCSP_SIGNATURE_new,
|
||||
OCSP_SINGLERESP_free,
|
||||
OCSP_SINGLERESP_new,
|
||||
OSSL_CRMF_CERTID_free,
|
||||
OSSL_CRMF_CERTID_new,
|
||||
OSSL_CRMF_CERTTEMPLATE_free,
|
||||
OSSL_CRMF_CERTTEMPLATE_new,
|
||||
OSSL_CRMF_ENCRYPTEDVALUE_free,
|
||||
OSSL_CRMF_ENCRYPTEDVALUE_new,
|
||||
OSSL_CRMF_MSG_free,
|
||||
OSSL_CRMF_MSG_new,
|
||||
OSSL_CRMF_PBMPARAMETER_free,
|
||||
OSSL_CRMF_PBMPARAMETER_new,
|
||||
OSSL_CRMF_PKIPUBLICATIONINFO_free,
|
||||
OSSL_CRMF_PKIPUBLICATIONINFO_new,
|
||||
OSSL_CRMF_MSGS_free,
|
||||
OSSL_CRMF_MSGS_new,
|
||||
OTHERNAME_free,
|
||||
OTHERNAME_new,
|
||||
PBE2PARAM_free,
|
||||
|
||||
Reference in New Issue
Block a user