From aa144ced5d61b5c7fb74acaebb37d85bd08f0416 Mon Sep 17 00:00:00 2001 From: Jung-uk Kim Date: Tue, 17 Mar 2020 21:27:57 +0000 Subject: Import OpenSSL 1.1.1e. --- doc/man3/ASN1_INTEGER_get_int64.pod | 4 +- doc/man3/ASN1_TYPE_get.pod | 4 +- doc/man3/BIO_f_buffer.pod | 20 +- doc/man3/BIO_get_ex_new_index.pod | 6 +- doc/man3/DTLSv1_listen.pod | 12 +- doc/man3/EC_GROUP_copy.pod | 90 +++++---- doc/man3/EC_GROUP_new.pod | 102 ++++++---- doc/man3/EC_POINT_new.pod | 20 ++ doc/man3/EVP_DigestInit.pod | 96 ++++++++-- doc/man3/EVP_DigestSignInit.pod | 10 +- doc/man3/EVP_DigestVerifyInit.pod | 2 +- doc/man3/EVP_EncryptInit.pod | 9 + doc/man3/EVP_MD_meth_new.pod | 21 +- doc/man3/EVP_PKEY_CTX_ctrl.pod | 16 +- doc/man3/EVP_PKEY_meth_new.pod | 32 +++- doc/man3/EVP_PKEY_new.pod | 31 +-- doc/man3/EVP_PKEY_size.pod | 80 ++++++++ doc/man3/EVP_SignInit.pod | 44 ++--- doc/man3/OCSP_request_add1_nonce.pod | 4 +- doc/man3/OCSP_response_status.pod | 4 +- doc/man3/OCSP_sendreq_new.pod | 9 +- doc/man3/OPENSSL_malloc.pod | 4 +- doc/man3/OPENSSL_secure_malloc.pod | 4 + doc/man3/PEM_bytes_read_bio.pod | 4 +- doc/man3/PEM_read_bio_PrivateKey.pod | 12 +- doc/man3/PEM_read_bio_ex.pod | 2 +- doc/man3/RAND_bytes.pod | 26 ++- doc/man3/RAND_set_rand_method.pod | 2 +- doc/man3/RSA_get0_key.pod | 7 +- doc/man3/SSL_CTX_sess_set_get_cb.pod | 57 +++--- .../SSL_CTX_set_stateless_cookie_generate_cb.pod | 69 +++++-- .../SSL_CTX_set_tlsext_servername_callback.pod | 122 +++++++++++- doc/man3/SSL_CTX_use_psk_identity_hint.pod | 6 +- doc/man3/SSL_SESSION_get0_hostname.pod | 7 +- doc/man3/SSL_accept.pod | 4 +- doc/man3/SSL_connect.pod | 4 +- doc/man3/SSL_do_handshake.pod | 4 +- doc/man3/SSL_load_client_CA_file.pod | 19 +- doc/man3/X509_LOOKUP.pod | 212 +++++++++++++++++++++ doc/man3/X509_LOOKUP_meth_new.pod | 23 +-- doc/man3/X509_STORE_CTX_new.pod | 2 +- doc/man3/X509_STORE_add_cert.pod | 17 +- doc/man3/d2i_X509.pod | 5 +- 43 files changed, 951 insertions(+), 277 deletions(-) create mode 100644 doc/man3/EVP_PKEY_size.pod create mode 100644 doc/man3/X509_LOOKUP.pod (limited to 'doc/man3') diff --git a/doc/man3/ASN1_INTEGER_get_int64.pod b/doc/man3/ASN1_INTEGER_get_int64.pod index 9b73290742d4..ac6a5799df9d 100644 --- a/doc/man3/ASN1_INTEGER_get_int64.pod +++ b/doc/man3/ASN1_INTEGER_get_int64.pod @@ -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); diff --git a/doc/man3/ASN1_TYPE_get.pod b/doc/man3/ASN1_TYPE_get.pod index 70c56878b8e6..fb797220a47f 100644 --- a/doc/man3/ASN1_TYPE_get.pod +++ b/doc/man3/ASN1_TYPE_get.pod @@ -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 match. So +unparsable type which returns NULL) for types which do B 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 diff --git a/doc/man3/BIO_f_buffer.pod b/doc/man3/BIO_f_buffer.pod index 8ceaaa3c0343..047a11d2407c 100644 --- a/doc/man3/BIO_f_buffer.pod +++ b/doc/man3/BIO_f_buffer.pod @@ -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. =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 diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod index e61228f1caea..89008531d381 100644 --- a/doc/man3/BIO_get_ex_new_index.pod +++ b/doc/man3/BIO_get_ex_new_index.pod @@ -39,7 +39,7 @@ L. 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 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. =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 diff --git a/doc/man3/DTLSv1_listen.pod b/doc/man3/DTLSv1_listen.pod index 76be40b68f10..98511a475f9f 100644 --- a/doc/man3/DTLSv1_listen.pod +++ b/doc/man3/DTLSv1_listen.pod @@ -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 and L +respectively. For SSL_stateless(), L +and L 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, L, -L, L +L, L, +L, +L, L, +L, L, L =head1 HISTORY diff --git a/doc/man3/EC_GROUP_copy.pod b/doc/man3/EC_GROUP_copy.pod index 7bf350062375..0d50fdc0c74f 100644 --- a/doc/man3/EC_GROUP_copy.pod +++ b/doc/man3/EC_GROUP_copy.pod @@ -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 into B. Both B and B must use the same EC_METHOD. +EC_GROUP_copy() copies the curve B into B. Both B and B must use the same EC_METHOD. -EC_GROUP_dup creates a new EC_GROUP object and copies the content from B to the newly created +EC_GROUP_dup() creates a new EC_GROUP object and copies the content from B to the newly created EC_GROUP object. -EC_GROUP_method_of obtains the EC_METHOD of B. +EC_GROUP_method_of() obtains the EC_METHOD of B. -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, the B and the B. The B 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. The B multiplied by the B gives the number of points on the curve. -EC_GROUP_get0_generator returns the generator for the identified B. +EC_GROUP_get0_generator() returns the generator for the identified B. -The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B and B parameters -with the respective order and cofactors for the B. +EC_GROUP_get_order() retrieves the order of B and copies its value into +B. It fails in case B 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 and copies its value +into B. It fails in case B 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). 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 then the named curve form is used and the parameters must have a corresponding named curve NID set. If asn1_flags is B 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 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 and B to determine whether they represent the same curve or not. +EC_GROUP_cmp() compares B and 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. 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, +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. 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, B and B 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_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_get_order() returns 0 if the order is not set (or set to zero) for +B or if copying into B fails, 1 otherwise. + +EC_GROUP_get_cofactor() returns 0 if the cofactor is not set (or is set to zero) for B or if copying into B fails, 1 otherwise. -EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error. +EC_GROUP_get_curve_name() returns the curve name (NID) for B or will return NID_undef if no curve name is associated. -EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error. +EC_GROUP_get_asn1_flag() returns the ASN1 flag for the specified B . -EC_GROUP_get0_generator returns the generator for the given curve or NULL on error. +EC_GROUP_get_point_conversion_form() returns the point_conversion_form for B. -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_degree() returns the degree for B 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 ) for a +EC_GROUP_get_basis_type() returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in ) for a trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. =head1 SEE ALSO diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod index 1eee494927f5..c80b191785c4 100644 --- a/doc/man3/EC_GROUP_new.pod +++ b/doc/man3/EC_GROUP_new.pod @@ -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. 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 (see -L). 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 and -EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B. - -EC_GROUP_set_curve() sets the curve parameters B

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. +Operations in a binary field are performed relative to an B. 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 (see L). 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 and EC_GROUP_new_from_ecpkparameters() will create a group from the +specific PK B. + +EC_GROUP_set_curve() sets the curve parameters B

