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-09-21 00:43:47 +09:00
parent 2e57f602ae
commit 62515c7d8d
1131 changed files with 47556 additions and 24957 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man3/ASYNC_WAIT_CTX_new.pod
+1 -1
View File
@@ -195,7 +195,7 @@ were added in OpenSSL 1.1.0.
ASYNC_WAIT_CTX_set_callback(), ASYNC_WAIT_CTX_get_callback(),
ASYNC_WAIT_CTX_set_status(), and ASYNC_WAIT_CTX_get_status()
were added in OpenSSL 3.0.0.
were added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/ASYNC_start_job.pod
+1 -1
View File
@@ -174,7 +174,7 @@ is included, commonly as one of the first included headers. Therefore
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
=head1 EXAMPLE
=head1 EXAMPLES
The following example demonstrates how to use most of the core async APIs:
doc/man3/BIO_ctrl.pod
+1 -1
View File
@@ -141,7 +141,7 @@ the case of BIO_seek() on a file BIO for a successful operation.
=head1 HISTORY
The BIO_get_ktls_send() and BIO_get_ktls_recv() functions were added in
OpenSSL 3.0.0.
OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/BIO_f_ssl.pod
+18 -18
View File
@@ -129,9 +129,25 @@ BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
=head1 EXAMPLE
=head1 RETURN VALUES
This SSL/TLS client example, attempts to retrieve a page from an
BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
success or a value which is less than or equal to 0 if an error occurred.
BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
a valid B<BIO> structure on success or B<NULL> if an error occurred.
BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
BIO_do_handshake() returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
=head1 EXAMPLES
This SSL/TLS client example attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
unencrypted example in L<BIO_s_connect(3)>.
@@ -271,22 +287,6 @@ a client and also echoes the request to standard output.
BIO_flush(sbio);
BIO_free_all(sbio);
=head1 RETURN VALUES
BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
success or a value which is less than or equal to 0 if an error occurred.
BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
a valid B<BIO> structure on success or B<NULL> if an error occurred.
BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
BIO_do_handshake() returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection could not be established.
=head1 HISTORY
In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
doc/man3/BIO_find_type.pod
+1 -1
View File
@@ -40,7 +40,7 @@ BIO_next() returns the next BIO in a chain.
BIO_method_type() returns the type of the BIO B<b>.
=head1 EXAMPLE
=head1 EXAMPLES
Traverse a chain looking for digest BIOs:
doc/man3/BIO_new.pod
+1 -1
View File
@@ -53,7 +53,7 @@ on it other than the discarded return value.
BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
=head1 EXAMPLE
=head1 EXAMPLES
Create a memory BIO:
doc/man3/BIO_s_accept.pod
+1 -1
View File
@@ -174,7 +174,7 @@ BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
BIO_new_accept() returns a BIO or NULL on error.
=head1 EXAMPLE
=head1 EXAMPLES
This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
doc/man3/BIO_s_bio.pod
+2 -2
View File
@@ -133,7 +133,7 @@ locations for B<bio1> and B<bio2>. Check the error stack for more information.
[XXXXX: More return values need to be added here]
=head1 EXAMPLE
=head1 EXAMPLES
The BIO pair can be used to have full control over the network access of an
application. The application can call select() on the socket as required
@@ -176,7 +176,7 @@ and must be transferred to the network. Use BIO_ctrl_get_read_request() to
find out, how many bytes must be written into the buffer before the
SSL_operation() can successfully be continued.
=head1 WARNING
=head1 WARNINGS
As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
condition, but there is still data in the write buffer. An application must
doc/man3/BIO_s_connect.pod
+1 -1
View File
@@ -163,7 +163,7 @@ BIO_set_nbio() always returns 1.
BIO_do_connect() returns 1 if the connection was successfully
established and 0 or -1 if the connection failed.
=head1 EXAMPLE
=head1 EXAMPLES
This is example connects to a webserver on the local host and attempts
to retrieve a page and copy the result to standard output.
doc/man3/BIO_s_fd.pod
+1 -1
View File
@@ -68,7 +68,7 @@ been initialized.
BIO_new_fd() returns the newly allocated BIO or NULL is an error
occurred.
=head1 EXAMPLE
=head1 EXAMPLES
This is a file descriptor BIO version of "Hello World":
doc/man3/BIO_s_mem.pod
+13 -9
View File
@@ -118,7 +118,19 @@ BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation.
There should be an option to set the maximum size of a memory BIO.
=head1 EXAMPLE
=head1 RETURN VALUES
BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
BIO_set_mem_eof_return(), BIO_set_mem_buf() and BIO_get_mem_ptr()
return 1 on success or a value which is less than or equal to 0 if an error occurred.
BIO_get_mem_data() returns the total number of bytes available on success,
0 if b is NULL, or a negative value in case of other errors.
BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
=head1 EXAMPLES
Create a memory BIO and write some data to it:
@@ -139,14 +151,6 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
=head1 RETURN VALUES
BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
return 1 on success or a value which is less than or equal to 0 if an error occurred.
BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
=head1 COPYRIGHT
doc/man3/BIO_set_callback.pod
+5 -5
View File
@@ -211,11 +211,6 @@ the actual call parameter, see B<BIO_callback_ctrl>.
=back
=head1 EXAMPLE
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 RETURN VALUES
BIO_get_callback_ex() and BIO_get_callback() return the callback function
@@ -228,6 +223,11 @@ via a call to BIO_set_callback_arg().
BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
operations.
=head1 EXAMPLES
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/BN_generate_prime.pod
+25 -9
View File
@@ -2,15 +2,19 @@
=head1 NAME
BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg,
BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test
for primality
BN_generate_prime_ex2, BN_generate_prime_ex, BN_is_prime_ex,
BN_is_prime_fasttest_ex, BN_GENCB_call, BN_GENCB_new, BN_GENCB_free,
BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, BN_generate_prime,
BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_generate_prime_ex2(BIGNUM *ret, int bits, int safe,
const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb,
BN_CTX *ctx);
int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
const BIGNUM *rem, BN_GENCB *cb);
@@ -50,9 +54,12 @@ L<openssl_user_macros(7)>:
=head1 DESCRIPTION
BN_generate_prime_ex() generates a pseudo-random prime number of
at least bit length B<bits>. The returned number is probably prime
with a negligible error.
BN_generate_prime_ex2() generates a pseudo-random prime number of
at least bit length B<bits> using the BN_CTX provided in B<ctx>. The value of
B<ctx> must not be NULL.
The returned number is probably prime with a negligible error.
If B<add> is B<NULL> the returned prime number will have exact bit
length B<bits> with the top most two bits set.
If B<ret> is not B<NULL>, it will be used to store the number.
@@ -89,11 +96,20 @@ If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add>
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).
that (p-1)/2 is also prime). If B<safe> is true, and B<rem> == B<NULL>
the condition will be p % B<add> == 3.
It is recommended that B<add> is a multiple of 4.
The random generator must be seeded prior to calling BN_generate_prime_ex().
If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
external circumstances (see L<RAND(7)>), the operation will fail.
The random number generator configured for the OPENSSL_CTX associated with
B<ctx> will be used.
BN_generate_prime_ex() is the same as BN_generate_prime_ex2() except that no
B<ctx> parameter is passed.
In this case the random number generator associated with the default OPENSSL_CTX
will be used.
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
@@ -206,7 +222,7 @@ and BN_GENCB_get_arg() functions were added in OpenSSL 1.1.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/BN_mod_mul_montgomery.pod
+1 -1
View File
@@ -64,7 +64,7 @@ BN_MONT_CTX_free() has no return value.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 WARNING
=head1 WARNINGS
The inputs must be reduced modulo B<m>, otherwise the result will be
outside the expected range.
doc/man3/BN_new.pod
+2 -2
View File
@@ -22,7 +22,7 @@ BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGN
BN_new() allocates and initializes a B<BIGNUM> structure.
BN_secure_new() does the same except that the secure heap
OPENSSL_secure_malloc(3) is used to store the value.
L<OPENSSL_secure_malloc(3)> is used to store the value.
BN_clear() is used to destroy sensitive data such as keys when they
are no longer needed. It erases the memory used by B<a> and sets it
@@ -46,7 +46,7 @@ BN_clear(), BN_free() and BN_clear_free() have no return values.
=head1 SEE ALSO
L<ERR_get_error(3)>
L<ERR_get_error(3)>, L<OPENSSL_secure_malloc(3)>
=head1 HISTORY
doc/man3/CMS_add1_signing_cert.pod
-45
View File
@@ -1,45 +0,0 @@
=pod
=head1 NAME
CMS_add1_signing_cert, CMS_add1_signing_cert_v2
- add ESS signing-certificate signed attribute to a
CMS_SignerInfo data structure
=head1 SYNOPSIS
#include <openssl/cms.h>
int CMS_add1_signing_cert(CMS_SignerInfo *si, ESS_SIGNING_CERT *sc);
int CMS_add1_signing_cert_v2(CMS_SignerInfo *si, ESS_SIGNING_CERT_V2 *sc2);
=head1 DESCRIPTION
CMS_add1_signing_cert() adds an ESS Signing Certificate B<sc> (version 1) signed
attribute to the CMS_SignerInfo B<si>.
CMS_add1_signing_cert_v2() adds an ESS Signing Certificate B<sc2> (version 2) signed
attribute to the CMS_SignerInfo B<si>.
The ESS Signing Certificate attributes version 1 and 2 are defined in RFC 5035
which updates Section 5.4 of RFC 2634.
=head1 NOTES
This attribute is mandatory to make a CMS compliant with CAdES-BES
(European Standard ETSI EN 319 122-1 V1.1.1).
For a fuller description see L<cms(1)>).
=head1 RETURN VALUES
CMS_add1_signing_cert() and CMS_add1_signing_cert_v2() return 1 if attribute is added or 0 if an error occurred.
=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/CMS_compress.pod
-4
View File
@@ -17,8 +17,6 @@ is the compression algorithm to use or B<NID_undef> to use the default
algorithm (zlib compression). B<in> is the content to be compressed.
B<flags> is an optional set of flags.
=head1 NOTES
The only currently supported compression algorithm is zlib using the NID
NID_zlib_compression.
@@ -41,8 +39,6 @@ The compressed data is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
practice and is not supported by SMIME_write_CMS().
=head1 NOTES
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
doc/man3/CMS_encrypt.pod
-4
View File
@@ -17,8 +17,6 @@ CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs>
is a list of recipient certificates. B<in> is the content to be encrypted.
B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
=head1 NOTES
Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this
function.
@@ -60,8 +58,6 @@ The data being encrypted is included in the CMS_ContentInfo structure, unless
B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
practice and is not supported by SMIME_write_CMS().
=head1 NOTES
If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
B<not> complete and outputting its contents via a function that does not
properly finalize the B<CMS_ContentInfo> structure will give unpredictable
doc/man3/CRYPTO_THREAD_run_once.pod
+10 -12
View File
@@ -97,7 +97,16 @@ one of the first included headers. Therefore it is defined as an
application developer's responsibility to include windows.h prior to
crypto.h where use of CRYPTO_THREAD_* types and functions is required.
=head1 EXAMPLE
=head1 EXAMPLES
You can find out if OpenSSL was configured with thread support:
#include <openssl/opensslconf.h>
#if defined(OPENSSL_THREADS)
/* thread support enabled */
#else
/* no thread support */
#endif
This example safely initializes and uses a lock.
@@ -144,17 +153,6 @@ no longer in use and is unloaded.
The simplest solution is to just "leak" the lock in applications and not
repeatedly load/unload shared libraries that allocate locks.
=head1 NOTES
You can find out if OpenSSL was configured with thread support:
#include <openssl/opensslconf.h>
#if defined(OPENSSL_THREADS)
/* thread support enabled */
#else
/* no thread support */
#endif
=head1 SEE ALSO
L<crypto(7)>
doc/man3/CRYPTO_get_ex_new_index.pod
+1 -1
View File
@@ -162,7 +162,7 @@ dup_func() should return 0 for failure and 1 for success.
=head1 HISTORY
CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.0.
CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/DH_generate_parameters.pod
+9 -1
View File
@@ -73,6 +73,14 @@ The generator B<g> is not suitable.
Note that the lack of this bit doesn't guarantee that B<g> is
suitable, unless B<p> is known to be a strong prime.
=item DH_MODULUS_TOO_SMALL
The modulus is too small.
=item DH_MODULUS_TOO_LARGE
The modulus is too large.
=back
DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The
@@ -141,7 +149,7 @@ DH_generate_parameters_ex() instead.
=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/ECDSA_SIG_new.pod
+9 -16
View File
@@ -3,10 +3,10 @@
=head1 NAME
ECDSA_SIG_get0, ECDSA_SIG_get0_r, ECDSA_SIG_get0_s, ECDSA_SIG_set0,
ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size,
ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup,
ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic curve digital signature
algorithm (ECDSA) functions
ECDSA_SIG_new, ECDSA_SIG_free, ECDSA_size, ECDSA_sign, ECDSA_do_sign,
ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, ECDSA_sign_ex,
ECDSA_do_sign_ex - low level elliptic curve digital signature algorithm (ECDSA)
functions
=head1 SYNOPSIS
@@ -18,8 +18,6 @@ algorithm (ECDSA) functions
const BIGNUM *ECDSA_SIG_get0_r(const ECDSA_SIG *sig);
const BIGNUM *ECDSA_SIG_get0_s(const ECDSA_SIG *sig);
int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s);
int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len);
int ECDSA_size(const EC_KEY *eckey);
int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen,
@@ -68,15 +66,8 @@ function transfers the memory management of the values to the ECDSA_SIG object,
and therefore the values that have been passed in should not be freed directly
after this function has been called.
i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B<sig> and
writes the encoded signature to B<*pp> (note: if B<pp> is NULL i2d_ECDSA_SIG()
returns the expected length in bytes of the DER encoded signature).
i2d_ECDSA_SIG() returns the length of the DER encoded signature (or 0 on
error).
d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the decoded
signature in a newly allocated B<ECDSA_SIG> structure. B<*sig> points to the
buffer containing the DER encoded signature of size B<len>.
See L<i2d_ECDSA_SIG(3)> and L<d2i_ECDSA_SIG(3)> for information about encoding
and decoding ECDSA signatures to/from DER.
ECDSA_size() returns the maximum length of a DER encoded ECDSA signature
created with the private EC key B<eckey>.
@@ -202,7 +193,9 @@ ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
L<EC_KEY_new(3)>,
L<EVP_DigestSignInit(3)>,
L<EVP_DigestVerifyInit(3)>
L<EVP_DigestVerifyInit(3)>,
L<i2d_ECDSA_SIG(3)>,
L<d2i_ECDSA_SIG(3)>
=head1 COPYRIGHT
doc/man3/EC_GROUP_copy.pod
+4 -1
View File
@@ -51,7 +51,8 @@ EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
int EC_GROUP_get_degree(const EC_GROUP *group);
int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
int EC_GROUP_check_named_curve(const EC_GROUP *group, int nist_only);
int EC_GROUP_check_named_curve(const EC_GROUP *group, int nist_only,
BN_CTX *ctx);
int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
@@ -152,6 +153,8 @@ then this method can be used to lookup the name of the curve that matches the gr
aliases, so that multiple NID's can map to the same domain parameters. For such curves it is unspecified which of the aliases will be
returned if the curve name of the given group is NID_undef.
If B<nist_only> is 1 it will only look for NIST approved curves, otherwise it searches all built-in curves.
This function may be passed a BN_CTX object in the B<ctx> parameter.
The B<ctx> parameter may be NULL.
EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
doc/man3/EC_GROUP_new.pod
+24 -5
View File
@@ -4,6 +4,7 @@
EC_GROUP_get_ecparameters,
EC_GROUP_get_ecpkparameters,
EC_GROUP_new_ex,
EC_GROUP_new,
EC_GROUP_new_from_ecparameters,
EC_GROUP_new_from_ecpkparameters,
@@ -11,6 +12,7 @@ EC_GROUP_free,
EC_GROUP_clear_free,
EC_GROUP_new_curve_GFp,
EC_GROUP_new_curve_GF2m,
EC_GROUP_new_by_curve_name_ex,
EC_GROUP_new_by_curve_name,
EC_GROUP_set_curve,
EC_GROUP_get_curve,
@@ -25,6 +27,7 @@ objects
#include <openssl/ec.h>
EC_GROUP *EC_GROUP_new_ex(OPENSSL_CTX *libctx, const EC_METHOD *meth);
EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
@@ -35,6 +38,7 @@ objects
const BIGNUM *b, BN_CTX *ctx);
EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,
const BIGNUM *b, BN_CTX *ctx);
EC_GROUP *EC_GROUP_new_by_curve_name_ex(OPENSSL_CTX *libctx, int nid);
EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
@@ -71,12 +75,18 @@ y^2 + xy = x^3 + ax^2 + b (where b != 0)
Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
use a trinomial or a pentanomial for this parameter.
A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
L<EC_GFp_simple_method(3)>). It is then necessary to call EC_GROUP_set_curve() to set the curve parameters.
A new curve can be constructed by calling EC_GROUP_new_ex, using the implementation provided by B<meth> (see
L<EC_GFp_simple_method(3)>) and associated with the library context B<ctx>
(see L<OPENSSL_CTX(3)>).
The B<ctx> parameter may be NULL in which case the default library context is used.
It is then necessary to call EC_GROUP_set_curve() to set the curve parameters.
EC_GROUP_new_from_ecparameters() will create a group from the
specified B<params> and
EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>.
EC_GROUP_new is the same as EC_GROUP_new_ex() except that the library context
used is always the default library context.
EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve over Fp B<b>
is the prime for the field. For a curve over F2^m B<p> represents the irreducible polynomial - each bit
represents a term in the polynomial. Therefore there will either be three or five bits set dependent on whether
@@ -109,8 +119,12 @@ The EC_builtin_curve structure is defined as follows:
Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to
be constructed.
In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name_ex and provide the B<nid> of the curve to
be constructed and the associated library context to be used in B<ctx> (see L<OPENSSL_CTX(3)>).
The B<ctx> value may be NULL in which case the default library context is used.
EC_GROUP_new_by_curve_name is the same as EC_GROUP_new_by_curve_name_ex except
that the default library context is always used.
EC_GROUP_free frees the memory associated with the EC_GROUP.
If B<group> is NULL nothing is done.
@@ -130,7 +144,12 @@ EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROU
L<crypto(7)>, L<EC_GROUP_copy(3)>,
L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>,
L<OPENSSL_CTX(3)>
=head1 HISTORY
EC_GROUP_new_ex and EC_GROUP_new_by_curve_name_ex were added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/EC_KEY_new.pod
+31 -12
View File
@@ -2,10 +2,10 @@
=head1 NAME
EC_KEY_get_method, EC_KEY_set_method,
EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex,
EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags,
EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref,
EC_KEY_get0_engine,
EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy,
EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_engine,
EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key,
EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key,
EC_KEY_get_conv_form,
@@ -19,10 +19,12 @@ EC_KEY objects
#include <openssl/ec.h>
EC_KEY *EC_KEY_new_ex(OPENSSL_CTX *ctx);
EC_KEY *EC_KEY_new(void);
int EC_KEY_get_flags(const EC_KEY *key);
void EC_KEY_set_flags(EC_KEY *key, int flags);
void EC_KEY_clear_flags(EC_KEY *key, int flags);
EC_KEY *EC_KEY_new_by_curve_name_ex(OPENSSL_CTX *ctx, int nid);
EC_KEY *EC_KEY_new_by_curve_name(int nid);
void EC_KEY_free(EC_KEY *key);
EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
@@ -57,15 +59,31 @@ EC_KEY objects
=head1 DESCRIPTION
An EC_KEY represents a public key and, optionally, the associated private
key. A new EC_KEY with no associated curve can be constructed by calling
EC_KEY_new(). The reference count for the newly created EC_KEY is initially
set to 1. A curve can be associated with the EC_KEY by calling
key.
A new EC_KEY with no associated curve can be constructed by calling
EC_KEY_new_ex() and specifying the associated library context in B<ctx>
(see L<OPENSSL_CTX(3)>).
The B<ctx> parameter may be NULL in which case the default library context is
used.
The reference count for the newly created EC_KEY is initially
set to 1.
A curve can be associated with the EC_KEY by calling
EC_KEY_set_group().
EC_KEY_new() is the same as EC_KEY_new_ex() except that the default library
context is always used.
Alternatively a new EC_KEY can be constructed by calling
EC_KEY_new_by_curve_name() and supplying the nid of the associated curve. See
L<EC_GROUP_new(3)> for a description of curve names. This function simply
wraps calls to EC_KEY_new() and EC_GROUP_new_by_curve_name().
EC_KEY_new_by_curve_name_ex() and supplying the nid of the associated curve and
the library context to be used B<ctx> (see L<OPENSSL_CTX(3)>).
The B<ctx> parameter may be NULL in which case the default library context is
used.
See L<EC_GROUP_new(3)> for a description of curve names.
This function simply wraps calls to EC_KEY_new_ex() and
EC_GROUP_new_by_curve_name_ex().
EC_KEY_new_by_curve_name() is the same as EC_KEY_new_by_curve_name_ex() except
that the default library context is always used.
Calling EC_KEY_free() decrements the reference count for the EC_KEY object,
and if it has dropped to zero then frees the memory associated with it. If
@@ -144,8 +162,8 @@ EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer.
=head1 RETURN VALUES
EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to
the newly created EC_KEY object, or NULL on error.
EC_KEY_new_ex(), EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup()
return a pointer to the newly created EC_KEY object, or NULL on error.
EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an
integer.
@@ -174,7 +192,8 @@ L<crypto(7)>, L<EC_GROUP_new(3)>,
L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>,
L<EC_POINT_add(3)>,
L<EC_GFp_simple_method(3)>,
L<d2i_ECPKParameters(3)>
L<d2i_ECPKParameters(3)>,
L<OPENSSL_CTX(3)>
=head1 COPYRIGHT
doc/man3/ERR_GET_LIB.pod
+2 -1
View File
@@ -38,12 +38,13 @@ unique. However, when checking for sub-library specific reason codes,
be sure to also compare the library number.
ERR_GET_LIB(), ERR_GET_FUNC(), ERR_GET_REASON(), and ERR_FATAL_ERROR()
are macros.
are macros.
=head1 RETURN VALUES
The library number, function code, reason code, and whether the error
is fatal, respectively.
Starting with OpenSSL 3.0.0, the function code is always set to zero.
=head1 SEE ALSO
doc/man3/ERR_error_string.pod
+16 -9
View File
@@ -14,9 +14,12 @@ error message
void ERR_error_string_n(unsigned long e, char *buf, size_t len);
const char *ERR_lib_error_string(unsigned long e);
const char *ERR_func_error_string(unsigned long e);
const char *ERR_reason_error_string(unsigned long e);
Deprecated in OpenSSL 3.0:
const char *ERR_func_error_string(unsigned long e);
=head1 DESCRIPTION
ERR_error_string() generates a human-readable string representing the
@@ -33,13 +36,12 @@ For ERR_error_string_n(), I<buf> may not be B<NULL>.
The string will have the following format:
error:[error code]:[library name]:[function name]:[reason string]
error:[error code]:[library name]::[reason string]
I<error code> is an 8 digit hexadecimal number, I<library name>,
I<function name> and I<reason string> are ASCII text.
I<error code> is an 8 digit hexadecimal number, I<library name> and
I<reason string> are ASCII text.
ERR_lib_error_string(), ERR_func_error_string() and
ERR_reason_error_string() return the library name, function
ERR_lib_error_string() and ERR_reason_error_string() return the library
name and reason string respectively.
If there is no text string registered for the given error code,
@@ -53,15 +55,20 @@ all error codes currently in the queue.
ERR_error_string() returns a pointer to a static buffer containing the
string if I<buf> B<== NULL>, I<buf> otherwise.
ERR_lib_error_string(), ERR_func_error_string() and
ERR_reason_error_string() return the strings, and B<NULL> if
none is registered for the error code.
ERR_lib_error_string() and ERR_reason_error_string() return the strings,
and B<NULL> if none is registered for the error code.
ERR_func_error_string() returns NULL.
=head1 SEE ALSO
L<ERR_get_error(3)>,
L<ERR_print_errors(3)>
=head1 HISTORY
ERR_func_error_string() became deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/ERR_get_error.pod
+57 -7
View File
@@ -4,8 +4,11 @@
ERR_get_error, ERR_peek_error, ERR_peek_last_error,
ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line,
ERR_get_error_line_data, ERR_peek_error_line_data,
ERR_peek_last_error_line_data - obtain error code and data
ERR_get_error_func, ERR_peek_error_func, ERR_peek_last_error_func,
ERR_get_error_data, ERR_peek_error_data, ERR_peek_last_error_data,
ERR_get_error_all, ERR_peek_error_all, ERR_peek_last_error_all,
ERR_get_error_line_data, ERR_peek_error_line_data, ERR_peek_last_error_line_data
- obtain error code and data
=head1 SYNOPSIS
@@ -19,6 +22,26 @@ ERR_peek_last_error_line_data - obtain error code and data
unsigned long ERR_peek_error_line(const char **file, int *line);
unsigned long ERR_peek_last_error_line(const char **file, int *line);
unsigned long ERR_get_error_func(const char **func);
unsigned long ERR_peek_error_func(const char **func);
unsigned long ERR_peek_last_error_func(const char **func);
unsigned long ERR_get_error_data(const char **data, int *flags);
unsigned long ERR_peek_error_data(const char **data, int *flags);
unsigned long ERR_peek_last_error_data(const char **data, int *flags);
unsigned long ERR_get_error_all(const char **file, int *line,
const char *func,
const char **data, int *flags);
unsigned long ERR_peek_error_all(const char **file, int *line,
const char *func,
const char **data, int *flags);
unsigned long ERR_peek_last_error_all(const char **file, int *line,
const char *func,
const char **data, int *flags);
Deprecated since OpenSSL 3.0:
unsigned long ERR_get_error_line_data(const char **file, int *line,
const char **data, int *flags);
unsigned long ERR_peek_error_line_data(const char **file, int *line,
@@ -44,15 +67,31 @@ L<ERR_error_string(3)> for human-readable error
messages.
ERR_get_error_line(), ERR_peek_error_line() and
ERR_peek_last_error_line() are the same as the above, but they
ERR_peek_last_error_line() are the same as ERR_get_error(),
ERR_peek_error() and ERR_peek_last_error(), but they
additionally store the file name and line number where
the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
ERR_get_error_func(), ERR_peek_error_func() and
ERR_peek_last_error_func() are the same as ERR_get_error(),
ERR_peek_error() and ERR_peek_last_error(), but they
additionally store the name of the function where the error in *B<func>,
unless it is B<NULL>.
ERR_get_error_data(), ERR_peek_error_data() and
ERR_peek_last_error_data() are the same as ERR_get_error(),
ERR_peek_error() and ERR_peek_last_error(), but they
additionally store additional data and flags associated with the error
code in *B<data> and *B<flags>, unless these are B<NULL>.
*B<data> contains a string if *B<flags>&B<ERR_TXT_STRING> is true.
ERR_get_error_all(), ERR_peek_error_all() and
ERR_peek_last_error_all() are combinations of all of the above.
ERR_get_error_line_data(), ERR_peek_error_line_data() and
ERR_peek_last_error_line_data() store additional data and flags
associated with the error code in *B<data>
and *B<flags>, unless these are B<NULL>. *B<data> contains a string
if *B<flags>&B<ERR_TXT_STRING> is true.
ERR_peek_last_error_line_data() are older variants of ERR_get_error_all(),
ERR_peek_error_all() and ERR_peek_last_error_all(), and should no longer
be used.
An application B<MUST NOT> free the *B<data> pointer (or any other pointers
returned by these functions) with OPENSSL_free() as freeing is handled
@@ -67,6 +106,17 @@ The error code, or 0 if there is no error in the queue.
L<ERR_error_string(3)>,
L<ERR_GET_LIB(3)>
=head1 HISTORY
ERR_get_error_func(), ERR_peek_error_func(), ERR_peek_last_error_func(),
ERR_get_error_data(), ERR_peek_error_data(), ERR_peek_last_error_data(),
ERR_get_error_all(), ERR_peek_error_all() and ERR_peek_last_error_all()
were added in OpenSSL 3.0.
ERR_get_error_line_data(), ERR_peek_error_line_data() and
ERR_peek_last_error_line_data() became deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/ERR_new.pod
+78
View File
@@ -0,0 +1,78 @@
=pod
=head1 NAME
ERR_new, ERR_set_debug, ERR_set_error, ERR_vset_error
- Error recording building blocks
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_new(void);
void ERR_set_debug(const char *file, int line, const char *func);
void ERR_set_error(int lib, int reason, const char *fmt, ...);
void ERR_vset_error(int lib, int reason, const char *fmt, va_list args);
=head1 DESCRIPTION
The functions described here are generally not used directly, but
rather through macros such as L<ERR_raise(3)>.
They can still be useful for anyone that wants to make their own
macros.
ERR_new() allocates a new slot in the thread's error queue.
ERR_set_debug() sets the debug information related to the current
error in the thread's error queue.
The values that can be given are the file name I<file>, line in the
file I<line> and the name of the function I<func> where the error
occured.
The names must be constant, this function will only save away the
pointers, not copy the strings.
ERR_set_error() sets the error information, which are the library
number I<lib> and the reason code I<reason>, and additional data as a
format string I<fmt> and an arbitrary number of arguments.
The additional data is processed with L<BIO_snprintf(3)> to form the
additional data string, which is allocated and store in the error
record.
ERR_vset_error() works like ERR_set_error(), but takes a B<va_list>
argument instead of a variable number of arguments.
=head1 RETURN VALUES
ERR_new, ERR_set_debug, ERR_set_error and ERR_vset_error
do not return any values.
=head1 NOTES
The library number is unique to each unit that records errors.
OpenSSL has a number of pre-allocated ones for its own uses, but
others may allocate their own library number dynamically with
L<ERR_get_next_error_library(3)>.
Reason codes are unique within each library, and may have an
associated set of strings as a short description of the reason.
For dynamically allocated library numbers, reason strings are recorded
with L<ERR_load_strings(3)>.
Provider authors are supplied with core versions of these functions,
see L<provider-base(7)>.
=head1 SEE ALSO
L<ERR_raise(3)>, L<ERR_get_next_error_library(3)>,
L<ERR_load_strings(3)>, L<BIO_snprintf(3)>, L<provider-base(7)>
=head1 COPYRIGHT
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
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
doc/man3/ERR_put_error.pod
+28 -5
View File
@@ -2,19 +2,36 @@
=head1 NAME
ERR_put_error, ERR_add_error_data, ERR_add_error_vdata - record an error
ERR_raise, ERR_raise_data,
ERR_put_error, ERR_add_error_data, ERR_add_error_vdata
- record an error
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_put_error(int lib, int func, int reason, const char *file, int line);
void ERR_raise(int lib, int reason);
void ERR_raise_data(int lib, int reason, const char *fmt, ...);
void ERR_add_error_data(int num, ...);
void ERR_add_error_vdata(int num, va_list arg);
Deprecated since OpenSSL 3.0:
void ERR_put_error(int lib, int func, int reason, const char *file, int line);
=head1 DESCRIPTION
ERR_raise() adds a new error to the thread's error queue. The
error occured in the library B<lib> for the reason given by the
B<reason> code. Furthermore, the name of the file, the line, and name
of the function where the error occured is saved with the error
record.
ERR_raise_data() does the same thing as ERR_raise(), but also lets the
caller specify additional information as a format string B<fmt> and an
arbitrary number of values, which are processed with L<BIO_snprintf(3)>.
ERR_put_error() adds an error code to the thread's error queue. It
signals that the error of reason code B<reason> occurred in function
B<func> of library B<lib>, in line number B<line> of B<file>.
@@ -31,6 +48,8 @@ error messages for the error code.
=head2 Reporting errors
=for comment TODO(3.0) should this be internal documentation?
Each sub-library has a specific macro XXXerr() that is used to report
errors. Its first argument is a function code B<XXX_F_...>, the second
argument is a reason code B<XXX_R_...>. Function codes are derived
@@ -57,8 +76,12 @@ the ASN1err() macro.
=head1 RETURN VALUES
ERR_put_error() and ERR_add_error_data() return
no values.
ERR_raise(), ERR_put_error(), ERR_add_error_data() and
ERR_add_error_vdata() return no values.
=head1 NOTES
ERR_raise() and ERR_put_error() are implemented as macros.
=head1 SEE ALSO
@@ -66,7 +89,7 @@ L<ERR_load_strings(3)>
=head1 COPYRIGHT
Copyright 2000-2017 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_CIPHER_meth_new.pod
+3 -7
View File
@@ -10,7 +10,7 @@ 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, EVP_CIPHER_up_ref
EVP_CIPHER_meth_get_ctrl
- Routines to build up EVP_CIPHER methods
=head1 SYNOPSIS
@@ -63,8 +63,6 @@ EVP_CIPHER_meth_get_ctrl, EVP_CIPHER_up_ref
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
@@ -226,8 +224,6 @@ 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
@@ -236,8 +232,6 @@ 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>
@@ -245,6 +239,8 @@ L<EVP_EncryptInit>
=head1 HISTORY
The functions described here were added in OpenSSL 1.1.0.
The B<EVP_CIPHER> structure created with these functions became reference
counted in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/EVP_DigestInit.pod
+115 -22
View File
@@ -2,28 +2,44 @@
=head1 NAME
EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free,
EVP_MD_get_params, EVP_MD_gettable_params,
EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_params, EVP_MD_CTX_get_params,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl,
EVP_MD_CTX_set_params, EVP_MD_CTX_get_params,
EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params,
EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
EVP_MD_name, EVP_MD_provider,
EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags,
EVP_MD_CTX_name,
EVP_MD_CTX_md, EVP_MD_CTX_type, EVP_MD_CTX_size, EVP_MD_CTX_block_size,
EVP_MD_CTX_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn,
EVP_md_null,
EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj,
EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx,
EVP_MD_do_all_ex
- EVP digest routines
=head1 SYNOPSIS
#include <openssl/evp.h>
EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm,
const char *properties);
int EVP_MD_up_ref(EVP_MD *md);
void EVP_MD_free(EVP_MD *md);
int EVP_MD_get_params(const EVP_MD *digest, OSSL_PARAM params[]);
const OSSL_PARAM *EVP_MD_gettable_params(const EVP_MD *digest);
EVP_MD_CTX *EVP_MD_CTX_new(void);
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[]);
const OSSL_PARAM *EVP_MD_CTX_settable_params(const EVP_MD *digest);
const OSSL_PARAM *EVP_MD_CTX_gettable_params(const EVP_MD *digest);
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);
@@ -42,6 +58,8 @@ EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
const char *EVP_MD_name(const EVP_MD *md);
const OSSL_PROVIDER *EVP_MD_provider(const EVP_MD *md);
int EVP_MD_type(const EVP_MD *md);
int EVP_MD_pkey_type(const EVP_MD *md);
int EVP_MD_size(const EVP_MD *md);
@@ -49,6 +67,7 @@ EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
unsigned long EVP_MD_flags(const EVP_MD *md);
const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
const char *EVP_MD_CTX_name(const EVP_MD_CTX *ctx);
int EVP_MD_CTX_size(const EVP_MD *ctx);
int EVP_MD_CTX_block_size(const EVP_MD *ctx);
int EVP_MD_CTX_type(const EVP_MD *ctx);
@@ -68,13 +87,38 @@ EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx);
void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);
void EVP_MD_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_MD *mac, void *arg),
void *arg);
=head1 DESCRIPTION
The EVP digest routines are a high level interface to message digests,
and should be used instead of the cipher-specific functions.
and should be used instead of the digest-specific functions.
The B<EVP_MD> type is a structure for digest method implementation.
=over 4
=item EVP_MD_fetch()
Fetches the digest implementation for the given B<algorithm> from any
provider offering it, within the criteria given by the B<properties>.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with EVP_MD_free().
Fetched B<EVP_MD> structures are reference counted.
=item EVP_MD_up_ref()
Increments the reference count for an B<EVP_MD> structure.
=item EVP_MD_free()
Decrements the reference count for the fetched B<EVP_MD> structure.
If the reference count drops to 0 then the structure is freed.
=item EVP_MD_CTX_new()
Allocates and returns a digest context.
@@ -99,15 +143,28 @@ 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
=item EVP_MD_get_params()
Retrieves the requested list of B<params> from a MD B<md>.
See L</PARAMETERS> below for more information.
=item EVP_MD_CTX_get_params()
Retrieves the requested list of B<params> from a MD context B<ctx>.
See L</PARAMS> below for more information.
See L</PARAMETERS> below for more information.
=item EVP_MD_CTX_set_params
=item EVP_MD_CTX_set_params()
Sets the list of <params> into a MD context B<ctx>.
See L</PARAMS> below for more information.
Sets the list of B<params> into a MD context B<ctx>.
See L</PARAMETERS> below for more information.
=item EVP_MD_gettable_params(), EVP_MD_CTX_gettable_params(),
EVP_MD_CTX_settable_params()
Get a B<OSSL_PARAM> array that describes the retrievable and settable
parameters, i.e. parameters that can be used with EVP_MD_get_params(),
EVP_MD_CTX_get_params() and EVP_MD_CTX_set_params(), respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()
@@ -123,9 +180,12 @@ If B<impl> is NULL the default implementation of digest B<type> is used.
=item EVP_DigestInit_ex()
Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
B<type> will typically be supplied by a function such as EVP_sha1(). If
B<impl> is NULL then the default implementation of digest B<type> is used.
Sets up digest context B<ctx> to use a digest B<type>.
B<type> is typically supplied by a function such as EVP_sha1(), or a
value explicitly fetched with EVP_MD_fetch().
If B<impl> is non-NULL, its implementation of the digest B<type> is used if
there is one, and if not, the default implementation is used.
=item EVP_DigestUpdate()
@@ -170,6 +230,16 @@ automatically cleaned up.
Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to
be initialized.
=item EVP_MD_name(),
EVP_MD_CTX_name()
Return the name of the given message digest.
=item EVP_MD_provider()
Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given
B<EVP_MD>.
=item EVP_MD_size(),
EVP_MD_CTX_size()
@@ -252,9 +322,16 @@ by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CT
assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
depends on how the B<EVP_PKEY_CTX> is created.
=item EVP_MD_do_all_ex()
Traverses all messages digests implemented by all activated providers
in the given library context I<libctx>, and for each of the implementations,
calls the given function I<fn> with the implementation method and the given
I<arg> as argument.
=back
=head1 PARAMS
=head1 PARAMETERS
See L<OSSL_PARAM(3)> for information about passing parameters.
@@ -262,12 +339,13 @@ EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys:
=over 4
=item OSSL_PARAM_DIGEST_KEY_XOFLEN <size_t>
=item OSSL_PARAM_DIGEST_KEY_XOFLEN <unsigned integer>
Sets the digest length for extendable output functions.
It is used by the SHAKE algorithm.
It is used by the SHAKE algorithm and should not exceed what can be given
using a B<size_t>.
=item OSSL_PARAM_DIGEST_KEY_PAD_TYPE <int>
=item OSSL_PARAM_DIGEST_KEY_PAD_TYPE <integer>
Sets the pad type.
It is used by the MDC2 algorithm.
@@ -278,7 +356,7 @@ EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys:
=over 4
=item OSSL_PARAM_DIGEST_KEY_MICALG <utf8string>.
=item OSSL_PARAM_DIGEST_KEY_MICALG <UTF8 string>.
Gets the digest Message Integrity Check algorithm string. This is used when
creating S/MIME multipart/signed messages, as specified in RFC 3851.
@@ -343,6 +421,14 @@ disabled with this flag.
=over 4
=item EVP_MD_fetch()
Returns a pointer to a B<EVP_MD> for success or NULL for failure.
=item EVP_MD_up_ref()
Returns 1 for success or 0 for failure.
=item EVP_DigestInit_ex(),
EVP_DigestUpdate(),
EVP_DigestFinal_ex()
@@ -359,6 +445,12 @@ EVP_MD_CTX_get_params()
Returns 1 if successful or 0 for failure.
=item EVP_MD_CTX_settable_params(),
EVP_MD_CTX_gettable_params()
Return an array of constant B<OSSL_PARAM>s, or NULL if there is none
to get.
=item EVP_MD_CTX_copy_ex()
Returns 1 if successful or 0 for failure.
@@ -415,14 +507,14 @@ implementations of digests to be specified.
If digest contexts are not cleaned up after use,
memory leaks will occur.
EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(),
EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as
macros.
EVP_MD_CTX_name(), EVP_MD_CTX_size(), EVP_MD_CTX_block_size(),
EVP_MD_CTX_type(), EVP_get_digestbynid() and EVP_get_digestbyobj() are defined
as macros.
EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration
or control.
=head1 EXAMPLE
=head1 EXAMPLES
This example digests the data "Test Message\n" and "Hello World\n", using the
digest name passed on the command line.
@@ -487,6 +579,7 @@ L<EVP_sha224(3)>,
L<EVP_sha3_224(3)>,
L<EVP_sm3(3)>,
L<EVP_whirlpool(3)>
L<provider(7)/Fetching algorithms>
=head1 HISTORY
@@ -500,8 +593,8 @@ 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.
The EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), EVP_MD_CTX_set_params()
and EVP_MD_CTX_get_params() functions were added in 3.0.
=head1 COPYRIGHT
doc/man3/EVP_EncryptInit.pod
+112 -9
View File
@@ -2,6 +2,9 @@
=head1 NAME
EVP_CIPHER_fetch,
EVP_CIPHER_up_ref,
EVP_CIPHER_free,
EVP_CIPHER_CTX_new,
EVP_CIPHER_CTX_reset,
EVP_CIPHER_CTX_free,
@@ -25,7 +28,12 @@ EVP_CipherFinal,
EVP_get_cipherbyname,
EVP_get_cipherbynid,
EVP_get_cipherbyobj,
EVP_CIPHER_is_a,
EVP_CIPHER_name,
EVP_CIPHER_provider,
EVP_CIPHER_nid,
EVP_CIPHER_get_params,
EVP_CIPHER_gettable_params,
EVP_CIPHER_block_size,
EVP_CIPHER_key_length,
EVP_CIPHER_iv_length,
@@ -33,10 +41,16 @@ EVP_CIPHER_flags,
EVP_CIPHER_mode,
EVP_CIPHER_type,
EVP_CIPHER_CTX_cipher,
EVP_CIPHER_CTX_name,
EVP_CIPHER_CTX_nid,
EVP_CIPHER_CTX_get_params,
EVP_CIPHER_CTX_gettable_params,
EVP_CIPHER_CTX_set_params,
EVP_CIPHER_CTX_settable_params,
EVP_CIPHER_CTX_block_size,
EVP_CIPHER_CTX_key_length,
EVP_CIPHER_CTX_iv_length,
EVP_CIPHER_CTX_tag_length,
EVP_CIPHER_CTX_get_app_data,
EVP_CIPHER_CTX_set_app_data,
EVP_CIPHER_CTX_type,
@@ -45,7 +59,8 @@ EVP_CIPHER_CTX_mode,
EVP_CIPHER_param_to_asn1,
EVP_CIPHER_asn1_to_param,
EVP_CIPHER_CTX_set_padding,
EVP_enc_null
EVP_enc_null,
EVP_CIPHER_do_all_ex
- EVP cipher routines
=head1 SYNOPSIS
@@ -54,6 +69,10 @@ EVP_enc_null
#include <openssl/evp.h>
EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
const char *properties);
int EVP_CIPHER_up_ref(EVP_CIPHER *cipher);
void EVP_CIPHER_free(EVP_CIPHER *cipher);
EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
@@ -98,6 +117,9 @@ EVP_enc_null
const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);
int EVP_CIPHER_nid(const EVP_CIPHER *e);
int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name);
const char *EVP_CIPHER_name(const EVP_CIPHER *cipher);
const OSSL_PROVIDER *EVP_CIPHER_provider(const EVP_CIPHER *cipher);
int EVP_CIPHER_block_size(const EVP_CIPHER *e);
int EVP_CIPHER_key_length(const EVP_CIPHER *e);
int EVP_CIPHER_iv_length(const EVP_CIPHER *e);
@@ -107,9 +129,18 @@ EVP_enc_null
const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx);
const char *EVP_CIPHER_CTX_name(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]);
int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]);
int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher);
const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(const EVP_CIPHER *cipher);
const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(const EVP_CIPHER *cipher);
int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
int EVP_CIPHER_CTX_tag_length(const EVP_CIPHER_CTX *ctx);
void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);
int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx);
@@ -118,11 +149,31 @@ EVP_enc_null
int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
void EVP_CIPHER_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_CIPHER *cipher, void *arg),
void *arg);
=head1 DESCRIPTION
The EVP cipher routines are a high level interface to certain
symmetric ciphers.
The B<EVP_CIPHER> type is a structure for cipher method implementation.
EVP_CIPHER_fetch() fetches the cipher implementation for the given
B<algorithm> from any provider offering it, within the criteria given
by the B<properties>.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with EVP_CIPHER_free().
EVP_CIPHER_up_ref() increments the reference count for an B<EVP_CIPHER>
structure.
EVP_CIPHER_free() decrements the reference count for the B<EVP_CIPHER>
structure.
If the reference count drops to 0 then the structure is freed.
EVP_CIPHER_CTX_new() creates a cipher context.
EVP_CIPHER_CTX_free() clears all information from a cipher context
@@ -132,16 +183,19 @@ cipher are complete so sensitive information does not remain in
memory.
EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
with cipher B<type> from ENGINE B<impl>. B<ctx> must be created
before calling this function. B<type> is normally supplied
by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
default implementation is used. B<key> is the symmetric key to use
with cipher B<type>. B<type> is typically supplied by a function such
as EVP_aes_256_cbc(), or a value explicitly fetched with
EVP_CIPHER_fetch(). If B<impl> is non-NULL, its implementation of the
cipher B<type> is used if there is one, and if not, the default
implementation is used. B<key> is the symmetric key to use
and B<iv> is the IV to use (if necessary), the actual number of bytes
used for the key and IV depends on the cipher. It is possible to set
all parameters to NULL except B<type> in an initial call and supply
the remaining parameters in subsequent calls, all of which have B<type>
set to NULL. This is done when the default cipher parameters are not
appropriate.
For EVP_CIPH_GCM_MODE the IV will be generated internally if it is not
specified.
EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
writes the encrypted version to B<out>. This function can be called
@@ -215,6 +269,22 @@ decrypting. If the B<pad> parameter is zero then no padding is
performed, the total amount of data encrypted or decrypted must then
be a multiple of the block size or an error will occur.
EVP_CIPHER_get_params() retrieves the requested list of algorithm
B<params> from a B<cipher>.
EVP_CIPHER_CTX_set_params() Sets the list of operation B<params> into a CIPHER
context B<ctx>.
EVP_CIPHER_CTX_get_params() retrieves the requested list of operation
B<params> from CIPHER context B<ctx>.
EVP_CIPHER_gettable_params(), EVP_CIPHER_CTX_gettable_params(), and
EVP_CIPHER_CTX_settable_params() get a constant B<OSSL_PARAM> array
that decribes the retrievable and settable parameters, i.e. parameters
that can be used with EVP_CIPHER_get_params(), EVP_CIPHER_CTX_get_params()
and EVP_CIPHER_CTX_set_params(), respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
@@ -231,6 +301,10 @@ length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
It will return zero if the cipher does not use an IV. The constant
B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
EVP_CIPHER_CTX_tag_length() returns the tag length of a AEAD cipher when passed
a B<EVP_CIPHER_CTX>. It will return zero if the cipher does not support a tag.
It returns a default value if the tag length has not been set.
EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the maximum block
@@ -243,14 +317,26 @@ IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
identifier or does not have ASN1 support this function will return
B<NID_undef>.
EVP_CIPHER_is_a() returns 1 if the given I<cipher> is an implementation of an
algorithm that's identifiable with I<name>, otherwise 0.
EVP_CIPHER_name() and EVP_CIPHER_CTX_name() return the name of the passed
cipher or context.
EVP_CIPHER_provider() returns an B<OSSL_PROVIDER> pointer to the provider
that implements the given B<EVP_CIPHER>.
EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
an B<EVP_CIPHER_CTX> structure.
EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE,
EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE,
EVP_CIPH_WRAP_MODE or EVP_CIPH_OCB_MODE. If the cipher is a stream cipher then
EVP_CIPH_STREAM_CIPHER is returned.
EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. If the cipher is a
stream cipher then EVP_CIPH_STREAM_CIPHER is returned.
EVP_CIPHER_flags() returns any flags associated with the cipher. See
EVP_CIPHER_meth_set_flags() for a list of currently defined flags.
EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
on the passed cipher. This will typically include any parameters and an
@@ -278,8 +364,18 @@ based on the cipher context. The EVP_CIPHER can provide its own random key
generation routine to support keys of a specific form. B<Key> must point to a
buffer at least as big as the value returned by EVP_CIPHER_CTX_key_length().
EVP_CIPHER_do_all_ex() traverses all ciphers implemented by all activated
providers in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.
=head1 RETURN VALUES
EVP_CIPHER_fetch() returns a pointer to a B<EVP_CIPHER> for success
and B<NULL> for failure.
EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise.
EVP_CIPHER_CTX_new() returns a pointer to a newly created
B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
@@ -310,6 +406,9 @@ EVP_CIPHER_CTX_set_padding() always returns 1.
EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
length or zero if the cipher does not use an IV.
EVP_CIPHER_CTX_tag_length() return the tag length or zero if the cipher does not
use a tag.
EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
@@ -335,7 +434,7 @@ Null cipher: does nothing.
=back
=head1 AEAD Interface
=head1 AEAD INTERFACE
The EVP interface for Authenticated Encryption with Associated Data (AEAD)
modes are subtly altered and several additional I<ctrl> operations are supported
@@ -414,7 +513,7 @@ the length of the tag (with the C<tag> parameter set to NULL) when encrypting.
The tag length is often referred to as B<M>. If not set a default value is
used (12 for AES). When decrypting, the tag needs to be set before passing
in data to be decrypted, but as in GCM and OCB mode, it can be set after
passing additional authenticated data (see L<AEAD Interface>).
passing additional authenticated data (see L</AEAD INTERFACE>).
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
@@ -686,6 +785,10 @@ EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
disappeared. EVP_CIPHER_CTX_init() remains as an alias for
EVP_CIPHER_CTX_reset().
The EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(),
EVP_CIPHER_CTX_set_params() and EVP_CIPHER_CTX_get_params() functions
were added in 3.0.
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/EVP_KDF.pod
+265
View File
@@ -0,0 +1,265 @@
=pod
=head1 NAME
EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_provider, EVP_KDF_up_ref,
EVP_KDF_name,
EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_kdf,
EVP_KDF_reset, EVP_KDF_size, EVP_KDF_derive, EVP_KDF_CTX_dup,
EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_ex,
EVP_KDF_get_params, EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params,
EVP_KDF_gettable_params - EVP KDF routines
=head1 SYNOPSIS
#include <openssl/kdf.h>
typedef struct evp_kdf_st EVP_KDF;
typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf);
const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);
void EVP_KDF_reset(EVP_KDF_CTX *ctx);
size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
const char *EVP_KDF_name(const EVP_KDF *kdf);
int EVP_KDF_up_ref(EVP_KDF *kdf);
void EVP_KDF_free(EVP_KDF *kdf);
EVP_KDF *EVP_KDF_fetch(OPENSSL_CTX *libctx, const char *algorithm,
const char *properties);
void EVP_KDF_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_KDF *kdf, void *arg),
void *arg);
int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);
int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf);
const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf);
const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
=head1 DESCRIPTION
The EVP KDF routines are a high level interface to Key Derivation Function
algorithms and should be used instead of algorithm-specific functions.
After creating a B<EVP_KDF_CTX> for the required algorithm using
EVP_KDF_CTX_new(), inputs to the algorithm are supplied
using calls to EVP_KDF_CTX_set_params() before
calling EVP_KDF_derive() to derive the key.
=head2 Types
B<EVP_KDF> is a type that holds the implementation of a KDF.
B<EVP_KDF_CTX> is a context type that holds the algorithm inputs.
=head2 Algorithm implementation fetching
EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
a library context I<libctx> and a set of I<properties>.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with
L<EVP_KDF_free(3)>.
EVP_KDF_up_ref() increments the reference count of an already fetched
KDF.
EVP_KDF_free() frees a fetched algorithm.
NULL is a valid parameter, for which this function is a no-op.
=head2 Context manipulation functions
EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>.
EVP_KDF_CTX_free() frees up the context C<ctx>. If I<ctx> is NULL, nothing
is done.
EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
I<ctx>.
=head2 Computing functions
EVP_KDF_reset() resets the context to the default state as if the context
had just been created.
EVP_KDF_derive() derives C<keylen> bytes of key material and places it in the
I<key> buffer. If the algorithm produces a fixed amount of output then an
error will occur unless the C<keylen> parameter is equal to that output size,
as returned by EVP_KDF_size().
EVP_KDF_get_params() retrieves details about the implementation
I<kdf>.
The set of parameters given with I<params> determine exactly what
parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_KDF_CTX_get_params() retrieves chosen parameters, given the
context I<ctx> and its underlying context.
The set of parameters given with I<params> determine exactly what
parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_KDF_CTX_set_params() passes chosen parameters to the underlying
context, given a context I<ctx>.
The set of parameters given with I<params> determine exactly what
parameters are passed down.
Note that a parameter that is unknown in the underlying context is
simply ignored.
Also, what happens when a needed parameter isn't passed down is
defined by the implementation.
EVP_KDF_gettable_params(), EVP_KDF_CTX_gettable_params() and
EVP_KDF_CTX_settable_params() get a constant B<OSSL_PARAM> array that
decribes the retrievable and settable parameters, i.e. parameters that
can be used with EVP_KDF_get_params(), EVP_KDF_CTX_get_params()
and EVP_KDF_CTX_set_params(), respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=head2 Information functions
EVP_KDF_size() returns the output size if the algorithm produces a fixed amount
of output and B<SIZE_MAX> otherwise. If an error occurs then 0 is returned.
For some algorithms an error may result if input parameters necessary to
calculate a fixed output size have not yet been supplied.
EVP_KDF_name() returns the name of the given KDF implementation.
EVP_KDF_provider() returns the provider that holds the implementation
of the given I<kdf>.
EVP_KDF_do_all_ex() traverses all KDF implemented by all activated
providers in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.
=head1 PARAMETERS
The standard parameter names are:
=over 4
=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string>
Some KDF implementations require a password.
For those KDF implementations that support it, this parameter sets the password.
=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
Some KDF implementations can take a salt.
For those KDF implementations that support it, this parameter sets the salt.
The default value, if any, is implementation dependent.
=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned integer>
Some KDF implementations require an iteration count.
For those KDF implementations that support it, this parameter sets the
iteration count.
The default value, if any, is implementation dependent.
=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<OSSL_KDF_PARAM_MAC> ("mac") <UTF8 string>
=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <UTF8 string>
For KDF implementations that use an underlying computation MAC or
digest, these parameters set what the algorithm should be, and the
engine that implements the algorithm or the properties to fetch it
by if needed.
The value is always the name of the intended engine, algorithm,
or the properties.
Note that not all algorithms may support all possible underlying
implementations.
=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
Some KDF implementations require a key.
For those KDF implementations that support it, this octet string parameter
sets the key.
=item B<OSSL_KDF_PARAM_MAC_SIZE> ("maclen") <unsigned integer>
Used by implementations that use a MAC with a variable output size (KMAC).
For those KDF implementations that support it, this parameter
sets the MAC output size.
The default value, if any, is implementation dependent.
The length must never exceed what can be given with a B<size_t>.
=item B<OSSL_KDF_PARAM_SCRYPT_MAXMEM> ("macmaxmem_byteslen") <unsigned integer>
Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
memory that depends on the load factors provided as input.
For those KDF implementations that support it, this uint64_t parameter sets
an upper limit on the amount of memory that may be consumed while performing
a key derivation.
If this memory usage limit is exceeded because the load factors are chosen
too high, the key derivation will fail.
The default value is implementation dependent.
The memory size must never exceed what can be given with a B<size_t>.
=back
=head1 RETURN VALUES
EVP_MAC_fetch() returns a pointer to a newly fetched B<EVP_KDF>, or
NULL if allocation failed.
EVP_KDF_name() returns the name for the given I<kdf>, if it has been
added to the object database.
EVP_KDF_provider() returns a pointer to the provider for the KDF, or
NULL on error.
EVP_MAC_up_ref() returns 1 on success, 0 on error.
EVP_KDF_CTX_new() returns either the newly allocated
C<EVP_KDF_CTX> structure or C<NULL> if an error occurred.
EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
EVP_KDF_size() returns the output size. C<SIZE_MAX> is returned to indicate
that the algorithm produces a variable amount of output; 0 to indicate failure.
The remaining functions return 1 for success and 0 or a negative value for
failure. In particular, a return value of -2 indicates the operation is not
supported by the KDF algorithm.
=head1 SEE ALSO
L<EVP_KDF-SCRYPT(7)>
L<EVP_KDF-TLS1_PRF(7)>
L<EVP_KDF-PBKDF2(7)>
L<EVP_KDF-HKDF(7)>
L<EVP_KDF-SS(7)>
L<EVP_KDF-SSHKDF(7)>
L<EVP_KDF-X963(7)>
L<EVP_KDF-X942(7)>
=head1 HISTORY
This functionality was added to 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/man3/EVP_KDF_CTX.pod
-296
View File
@@ -1,296 +0,0 @@
=pod
=head1 NAME
EVP_KDF, EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_new_id, EVP_KDF_CTX_free,
EVP_KDF_CTX_kdf, EVP_KDF_reset, EVP_KDF_ctrl, EVP_KDF_vctrl, EVP_KDF_ctrl_str,
EVP_KDF_size, EVP_KDF_derive, EVP_KDF_nid, EVP_KDF_name,
EVP_get_kdfbyname, EVP_get_kdfbynid, EVP_get_kdfbyobj - EVP KDF routines
=head1 SYNOPSIS
#include <openssl/kdf.h>
typedef struct evp_kdf_st EVP_KDF;
typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf);
EVP_KDF_CTX *EVP_KDF_CTX_new_id(int nid);
const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
void EVP_KDF_reset(EVP_KDF_CTX *ctx);
int EVP_KDF_ctrl(EVP_KDF_CTX *ctx, int cmd, ...);
int EVP_KDF_vctrl(EVP_KDF_CTX *ctx, int cmd, va_list args);
int EVP_KDF_ctrl_str(EVP_KDF_CTX *ctx, const char *type, const char *value);
size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
int EVP_KDF_nid(const EVP_KDF *kdf);
const char *EVP_KDF_name(const EVP_KDF *kdf);
const EVP_KDF *EVP_get_kdfbyname(const char *name);
const EVP_KDF *EVP_get_kdfbynid(int nid);
const EVP_KDF *EVP_get_kdfbyobj(const ASN1_OBJECT *o);
=head1 DESCRIPTION
The EVP KDF routines are a high level interface to Key Derivation Function
algorithms and should be used instead of algorithm-specific functions.
After creating a C<EVP_KDF_CTX> for the required algorithm using either
EVP_KDF_CTX_new() or EVP_KDF_CTX_new_id(), inputs to the algorithm are supplied
using calls to EVP_KDF_ctrl(), EVP_KDF_vctrl() or EVP_KDF_ctrl_str() before
calling EVP_KDF_derive() to derive the key.
=head2 Types
B<EVP_KDF> is a type that holds the implementation of a KDF.
B<EVP_KDF_CTX> is a context type that holds the algorithm inputs.
=head2 Context manipulation functions
EVP_KDF_CTX_new() creates a new context for the KDF type C<kdf>.
EVP_KDF_CTX_new_id() creates a new context for the numerical KDF identity C<nid>.
EVP_KDF_CTX_free() frees up the context C<ctx>. If C<ctx> is C<NULL>, nothing
is done.
EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
C<ctx>.
=head2 Computing functions
EVP_KDF_reset() resets the context to the default state as if the context
had just been created.
EVP_KDF_ctrl() is used to provide inputs to the KDF algorithm prior to
EVP_KDF_derive() being called. The inputs that may be provided will vary
depending on the KDF algorithm or its implementation. This functions takes
variable arguments, the exact expected arguments depend on C<cmd>.
See L</CONTROLS> below for a description of standard controls.
EVP_KDF_vctrl() is the variant of EVP_KDF_ctrl() that takes a C<va_list>
argument instead of variadic arguments.
EVP_KDF_ctrl_str() allows an application to send an algorithm specific control
operation to a context C<ctx> in string form. This is intended to be used for
options specified on the command line or in text files.
EVP_KDF_derive() derives C<keylen> bytes of key material and places it in the
C<key> buffer. If the algorithm produces a fixed amount of output then an
error will occur unless the C<keylen> parameter is equal to that output size,
as returned by EVP_KDF_size().
=head2 Information functions
EVP_KDF_size() returns the output size if the algorithm produces a fixed amount
of output and C<SIZE_MAX> otherwise. If an error occurs then 0 is returned.
For some algorithms an error may result if input parameters necessary to
calculate a fixed output size have not yet been supplied.
EVP_KDF_nid() returns the numeric identity of the given KDF implementation.
EVP_KDF_name() returns the name of the given KDF implementation.
=head2 Object database functions
EVP_get_kdfbyname() fetches a KDF implementation from the object
database by name.
EVP_get_kdfbynid() fetches a KDF implementation from the object
database by numeric identity.
EVP_get_kdfbyobj() fetches a KDF implementation from the object
database by ASN.1 OBJECT (i.e. an encoded OID).
=head1 CONTROLS
The standard controls are:
=over 4
=item B<EVP_KDF_CTRL_SET_PASS>
This control expects two arguments: C<unsigned char *pass>, C<size_t passlen>
Some KDF implementations require a password. For those KDF implementations
that support it, this control sets the password.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "pass"
The value string is used as is.
=item "hexpass"
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_SALT>
This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen>
Some KDF implementations can take a salt. For those KDF implementations that
support it, this control sets the salt.
The default value, if any, is implementation dependent.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "salt"
The value string is used as is.
=item "hexsalt"
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_ITER>
This control expects one argument: C<int iter>
Some KDF implementations require an iteration count. For those KDF implementations that support it, this control sets the iteration count.
The default value, if any, is implementation dependent.
EVP_KDF_ctrl_str() type string: "iter"
The value string is expected to be a decimal number.
=item B<EVP_KDF_CTRL_SET_MAC>
This control expects one argument: C<EVP_MAC *mac>
Some KDF implementations use a MAC as an underlying computation
algorithm, this control sets what the MAC algorithm should be.
EVP_KDF_ctrl_str() type string: "mac"
The value string is expected to be the name of a MAC.
=item B<EVP_KDF_CTRL_SET_MD>
This control expects one argument: C<EVP_MD *md>
For MAC implementations that use a message digest as an underlying computation
algorithm, this control sets what the digest algorithm should be.
EVP_KDF_ctrl_str() type string: "digest"
The value string is expected to be the name of a digest.
=item B<EVP_KDF_CTRL_SET_KEY>
This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
Some KDF implementations require a key. For those KDF implementations that
support it, this control sets the key.
EVP_KDF_ctrl_str() takes two type strings for this control:
=over 4
=item "key"
The value string is used as is.
=item "hexkey"
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_MAC_SIZE>
This control expects one argument: C<size_t size>
Used by implementations that use a MAC with a variable output size (KMAC). For
those KDF implementations that support it, this control sets the MAC output size.
The default value, if any, is implementation dependent.
EVP_KDF_ctrl_str() type string: "outlen"
The value string is expected to be a decimal number.
=item B<EVP_KDF_CTRL_SET_MAXMEM_BYTES>
This control expects one argument: C<uint64_t maxmem_bytes>
Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
memory that depends on the load factors provided as input. For those KDF
implementations that support it, this control sets an upper limit on the amount
of memory that may be consumed while performing a key derivation. If this
memory usage limit is exceeded because the load factors are chosen too high,
the key derivation will fail.
The default value is implementation dependent.
EVP_KDF_ctrl_str() type string: "maxmem_bytes"
The value string is expected to be a decimal number.
=back
=head1 RETURN VALUES
EVP_KDF_CTX_new() and EVP_KDF_CTX_new_id() return either the newly allocated
C<EVP_KDF_CTX> structure or C<NULL> if an error occurred.
EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
EVP_KDF_size() returns the output size. C<SIZE_MAX> is returned to indicate
that the algorithm produces a variable amount of output; 0 to indicate failure.
EVP_KDF_nid() returns the numeric identity for the given C<kdf>.
EVP_KDF_name() returns the name for the given C<kdf>, if it has been
added to the object database.
EVP_add_kdf() returns 1 if the given C<kdf> was successfully added to
the object database, otherwise 0.
EVP_get_kdfbyname(), EVP_get_kdfbynid() and EVP_get_kdfbyobj() return
the requested KDF implementation, if it exists in the object database,
otherwise B<NULL>.
The remaining functions return 1 for success and 0 or a negative value for
failure. In particular, a return value of -2 indicates the operation is not
supported by the KDF algorithm.
=head1 SEE ALSO
L<EVP_KDF_SCRYPT(7)>
L<EVP_KDF_TLS1_PRF(7)>
L<EVP_KDF_PBKDF2(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
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/man3/EVP_KEYEXCH_free.pod
+61
View File
@@ -0,0 +1,61 @@
=pod
=head1 NAME
EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, EVP_KEYEXCH_provider
- Functions to manage EVP_KEYEXCH algorithm objects
=head1 SYNOPSIS
#include <openssl/evp.h>
EVP_KEYEXCH *EVP_KEYEXCH_fetch(OPENSSL_CTX *ctx, const char *algorithm,
const char *properties);
void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange);
int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange);
OSSL_PROVIDER *EVP_KEYEXCH_provider(const EVP_KEYEXCH *exchange);
=head1 DESCRIPTION
EVP_KEYEXCH_fetch() fetches the key exchange implementation for the given
B<algorithm> from any provider offering it, within the criteria given
by the B<properties>.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with EVP_KEYEXCH_free().
EVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH>
structure. Typically this structure will have been obtained from an earlier call
to EVP_KEYEXCH_fetch(). If the reference count drops to 0 then the
structure is freed.
EVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH>
structure.
EVP_KEYEXCH_provider() returns the provider that I<exchange> was fetched from.
=head1 RETURN VALUES
EVP_KEYEXCH_fetch() returns a pointer to a B<EVP_KEYEXCH> for success
or B<NULL> for failure.
EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise.
=head1 SEE ALSO
L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
=head1 HISTORY
The 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
doc/man3/EVP_KEYMGMT.pod
+84
View File
@@ -0,0 +1,84 @@
=pod
=head1 NAME
EVP_KEYMGMT,
EVP_KEYMGMT_fetch,
EVP_KEYMGMT_up_ref,
EVP_KEYMGMT_free,
EVP_KEYMGMT_provider
- EVP key management routines
=head1 SYNOPSIS
#include <openssl/evp.h>
typedef struct evp_keymgmt_st EVP_KEYMGMT;
EVP_KEYMGMT *EVP_KEYMGMT_fetch(OPENSSL_CTX *ctx, const char *algorithm,
const char *properties);
int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
const OSSL_PROVIDER *EVP_KEYMGMT_provider(const EVP_KEYMGMT *keymgmt);
=head1 DESCRIPTION
B<EVP_KEYMGMT> is a method object that represents key management
implementations for different cryptographic algorithms.
This method object provides functionality to have providers import key
material from the outside, as well as export key material to the
outside.
Most of the functionality can only be used internally and has no
public interface, this object is simply passed into other functions
when needed.
EVP_KEYMGMT_fetch() looks for an algorithm within the provider that
has been loaded into the B<OPENSSL_CTX> given by I<ctx>, having the
name given by I<algorithm> and the properties given by I<properties>.
EVP_KEYMGMT_up_ref() increments the reference count for the given
B<EVP_KEYMGMT> I<keymgmt>.
EVP_KEYMGMT_free() decrements the reference count for the given
B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it.
EVP_KEYMGMT_provider() returns the provider that has this particular
implementation.
=head1 NOTES
EVP_KEYMGMT_fetch() may be called implicitly by other fetching
functions, using the same library context and properties.
Any other API that uses keys will typically do this.
=head1 RETURN VALUES
EVP_KEYMGMT_fetch() returns a pointer to the key management
implementation represented by an EVP_KEYMGMT object, or NULL on
error.
EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error.
EVP_KEYMGMT_free() doesn't return any value.
EVP_KEYMGMT_provider() returns a pointer to a provider object, or NULL
on error.
=head1 SEE ALSO
L<EVP_MD_fetch(3)>, L<OPENSSL_CTX(3)>
=head1 HISTORY
The 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
doc/man3/EVP_MAC.pod
+177 -155
View File
@@ -2,11 +2,14 @@
=head1 NAME
EVP_MAC, EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_new_id, EVP_MAC_CTX_free,
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
EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free,
EVP_MAC_is_a, EVP_MAC_name,
EVP_MAC_provider, EVP_MAC_get_params, EVP_MAC_gettable_params,
EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
EVP_MAC_size, EVP_MAC_init, EVP_MAC_update, EVP_MAC_final,
EVP_MAC_CTX_gettable_params, EVP_MAC_CTX_settable_params,
EVP_MAC_do_all_ex - EVP MAC routines
=head1 SYNOPSIS
@@ -15,25 +18,35 @@ EVP_get_macbyname, EVP_get_macbynid, EVP_get_macbyobj - EVP MAC routines
typedef struct evp_mac_st EVP_MAC;
typedef struct evp_mac_ctx_st EVP_MAC_CTX;
EVP_MAC_CTX *EVP_MAC_CTX_new(const EVP_MAC *mac);
EVP_MAC_CTX *EVP_MAC_CTX_new_id(int nid);
EVP_MAC *EVP_MAC_fetch(OPENSSL_CTX *libctx, const char *algorithm,
const char *properties);
int EVP_MAC_up_ref(EVP_MAC *mac);
void EVP_MAC_free(EVP_MAC *mac);
int EVP_MAC_is_a(const EVP_MAC *mac, const char *name);
const char *EVP_MAC_name(const EVP_MAC *mac);
const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
EVP_MAC_CTX *EVP_MAC_CTX_new(EVP_MAC *mac);
void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);
const EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
int EVP_MAC_CTX_get_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]);
int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
int EVP_MAC_init(EVP_MAC_CTX *ctx);
int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
int EVP_MAC_final(EVP_MAC_CTX *ctx, unsigned char *out, size_t *poutlen);
int EVP_MAC_ctrl(EVP_MAC_CTX *ctx, int cmd, ...);
int EVP_MAC_vctrl(EVP_MAC_CTX *ctx, int cmd, va_list args);
int EVP_MAC_ctrl_str(EVP_MAC_CTX *ctx, const char *type, const char *value);
int EVP_MAC_str2ctrl(EVP_MAC_CTX *ctx, int cmd, const char *value);
int EVP_MAC_hex2ctrl(EVP_MAC_CTX *ctx, int cmd, const char *value);
int EVP_MAC_nid(const EVP_MAC *mac);
const char *EVP_MAC_name(const EVP_MAC *mac);
const EVP_MAC *EVP_get_macbyname(const char *name);
const EVP_MAC *EVP_get_macbynid(int nid);
const EVP_MAC *EVP_get_macbyobj(const ASN1_OBJECT *o);
int EVP_MAC_final(EVP_MAC_CTX *ctx,
unsigned char *out, size_t *outl, size_t outsize);
const OSSL_PARAM *EVP_MAC_gettable_params(const EVP_MAC *mac);
const OSSL_PARAM *EVP_MAC_CTX_gettable_params(const EVP_MAC *mac);
const OSSL_PARAM *EVP_MAC_CTX_settable_params(const EVP_MAC *mac);
void EVP_MAC_do_all_ex(OPENSSL_CTX *libctx,
void (*fn)(EVP_MAC *mac, void *arg),
void *arg);
=head1 DESCRIPTION
@@ -60,23 +73,36 @@ B<EVP_MAC_CTX> is a context type that holds internal MAC information
as well as a reference to a computation context, for those MACs that
rely on an underlying computation algorithm.
=head2 Algorithm implementation fetching
EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
a library context I<libctx> and a set of I<properties>.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with
L<EVP_MAC_free(3)>.
EVP_MAC_up_ref() increments the reference count of an already fetched
MAC.
EVP_MAC_free() frees a fetched algorithm.
NULL is a valid parameter, for which this function is a no-op.
=head2 Context manipulation functions
EVP_MAC_CTX_new() creates a new context for the MAC type C<mac>.
EVP_MAC_CTX_new_id() creates a new context for the numerical MAC
identity <nid>.
EVP_MAC_CTX_new() creates a new context for the MAC type I<mac>.
The created context can then be used with most other functions
described here.
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.
NULL is a valid parameter, for which this function is a no-op.
EVP_MAC_CTX_dup() duplicates the C<src> context and returns a newly allocated
EVP_MAC_CTX_dup() duplicates the I<src> context and returns a newly allocated
context.
EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
C<ctx>.
I<ctx>.
=head2 Computing functions
@@ -85,180 +111,180 @@ through diverse controls.
This should be called before calling EVP_MAC_update() and
EVP_MAC_final().
EVP_MAC_update() adds C<datalen> bytes from C<data> to the MAC input.
EVP_MAC_update() adds I<datalen> bytes from I<data> to the MAC input.
EVP_MAC_final() does the final computation and stores the result in
the memory pointed at by C<out>, and sets its size in the B<size_t>
the C<poutlen> points at.
If C<out> is B<NULL>, then no computation is made.
the memory pointed at by I<out> of size I<outsize>, and sets the number
of bytes written in I<*outl> at.
If I<out> is B<NULL> or I<outsize> is too small, then no computation
is made.
To figure out what the output length will be and allocate space for it
dynamically, simply call with C<out> being B<NULL> and C<poutlen>
dynamically, simply call with I<out> being B<NULL> and I<outl>
pointing at a valid location, then allocate space and make a second
call with C<out> pointing at the allocated space.
call with I<out> pointing at the allocated space.
EVP_MAC_ctrl() is used to manipulate or get information on aspects of
the MAC which may vary depending on the MAC algorithm or its
implementation.
This includes the MAC key, and for MACs that use other algorithms to
do their computation, this is also the way to tell it which one to
use.
This functions takes variable arguments, the exact expected arguments
depend on C<cmd>.
EVP_MAC_ctrl() can be called both before and after EVP_MAC_init(), but
the effect will depend on what control is being use.
See L</CONTROLS> below for a description of standard controls.
EVP_MAC_get_params() retrieves details about the implementation
I<mac>.
The set of parameters given with I<params> determine exactly what
parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_MAC_vctrl() is the variant of EVP_MAC_ctrl() that takes a
C<va_list> argument instead of variadic arguments.
EVP_MAC_CTX_get_params() retrieves chosen parameters, given the
context I<ctx> and its underlying context.
The set of parameters given with I<params> determine exactly what
parameters should be retrieved.
Note that a parameter that is unknown in the underlying context is
simply ignored.
EVP_MAC_ctrl_str() is an alternative to EVP_MAC_ctrl() to control the
MAC implementation as E<lt> C<type>, C<value> E<gt> pairs.
The MAC implementation documentation should specify what control type
strings are accepted.
EVP_MAC_CTX_set_params() passes chosen parameters to the underlying
context, given a context I<ctx>.
The set of parameters given with I<params> determine exactly what
parameters are passed down.
Note that a parameter that is unknown in the underlying context is
simply ignored.
Also, what happens when a needed parameter isn't passed down is
defined by the implementation.
EVP_MAC_str2ctrl() and EVP_MAC_hex2ctrl() are helper functions to
control the MAC implementation with raw strings or with strings
containing hexadecimal numbers.
The latter are decoded into bitstrings that are sent on to
EVP_MAC_ctrl().
EVP_MAC_gettable_params(), EVP_MAC_CTX_gettable_params() and
EVP_MAC_CTX_settable_params() get a constant B<OSSL_PARAM> array that
decribes the retrievable and settable parameters, i.e. parameters that
can be used with EVP_MAC_get_params(), EVP_MAC_CTX_get_params()
and EVP_MAC_CTX_set_params(), respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=head2 Information functions
EVP_MAC_size() returns the MAC output size for the given context.
EVP_MAC_nid() returns the numeric identity of the given MAC implementation.
EVP_MAC_name() returns the name of the given MAC implementation.
=head2 Object database functions
EVP_MAC_is_a() checks if the given I<mac> is an implementation of an
algorithm that's identifiable with I<name>.
EVP_get_macbyname() fetches a MAC implementation from the object
database by name.
EVP_MAC_provider() returns the provider that holds the implementation
of the given I<mac>.
EVP_get_macbynid() fetches a MAC implementation from the object
database by numeric identity.
EVP_MAC_do_all_ex() traverses all MAC implemented by all activated
providers in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.
EVP_get_macbyobj() fetches a MAC implementation from the object
database by ASN.1 OBJECT (i.e. an encoded OID).
=head1 PARAMETERS
=head1 CONTROLS
Parameters are identified by name as strings, and have an expected
data type and maximum size.
OpenSSL has a set of macros for parameter names it expects to see in
its own MAC implementations.
Here, we show all three, the OpenSSL macro for the parameter name, the
name in string form, and a type description.
The standard controls are:
The standard parameter names are:
=over 4
=item B<EVP_MAC_CTRL_SET_KEY>
=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
These will set the MAC key from the given string of the given length.
The string may be any bitstring, and can contain NUL bytes.
Its value is the MAC key as an array of bytes.
For MACs that use an underlying computation algorithm, the algorithm
I<must> be set first, see B<EVP_MAC_CTRL_SET_ENGINE>,
B<EVP_MAC_CTRL_SET_MD> and B<EVP_MAC_CTRL_SET_CIPHER> below.
must be set first, see parameter names "algorithm" below.
=item B<EVP_MAC_CTRL_SET_IV>
=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
Some MAC implementations require an IV, this parameter sets the IV.
Some MAC implementations require an IV, this control sets the IV.
=item B<EVP_MAC_CTRL_SET_CUSTOM>
This control expects two arguments: C<unsigned char *custom>, C<size_t customlen>
=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
this control sets the Customization String. The default value is "".
this parameter sets the Customization String. The default value is the
empty string.
=item B<EVP_MAC_CTRL_SET_SALT>
This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen>
=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string>
This option is used by BLAKE2 MAC.
=item B<EVP_MAC_CTRL_SET_XOF>
=item B<OSSL_MAC_PARAM_XOF> ("xof") <integer>
This control expects one argument: C<int xof>
It's a simple flag, the value 0 or 1 are expected.
This option is used by KMAC.
=item B<EVP_MAC_CTRL_SET_FLAGS>
This control expects one argument: C<unsigned long flags>
=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <integer>
These will set the MAC flags to the given numbers.
Some MACs do not support this option.
=item B<EVP_MAC_CTRL_SET_ENGINE>
=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <UTF8 string>
=item B<EVP_MAC_CTRL_SET_MD>
=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
=item B<EVP_MAC_CTRL_SET_CIPHER>
=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string>
For MAC implementations that use an underlying computation algorithm,
these controls set what the algorithm should be, and the engine that
implements the algorithm if needed.
=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string>
Note that not all algorithms may support all digests. HMAC does not support
variable output length digests such as SHAKE128 or SHAKE256.
For MAC implementations that use an underlying computation cipher or
digest, these parameters set what the algorithm should be, and the
engine that implements the algorithm or the properties to fetch it
by if needed.
B<EVP_MAC_CTRL_SET_ENGINE> takes one argument: C<ENGINE *>
The value is always the name of the intended engine, algorithm,
or the properties.
B<EVP_MAC_CTRL_SET_MD> takes one argument: C<EVP_MD *>
Note that not all algorithms may support all digests.
HMAC does not support variable output length digests such as SHAKE128
or SHAKE256.
B<EVP_MAC_CTRL_SET_CIPHER> takes one argument: C<EVP_CIPHER *>
=item B<EVP_MAC_CTRL_SET_SIZE>
=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
For MAC implementations that support it, set the output size that
EVP_MAC_final() should produce.
The allowed sizes vary between MAC implementations.
The allowed sizes vary between MAC implementations, but must never exceed
what can be given with a B<size_t>.
=back
All these control should be used before the calls to any of
All these parameters should be used before the calls to any of
EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
computation.
Anything else may give undefined results.
=head1 NOTES
EVP_get_macbynid(), EVP_get_macbyobj() and EVP_MAC_name() are
implemented as a macro.
=head1 RETURN VALUES
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_fetch() returns a pointer to a newly fetched EVP_MAC, or
NULL if allocation failed.
EVP_MAC_up_ref() returns 1 on success, 0 on error.
EVP_MAC_free() returns nothing at all.
EVP_MAC_name() returns the name of the MAC, or NULL if NULL was
passed.
EVP_MAC_is_a() returns 1 if the given method can be identified with
the given name, otherwise 0.
EVP_MAC_provider() returns a pointer to the provider for the MAC, or
NULL on error.
EVP_MAC_CTX_new() 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_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0 on error.
EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() 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
error.
In particular, the value -2 indicates that the given control type
isn't supported by the MAC implementation.
EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0
on error.
EVP_MAC_size() returns the expected output size, or 0 if it isn't
set.
If it isn't set, a call to EVP_MAC_init() should get it set.
EVP_MAC_nid() returns the numeric identity for the given C<mac>.
EVP_MAC_do_all_ex() returns nothing at all.
EVP_MAC_name() returns the name for the given C<mac>, if it has been
added to the object database.
EVP_add_mac() returns 1 if the given C<mac> was successfully added to
the object database, otherwise 0.
EVP_get_macbyname(), EVP_get_macbynid() and EVP_get_macbyobj() return
the request MAC implementation, if it exists in the object database,
otherwise B<NULL>.
=head1 EXAMPLE
=head1 EXAMPLES
#include <stdlib.h>
#include <stdio.h>
@@ -268,29 +294,12 @@ otherwise B<NULL>.
#include <openssl/evp.h>
#include <openssl/err.h>
int ctrl_ign_unsupported(EVP_MAC_CTX *ctx, int cmd, ...)
{
va_list args;
int rv;
va_start(args, cmd);
rv = EVP_MAC_vctrl(ctx, cmd, args);
va_end(args);
if (rv == -2)
rv = 1; /* Ignore unsupported, pretend it worked fine */
return rv;
}
#include <openssl/params.h>
int main() {
const EVP_MAC *mac =
EVP_get_macbyname(getenv("MY_MAC"));
const EVP_CIPHER *cipher =
EVP_get_cipherbyname(getenv("MY_MAC_CIPHER"));
const EVP_MD *digest =
EVP_get_digestbyname(getenv("MY_MAC_DIGEST"));
EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv("MY_MAC"), NULL);
const char *cipher = getenv("MY_MAC_CIPHER");
const char *digest = getenv("MY_MAC_DIGEST");
const char *key = getenv("MY_KEY");
EVP_MAC_CTX *ctx = NULL;
@@ -300,14 +309,23 @@ otherwise B<NULL>.
size_t i;
OSSL_PARAM params[4];
size_t params_n = 0;
if (cipher != NULL)
params[params_n++] =
OSSL_PARAM_construct_utf8_string("cipher", cipher, 0, NULL);
if (digest != NULL)
params[params_n++] =
OSSL_PARAM_construct_utf8_string("digest", digest, 0, NULL);
params[params_n++] =
OSSL_PARAM_construct_octet_string("key", key, strlen(key), NULL);
params[params_n] = OSSL_PARAM_construct_end();
if (mac == NULL
|| key == NULL
|| (ctx = EVP_MAC_CTX_new(mac)) == NULL
|| (cipher != NULL
&& !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_CIPHER, cipher))
|| (digest != NULL
&& !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_MD, digest))
|| EVP_MAC_ctrl(ctx, EVP_MAC_CTRL_SET_KEY, key, strlen(key)) <= 0)
|| EVP_MAC_CTX_set_params(ctx, params) <= 0)
goto err;
if (!EVP_MAC_init(ctx))
@@ -327,10 +345,12 @@ otherwise B<NULL>.
printf("\n");
EVP_MAC_CTX_free(ctx);
EVP_MAC_free(mac);
exit(0);
err:
EVP_MAC_CTX_free(ctx);
EVP_MAC_free(mac);
fprintf(stderr, "Something went wrong\n");
ERR_print_errors_fp(stderr);
exit (1);
@@ -348,6 +368,8 @@ F<./foo>)
=head1 SEE ALSO
L<property(7)>
L<OSSL_PARAM(3)>,
L<EVP_MAC_BLAKE2(7)>,
L<EVP_MAC_CMAC(7)>,
L<EVP_MAC_GMAC(7)>,
@@ -358,11 +380,11 @@ L<EVP_MAC_POLY1305(7)>
=head1 HISTORY
These functions were added in OpenSSL 3.0.0.
These functions were added in OpenSSL 3.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/man3/EVP_MD_fetch.pod
-237
View File
@@ -1,237 +0,0 @@
=pod
=head1 NAME
EVP_MD_fetch, EVP_CIPHER_fetch
- Functions to explicitly fetch algorithm implementations
=head1 SYNOPSIS
#include <openssl/evp.h>
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
Cryptographic algorithms are represented by different OpenSSL objects depending
on what type of algorithm it is. The following cryptographic algorithm types are
supported.
=over 4
=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_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 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 algorithm
object.
See L<EVP_MD_meth_new(3)> and L<EVP_CIPHER_meth_new(3)> for details.
=back
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 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 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
look for an algorithm implementation. Properties are given as a comma delimited
string of name value pairs. In order for an implementation to match, all the
properties in the query string must match those defined for that implementation.
Any properties defined by an implementation but not given in the query string
are ignored. All algorithm implementations in the default provider have the
property "default=yes". All algorithm implementations in the legacy provider have
the property "legacy=yes". All algorithm implementations in the FIPS provider
have the property "fips=yes". In the event that more than one implementation
of the given algorithm name matches the specified properties then an unspecified
one of those implementations may be returned. The B<properties> parameter may be
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_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 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.
EVP_MD_CTX_md does not increment the reference count and so the returned EVP_MD
object may not be accessible beyond the lifetime of the EVP_MD_CTX it is
associated with.
=head1 RETURN VALUES
EVP_MD_fetch() returns a pointer to the algorithm implementation represented by
an EVP_MD object, or NULL on error.
=head1 EXAMPLES
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:
EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
...
EVP_MD_meth_free(md);
Fetch an implementation of SHA256 that is not from the default provider in the
default context:
EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
...
EVP_MD_meth_free(md);
Fetch an implementation of SHA256 from the default provider in the specified
context:
EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
...
EVP_MD_meth_free(md);
Load the legacy provider into the default context and then fetch an
implementation of whirlpool from it:
/* This only needs to be done once - usually at application start up */
OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
...
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 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:
/* This only needs to be done once - usually at application start up */
OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
...
EVP_MD_meth_free(md_whirlpool);
EVP_MD_meth_free(md_sha256);
=head1 SEE ALSO
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
The 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
doc/man3/EVP_MD_meth_new.pod
+10 -14
View File
@@ -2,8 +2,8 @@
=head1 NAME
EVP_MD_meth_dup,
EVP_MD_meth_new, EVP_MD_meth_free, EVP_MD_meth_set_input_blocksize,
EVP_MD_meth_new, EVP_MD_meth_dup, EVP_MD_meth_free,
EVP_MD_meth_set_input_blocksize,
EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize,
EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update,
EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup,
@@ -11,8 +11,8 @@ 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_up_ref
- Routines to build up EVP_MD methods
EVP_MD_meth_get_ctrl
- Routines to build up legacy EVP_MD methods
=head1 SYNOPSIS
@@ -54,16 +54,14 @@ EVP_MD_meth_get_ctrl, EVP_MD_up_ref
int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
int p1, void *p2);
int EVP_MD_up_ref(EVP_MD *md);
=head1 DESCRIPTION
The B<EVP_MD> type is a structure for digest method implementation.
It can also have associated public/private key signing and verifying
routines.
EVP_MD_meth_new() creates a new B<EVP_MD> structure. Note that B<EVP_MD>
structures are reference counted.
EVP_MD_meth_new() creates a new B<EVP_MD> structure.
These B<EVP_MD> structures are reference counted.
EVP_MD_meth_dup() creates a copy of B<md>.
@@ -162,8 +160,6 @@ 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_up_ref() increments the reference count for an EVP_MD structure.
=head1 RETURN VALUES
EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly
@@ -175,8 +171,6 @@ indicated sizes or flags.
All other EVP_CIPHER_meth_get_*() functions return pointers to their
respective B<md> function.
EVP_MD_up_ref() returns 1 for success or 0 otherwise.
=head1 SEE ALSO
L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
@@ -184,8 +178,10 @@ 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_up_ref() was added in OpenSSL 3.0. All other functions described
here were added in OpenSSL 1.1.
1.1.
The functions described here were added in OpenSSL 1.1.
The B<EVP_MD> structure created with these functions became reference
counted in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/EVP_PKEY_ASN1_METHOD.pod
+10
View File
@@ -361,6 +361,16 @@ public key data for an EVP_PKEY. They MUST return 0 on error, or 1 on success.
They are called by L<EVP_PKEY_new_raw_private_key(3)>, and
L<EVP_PKEY_new_raw_public_key(3)> respectively.
size_t (*dirty) (const EVP_PKEY *pk);
void *(*export_to) (const EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
dirty_cnt() returns the internal key's dirty count.
This can be used to synchronise different copies of the same keys.
The export_to() method exports the key material from the given key to
a provider, through the L<EVP_KEYMGMT(3)> interface, if that provider
supports importing key material.
=head2 Functions
EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD>
doc/man3/EVP_PKEY_CTX_ctrl.pod
+74 -10
View File
@@ -2,6 +2,10 @@
=head1 NAME
EVP_PKEY_CTX_get_params,
EVP_PKEY_CTX_gettable_params,
EVP_PKEY_CTX_set_params,
EVP_PKEY_CTX_settable_params,
EVP_PKEY_CTX_ctrl,
EVP_PKEY_CTX_ctrl_str,
EVP_PKEY_CTX_ctrl_uint64,
@@ -62,6 +66,11 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
#include <openssl/evp.h>
int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
int cmd, int p1, void *p2);
int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
@@ -141,6 +150,50 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
=head1 DESCRIPTION
The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and
send arbitrary parameters from and to the algorithm implementation respectively.
Not all parameters may be supported by all providers.
See L<OSSL_PROVIDER(3)> for more information on providers.
See L<OSSL_PARAM(3)> for more information on parameters.
These functions must only be called after the EVP_PKEY_CTX has been initialised
for use in an operation (for example by L<EVP_PKEY_sign_init_ex(3)>,
L<EVP_PKEY_derive_init_ex(3)> or other similar functions).
The parameters currently supported by the default provider are:
=over 4
=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <uint>
Sets the DH padding mode.
If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the shared secret is padded with zeroes
up to the size of the DH prime B<p>.
If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
performed.
=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <utf8 string>
Gets and sets the name of the digest algorithm used for the input to the
signature functions.
=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <size_t>
Gets and sets the output size of the digest algorithm used for the input to the
signature functions.
The internal algorithm that supports this parameter is DSA.
=back
EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a
constant B<OSSL_PARAM> array that decribes the gettable and
settable parameters for the current algorithm implementation, i.e. parameters
that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
respectively.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
These functions must only be called after the EVP_PKEY_CTX has been initialised
for use in an operation (for example by L<EVP_PKEY_sign_init_ex(3)>,
L<EVP_PKEY_derive_init_ex(3)> or other similar functions).
The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter
B<optype> is a mask indicating which operations the control can be applied to.
@@ -166,13 +219,13 @@ B<pkeyutl>, B<genpkey> and B<req> commands.
The function EVP_PKEY_CTX_md() sends a message digest control operation
to the context B<ctx>. The message digest is specified by its name B<md>.
All the remaining "functions" are implemented as macros.
The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used
The EVP_PKEY_CTX_set_signature_md() function sets the message digest type used
in a signature. It can be used in the RSA, DSA and ECDSA algorithms.
The EVP_PKEY_CTX_get_signature_md() macro gets the message digest type used in a
signature. It can be used in the RSA, DSA and ECDSA algorithms.
The EVP_PKEY_CTX_get_signature_md() function gets the message digest type used
in a signature. It can be used in the RSA, DSA and ECDSA algorithms.
All the remaining "functions" are implemented as macros.
Key generation typically involves setting up parameters to be used and
generating the private and public key data. Some algorithm implementations
@@ -290,8 +343,9 @@ The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH
parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
The default is 0.
The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is
1 the shared secret is padded with zeroes up to the size of the DH prime B<p>.
The EVP_PKEY_CTX_set_dh_pad() function sets the DH padding mode.
If B<pad> is 1 the shared secret is padded with zeroes up to the size of the DH
prime B<p>.
If B<pad> is zero (the default) then no padding is performed.
EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to
@@ -437,9 +491,15 @@ allocate adequate memory space for the B<id> before calling EVP_PKEY_CTX_get1_id
=head1 RETURN VALUES
EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
error.
It may also return NULL if there are no settable parameters available.
EVP_PKEY_CTX_set_signature_md(), EVP_PKEY_CTX_set_dh_pad(), EVP_PKEY_CTX_ctrl()
and its macros return a positive value for success and 0 or a negative value for
failure. In particular a return value of -2 indicates the operation is not
supported by the public key algorithm.
=head1 SEE ALSO
@@ -458,6 +518,10 @@ The
EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len()
macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0.
EVP_PKEY_CTX_get_signature_md(), EVP_PKEY_CTX_set_signature_md() and
EVP_PKEY_CTX_set_dh_pad() were macros in OpenSSL 1.1.1 and below. From OpenSSL
3.0 they are functions.
=head1 COPYRIGHT
Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
+1 -1
View File
@@ -121,7 +121,7 @@ All these functions return 1 for success and 0 or a negative value for failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret",
salt value "salt" and info value "label":
doc/man3/EVP_PKEY_CTX_set_scrypt_N.pod
+5 -2
View File
@@ -29,7 +29,7 @@ EVP_PKEY_CTX_set_scrypt_maxmem_bytes
These functions are used to set up the necessary data to use the
scrypt KDF.
For more information on scrypt, see L<scrypt(7)>.
For more information on scrypt, see L<EVP_KDF_SCRYPT(7)>.
EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt
value.
@@ -54,6 +54,9 @@ respectively.
=head1 NOTES
There is a newer generic API for KDFs, L<EVP_KDF(3)>, which is
preferred over the EVP_PKEY method.
The scrypt KDF also uses EVP_PKEY_CTX_set1_pbe_pass() as well as
the value from the string controls "pass" and "hexpass".
See L<EVP_PKEY_CTX_set1_pbe_pass(3)>.
@@ -69,7 +72,7 @@ supported by the public key algorithm.
=head1 SEE ALSO
L<scrypt(7)>,
L<EVP_KDF(3)>
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl_str(3)>,
L<EVP_PKEY_derive(3)>
doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod
+1 -1
View File
@@ -70,7 +70,7 @@ All these functions return 1 for success and 0 or a negative value for failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
This example derives 10 bytes using SHA-256 with the secret key "secret"
and seed value "seed":
doc/man3/EVP_PKEY_decrypt.pod
+1 -1
View File
@@ -41,7 +41,7 @@ EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
Decrypt data using OAEP (for RSA keys):
doc/man3/EVP_PKEY_derive.pod
+27 -11
View File
@@ -2,20 +2,33 @@
=head1 NAME
EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret
EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, EVP_PKEY_derive_set_peer,
EVP_PKEY_derive - derive public key algorithm shared secret
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, EVP_KEYEXCH *exchange);
int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
=head1 DESCRIPTION
The EVP_PKEY_derive_init() function initializes a public key algorithm
context using key B<pkey> for shared secret derivation.
The EVP_PKEY_derive_init_ex() function initializes a public key algorithm
context for shared secret derivation using the key exchange algorithm
B<exchange>.
The key exchange algorithm B<exchange> should be fetched using a call to
L<EVP_KEYEXCH_fetch(3)>.
The EVP_PKEY object associated with B<ctx> must be compatible with that
algorithm.
B<exchange> may be NULL in which case the EVP_KEYEXCH algorithm is fetched
implicitly based on the type of EVP_PKEY associated with B<ctx>.
See L<provider(7)/Implicit fetch> for more information about implict fetches.
The EVP_PKEY_derive_init() function is the same as EVP_PKEY_derive_init_ex()
except that the EVP_KEYEXCH algorithm is always implicitly fetched.
The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
be a public key.
@@ -29,20 +42,21 @@ written to B<keylen>.
=head1 NOTES
After the call to EVP_PKEY_derive_init() algorithm specific control
operations can be performed to set any appropriate parameters for the
operation.
After the call to EVP_PKEY_derive_init() or EVP_PKEY_derive_init_ex() algorithm
specific control operations can be performed to set any appropriate parameters
for the operation.
The function EVP_PKEY_derive() can be called more than once on the same
context if several operations are performed using the same parameters.
=head1 RETURN VALUES
EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
EVP_PKEY_derive_init_ex(), EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1
for success and 0 or a negative value for failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
Derive shared secret (for example DH or EC keys):
@@ -86,10 +100,12 @@ L<EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)>,
L<EVP_PKEY_verify_recover(3)>,
L<EVP_KEYEXCH_fetch(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.0.0.
These functions were added in OpenSSL 1.0.0. The EVP_PKEY_derive_init_ex()
function was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/EVP_PKEY_encrypt.pod
+1 -1
View File
@@ -41,7 +41,7 @@ EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or
L<d2i_X509(3)> for means to load a public key. You may also simply
doc/man3/EVP_PKEY_sign.pod
+17 -4
View File
@@ -2,12 +2,14 @@
=head1 NAME
EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm
EVP_PKEY_sign_init_ex, EVP_PKEY_sign_init, EVP_PKEY_sign
- sign using a public key algorithm
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *signature);
int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
unsigned char *sig, size_t *siglen,
@@ -15,8 +17,18 @@ EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm
=head1 DESCRIPTION
The EVP_PKEY_sign_init() function initializes a public key algorithm
context using key B<pkey> for a signing operation.
The EVP_PKEY_sign_init_ex() function initializes a public key algorithm
context for performing signing using the signature algorithm B<signature>.
The signature algorithm B<signature> should be fetched using a call to
L<EVP_SIGNATURE_fetch(3)>.
The EVP_PKEY object associated with B<ctx> must be compatible with that
algorithm.
B<signature> may be NULL in which case the EVP_SIGNATURE algorithm is fetched
implicitly based on the type of EVP_PKEY associated with B<ctx>.
See L<provider(7)/Implicit fetch> for more information about implict fetches.
The EVP_PKEY_sign_init() function is the same as EVP_PKEY_sign_init_ex() except
that the EVP_SIGNATURE algorithm is always implicitly fetched.
The EVP_PKEY_sign() function performs a public key signing operation
using B<ctx>. The data to be signed is specified using the B<tbs> and
@@ -46,7 +58,7 @@ EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0
or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
Sign data using RSA with PKCS#1 padding and SHA256 digest:
@@ -101,6 +113,7 @@ L<EVP_PKEY_derive(3)>
=head1 HISTORY
EVP_PKEY_sign_init_ex() was added in OpenSSL 3.0.
These functions were added in OpenSSL 1.0.0.
=head1 COPYRIGHT
doc/man3/EVP_PKEY_supports_digest_nid.pod
+1 -1
View File
@@ -39,7 +39,7 @@ L<EVP_PKEY_verify_recover(3)>,
=head1 HISTORY
The EVP_PKEY_supports_digest_nid() function was added in OpenSSL 3.0.0.
The EVP_PKEY_supports_digest_nid() function was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/EVP_PKEY_verify.pod
+19 -5
View File
@@ -2,12 +2,14 @@
=head1 NAME
EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm
EVP_PKEY_verify_init_ex, EVP_PKEY_verify_init, EVP_PKEY_verify
- signature verification using a public key algorithm
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *signature);
int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
const unsigned char *sig, size_t siglen,
@@ -15,8 +17,19 @@ EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public ke
=head1 DESCRIPTION
The EVP_PKEY_verify_init() function initializes a public key algorithm
context using key B<pkey> for a signature verification operation.
The EVP_PKEY_verify_init_ex() function initializes a public key algorithm
context for performing signature verification using the signature algorithm
B<signature>.
The signature algorithm B<signature> should be fetched using a call to
L<EVP_SIGNATURE_fetch(3)>.
The EVP_PKEY object associated with B<ctx> must be compatible with that
algorithm.
B<signature> may be NULL in which case the EVP_SIGNATURE algorithm is fetched
implicitly based on the type of EVP_PKEY associated with B<ctx>.
See L<provider(7)/Implicit fetch> for more information about implict fetches.
The EVP_PKEY_verify_init() function is the same as EVP_PKEY_verify_init_ex()
except that the EVP_SIGNATURE algorithm is always implicitly fetched.
The EVP_PKEY_verify() function performs a public key verification operation
using B<ctx>. The signature is specified using the B<sig> and
@@ -44,7 +57,7 @@ A negative value indicates an error other that signature verification failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
Verify signature using PKCS#1 and SHA256 digest:
@@ -89,7 +102,8 @@ L<EVP_PKEY_derive(3)>
=head1 HISTORY
These functions were added in OpenSSL 1.0.0.
EVP_PKEY_verify_init_ex() was added in OpenSSL 3.0.
All other functions were added in OpenSSL 1.0.0.
=head1 COPYRIGHT
doc/man3/EVP_PKEY_verify_recover.pod
+19 -4
View File
@@ -2,12 +2,15 @@
=head1 NAME
EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm
EVP_PKEY_verify_recover_init_ex, EVP_PKEY_verify_recover_init,
EVP_PKEY_verify_recover - recover signature using a public key algorithm
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx,
EVP_SIGNATURE *signature);
int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
unsigned char *rout, size_t *routlen,
@@ -15,8 +18,20 @@ EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using
=head1 DESCRIPTION
The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
context using key B<pkey> for a verify recover operation.
The EVP_PKEY_verify_recover_init_ex() function initializes a public key
algorithm context for performing signature signed data recovery using the
signature algorithm B<signature>.
The signature algorithm B<signature> should be fetched using a call to
L<EVP_SIGNATURE_fetch(3)>.
The EVP_PKEY object associated with B<ctx> must be compatible with that
algorithm.
B<signature> may be NULL in which case the EVP_SIGNATURE algorithm is fetched
implicitly based on the type of EVP_PKEY associated with B<ctx>.
See L<provider(7)/Implicit fetch> for more information about implict fetches.
The EVP_PKEY_verify_recover_init() function is the same as
EVP_PKEY_verify_recover_init_ex() except that the EVP_SIGNATURE algorithm is
always implicitly fetched.
The EVP_PKEY_verify_recover() function recovers signed data
using B<ctx>. The signature is specified using the B<sig> and
@@ -49,7 +64,7 @@ EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for succes
and 0 or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
=head1 EXAMPLES
Recover digest originally signed using PKCS#1 and SHA256 digest:
doc/man3/EVP_SIGNATURE_free.pod
+64
View File
@@ -0,0 +1,64 @@
=pod
=head1 NAME
EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref,
EVP_SIGNATURE_provider
- Functions to manage EVP_SIGNATURE algorithm objects
=head1 SYNOPSIS
#include <openssl/evp.h>
EVP_SIGNATURE *EVP_SIGNATURE_fetch(OPENSSL_CTX *ctx, const char *algorithm,
const char *properties);
void EVP_SIGNATURE_free(EVP_SIGNATURE *signature);
int EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature);
OSSL_PROVIDER *EVP_SIGNATURE_provider(const EVP_SIGNATURE *signature);
=head1 DESCRIPTION
EVP_SIGNATURE_fetch() fetches the implementation for the given
B<algorithm> from any provider offering it, within the criteria given
by the B<properties>.
The algorithm will be one offering functions for performing signature related
tasks such as signing and verifying.
See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with EVP_SIGNATURE_free().
EVP_SIGNATURE_free() decrements the reference count for the B<EVP_SIGNATURE>
structure. Typically this structure will have been obtained from an earlier call
to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the
structure is freed.
EVP_SIGNATURE_up_ref() increments the reference count for an B<EVP_SIGNATURE>
structure.
EVP_SIGNATURE_provider() returns the provider that I<signature> was fetched from.
=head1 RETURN VALUES
EVP_SIGNATURE_fetch() returns a pointer to an B<EVP_SIGNATURE> for success
or B<NULL> for failure.
EVP_SIGNATURE_up_ref() returns 1 for success or 0 otherwise.
=head1 SEE ALSO
L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
=head1 HISTORY
The 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
doc/man3/OCSP_REQUEST_new.pod
+1 -1
View File
@@ -75,7 +75,7 @@ corresponding to each certificate.
OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
OCSP responders.
=head1 EXAMPLE
=head1 EXAMPLES
Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
B<issuer>:
doc/man3/OPENSSL_CTX.pod
+1 -1
View File
@@ -38,7 +38,7 @@ OPENSSL_CTX_free() doesn't return any value.
=head1 HISTORY
OPENSSL_CTX, OPENSSL_CTX_new() and OPENSSL_CTX_free()
were added in OpenSSL 3.0.0.
were added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/OPENSSL_hexchar2int.pod
+74
View File
@@ -0,0 +1,74 @@
=pod
=head1 NAME
OPENSSL_hexchar2int,
OPENSSL_hexstr2buf_ex, OPENSSL_hexstr2buf,
OPENSSL_buf2hexstr_ex, OPENSSL_buf2hexstr
- Hex encoding and decoding functions
=head1 SYNOPSIS
#include <openssl/crypto.h>
int OPENSSL_hexchar2int(unsigned char c);
int OPENSSL_hexstr2buf_ex(unsigned char *buf, size_t buf_n, long *buflen,
const char *str);
unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
int OPENSSL_buf2hexstr_ex(char *str, size_t str_n, size_t *strlen,
const unsigned char *buf, long buflen);
char *OPENSSL_buf2hexstr(const unsigned char *buf, long buflen);
=head1 DESCRIPTION
OPENSSL_hexchar2int() converts a hexadecimal character to its numeric
equivalent.
OPENSSL_hexstr2buf_ex() decodes the hex string B<str> and places the
resulting string of bytes in the given I<buf>.
I<buf_n> gives the size of the buffer.
If I<buflen> is not NULL, it is filled in with the result length.
To find out how large the result will be, call this function with NULL
for I<buf>.
Colons between two-character hex "bytes" are accepted and ignored.
An odd number of hex digits is an error.
OPENSSL_hexstr2buf() does the same thing as OPENSSL_hexstr2buf_ex(),
but allocates the space for the result, and returns the result.
The memory is allocated by calling OPENSSL_malloc() and should be
released by calling OPENSSL_free().
OPENSSL_buf2hexstr_ex() encodes the contents of the given I<buf> with
length I<buflen> and places the resulting hexadecimal character string
in the given I<str>.
I<str_n> gives the size of the of the string buffer.
If I<strlen> is not NULL, it is filled in with the result length.
To find out how large the result will be, call this function with NULL
for I<str>.
OPENSSL_buf2hexstr() does the same thing as OPENSSL_buf2hexstr_ex(),
but allocates the space for the result, and returns the result.
The memory is allocated by calling OPENSSL_malloc() and should be
released by calling OPENSSL_free().
=head1 RETURN VALUES
OPENSSL_hexchar2int returns the value of a decoded hex character,
or -1 on error.
OPENSSL_buf2hexstr() and OPENSSL_hexstr2buf()
return a pointer to allocated memory, or NULL on error.
OPENSSL_buf2hexstr_ex() and OPENSSL_hexstr2buf_ex() return 1 on
success, or 0 on error.
=head1 COPYRIGHT
Copyright 2016-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/OPENSSL_init_crypto.pod
+7 -5
View File
@@ -101,10 +101,12 @@ B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored.
=item OPENSSL_INIT_LOAD_CONFIG
With this option an OpenSSL configuration file will be automatically loaded and
used by calling OPENSSL_config(). This is not a default option for libcrypto.
As of OpenSSL 1.1.1 this is a default option for libssl (see
L<OPENSSL_init_ssl(3)> for further details about libssl initialisation). See the
description of OPENSSL_INIT_new(), below.
used by calling OPENSSL_config(). This is a default option.
Note that in OpenSSL 1.1.1 this was the default for libssl but not for
libcrypto (see L<OPENSSL_init_ssl(3)> for further details about libssl
initialisation).
In OpenSSL 1.1.0 this was a non-default option for both libssl and libcrypto.
See the description of OPENSSL_INIT_new(), below.
=item OPENSSL_INIT_NO_LOAD_CONFIG
@@ -229,7 +231,7 @@ B<CONF_MFLAGS_IGNORE_MISSING_FILE>, B<CONF_MFLAGS_IGNORE_RETURN_CODES> and
B<CONF_MFLAGS_DEFAULT_SECTION> flags.
The filename, application name, and flags can be customized by providing a
non-null B<OPENSSL_INIT_SETTINGS> object.
The object can be allocated via B<OPENSSL_init_new()>.
The object can be allocated via B<OPENSSL_INIT_new()>.
The B<OPENSSL_INIT_set_config_filename()> function can be used to specify a
non-default filename, which is copied and need not refer to persistent storage.
Similarly, OPENSSL_INIT_set_config_appname() can be used to specify a
doc/man3/OPENSSL_malloc.pod
+19 -41
View File
@@ -8,7 +8,6 @@ OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
OPENSSL_strdup, OPENSSL_strndup,
OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat,
OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int,
CRYPTO_strdup, CRYPTO_strndup,
OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
@@ -40,10 +39,6 @@ OPENSSL_MALLOC_FD
void OPENSSL_clear_free(void *str, size_t num)
void OPENSSL_cleanse(void *ptr, size_t len);
unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len);
int OPENSSL_hexchar2int(unsigned char c);
void *CRYPTO_malloc(size_t num, const char *file, int line)
void *CRYPTO_zalloc(size_t num, const char *file, int line)
void *CRYPTO_realloc(void *p, size_t num, const char *file, int line)
@@ -72,17 +67,18 @@ OPENSSL_MALLOC_FD
int CRYPTO_mem_ctrl(int mode);
int OPENSSL_mem_debug_push(const char *info)
int OPENSSL_mem_debug_pop(void);
int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
int CRYPTO_mem_debug_pop(void);
int CRYPTO_mem_leaks(BIO *b);
int CRYPTO_mem_leaks_fp(FILE *fp);
int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),
void *u);
Deprecated:
int OPENSSL_mem_debug_push(const char *info)
int OPENSSL_mem_debug_pop(void);
int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
int CRYPTO_mem_debug_pop(void);
=head1 DESCRIPTION
OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are
@@ -118,20 +114,6 @@ OPENSSL_strlcpy(),
OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C
library functions and are provided for portability.
OPENSSL_hexstr2buf() parses B<str> as a hex string and returns a
pointer to the parsed value. The memory is allocated by calling
OPENSSL_malloc() and should be released by calling OPENSSL_free().
If B<len> is not NULL, it is filled in with the output length.
Colons between two-character hex "bytes" are ignored.
An odd number of hex digits is an error.
OPENSSL_buf2hexstr() takes the specified buffer and length, and returns
a hex string for value, or NULL on error.
B<Buffer> cannot be NULL; if B<len> is 0 an empty string is returned.
OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent,
or returns -1 on error.
If no allocations have been done, it is possible to "swap out" the default
implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free()
and replace them with alternate versions (hooks).
@@ -155,15 +137,6 @@ the B<CRYPTO_MEM_CHECK_ON>.
To disable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
the B<CRYPTO_MEM_CHECK_OFF>.
While checking memory, it can be useful to store additional context
about what is being done.
For example, identifying the field names when parsing a complicated
data structure.
OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push())
attachs an identifying string to the allocation stack.
This must be a global or other static string; it is not copied.
OPENSSL_mem_debug_pop() removes identifying state from the stack.
At the end of the program, calling CRYPTO_mem_leaks() or
CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it
to the specified BIO B<b> or FILE B<fp>. These functions return 1 if
@@ -207,6 +180,9 @@ to use this (will not work on all platforms):
export OPENSSL_MALLOC_FD
...app invocation... 3>/tmp/log$$
OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop()
have been deprecated and replaced with functions that only return zero.
=head1 RETURN VALUES
@@ -221,7 +197,6 @@ OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
OPENSSL_clear_realloc(),
CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(),
CRYPTO_clear_realloc(),
OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(),
OPENSSL_strdup(), and OPENSSL_strndup()
return a pointer to allocated memory or NULL on error.
@@ -232,16 +207,19 @@ always because allocations have already happened).
CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the
previous value of the mode.
OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop()
return 1 on success or 0 on failure.
=head1 NOTES
While it's permitted to swap out only a few and not all the functions
with CRYPTO_set_mem_functions(), it's recommended to swap them all out
at once. I<This applies specially if OpenSSL was built with the
configuration option> C<crypto-mdebug> I<enabled. In case, swapping out
only, say, the malloc() implementation is outright dangerous.>
at once, especially if OpenSSL was built with the
configuration option> C<crypto-mdebug>.
=head1 HISTORY
OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop()
were deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/OPENSSL_s390xcap.pod
+1
View File
@@ -72,6 +72,7 @@ the numbering is continuous across 64-bit mask boundaries.
#134 1<<57 vector packed decimal facility
#135 1<<56 vector enhancements facility 1
#146 1<<45 message-security assist extension 8
#155 1<<36 message-security assist extension 9
kimd :
# 1 1<<62 KIMD-SHA-1
doc/man3/OSSL_CMP_ITAV_set0.pod
+1 -1
View File
@@ -59,7 +59,7 @@ 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
=head1 EXAMPLES
The following code creates and sets a structure representing a generic
InfoTypeAndValue sequence, using an OID created from text as type, and an
doc/man3/OSSL_CRMF_pbmp_new.pod
+1 -1
View File
@@ -49,7 +49,7 @@ 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
=head1 EXAMPLES
OSSL_CRMF_PBMPARAMETER *pbm = NULL;
unsigned char *msg = "Hello";
doc/man3/OSSL_PARAM.pod
+72 -55
View File
@@ -19,7 +19,7 @@ OSSL_PARAM - a structure to pass or request object parameters
=head1 DESCRIPTION
C<OSSL_PARAM> is a type that allows passing arbitrary data for some
B<OSSL_PARAM> is a type that allows passing arbitrary data for some
object between two parties that have no or very little shared
knowledge about their respective internal structures for that object.
@@ -27,65 +27,82 @@ A typical usage example could be an application that wants to set some
parameters for an object, or wants to find out some parameters of an
object.
Arrays of this type can be used for two purposes:
Arrays of this type can be used for the following purposes:
=over 4
=item *
=item * Setting parameters for some object
Setting parameters for some object.
The caller sets up the C<OSSL_PARAM> array and calls some function
The caller sets up the B<OSSL_PARAM> array and calls some function
(the I<setter>) that has intimate knowledge about the object that can
take the data from the C<OSSL_PARAM> array and assign them in a
take the data from the B<OSSL_PARAM> array and assign them in a
suitable form for the internal structure of the object.
=item *
=item * Request parameters of some object
Request parameters of some object.
The caller (the I<requestor>) sets up the C<OSSL_PARAM> array and
The caller (the I<requestor>) sets up the B<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 memory prepared by the
I<requestor> and pointed at with the C<OSSL_PARAM> C<data>.
I<requestor> and pointed at with the B<OSSL_PARAM> I<data>.
=item * Request parameter descriptors
The caller gets an array of constant B<OSSL_PARAM>, which describe
available parameters and some of their properties; name, data type and
expected data size.
For a detailed description of each field for this use, see the field
descriptions below.
The caller may then use the information from this descriptor array to
build up its own B<OSSL_PARAM> array to pass down to a I<setter> or
I<responder>.
=back
=head2 C<OSSL_PARAM> fields
Normally, the order of the an B<OSSL_PARAM> array is not relevant.
However, if the I<responder> can handle multiple elements with the
same key, those elements must be handled in the order they are in.
=head2 B<OSSL_PARAM> fields
=over 4
=item C<key>
=item I<key>
The identity of the parameter in the form of a string.
=item C<data_type>
=item I<data_type>
=for comment It's still debated if this field should be present, or if
the type should always be implied by how it's used.
Either way, these data types will have to be passed together with the
names as an array of OSSL_ITEM, for discovery purposes.
The C<data_type> is a value that describes the type and organization of
The I<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<data>
=item I<data>
=item C<data_size>
=item I<data_size>
C<data> is a pointer to the memory where the parameter data is (when
I<data> is a pointer to the memory where the parameter data is (when
setting parameters) or shall (when requesting parameters) be stored,
and C<data_size> is its size in bytes.
and I<data_size> is its size in bytes.
The organization of the data depends on the parameter type and flag.
=item C<return_size>
When the B<OSSL_PARAM> is used as a parameter descriptor, I<data>
should be ignored.
If I<data_size> is zero, it means that an arbitrary data size is
accepted, otherwise it specifies the maximum size allowed.
When an array of C<OSSL_PARAM> is used to request data, the
=item I<return_size>
When an array of B<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<data_size> is too small for the data, the I<responder>
In case the I<data_size> is too small for the data, the I<responder>
must still set this field to indicate the minimum data size required.
When the B<OSSL_PARAM> is used as a parameter descriptor,
I<return_size> should be ignored.
=back
B<NOTE:>
@@ -98,75 +115,75 @@ except for the pointer form of strings (see data type descriptions
below).
Entities that want to set or request parameters need to know what
those keys are and of what type, any functionality between those two
entities should remain oblivious and just pass the C<OSSL_PARAM> array
entities should remain oblivious and just pass the B<OSSL_PARAM> array
along.
=head2 Supported types
The C<data_type> field can be one of the following types:
The I<data_type> field can be one of the following types:
=over 4
=item C<OSSL_PARAM_INTEGER>
=item B<OSSL_PARAM_INTEGER>
=item C<OSSL_PARAM_UNSIGNED_INTEGER>
=item B<OSSL_PARAM_UNSIGNED_INTEGER>
The parameter data is an integer (signed or unsigned) of arbitrary
length, organized in native form, i.e. most significant byte first on
Big-Endian systems, and least significant byte first on Little-Endian
systems.
=item C<OSSL_PARAM_REAL>
=item B<OSSL_PARAM_REAL>
The parameter data is a floating point value in native form.
=item C<OSSL_PARAM_UTF8_STRING>
=item B<OSSL_PARAM_UTF8_STRING>
The parameter data is a printable string.
=item C<OSSL_PARAM_OCTET_STRING>
=item B<OSSL_PARAM_OCTET_STRING>
The parameter data is an arbitrary string of bytes.
=item C<OSSL_PARAM_UTF8_PTR>
=item B<OSSL_PARAM_UTF8_PTR>
The parameter data is a pointer to a printable string.
The difference between this and C<OSSL_PARAM_UTF8_STRING> is that C<data>
The difference between this and B<OSSL_PARAM_UTF8_STRING> is that I<data>
doesn't point directly at the data, but to a pointer that points to the data.
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.
C<data_size> must be set to the size of the data, not the size of the
I<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.
I<data_size> is not relevant. However, the I<responder> will set
I<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
long enough duration (such as the life-time of the entity that
offers these parameters).
=item C<OSSL_PARAM_OCTET_PTR>
=item B<OSSL_PARAM_OCTET_PTR>
The parameter data is a pointer to an arbitrary string of bytes.
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
The difference between this and B<OSSL_PARAM_OCTET_STRING> is that
I<data> doesn't point directly at the data, but to a pointer that
points to the data.
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.
C<data_size> must be set to the size of the data, not the size of the
I<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.
I<data_size> is not relevant. However, the I<responder> will set
I<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,10 +213,10 @@ enough set of data, that call should succeed.
=item *
Apart from the C<return_size>, a I<responder> must never change the fields
of an C<OSSL_PARAM>.
Apart from the I<return_size>, a I<responder> must never change the fields
of an B<OSSL_PARAM>.
To return a value, it should change the contents of the memory that
C<data> points at.
I<data> points at.
=item *
@@ -209,14 +226,14 @@ the called function may return an error.
The called function may also try to convert the data to a suitable
form (for example, it's plausible to pass a large number as an octet
string, so even though a given key is defined as an
C<OSSL_PARAM_UNSIGNED_INTEGER>, is plausible to pass the value as an
C<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory.
B<OSSL_PARAM_UNSIGNED_INTEGER>, is plausible to pass the value as an
B<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
C<OSSL_PARAM> item to the required size, and eventually return an
requested data, it must set I<return_size> for each such
B<OSSL_PARAM> item to the required size, and eventually return an
error.
=back
@@ -233,7 +250,7 @@ txt
=head1 EXAMPLES
A couple of examples to just show how C<OSSL_PARAM> arrays could be
A couple of examples to just show how B<OSSL_PARAM> arrays could be
set up.
=head3 Example 1
@@ -265,7 +282,7 @@ This example is for requesting parameters on some object:
{ NULL, 0, NULL, 0, NULL }
};
A I<responder> that receives this array (as C<params> in this example)
A I<responder> that receives this array (as I<params> in this example)
could fill in the parameters like this:
/* OSSL_PARAM *params */
@@ -285,11 +302,11 @@ could fill in the parameters like this:
=head1 SEE ALSO
L<openssl-core.h(7)>, L<OSSL_PARAM_get_int32_t(3)>
L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>
=head1 HISTORY
C<OSSL_PARAM> was added in OpenSSL 3.0.
B<OSSL_PARAM> was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/OSSL_PARAM_construct_from_text.pod
+169
View File
@@ -0,0 +1,169 @@
=pod
=head1 NAME
OSSL_PARAM_construct_from_text, OSSL_PARAM_allocate_from_text
- OSSL_PARAM construction utilities
=head1 SYNOPSIS
#include <openssl/params.h>
int OSSL_PARAM_construct_from_text(OSSL_PARAM *to,
const OSSL_PARAM *paramdefs,
const char *key, const char *value,
size_t value_n,
void *buf, size_t *buf_n)
int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to,
const OSSL_PARAM *paramdefs,
const char *key, const char *value,
size_t value_n);
=head1 DESCRIPTION
With OpenSSL before version 3.0, parameters were passed down to or
retrieved from algorithm implementations via control functions.
Some of these control functions existed in variants that took string
parameters, for example L<EVP_PKEY_CTX_ctrl_str(3)>.
OpenSSL 3.0 introduces a new mechanism to do the same thing with an
array of parameters that contain name, value, value type and value
size (see L<OSSL_PARAM(3)> for more information).
OSSL_PARAM_construct_from_text() takes a control I<key>, I<value> and
value size I<value_n>, and given a parameter descriptor array
I<paramdefs>, it converts the value to something suitable for
L<OSSL_PARAM(3)> and stores that in the buffer I<buf>, and modifies
the parameter I<to> to match.
I<buf_n>, if not NULL, will be assigned the number of bytes used in
I<buf>.
If I<buf> is NULL, only I<buf_n> will be modified, everything else is
left untouched, allowing a caller to find out how large the buffer
should be.
I<buf> needs to be correctly aligned for the type of the B<OSSL_PARAM>
I<key>.
OSSL_PARAM_allocate_from_text() works like OSSL_PARAM_construct_from_text(),
except it allocates the buffer internally.
The caller must remember to free the data of I<to> when it's not
useful any more.
For parameters having the type B<OSSL_PARAM_INTEGER>,
B<OSSL_PARAM_UNSIGNED_INTEGER>, or B<OSSL_PARAM_OCTET_STRING>, both
functions will interpret the I<value> differently if the key starts
with "hex".
In that case, the value is decoded first, and the result will be used
as parameter value.
=head1 RETURN VALUES
OSSL_PARAM_construct_from_text() and OSSL_PARAM_allocate_from_text()
returns 1 on success, and 0 on error.
=head1 NOTES
The parameter descriptor array comes from functions dedicated to
return them.
The following B<OSSL_PARAM> attributes are used:
=over 4
=item I<key>
=item I<data>
=item I<data_size>
=back
All other attributes are ignored.
The I<data_size> attribute can be zero, meaning that the parameter it
describes expects arbitrary length data.
=head1 EXAMPLES
Code that looked like this:
int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
{
int rv;
char *stmp, *vtmp = NULL;
stmp = OPENSSL_strdup(value);
if (stmp == NULL)
return -1;
vtmp = strchr(stmp, ':');
if (vtmp != NULL)
*vtmp++ = '\0';
rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
OPENSSL_free(stmp);
return rv;
}
...
for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
char *macopt = sk_OPENSSL_STRING_value(macopts, i);
if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
BIO_printf(bio_err,
"MAC parameter error \"%s\"\n", macopt);
ERR_print_errors(bio_err);
goto mac_end;
}
}
Can be written like this instead:
OSSL_PARAM *params =
OPENSSL_zalloc(sizeof(*params)
* (sk_OPENSSL_STRING_num(opts) + 1));
const OSSL_PARAM *paramdefs = EVP_MAC_CTX_settable_params(mac);
size_t params_n;
char *opt = "<unknown>";
for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
params_n++) {
char *stmp, *vtmp = NULL;
opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
if ((stmp = OPENSSL_strdup(opt)) == NULL
|| (vtmp = strchr(stmp, ':')) == NULL)
goto err;
*vtmp++ = '\0';
if (!OSSL_PARAM_allocate_from_text(&params[params_n],
paramdefs, stmp,
vtmp, strlen(vtmp)))
goto err;
}
params[params_n] = OSSL_PARAM_construct_end();
if (!EVP_MAC_CTX_set_params(ctx, params))
goto err;
while (params_n-- > 0)
OPENSSL_free(params[params_n].data);
OPENSSL_free(params);
/* ... */
return;
err:
BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
ERR_print_errors(bio_err);
=head1 SEE ALSO
L<OSSL_PARAM(3)>, L<OSSL_PARAM_TYPE(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/OSSL_PARAM_int.pod
+45 -35
View File
@@ -6,25 +6,27 @@ 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_END,
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_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_get_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_get_utf8_string,
OSSL_PARAM_get_octet_string, OSSL_PARAM_get_utf8_ptr,
OSSL_PARAM_get_octet_ptr,
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_set_BN, OSSL_PARAM_set_utf8_string,
OSSL_PARAM_set_octet_string, OSSL_PARAM_set_utf8_ptr,
OSSL_PARAM_set_octet_ptr
- OSSL_PARAM helpers
@@ -34,15 +36,23 @@ OSSL_PARAM_set_octet_ptr
#include <openssl/params.h>
/*
* TYPE in function names is one of:
* double, int, int32, int64, long, size_t, uint, uint32, uint64, ulong
* Corresponding TYPE in function arguments is one of:
* double, int, int32_t, int64_t, long, size_t, unsigned int, uint32_t,
* uint64_t, unsigned long
*/
#define OSSL_PARAM_TYPE(key, address)
#define OSSL_PARAM_BN(key, address, size)
#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_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_TYPE(const char *key, TYPE *buf);
OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
size_t bsize);
OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf,
@@ -59,11 +69,11 @@ OSSL_PARAM_set_octet_ptr
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(OSSL_PARAM *p, const char *key, TYPE val);
int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val);
int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val);
int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val);
int OSSL_PARAM_set_BN(OSSL_PARAM *p, const char *key, const BIGNUM *val);
int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val);
int OSSL_PARAM_set_BN(OSSL_PARAM *p, const BIGNUM *val);
int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val,
size_t max_len);
@@ -73,12 +83,13 @@ OSSL_PARAM_set_octet_ptr
size_t max_len, size_t *used_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(OSSL_PARAM *p, char *val);
int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val);
int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val);
int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val,
int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val,
size_t *used_len);
int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, void *val, size_t used_len);
int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val,
size_t used_len);
=head1 DESCRIPTION
@@ -155,23 +166,22 @@ 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.
A parameter with name B<key>, storage B<buf> and size B<bsize> is created.
If B<bsize> is zero, the string length is determined using strlen(3).
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.
A parameter with name B<key>, storage B<buf> and size B<bsize> 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>, size B<bsize> and
return size B<rsize> is created.
A parameter with name B<key>, storage pointer B<*buf> and size B<bsize>
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>, size B<bsize> and
return size B<rsize> is created.
A parameter with name B<key>, storage pointer B<*buf> and size B<bsize>
is created.
OSSL_PARAM_construct_end() is a function that constructs the terminating
OSSL_PARAM structure.
@@ -312,7 +322,7 @@ L<openssl-core.h(7)>, L<OSSL_PARAM(3)>
=head1 HISTORY
These APIs were introduced in OpenSSL 3.0.0.
These APIs were introduced in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/OSSL_PROVIDER.pod
+26 -14
View File
@@ -3,8 +3,9 @@
=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
OSSL_PROVIDER_available,
OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name - provider routines
=head1 SYNOPSIS
@@ -12,15 +13,18 @@ OSSL_PROVIDER_add_builtin - provider routines
typedef struct ossl_provider_st OSSL_PROVIDER;
OSSL_PROVIDER *OSSL_PROVIDER_load(OPENSSL_CTX *, const char *name);
OSSL_PROVIDER *OSSL_PROVIDER_load(OPENSSL_CTX *libctx, const char *name);
int OSSL_PROVIDER_unload(OSSL_PROVIDER *prov);
int OSSL_PROVIDER_available(OPENSSL_CTX *libctx, const char *name);
const OSSL_ITEM *OSSL_PROVIDER_get_param_types(OSSL_PROVIDER *prov);
const OSSL_PARAM *OSSL_PROVIDER_gettable_params(OSSL_PROVIDER *prov);
int OSSL_PROVIDER_get_params(OSSL_PROVIDER *prov, OSSL_PARAM params[]);
int OSSL_PROVIDER_add_builtin(OPENSSL_CTX *, const char *name,
int OSSL_PROVIDER_add_builtin(OPENSSL_CTX *libctx, const char *name,
ossl_provider_init_fn *init_fn);
const char *OSSL_PROVIDER_name(const OSSL_PROVIDER *prov);
=head1 DESCRIPTION
B<OSSL_PROVIDER> is a type that holds internal information about
@@ -30,6 +34,9 @@ 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.
Some of these functions operate within a library context, please see
L<OPENSSL_CTX(3)> for further details.
=head2 Functions
OSSL_PROVIDER_add_builtin() is used to add a built in provider to
@@ -47,18 +54,20 @@ 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_available() checks if a named provider is available
for use.
OSSL_PROVIDER_gettable_params() is used to get a provider parameter
descriptor set as a constant B<OSSL_PARAM> array.
See L<OSSL_PARAM(3)> for more information.
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.
OSSL_PROVIDER_name() returns the name of the given provider.
=head1 RETURN VALUES
OSSL_PROVIDER_add() returns 1 on success, or 0 on error.
@@ -68,8 +77,11 @@ 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_available() returns 1 if the named provider is available,
otherwise 0.
OSSL_PROVIDER_gettable_params() returns a pointer to an array
of constant B<OSSL_PARAM>, or NULL if none is provided.
OSSL_PROVIDER_get_params() returns 1 on success, or 0 on error.
@@ -94,7 +106,7 @@ its build number.
=head1 SEE ALSO
L<openssl-core.h(7)>, L<provider(7)>
L<openssl-core.h(7)>, L<OPENSSL_CTX(3)>, L<provider(7)>
=head1 HISTORY
doc/man3/OSSL_trace_enabled.pod
+1 -1
View File
@@ -278,7 +278,7 @@ otherwise C<NULL>.
=head1 HISTORY
The OpenSSL Tracing API was added ino OpenSSL 3.0.0.
The OpenSSL Tracing API was added ino OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/OSSL_trace_get_category_num.pod
+1 -1
View File
@@ -30,7 +30,7 @@ C<num> is a recognised category number, otherwise NULL.
=head1 HISTORY
The OpenSSL Tracing API was added ino OpenSSL 3.0.0.
The OpenSSL Tracing API was added ino OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/OSSL_trace_set_channel.pod
+4 -2
View File
@@ -1,5 +1,7 @@
=pod
=for comment foreign manuals: atexit(3)
=head1 NAME
OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix,
@@ -212,7 +214,7 @@ the following:
BIO_dump(trc_out, bar, sizeof(bar));
} OSSL_TRACE_END(TLS);
=head1 Simple example
=head2 Simple example
An example with just a channel and constant prefix / suffix.
@@ -297,7 +299,7 @@ functions described here are inoperational, i.e. will do nothing.
OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
in OpenSSL 3.0.0.
in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/OpenSSL_version.pod
+24 -2
View File
@@ -125,6 +125,20 @@ if available or "OPENSSLDIR: N/A" otherwise.
The "ENGINESDIR" setting of the library build in the form "ENGINESDIR: "...""
if available or "ENGINESDIR: N/A" otherwise.
=item OPENSSL_MODULES_DIR
The "MODULESDIR" setting of the library build in the form "MODULESDIR: "...""
if available or "MODULESDIR: N/A" otherwise.
=item OPENSSL_CPU_INFO
The current OpenSSL cpu settings.
This is the current setting of the cpu capability flags. It is usually
automatically configured but may be set via an environment variable.
The value has the same syntax as the environment variable.
For x86 the string looks like "CPUINFO: OPENSSL_ia32cap=0x123:0x456".
Or "CPUINFO: N/A" if not available, e.g. no-asm build.
=back
For an unknown B<t>, the text "not available" is returned.
@@ -166,6 +180,14 @@ value of the environment variable C<$PATH> on Unix (where the
separator is ":") or C<%PATH%> on Windows (where the separator is
";").
=item OPENSSL_INFO_CPU_SETTINGS
The current OpenSSL cpu settings.
This is the current setting of the cpu capability flags. It is usually
automatically configured but may be set via an environment variable.
The value has the same syntax as the environment variable.
For x86 the string looks like "OPENSSL_ia32cap=0x123:0x456".
=back
For an unknown B<t>, NULL is returned.
@@ -219,12 +241,12 @@ L<crypto(7)>
=head1 HISTORY
The macros and functions described here were added in OpenSSL 3.0.0,
The macros and functions described here were added in OpenSSL 3.0,
with the exception of the L</BACKWARD COMPATIBILITY> ones.
=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/man3/PKCS12_newpass.pod
+10 -14
View File
@@ -17,8 +17,6 @@ PKCS12_newpass() changes the password of a PKCS12 structure.
B<p12> is a pointer to a PKCS12 structure. B<oldpass> is the existing password
and B<newpass> is the new password.
=head1 NOTES
Each of B<oldpass> and B<newpass> is independently interpreted as a string in
the UTF-8 encoding. If it is not valid UTF-8, it is assumed to be ISO8859-1
instead.
@@ -29,12 +27,21 @@ use. This may include passwords from local text files, or input from
the terminal or command line. Refer to the documentation of
L<UI_OpenSSL(3)>, for example.
If the PKCS#12 structure does not have a password, then you must use the empty
string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
PKCS12_newpass() failure.
If the wrong password is used for B<oldpass> then the function will fail,
with a MAC verification error. In rare cases the PKCS12 structure does not
contain a MAC: in this case it will usually fail with a decryption padding
error.
=head1 RETURN VALUES
PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
retrieve the most recent error from PKCS12_newpass() with ERR_get_error().
=head1 EXAMPLE
=head1 EXAMPLES
This example loads a PKCS#12 file, changes its password and writes out
the result to a new file.
@@ -83,17 +90,6 @@ the result to a new file.
}
=head1 NOTES
If the PKCS#12 structure does not have a password, then you must use the empty
string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
PKCS12_newpass() failure.
If the wrong password is used for B<oldpass> then the function will fail,
with a MAC verification error. In rare cases the PKCS12 structure does not
contain a MAC: in this case it will usually fail with a decryption padding
error.
=head1 BUGS
The password format is a NULL terminated ASCII string which is converted to
doc/man3/PKCS7_encrypt.pod
-4
View File
@@ -17,8 +17,6 @@ PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs>
is a list of recipient certificates. B<in> is the content to be encrypted.
B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
=head1 NOTES
Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
certificates supplied to this function must all contain RSA public keys, though
they do not have to be signed using the RSA algorithm.
@@ -52,8 +50,6 @@ B<PKCS7_TEXT> is ignored.
If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output
suitable for streaming I/O: no data is read from the BIO B<in>.
=head1 NOTES
If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
complete and outputting its contents via a function that does not
properly finalize the B<PKCS7> structure will give unpredictable
doc/man3/PKCS7_sign.pod
-4
View File
@@ -22,8 +22,6 @@ The data to be signed is read from BIO B<data>.
B<flags> is an optional set of flags.
=head1 NOTES
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
@@ -66,8 +64,6 @@ way data can be signed in a single pass.
If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
which additional signers and capabilities can be added before finalization.
=head1 NOTES
If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
complete and outputting its contents via a function that does not properly
finalize the B<PKCS7> structure will give unpredictable results.
doc/man3/RAND_DRBG_generate.pod
+1 -1
View File
@@ -76,7 +76,7 @@ L<RAND_DRBG(7)>
The RAND_DRBG functions were added in OpenSSL 1.1.1.
Prediction resistance is supported from OpenSSL 3.0.0.
Prediction resistance is supported from OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/RAND_DRBG_reseed.pod
+1 -1
View File
@@ -104,7 +104,7 @@ L<RAND_DRBG(7)>
The RAND_DRBG functions were added in OpenSSL 1.1.1.
Prediction resistance is supported from OpenSSL 3.0.0.
Prediction resistance is supported from OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/RAND_set_rand_method.pod
+4 -3
View File
@@ -10,7 +10,7 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method
RAND_METHOD *RAND_OpenSSL(void);
void RAND_set_rand_method(const RAND_METHOD *meth);
int RAND_set_rand_method(const RAND_METHOD *meth);
const RAND_METHOD *RAND_get_rand_method(void);
@@ -48,8 +48,9 @@ Each pointer may be NULL if the function is not implemented.
=head1 RETURN VALUES
RAND_set_rand_method() returns no value. RAND_get_rand_method() and
RAND_OpenSSL() return pointers to the respective methods.
RAND_set_rand_method() returns 1 on success and 0 on failue.
RAND_get_rand_method() and RAND_OpenSSL() return pointers to the respective
methods.
=head1 SEE ALSO
doc/man3/RSA_padding_add_PKCS1_type_1.pod
+1 -1
View File
@@ -123,7 +123,7 @@ The RSA_padding_check_xxx() functions return the length of the
recovered data, -1 on error. Error codes can be obtained by calling
L<ERR_get_error(3)>.
=head1 WARNING
=head1 WARNINGS
The result of RSA_padding_check_PKCS1_type_2() is a very sensitive
information which can potentially be used to mount a Bleichenbacher
doc/man3/RSA_public_encrypt.pod
+1 -1
View File
@@ -81,7 +81,7 @@ means only that the plaintext was empty.
On error, -1 is returned; the error codes can be
obtained by L<ERR_get_error(3)>.
=head1 WARNING
=head1 WARNINGS
Decryption failures in the RSA_PKCS1_PADDING mode leak information
which can potentially be used to mount a Bleichenbacher padding oracle
doc/man3/SRP_VBASE_new.pod
+1 -1
View File
@@ -83,7 +83,7 @@ L<SSL_CTX_set_srp_password(3)>
=head1 HISTORY
The SRP_VBASE_add0_user() function was added in OpenSSL 3.0.0.
The SRP_VBASE_add0_user() function was added in OpenSSL 3.0.
All other functions were added in OpenSSL 1.0.1.
doc/man3/SRP_user_pwd_new.pod
+1 -1
View File
@@ -56,7 +56,7 @@ L<SSL_CTX_set_srp_password(3)>
=head1 HISTORY
These functions were made public in OpenSSL 3.0.0.
These functions were made public in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/SSL_CTX_config.pod
+1 -1
View File
@@ -33,7 +33,7 @@ file syntax.
SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
occurred.
=head1 EXAMPLE
=head1 EXAMPLES
If the file "config.cnf" contains the following:
doc/man3/SSL_CTX_dane_enable.pod
+1 -1
View File
@@ -181,7 +181,7 @@ The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(),
SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect
before they were called.
=head1 EXAMPLE
=head1 EXAMPLES
Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
DNSSEC-validated TLSA records.
doc/man3/SSL_CTX_get0_param.pod
+7 -7
View File
@@ -29,13 +29,6 @@ Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure
using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
them to suit its needs: for example to add a hostname check.
=head1 EXAMPLE
Check hostname matches "www.foo.com" in peer certificate:
X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
=head1 RETURN VALUES
SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
@@ -44,6 +37,13 @@ B<X509_VERIFY_PARAM> structure.
SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
for failure.
=head1 EXAMPLES
Check hostname matches "www.foo.com" in peer certificate:
X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
=head1 SEE ALSO
L<X509_VERIFY_PARAM_set_flags(3)>
doc/man3/SSL_CTX_set1_curves.pod
+12 -3
View File
@@ -4,8 +4,8 @@
SSL_CTX_set1_groups, SSL_CTX_set1_groups_list, SSL_set1_groups,
SSL_set1_groups_list, SSL_get1_groups, SSL_get_shared_group,
SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves,
SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve
SSL_get_negotiated_group, SSL_CTX_set1_curves, SSL_CTX_set1_curves_list,
SSL_set1_curves, SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve
- EC supported curve functions
=head1 SYNOPSIS
@@ -20,6 +20,7 @@ SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve
int SSL_get1_groups(SSL *ssl, int *groups);
int SSL_get_shared_group(SSL *s, int n);
int SSL_get_negotiated_group(SSL *s);
int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen);
int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list);
@@ -68,6 +69,9 @@ most applications will only be interested in the first shared group
so B<n> is normally set to zero. If the value B<n> is out of range,
NID_undef is returned.
SSL_get_negotiated_group() returns the negotiated group on a TLSv1.3 connection
for key exchange. This can be called by either client or server.
All these functions are implemented as macros.
The curve functions are synonyms for the equivalently named group functions and
@@ -96,6 +100,10 @@ is -1.
When called on a client B<ssl>, SSL_get_shared_group() has no meaning and
returns -1.
SSL_get_negotiated_group() returns the NID of the negotiated group on a
TLSv1.3 connection for key exchange. Or it returns NID_undef if no negotiated
group.
=head1 SEE ALSO
L<SSL_CTX_add_extra_chain_cert(3)>
@@ -103,7 +111,8 @@ L<SSL_CTX_add_extra_chain_cert(3)>
=head1 HISTORY
The curve functions were added in OpenSSL 1.0.2. The equivalent group
functions were added in OpenSSL 1.1.1.
functions were added in OpenSSL 1.1.1. The SSL_get_negotiated_group() function
was added in OpenSSL 3.0.0.
=head1 COPYRIGHT
doc/man3/SSL_CTX_set_cipher_list.pod
+2 -2
View File
@@ -96,7 +96,7 @@ 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.
cipher list defines are deprecated as of 3.0.
=head1 RETURN VALUES
@@ -115,7 +115,7 @@ L<ciphers(1)>
=head1 HISTORY
OSSL_default_cipher_list() and OSSL_default_ciphersites() are new in 3.0.0.
OSSL_default_cipher_list() and OSSL_default_ciphersites() are new in 3.0.
=head1 COPYRIGHT
doc/man3/SSL_CTX_set_mode.pod
+1 -1
View File
@@ -150,7 +150,7 @@ L<SSL_write(3)>, L<SSL_get_error(3)>
=head1 HISTORY
SSL_MODE_ASYNC was added in OpenSSL 1.1.0.
SSL_MODE_NO_KTLS_TX was added in OpenSSL 3.0.0.
SSL_MODE_NO_KTLS_TX was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/SSL_CTX_set_options.pod
+2 -2
View File
@@ -313,7 +313,7 @@ unaware of the unpatched nature of the client.
If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
renegotiation B<always> succeeds.
=head2 Patched OpenSSL client and unpatched server.
=head2 Patched OpenSSL client and unpatched server
If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
@@ -374,7 +374,7 @@ OpenSSL 0.9.8m.
The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options
were added in OpenSSL 1.1.1.
The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> option was added in OpenSSL 3.0.0.
The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> option was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/SSL_CTX_set_session_id_context.pod
+2 -2
View File
@@ -42,7 +42,7 @@ OpenSSL clients will check the session id context returned by the server
when reusing a session.
The maximum length of the B<sid_ctx> is limited to
B<SSL_MAX_SSL_SESSION_ID_LENGTH>.
B<SSL_MAX_SID_CTX_LENGTH>.
=head1 WARNINGS
@@ -67,7 +67,7 @@ return the following values:
=item Z<>0
The length B<sid_ctx_len> of the session id context B<sid_ctx> exceeded
the maximum allowed length of B<SSL_MAX_SSL_SESSION_ID_LENGTH>. The error
the maximum allowed length of B<SSL_MAX_SID_CTX_LENGTH>. The error
is logged to the error stack.
=item Z<>1
doc/man3/SSL_CTX_use_psk_identity_hint.pod
-2
View File
@@ -85,8 +85,6 @@ check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or
SSL_set_psk_server_callback() and use that. In this case the handshake digest
will default to SHA-256 for any returned PSK.
=head1 NOTES
A connection established via a TLSv1.3 PSK will appear as if session resumption
has occurred so that L<SSL_session_reused(3)> will return true.
doc/man3/SSL_library_init.pod
+1 -1
View File
@@ -25,7 +25,7 @@ implemented as a macro.
SSL_library_init() must be called before any other action takes place.
SSL_library_init() is not reentrant.
=head1 WARNING
=head1 WARNINGS
SSL_library_init() adds ciphers and digests used directly and indirectly by
SSL/TLS.
doc/man3/SSL_set1_host.pod
+1 -1
View File
@@ -71,7 +71,7 @@ applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
matched. Otherwise, it returns the matched peername. To determine
whether verification succeeded call L<SSL_get_verify_result(3)>.
=head1 EXAMPLE
=head1 EXAMPLES
Suppose "smtp.example.com" is the MX host of the domain "example.com".
The calls below will arrange to match either the MX hostname or the
doc/man3/SSL_set_async_callback.pod
+1 -1
View File
@@ -82,7 +82,7 @@ SSL_get_async_status() return 1 on success or 0 on error.
SSL_CTX_set_async_callback(), SSL_CTX_set_async_callback_arg(),
SSL_set_async_callback(), SSL_set_async_callback_arg() and
SSL_get_async_status() were first added to OpenSSL 3.0.0.
SSL_get_async_status() were first added to OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/SSL_shutdown.pod
+26 -30
View File
@@ -15,8 +15,6 @@ SSL_shutdown - shut down a TLS/SSL connection
SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
close_notify shutdown alert to the peer.
=head1 NOTES
SSL_shutdown() tries to send the close_notify shutdown alert to the peer.
Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
a currently open session is considered closed and good and will be kept in the
@@ -52,6 +50,32 @@ SSL_shutdown() only closes the write direction.
It is not possible to call SSL_write() after calling SSL_shutdown().
The read direction is closed by the peer.
The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
handshake step has been finished or an error occurred.
If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
when the underlying BIO could not satisfy the needs of SSL_shutdown()
to continue the handshake. In this case a call to SSL_get_error() with the
return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
taking appropriate action to satisfy the needs of SSL_shutdown().
The action depends on the underlying BIO. When using a non-blocking socket,
nothing is to be done, but select() can be used to check for the required
condition. When using a buffering BIO, like a BIO pair, data must be written
into or retrieved out of the BIO before being able to continue.
After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
to wait for the peer's close_notify alert.
SSL_shutdown() will return 1 in that case.
However, it is recommended to wait for it using SSL_read() instead.
SSL_shutdown() can be modified to only set the connection to "shutdown"
state but not actually send the close_notify alert messages,
see L<SSL_CTX_set_quiet_shutdown(3)>.
When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
and return 1.
=head2 First to close the connection
When the application is the first party to send the close_notify
@@ -89,34 +113,6 @@ If successful, SSL_shutdown() will return 1.
Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
=head1 NOTES
The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
handshake step has been finished or an error occurred.
If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
when the underlying BIO could not satisfy the needs of SSL_shutdown()
to continue the handshake. In this case a call to SSL_get_error() with the
return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
taking appropriate action to satisfy the needs of SSL_shutdown().
The action depends on the underlying BIO. When using a non-blocking socket,
nothing is to be done, but select() can be used to check for the required
condition. When using a buffering BIO, like a BIO pair, data must be written
into or retrieved out of the BIO before being able to continue.
After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
to wait for the peer's close_notify alert.
SSL_shutdown() will return 1 in that case.
However, it is recommended to wait for it using SSL_read() instead.
SSL_shutdown() can be modified to only set the connection to "shutdown"
state but not actually send the close_notify alert messages,
see L<SSL_CTX_set_quiet_shutdown(3)>.
When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
and return 1.
=head1 RETURN VALUES
The following return values can occur:
doc/man3/SSL_write.pod
+2 -2
View File
@@ -66,7 +66,7 @@ operation is considered completed. The bytes are sent and a new write call with
a new buffer (with the already sent bytes removed) must be started. A partial
write is performed with the size of a message block, which is 16kB.
=head1 WARNING
=head1 WARNINGS
When a write function call has to be repeated because L<SSL_get_error(3)>
returned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
@@ -141,7 +141,7 @@ L<ssl(7)>, L<bio(7)>
=head1 HISTORY
The SSL_write_ex() function was added in OpenSSL 1.1.1.
The SSL_sendfile() function was added in OpenSSL 3.0.0.
The SSL_sendfile() function was added in OpenSSL 3.0.
=head1 COPYRIGHT
doc/man3/X509_PUBKEY_new.pod
+4 -2
View File
@@ -2,8 +2,9 @@
=head1 NAME
X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0,
X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp,
X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup,
X509_PUBKEY_set, X509_PUBKEY_get0, X509_PUBKEY_get,
d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp,
i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param,
X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
@@ -13,6 +14,7 @@ X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
X509_PUBKEY *X509_PUBKEY_new(void);
void X509_PUBKEY_free(X509_PUBKEY *a);
X509_PUBKEY *X509_PUBKEY_dup(const X509_PUBKEY *a);
int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey);
EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key);
doc/man3/X509_STORE_CTX_get_error.pod
+4 -4
View File
@@ -101,8 +101,8 @@ the operation was successful.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
the issuer certificate could not be found: this occurs if the issuer certificate
of an untrusted certificate cannot be found.
the issuer certificate of a locally looked up certificate could not be found.
This normally means the list of trusted certificates is not complete.
=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
@@ -180,8 +180,8 @@ the root could not be found locally.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
the issuer certificate of a locally looked up certificate could not be found.
This normally means the list of trusted certificates is not complete.
the issuer certificate could not be found: this occurs if the issuer certificate
of an untrusted certificate cannot be found.
=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
doc/man3/X509_STORE_CTX_new.pod
+1 -1
View File
@@ -28,7 +28,7 @@ X509_STORE_CTX_verify_fn
void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x);
STACK_OF(X509) *X509_STORE_CTX_get0_chain(X609_STORE_CTX *ctx);
STACK_OF(X509) *X509_STORE_CTX_get0_chain(X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
doc/man3/X509_STORE_CTX_set_verify_cb.pod
+1 -1
View File
@@ -76,7 +76,7 @@ from the corresponding B<X509_STORE>, please see
L<X509_STORE_set_verify(3)> for more information.
=head1 WARNING
=head1 WARNINGS
In general a verification callback should B<NOT> unconditionally return 1 in
all circumstances because this will allow verification to succeed no matter
doc/man3/X509_STORE_add_cert.pod
+4 -2
View File
@@ -55,7 +55,9 @@ operate on pointers to B<X509> objects, though.
X509_STORE_add_cert() and X509_STORE_add_crl() add the respective object
to the B<X509_STORE>'s local storage. Untrusted objects should not be
added in this way.
added in this way. The added object's reference count is incremented by one,
hence the caller retains ownership of the object and needs to free it when it
is no longer needed.
X509_STORE_set_depth(), X509_STORE_set_flags(), X509_STORE_set_purpose(),
X509_STORE_set_trust(), and X509_STORE_set1_param() set the default values
@@ -90,7 +92,7 @@ L<X509_STORE_get0_param(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/X509_VERIFY_PARAM_set_flags.pod
+1 -1
View File
@@ -346,7 +346,7 @@ If CRLs checking is enable CRLs are expected to be available in the
corresponding B<X509_STORE> structure. No attempt is made to download
CRLs from the CRL distribution points extension.
=head1 EXAMPLE
=head1 EXAMPLES
Enable CRL checking when performing certificate verification during SSL
connections associated with an B<SSL_CTX> structure B<ctx>:
doc/man3/X509_dup.pod
+14 -3
View File
@@ -52,12 +52,18 @@ EDIPARTYNAME_new,
ESS_CERT_ID_dup,
ESS_CERT_ID_free,
ESS_CERT_ID_new,
ESS_CERT_ID_V2_dup,
ESS_CERT_ID_V2_free,
ESS_CERT_ID_V2_new,
ESS_ISSUER_SERIAL_dup,
ESS_ISSUER_SERIAL_free,
ESS_ISSUER_SERIAL_new,
ESS_SIGNING_CERT_dup,
ESS_SIGNING_CERT_free,
ESS_SIGNING_CERT_new,
ESS_SIGNING_CERT_V2_dup,
ESS_SIGNING_CERT_V2_free,
ESS_SIGNING_CERT_V2_new,
EXTENDED_KEY_USAGE_free,
EXTENDED_KEY_USAGE_new,
GENERAL_NAMES_free,
@@ -118,8 +124,8 @@ OCSP_SINGLERESP_free,
OCSP_SINGLERESP_new,
OSSL_CMP_ITAV_free,
OSSL_CMP_MSG_dup,
OSSL_CMP_MSG_it,
OSSL_CMP_MSG_free,
OSSL_CMP_MSG_it,
OSSL_CMP_PKIHEADER_free,
OSSL_CMP_PKIHEADER_it,
OSSL_CMP_PKIHEADER_new,
@@ -199,10 +205,10 @@ POLICY_CONSTRAINTS_free,
POLICY_CONSTRAINTS_new,
POLICY_MAPPING_free,
POLICY_MAPPING_new,
PROFESSION_INFO_free,
PROFESSION_INFO_new,
PROFESSION_INFOS_free,
PROFESSION_INFOS_new,
PROFESSION_INFO_free,
PROFESSION_INFO_new,
PROXY_CERT_INFO_EXTENSION_free,
PROXY_CERT_INFO_EXTENSION_new,
PROXY_POLICY_free,
@@ -246,10 +252,13 @@ X509_ALGOR_new,
X509_ATTRIBUTE_dup,
X509_ATTRIBUTE_free,
X509_ATTRIBUTE_new,
X509_CERT_AUX_dup,
X509_CERT_AUX_free,
X509_CERT_AUX_new,
X509_CINF_dup,
X509_CINF_free,
X509_CINF_new,
X509_CRL_INFO_dup,
X509_CRL_INFO_free,
X509_CRL_INFO_new,
X509_CRL_dup,
@@ -264,6 +273,7 @@ X509_NAME_ENTRY_new,
X509_NAME_dup,
X509_NAME_free,
X509_NAME_new,
X509_REQ_INFO_dup,
X509_REQ_INFO_free,
X509_REQ_INFO_new,
X509_REQ_dup,
@@ -272,6 +282,7 @@ X509_REQ_new,
X509_REVOKED_dup,
X509_REVOKED_free,
X509_REVOKED_new,
X509_SIG_dup,
X509_SIG_free,
X509_SIG_new,
X509_VAL_free,

Some files were not shown because too many files have changed in this diff Show More