diff options
Diffstat (limited to 'doc')
83 files changed, 344 insertions, 221 deletions
diff --git a/doc/HOWTO/certificates.txt b/doc/HOWTO/certificates.txt index 78ab97b41928..82ce502a1d3d 100644 --- a/doc/HOWTO/certificates.txt +++ b/doc/HOWTO/certificates.txt @@ -89,7 +89,7 @@ was kind enough, your certificate is a raw DER thing in PEM format. Your key most definitely is if you have followed the examples above. However, some (most?) certificate authorities will encode them with things like PKCS7 or PKCS12, or something else. Depending on your -applications, this may be perfectly OK, it all depends on what they +applications, this may be perfectly OK. It all depends on what they know how to decode. If not, there are a number of OpenSSL tools to convert between some (most?) formats. diff --git a/doc/fingerprints.txt b/doc/fingerprints.txt index 9613cbac9848..bdcad1472309 100644 --- a/doc/fingerprints.txt +++ b/doc/fingerprints.txt @@ -12,9 +12,6 @@ in the file named openssl-1.0.1h.tar.gz.asc. The following is the list of fingerprints for the keys that are currently in use to sign OpenSSL distributions: -OpenSSL OMC: -EFC0 A467 D613 CB83 C7ED 6D30 D894 E2CE 8B3D 79F5 - OpenSSL: BA54 73A2 B058 7B07 FB27 CF2D 2160 94DF D0CB 81EF diff --git a/doc/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in index e6d5103bd91a..a47e783e2d63 100644 --- a/doc/man1/openssl-enc.pod.in +++ b/doc/man1/openssl-enc.pod.in @@ -97,13 +97,19 @@ Base64 process the data. This means that if encryption is taking place the data is base64 encoded after encryption. If decryption is set then the input data is base64 decoded before being decrypted. +When the B<-A> option not given, +on encoding a newline is inserted after each 64 characters, and +on decoding a newline is expected among the first 1024 bytes of input. + =item B<-base64> Same as B<-a> =item B<-A> -If the B<-a> option is set then base64 process the data on one line. +If the B<-a> option is set then base64 encoding produces output without any +newline character, and base64 decoding does not require any newlines. +Therefore it can be helpful to use the B<-A> option when decoding unknown input. =item B<-k> I<password> @@ -434,6 +440,9 @@ Base64 decode a file then decrypt it using a password supplied in a file: =head1 BUGS The B<-A> option when used with large files doesn't work properly. +On the other hand, when base64 decoding without the B<-A> option, +if the first 1024 bytes of input do not include a newline character +the first two lines of input are ignored. The B<openssl enc> command only supports a fixed number of algorithms with certain parameters. So if, for example, you want to use RC2 with a @@ -449,7 +458,7 @@ The B<-ciphers> and B<-engine> options were deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man1/openssl-passphrase-options.pod b/doc/man1/openssl-passphrase-options.pod index abc43fb41e6f..2260dce8a650 100644 --- a/doc/man1/openssl-passphrase-options.pod +++ b/doc/man1/openssl-passphrase-options.pod @@ -46,26 +46,32 @@ the environment of other processes is visible on certain platforms =item B<file:>I<pathname> -The first line of I<pathname> is the password. If the same I<pathname> -argument is supplied to B<-passin> and B<-passout> arguments then the first -line will be used for the input password and the next line for the output -password. I<pathname> need not refer to a regular file: it could for example -refer to a device or named pipe. +Reads the password from the specified file I<pathname>, which can be a regular +file, device, or named pipe. Only the first line, up to the newline character, +is read from the stream. + +If the same I<pathname> argument is supplied to both B<-passin> and B<-passout> +arguments, the first line will be used for the input password, and the next +line will be used for the output password. =item B<fd:>I<number> -Read the password from the file descriptor I<number>. This can be used to -send the data via a pipe for example. +Reads the password from the file descriptor I<number>. This can be useful for +sending data via a pipe, for example. The same line handling as described for +B<file:> applies to passwords read from file descriptors. + +B<fd:> is not supported on Windows. =item B<stdin> -Read the password from standard input. +Reads the password from standard input. The same line handling as described for +B<file:> applies to passwords read from standard input. =back =head1 COPYRIGHT -Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 4b7b58b72d55..bd6171aa265c 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -616,7 +616,11 @@ For example strings, see L<SSL_CTX_set1_sigalgs(3)> =item B<-curves> I<curvelist> Specifies the list of supported curves to be sent by the client. The curve is -ultimately selected by the server. For a list of all curves, use: +ultimately selected by the server. + +The list of all supported groups includes named EC parameters as well as X25519 +and X448 or FFDHE groups, and may also include groups implemented in 3rd-party +providers. For a list of named EC parameters, use: $ openssl ecparam -list_curves @@ -910,7 +914,7 @@ The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index 319f1e342b48..99a252a82254 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -641,7 +641,10 @@ Signature algorithms to support for client certificate authentication =item B<-named_curve> I<val> Specifies the elliptic curve to use. NOTE: this is single curve, not a list. -For a list of all possible curves, use: + +The list of all supported groups includes named EC parameters as well as X25519 +and X448 or FFDHE groups, and may also include groups implemented in 3rd-party +providers. For a list of named EC parameters, use: $ openssl ecparam -list_curves @@ -930,7 +933,7 @@ option were deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod index 4998e452b549..bf9ed9c1a62e 100644 --- a/doc/man1/openssl-verification-options.pod +++ b/doc/man1/openssl-verification-options.pod @@ -430,7 +430,7 @@ This option may be used multiple times. =item B<-policy> I<arg> Enable policy processing and add I<arg> to the user-initial-policy-set (see -RFC5280). The policy I<arg> can be an object name an OID in numeric form. +RFC5280). The policy I<arg> can be an object name or an OID in numeric form. This argument can appear more than once. =item B<-explicit_policy> @@ -686,7 +686,7 @@ The checks enabled by B<-x509_strict> have been extended in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/ASN1_INTEGER_new.pod b/doc/man3/ASN1_INTEGER_new.pod index 4722f880c0b2..869ac754f4b7 100644 --- a/doc/man3/ASN1_INTEGER_new.pod +++ b/doc/man3/ASN1_INTEGER_new.pod @@ -18,6 +18,7 @@ ASN1_INTEGER_new, ASN1_INTEGER_free - ASN1_INTEGER allocation functions ASN1_INTEGER_new() returns an allocated B<ASN1_INTEGER> structure. ASN1_INTEGER_free() frees up a single B<ASN1_INTEGER> object. +If the argument is NULL, nothing is done. B<ASN1_INTEGER> structure representing the ASN.1 INTEGER type @@ -34,7 +35,7 @@ L<ERR_get_error(3)> =head1 COPYRIGHT -Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod index 7621a8b3a166..d85c51e5556d 100644 --- a/doc/man3/ASYNC_WAIT_CTX_new.pod +++ b/doc/man3/ASYNC_WAIT_CTX_new.pod @@ -178,6 +178,9 @@ operation, normally it is detected by a polling function or an interrupt, as the user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously, then the registered callback will be called. +ASYNC_WAIT_CTX_free() frees up a single B<ASYNC_WAIT_CTX> object. +If the argument is NULL, nothing is done. + =head1 RETURN VALUES ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated B<ASYNC_WAIT_CTX> @@ -216,7 +219,7 @@ were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/BIO_ADDR.pod b/doc/man3/BIO_ADDR.pod index 5ab88622cee0..12ec84d15ca0 100644 --- a/doc/man3/BIO_ADDR.pod +++ b/doc/man3/BIO_ADDR.pod @@ -38,6 +38,7 @@ with routines that will fill it with information, such as BIO_accept_ex(). BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new(). +If the argument is NULL, nothing is done. BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets it back to an uninitialised state. @@ -115,7 +116,7 @@ L<BIO_connect(3)>, L<BIO_s_connect(3)> =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/BIO_ADDRINFO.pod b/doc/man3/BIO_ADDRINFO.pod index 626052e7f8b9..71a14ff4f0d7 100644 --- a/doc/man3/BIO_ADDRINFO.pod +++ b/doc/man3/BIO_ADDRINFO.pod @@ -78,7 +78,7 @@ BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain from the given one. BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting -with the given one. +with the given one. If the argument is NULL, nothing is done. =head1 RETURN VALUES @@ -103,7 +103,7 @@ The BIO_lookup_ex() function was added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/BIO_f_base64.pod b/doc/man3/BIO_f_base64.pod index c865f0a17ac1..c951d4926190 100644 --- a/doc/man3/BIO_f_base64.pod +++ b/doc/man3/BIO_f_base64.pod @@ -21,25 +21,23 @@ any data read through it. Base64 BIOs do not support BIO_gets() or BIO_puts(). -For writing, output is by default divided to lines of length 64 -characters and there is always a newline at the end of output. +For writing, by default output is divided to lines of length 64 +characters and there is a newline at the end of output. +This behavior can be changed with B<BIO_FLAGS_BASE64_NO_NL> flag. -For reading, first line should be at most 1024 -characters long. If it is longer then it is ignored completely. -Other input lines can be of any length. There must be a newline -at the end of input. - -This behavior can be changed with BIO_FLAGS_BASE64_NO_NL flag. +For reading, first line should be at most 1024 bytes long including newline +unless the flag B<BIO_FLAGS_BASE64_NO_NL> is set. +Further input lines can be of any length (i.e., newlines may appear anywhere +in the input) and a newline at the end of input is not needed. BIO_flush() on a base64 BIO that is being written through is used to signal that no more data is to be encoded: this is used to flush the final block through the BIO. -The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags(). +The flag B<BIO_FLAGS_BASE64_NO_NL> can be set with BIO_set_flags(). For writing, it causes all data to be written on one line without newline at the end. -For reading, it expects the data to be all on one line (with or -without a trailing newline). +For reading, it removes all expectations on newlines in the input data. =head1 NOTES @@ -85,6 +83,10 @@ data to standard output: =head1 BUGS +On decoding, if the flag B<BIO_FLAGS_BASE64_NO_NL> is not set and +the first 1024 bytes of input do not include a newline character +the first two lines of input are ignored. + The ambiguity of EOF in base64 encoded data can cause additional data following the base64 encoded block to be misinterpreted. @@ -93,7 +95,7 @@ to reliably determine EOF (for example a MIME boundary). =head1 COPYRIGHT -Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/BIO_meth_new.pod b/doc/man3/BIO_meth_new.pod index 86301b97189f..d626277c03b1 100644 --- a/doc/man3/BIO_meth_new.pod +++ b/doc/man3/BIO_meth_new.pod @@ -76,7 +76,7 @@ additionally have the "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type(3)> page for more information. BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory -associated with it. +associated with it. If the argument is NULL, nothing is done. BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function used for writing arbitrary length data to the BIO respectively. This function @@ -157,7 +157,7 @@ The functions described here were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/BN_add.pod b/doc/man3/BN_add.pod index 35cfdd1495fd..46966d996379 100644 --- a/doc/man3/BN_add.pod +++ b/doc/man3/BN_add.pod @@ -14,9 +14,9 @@ arithmetic operations on BIGNUMs int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + int BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); + int BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx); int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, BN_CTX *ctx); @@ -25,25 +25,25 @@ arithmetic operations on BIGNUMs int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + int BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + int BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); + int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - BIGNUM *BN_mod_sqrt(BIGNUM *in, BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); + BIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); - int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); + int BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx); - int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + int BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx); - int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + int BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); =head1 DESCRIPTION @@ -135,7 +135,7 @@ L<BN_add_word(3)>, L<BN_set_bit(3)> =head1 COPYRIGHT -Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod index b536bcb3b781..accc8a749f0c 100644 --- a/doc/man3/BN_generate_prime.pod +++ b/doc/man3/BN_generate_prime.pod @@ -167,7 +167,8 @@ programs should prefer the "new" style, whilst the "old" style is provided for backwards compatibility purposes. A B<BN_GENCB> structure should be created through a call to BN_GENCB_new(), -and freed through a call to BN_GENCB_free(). +and freed through a call to BN_GENCB_free(). If the argument is NULL, +nothing is done. For "new" style callbacks a BN_GENCB structure should be initialised with a call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of @@ -245,7 +246,7 @@ BN_check_prime() was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/BN_set_bit.pod b/doc/man3/BN_set_bit.pod index 349ef9e0562c..ddc27d0c407a 100644 --- a/doc/man3/BN_set_bit.pod +++ b/doc/man3/BN_set_bit.pod @@ -33,8 +33,11 @@ error occurs if B<a> is shorter than B<n> bits. BN_is_bit_set() tests if bit B<n> in B<a> is set. BN_mask_bits() truncates B<a> to an B<n> bit number -(C<a&=~((~0)E<lt>E<lt>n)>). An error occurs if B<a> already is -shorter than B<n> bits. +(C<a&=~((~0)E<lt>E<lt>n)>). An error occurs if B<n> is negative. An error is +also returned if the internal representation of B<a> is already shorter than +B<n> bits. The internal representation depends on the platform's word size, and +this error can be safely ignored. Use L<BN_num_bits(3)> to determine the exact +number of bits if needed. BN_lshift() shifts B<a> left by B<n> bits and places the result in B<r> (C<r=a*2^n>). Note that B<n> must be nonnegative. BN_lshift1() shifts @@ -59,7 +62,7 @@ L<BN_num_bytes(3)>, L<BN_add(3)> =head1 COPYRIGHT -Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/BUF_MEM_new.pod b/doc/man3/BUF_MEM_new.pod index 262e18f31bfe..79de43a1df9a 100644 --- a/doc/man3/BUF_MEM_new.pod +++ b/doc/man3/BUF_MEM_new.pod @@ -34,6 +34,7 @@ should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>. BUF_MEM_free() frees up an already existing buffer. The data is zeroed before freeing up in case the buffer contains sensitive data. +If the argument is NULL, nothing is done. BUF_MEM_grow() changes the size of an already existing buffer to B<len>. Any data already in the buffer is preserved if it increases in @@ -65,7 +66,7 @@ The BUF_MEM_new_ex() function was added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod index a51679b97edd..420ff7278b26 100644 --- a/doc/man3/CRYPTO_THREAD_run_once.pod +++ b/doc/man3/CRYPTO_THREAD_run_once.pod @@ -69,6 +69,7 @@ CRYPTO_THREAD_unlock() unlocks the previously locked I<lock>. =item * CRYPTO_THREAD_lock_free() frees the provided I<lock>. +If the argument is NULL, nothing is done. =item * @@ -163,10 +164,13 @@ This example safely initializes and uses a lock. { int ret = 0; - if (mylock()) { - /* Your code here, do not return without releasing the lock! */ - ret = ... ; + if (!mylock()) { + /* Do not unlock unless the lock was successfully acquired. */ + return 0; } + + /* Your code here, do not return without releasing the lock! */ + ret = ... ; myunlock(); return ret; } @@ -183,7 +187,7 @@ L<crypto(7)>, L<openssl-threads(7)>. =head1 COPYRIGHT -Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/CTLOG_STORE_new.pod b/doc/man3/CTLOG_STORE_new.pod index 801b1447e155..361eda57b182 100644 --- a/doc/man3/CTLOG_STORE_new.pod +++ b/doc/man3/CTLOG_STORE_new.pod @@ -52,7 +52,7 @@ The expected format of the file is: Once a CTLOG_STORE is no longer required, it should be passed to CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along -with the CTLOG_STORE itself. +with the CTLOG_STORE itself. If the argument is NULL, nothing is done. =head1 NOTES @@ -78,7 +78,7 @@ added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/CTLOG_new.pod b/doc/man3/CTLOG_new.pod index 30b806824966..7a78a6c58dd3 100644 --- a/doc/man3/CTLOG_new.pod +++ b/doc/man3/CTLOG_new.pod @@ -50,7 +50,7 @@ property query string are used. Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that -was passed to it. +was passed to it. If the argument to CTLOG_free() is NULL, nothing is done. CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was created. Ownership of the string remains with the CTLOG. @@ -80,7 +80,7 @@ were added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/CT_POLICY_EVAL_CTX_new.pod b/doc/man3/CT_POLICY_EVAL_CTX_new.pod index bba6778d2deb..3b79980c43c2 100644 --- a/doc/man3/CT_POLICY_EVAL_CTX_new.pod +++ b/doc/man3/CT_POLICY_EVAL_CTX_new.pod @@ -105,7 +105,8 @@ The time should be in milliseconds since the Unix Epoch. Each setter has a matching getter for accessing the current value. When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to -CT_POLICY_EVAL_CTX_free() to delete it. +CT_POLICY_EVAL_CTX_free() to delete it. If the argument to +CT_POLICY_EVAL_CTX_free() is NULL, nothing is done. =head1 NOTES @@ -130,7 +131,7 @@ functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/DH_meth_new.pod b/doc/man3/DH_meth_new.pod index 43827f55ef8c..d5ba5eac565d 100644 --- a/doc/man3/DH_meth_new.pod +++ b/doc/man3/DH_meth_new.pod @@ -81,7 +81,7 @@ parameter. This might be useful for creating a new B<DH_METHOD> based on an existing one, but with some differences. DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory -associated with it. +associated with it. If the argument is NULL, nothing is done. DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This is a pointer to the internal name string and so should not be freed by the @@ -166,7 +166,7 @@ The functions described here were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/DSA_SIG_new.pod b/doc/man3/DSA_SIG_new.pod index 1f532d300065..158da2d7dd06 100644 --- a/doc/man3/DSA_SIG_new.pod +++ b/doc/man3/DSA_SIG_new.pod @@ -20,6 +20,7 @@ DSA_SIG_new() allocates an empty B<DSA_SIG> structure. DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The values are erased before the memory is returned to the system. +If the argument is NULL, nothing is done. DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained in B<sig>. @@ -48,7 +49,7 @@ L<ERR_get_error(3)> =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/DSA_meth_new.pod b/doc/man3/DSA_meth_new.pod index c00747cfc448..534561c61046 100644 --- a/doc/man3/DSA_meth_new.pod +++ b/doc/man3/DSA_meth_new.pod @@ -110,7 +110,7 @@ parameter. This might be useful for creating a new B<DSA_METHOD> based on an existing one, but with some differences. DSA_meth_free() destroys a B<DSA_METHOD> structure and frees up any memory -associated with it. +associated with it. If the argument is NULL, nothing is done. DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This is a pointer to the internal name string and so should not be freed by the @@ -214,7 +214,7 @@ The functions described here were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/ECDSA_SIG_new.pod b/doc/man3/ECDSA_SIG_new.pod index 3266c43b550c..e56ec959edff 100644 --- a/doc/man3/ECDSA_SIG_new.pod +++ b/doc/man3/ECDSA_SIG_new.pod @@ -31,6 +31,7 @@ ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure. Note: before OpenSSL 1.1.0, the I<r> and I<s> components were initialised. ECDSA_SIG_free() frees the B<ECDSA_SIG> structure I<sig>. +If the argument is NULL, nothing is done. ECDSA_SIG_get0() returns internal pointers the I<r> and I<s> values contained in I<sig> and stores them in I<*pr> and I<*ps>, respectively. @@ -136,7 +137,7 @@ L<ECDSA_sign(3)> =head1 COPYRIGHT -Copyright 2004-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2004-2024 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 diff --git a/doc/man3/ENGINE_add.pod b/doc/man3/ENGINE_add.pod index 55e5d76fcdb8..24c83c576476 100644 --- a/doc/man3/ENGINE_add.pod +++ b/doc/man3/ENGINE_add.pod @@ -227,7 +227,8 @@ references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next(), ENGINE_get_prev(). All structural references should be released by a corresponding to call to the ENGINE_free() function - the ENGINE object itself will only actually be cleaned up and deallocated when -the last structural reference is released. +the last structural reference is released. If the argument to ENGINE_free() +is NULL, nothing is done. It should also be noted that many ENGINE API function calls that accept a structural reference will internally obtain another reference - typically @@ -665,7 +666,7 @@ and should not be used. =head1 COPYRIGHT -Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2002-2024 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 diff --git a/doc/man3/EVP_ASYM_CIPHER_free.pod b/doc/man3/EVP_ASYM_CIPHER_free.pod index c158ec1ae74a..162ad7ed7687 100644 --- a/doc/man3/EVP_ASYM_CIPHER_free.pod +++ b/doc/man3/EVP_ASYM_CIPHER_free.pod @@ -45,7 +45,7 @@ The returned value must eventually be freed with EVP_ASYM_CIPHER_free(). EVP_ASYM_CIPHER_free() decrements the reference count for the B<EVP_ASYM_CIPHER> structure. Typically this structure will have been obtained from an earlier call to EVP_ASYM_CIPHER_fetch(). If the reference count drops to 0 then the -structure is freed. +structure is freed. If the argument is NULL, nothing is done. EVP_ASYM_CIPHER_up_ref() increments the reference count for an B<EVP_ASYM_CIPHER> structure. @@ -102,7 +102,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/EVP_CIPHER_meth_new.pod b/doc/man3/EVP_CIPHER_meth_new.pod index 8b862d9d99c8..8638cd3009c7 100644 --- a/doc/man3/EVP_CIPHER_meth_new.pod +++ b/doc/man3/EVP_CIPHER_meth_new.pod @@ -80,6 +80,7 @@ EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure. EVP_CIPHER_meth_dup() creates a copy of B<cipher>. EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure. +If the argument is NULL, nothing is done. EVP_CIPHER_meth_set_iv_length() sets the length of the IV. This is only needed when the implemented cipher mode requires it. @@ -249,7 +250,7 @@ counted in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index d7202c538172..de30191b61ac 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -157,6 +157,7 @@ Increments the reference count for an B<EVP_MD> structure. Decrements the reference count for the fetched B<EVP_MD> structure. If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. =item EVP_MD_CTX_new() @@ -170,6 +171,7 @@ existing context. =item EVP_MD_CTX_free() Cleans up digest context I<ctx> and frees up the space allocated to it. +If the argument is NULL, nothing is done. =item EVP_MD_CTX_ctrl() @@ -529,9 +531,13 @@ can be used the manipulate and test these B<EVP_MD_CTX> flags: This flag instructs the digest to optimize for one update only, if possible. -=for comment EVP_MD_CTX_FLAG_CLEANED is internal, don't mention it +=item EVP_MD_CTX_FLAG_CLEANED -=for comment EVP_MD_CTX_FLAG_REUSE is internal, don't mention it +This flag is for internal use only and I<must not> be used in user code. + +=item EVP_MD_CTX_FLAG_REUSE + +This flag is for internal use only and I<must not> be used in user code. =for comment We currently avoid documenting flags that are only bit holder: EVP_MD_CTX_FLAG_NON_FIPS_ALLOW, EVP_MD_CTX_FLAGS_PAD_* diff --git a/doc/man3/EVP_EncodeInit.pod b/doc/man3/EVP_EncodeInit.pod index 2b9e02e02d79..03c6f4e60579 100644 --- a/doc/man3/EVP_EncodeInit.pod +++ b/doc/man3/EVP_EncodeInit.pod @@ -41,7 +41,7 @@ EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for the encode/decode functions. EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the -space allocated to it. +space allocated to it. If the argument is NULL, nothing is done. Encoding of binary data is performed in blocks of 48 input bytes (or less for the final block). For each 48 byte input block encoded 64 bytes of base 64 data @@ -151,7 +151,7 @@ L<evp(7)> =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 12d7153d0fd4..f037d135c9da 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -268,6 +268,7 @@ Increments the reference count for an B<EVP_CIPHER> structure. Decrements the reference count for the fetched B<EVP_CIPHER> structure. If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. =item EVP_CIPHER_CTX_new() @@ -276,9 +277,9 @@ Allocates and returns a cipher context. =item EVP_CIPHER_CTX_free() Clears all information from a cipher context and frees any allocated memory -associated with it, including I<ctx> itself. This function should be called after -all operations using a cipher are complete so sensitive information does not -remain in memory. +associated with it, including I<ctx> itself. This function should be called +after all operations using a cipher are complete so sensitive information does +not remain in memory. If the argument is NULL, nothing is done. =item EVP_CIPHER_CTX_ctrl() @@ -360,9 +361,13 @@ exists. Encrypts I<inl> bytes from the buffer I<in> and writes the encrypted version to I<out>. The pointers I<out> and I<in> may point to the same location, in which -case the encryption will be done in-place. If I<out> and I<in> point to different -locations, the two buffers must be disjoint, otherwise the operation might fail -or the outcome might be undefined. +case the encryption will be done in-place. However, in-place encryption is +guaranteed to work only if the encryption context (I<ctx>) has processed data in +multiples of the block size. If the context contains an incomplete data block +from previous operations, in-place encryption will fail. + +If I<out> and I<in> point to different locations, the two buffers must be +disjoint, otherwise the operation might fail or the outcome might be undefined. This function can be called multiple times to encrypt successive blocks of data. The amount of data written depends on the block alignment of the @@ -1733,7 +1738,7 @@ The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/EVP_KEM_free.pod b/doc/man3/EVP_KEM_free.pod index 575abc5f5798..b0ef604757d7 100644 --- a/doc/man3/EVP_KEM_free.pod +++ b/doc/man3/EVP_KEM_free.pod @@ -41,6 +41,7 @@ The returned value must eventually be freed with EVP_KEM_free(). EVP_KEM_free() decrements the reference count for the B<EVP_KEM> structure. Typically this structure will have been obtained from an earlier call to EVP_KEM_fetch(). If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. EVP_KEM_up_ref() increments the reference count for an B<EVP_KEM> structure. @@ -95,7 +96,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod index 272855ccb3dd..e08f44e60c73 100644 --- a/doc/man3/EVP_KEYEXCH_free.pod +++ b/doc/man3/EVP_KEYEXCH_free.pod @@ -41,7 +41,7 @@ The returned value must eventually be freed with EVP_KEYEXCH_free(). EVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH> structure. Typically this structure will have been obtained from an earlier call to EVP_KEYEXCH_fetch(). If the reference count drops to 0 then the -structure is freed. +structure is freed. If the argument is NULL, nothing is done. EVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH> structure. @@ -101,7 +101,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/EVP_KEYMGMT.pod b/doc/man3/EVP_KEYMGMT.pod index 455ffadce5ec..4c0c3b776c64 100644 --- a/doc/man3/EVP_KEYMGMT.pod +++ b/doc/man3/EVP_KEYMGMT.pod @@ -62,6 +62,7 @@ B<EVP_KEYMGMT> I<keymgmt>. EVP_KEYMGMT_free() decrements the reference count for the given B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. EVP_KEYMGMT_get0_provider() returns the provider that has this particular implementation. @@ -140,7 +141,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod index a553c378f3d7..349797332376 100644 --- a/doc/man3/EVP_MD_meth_new.pod +++ b/doc/man3/EVP_MD_meth_new.pod @@ -74,6 +74,7 @@ EVP_MD_meth_dup() creates a copy of B<md>. EVP_MD_meth_free() decrements the reference count for the B<EVP_MD> structure. If the reference count drops to 0 then the structure is freed. +If the argument is NULL, nothing is done. EVP_MD_meth_set_input_blocksize() sets the internal input block size for the method B<md> to B<blocksize> bytes. @@ -194,7 +195,7 @@ counted in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2024 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 diff --git a/doc/man3/EVP_PKEY_ASN1_METHOD.pod b/doc/man3/EVP_PKEY_ASN1_METHOD.pod index cc50d363daf1..41f058fe54ee 100644 --- a/doc/man3/EVP_PKEY_ASN1_METHOD.pod +++ b/doc/man3/EVP_PKEY_ASN1_METHOD.pod @@ -393,7 +393,7 @@ This function is not thread safe, it's recommended to only use this when initializing the application. EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed -by B<ameth>. +by B<ameth>. If the argument is NULL, nothing is done. EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is @@ -439,7 +439,7 @@ parameter is now constified. =head1 COPYRIGHT -Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2024 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 diff --git a/doc/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod index db0b09f855fc..1b0adb2913f8 100644 --- a/doc/man3/EVP_PKEY_meth_new.pod +++ b/doc/man3/EVP_PKEY_meth_new.pod @@ -407,7 +407,7 @@ of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a digest signing operation by calling L<EVP_DigestSignFinal(3)>. EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by -B<pmeth>. +B<pmeth>. If the argument is NULL, nothing is done. EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src> to B<dst>. @@ -456,7 +456,7 @@ has changed in OpenSSL 3.0 so its I<src> parameter is now constified. =head1 COPYRIGHT -Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2024 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 diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod index 11ea807cc330..e5f75010499c 100644 --- a/doc/man3/EVP_RAND.pod +++ b/doc/man3/EVP_RAND.pod @@ -284,7 +284,7 @@ associated RAND ctx. Reads or set the number of elapsed seconds before reseeding the associated RAND ctx. -=item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> +=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer> Specifies the maximum number of bytes that can be generated in a single call to OSSL_FUNC_rand_generate. @@ -406,7 +406,7 @@ This functionality was added to OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/EVP_SIGNATURE.pod b/doc/man3/EVP_SIGNATURE.pod index 1f534ef33810..cf476d145315 100644 --- a/doc/man3/EVP_SIGNATURE.pod +++ b/doc/man3/EVP_SIGNATURE.pod @@ -49,7 +49,7 @@ The returned value must eventually be freed with EVP_SIGNATURE_free(). EVP_SIGNATURE_free() decrements the reference count for the B<EVP_SIGNATURE> structure. Typically this structure will have been obtained from an earlier call to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the -structure is freed. +structure is freed. If the argument is NULL, nothing is done. EVP_SIGNATURE_up_ref() increments the reference count for an B<EVP_SIGNATURE> structure. @@ -106,7 +106,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod index 87a567242f60..ebe69d2db9d3 100644 --- a/doc/man3/HMAC.pod +++ b/doc/man3/HMAC.pod @@ -87,7 +87,7 @@ created with HMAC_CTX_new(). HMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>, releases any associated resources and finally frees the B<HMAC_CTX> -itself. +itself. If the argument is NULL, nothing is done. The following functions may be used if the message is not completely stored in memory: @@ -163,7 +163,7 @@ OpenSSL before version 1.0.0. =head1 COPYRIGHT -Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/MD5.pod b/doc/man3/MD5.pod index 2e01fe8193dd..99bf82116015 100644 --- a/doc/man3/MD5.pod +++ b/doc/man3/MD5.pod @@ -7,12 +7,12 @@ MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions =head1 SYNOPSIS - #include <openssl/md2.h> - The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, see L<openssl_user_macros(7)>: + #include <openssl/md2.h> + unsigned char *MD2(const unsigned char *d, unsigned long n, unsigned char *md); int MD2_Init(MD2_CTX *c); @@ -20,25 +20,24 @@ see L<openssl_user_macros(7)>: int MD2_Final(unsigned char *md, MD2_CTX *c); - #include <openssl/md4.h> - The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, see L<openssl_user_macros(7)>: + #include <openssl/md4.h> + unsigned char *MD4(const unsigned char *d, unsigned long n, unsigned char *md); int MD4_Init(MD4_CTX *c); int MD4_Update(MD4_CTX *c, const void *data, unsigned long len); int MD4_Final(unsigned char *md, MD4_CTX *c); - - #include <openssl/md5.h> - The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, see L<openssl_user_macros(7)>: + #include <openssl/md5.h> + unsigned char *MD5(const unsigned char *d, unsigned long n, unsigned char *md); int MD5_Init(MD5_CTX *c); @@ -105,7 +104,7 @@ All of these functions were deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/NCONF_new_ex.pod b/doc/man3/NCONF_new_ex.pod index 6861fb198c10..d088ab2fed29 100644 --- a/doc/man3/NCONF_new_ex.pod +++ b/doc/man3/NCONF_new_ex.pod @@ -35,7 +35,7 @@ I<meth> is set to NULL then the default value of NCONF_default() is used. NCONF_new() is similar to NCONF_new_ex() but sets the I<libctx> to NULL. NCONF_free() frees the data associated with I<conf> and then frees the I<conf> -object. +object. If the argument is NULL, nothing is done. NCONF_load() parses the file named I<filename> and adds the values found to I<conf>. If an error occurs I<file> and I<eline> list the file and line that @@ -74,7 +74,7 @@ in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/OCSP_REQUEST_new.pod b/doc/man3/OCSP_REQUEST_new.pod index e34e591fe01b..3f171e822971 100644 --- a/doc/man3/OCSP_REQUEST_new.pod +++ b/doc/man3/OCSP_REQUEST_new.pod @@ -29,6 +29,7 @@ OCSP_request_onereq_get0 - OCSP request functions OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure. OCSP_REQUEST_free() frees up the request structure B<req>. +If the argument is NULL, nothing is done. OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns the B<OCSP_ONEREQ> structure added so an application can add additional @@ -108,7 +109,7 @@ L<OCSP_sendreq_new(3)> =head1 COPYRIGHT -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2024 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 diff --git a/doc/man3/OCSP_cert_to_id.pod b/doc/man3/OCSP_cert_to_id.pod index 298527f6bb25..e0fbdfa9eacb 100644 --- a/doc/man3/OCSP_cert_to_id.pod +++ b/doc/man3/OCSP_cert_to_id.pod @@ -38,6 +38,7 @@ issuer name B<issuerName>, issuer key hash B<issuerKey> and serial number B<serialNumber>. OCSP_CERTID_free() frees up B<id>. +If the argument is NULL, nothing is done. OCSP_id_cmp() compares B<OCSP_CERTID> B<a> and B<b>. @@ -79,7 +80,7 @@ L<OCSP_sendreq_new(3)> =head1 COPYRIGHT -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2024 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 diff --git a/doc/man3/OCSP_response_status.pod b/doc/man3/OCSP_response_status.pod index 7ff74923a53f..0902ae8a31bc 100644 --- a/doc/man3/OCSP_response_status.pod +++ b/doc/man3/OCSP_response_status.pod @@ -46,6 +46,7 @@ OCSP_response_create() creates and returns an I<OCSP_RESPONSE> structure for I<status> and optionally including basic response I<bs>. OCSP_RESPONSE_free() frees up OCSP response I<resp>. +If the argument is NULL, nothing is done. OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the subject name in the supplied X509 certificate I<cert> for the OCSP responder. @@ -123,7 +124,7 @@ The OCSP_basic_sign_ctx() function was added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2024 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 diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod index 688ef0edcb91..f62c57172cb7 100644 --- a/doc/man3/OPENSSL_LH_COMPFUNC.pod +++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod @@ -123,7 +123,7 @@ Then a hash table of B<I<TYPE>> objects can be created using this: B<lh_I<TYPE>_free>() frees the B<LHASH_OF>(B<I<TYPE>>) structure I<table>. Allocated hash table entries will not be freed; consider using B<lh_I<TYPE>_doall>() to deallocate any remaining entries in the -hash table (see below). +hash table (see below). If the argument is NULL, nothing is done. B<lh_I<TYPE>_flush>() empties the B<LHASH_OF>(B<I<TYPE>>) structure I<table>. New entries can be added to the flushed table. Allocated hash table entries @@ -299,7 +299,7 @@ type checking. =head1 COPYRIGHT -Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/OPENSSL_init_crypto.pod b/doc/man3/OPENSSL_init_crypto.pod index c3e72d274423..1363693c779b 100644 --- a/doc/man3/OPENSSL_init_crypto.pod +++ b/doc/man3/OPENSSL_init_crypto.pod @@ -249,6 +249,7 @@ If the B<CONF_MFLAGS_IGNORE_RETURN_CODES> flag is not included, any errors in the configuration file will cause an error return from B<OPENSSL_init_crypto> or indirectly L<OPENSSL_init_ssl(3)>. The object can be released with OPENSSL_INIT_free() when done. +If the argument to OPENSSL_INIT_free() is NULL, nothing is done. =head1 NOTES @@ -289,7 +290,7 @@ and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 76751012bde5..20441e76ac65 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -99,7 +99,8 @@ OPENSSL_zalloc() calls memset() to zero the memory before returning. OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used when the buffer at B<addr> holds sensitive information. The old buffer is filled with zero's by calling OPENSSL_cleanse() -before ultimately calling OPENSSL_free(). +before ultimately calling OPENSSL_free(). If the argument to OPENSSL_free() is +NULL, nothing is done. OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's. Use OPENSSL_cleanse() with care if the memory is a mapping of a file. @@ -198,7 +199,7 @@ clang's memory and leak sanitizer. =head1 COPYRIGHT -Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/OPENSSL_secure_malloc.pod b/doc/man3/OPENSSL_secure_malloc.pod index c5d4bb2dbbb8..1bddd7737069 100644 --- a/doc/man3/OPENSSL_secure_malloc.pod +++ b/doc/man3/OPENSSL_secure_malloc.pod @@ -82,13 +82,15 @@ If CRYPTO_secure_malloc_init() is not called, this is equivalent to calling OPENSSL_free(). It exists for consistency with OPENSSL_secure_malloc() , and is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__> -and C<__LINE__> parameters.. +and C<__LINE__> parameters.. If the argument to OPENSSL_secure_free() +is NULL, nothing is done. OPENSSL_secure_clear_free() is similar to OPENSSL_secure_free() except that it has an additional C<num> parameter which is used to clear the memory if it was not allocated from the secure heap. If CRYPTO_secure_malloc_init() is not called, this is equivalent to -calling OPENSSL_clear_free(). +calling OPENSSL_clear_free(). If the argument to OPENSSL_secure_clear_free() +is NULL, nothing is done. OPENSSL_secure_actual_size() tells the actual size allocated to the pointer; implementations may allocate more space than initially @@ -133,7 +135,7 @@ a B<size_t> in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2024 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 diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index ce7db8f2f086..cab88ae88c91 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -176,6 +176,7 @@ the message timeout is set to 120 seconds, and the proof-of-possession method is set to OSSL_CRMF_POPO_SIGNATURE. OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure. +If the argument is NULL, nothing is done. OSSL_CMP_CTX_reinit() prepares the given I<ctx> for a further transaction by clearing the internal CMP transaction (aka session) status, PKIStatusInfo, @@ -312,6 +313,11 @@ RFC 4210. Allow retrieving a trust anchor from extraCerts and using that to validate the certificate chain of an IP message. + This is a quirk option added to support 3GPP TS 33.310. + + Note that using this option is dangerous as the certificate obtained + this way has not been authenticated (at least not at CMP level). + Taking it over as a trust anchor implements trust-on-first-use (TOFU). =back @@ -796,7 +802,7 @@ OSSL_CMP_CTX_reset_geninfo_ITAVs() was added in OpenSSL 3.0.8. =head1 COPYRIGHT -Copyright 2007-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2007-2024 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 diff --git a/doc/man3/OSSL_CMP_SRV_CTX_new.pod b/doc/man3/OSSL_CMP_SRV_CTX_new.pod index d7f1a2e4dba7..12b1bfa88a1d 100644 --- a/doc/man3/OSSL_CMP_SRV_CTX_new.pod +++ b/doc/man3/OSSL_CMP_SRV_CTX_new.pod @@ -104,6 +104,7 @@ associated with the library context I<libctx> and property query string I<propq>, both of which may be NULL to select the defaults. OSSL_CMP_SRV_CTX_free() deletes the given I<srv_ctx>. +If the argument is NULL, nothing is done. OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context pointer as well as callback functions performing the specific processing of CMP @@ -158,7 +159,7 @@ The OpenSSL CMP support was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2007-2024 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 diff --git a/doc/man3/OSSL_CMP_validate_msg.pod b/doc/man3/OSSL_CMP_validate_msg.pod index 44c901210feb..555624a40358 100644 --- a/doc/man3/OSSL_CMP_validate_msg.pod +++ b/doc/man3/OSSL_CMP_validate_msg.pod @@ -40,11 +40,14 @@ using any trust store set via L<OSSL_CMP_CTX_set0_trustedStore(3)>. If the option OSSL_CMP_OPT_PERMIT_TA_IN_EXTRACERTS_FOR_IR was set by calling L<OSSL_CMP_CTX_set_option(3)>, for an Initialization Response (IP) message -any self-issued certificate from the I<msg> extraCerts field may also be used -as trust anchor for the path verification of an acceptable cert if it can be +any self-issued certificate from the I<msg> extraCerts field may be used +as a trust anchor for the path verification of an 'acceptable' cert if it can be used also to validate the issued certificate returned in the IP message. This is according to TS 33.310 [Network Domain Security (NDS); Authentication Framework (AF)] document specified by the The 3rd Generation Partnership Project (3GPP). +Note that using this option is dangerous as the certificate obtained this way +has not been authenticated (at least not at CMP level). +Taking it over as a trust anchor implements trust-on-first-use (TOFU). Any cert that has been found as described above is cached and tried first when validating the signatures of subsequent messages in the same transaction. @@ -74,7 +77,7 @@ The OpenSSL CMP support was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2007-2024 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 diff --git a/doc/man3/OSSL_DECODER.pod b/doc/man3/OSSL_DECODER.pod index dcfd72bf9738..633aa07f8fff 100644 --- a/doc/man3/OSSL_DECODER.pod +++ b/doc/man3/OSSL_DECODER.pod @@ -61,6 +61,7 @@ I<decoder>. OSSL_DECODER_free() decrements the reference count for the given I<decoder>, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. OSSL_DECODER_get0_provider() returns the provider of the given I<decoder>. @@ -180,7 +181,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/OSSL_DECODER_CTX.pod b/doc/man3/OSSL_DECODER_CTX.pod index 3ffd794cf0fb..bace3ee0cfed 100644 --- a/doc/man3/OSSL_DECODER_CTX.pod +++ b/doc/man3/OSSL_DECODER_CTX.pod @@ -126,6 +126,7 @@ decoders that have been added to the I<ctx> so far. Parameters that an implementation doesn't recognise should be ignored by it. OSSL_DECODER_CTX_free() frees the given context I<ctx>. +If the argument is NULL, nothing is done. OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX> I<ctx> with a decoder, to be used to attempt to decode some encoded input. @@ -249,7 +250,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod index acb04bc37623..e55212ad554b 100644 --- a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod +++ b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod @@ -82,7 +82,7 @@ choice of preferred pass phrase callback form. These are called indirectly, through an internal L<OSSL_PASSPHRASE_CALLBACK(3)> function. The internal L<OSSL_PASSPHRASE_CALLBACK(3)> function caches the pass phrase, to -be re-used in all decodings that are performed in the same decoding run (for +be reused in all decodings that are performed in the same decoding run (for example, within one L<OSSL_DECODER_from_bio(3)> call). =head2 Input Types @@ -135,7 +135,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/OSSL_ENCODER.pod b/doc/man3/OSSL_ENCODER.pod index 06d8f80f8812..bbf64b0b47bf 100644 --- a/doc/man3/OSSL_ENCODER.pod +++ b/doc/man3/OSSL_ENCODER.pod @@ -61,6 +61,7 @@ I<encoder>. OSSL_ENCODER_free() decrements the reference count for the given I<encoder>, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. OSSL_ENCODER_get0_provider() returns the provider of the given I<encoder>. @@ -134,7 +135,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/OSSL_ENCODER_CTX.pod b/doc/man3/OSSL_ENCODER_CTX.pod index 7f3915fda882..e9248c356a05 100644 --- a/doc/man3/OSSL_ENCODER_CTX.pod +++ b/doc/man3/OSSL_ENCODER_CTX.pod @@ -102,6 +102,7 @@ with an L<OSSL_PARAM(3)> array I<params>. Parameters that the implementation doesn't recognise should be ignored. OSSL_ENCODER_CTX_free() frees the given context I<ctx>. +If the argument is NULL, nothing is done. OSSL_ENCODER_CTX_add_encoder() populates the B<OSSL_ENCODER_CTX> I<ctx> with a encoder, to be used to encode an input object. @@ -211,7 +212,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod index 6216420e4ffe..d6c4cdfa0ca7 100644 --- a/doc/man3/OSSL_HTTP_REQ_CTX.pod +++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod @@ -71,6 +71,7 @@ which collects the HTTP request header lines. OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>. The I<rbio> is not free'd, I<wbio> will be free'd if I<free_wbio> is set. +If the argument is NULL, nothing is done. OSSL_HTTP_REQ_CTX_set_request_line() adds the 1st HTTP request line to I<rctx>. The HTTP method is determined by I<method_POST>, @@ -260,7 +261,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2024 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 diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod index 45fdd8f39a6a..ad203299e986 100644 --- a/doc/man3/OSSL_LIB_CTX.pod +++ b/doc/man3/OSSL_LIB_CTX.pod @@ -88,7 +88,7 @@ This can be used to associate a library context with providers that are loaded from a configuration. OSSL_LIB_CTX_free() frees the given I<ctx>, unless it happens to be the -default OpenSSL library context. +default OpenSSL library context. If the argument is NULL, nothing is done. OSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL) reference to the global default library context. @@ -126,7 +126,7 @@ All of the functions described on this page were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/OSSL_PARAM_BLD.pod b/doc/man3/OSSL_PARAM_BLD.pod index 455761c20d32..8598ed0626e0 100644 --- a/doc/man3/OSSL_PARAM_BLD.pod +++ b/doc/man3/OSSL_PARAM_BLD.pod @@ -53,6 +53,7 @@ so that values can be added. Any existing values are cleared. OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new(). +If the argument is NULL, nothing is done. OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure I<bld> into an allocated OSSL_PARAM array. @@ -193,7 +194,7 @@ The functions described here were all added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2024 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 diff --git a/doc/man3/OSSL_PARAM_dup.pod b/doc/man3/OSSL_PARAM_dup.pod index 4ae33faf1e4e..c8d109a22782 100644 --- a/doc/man3/OSSL_PARAM_dup.pod +++ b/doc/man3/OSSL_PARAM_dup.pod @@ -32,6 +32,7 @@ array that have the same key. OSSL_PARAM_free() frees the parameter array I<params> that was created using OSSL_PARAM_dup(), OSSL_PARAM_merge() or OSSL_PARAM_BLD_to_param(). +If the argument to OSSL_PARAM_free() is NULL, nothing is done. =head1 RETURN VALUES @@ -49,7 +50,7 @@ The functions were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021-2024 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 diff --git a/doc/man3/OSSL_SELF_TEST_new.pod b/doc/man3/OSSL_SELF_TEST_new.pod index 4c4b10fca96a..c46becd1ad9b 100644 --- a/doc/man3/OSSL_SELF_TEST_new.pod +++ b/doc/man3/OSSL_SELF_TEST_new.pod @@ -32,6 +32,7 @@ The callback I<cb> may be triggered multiple times by a self test to indicate different phases. OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new(). +If the argument is NULL, nothing is done. OSSL_SELF_TEST_onbegin() may be inserted at the start of a block of self test code. It can be used for diagnostic purposes. @@ -165,7 +166,7 @@ The functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/OSSL_STORE_INFO.pod b/doc/man3/OSSL_STORE_INFO.pod index 39bb93fbf5f2..b8332855d4d0 100644 --- a/doc/man3/OSSL_STORE_INFO.pod +++ b/doc/man3/OSSL_STORE_INFO.pod @@ -101,6 +101,7 @@ holds if the B<OSSL_STORE_INFO> type (as returned by OSSL_STORE_INFO_get_type()) matches the function, otherwise NULL. OSSL_STORE_INFO_free() frees a B<OSSL_STORE_INFO> and its contained type. +If the argument is NULL, nothing is done. OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(), , OSSL_STORE_INFO_new_PUBKEY(), OSSL_STORE_INFO_new_PKEY(), @@ -221,7 +222,7 @@ The OSSL_STORE_INFO_PUBKEY object type was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod index 9cd016be158a..b4fcc7efe935 100644 --- a/doc/man3/OSSL_STORE_LOADER.pod +++ b/doc/man3/OSSL_STORE_LOADER.pod @@ -105,7 +105,6 @@ see L<openssl_user_macros(7)>: typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *store_loader, OSSL_STORE_close_fn store_close_function); - void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *store_loader); int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); @@ -126,6 +125,7 @@ I<loader>. OSSL_STORE_LOADER_free() decrements the reference count for the given I<loader>, and when the count reaches zero, frees it. +If the argument is NULL, nothing is done. OSSL_STORE_LOADER_get0_provider() returns the provider of the given I<loader>. @@ -297,6 +297,7 @@ OSSL_STORE_LOADER_set_close() sets the closing function for the I<store_loader>. OSSL_STORE_LOADER_free() frees the given I<store_loader>. +If the argument is NULL, nothing is done. OSSL_STORE_register_loader() register the given I<store_loader> and thereby makes it available for use with OSSL_STORE_open(), @@ -358,21 +359,25 @@ L<provider-storemgmt(7)> =head1 HISTORY OSSL_STORE_LOADER_fetch(), OSSL_STORE_LOADER_up_ref(), -OSSL_STORE_LOADER_free(), OSSL_STORE_LOADER_get0_provider(), -OSSL_STORE_LOADER_get0_properties(), OSSL_STORE_LOADER_is_a(), -OSSL_STORE_LOADER_do_all_provided() and -OSSL_STORE_LOADER_names_do_all() were added in OpenSSL 3.0. +OSSL_STORE_LOADER_get0_provider(), OSSL_STORE_LOADER_get0_properties(), +OSSL_STORE_LOADER_get0_description(), OSSL_STORE_LOADER_is_a(), +OSSL_STORE_LOADER_do_all_provided() and OSSL_STORE_LOADER_names_do_all() +were added in OpenSSL 3.0. -OSSL_STORE_open_ex_fn() was added in OpenSSL 3.0. +B<OSSL_STORE_LOADER> and OSSL_STORE_LOADER_free() were added in OpenSSL +1.1.1. -B<OSSL_STORE_LOADER>, B<OSSL_STORE_LOADER_CTX>, OSSL_STORE_LOADER_new(), +OSSL_STORE_LOADER_set_open_ex() and OSSL_STORE_open_ex_fn() were added in +OpenSSL 3.0, and are deprecated. + +B<OSSL_STORE_LOADER_CTX>, OSSL_STORE_LOADER_new(), OSSL_STORE_LOADER_set0_scheme(), OSSL_STORE_LOADER_get0_scheme(), OSSL_STORE_LOADER_get0_engine(), OSSL_STORE_LOADER_set_expect(), OSSL_STORE_LOADER_set_find(), OSSL_STORE_LOADER_set_attach(), OSSL_STORE_LOADER_set_open_ex(), OSSL_STORE_LOADER_set_open(), OSSL_STORE_LOADER_set_ctrl(), OSSL_STORE_LOADER_set_load(), OSSL_STORE_LOADER_set_eof(), -OSSL_STORE_LOADER_set_close(), OSSL_STORE_LOADER_free(), +OSSL_STORE_LOADER_set_close(), OSSL_STORE_register_loader(), OSSL_STORE_LOADER_set_error(), OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(), OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn() @@ -380,7 +385,7 @@ were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/OSSL_STORE_SEARCH.pod b/doc/man3/OSSL_STORE_SEARCH.pod index 79186b08997e..bd512890c607 100644 --- a/doc/man3/OSSL_STORE_SEARCH.pod +++ b/doc/man3/OSSL_STORE_SEARCH.pod @@ -75,6 +75,7 @@ criterion, so they must have at least the same life time as the created B<OSSL_STORE_SEARCH>. OSSL_STORE_SEARCH_free() is used to free the B<OSSL_STORE_SEARCH>. +If the argument is NULL, nothing is done. =head2 Loader Functions @@ -183,7 +184,7 @@ were added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018-2024 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 diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod index ac93920addec..f1635b89808a 100644 --- a/doc/man3/PEM_read_bio_PrivateKey.pod +++ b/doc/man3/PEM_read_bio_PrivateKey.pod @@ -320,7 +320,9 @@ NULL but I<*x> is NULL then the structure returned will be written to I<*x>. If neither I<x> nor I<*x> is NULL then an attempt is made to reuse the structure at I<*x> (but see BUGS and EXAMPLES sections). Irrespective of the value of I<x> a pointer to the structure is always -returned (or NULL if an error occurred). +returned (or NULL if an error occurred). The caller retains ownership of the +returned object and needs to free it when it is no longer needed, e.g. +using X509_free() for X509 objects or EVP_PKEY_free() for EVP_PKEY objects. The PEM functions which write private keys take an I<enc> parameter which specifies the encryption algorithm to use, encryption is done @@ -574,7 +576,7 @@ PEM_write_bio_DHparams() and PEM_write_DHparams() were deprecated in 3.0. =head1 COPYRIGHT -Copyright 2001-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2024 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 diff --git a/doc/man3/RAND_set_DRBG_type.pod b/doc/man3/RAND_set_DRBG_type.pod index f78c15ff45f3..423ebfad656f 100644 --- a/doc/man3/RAND_set_DRBG_type.pod +++ b/doc/man3/RAND_set_DRBG_type.pod @@ -27,7 +27,7 @@ private random instances. RAND_set_seed_source_type() specifies the seed source that will be used within the library context I<ctx>. The seed source of name I<seed> with properties I<propq> will be fetched and used to seed the primary -random big generator. +random bit generator. =head1 RETURN VALUES @@ -54,7 +54,7 @@ These functions were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021-2024 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 diff --git a/doc/man3/RSA_meth_new.pod b/doc/man3/RSA_meth_new.pod index 29ea4161b0b5..40f9bc4e8281 100644 --- a/doc/man3/RSA_meth_new.pod +++ b/doc/man3/RSA_meth_new.pod @@ -147,7 +147,7 @@ passed as a parameter. This might be useful for creating a new B<RSA_METHOD> based on an existing one, but with some differences. RSA_meth_free() destroys an B<RSA_METHOD> structure and frees up any -memory associated with it. +memory associated with it. If the argument is NULL, nothing is done. RSA_meth_get0_name() will return a pointer to the name of this RSA_METHOD. This is a pointer to the internal name string and so @@ -260,7 +260,7 @@ Other functions described here were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/SCT_new.pod b/doc/man3/SCT_new.pod index 235762721992..a20affd38a84 100644 --- a/doc/man3/SCT_new.pod +++ b/doc/man3/SCT_new.pod @@ -166,6 +166,12 @@ SCT_set_source() can be used to record where the SCT was found (TLS extension, X.509 certificate extension or OCSP response). This is not required for verifying the SCT. +SCT_free() frees the specified SCT. +If the argument is NULL, nothing is done. + +SCT_LIST_free() frees the specified stack of SCTs. +If the argument is NULL, nothing is done. + =head1 NOTES Some of the setters return int, instead of void. These will all return 1 on @@ -210,7 +216,7 @@ These functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/SSL_CTX_set_alpn_select_cb.pod b/doc/man3/SSL_CTX_set_alpn_select_cb.pod index 102e6578512c..2997a9955756 100644 --- a/doc/man3/SSL_CTX_set_alpn_select_cb.pod +++ b/doc/man3/SSL_CTX_set_alpn_select_cb.pod @@ -52,7 +52,8 @@ SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to set the list of protocols available to be negotiated. The B<protos> must be in protocol-list format, described below. The length of B<protos> is specified in -B<protos_len>. +B<protos_len>. Setting B<protos_len> to 0 clears any existing list of ALPN +protocols and no ALPN extension will be sent to the server. SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a server to select which protocol to use for the incoming connection. When B<cb> @@ -73,9 +74,16 @@ B<server_len> and B<client>, B<client_len> must be in the protocol-list format described below. The first item in the B<server>, B<server_len> list that matches an item in the B<client>, B<client_len> list is selected, and returned in B<out>, B<outlen>. The B<out> value will point into either B<server> or -B<client>, so it should be copied immediately. If no match is found, the first -item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This -function can also be used in the NPN callback. +B<client>, so it should be copied immediately. The client list must include at +least one valid (nonempty) protocol entry in the list. + +The SSL_select_next_proto() helper function can be useful from either the ALPN +callback or the NPN callback (described below). If no match is found, the first +item in B<client>, B<client_len> is returned in B<out>, B<outlen> and +B<OPENSSL_NPN_NO_OVERLAP> is returned. This can be useful when implementing +the NPN callback. In the ALPN case, the value returned in B<out> and B<outlen> +must be ignored if B<OPENSSL_NPN_NO_OVERLAP> has been returned from +SSL_select_next_proto(). SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a client needs to select a protocol from the server's provided list, and a @@ -85,9 +93,10 @@ must be set to point to the selected protocol (which may be within B<in>). The length of the protocol name must be written into B<outlen>. The server's advertised protocols are provided in B<in> and B<inlen>. The callback can assume that B<in> is syntactically valid. The client must -select a protocol. It is fatal to the connection if this callback returns -a value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer -set via SSL_CTX_set_next_proto_select_cb(). +select a protocol (although it may be an empty, zero length protocol). It is +fatal to the connection if this callback returns a value other than +B<SSL_TLSEXT_ERR_OK> or if the zero length protocol is selected. The B<arg> +parameter is the pointer set via SSL_CTX_set_next_proto_select_cb(). SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called when a TLS server needs a list of supported protocols for Next Protocol @@ -149,7 +158,8 @@ A match was found and is returned in B<out>, B<outlen>. =item OPENSSL_NPN_NO_OVERLAP No match was found. The first item in B<client>, B<client_len> is returned in -B<out>, B<outlen>. +B<out>, B<outlen> (or B<NULL> and 0 in the case where the first entry in +B<client> is invalid). =back @@ -187,7 +197,7 @@ L<SSL_CTX_set_tlsext_servername_arg(3)> =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/SSL_CTX_set_cipher_list.pod b/doc/man3/SSL_CTX_set_cipher_list.pod index 71f399400c2a..08d7693f420e 100644 --- a/doc/man3/SSL_CTX_set_cipher_list.pod +++ b/doc/man3/SSL_CTX_set_cipher_list.pod @@ -52,7 +52,7 @@ ciphersuite names in order of preference. Valid TLSv1.3 ciphersuite names are: =back -An empty list is permissible. The default value for the this setting is: +An empty list is permissible. The default value for this setting is: "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" @@ -119,7 +119,7 @@ OSSL_default_cipher_list() and OSSL_default_ciphersites() are new in 3.0. =head1 COPYRIGHT -Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2024 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 diff --git a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod index f289383c7815..e4871590f719 100644 --- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod +++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod @@ -126,9 +126,9 @@ The I<hctx> key material can be set using L<HMAC_Init_ex(3)>. =head1 NOTES -Session resumption shortcuts the TLS so that the client certificate -negotiation don't occur. It makes up for this by storing client certificate -an all other negotiated state information encrypted within the ticket. In a +Session resumption shortcuts the TLS handshake so that the client certificate +negotiation doesn't occur. It makes up for this by storing the client certificate +and all other negotiated state information encrypted within the ticket. In a resumed session the applications will have all this state information available exactly as if a full negotiation had occurred. @@ -241,7 +241,7 @@ OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2014-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2014-2024 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 diff --git a/doc/man3/TS_RESP_CTX_new.pod b/doc/man3/TS_RESP_CTX_new.pod index 725a1921d133..01fd23a10eb4 100644 --- a/doc/man3/TS_RESP_CTX_new.pod +++ b/doc/man3/TS_RESP_CTX_new.pod @@ -27,6 +27,7 @@ and property query to NULL. This results in the default (NULL) library context being used for any operations requiring algorithm fetches. TS_RESP_CTX_free() frees the B<TS_RESP_CTX> object I<ctx>. +If the argument is NULL, nothing is done. =head1 RETURN VALUES @@ -39,7 +40,7 @@ The function TS_RESP_CTX_new_ex() was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021-2024 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 diff --git a/doc/man3/X509V3_get_d2i.pod b/doc/man3/X509V3_get_d2i.pod index 4a2e81b0dbdf..88294ff710f2 100644 --- a/doc/man3/X509V3_get_d2i.pod +++ b/doc/man3/X509V3_get_d2i.pod @@ -108,6 +108,7 @@ The function X509V3_get_d2i() and its variants will return NULL if the extension is not found, occurs multiple times or cannot be decoded. It is possible to determine the precise reason by checking the value of I<*crit>. +The returned pointer must be explicitly freed. The function X509V3_add1_i2d() and its variants allocate B<X509_EXTENSION> objects on STACK I<*x> depending on I<flags>. The B<X509_EXTENSION> objects @@ -236,7 +237,7 @@ L<X509_verify_cert(3)> =head1 COPYRIGHT -Copyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2024 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 diff --git a/doc/man3/X509_LOOKUP.pod b/doc/man3/X509_LOOKUP.pod index 4d2fe38f25ab..8f0240de2d13 100644 --- a/doc/man3/X509_LOOKUP.pod +++ b/doc/man3/X509_LOOKUP.pod @@ -85,6 +85,7 @@ X509_LOOKUP_shutdown() tears down the internal state and resources of the given B<X509_LOOKUP>. X509_LOOKUP_free() destructs the given B<X509_LOOKUP>. +If the argument is NULL, nothing is done. X509_LOOKUP_set_method_data() and X509_LOOKUP_get_method_data() associates and retrieves a pointer to application data to and from the @@ -228,7 +229,7 @@ added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man3/X509_LOOKUP_meth_new.pod b/doc/man3/X509_LOOKUP_meth_new.pod index 202174993563..ef2c3cdd500a 100644 --- a/doc/man3/X509_LOOKUP_meth_new.pod +++ b/doc/man3/X509_LOOKUP_meth_new.pod @@ -110,6 +110,7 @@ be given a human-readable string containing a brief description of the lookup method. X509_LOOKUP_meth_free() destroys a B<X509_LOOKUP_METHOD> structure. +If the argument is NULL, nothing is done. X509_LOOKUP_get_new_item() and X509_LOOKUP_set_new_item() get and set the function that is called when an B<X509_LOOKUP> object is created with @@ -186,7 +187,7 @@ The functions described here were added in OpenSSL 1.1.0i. =head1 COPYRIGHT -Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018-2024 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 diff --git a/doc/man3/X509_STORE_new.pod b/doc/man3/X509_STORE_new.pod index 31d466faa42a..5b3dadb243d7 100644 --- a/doc/man3/X509_STORE_new.pod +++ b/doc/man3/X509_STORE_new.pod @@ -27,6 +27,7 @@ X509_STORE_lock() locks the store from modification by other threads, X509_STORE_unlock() unlocks it. X509_STORE_free() frees up a single X509_STORE object. +If the argument is NULL, nothing is done. =head1 RETURN VALUES @@ -49,7 +50,7 @@ functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 diff --git a/doc/man3/X509_dup.pod b/doc/man3/X509_dup.pod index 849364e2aae7..c8dd79ff71b7 100644 --- a/doc/man3/X509_dup.pod +++ b/doc/man3/X509_dup.pod @@ -367,7 +367,7 @@ followed by I<X509_check_purpose(copied_cert, -1, 0)>, which re-builds the cached data. B<I<TYPE>_free>() releases the object and all pointers and sub-objects -within it. +within it. If the argument is NULL, nothing is done. B<I<TYPE>_print_ctx>() prints the object I<a> on the specified BIO I<out>. Each line will be prefixed with I<indent> spaces. diff --git a/doc/man3/X509_new.pod b/doc/man3/X509_new.pod index ea2b3a2cc9b0..4b52972554de 100644 --- a/doc/man3/X509_new.pod +++ b/doc/man3/X509_new.pod @@ -18,7 +18,7 @@ X509_chain_up_ref - X509 certificate ASN1 allocation functions =head1 DESCRIPTION -The X509 ASN1 allocation routines, allocate and free an +The X509 ASN1 allocation routines allocate and free an X509 structure, which represents an X509 certificate. X509_new_ex() allocates and initializes a X509 structure with a @@ -33,7 +33,8 @@ and property query to NULL. This results in the default (NULL) library context being used for any X509 operations requiring algorithm fetches. X509_free() decrements the reference count of B<X509> structure B<a> and -frees it up if the reference count is zero. If B<a> is NULL nothing is done. +frees it up if the reference count is zero. If the argument is NULL, +nothing is done. X509_up_ref() increments the reference count of B<a>. @@ -86,7 +87,7 @@ The function X509_new_ex() was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2002-2024 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 diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index 00efb6035816..c4b589dd8957 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -387,7 +387,9 @@ B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to the byte following the parsed data. If I<a> is not NULL then a pointer to the returned structure is also written to I<*a>. If an error occurred -then NULL is returned. +then NULL is returned. The caller retains ownership of the +returned object and needs to free it when it is no longer needed, e.g. +using X509_free() for X509 objects or DSA_SIG_free() for DSA_SIG objects. On a successful return, if I<*a> is not NULL then it is assumed that I<*a> contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. @@ -615,7 +617,7 @@ efficiency reasons. =head1 COPYRIGHT -Copyright 1998-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 1998-2024 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 diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod index a6927afefb24..eaec67775ddb 100644 --- a/doc/man7/EVP_KEYEXCH-DH.pod +++ b/doc/man7/EVP_KEYEXCH-DH.pod @@ -7,9 +7,14 @@ EVP_KEYEXCH-DH =head1 DESCRIPTION -Key exchange support for the B<DH> key type. +Key exchange support for the B<DH> and B<DHX> key types. -=head2 DH key exchange parameters +Please note that although both key types support the same key exchange +operations, they cannot be used together in a single key exchange. It +is not possible to use a private key of the B<DH> type in key exchange +with the public key of B<DHX> type and vice versa. + +=head2 DH and DHX key exchange parameters =over 4 @@ -122,7 +127,7 @@ L<OSSL_PROVIDER-FIPS(7)>, =head1 COPYRIGHT -Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod index 1dfc9c734544..1232730c3364 100644 --- a/doc/man7/EVP_PKEY-DH.pod +++ b/doc/man7/EVP_PKEY-DH.pod @@ -7,11 +7,12 @@ EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX =head1 DESCRIPTION -For B<DH> FFC key agreement, two classes of domain parameters can be used: -"safe" domain parameters that are associated with approved named safe-prime -groups, and a class of "FIPS186-type" domain parameters. FIPS186-type domain -parameters should only be used for backward compatibility with existing -applications that cannot be upgraded to use the approved safe-prime groups. +For finite field Diffie-Hellman key agreement, two classes of domain +parameters can be used: "safe" domain parameters that are associated with +approved named safe-prime groups, and a class of "FIPS186-type" domain +parameters. FIPS186-type domain parameters should only be used for backward +compatibility with existing applications that cannot be upgraded to use the +approved safe-prime groups. See L<EVP_PKEY-FFC(7)> for more information about FFC keys. @@ -20,11 +21,11 @@ I<q> value. The B<DHX> key type uses X9.42 format which saves the value of I<q> and this must be used for FIPS186-4. If key validation is required, users should be aware of the nuances associated with FIPS186-4 style parameters as discussed in -L</DH key validation>. +L</DH and DHX key validation>. =head2 DH and DHX domain parameters -In addition to the common FCC parameters that all FFC keytypes should support +In addition to the common FFC parameters that all FFC keytypes should support (see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DHX> and B<DH> keytype implementations support the following: @@ -129,43 +130,44 @@ Where s is the security strength of the key which has values of =back -=head2 DH key validation +=head2 DH and DHX key validation -For B<DHX> that is not a named group the FIPS186-4 standard specifies that the +For keys that are not a named group the FIPS186-4 standard specifies that the values used for FFC parameter generation are also required for parameter validation. This means that optional FFC domain parameter values for I<seed>, I<pcounter> and I<gindex> or I<hindex> may need to be stored for validation purposes. For B<DHX> the I<seed> and I<pcounter> can be stored in ASN1 data (but the I<gindex> or I<hindex> cannot be stored). It is recommended to use a -named safe prime group instead. +B<DH> parameters with named safe prime group instead. -For DH keys, L<EVP_PKEY_param_check(3)> behaves in the following way: -The OpenSSL FIPS provider tests if the parameters are either an approved safe -prime group OR that the FFC parameters conform to FIPS186-4 as defined in -SP800-56Ar3 I<Assurances of Domain-Parameter Validity>. -The OpenSSL default provider uses simpler checks that allows there to be no I<q> -value for backwards compatibility. +With the OpenSSL FIPS provider, L<EVP_PKEY_param_check(3)> and +L<EVP_PKEY_param_check_quick(3)> behave in the following way: the parameters +are tested if they are either an approved safe prime group OR that the FFC +parameters conform to FIPS186-4 as defined in SP800-56Ar3 I<Assurances of +Domain-Parameter Validity>. -For DH keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to -L<EVP_PKEY_param_check(3)>. +The OpenSSL default provider uses simpler checks that allows there to be no I<q> +value for backwards compatibility, however the L<EVP_PKEY_param_check(3)> will +test the I<p> value for being a prime (and a safe prime if I<q> is missing) +which can take significant time. The L<EVP_PKEY_param_check_quick(3)> avoids +the prime tests. -For DH keys, L<EVP_PKEY_public_check(3)> conforms to -SP800-56Ar3 I<FFC Full Public-Key Validation>. +L<EVP_PKEY_public_check(3)> conforms to SP800-56Ar3 +I<FFC Full Public-Key Validation>. -For DH keys, L<EVP_PKEY_public_check_quick(3)> conforms to -SP800-56Ar3 I<FFC Partial Public-Key Validation> when the -DH key is an approved named safe prime group, otherwise it is the same as -L<EVP_PKEY_public_check(3)>. +L<EVP_PKEY_public_check_quick(3)> conforms to SP800-56Ar3 +I<FFC Partial Public-Key Validation> when the key is an approved named safe +prime group, otherwise it is the same as L<EVP_PKEY_public_check(3)>. -For DH Keys, L<EVP_PKEY_private_check(3)> tests that the private key is in the -correct range according to SP800-56Ar3. The OpenSSL FIPS provider requires the -value of I<q> to be set (note that this is set for named safe prime groups). +L<EVP_PKEY_private_check(3)> tests that the private key is in the correct range +according to SP800-56Ar3. The OpenSSL FIPS provider requires the value of I<q> +to be set (note that this is implicitly set for named safe prime groups). For backwards compatibility the OpenSSL default provider only requires I<p> to be set. -For DH keys, L<EVP_PKEY_pairwise_check(3)> conforms to -SP800-56Ar3 I<Owner Assurance of Pair-wise Consistency>. +L<EVP_PKEY_pairwise_check(3)> conforms to SP800-56Ar3 +I<Owner Assurance of Pair-wise Consistency>. =head1 EXAMPLES @@ -327,7 +329,7 @@ L<OSSL_PROVIDER-FIPS(7)> =head1 COPYRIGHT -Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020-2024 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 diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod index 3152cff10424..d6fdae8f22b0 100644 --- a/doc/man7/ossl_store.pod +++ b/doc/man7/ossl_store.pod @@ -44,7 +44,11 @@ other encoding is undefined. =head2 A generic call - OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem"); + #include <openssl/ui.h> /* for UI_get_default_method */ + #include <openssl/store.h> + + OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem", + UI_get_default_method(), NULL, NULL, NULL); /* * OSSL_STORE_eof() simulates file semantics for any repository to signal @@ -65,6 +69,7 @@ other encoding is undefined. PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info)); break; } + OSSL_STORE_INFO_free(info); } OSSL_STORE_close(ctx); @@ -77,7 +82,7 @@ L<OSSL_STORE_SEARCH(3)> =head1 COPYRIGHT -Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2024 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 |