, B and B. For a curve +over Fp B

is the prime for the field. For a curve over F2^m B

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 and 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_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. - -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 should be an array of EC_builtin_curve structures of size B. The function -will populate the B array with information about the builtin curves. If B is less than the total number of -curves available, then the first B 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 or -not). Passing a NULL B, or setting B to 0 will do nothing other than return the total number of curves available. +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. + +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 should be an array of +EC_builtin_curve structures of size B. The function will populate the +B array with information about the builtin curves. If B is less than +the total number of curves available, then the first B 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 or not). Passing a NULL B, or setting B 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), and a human readable comment string describing the curve. +Each EC_builtin_curve item has a unique integer id (B), 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 of the curve to +In order to construct a builtin curve use the function +EC_GROUP_new_by_curve_name() and provide the B 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 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 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 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, L =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 diff --git a/doc/man3/EC_POINT_new.pod b/doc/man3/EC_POINT_new.pod index 796f6666dd38..8cadaa75f145 100644 --- a/doc/man3/EC_POINT_new.pod +++ b/doc/man3/EC_POINT_new.pod @@ -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

as an +octet string into the buffer B of size B, using the specified +conversion form B

. +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

from +the octet string contained in the given buffer B of size B, 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

, +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

. + +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 diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index 3e3e34229763..434e22030fdd 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -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 and frees up the space allocated to it. =item EVP_MD_CTX_ctrl() -Performs digest-specific control actions on context B. +Performs digest-specific control actions on context B. The control command +is indicated in B and any additional arguments in B and B. +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 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 flags. See L below for more information. +=item EVP_Digest() + +A wrapper around the Digest Init_ex, Update and Final_ex functions. +Hashes B bytes of data at B using a digest B from ENGINE +B. The digest value is placed in B and its length is written at B +if the pointer is not NULL. At most B bytes will be written. +If B is NULL the default implementation of digest B is used. + =item EVP_DigestInit_ex() Sets up digest context B to use a digest B from ENGINE B. @@ -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 structure corresponding to the passed B. +=item EVP_MD_CTX_set_update_fn() + +Sets the update function for B to B. +This is the function that is called by EVP_DigestUpdate. If not set, the +update function from the B type specified at initialization is used. + +=item EVP_MD_CTX_update_fn() + +Returns the update function for B. + +=item EVP_MD_flags() + +Returns the B flags. Note that these are different from the B +ones. See L 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 structure when passed a digest name, a digest B or an B structure respectively. +=item EVP_MD_CTX_pkey_ctx() + +Returns the B assigned to B. The returned pointer should not +be freed by the caller. + =item EVP_MD_CTX_set_pkey_ctx() Assigns an B to B. This is usually used to provide -a customzied B to L or +a customized B to L or L. The B passed to this function should be freed by the caller. A NULL B pointer is also allowed to clear the B assigned to B. In such case, freeing the cleared B or not @@ -193,6 +234,27 @@ depends on how the B 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. + +=item EVP_MD_CTRL_XOF_LEN + +This control sets the digest length for extendable output functions to B. +Sending this control directly should not be necessary, the use of +C 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, L, L diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod index 0bbc3d0ff8f3..912880a5e1c5 100644 --- a/doc/man3/EVP_DigestSignInit.pod +++ b/doc/man3/EVP_DigestSignInit.pod @@ -36,7 +36,7 @@ EVP_MD_CTX is freed). The digest B may be NULL if the signing algorithm supports it. No B will be created by EVP_DigestSignInit() if the passed B -has already been assigned one via L. See also L. +has already been assigned one via L. See also L. 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. @@ -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 diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod index 05b99bb913ce..0806cd5d58c4 100644 --- a/doc/man3/EVP_DigestVerifyInit.pod +++ b/doc/man3/EVP_DigestVerifyInit.pod @@ -33,7 +33,7 @@ inside EVP_DigestVerifyInit() and it will be freed automatically when the EVP_MD_CTX is freed). No B will be created by EVP_DigestSignInit() if the passed B -has already been assigned one via L. See also L. +has already been assigned one via L. See also L. EVP_DigestVerifyUpdate() hashes B bytes of data at B into the verification context B. This function can be called several times on the diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 6b068617b0ad..aaf9975c4c26 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -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 and I 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 flag treated specially in +EVP_CipherInit_ex(). + EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros. =head1 BUGS diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod index 0265c7d50456..e17a4cd519ab 100644 --- a/doc/man3/EVP_MD_meth_new.pod +++ b/doc/man3/EVP_MD_meth_new.pod @@ -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 control. =item EVP_MD_FLAG_DIGALGID_NULL @@ -105,19 +110,24 @@ B as default. I 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. -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. -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. -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 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. +See L 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 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 diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 75fad0f70ce0..16d8462a4263 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -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 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 @@ -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. If not specified 1024 is used. +for DSA parameter generation to B. 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 for DSA parameter generation to B. 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 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. If not specified, one of SHA-1, SHA-224, or +SHA-256 is selected to match the bit length of B above. =head2 DH parameters diff --git a/doc/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod index 8a167ce0d6ff..106873d9acc1 100644 --- a/doc/man3/EVP_PKEY_meth_new.pod +++ b/doc/man3/EVP_PKEY_meth_new.pod @@ -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, diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod index ebe20986dba1..667269cc624e 100644 --- a/doc/man3/EVP_PKEY_new.pod +++ b/doc/man3/EVP_PKEY_new.pod @@ -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 with raw -private key data. The number of bytes written is populated in B<*len>. If the -buffer B 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, B, B, B, -B, B or B. +private key data. The size of the B 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 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, B, B, +B, B, B or B. EVP_PKEY_get_raw_public_key() fills the buffer provided by B with raw -public key data. The number of bytes written is populated in B<*len>. If the -buffer B 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, B, B or B. +public key data. The size of the B 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 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, B, B or +B. =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 diff --git a/doc/man3/EVP_PKEY_size.pod b/doc/man3/EVP_PKEY_size.pod new file mode 100644 index 000000000000..786c5039142c --- /dev/null +++ b/doc/man3/EVP_PKEY_size.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +EVP_PKEY_size, EVP_PKEY_bits, EVP_PKEY_security_bits +- EVP_PKEY information functions + +=head1 SYNOPSIS + + #include + + 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. +The primary documented use is with L and +L, but it isn't limited there. The returned size is +also large enough for the output buffer of L, +L, L, L. + +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 (the I argument will +receive that length), to avoid bugs. + +EVP_PKEY_bits() returns the cryptographic length of the cryptosystem +to which the key in I 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, 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. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=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. + +=cut diff --git a/doc/man3/EVP_SignInit.pod b/doc/man3/EVP_SignInit.pod index c26b7f7d5d22..22ce747d333f 100644 --- a/doc/man3/EVP_SignInit.pod +++ b/doc/man3/EVP_SignInit.pod @@ -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 to use digest -B from ENGINE B. B must be created with +EVP_SignInit_ex() sets up signing context I to use digest +I from B I. I must be created with EVP_MD_CTX_new() before calling this function. -EVP_SignUpdate() hashes B bytes of data at B into the -signature context B. This function can be called several times on the -same B to include additional data. +EVP_SignUpdate() hashes I bytes of data at I into the +signature context I. This function can be called several times on the +same I to include additional data. -EVP_SignFinal() signs the data in B using the private key B and -places the signature in B. B must be at least EVP_PKEY_size(pkey) -bytes in size. B is an OUT parameter, and not used as an IN parameter. +EVP_SignFinal() signs the data in I using the private key I and +places the signature in I. I must be at least C +bytes in size. I 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, at most EVP_PKEY_size(pkey) bytes +will be written to the integer at I, at most C bytes will be written. -EVP_SignInit() initializes a signing context B to use the default -implementation of digest B. - -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, -bits of security is defined in NIST SP800-57. +EVP_SignInit() initializes a signing context I to use the default +implementation of digest I. =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. -EVP_PKEY_security_bits() returns the number of security bits. - =head1 NOTES The B 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, L, L, L, L, L, L, L, @@ -103,7 +89,7 @@ L, L =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 diff --git a/doc/man3/OCSP_request_add1_nonce.pod b/doc/man3/OCSP_request_add1_nonce.pod index 66e4c7b8fb78..81bf645108f3 100644 --- a/doc/man3/OCSP_request_add1_nonce.pod +++ b/doc/man3/OCSP_request_add1_nonce.pod @@ -24,7 +24,7 @@ it adds a nonce to OCSP basic response B. OCSP_check_nonce() compares the nonce value in B and B. -OCSP_copy_nonce() copys any nonce value present in B to B. +OCSP_copy_nonce() copies any nonce value present in B to B. =head1 RETURN VALUES @@ -74,7 +74,7 @@ L =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 diff --git a/doc/man3/OCSP_response_status.pod b/doc/man3/OCSP_response_status.pod index 82f95b3af1d1..e7e22e4cb549 100644 --- a/doc/man3/OCSP_response_status.pod +++ b/doc/man3/OCSP_response_status.pod @@ -58,7 +58,7 @@ with the X509 certificate B. OCSP_basic_sign() signs OCSP response B using certificate B, private key B, digest B and additional certificates B. If the B option -B is set then no certificates will be included in the request. If the +B is set then no certificates will be included in the response. If the B option B is set then the responder is identified by key ID rather than by name. OCSP_basic_sign_ctx() also signs OCSP response B but uses the parameters contained in digest context B. @@ -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 diff --git a/doc/man3/OCSP_sendreq_new.pod b/doc/man3/OCSP_sendreq_new.pod index 65ba235c104e..a129a16bf23c 100644 --- a/doc/man3/OCSP_sendreq_new.pod +++ b/doc/man3/OCSP_sendreq_new.pod @@ -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 to B. 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, the URL -path B, the OCSP request B and with a response header maximum line -length of B. If B is zero a default value of 4k is used. +path B, and the OCSP request B with a response header maximum line +length 4k. It waits indefinitely on a response. =head1 RETURN VALUES @@ -112,7 +111,7 @@ L =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 diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 2d678c951f0a..c60e038309a1 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -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 diff --git a/doc/man3/OPENSSL_secure_malloc.pod b/doc/man3/OPENSSL_secure_malloc.pod index 6c395383513b..86c2522afe49 100644 --- a/doc/man3/OPENSSL_secure_malloc.pod +++ b/doc/man3/OPENSSL_secure_malloc.pod @@ -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. diff --git a/doc/man3/PEM_bytes_read_bio.pod b/doc/man3/PEM_bytes_read_bio.pod index 3a5bfee9969f..eb2fb2059ee7 100644 --- a/doc/man3/PEM_bytes_read_bio.pod +++ b/doc/man3/PEM_bytes_read_bio.pod @@ -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 for the data type given in I (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, L, L diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod index 7c381e85feff..a8306500fb3c 100644 --- a/doc/man3/PEM_read_bio_PrivateKey.pod +++ b/doc/man3/PEM_read_bio_PrivateKey.pod @@ -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 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 type>. + The B functions process DSA parameters using a DSA structure. The parameters are encoded using a Dss-Parms structure as defined in RFC2459. diff --git a/doc/man3/PEM_read_bio_ex.pod b/doc/man3/PEM_read_bio_ex.pod index a16b0ede5a9c..9748e74e0f77 100644 --- a/doc/man3/PEM_read_bio_ex.pod +++ b/doc/man3/PEM_read_bio_ex.pod @@ -52,7 +52,7 @@ PEM_read_bio_ex() returns 1 for success or 0 for failure. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod index e2265d170a61..c44c2f967607 100644 --- a/doc/man3/RAND_bytes.pod +++ b/doc/man3/RAND_bytes.pod @@ -19,8 +19,8 @@ Deprecated: =head1 DESCRIPTION -RAND_bytes() puts B cryptographically strong pseudo-random bytes -into B. +RAND_bytes() generates B random bytes using a cryptographically +secure pseudo random generator (CSPRNG) and stores them in B. 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. =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 diff --git a/doc/man3/RAND_set_rand_method.pod b/doc/man3/RAND_set_rand_method.pod index 83a6cac17a51..b120e712e6f3 100644 --- a/doc/man3/RAND_set_rand_method.pod +++ b/doc/man3/RAND_set_rand_method.pod @@ -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. diff --git a/doc/man3/RSA_get0_key.pod b/doc/man3/RSA_get0_key.pod index 358c2de256f9..adcd57c49071 100644 --- a/doc/man3/RSA_get0_key.pod +++ b/doc/man3/RSA_get0_key.pod @@ -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 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, L =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(), diff --git a/doc/man3/SSL_CTX_sess_set_get_cb.pod b/doc/man3/SSL_CTX_sess_set_get_cb.pod index 774c4b120f6e..d30f84d78a28 100644 --- a/doc/man3/SSL_CTX_sess_set_get_cb.pod +++ b/doc/man3/SSL_CTX_sess_set_get_cb.pod @@ -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/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 interface. -The new_session_cb() is called, whenever a new session has been negotiated -and session caching is enabled (see -L). -The new_session_cb() is passed the B connection and the ssl session -B. 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). The +new_session_cb() is passed the B connection and the nascent +ssl session B. +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 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 is called. The remove_session_cb() is passed the B and the ssl session B. 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 connection, the session id of length B at the memory location -B. With the parameter B 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 connection and the session id of length B at the memory location +B. By setting the parameter B to B<1>, the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object; +setting B to B<0> causes the reference count to remain unchanged. +If the get_session_cb() does not write to B, the reference count +is incremented and the session must be explicitly freed with L. =head1 RETURN VALUES @@ -104,7 +113,7 @@ L =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 diff --git a/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod index f29153ed25d8..aa167f6332ed 100644 --- a/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod +++ b/doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod @@ -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 -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, and must write the number of bytes -written to B. 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 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_generate_cb() sets the callback used by +L 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, and must write the number +of bytes written to B. If a cookie cannot be generated, a zero +return value can be used to abort the handshake. + +SSL_CTX_set_stateless_cookie_verify_cb() sets the callback used by +L to determine whether the application-controlled portion of a +ClientHello cookie is valid. The cookie data is pointed to by B and is of +length B. 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 +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, and must write the number of bytes written to B. 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 to +determine whether the cookie in a ClientHello is valid. The cookie data is +pointed to by B and is of length B. 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 +L, +L + +=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 diff --git a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod index b1fb5ab7d9fa..e971035734e1 100644 --- a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod +++ b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod @@ -11,7 +11,7 @@ SSL_set_tlsext_host_name - handle server name indication (SNI) #include 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 used by a server to perform any actions or configuration required based on the servername extension received in the incoming connection. When B -is NULL, SNI is not used. The B 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 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 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. +passed into the callback (via the B parameter) for this B. + +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. -SSL_get_servername() returns a servername extension value of the specified -type if provided in the Client Hello or 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, L, L, L +=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 diff --git a/doc/man3/SSL_CTX_use_psk_identity_hint.pod b/doc/man3/SSL_CTX_use_psk_identity_hint.pod index c8f7526610a8..0957ade5e106 100644 --- a/doc/man3/SSL_CTX_use_psk_identity_hint.pod +++ b/doc/man3/SSL_CTX_use_psk_identity_hint.pod @@ -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 and an identity in B of length B. The callback function diff --git a/doc/man3/SSL_SESSION_get0_hostname.pod b/doc/man3/SSL_SESSION_get0_hostname.pod index 475f700a88c5..6e39cbc656dd 100644 --- a/doc/man3/SSL_SESSION_get0_hostname.pod +++ b/doc/man3/SSL_SESSION_get0_hostname.pod @@ -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 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 diff --git a/doc/man3/SSL_accept.pod b/doc/man3/SSL_accept.pod index 335655f0c8c8..b1595f7acf34 100644 --- a/doc/man3/SSL_accept.pod +++ b/doc/man3/SSL_accept.pod @@ -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 to find out the reason. @@ -72,7 +72,7 @@ L =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 diff --git a/doc/man3/SSL_connect.pod b/doc/man3/SSL_connect.pod index 426b8ad757db..f7d9e57db622 100644 --- a/doc/man3/SSL_connect.pod +++ b/doc/man3/SSL_connect.pod @@ -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 to find out the reason. @@ -87,7 +87,7 @@ L =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 diff --git a/doc/man3/SSL_do_handshake.pod b/doc/man3/SSL_do_handshake.pod index a1b973f7b80a..8852f9d3e3dc 100644 --- a/doc/man3/SSL_do_handshake.pod +++ b/doc/man3/SSL_do_handshake.pod @@ -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 to find out the reason. @@ -71,7 +71,7 @@ L =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 diff --git a/doc/man3/SSL_load_client_CA_file.pod b/doc/man3/SSL_load_client_CA_file.pod index a6cfb308d30c..f354ef4177dc 100644 --- a/doc/man3/SSL_load_client_CA_file.pod +++ b/doc/man3/SSL_load_client_CA_file.pod @@ -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 and returns +SSL_load_client_CA_file() reads certificates from I and returns a STACK_OF(X509_NAME) with the subject names found. +SSL_add_file_cert_subjects_to_stack() reads certificates from I, +and adds their subject name to the already existing I. + +SSL_add_dir_cert_subjects_to_stack() reads certificates from every +file in the directory I

