ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import OpenSSL 1.1.1f

Browse Source
This commit is contained in:
Steve Dower
2020-04-03 21:53:21 +01:00
parent 6f2f71e7ea
commit e531386a2f
993 changed files with 23821 additions and 3602 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/man3/ASN1_INTEGER_get_int64.pod
View File

@@ -22,10 +22,10 @@ ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_s
ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a);
long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r);
int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);

4
doc/man3/ASN1_TYPE_get.pod
View File

@@ -69,7 +69,7 @@ If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
return value is non-zero. Technically if both parameters are NULL the two
types could be absent OPTIONAL fields and so should match, however passing
NULL values could also indicate a programming error (for example an
unparseable type which returns NULL) for types which do B<not> match. So
unparsable type which returns NULL) for types which do B<not> match. So
applications should handle the case of two absent values separately.
=head1 RETURN VALUES
@@ -90,7 +90,7 @@ NULL on failure.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

20
doc/man3/BIO_f_buffer.pod
View File

@@ -49,10 +49,20 @@ is expanded.
These functions, other than BIO_f_buffer(), are implemented as macros.
Buffering BIOs implement BIO_gets() by using BIO_read_ex() operations on the
next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
possible to provide BIO_gets() functionality if the following BIOs do not
support it (for example SSL BIOs).
Buffering BIOs implement BIO_read_ex() and BIO_gets() by using
BIO_read_ex() operations on the next BIO in the chain and storing the
result in an internal buffer, from which bytes are given back to the
caller as appropriate for the call; a BIO_gets() is guaranteed to give
the caller a whole line, and BIO_read_ex() is guaranteed to give the
caller the number of bytes it asks for, unless there's an error or end
of communication is reached in the next BIO. By prepending a
buffering BIO to a chain it is therefore possible to provide
BIO_gets() or exact size BIO_read_ex() functionality if the following
BIOs do not support it.
Do not add more than one BIO_f_buffer() to a BIO chain. The result of
doing so will force a full read of the size of the internal buffer of
the top BIO_f_buffer(), which is 4 KiB at a minimum.
Data is only written to the next BIO in the chain when the write buffer fills
or when BIO_flush() is called. It is therefore important to call BIO_flush()
@@ -82,7 +92,7 @@ L<BIO_ctrl(3)>.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

6
doc/man3/BIO_get_ex_new_index.pod
View File

@@ -39,7 +39,7 @@ L<CRYPTO_get_ex_new_index(3)>.
These functions handle application-specific data for OpenSSL data
structures.
TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
TYPE_get_ex_new_index() is a macro that calls CRYPTO_get_ex_new_index()
with the correct B<index> value.
TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
@@ -50,7 +50,7 @@ an offset into the opaque exdata part of the TYPE object.
=head1 RETURN VALUES
TYPE_get_new_ex_index() returns a new index on success or -1 on error.
TYPE_get_ex_new_index() returns a new index on success or -1 on error.
TYPE_set_ex_data() returns 1 on success or 0 on error.
@@ -62,7 +62,7 @@ L<CRYPTO_get_ex_new_index(3)>.
=head1 COPYRIGHT
Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

10
doc/man3/BN_generate_prime.pod
View File

@@ -52,7 +52,9 @@ Deprecated:
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.
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,7 +91,9 @@ 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
@@ -206,7 +210,7 @@ and BN_GENCB_get_arg() functions were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

12
doc/man3/DTLSv1_listen.pod
View File

@@ -66,9 +66,9 @@ the peer and continue the handshake in a connected state.
Prior to calling DTLSv1_listen() user code must ensure that cookie generation
and verification callbacks have been set up using
SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb()
and SSL_CTX_set_stateless_cookie_verify_cb() must be used instead.
L<SSL_CTX_set_cookie_generate_cb(3)> and L<SSL_CTX_set_cookie_verify_cb(3)>
respectively. For SSL_stateless(), L<SSL_CTX_set_stateless_cookie_generate_cb(3)>
and L<SSL_CTX_set_stateless_cookie_verify_cb(3)> must be used instead.
Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
ClientHellos it is unable to process fragmented messages (since this would
@@ -112,8 +112,10 @@ errors as non-fatal), whilst return codes >0 indicate success.
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_accept(3)>,
L<ssl(7)>, L<bio(7)>
L<SSL_CTX_set_cookie_generate_cb(3)>, L<SSL_CTX_set_cookie_verify_cb(3)>,
L<SSL_CTX_set_stateless_cookie_generate_cb(3)>,
L<SSL_CTX_set_stateless_cookie_verify_cb(3)>, L<SSL_get_error(3)>,
L<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>
=head1 HISTORY

90
doc/man3/EC_GROUP_copy.pod
View File

