diff options
Diffstat (limited to 'doc')
24 files changed, 285 insertions, 96 deletions
diff --git a/doc/fingerprints.txt b/doc/fingerprints.txt index bdcad1472309..e8015f26b9ac 100644 --- a/doc/fingerprints.txt +++ b/doc/fingerprints.txt @@ -13,6 +13,9 @@ The following is the list of fingerprints for the keys that are currently in use to sign OpenSSL distributions: OpenSSL: +B146 647E 45A7 B339 47AB 226B 2A2C 87D1 6169 2D40 + +OpenSSL (old keys): BA54 73A2 B058 7B07 FB27 CF2D 2160 94DF D0CB 81EF Richard Levitte: diff --git a/doc/internal/man3/ossl_rcu_lock_new.pod b/doc/internal/man3/ossl_rcu_lock_new.pod index 57b5e4d73d2f..aca2693e2313 100644 --- a/doc/internal/man3/ossl_rcu_lock_new.pod +++ b/doc/internal/man3/ossl_rcu_lock_new.pod @@ -6,6 +6,7 @@ ossl_rcu_lock_new, ossl_rcu_lock_free, ossl_rcu_read_lock, ossl_rcu_read_unlock, ossl_rcu_write_lock, ossl_rcu_write_unlock, ossl_synchronize_rcu, +ossl_rcu_cb_item_new, ossl_rcu_cb_item_free, ossl_rcu_call, ossl_rcu_deref, ossl_rcu_assign_ptr, ossl_rcu_uptr_deref, ossl_rcu_assign_uptr @@ -19,7 +20,10 @@ ossl_rcu_assign_uptr void ossl_rcu_write_unlock(CRYPTO_RCU_LOCK *lock); void ossl_rcu_read_unlock(CRYPTO_RCU_LOCK *lock); void ossl_synchronize_rcu(CRYPTO_RCU_LOCK *lock); - void ossl_rcu_call(CRYPTO_RCU_LOCK *lock, rcu_cb_fn cb, void *data); + CRYPTO_RCU_CB_ITEM *ossl_rcu_cb_item_new(void); + void ossl_rcu_cb_item_free(CRYPTO_RCU_CB_ITEM *item); + void ossl_rcu_call(CRYPTO_RCU_LOCK *lock, CRYPTO_RCU_CB_ITEM *item, + rcu_cb_fn cb, void *data); void *ossl_rcu_deref(void **p); void ossl_rcu_uptr_deref(void **p); void ossl_rcu_assign_ptr(void **p, void **v); @@ -96,10 +100,29 @@ the write side thread is safe to free. =item * -ossl_rcu_call() enqueues a callback function to the lock, to be called -when the next synchronization completes. Note: It is not guaranteed that the -thread which enqueued the callback will be the thread which executes the -callback +ossl_rcu_cb_item_new() allocates a callback item suitable for use with +ossl_rcu_call(). Returns NULL on allocation failure. The item is owned by +the caller until it is passed to ossl_rcu_call(), at which point ownership +transfers to the lock and the item must not be touched again by the caller. + +=item * + +ossl_rcu_cb_item_free() frees a callback item that was allocated by +ossl_rcu_cb_item_new() but never passed to ossl_rcu_call(). Use this to +release the item on the failure path of an operation that decided not to +publish its update. + +=item * + +ossl_rcu_call() enqueues a callback function I<cb> to the lock, to be +called with I<data> when the next synchronization completes. The caller +must provide a callback item I<item> previously obtained from +ossl_rcu_cb_item_new(). After this call the lock owns the item and will +free it after invoking the callback. This function does not allocate and +cannot fail, which lets callers allocate the item before performing any +publish (assign_ptr) and bail cleanly if allocation fails. Note: it is +not guaranteed that the thread which enqueued the callback will be the +thread which executes the callback. =item * @@ -121,6 +144,9 @@ ossl_rcu_lock_free() frees an allocated RCU lock ossl_rcu_lock_new() returns a pointer to a newly created RCU lock structure. +ossl_rcu_cb_item_new() returns a pointer to a newly created callback item, +or NULL on allocation failure. + ossl_rcu_deref() and ossl_rcu_uptr_deref() return the value pointed to by the passed in value v. @@ -152,7 +178,7 @@ This example safely initializes and uses a lock. static void myinit(void) { - lock = ossl_rcu_lock_new(1); + lock = ossl_rcu_lock_new(1, NULL); } static int initlock(void) @@ -162,10 +188,16 @@ This example safely initializes and uses a lock. return 1; } - static void writer_thread() + static void free_old_foo(void *data) + { + OPENSSL_free(data); + } + + static int writer_thread(void) { struct foo *newfoo; struct foo *oldfoo; + CRYPTO_RCU_CB_ITEM *cbi; initlock(); @@ -177,48 +209,60 @@ This example safely initializes and uses a lock. * 1) create a new shared object */ newfoo = OPENSSL_zalloc(sizeof(struct foo)); + if (newfoo == NULL) + return 0; /* - * acquire the write side lock + * 2) Pre allocate the rcu callback item before any publish. + */ + cbi = ossl_rcu_cb_item_new(); + if (cbi == NULL) { + OPENSSL_free(newfoo); + return 0; + } + + /* + * 3) acquire the write side lock */ ossl_rcu_write_lock(lock); /* - * 2) read the old pointer + * 4) read the old pointer */ oldfoo = ossl_rcu_deref(&fooptr); /* - * 3) Copy the old pointer to the new object, and + * 5) Copy the old pointer to the new object, and * make any needed adjustments */ memcpy(newfoo, oldfoo, sizeof(struct foo)); newfoo->aval++; /* - * 4) Update the shared pointer to the new value + * 6) Update the shared pointer to the new value */ ossl_rcu_assign_ptr(&fooptr, &newfoo); /* - * 5) Release the write side lock + * 7) Schedule the old pointer to be freed when readers are done. */ - ossl_rcu_write_unlock(lock); + ossl_rcu_call(lock, cbi, free_old_foo, oldfoo); /* - * 6) wait for any read side holds on the old data - * to be released + * 8) Release the write side lock */ - ossl_synchronize_rcu(lock); + ossl_rcu_write_unlock(lock); /* - * 7) free the old pointer, now that there are no - * further readers + * 9) wait for any read side holds on the old data + * to be released, after which free_old_foo will run */ - OPENSSL_free(oldfoo); + ossl_synchronize_rcu(lock); + + return 1; } - static void reader_thread() + static void reader_thread(void) { struct foo *myfoo = NULL; int a; @@ -249,7 +293,7 @@ L<crypto(7)>, L<openssl-threads(7)>. =head1 COPYRIGHT -Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2023-2026 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-format-options.pod b/doc/man1/openssl-format-options.pod index 115aa9936f8f..e97cc3b51e91 100644 --- a/doc/man1/openssl-format-options.pod +++ b/doc/man1/openssl-format-options.pod @@ -84,11 +84,11 @@ a block of base-64 encoding (defined in IETF RFC 4648), with specific lines used to mark the start and end: Text before the BEGIN line is ignored. - ----- BEGIN object-type ----- + -----BEGIN object-type----- OT43gQKBgQC/2OHZoko6iRlNOAQ/tMVFNq7fL81GivoQ9F1U0Qr+DH3ZfaH8eIkX xT0ToMPJUzWAn8pZv0snA0um6SIgvkCuxO84OkANCVbttzXImIsL7pFzfcwV/ERK UM6j0ZuSMFOCr/lGPAoOQU0fskidGEHi1/kW+suSr28TqsyYZpwBDQ== - ----- END object-type ----- + -----END object-type----- Text after the END line is also ignored The I<object-type> must match the type of object that is expected. diff --git a/doc/man1/openssl-pkcs8.pod.in b/doc/man1/openssl-pkcs8.pod.in index db089d6777d7..0e50459d2cae 100644 --- a/doc/man1/openssl-pkcs8.pod.in +++ b/doc/man1/openssl-pkcs8.pod.in @@ -74,7 +74,7 @@ is included. =item B<-traditional> -When this option is present and B<-topk8> is not a traditional format private +When this option is present and B<-topk8> is not, a traditional format private key is written. =item B<-in> I<filename> @@ -289,7 +289,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-2026 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-rehash.pod.in b/doc/man1/openssl-rehash.pod.in index 466ff42aea56..4605f088d009 100644 --- a/doc/man1/openssl-rehash.pod.in +++ b/doc/man1/openssl-rehash.pod.in @@ -49,8 +49,8 @@ directories to be set up like this in order to find certificates. If any directories are named on the command line, then those are processed in turn. If not, then the B<SSL_CERT_DIR> environment variable -is consulted; this should be a colon-separated list of directories, -like the Unix B<PATH> variable. +is consulted; this should be a colon-separated list of directories +(or semicolon-separated on Windows), like the B<PATH> variable. If that is not set then the default directory (installation-specific but often F</usr/local/ssl/certs>) is processed. @@ -149,7 +149,7 @@ L<openssl-x509(1)> =head1 COPYRIGHT -Copyright 2015-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2026 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 82c5917f6081..bd24ab1ef197 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -323,6 +323,12 @@ see L<openssl-verify(1)> for more information. The URI of a store containing trusted certificates to use for verifying the server's certificate. +When any of B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> is +specified, they are loaded into a separate verification store (via +L<SSL_CTX_set1_verify_cert_store(3)>) and used for server certificate +verification instead of the store built from B<-CAfile>, B<-CApath>, and +B<-CAstore>. + =item B<-chainCAfile> I<file> A file in PEM format containing trusted certificates to use @@ -680,9 +686,6 @@ The I<protocols> list is a comma-separated list of protocol names that the client should advertise support for. The list should contain the most desirable protocols first. Protocol names are printable ASCII strings, for example "http/1.1" or "spdy/3". -An empty list of protocols is treated specially and will cause the -client to advertise support for the TLS extension but disconnect just -after receiving ServerHello with a list of server supported protocols. The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used. =item B<-ct>, B<-noct> @@ -1025,7 +1028,7 @@ options were added in OpenSSL 3.2. =head1 COPYRIGHT -Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2026 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 4f2a63d9b69b..6d55fac7d115 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -334,8 +334,8 @@ Download CRLs from distribution points given in CDP extensions of certificates =item B<-verifyCAfile> I<filename> -A file in PEM format CA containing trusted certificates to use -for verifying client certificates. +A file in PEM format containing trusted CA certificates (root and/or +intermediate) used to verify the client certificate chain. =item B<-verifyCApath> I<dir> @@ -349,6 +349,15 @@ see L<openssl-verify(1)> for more information. The URI of a store containing trusted certificates to use for verifying client certificates. +When any of B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> is +specified, they are loaded into a separate verification store (via +L<SSL_CTX_set1_verify_cert_store(3)>) and used for client certificate +verification instead of the store built from B<-CAfile>, B<-CApath>, and +B<-CAstore>. Note that B<-CAfile> is the sole source of acceptable issuing +CA names sent to the client in the Certificate Request message during the +handshake; B<-CApath>, B<-CAstore>, and the B<-verifyCA*> options do not +contribute to this list. + =item B<-chainCAfile> I<file> A file in PEM format containing trusted certificates to use @@ -763,6 +772,10 @@ has been negotiated, and early data is enabled on the server. A full handshake is forced if a session ticket is used a second or subsequent time. Any early data that was sent will be rejected. +Note that the server manages an internal cache of session tickets. If a client +closes the connection without sending the close_notify alert, the +corresponding session ticket is removed and a full handshake is forced. + =item B<-tfo> Enable acceptance of TCP Fast Open (RFC7413) connections. @@ -927,7 +940,7 @@ options were added in OpenSSL 3.2. =head1 COPYRIGHT -Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2026 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-smime.pod.in b/doc/man1/openssl-smime.pod.in index 0a8fe0136655..63a16ddfe068 100644 --- a/doc/man1/openssl-smime.pod.in +++ b/doc/man1/openssl-smime.pod.in @@ -54,8 +54,9 @@ I<recipcert> ... =head1 DESCRIPTION -This command handles S/MIME mail. It can encrypt, decrypt, sign -and verify S/MIME messages. +This command handles S/MIME according to RFC 2311 (1998) with no CMS support. +It can encrypt, decrypt, sign and verify S/MIME 2.0 messages. For newer messages +use the OpenSSL CMS tool. =head1 OPTIONS @@ -479,7 +480,7 @@ The B<-engine> option was deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2026 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_s_bio.pod b/doc/man3/BIO_s_bio.pod index 653fe4785a49..494b3632ee93 100644 --- a/doc/man3/BIO_s_bio.pod +++ b/doc/man3/BIO_s_bio.pod @@ -5,7 +5,8 @@ BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, -BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO +BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request, +BIO_nread0, BIO_nread, BIO_nwrite0, BIO_nwrite - BIO pair BIO =head1 SYNOPSIS @@ -28,6 +29,11 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO size_t BIO_ctrl_get_read_request(BIO *b); int BIO_ctrl_reset_read_request(BIO *b); + int BIO_nread0(BIO *bio, char **buf); + int BIO_nread(BIO *bio, char **buf, int num); + int BIO_nwrite0(BIO *bio, char **buf); + int BIO_nwrite(BIO *bio, char **buf, int num); + =head1 DESCRIPTION BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink @@ -98,6 +104,44 @@ than that returned by BIO_get_write_guarantee(). BIO_ctrl_reset_read_request() can also be used to reset the value returned by BIO_get_read_request() to zero. +=head2 Non-copying Interface + +BIO_nread0(), BIO_nread(), BIO_nwrite0(), and BIO_nwrite() provide a non-copying +interface for reading from and writing to BIO pairs. These functions allow +direct access to the internal buffer, avoiding the overhead of copying data. + +BIO_nread0() returns in B<*buf> a pointer to the start of the available data +in the peer's write buffer and returns the number of bytes available. +This allows reading directly from the buffer without copying. +It does not consume the data; a subsequent call to BIO_nread() is needed +to advance the buffer position. + +BIO_nread() is similar to BIO_nread0() but also advances the read position +by up to B<num> bytes. The actual number of bytes consumed is returned. +The B<*buf> pointer is set to the start of the data that was consumed. +Since the data is considered consumed after this call, the pointer returned +by BIO_nread() should not be used afterwards unless the caller also +controls the writing side. The typical pattern is to call BIO_nread0() first, +use the data, and then call BIO_nread() to consume it. + +BIO_nwrite0() returns in B<*buf> a pointer to the start of the available +space in the write buffer and returns the number of bytes that can be written. +This allows writing directly to the buffer without copying. +It does not commit the data; a subsequent call to BIO_nwrite() is needed +to update the buffer length. + +BIO_nwrite() is similar to BIO_nwrite0() but also commits up to B<num> bytes +as written. The actual number of bytes committed is returned. +The B<*buf> pointer is set to the start of the region that was committed. +BIO_nwrite() should only be called after the data has actually been written +to the buffer obtained from BIO_nwrite0(), since committing signals data +availability to the reading side. + +Note that due to the ring buffer implementation, if wrapping around would be +required, BIO_nread0() and BIO_nwrite0() may return less than the total +available space. In such cases, a second call may be needed to access the +remaining data or space. + =head1 NOTES Both halves of a BIO pair should be freed. That is even if one half is implicit @@ -133,6 +177,17 @@ locations for B<bio1> and B<bio2>. Check the error stack for more information. [XXXXX: More return values need to be added here] +BIO_nread0() returns the number of bytes available for reading, 0 if the peer +has closed and no data remains (EOF), or -1 if no data is currently available +(retry may be appropriate). If the BIO is not initialized, -2 is returned. + +BIO_nwrite0() returns the number of bytes of space available for writing, or -1 +if no space is currently available (retry may be appropriate) or the BIO has +been closed. If the BIO is not initialized, -2 is returned. + +BIO_nread() and BIO_nwrite() return the number of bytes consumed or committed +respectively, or the same error values as BIO_nread0() and BIO_nwrite0(). + =head1 EXAMPLES The BIO pair can be used to have full control over the network access of an @@ -176,6 +231,30 @@ and must be transferred to the network. Use BIO_ctrl_get_read_request() to find out, how many bytes must be written into the buffer before the SSL_operation() can successfully be continued. +A typical usage pattern for the non-copying write interface is: + + int ret; + char *buf; + + ret = BIO_nwrite0(bio, &buf); + if (ret > 0) { + /* write up to 'ret' bytes directly to 'buf' */ + memcpy(buf, data, len); + BIO_nwrite(bio, &buf, len); /* commit the write */ + } + +A typical usage pattern for the non-copying read interface is: + + int ret; + char *buf; + + ret = BIO_nread0(bio, &buf); + if (ret > 0) { + /* read up to 'ret' bytes directly from 'buf' */ + process_data(buf, ret); + BIO_nread(bio, &buf, ret); /* consume the data */ + } + =head1 WARNINGS As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ @@ -191,7 +270,7 @@ L<BIO_should_retry(3)>, L<BIO_read_ex(3)> =head1 COPYRIGHT -Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2026 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 46966d996379..a7ff19565f49 100644 --- a/doc/man3/BN_add.pod +++ b/doc/man3/BN_add.pod @@ -108,8 +108,10 @@ BN_gcd() computes the greatest common divisor of I<a> and I<b> and places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or I<b>. -For all functions, I<ctx> is a previously allocated B<BN_CTX> used for -temporary variables; see L<BN_CTX_new(3)>. +For all functions that take a I<ctx> parameter, it must be a previously +allocated B<BN_CTX> used for temporary variables; see L<BN_CTX_new(3)>. +Unless stated otherwise in the documentation for a specific function, +the I<ctx> parameter must not be NULL. Unless noted otherwise, the result B<BIGNUM> must be different from the arguments. @@ -135,7 +137,7 @@ L<BN_add_word(3)>, L<BN_set_bit(3)> =head1 COPYRIGHT -Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2026 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/CMS_decrypt.pod b/doc/man3/CMS_decrypt.pod index 121b74a30a10..4e40b37f214a 100644 --- a/doc/man3/CMS_decrypt.pod +++ b/doc/man3/CMS_decrypt.pod @@ -68,7 +68,7 @@ then the above behaviour is modified and an error B<is> returned if no recipient encrypted key can be decrypted B<without> generating a random content encryption key. Applications should use this flag with B<extreme caution> especially in automated gateways as it can leave them -open to attack. +open to attack. See L<EVP_PKEY_decrypt(3)> for more details. It is possible to determine the correct recipient key by other means (for example looking them up in a database) and setting them in the CMS structure @@ -103,7 +103,7 @@ mentioned in CMS_verify() also applies to CMS_decrypt(). =head1 SEE ALSO -L<ERR_get_error(3)>, L<CMS_encrypt(3)> +L<ERR_get_error(3)>, L<CMS_encrypt(3)>, L<EVP_PKEY_decrypt(3)> =head1 HISTORY @@ -112,7 +112,7 @@ were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2008-2026 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 2af4ebec91f9..46cff34f075c 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -413,7 +413,8 @@ encrypted data. For most ciphers and modes, the amount of data written can be anything from zero bytes to (inl + cipher_block_size - 1) bytes. For wrap cipher modes, the amount of data written can be anything -from zero bytes to (inl + cipher_block_size) bytes. +from zero bytes to (inl rounded up to cipher_block_size + cipher_block_size) +bytes. For stream ciphers, the amount of data written can be anything from zero bytes to inl bytes. Thus, the buffer pointed to by I<out> must contain sufficient room for the diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod index 210f33801cae..b8db1724c6f4 100644 --- a/doc/man3/OSSL_HTTP_REQ_CTX.pod +++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod @@ -86,9 +86,12 @@ For backward compatibility, I<path> may begin with C<http://> and thus convey an absoluteURI. In this case it indicates HTTP proxy use and provides also the server (and optionally the port) that the proxy shall forward the request to. In this case the I<server> and I<port> arguments must be NULL. +The I<server>, I<port>, and I<path> arguments must not contain CR or LF +characters. OSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the context I<rctx>. It can be called more than once to add multiple header lines. +The I<name> and I<value> arguments must not contain CR or LF characters. For example, to add a C<Host> header for C<example.com> you would call: OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com"); @@ -143,6 +146,7 @@ The HTTP header C<Content-Length> is filled out with the length of the request. I<content_type> must be NULL if I<req> is NULL. If I<content_type> isn't NULL, the HTTP header C<Content-Type> is also added with the given string value. +The I<content_type> argument must not contain CR or LF characters. The header lines are added to the internal memory B<BIO> for the request header. OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in I<rctx> @@ -299,7 +303,7 @@ All other functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2015-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2026 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_parse_url.pod b/doc/man3/OSSL_HTTP_parse_url.pod index bc29fb18d14b..60d9fcdd6401 100644 --- a/doc/man3/OSSL_HTTP_parse_url.pod +++ b/doc/man3/OSSL_HTTP_parse_url.pod @@ -32,7 +32,9 @@ see L<openssl_user_macros(7)>: =head1 DESCRIPTION -OSSL_HTTP_adapt_proxy() takes an optional proxy hostname I<proxy> +OSSL_HTTP_adapt_proxy() determines whether a proxy should be used +when connecting to the given I<server>. +It takes an optional proxy hostname I<proxy> and returns it transformed according to the optional I<no_proxy> parameter, I<server>, I<use_ssl>, and the applicable environment variable, as follows. If I<proxy> is NULL, take any default value from the C<http_proxy> @@ -40,11 +42,13 @@ environment variable, or from C<https_proxy> if I<use_ssl> is nonzero. If this still does not yield a proxy hostname, take any further default value from the C<HTTP_PROXY> environment variable, or from C<HTTPS_PROXY> if I<use_ssl> is nonzero. -If I<no_proxy> is NULL, take any default exclusion value from the C<no_proxy> -environment variable, or else from C<NO_PROXY>. -Return the determined proxy host unless the exclusion value, -which is a list of proxy hosts separated by C<,> and/or whitespace, -contains I<server>. +Return the determined proxy host if I<server> is the empty string +or I<server> is not in the exclusion list. +The exclusion list is a list of server hosts separated by C<,> +and/or whitespace. +They may be given via the I<no_proxy> parameter. +If it is NULL, the exclusion list is taken from the C<no_proxy> +environment variable if set, otherwise from C<NO_PROXY>. Otherwise return NULL. When I<server> is a string delimited by C<[> and C<]>, which are used for IPv6 addresses, the enclosing C<[> and C<]> are stripped prior to comparison. @@ -102,7 +106,7 @@ OCSP_parse_url() was deprecated in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2026 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_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index eaa0986666fc..b854756ffd46 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -158,6 +158,7 @@ pre-established with a TLS proxy using the HTTP CONNECT method, optionally using proxy client credentials I<proxyuser> and I<proxypass>, to connect with TLS protection ultimately to I<server> and I<port>. If the I<port> argument is NULL or the empty string it defaults to "443". +The I<server> and I<port> arguments must not contain CR or LF characters. If the I<timeout> parameter is > 0 this indicates the maximum number of seconds the connection setup is allowed to take. A value <= 0 enables waiting indefinitely, i.e., no timeout. @@ -178,6 +179,8 @@ else HTTP POST with the contents of I<req> and optional I<content_type>, where the length of the data in I<req> does not need to be determined in advance: the BIO will be read on-the-fly while sending the request, which supports streaming. The optional list I<headers> may contain additional custom HTTP header lines. +The I<path>, I<headers> names and values, and I<content_type> must not contain +CR or LF characters. The I<max_resp_len> parameter specifies the maximum allowed response content length, where the value 0 indicates no limit. For the meaning of the I<expected_content_type>, I<expect_asn1>, I<timeout>, @@ -275,7 +278,7 @@ All the functions described here were added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2026 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/PKCS7_decrypt.pod b/doc/man3/PKCS7_decrypt.pod index aea15937ab86..751556501b91 100644 --- a/doc/man3/PKCS7_decrypt.pod +++ b/doc/man3/PKCS7_decrypt.pod @@ -22,6 +22,14 @@ B<flags> is an optional set of flags. Although the recipients certificate is not needed to decrypt the data it is needed to locate the appropriate (of possible several) recipients in the PKCS#7 structure. +When RSA PKCS#1 v1.5 Key Transport is in use, the invoked EVP_PKEY_decrypt() +will use implicit rejection mechanism. It always returns the result of RSA +decryption of the symmetric key to avoid Marvin attack. This result is +deterministic and can happen to match the symmetric cipher used for the content +encryption. In case when the certificate is not provided, the last +RecipientInfo producing the key looking valid will be used. It may cause +getting garbage content on decryption. + The following flags can be passed in the B<flags> parameter. If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted @@ -38,16 +46,13 @@ The error can be obtained from ERR_get_error(3) PKCS7_decrypt() must be passed the correct recipient key and certificate. It would be better if it could look up the correct key and certificate from a database. -The lack of single pass processing and need to hold all data in memory as -mentioned in PKCS7_sign() also applies to PKCS7_verify(). - =head1 SEE ALSO -L<ERR_get_error(3)>, L<PKCS7_encrypt(3)> +L<ERR_get_error(3)>, L<PKCS7_encrypt(3)>, L<EVP_PKEY_decrypt(3)> =head1 COPYRIGHT -Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2002-2026 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_session_cache_mode.pod b/doc/man3/SSL_CTX_set_session_cache_mode.pod index 25b588f58091..839f787d9d3c 100644 --- a/doc/man3/SSL_CTX_set_session_cache_mode.pod +++ b/doc/man3/SSL_CTX_set_session_cache_mode.pod @@ -8,8 +8,8 @@ SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable #include <openssl/ssl.h> - long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); - long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); + long SSL_CTX_set_session_cache_mode(SSL_CTX *ctx, long mode); + long SSL_CTX_get_session_cache_mode(SSL_CTX *ctx); =head1 DESCRIPTION @@ -136,7 +136,7 @@ L<SSL_CTX_flush_sessions(3)> =head1 COPYRIGHT -Copyright 2001-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2026 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_session_id_context.pod b/doc/man3/SSL_CTX_set_session_id_context.pod index c9572bd0d83f..35b06ef2037f 100644 --- a/doc/man3/SSL_CTX_set_session_id_context.pod +++ b/doc/man3/SSL_CTX_set_session_id_context.pod @@ -38,9 +38,6 @@ is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and SSL_set_session_id_context() functions are therefore only useful on the server side. -OpenSSL clients will check the session id context returned by the server -when reusing a session. - The maximum length of the B<sid_ctx> is limited to B<SSL_MAX_SID_CTX_LENGTH>. @@ -51,11 +48,24 @@ certificates are used, stored sessions will not be reused but a fatal error will be flagged and the handshake will fail. -If a server returns a different session id context to an OpenSSL client -when reusing a session, an error will be flagged and the handshake will -fail. OpenSSL servers will always return the correct session id context, -as an OpenSSL server checks the session id context itself before reusing -a session as described above. +If a client attempts to resume a session and the server detects that the session +id context associated with the session is different to the current session id +context then the resumption will fail. The handshake will continue normally but +no resumption will occur. + +It is vital that the session id context is set before any session resumption +occurs. Sessions get created early in the handshake. If the session id context +is not set by the time the session gets created then the session will be +associated with an empty session id context. The already created session will +not get updated if the session id context is later set. In particular the +callback set via the L<SSL_CTX_set_tlsext_servername_callback(3)> function will +be invoked after the session gets created, so if the session id context is set +in the callback then this will be too late for the current handshake and the +session id context setting will be ignored with respect to resumption. Typically +the session id context should be set before the TLS handshake starts, but it may +occur as late as in the callback set via the L<SSL_CTX_set_client_hello_cb(3)> +function. + =head1 RETURN VALUES @@ -82,7 +92,7 @@ L<ssl(7)> =head1 COPYRIGHT -Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2026 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_servername_callback.pod b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod index a0a4bd636785..a1b3f58994b5 100644 --- a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod +++ b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod @@ -29,7 +29,11 @@ still necessary in order to acknowledge the servername requested by the client. SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb> used by a server to perform any actions or configuration required based on the servername extension received in the incoming connection. When B<cb> -is NULL, SNI is not used. +is NULL, SNI is not used. Note that this callback occurs late in the processing +of the ClientHello message. In particular it happens after session resumption +has occurred, and so typically this callback should not call functions such +as L<SSL_set_session_id_context(3)> since it is too late to affect the session +resumption for the current handshake. The servername callback should return one of the following values: @@ -169,7 +173,7 @@ NULL. =head1 COPYRIGHT -Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017-2026 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 41e76ae8379b..9f0589a87e4c 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -471,21 +471,29 @@ encoding. Unlike the C structures which can have pointers to sub-objects within, the DER is a serialized encoding, suitable for sending over the network, writing to a file, and so on. -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. 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. +B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. +When there is no error, a pointer to a B<I<TYPE>> object is returned and I<*ppin> is +incremented to the byte following the parsed data. +The caller owns the returned object and needs to free it when it is no longer needed, +e.g., via X509_free() for B<X509> 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. -For B<I<TYPE>> structures where it matters it is possible to set up a library -context on the decoded structure this way (see the B<EXAMPLES> section). -However using the "reuse" capability for other purposes is B<strongly -discouraged> (see B<BUGS> below, and the discussion in the B<RETURN VALUES> -section). +If either I<a> or I<*a> is NULL, then fresh storage is allocated for the +returned object, and if I<a> is not NULL then I<*a> is set equal to the +returned pointer. + +When both I<a> and I<*a> are not NULL, I<*a> MUST be a pointer to an +existing I<TYPE> object, which is reused to hold the decoded result. +On error (NULL return value), the object is freed and I<*a> is set to NULL. + +From OpenSSL 3.x onwards, reuse is only supported when I<*a> points to a newly +allocated, and not otherwise modified, I<TYPE> object. +Allocation can be via one of the various _ex() routines, which make it possible +to associate the allocated object with a chosen I<libctx> (library context) +or I<propq> (property query), see the B<EXAMPLES> section. +No other reuse is supported (see B<BUGS> below, and the discussion in the +B<RETURN VALUES> section). +The returned object is not suitable for another reuse: each reuse attempt MUST +start with a newly allocated object. B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts to parse data from BIO I<bp>. @@ -761,7 +769,7 @@ were added in OpenSSL 3.5. =head1 COPYRIGHT -Copyright 1998-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 1998-2026 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_CIPHER-AES.pod b/doc/man7/EVP_CIPHER-AES.pod index 7bd3746c9ba2..2c894bb34eaa 100644 --- a/doc/man7/EVP_CIPHER-AES.pod +++ b/doc/man7/EVP_CIPHER-AES.pod @@ -69,6 +69,10 @@ The AES-SIV and AES-WRAP mode implementations do not support streaming. That means to obtain correct results there can be only one L<EVP_EncryptUpdate(3)> or L<EVP_DecryptUpdate(3)> call after the initialization of the context. +When wrapping with AES-WRAP-PAD ciphers, the output buffer must be at least +I<inl> rounded up to the cipher block size (8 bytes) plus the block size. +That is, the minimum output buffer size is C<((inl + 7) / 8) * 8 + 8> bytes. + The AES-XTS implementations allow streaming to be performed, but each L<EVP_EncryptUpdate(3)> or L<EVP_DecryptUpdate(3)> call requires each input to be a multiple of the blocksize. Only the final EVP_EncryptUpdate() or @@ -86,7 +90,7 @@ The GCM-SIV mode ciphers were added in OpenSSL version 3.2. =head1 COPYRIGHT -Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021-2026 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/openssl-env.pod b/doc/man7/openssl-env.pod index 73a2e933fa76..5647af84f963 100644 --- a/doc/man7/openssl-env.pod +++ b/doc/man7/openssl-env.pod @@ -168,6 +168,8 @@ See L<RAND_load_file(3)>. =item B<SSL_CERT_DIR>, B<SSL_CERT_FILE> Specify the default directory or file containing CA certificates. +B<SSL_CERT_DIR> can contain multiple directories separated by colons +(or semicolons on Windows). See L<SSL_CTX_load_verify_locations(3)>. =item B<TSGET> diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod index 9679c5c98526..3ff9e647ca63 100644 --- a/doc/man7/provider-asym_cipher.pod +++ b/doc/man7/provider-asym_cipher.pod @@ -38,9 +38,9 @@ provider-asym_cipher - The asym_cipher library E<lt>-E<gt> provider functions /* Asymmetric Cipher parameters */ int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]); - const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void *provctx); + const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void *ctx, void *provctx); int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]); - const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void *provctx); + const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void *ctx, void *provctx); =head1 DESCRIPTION @@ -291,7 +291,7 @@ were added in OpenSSL 3.4. =head1 COPYRIGHT -Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2026 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/provider-signature.pod b/doc/man7/provider-signature.pod index 3ef927feb594..0e25dc3d32d3 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -269,7 +269,6 @@ OSSL_FUNC_signature_gettable_ctx_params() functions, as well as the "md_params" functions. The OSSL_FUNC_signature_dupctx() function is optional. -It is not yet used by OpenSSL. The OSSL_FUNC_signature_query_key_types() function is optional. When present, it should return a NULL-terminated array of strings @@ -708,7 +707,7 @@ Deterministic digital signature generation for ECDSA was added to the FIPS provi =head1 COPYRIGHT -Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019-2026 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 |