, and adds their subject name to the +already existing I. + =head1 NOTES SSL_load_client_CA_file() reads a file of PEM formatted certificates and diff --git a/doc/man3/X509_LOOKUP.pod b/doc/man3/X509_LOOKUP.pod new file mode 100644 index 000000000000..3e0bb6ab221c --- /dev/null +++ b/doc/man3/X509_LOOKUP.pod @@ -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 + + 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 structure holds the information needed to look up +certificates and CRLs according to an associated L. +Multiple B instances can be added to an L +to enable lookup in that store. + +X509_LOOKUP_new() creates a new B using the given lookup +I. +It can also be created by calling L, which +will associate an B with the lookup mechanism. + +X509_LOOKUP_init() initializes the internal state and resources as +needed by the given B to do its work. + +X509_LOOKUP_shutdown() tears down the internal state and resources of +the given B. + +X509_LOOKUP_free() destructs the given B. + +X509_LOOKUP_set_method_data() associates a pointer to application data +to the given B. + +X509_LOOKUP_get_method_data() retrieves a pointer to application data +from the given B. + +X509_LOOKUP_ctrl() is used to set or get additional data to or from an +B structure or its associated L. +The arguments of the control command are passed via I and I, +its return value via I<*ret>. +The meaning of the arguments depends on the I number of the +control command. In general, this function is not called directly, but +wrapped by a macro call, see below. +The control Is known to OpenSSL are discussed in more depth +in L. + +X509_LOOKUP_load_file() passes a filename to be loaded immediately +into the associated B. +I indicates what type of object is expected. +This can only be used with a lookup using the implementation +L. + +X509_LOOKUP_add_dir() passes a directory specification from which +certificates and CRLs are loaded on demand into the associated +B. +I indicates what type of object is expected. +This can only be used with a lookup using the implementation +L. + +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 associated with the +B using different criteria, where the looked up object is +stored in I. +Some of the underlying Bs will also cache objects +matching the criteria in the associated B, 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, +which can be one of the following: + +=over 4 + +=item B + +The file or files that are loaded are expected to be in PEM format. + +=item B + +The file or files that are loaded are expected to be in raw DER format. + +=item B + +The default certificate file or directory is used. In this case, +I 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 Bs built into OpenSSL recognise the following +X509_LOOKUP_ctrl() Is: + +=over 4 + +=item B + +This is the command that X509_LOOKUP_load_file() uses. +The filename is passed in I, and the type in I. + +=item B + +This is the command that X509_LOOKUP_add_dir() uses. +The directory specification is passed in I, and the type in +I. + +=item B + +This is the command that X509_LOOKUP_add_store() uses. +The URI is passed in I. + +=item B + +This is the command that X509_LOOKUP_load_store() uses. +The URI is passed in I. + +=back + +=head1 RETURN VALUES + +X509_LOOKUP_new() returns an B 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 doesn't have an +associated B, or 1 if the X<509_LOOKUP_METHOD> +doesn't have a control function. +Otherwise, it returns what the control function in the +B returns, which is usually 1 on success and 0 in +error. + +X509_LOOKUP_get_store() returns an B 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 or that method doesn't implement +the corresponding function. +Otherwise, it returns what the corresponding function in the +B returns, which is usually 1 on success and 0 in +error. + +=head1 SEE ALSO + +L, L + +=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. + +=cut diff --git a/doc/man3/X509_LOOKUP_meth_new.pod b/doc/man3/X509_LOOKUP_meth_new.pod index e5f0a098b3fa..a4e7466395dd 100644 --- a/doc/man3/X509_LOOKUP_meth_new.pod +++ b/doc/man3/X509_LOOKUP_meth_new.pod @@ -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 + 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 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_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 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 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. The B object that owns the +X509_LOOKUP may be accessed with L. 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 diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod index 472db508bc4e..c5042858be85 100644 --- a/doc/man3/X509_STORE_CTX_new.pod +++ b/doc/man3/X509_STORE_CTX_new.pod @@ -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); diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod index 3ea5b8b1272f..d840bd6d69bf 100644 --- a/doc/man3/X509_STORE_add_cert.pod +++ b/doc/man3/X509_STORE_add_cert.pod @@ -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 + 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 manual pages, e.g., L. +X509_STORE_add_lookup() finds or creates a L with the +L I and adds it to the B +I. This also associates the B with the lookup, so +B functions can look up objects in that store. + X509_STORE_load_locations() loads trusted certificate(s) into an B 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, or NULL on error. + =head1 SEE ALSO L. @@ -92,7 +107,7 @@ L =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 diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index e36270f73940..a8319bd4715b 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -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 +=item B 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 -- cgit v1.2.3

, B and B. For a curve over Fp B -is the prime for the field. For a curve over F2^m B