@@ -40,7 +40,7 @@ EC_GROUP_get_pentanomial_basis
int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *);
point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *group);
unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x);
size_t EC_GROUP_get_seed_len(const EC_GROUP *);
@@ -61,34 +61,39 @@ EC_GROUP_get_pentanomial_basis
=head1 DESCRIPTION
EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
EC_GROUP_copy() copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created
EC_GROUP_dup() creates a new EC_GROUP object and copies the content from B<src> to the newly created
EC_GROUP object.
EC_GROUP_method_of obtains the EC_METHOD of B<group>.
EC_GROUP_method_of() obtains the EC_METHOD of B<group>.
EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These
EC_GROUP_set_generator() sets curve parameters that must be agreed by all participants using the curve. These
parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve.
EC_GROUP_get0_generator returns the generator for the identified B<group>.
EC_GROUP_get0_generator() returns the generator for the identified B<group>.
The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters
with the respective order and cofactors for the B<group>.
EC_GROUP_get_order() retrieves the order of B<group> and copies its value into
B<order>. It fails in case B<group> is not fully initialized (i.e., its order
is not set or set to zero).
The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
EC_GROUP_get_cofactor() retrieves the cofactor of B<group> and copies its value
into B<cofactor>. It fails in case B<group> is not fully initialized or if the
cofactor is not set (or set to zero).
The functions EC_GROUP_set_curve_name() and EC_GROUP_get_curve_name(), set and get the NID for the curve respectively
(see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
will return 0.
will return NID_undef.
The asn1_flag value is used to determine whether the curve encoding uses
explicit parameters or a named curve using an ASN1 OID: many applications only
support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the
named curve form is used and the parameters must have a corresponding
named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the
parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and
EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve.
parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag() and
EC_GROUP_set_asn1_flag() get and set the status of the asn1_flag for the curve.
Note: B<OPENSSL_EC_EXPLICIT_CURVE> was added in OpenSSL 1.1.0, for
previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL
1.1.0 the default form was to use explicit parameters (meaning that
@@ -119,32 +124,32 @@ the two possible solutions for y has been used, followed by the octets for x.
For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form
The functions EC_GROUP_set_point_conversion_form() and EC_GROUP_get_point_conversion_form(), set and get the point_conversion_form
for the curve respectively.
ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages
in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it.
If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library
does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block
containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the
builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed(). This returns a pointer to a memory block
containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len(). A number of the
built-in curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
EC_GROUP_set_seed() and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
this seed value, although it will be preserved in any ASN1 based communications.
EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
EC_GROUP_get_degree() gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
the value m.
The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid.
The function EC_GROUP_check_discriminant() calculates the discriminant for the curve and verifies that it is valid.
For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
simply b. In either case for the curve to be valid the discriminant must be non zero.
The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include
The function EC_GROUP_check() performs a number of checks on a curve to verify that it is valid. Checks performed include
verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
the correct order.
EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
EC_GROUP_cmp() compares B<a> and B<b> to determine whether they represent the same curve or not.
The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
The functions EC_GROUP_get_basis_type(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis() should only be called for curves
defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial
function f(x). This function is either a trinomial of the form:
@@ -154,39 +159,48 @@ or a pentanomial of the form:
f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
The function EC_GROUP_get_basis_type() returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
function EC_GROUP_get_trinomial_basis() must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly
the function EC_GROUP_get_pentanomial_basis() must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
B<k2> and B<k3> respectively.
=head1 RETURN VALUES
The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check,
EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis.
The following functions return 1 on success or 0 on error: EC_GROUP_copy(), EC_GROUP_set_generator(), EC_GROUP_check(),
EC_GROUP_check_discriminant(), EC_GROUP_get_trinomial_basis() and EC_GROUP_get_pentanomial_basis().
EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error.
EC_GROUP_dup() returns a pointer to the duplicated curve, or NULL on error.
EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error.
EC_GROUP_method_of() returns the EC_METHOD implementation in use for the given curve or NULL on error.
EC_GROUP_get0_generator returns the generator for the given curve or NULL on error.
EC_GROUP_get0_generator() returns the generator for the given curve or NULL on error.
EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form
and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
EC_GROUP_get_order() returns 0 if the order is not set (or set to zero) for
B<group> or if copying into B<order> fails, 1 otherwise.
EC_GROUP_get_cofactor() returns 0 if the cofactor is not set (or is set to zero) for B<group> or if copying into B<cofactor> fails, 1 otherwise.
EC_GROUP_get_curve_name() returns the curve name (NID) for B<group> or will return NID_undef if no curve name is associated.
EC_GROUP_get_asn1_flag() returns the ASN1 flag for the specified B<group> .
EC_GROUP_get_point_conversion_form() returns the point_conversion_form for B<group>.
EC_GROUP_get_degree() returns the degree for B<group> or 0 if the operation is not supported by the underlying group implementation.
EC_GROUP_get0_order() returns an internal pointer to the group order.
EC_GROUP_order_bits() returns the number of bits in the group order.
EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor.
EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
EC_GROUP_get0_seed() returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
specified. EC_GROUP_get_seed_len() returns the length of the seed or 0 if the seed is not specified.
EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
EC_GROUP_set_seed() returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
0, the return value will be 1. On error 0 is returned.
EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
EC_GROUP_cmp() returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
EC_GROUP_get_basis_type() returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
=head1 SEE ALSO

92
doc/man3/EC_GROUP_new.pod
View File

@@ -57,49 +57,63 @@ objects
=head1 DESCRIPTION
Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised
Within the library there are two forms of elliptic curve that are of interest.
The first form is those defined over the prime field Fp. The elements of Fp are
the integers 0 to p-1, where p is a prime number. This gives us a revised
elliptic curve equation as follows:
y^2 mod p = x^3 +ax + b mod p
The second form is those defined over a binary field F2^m where the elements of the field are integers of length at
most m bits. For this form the elliptic curve equation is modified to:
The second form is those defined over a binary field F2^m where the elements of
the field are integers of length at most m bits. For this form the elliptic
curve equation is modified to:
y^2 + xy = x^3 + ax^2 + b (where b != 0)
Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
use a trinomial or a pentanomial for this parameter.
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.
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>.
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.
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_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
the polynomial is a trinomial or a pentanomial.
EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve
over Fp B<p> 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 the
polynomial is a trinomial or a pentanomial.
In either case, B<a> and B<b> represents the coefficients a and b from the
relevant equation introduced above.
EC_group_get_curve() obtains the previously set curve parameters.
EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for EC_GROUP_set_curve(). They are defined for
backwards compatibility only and should not be used.
EC_GROUP_set_curve_GFp() and EC_GROUP_set_curve_GF2m() are synonyms for
EC_GROUP_set_curve(). They are defined for backwards compatibility only and
should not be used.
EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for EC_GROUP_get_curve(). They are defined for
backwards compatibility only and should not be used.
EC_GROUP_get_curve_GFp() and EC_GROUP_get_curve_GF2m() are synonyms for
EC_GROUP_get_curve(). They are defined for backwards compatibility only and
should not be used.
The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and then the
EC_GROUP_set_curve function. An appropriate default implementation method will be used.
The functions EC_GROUP_new_curve_GFp() and EC_GROUP_new_curve_GF2m() are
shortcuts for calling EC_GROUP_new() and then the EC_GROUP_set_curve() function.
An appropriate default implementation method will be used.
Whilst the library can be used to create any curve using the functions described above, there are also a number of
predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
Whilst the library can be used to create any curve using the functions described
above, there are also a number of predefined curves that are available. In order
to obtain a list of all of the predefined curves, call the function
EC_get_builtin_curves(). The parameter B<r> should be an array of
EC_builtin_curve structures of size B<nitems>. The function will populate the
B<r> array with information about the builtin curves. If B<nitems> is less than
the total number of curves available, then the first B<nitems> curves will be
returned. Otherwise the total number of curves will be provided. The return
value is the total number of curves available (whether that number has been
populated in B<r> or not). Passing a NULL B<r>, or setting B<nitems> to 0 will
do nothing other than return the total number of curves available.
The EC_builtin_curve structure is defined as follows:
typedef struct {
@@ -107,24 +121,28 @@ The EC_builtin_curve structure is defined as follows:
const char *comment;
} EC_builtin_curve;
Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
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
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.
EC_GROUP_free frees the memory associated with the EC_GROUP.
EC_GROUP_free() frees the memory associated with the EC_GROUP.
If B<group> is NULL nothing is done.
EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
If B<group> is NULL nothing is done.
EC_GROUP_clear_free() destroys any sensitive data held within the EC_GROUP and
then frees its memory. If B<group> is NULL nothing is done.
=head1 RETURN VALUES
All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
All EC_GROUP_new* functions return a pointer to the newly constructed group, or
NULL on error.
EC_get_builtin_curves returns the number of builtin curves that are available.
EC_get_builtin_curves() returns the number of builtin curves that are available.
EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error.
=head1 SEE ALSO
@@ -134,7 +152,7 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
=head1 COPYRIGHT
Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2013-2019 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

20
doc/man3/EC_POINT_new.pod
View File

@@ -171,6 +171,26 @@ The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(),
EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from
and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively.
The function EC_POINT_point2oct() encodes the given curve point B<p> as an
octet string into the buffer B<buf> of size B<len>, using the specified
conversion form B<form>.
The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve
Cryptography") standard.
Similarly the function EC_POINT_oct2point() decodes a curve point into B<p> from
the octet string contained in the given buffer B<buf> of size B<len>, conforming
to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
The functions EC_POINT_point2hex() and EC_POINT_point2bn() convert a point B<p>,
respectively, to the hexadecimal or BIGNUM representation of the same
encoding of the function EC_POINT_point2oct().
Vice versa, similarly to the function EC_POINT_oct2point(), the functions
EC_POINT_hex2point() and EC_POINT_point2bn() decode the hexadecimal or
BIGNUM representation into the EC_POINT B<p>.
Notice that, according to the standard, the octet string encoding of the point
at infinity for a given curve is fixed to a single octet of value zero and that,
vice versa, a single octet of size zero is decoded as the point at infinity.
The function EC_POINT_point2oct() must be supplied with a buffer long enough to
store the octet form. The return value provides the number of octets stored.
Calling the function with a NULL buffer will not perform the conversion but

96
doc/man3/EVP_DigestInit.pod
View File

@@ -2,17 +2,17 @@
=head1 NAME
EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,
EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags,
EVP_MD_CTX_test_flags, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags,
EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size,
EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data,
EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags,
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_set_pkey_ctx - EVP digest routines
EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj,
EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
=head1 SYNOPSIS
@@ -26,6 +26,8 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
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);
int EVP_Digest(const void *data, size_t count, unsigned char *md,
unsigned int *size, const EVP_MD *type, ENGINE *impl);
int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
@@ -42,12 +44,18 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
int EVP_MD_pkey_type(const EVP_MD *md);
int EVP_MD_size(const EVP_MD *md);
int EVP_MD_block_size(const EVP_MD *md);
unsigned long EVP_MD_flags(const EVP_MD *md);
const EVP_MD *EVP_MD_CTX_md(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);
int EVP_MD_CTX_size(const EVP_MD_CTX *ctx);
int EVP_MD_CTX_block_size(const EVP_MD_CTX *ctx);
int EVP_MD_CTX_type(const EVP_MD_CTX *ctx);
void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx,
const void *data, size_t count);
void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx,
int (*update)(EVP_MD_CTX *ctx,
const void *data, size_t count));
const EVP_MD *EVP_md_null(void);
@@ -55,6 +63,7 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines
const EVP_MD *EVP_get_digestbynid(int type);
const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);
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);
=head1 DESCRIPTION
@@ -79,12 +88,24 @@ Cleans up digest context B<ctx> and frees up the space allocated to it.
=item EVP_MD_CTX_ctrl()
Performs digest-specific control actions on context B<ctx>.
Performs digest-specific control actions on context B<ctx>. The control command
is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>.
EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions
may apply depending on the control type and digest implementation.
See L</CONTROLS> below for more information.
=item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()
Sets, clears and tests B<ctx> flags. See L</FLAGS> below for more information.
=item EVP_Digest()
A wrapper around the Digest Init_ex, Update and Final_ex functions.
Hashes B<count> bytes of data at B<data> using a digest B<type> from ENGINE
B<impl>. The digest value is placed in B<md> and its length is written at B<size>
if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written.
If B<impl> is NULL the default implementation of digest B<type> is used.
=item EVP_DigestInit_ex()
Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
@@ -122,7 +143,7 @@ few bytes.
=item EVP_DigestInit()
Behaves in the same way as EVP_DigestInit_ex() except it always uses the
default digest implementation.
default digest implementation and calls EVP_MD_CTX_reset().
=item EVP_DigestFinal()
@@ -163,6 +184,21 @@ EVP_MD_meth_set_app_datasize().
Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>.
=item EVP_MD_CTX_set_update_fn()
Sets the update function for B<ctx> to B<update>.
This is the function that is called by EVP_DigestUpdate. If not set, the
update function from the B<EVP_MD> type specified at initialization is used.
=item EVP_MD_CTX_update_fn()
Returns the update function for B<ctx>.
=item EVP_MD_flags()
Returns the B<md> flags. Note that these are different from the B<EVP_MD_CTX>
ones. See L<EVP_MD_meth_set_flags(3)> for more information.
=item EVP_MD_pkey_type()
Returns the NID of the public key signing algorithm associated with this
@@ -182,10 +218,15 @@ EVP_get_digestbyobj()
Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an
B<ASN1_OBJECT> structure respectively.
=item EVP_MD_CTX_pkey_ctx()
Returns the B<EVP_PKEY_CTX> assigned to B<ctx>. The returned pointer should not
be freed by the caller.
=item EVP_MD_CTX_set_pkey_ctx()
Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide
a customzied B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or
a customized B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or
L<EVP_DigestVerifyInit(3)>. The B<pctx> passed to this function should be freed
by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX>
assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
@@ -193,6 +234,27 @@ depends on how the B<EVP_PKEY_CTX> is created.
=back
=head1 CONTROLS
EVP_MD_CTX_ctrl() can be used to send the following standard controls:
=over 4
=item EVP_MD_CTRL_MICALG
Gets the digest Message Integrity Check algorithm string. This is used when
creating S/MIME multipart/signed messages, as specified in RFC 3851.
The string value is written to B<p2>.
=item EVP_MD_CTRL_XOF_LEN
This control sets the digest length for extendable output functions to B<p1>.
Sending this control directly should not be necessary, the use of
C<EVP_DigestFinalXOF()> is preferred.
Currently used by SHAKE.
=back
=head1 FLAGS
EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags()
@@ -245,8 +307,7 @@ Returns 1 if successful or 0 for failure.
Returns 1 if successful or 0 for failure.
=item EVP_MD_type(),
EVP_MD_pkey_type(),
EVP_MD_type()
EVP_MD_pkey_type()
Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none
exists.
@@ -350,6 +411,7 @@ digest name passed on the command line.
=head1 SEE ALSO
L<EVP_MD_meth_new(3)>,
L<dgst(1)>,
L<evp(7)>

10
doc/man3/EVP_DigestSignInit.pod
View File

@@ -36,7 +36,7 @@ EVP_MD_CTX is freed).
The digest B<type> may be NULL if the signing algorithm supports it.
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>. See also L<SM2(7)>.
Only EVP_PKEY types that support signing can be used with these functions. This
includes MAC algorithms where the MAC generation is considered as a form of
@@ -102,10 +102,8 @@ EVP_DigestSignFinal().
=head1 RETURN VALUES
EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignaFinal() and
EVP_DigestSign() 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_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignFinal() and
EVP_DigestSign() return 1 for success and 0 for failure.
The error codes can be obtained from L<ERR_get_error(3)>.
@@ -158,7 +156,7 @@ were added in OpenSSL 1.0.0.
=head1 COPYRIGHT
Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

2
doc/man3/EVP_DigestVerifyInit.pod
View File

@@ -33,7 +33,7 @@ inside EVP_DigestVerifyInit() and it will be freed automatically when the
EVP_MD_CTX is freed).
No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>. See also L<SM2(7)>.
EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
verification context B<ctx>. This function can be called several times on the

9
doc/man3/EVP_EncryptInit.pod
View File

@@ -492,6 +492,15 @@ EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
existing context without allocating and freeing it up on each call.
There are some differences between functions EVP_CipherInit() and
EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills
the passed context object with zeros. As a consequence, EVP_CipherInit() does
not allow step-by-step initialization of the ctx when the I<key> and I<iv> are
passed in separate calls. It also means that the flags set for the CTX are
removed, and it is especially important for the
B<EVP_CIPHER_CTX_FLAG_WRAP_ALLOW> flag treated specially in
EVP_CipherInit_ex().
EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.
=head1 BUGS

21
doc/man3/EVP_MD_meth_new.pod
View File

@@ -84,7 +84,12 @@ together. The available flags are:
=item EVP_MD_FLAG_ONESHOT
This digest method can only handles one block of input.
This digest method can only handle one block of input.
=item EVP_MD_FLAG_XOF
This digest method is an extensible-output function (XOF) and supports
the B<EVP_MD_CTRL_XOF_LEN> control.
=item EVP_MD_FLAG_DIGALGID_NULL
@@ -105,19 +110,24 @@ B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
Currently unused.
=item EVP_MD_FLAG_FIPS
This digest method is suitable for use in FIPS mode.
Currently unused.
=back
EVP_MD_meth_set_init() sets the digest init function for B<md>.
The digest init function is called by EVP_DigestInit(),
The digest init function is called by EVP_Digest(), EVP_DigestInit(),
EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
and EVP_VerifyInit_ex().
EVP_MD_meth_set_update() sets the digest update function for B<md>.
The digest update function is called by EVP_DigestUpdate(),
The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and
EVP_SignUpdate().
EVP_MD_meth_set_final() sets the digest final function for B<md>.
The digest final function is called by EVP_DigestFinal(),
The digest final function is called by EVP_Digest(), EVP_DigestFinal(),
EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
EVP_MD_meth_set_copy() sets the function for B<md> to do extra
@@ -138,6 +148,7 @@ This cleanup function is called by EVP_MD_CTX_reset() and
EVP_MD_CTX_free().
EVP_MD_meth_set_ctrl() sets the control function for B<md>.
See L<EVP_MD_CTX_ctrl(3)> for the available controls.
EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
@@ -169,7 +180,7 @@ The B<EVP_MD> structure was openly available in OpenSSL before version
=head1 COPYRIGHT
Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

16
doc/man3/EVP_PKEY_CTX_ctrl.pod
View File

@@ -23,6 +23,8 @@ EVP_PKEY_CTX_get_rsa_oaep_md,
EVP_PKEY_CTX_set0_rsa_oaep_label,
EVP_PKEY_CTX_get0_rsa_oaep_label,
EVP_PKEY_CTX_set_dsa_paramgen_bits,
EVP_PKEY_CTX_set_dsa_paramgen_q_bits,
EVP_PKEY_CTX_set_dsa_paramgen_md,
EVP_PKEY_CTX_set_dh_paramgen_prime_len,
EVP_PKEY_CTX_set_dh_paramgen_subprime_len,
EVP_PKEY_CTX_set_dh_paramgen_generator,
@@ -93,6 +95,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
#include <openssl/dsa.h>
int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
int EVP_PKEY_CTX_set_dsa_paramgen_q_bits(EVP_PKEY_CTX *ctx, int qbits);
int EVP_PKEY_CTX_set_dsa_paramgen_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
#include <openssl/dh.h>
@@ -255,7 +259,17 @@ by the library and should not be freed by the caller.
=head2 DSA parameters
The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used
for DSA parameter generation to B<bits>. If not specified 1024 is used.
for DSA parameter generation to B<nbits>. If not specified, 1024 is used.
The EVP_PKEY_CTX_set_dsa_paramgen_q_bits() macro sets the number of bits in the
subprime parameter B<q> for DSA parameter generation to B<qbits>. If not
specified, 160 is used. If a digest function is specified below, this parameter
is ignored and instead, the number of bits in B<q> matches the size of the
digest.
The EVP_PKEY_CTX_set_dsa_paramgen_md() macro sets the digest function used for
DSA parameter generation to B<md>. If not specified, one of SHA-1, SHA-224, or
SHA-256 is selected to match the bit length of B<q> above.
=head2 DH parameters

32
doc/man3/EVP_PKEY_meth_new.pod
View File

@@ -8,14 +8,18 @@ EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup,
EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign,
EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx,
EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt,
EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, EVP_PKEY_meth_set_check,
EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl,
EVP_PKEY_meth_set_digestsign, EVP_PKEY_meth_set_digestverify,
EVP_PKEY_meth_set_check,
EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check,
EVP_PKEY_meth_set_digest_custom,
EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup,
EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign,
EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx,
EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt,
EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check,
EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl,
EVP_PKEY_meth_get_digestsign, EVP_PKEY_meth_get_digestverify,
EVP_PKEY_meth_get_check,
EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check,
EVP_PKEY_meth_get_digest_custom,
EVP_PKEY_meth_remove
@@ -112,6 +116,18 @@ EVP_PKEY_meth_remove
int (*ctrl_str) (EVP_PKEY_CTX *ctx,
const char *type,
const char *value));
void EVP_PKEY_meth_set_digestsign(EVP_PKEY_METHOD *pmeth,
int (*digestsign) (EVP_MD_CTX *ctx,
unsigned char *sig,
size_t *siglen,
const unsigned char *tbs,
size_t tbslen));
void EVP_PKEY_meth_set_digestverify(EVP_PKEY_METHOD *pmeth,
int (*digestverify) (EVP_MD_CTX *ctx,
const unsigned char *sig,
size_t siglen,
const unsigned char *tbs,
size_t tbslen));
void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
int (*check) (EVP_PKEY *pkey));
void EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth,
@@ -200,6 +216,18 @@ EVP_PKEY_meth_remove
int (**pctrl_str) (EVP_PKEY_CTX *ctx,
const char *type,
const char *value));
void EVP_PKEY_meth_get_digestsign(EVP_PKEY_METHOD *pmeth,
int (**digestsign) (EVP_MD_CTX *ctx,
unsigned char *sig,
size_t *siglen,
const unsigned char *tbs,
size_t tbslen));
void EVP_PKEY_meth_get_digestverify(EVP_PKEY_METHOD *pmeth,
int (**digestverify) (EVP_MD_CTX *ctx,
const unsigned char *sig,
size_t siglen,
const unsigned char *tbs,
size_t tbslen));
void EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth,
int (**pcheck) (EVP_PKEY *pkey));
void EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth,

31
doc/man3/EVP_PKEY_new.pod
View File

@@ -72,21 +72,24 @@ EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key().
New applications should use EVP_PKEY_new_raw_private_key() instead.
EVP_PKEY_get_raw_private_key() fills the buffer provided by B<priv> with raw
private key data. The number of bytes written is populated in B<*len>. If the
buffer B<priv> is NULL then B<*len> is populated with the number of bytes
required to hold the key. The calling application is responsible for ensuring
that the buffer is large enough to receive the private key data. This function
only works for algorithms that support raw private keys. Currently this is:
B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>, B<EVP_PKEY_X25519>,
B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
private key data. The size of the B<priv> buffer should be in B<*len> on entry
to the function, and on exit B<*len> is updated with the number of bytes
actually written. If the buffer B<priv> is NULL then B<*len> is populated with
the number of bytes required to hold the key. The calling application is
responsible for ensuring that the buffer is large enough to receive the private
key data. This function only works for algorithms that support raw private keys.
Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>,
B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
EVP_PKEY_get_raw_public_key() fills the buffer provided by B<pub> with raw
public key data. The number of bytes written is populated in B<*len>. If the
buffer B<pub> is NULL then B<*len> is populated with the number of bytes
required to hold the key. The calling application is responsible for ensuring
that the buffer is large enough to receive the public key data. This function
only works for algorithms that support raw public keys. Currently this is:
B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
public key data. The size of the B<pub> buffer should be in B<*len> on entry
to the function, and on exit B<*len> is updated with the number of bytes
actually written. If the buffer B<pub> is NULL then B<*len> is populated with
the number of bytes required to hold the key. The calling application is
responsible for ensuring that the buffer is large enough to receive the public
key data. This function only works for algorithms that support raw public keys.
Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or
B<EVP_PKEY_ED448>.
=head1 NOTES
@@ -126,7 +129,7 @@ EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

80
doc/man3/EVP_PKEY_size.pod Normal file
View File

@@ -0,0 +1,80 @@
=pod
=head1 NAME
EVP_PKEY_size, EVP_PKEY_bits, EVP_PKEY_security_bits
- EVP_PKEY information functions
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_size(const EVP_PKEY *pkey);
int EVP_PKEY_bits(const EVP_PKEY *pkey);
int EVP_PKEY_security_bits(const EVP_PKEY *pkey);
=head1 DESCRIPTION
EVP_PKEY_size() returns the maximum suitable size for the output
buffers for almost all operations that can be done with I<pkey>.
The primary documented use is with L<EVP_SignFinal(3)> and
L<EVP_SealInit(3)>, but it isn't limited there. The returned size is
also large enough for the output buffer of L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)>, L<EVP_PKEY_derive(3)>.
It must be stressed that, unless the documentation for the operation
that's being performed says otherwise, the size returned by
EVP_PKEY_size() is only preliminary and not exact, so the final
contents of the target buffer may be smaller. It is therefore crucial
to take note of the size given back by the function that performs the
operation, such as L<EVP_PKEY_sign(3)> (the I<siglen> argument will
receive that length), to avoid bugs.
EVP_PKEY_bits() returns the cryptographic length of the cryptosystem
to which the key in I<pkey> belongs, in bits. Note that the definition
of cryptographic length is specific to the key cryptosystem.
EVP_PKEY_security_bits() returns the number of security bits of the given
I<pkey>, bits of security is defined in NIST SP800-57.
=head1 RETURN VALUES
EVP_PKEY_size(), EVP_PKEY_bits() and EVP_PKEY_security_bits() return a
positive number, or 0 if this size isn't available.
=head1 NOTES
Most functions that have an output buffer and are mentioned with
EVP_PKEY_size() have a functionality where you can pass NULL for the
buffer and still pass a pointer to an integer and get the exact size
that this function call delivers in the context that it's called in.
This allows those functions to be called twice, once to find out the
exact buffer size, then allocate the buffer in between, and call that
function again actually output the data. For those functions, it
isn't strictly necessary to call EVP_PKEY_size() to find out the
buffer size, but may be useful in cases where it's desirable to know
the upper limit in advance.
It should also be especially noted that EVP_PKEY_size() shouldn't be
used to get the output size for EVP_DigestSignFinal(), according to
L<EVP_DigestSignFinal(3)/NOTES>.
=head1 SEE ALSO
L<EVP_SignFinal(3)>,
L<EVP_SealInit(3)>,
L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_derive(3)>
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

44
doc/man3/EVP_SignInit.pod
View File

@@ -2,10 +2,8 @@
=head1 NAME
EVP_PKEY_size,
EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal,
EVP_PKEY_security_bits - EVP signing
functions
EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal
- EVP signing functions
=head1 SYNOPSIS
@@ -17,49 +15,36 @@ functions
void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
int EVP_PKEY_size(const EVP_PKEY *pkey);
int EVP_PKEY_security_bits(const EVP_PKEY *pkey);
=head1 DESCRIPTION
The EVP signature routines are a high level interface to digital
signatures.
EVP_SignInit_ex() sets up signing context B<ctx> to use digest
B<type> from ENGINE B<impl>. B<ctx> must be created with
EVP_SignInit_ex() sets up signing context I<ctx> to use digest
I<type> from B<ENGINE> I<impl>. I<ctx> must be created with
EVP_MD_CTX_new() before calling this function.
EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
signature context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data.
EVP_SignUpdate() hashes I<cnt> bytes of data at I<d> into the
signature context I<ctx>. This function can be called several times on the
same I<ctx> to include additional data.
EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey)
bytes in size. B<s> is an OUT parameter, and not used as an IN parameter.
EVP_SignFinal() signs the data in I<ctx> using the private key I<pkey> and
places the signature in I<sig>. I<sig> must be at least C<EVP_PKEY_size(pkey)>
bytes in size. I<s> is an OUT parameter, and not used as an IN parameter.
The number of bytes of data written (i.e. the length of the signature)
will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
will be written to the integer at I<s>, at most C<EVP_PKEY_size(pkey)> bytes
will be written.
EVP_SignInit() initializes a signing context B<ctx> to use the default
implementation of digest B<type>.
EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
signature returned by EVP_SignFinal() may be smaller.
EVP_PKEY_security_bits() returns the number of security bits of the given B<pkey>,
bits of security is defined in NIST SP800-57.
EVP_SignInit() initializes a signing context I<ctx> to use the default
implementation of digest I<type>.
=head1 RETURN VALUES
EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
for success and 0 for failure.
EVP_PKEY_size() returns the maximum size of a signature in bytes.
The error codes can be obtained by L<ERR_get_error(3)>.
EVP_PKEY_security_bits() returns the number of security bits.
=head1 NOTES
The B<EVP> interface to digital signatures should almost always be used in
@@ -95,6 +80,7 @@ The previous two bugs are fixed in the newer EVP_SignDigest*() function.
=head1 SEE ALSO
L<EVP_PKEY_size(3)>, L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)>,
L<EVP_VerifyInit(3)>,
L<EVP_DigestInit(3)>,
L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
@@ -103,7 +89,7 @@ L<SHA1(3)>, L<dgst(1)>
=head1 COPYRIGHT
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

4
doc/man3/OCSP_request_add1_nonce.pod
View File

@@ -24,7 +24,7 @@ it adds a nonce to OCSP basic response B<resp>.
OCSP_check_nonce() compares the nonce value in B<req> and B<resp>.
OCSP_copy_nonce() copys any nonce value present in B<req> to B<resp>.
OCSP_copy_nonce() copies any nonce value present in B<req> to B<resp>.
=head1 RETURN VALUES
@@ -74,7 +74,7 @@ L<OCSP_sendreq_new(3)>
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

4
doc/man3/OCSP_response_status.pod
View File

@@ -58,7 +58,7 @@ with the X509 certificate B<cert>.
OCSP_basic_sign() signs OCSP response B<brsp> using certificate B<signer>, private key
B<key>, digest B<dgst> and additional certificates B<certs>. If the B<flags> option
B<OCSP_NOCERTS> is set then no certificates will be included in the request. If the
B<OCSP_NOCERTS> is set then no certificates will be included in the response. If the
B<flags> option B<OCSP_RESPID_KEY> is set then the responder is identified by key ID
rather than by name. OCSP_basic_sign_ctx() also signs OCSP response B<brsp> but
uses the parameters contained in digest context B<ctx>.
@@ -107,7 +107,7 @@ The OCSP_basic_sign_ctx() function was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

9
doc/man3/OCSP_sendreq_new.pod
View File

@@ -24,8 +24,7 @@ OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions
int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req);
OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req,
int maxline);
OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req);
=head1 DESCRIPTION
@@ -54,8 +53,8 @@ OCSP_REQ_CTX_set1_req() sets the OCSP request in B<rctx> to B<req>. This
function should be called after any calls to OCSP_REQ_CTX_add1_header().
OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL
path B<path>, the OCSP request B<req> and with a response header maximum line
length of B<maxline>. If B<maxline> is zero a default value of 4k is used.
path B<path>, and the OCSP request B<req> with a response header maximum line
length 4k. It waits indefinitely on a response.
=head1 RETURN VALUES
@@ -112,7 +111,7 @@ L<OCSP_response_status(3)>
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

4
doc/man3/OPENSSL_malloc.pod
View File

@@ -160,7 +160,7 @@ 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.
attaches 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.
@@ -245,7 +245,7 @@ only, say, the malloc() implementation is outright dangerous.>
=head1 COPYRIGHT
Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

4
doc/man3/OPENSSL_secure_malloc.pod
View File

@@ -7,6 +7,7 @@ CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc,
OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free,
CRYPTO_secure_free, OPENSSL_secure_clear_free,
CRYPTO_secure_clear_free, OPENSSL_secure_actual_size,
CRYPTO_secure_allocated,
CRYPTO_secure_used - secure heap storage
=head1 SYNOPSIS
@@ -33,6 +34,7 @@ CRYPTO_secure_used - secure heap storage
size_t OPENSSL_secure_actual_size(const void *ptr);
int CRYPTO_secure_allocated(const void *ptr);
size_t CRYPTO_secure_used();
=head1 DESCRIPTION
@@ -90,6 +92,8 @@ OPENSSL_secure_actual_size() tells the actual size allocated to the
pointer; implementations may allocate more space than initially
requested, in order to "round up" and reduce secure heap fragmentation.
OPENSSL_secure_allocated() tells if a pointer is allocated in the secure heap.
CRYPTO_secure_used() returns the number of bytes allocated in the
secure heap.

4
doc/man3/PEM_bytes_read_bio.pod
View File

@@ -17,7 +17,8 @@ PEM_bytes_read_bio, PEM_bytes_read_bio_secmem - read a PEM-encoded data structur
=head1 DESCRIPTION
PEM_bytes_read_bio() reads PEM-formatted (RFC 1421) data from the BIO
PEM_bytes_read_bio() reads PEM-formatted (IETF RFC 1421 and IETF RFC 7468)
data from the BIO
I<bp> for the data type given in I<name> (RSA PRIVATE KEY, CERTIFICATE,
etc.). If multiple PEM-encoded data structures are present in the same
stream, PEM_bytes_read_bio() will skip non-matching data types and
@@ -66,7 +67,6 @@ PEM_bytes_read_bio() and PEM_bytes_read_bio_secmem() return 1 for success or
=head1 SEE ALSO
L<PEM(3)>,
L<PEM_read_bio_ex(3)>,
L<passphrase-encoding(7)>

12
doc/man3/PEM_read_bio_PrivateKey.pod
View File

@@ -15,7 +15,8 @@ PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
PEM_write_DSA_PUBKEY, PEM_read_bio_Parameters, PEM_write_bio_Parameters,
PEM_read_bio_DSAparams, PEM_read_DSAparams,
PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
@@ -110,6 +111,9 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x);
int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x);
DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
@@ -216,6 +220,12 @@ a DSA structure. The public key is encoded using a
SubjectPublicKeyInfo structure and an error occurs if the public
key is not DSA.
The B<Parameters> functions read or write key parameters in PEM format using
an EVP_PKEY structure. The encoding depends on the type of key; for DSA key
parameters, it will be a Dss-Parms structure as defined in RFC2459, and for DH
key parameters, it will be a PKCS#3 DHparameter structure. I<These functions
only exist for the B<BIO> type>.
The B<DSAparams> functions process DSA parameters using a DSA
structure. The parameters are encoded using a Dss-Parms structure
as defined in RFC2459.

2
doc/man3/PEM_read_bio_ex.pod
View File

@@ -52,7 +52,7 @@ PEM_read_bio_ex() returns 1 for success or 0 for failure.
=head1 SEE ALSO
L<PEM(3)>
L<PEM_bytes_read_bio(3)>
=head1 HISTORY

26
doc/man3/RAND_bytes.pod
View File

@@ -19,8 +19,8 @@ Deprecated:
=head1 DESCRIPTION
RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
into B<buf>.
RAND_bytes() generates B<num> random bytes using a cryptographically
secure pseudo random generator (CSPRNG) and stores them in B<buf>.
RAND_priv_bytes() has the same semantics as RAND_bytes(). It is intended to
be used for generating values that should remain private. If using the
@@ -31,10 +31,22 @@ and L<RAND_DRBG(7)>.
=head1 NOTES
Always check the error return value of RAND_bytes() and
RAND_priv_bytes() and do not take randomness for granted: an error occurs
if the CSPRNG has not been seeded with enough randomness to ensure an
unpredictable byte sequence.
By default, the OpenSSL CSPRNG supports a security level of 256 bits, provided it
was able to seed itself from a trusted entropy source.
On all major platforms supported by OpenSSL (including the Unix-like platforms
and Windows), OpenSSL is configured to automatically seed the CSPRNG on first use
using the operating systems's random generator.
If the entropy source fails or is not available, the CSPRNG will enter an
error state and refuse to generate random bytes. For that reason, it is important
to always check the error return value of RAND_bytes() and RAND_priv_bytes() and
not take randomness for granted.
On other platforms, there might not be a trusted entropy source available
or OpenSSL might have been explicitly configured to use different entropy sources.
If you are in doubt about the quality of the entropy source, don't hesitate to ask
your operating system vendor or post a question on GitHub or the openssl-users
mailing list.
=head1 RETURN VALUES
@@ -68,7 +80,7 @@ The RAND_priv_bytes() function was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

2
doc/man3/RAND_set_rand_method.pod
View File

@@ -48,7 +48,7 @@ Each pointer may be NULL if the function is not implemented.
=head1 RETURN VALUES
RAND_set_rand_method() returns 1 on success and 0 on failue.
RAND_set_rand_method() returns 1 on success and 0 on failure.
RAND_get_rand_method() and RAND_OpenSSL() return pointers to the respective
methods.

7
doc/man3/RSA_get0_key.pod
View File

@@ -5,7 +5,7 @@
RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key,
RSA_get0_factors, RSA_get0_crt_params,
RSA_get0_n, RSA_get0_e, RSA_get0_d, RSA_get0_p, RSA_get0_q,
RSA_get0_dmp1, RSA_get0_dmq1, RSA_get0_iqmp,
RSA_get0_dmp1, RSA_get0_dmq1, RSA_get0_iqmp, RSA_get0_pss_params,
RSA_clear_flags,
RSA_test_flags, RSA_set_flags, RSA_get0_engine, RSA_get_multi_prime_extra_count,
RSA_get0_multi_prime_factors, RSA_get0_multi_prime_crt_params,
@@ -33,6 +33,7 @@ RSA_set0_multi_prime_params, RSA_get_version
const BIGNUM *RSA_get0_dmp1(const RSA *r);
const BIGNUM *RSA_get0_dmq1(const RSA *r);
const BIGNUM *RSA_get0_iqmp(const RSA *r);
const RSA_PSS_PARAMS *RSA_get0_pss_params(const RSA *r);
void RSA_clear_flags(RSA *r, int flags);
int RSA_test_flags(const RSA *r, int flags);
void RSA_set_flags(RSA *r, int flags);
@@ -98,6 +99,8 @@ retrieved separately by the corresponding function
RSA_get0_n(), RSA_get0_e(), RSA_get0_d(), RSA_get0_p(), RSA_get0_q(),
RSA_get0_dmp1(), RSA_get0_dmq1(), and RSA_get0_iqmp(), respectively.
RSA_get0_pss_params() is used to retrieve the RSA-PSS parameters.
RSA_set_flags() sets the flags in the B<flags> parameter on the RSA
object. Multiple flags can be passed in one go (bitwise ORed together).
Any flags that are already set are left set. RSA_test_flags() tests to
@@ -157,6 +160,8 @@ L<RSA_new(3)>, L<RSA_size(3)>
=head1 HISTORY
The RSA_get0_pss_params() function was added in OpenSSL 1.1.1e.
The
RSA_get_multi_prime_extra_count(), RSA_get0_multi_prime_factors(),
RSA_get0_multi_prime_crt_params(), RSA_set0_multi_prime_params(),

57
doc/man3/SSL_CTX_sess_set_get_cb.pod
View File

@@ -28,19 +28,19 @@ SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SS
=head1 DESCRIPTION
SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically
SSL_CTX_sess_set_new_cb() sets the callback function that is
called whenever a new session was negotiated.
SSL_CTX_sess_set_remove_cb() sets the callback function, which is
automatically called whenever a session is removed by the SSL engine,
because it is considered faulty or the session has become obsolete because
of exceeding the timeout value.
SSL_CTX_sess_set_remove_cb() sets the callback function that is
called whenever a session is removed by the SSL engine. For example,
this can occur because a session is considered faulty or has become obsolete
because of exceeding the timeout value.
SSL_CTX_sess_set_get_cb() sets the callback function which is called,
whenever a SSL/TLS client proposed to resume a session but the session
SSL_CTX_sess_set_get_cb() sets the callback function that is called
whenever a TLS client proposed to resume a session but the session
could not be found in the internal session cache (see
L<SSL_CTX_set_session_cache_mode(3)>).
(SSL/TLS server only.)
(TLS server only.)
SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and
SSL_CTX_sess_get_get_cb() retrieve the function pointers set by the
@@ -54,12 +54,19 @@ session cache is realized via callback functions. Inside these callback
functions, session can be saved to disk or put into a database using the
L<d2i_SSL_SESSION(3)> interface.
The new_session_cb() is called, whenever a new session has been negotiated
and session caching is enabled (see
L<SSL_CTX_set_session_cache_mode(3)>).
The new_session_cb() is passed the B<ssl> connection and the ssl session
B<sess>. If the callback returns B<0>, the session will be immediately
removed again. Note that in TLSv1.3, sessions are established after the main
The new_session_cb() is called whenever a new session has been negotiated and
session caching is enabled (see L<SSL_CTX_set_session_cache_mode(3)>). The
new_session_cb() is passed the B<ssl> connection and the nascent
ssl session B<sess>.
Since sessions are reference-counted objects, the reference count on the
session is incremented before the callback, on behalf of the application. If
the callback returns B<0>, the session will be immediately removed from the
internal cache and the reference count released. If the callback returns B<1>,
the application retains the reference (for an entry in the
application-maintained "external session cache"), and is responsible for
calling SSL_SESSION_free() when the session reference is no longer in use.
Note that in TLSv1.3, sessions are established after the main
handshake has completed. The server decides when to send the client the session
information and this may occur some time after the end of the handshake (or not
at all). This means that applications should expect the new_session_cb()
@@ -72,21 +79,23 @@ In TLSv1.3 it is recommended that each SSL_SESSION object is only used for
resumption once. One way of enforcing that is for applications to call
L<SSL_CTX_remove_session(3)> after a session has been used.
The remove_session_cb() is called, whenever the SSL engine removes a session
from the internal cache. This happens when the session is removed because
The remove_session_cb() is called whenever the SSL engine removes a session
from the internal cache. This can happen when the session is removed because
it is expired or when a connection was not shutdown cleanly. It also happens
for all sessions in the internal session cache when
L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed
the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
The get_session_cb() is only called on SSL/TLS servers with the session id
proposed by the client. The get_session_cb() is always called, also when
The get_session_cb() is only called on SSL/TLS servers, and is given
the session id
proposed by the client. The get_session_cb() is always called, even when
session caching was disabled. The get_session_cb() is passed the
B<ssl> connection, the session id of length B<length> at the memory location
B<data>. With the parameter B<copy> the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object,
Normally the reference count is not incremented and therefore the
session must not be explicitly freed with
B<ssl> connection and the session id of length B<length> at the memory location
B<data>. By setting the parameter B<copy> to B<1>, the callback can require the
SSL engine to increment the reference count of the SSL_SESSION object;
setting B<copy> to B<0> causes the reference count to remain unchanged.
If the get_session_cb() does not write to B<copy>, the reference count
is incremented and the session must be explicitly freed with
L<SSL_SESSION_free(3)>.
=head1 RETURN VALUES
@@ -104,7 +113,7 @@ L<SSL_CTX_free(3)>
=head1 COPYRIGHT
Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

67
doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod
View File

@@ -3,7 +3,9 @@
=head1 NAME
SSL_CTX_set_stateless_cookie_generate_cb,
SSL_CTX_set_stateless_cookie_verify_cb
SSL_CTX_set_stateless_cookie_verify_cb,
SSL_CTX_set_cookie_generate_cb,
SSL_CTX_set_cookie_verify_cb
- Callback functions for stateless TLS1.3 cookies
=head1 SYNOPSIS
@@ -21,22 +23,51 @@ SSL_CTX_set_stateless_cookie_verify_cb
const unsigned char *cookie,
size_t cookie_len));
void SSL_CTX_set_cookie_generate_cb(SSL_CTX *ctx,
int (*app_gen_cookie_cb) (SSL *ssl,
unsigned char
*cookie,
unsigned int
*cookie_len));
void SSL_CTX_set_cookie_verify_cb(SSL_CTX *ctx,
int (*app_verify_cookie_cb) (SSL *ssl,
const unsigned
char *cookie,
unsigned int
cookie_len));
=head1 DESCRIPTION
SSL_CTX_set_cookie_generate_cb() sets the callback used by L<SSL_stateless(3)>
to generate the application-controlled portion of the cookie provided to clients
in the HelloRetryRequest transmitted as a response to a ClientHello with a
missing or invalid cookie. gen_stateless_cookie_cb() must write at most
SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number of bytes
written to B<cookie_len>. If a cookie cannot be generated, a zero return value
can be used to abort the handshake.
SSL_CTX_set_stateless_cookie_generate_cb() sets the callback used by
L<SSL_stateless(3)> to generate the application-controlled portion of the cookie
provided to clients in the HelloRetryRequest transmitted as a response to a
ClientHello with a missing or invalid cookie. gen_stateless_cookie_cb() must
write at most SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number
of bytes written to B<cookie_len>. If a cookie cannot be generated, a zero
return value can be used to abort the handshake.
SSL_CTX_set_cookie_verify_cb() sets the callback used by L<SSL_stateless(3)> to
determine whether the application-controlled portion of a ClientHello cookie is
valid. A nonzero return value from app_verify_cookie_cb() communicates that the
cookie is valid. The integrity of the entire cookie, including the
application-controlled portion, is automatically verified by HMAC before
verify_stateless_cookie_cb() is called.
SSL_CTX_set_stateless_cookie_verify_cb() sets the callback used by
L<SSL_stateless(3)> to determine whether the application-controlled portion of a
ClientHello cookie is valid. The cookie data is pointed to by B<cookie> and is of
length B<cookie_len>. A nonzero return value from verify_stateless_cookie_cb()
communicates that the cookie is valid. The integrity of the entire cookie,
including the application-controlled portion, is automatically verified by HMAC
before verify_stateless_cookie_cb() is called.
SSL_CTX_set_cookie_generate_cb() sets the callback used by L<DTLSv1_listen(3)>
to generate the cookie provided to clients in the HelloVerifyRequest transmitted
as a response to a ClientHello with a missing or invalid cookie.
app_gen_cookie_cb() must write at most DTLS1_COOKIE_LENGTH bytes into
B<cookie>, and must write the number of bytes written to B<cookie_len>. If a
cookie cannot be generated, a zero return value can be used to abort the
handshake.
SSL_CTX_set_cookie_verify_cb() sets the callback used by L<DTLSv1_listen(3)> to
determine whether the cookie in a ClientHello is valid. The cookie data is
pointed to by B<cookie> and is of length B<cookie_len>. A nonzero return value
from app_verify_cookie_cb() communicates that the cookie is valid. The
integrity of the cookie is not verified by OpenSSL. This is an application
responsibility.
=head1 RETURN VALUES
@@ -44,7 +75,13 @@ Neither function returns a value.
=head1 SEE ALSO
L<SSL_stateless(3)>
L<SSL_stateless(3)>,
L<DTLSv1_listen(3)>
=head1 HISTORY
SSL_CTX_set_stateless_cookie_generate_cb() and
SSL_CTX_set_stateless_cookie_verify_cb() were added in OpenSSL 1.1.1.
=head1 COPYRIGHT

122
doc/man3/SSL_CTX_set_tlsext_servername_callback.pod
View File

@@ -11,7 +11,7 @@ SSL_set_tlsext_host_name - handle server name indication (SNI)
#include <openssl/ssl.h>
long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx,
int (*cb)(SSL *, int *, void *));
int (*cb)(SSL *s, int *al, void *arg));
long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg);
const char *SSL_get_servername(const SSL *s, const int type);
@@ -21,21 +21,106 @@ SSL_set_tlsext_host_name - handle server name indication (SNI)
=head1 DESCRIPTION
The functionality provided by the servername callback is superseded by the
ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb().
The servername callback is retained for historical compatibility.
The functionality provided by the servername callback is mostly superseded by
the ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb().
However, even where the ClientHello callback is used, the servername callback is
still necessary in order to acknowledge the servername requested by the client.
SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
used by a server to perform any actions or configuration required based on
the servername extension received in the incoming connection. When B<cb>
is NULL, SNI is not used. The B<arg> value is a pointer which is passed to
the application callback.
is NULL, SNI is not used.
The servername callback should return one of the following values:
=over 4
=item SSL_TLSEXT_ERR_OK
This is used to indicate that the servername requested by the client has been
accepted. Typically a server will call SSL_set_SSL_CTX() in the callback to set
up a different configuration for the selected servername in this case.
=item SSL_TLSEXT_ERR_ALERT_FATAL
In this case the servername requested by the client is not accepted and the
handshake will be aborted. The value of the alert to be used should be stored in
the location pointed to by the B<al> parameter to the callback. By default this
value is initialised to SSL_AD_UNRECOGNIZED_NAME.
=item SSL_TLSEXT_ERR_ALERT_WARNING
If this value is returned then the servername is not accepted by the server.
However the handshake will continue and send a warning alert instead. The value
of the alert should be stored in the location pointed to by the B<al> parameter
as for SSL_TLSEXT_ERR_ALERT_FATAL above. Note that TLSv1.3 does not support
warning alerts, so if TLSv1.3 has been negotiated then this return value is
treated the same way as SSL_TLSEXT_ERR_NOACK.
=item SSL_TLSEXT_ERR_NOACK
This return value indicates that the servername is not accepted by the server.
No alerts are sent and the server will not acknowledge the requested servername.
=back
SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be
passed into the callback for this B<SSL_CTX>.
passed into the callback (via the B<arg> parameter) for this B<SSL_CTX>.
SSL_get_servername() returns a servername extension value of the specified
type if provided in the Client Hello or NULL.
The behaviour of SSL_get_servername() depends on a number of different factors.
In particular note that in TLSv1.3 the servername is negotiated in every
handshake. In TLSv1.2 the servername is only negotiated on initial handshakes
and not on resumption handshakes.
=over 4
=item On the client, before the handshake
If a servername has been set via a call to SSL_set_tlsext_host_name() then it
will return that servername.
If one has not been set, but a TLSv1.2 resumption is being attempted and the
session from the original handshake had a servername accepted by the server then
it will return that servername.
Otherwise it returns NULL.
=item On the client, during or after the handshake and a TLSv1.2 (or below)
resumption occurred
If the session from the orignal handshake had a servername accepted by the
server then it will return that servername.
Otherwise it returns the servername set via SSL_set_tlsext_host_name() or NULL
if it was not called.
=item On the client, during or after the handshake and a TLSv1.2 (or below)
resumption did not occur
It will return the servername set via SSL_set_tlsext_host_name() or NULL if it
was not called.
=item On the server, before the handshake
The function will always return NULL before the handshake
=item On the server, after the servername extension has been processed and a
TLSv1.2 (or below) resumption occurred
If a servername was accepted by the server in the original handshake then it
will return that servername, or NULL otherwise.
=item On the server, after the servername extension has been processed and a
TLSv1.2 (or below) resumption did not occur
The function will return the servername requested by the client in this
handshake or NULL if none was requested.
=back
Note that the ClientHello callback occurs before a servername extension from the
client is processed. The servername, certificate and ALPN callbacks occur after
a servername extension from the client is processed.
SSL_get_servername_type() returns the servername type or -1 if no servername
is present. Currently the only supported type (defined in RFC3546) is
@@ -65,9 +150,26 @@ SSL_set_tlsext_host_name() returns 1 on success, 0 in case of error.
L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>,
L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)>
=head1 HISTORY
SSL_get_servername() historically provided some unexpected results in certain
corner cases. This has been fixed from OpenSSL 1.1.1e.
Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2
handshake, the server accepted it, and then the client successfully resumed but
set a different explict servername in the second handshake then when called by
the client it returned the servername from the second handshake. This has now
been changed to return the servername requested in the original handshake.
Also prior to 1.1.1e, if the client sent a servername in the first handshake but
the server did not accept it, and then a second handshake occured where TLSv1.2
resumption was successful then when called by the server it returned the
servername requested in the original handshake. This has now been changed to
NULL.
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

6
doc/man3/SSL_CTX_use_psk_identity_hint.pod
View File

@@ -39,9 +39,9 @@ SSL_set_psk_find_session_callback
=head1 DESCRIPTION
A client application wishing to use TLSv1.3 PSKs should set a callback
using either SSL_CTX_set_psk_use_session_callback() or
SSL_set_psk_use_session_callback() as appropriate.
A server application wishing to use TLSv1.3 PSKs should set a callback
using either SSL_CTX_set_psk_find_session_callback() or
SSL_set_psk_find_session_callback() as appropriate.
The callback function is given a pointer to the SSL connection in B<ssl> and
an identity in B<identity> of length B<identity_len>. The callback function

7
doc/man3/SSL_SESSION_get0_hostname.pod
View File

@@ -24,7 +24,10 @@ SSL_SESSION_set1_alpn_selected
=head1 DESCRIPTION
SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the
client when the session was created, or NULL if no value was sent.
client when the session was created if it was accepted by the server and TLSv1.2
or below was negotiated. Otherwise NULL is returned. Note that in TLSv1.3 the
SNI hostname is negotiated with each handshake including resumption handshakes
and is therefore never associated with the session.
The value returned is a pointer to memory maintained within B<s> and
should not be free'd.
@@ -64,7 +67,7 @@ SSL_SESSION_set1_alpn_selected() functions were added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

4
doc/man3/SSL_accept.pod
View File

@@ -56,7 +56,7 @@ established.
The TLS/SSL handshake was not successful because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
not clean. It can also occur of action is need to continue the operation
not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -72,7 +72,7 @@ L<SSL_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

4
doc/man3/SSL_connect.pod
View File

@@ -71,7 +71,7 @@ established.
The TLS/SSL handshake was not successful, because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
not clean. It can also occur of action is need to continue the operation
not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -87,7 +87,7 @@ L<SSL_CTX_new(3)>
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

4
doc/man3/SSL_do_handshake.pod
View File

@@ -57,7 +57,7 @@ established.
The TLS/SSL handshake was not successful because a fatal error occurred either
at the protocol level or a connection failure occurred. The shutdown was
not clean. It can also occur of action is need to continue the operation
not clean. It can also occur if action is needed to continue the operation
for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
to find out the reason.
@@ -71,7 +71,7 @@ L<SSL_set_connect_state(3)>
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

14
doc/man3/SSL_get_error.pod
View File

@@ -155,6 +155,18 @@ connection and SSL_shutdown() must not be called.
=back
=head1 BUGS
The B<SSL_ERROR_SYSCALL> with B<errno> value of 0 indicates unexpected EOF from
the peer. This will be properly reported as B<SSL_ERROR_SSL> with reason
code B<SSL_R_UNEXPECTED_EOF_WHILE_READING> in the OpenSSL 3.0 release because
it is truly a TLS protocol error to terminate the connection without
a SSL_shutdown().
The issue is kept unfixed in OpenSSL 1.1.1 releases because many applications
which choose to ignore this protocol error depend on the existing way of
reporting the error.
=head1 SEE ALSO
L<ssl(7)>
@@ -166,7 +178,7 @@ The SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

19
doc/man3/SSL_load_client_CA_file.pod
View File

@@ -2,7 +2,10 @@
=head1 NAME
SSL_load_client_CA_file - load certificate names from file
SSL_load_client_CA_file,
SSL_add_file_cert_subjects_to_stack,
SSL_add_dir_cert_subjects_to_stack
- load certificate names
=head1 SYNOPSIS
@@ -10,11 +13,23 @@ SSL_load_client_CA_file - load certificate names from file
STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
const char *file)
int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
const char *dir)
=head1 DESCRIPTION
SSL_load_client_CA_file() reads certificates from B<file> and returns
SSL_load_client_CA_file() reads certificates from I<file> and returns
a STACK_OF(X509_NAME) with the subject names found.
SSL_add_file_cert_subjects_to_stack() reads certificates from I<file>,
and adds their subject name to the already existing I<stack>.
SSL_add_dir_cert_subjects_to_stack() reads certificates from every
file in the directory I<dir>, and adds their subject name to the
already existing I<stack>.
=head1 NOTES
SSL_load_client_CA_file() reads a file of PEM formatted certificates and

212
doc/man3/X509_LOOKUP.pod Normal file
View File

@@ -0,0 +1,212 @@
=pod
=head1 NAME
X509_LOOKUP, X509_LOOKUP_TYPE,
X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init,
X509_LOOKUP_shutdown,
X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data,
X509_LOOKUP_ctrl,
X509_LOOKUP_load_file, X509_LOOKUP_add_dir,
X509_LOOKUP_get_store, X509_LOOKUP_by_subject,
X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint,
X509_LOOKUP_by_alias
- OpenSSL certificate lookup mechanisms
=head1 SYNOPSIS
#include <openssl/x509_vfy.h>
typedef x509_lookup_st X509_LOOKUP;
typedef enum X509_LOOKUP_TYPE;
X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method);
int X509_LOOKUP_init(X509_LOOKUP *ctx);
int X509_LOOKUP_shutdown(X509_LOOKUP *ctx);
void X509_LOOKUP_free(X509_LOOKUP *ctx);
int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc,
long argl, char **ret);
int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type);
int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type);
X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, X509_OBJECT *ret);
int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, ASN1_INTEGER *serial,
X509_OBJECT *ret);
int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
const unsigned char *bytes, int len,
X509_OBJECT *ret);
int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
const char *str, int len, X509_OBJECT *ret);
=head1 DESCRIPTION
The B<X509_LOOKUP> structure holds the information needed to look up
certificates and CRLs according to an associated L<X509_LOOKUP_METHOD(3)>.
Multiple B<X509_LOOKUP> instances can be added to an L<X509_STORE(3)>
to enable lookup in that store.
X509_LOOKUP_new() creates a new B<X509_LOOKUP> using the given lookup
I<method>.
It can also be created by calling L<X509_STORE_add_lookup(3)>, which
will associate an B<X509_STORE> with the lookup mechanism.
X509_LOOKUP_init() initializes the internal state and resources as
needed by the given B<X509_LOOKUP> to do its work.
X509_LOOKUP_shutdown() tears down the internal state and resources of
the given B<X509_LOOKUP>.
X509_LOOKUP_free() destructs the given B<X509_LOOKUP>.
X509_LOOKUP_set_method_data() associates a pointer to application data
to the given B<X509_LOOKUP>.
X509_LOOKUP_get_method_data() retrieves a pointer to application data
from the given B<X509_LOOKUP>.
X509_LOOKUP_ctrl() is used to set or get additional data to or from an
B<X509_LOOKUP> structure or its associated L<X509_LOOKUP_METHOD(3)>.
The arguments of the control command are passed via I<argc> and I<argl>,
its return value via I<*ret>.
The meaning of the arguments depends on the I<cmd> number of the
control command. In general, this function is not called directly, but
wrapped by a macro call, see below.
The control I<cmd>s known to OpenSSL are discussed in more depth
in L</Control Commands>.
X509_LOOKUP_load_file() passes a filename to be loaded immediately
into the associated B<X509_STORE>.
I<type> indicates what type of object is expected.
This can only be used with a lookup using the implementation
L<X509_LOOKUP_file(3)>.
X509_LOOKUP_add_dir() passes a directory specification from which
certificates and CRLs are loaded on demand into the associated
B<X509_STORE>.
I<type> indicates what type of object is expected.
This can only be used with a lookup using the implementation
L<X509_LOOKUP_hash_dir(3)>.
X509_LOOKUP_load_file(), X509_LOOKUP_add_dir(),
X509_LOOKUP_add_store(), and X509_LOOKUP_load_store() are implemented
as macros that use X509_LOOKUP_ctrl().
X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() look up
certificates and CRLs in the L<X509_STORE(3)> associated with the
B<X509_LOOKUP> using different criteria, where the looked up object is
stored in I<ret>.
Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects
matching the criteria in the associated B<X509_STORE>, which makes it
possible to handle cases where the criteria have more than one hit.
=head2 File Types
X509_LOOKUP_load_file() and X509_LOOKUP_add_dir() take a I<type>,
which can be one of the following:
=over 4
=item B<X509_FILETYPE_PEM>
The file or files that are loaded are expected to be in PEM format.
=item B<X509_FILETYPE_ASN1>
The file or files that are loaded are expected to be in raw DER format.
=item B<X509_FILETYPE_DEFAULT>
The default certificate file or directory is used. In this case,
I<name> is ignored.
=begin comment
TODO
Document X509_get_default_cert_file_env(3),
X509_get_default_cert_file(3), X509_get_default_cert_dir_env(3) and
X509_get_default_cert_dir(3) and link to them here.
=end comment
=back
=head2 Control Commands
The B<X509_LOOKUP_METHOD>s built into OpenSSL recognise the following
X509_LOOKUP_ctrl() I<cmd>s:
=over 4
=item B<X509_L_FILE_LOAD>
This is the command that X509_LOOKUP_load_file() uses.
The filename is passed in I<argc>, and the type in I<argl>.
=item B<X509_L_ADD_DIR>
This is the command that X509_LOOKUP_add_dir() uses.
The directory specification is passed in I<argc>, and the type in
I<argl>.
=item B<X509_L_ADD_STORE>
This is the command that X509_LOOKUP_add_store() uses.
The URI is passed in I<argc>.
=item B<X509_L_LOAD_STORE>
This is the command that X509_LOOKUP_load_store() uses.
The URI is passed in I<argc>.
=back
=head1 RETURN VALUES
X509_LOOKUP_new() returns an B<X509_LOOKUP> pointer when successful,
or NULL on error.
X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or
0 on error.
X509_LOOKUP_ctrl() returns -1 if the B<X509_LOOKUP> doesn't have an
associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD>
doesn't have a control function.
Otherwise, it returns what the control function in the
B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
error.
X509_LOOKUP_get_store() returns an B<X509_STORE> pointer if there is
one, otherwise NULL.
X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() all return 0
if there is no B<X509_LOOKUP_METHOD> or that method doesn't implement
the corresponding function.
Otherwise, it returns what the corresponding function in the
B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
error.
=head1 SEE ALSO
L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)>
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/man3/X509_LOOKUP_meth_new.pod
View File

@@ -2,6 +2,7 @@
=head1 NAME
X509_LOOKUP_METHOD,
X509_LOOKUP_meth_new, X509_LOOKUP_meth_free, X509_LOOKUP_meth_set_new_item,
X509_LOOKUP_meth_get_new_item, X509_LOOKUP_meth_set_free,
X509_LOOKUP_meth_get_free, X509_LOOKUP_meth_set_init,
@@ -16,14 +17,15 @@ X509_LOOKUP_get_by_fingerprint_fn, X509_LOOKUP_meth_set_get_by_fingerprint,
X509_LOOKUP_meth_get_get_by_fingerprint,
X509_LOOKUP_get_by_alias_fn, X509_LOOKUP_meth_set_get_by_alias,
X509_LOOKUP_meth_get_get_by_alias,
X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data,
X509_LOOKUP_get_store, X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
- Routines to build up X509_LOOKUP methods
=head1 SYNOPSIS
#include <openssl/x509_vfy.h>
typedef x509_lookup_method_st X509_LOOKUP_METHOD;
X509_LOOKUP_METHOD *X509_LOOKUP_meth_new(const char *name);
void X509_LOOKUP_meth_free(X509_LOOKUP_METHOD *method);
@@ -92,11 +94,6 @@ X509_LOOKUP_get_store, X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
X509_LOOKUP_get_by_alias_fn X509_LOOKUP_meth_get_get_by_alias(
const X509_LOOKUP_METHOD *method);
int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
int X509_OBJECT_set1_X509(X509_OBJECT *a, X509 *obj);
int X509_OBJECT_set1_X509_CRL(X509_OBJECT *a, X509_CRL *obj);
@@ -118,7 +115,7 @@ X509_LOOKUP_get_new_item() and X509_LOOKUP_set_new_item() get and set the
function that is called when an B<X509_LOOKUP> object is created with
X509_LOOKUP_new(). If an X509_LOOKUP_METHOD requires any per-X509_LOOKUP
specific data, the supplied new_item function should allocate this data and
invoke X509_LOOKUP_set_method_data().
invoke L<X509_LOOKUP_set_method_data(3)>.
X509_LOOKUP_get_free() and X509_LOOKUP_set_free() get and set the function
that is used to free any method data that was allocated and set from within
@@ -126,7 +123,7 @@ new_item function.
X509_LOOKUP_meth_get_init() and X509_LOOKUP_meth_set_init() get and set the
function that is used to initialize the method data that was set with
X509_LOOKUP_set_method_data() as part of the new_item routine.
L<X509_LOOKUP_set_method_data(3)> as part of the new_item routine.
X509_LOOKUP_meth_get_shutdown() and X509_LOOKUP_meth_set_shutdown() get and set
the function that is used to shut down the method data whose state was
@@ -164,9 +161,9 @@ increments the result's reference count.
Any method data that was created as a result of the new_item function
set by X509_LOOKUP_meth_set_new_item() can be accessed with
X509_LOOKUP_get_method_data(). The B<X509_STORE> object that owns the
X509_LOOKUP may be accessed with X509_LOOKUP_get_store(). Successful lookups
should return 1, and unsuccessful lookups should return 0.
L<X509_LOOKUP_get_method_data(3)>. The B<X509_STORE> object that owns the
X509_LOOKUP may be accessed with L<X509_LOOKUP_get_store(3)>. Successful
lookups should return 1, and unsuccessful lookups should return 0.
X509_LOOKUP_get_get_by_subject(), X509_LOOKUP_get_get_by_issuer_serial(),
X509_LOOKUP_get_get_by_fingerprint(), X509_LOOKUP_get_get_by_alias() retrieve
@@ -189,7 +186,7 @@ The functions described here were added in OpenSSL 1.1.0i.
=head1 COPYRIGHT
Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

2
doc/man3/X509_STORE_CTX_new.pod
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);

17
doc/man3/X509_STORE_add_cert.pod
View File

@@ -2,8 +2,10 @@
=head1 NAME
X509_STORE,
X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth,
X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust,
X509_STORE_add_lookup,
X509_STORE_load_locations,
X509_STORE_set_default_paths
- X509_STORE manipulation
@@ -12,6 +14,8 @@ X509_STORE_set_default_paths
#include <openssl/x509_vfy.h>
typedef x509_store_st X509_STORE;
int X509_STORE_add_cert(X509_STORE *ctx, X509 *x);
int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x);
int X509_STORE_set_depth(X509_STORE *store, int depth);
@@ -19,6 +23,9 @@ X509_STORE_set_default_paths
int X509_STORE_set_purpose(X509_STORE *ctx, int purpose);
int X509_STORE_set_trust(X509_STORE *ctx, int trust);
X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store,
X509_LOOKUP_METHOD *meth);
int X509_STORE_load_locations(X509_STORE *ctx,
const char *file, const char *dir);
int X509_STORE_set_default_paths(X509_STORE *ctx);
@@ -65,6 +72,11 @@ for the corresponding values used in certificate chain validation. Their
behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual
pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>.
X509_STORE_add_lookup() finds or creates a L<X509_LOOKUP(3)> with the
L<X509_LOOKUP_METHOD(3)> I<meth> and adds it to the B<X509_STORE>
I<store>. This also associates the B<X509_STORE> with the lookup, so
B<X509_LOOKUP> functions can look up objects in that store.
X509_STORE_load_locations() loads trusted certificate(s) into an
B<X509_STORE> from a given file and/or directory path. It is permitted
to specify just a file, just a directory, or both paths. The certificates
@@ -83,6 +95,9 @@ X509_STORE_set_flags(), X509_STORE_set_purpose(),
X509_STORE_set_trust(), X509_STORE_load_locations(), and
X509_STORE_set_default_paths() return 1 on success or 0 on failure.
X509_STORE_add_lookup() returns the found or created
L<X509_LOOKUP(3)>, or NULL on error.
=head1 SEE ALSO
L<X509_LOOKUP_hash_dir(3)>.
@@ -92,7 +107,7 @@ L<X509_STORE_get0_param(3)>
=head1 COPYRIGHT
Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

13
doc/man3/X509_get_extension_flags.pod
View File

@@ -80,6 +80,17 @@ The certificate contains an unhandled critical extension.
Some certificate extension values are invalid or inconsistent. The
certificate should be rejected.
This bit may also be raised after an out-of-memory error while
processing the X509 object, so it may not be related to the processed
ASN1 object itself.
=item B<EXFLAG_INVALID_POLICY>
The NID_certificate_policies certificate extension is invalid or
inconsistent. The certificate should be rejected.
This bit may also be raised after an out-of-memory error while
processing the X509 object, so it may not be related to the processed
ASN1 object itself.
=item B<EXFLAG_KUSAGE>
@@ -183,7 +194,7 @@ X509_get_proxy_pathlen() were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

5
doc/man3/d2i_X509.pod
View File

@@ -307,7 +307,6 @@ i2d_POLICYQUALINFO,
i2d_PROFESSION_INFO,
i2d_PROXY_CERT_INFO_EXTENSION,
i2d_PROXY_POLICY,
i2d_PublicKey,
i2d_RSAPrivateKey,
i2d_RSAPrivateKey_bio,
i2d_RSAPrivateKey_fp,
@@ -461,7 +460,7 @@ Represents an ASN1 OBJECT IDENTIFIER.
Represents a PKCS#3 DH parameters structure.
=item B<DHparamx>
=item B<DHxparams>
Represents an ANSI X9.42 DH parameters structure.
@@ -611,7 +610,7 @@ efficiency reasons.
=head1 COPYRIGHT
Copyright 1998-2019 The OpenSSL Project Authors. All Rights Reserved.
Copyright 1998-2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy