2016-04-20 03:11:30 +08:00
|
|
|
=pod
|
|
|
|
|
|
|
|
|
|
=head1 NAME
|
|
|
|
|
|
|
|
|
|
X509_STORE_get0_param, X509_STORE_set1_param,
|
Add X509_STORE_get1_objects
X509_STORE_get0_objects returns a pointer to the X509_STORE's storage,
but this function is a bit deceptive. It is practically unusable in a
multi-threaded program. See, for example, RUSTSEC-2023-0072, a security
vulnerability caused by this OpenSSL API.
One might think that, if no other threads are mutating the X509_STORE,
it is safe to read the resulting list. However, the documention does not
mention that other logically-const operations on the X509_STORE, notably
certifcate verifications when a hash_dir is installed, will, under a
lock, write to the X509_STORE. The X509_STORE also internally re-sorts
the list on the first query.
If the caller knows to call X509_STORE_lock and X509_STORE_unlock, it
can work around this. But this is not obvious, and the documentation
does not discuss how X509_STORE_lock is very rarely safe to use. E.g.
one cannot call any APIs like X509_STORE_add_cert or
X509_STORE_CTX_get1_issuer while holding the lock because those
functions internally expect to take the lock. (X509_STORE_lock is
another such API which is not safe to export as public API.)
Rather than leave all this to the caller to figure out, the API should
have returned a shallow copy of the list, refcounting the values. Then
it could be internally locked and the caller can freely inspect the
result without synchronization with the X509_STORE.
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23224)
2023-12-11 14:47:25 +08:00
|
|
|
X509_STORE_get1_objects, X509_STORE_get0_objects, X509_STORE_get1_all_certs
|
2020-02-15 21:57:32 +08:00
|
|
|
- X509_STORE setter and getter functions
|
2016-04-20 03:11:30 +08:00
|
|
|
|
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
|
|
|
|
|
|
#include <openssl/x509_vfy.h>
|
|
|
|
|
|
2022-07-20 21:33:51 +08:00
|
|
|
X509_VERIFY_PARAM *X509_STORE_get0_param(const X509_STORE *xs);
|
|
|
|
|
int X509_STORE_set1_param(X509_STORE *xs, const X509_VERIFY_PARAM *pm);
|
Add X509_STORE_get1_objects
X509_STORE_get0_objects returns a pointer to the X509_STORE's storage,
but this function is a bit deceptive. It is practically unusable in a
multi-threaded program. See, for example, RUSTSEC-2023-0072, a security
vulnerability caused by this OpenSSL API.
One might think that, if no other threads are mutating the X509_STORE,
it is safe to read the resulting list. However, the documention does not
mention that other logically-const operations on the X509_STORE, notably
certifcate verifications when a hash_dir is installed, will, under a
lock, write to the X509_STORE. The X509_STORE also internally re-sorts
the list on the first query.
If the caller knows to call X509_STORE_lock and X509_STORE_unlock, it
can work around this. But this is not obvious, and the documentation
does not discuss how X509_STORE_lock is very rarely safe to use. E.g.
one cannot call any APIs like X509_STORE_add_cert or
X509_STORE_CTX_get1_issuer while holding the lock because those
functions internally expect to take the lock. (X509_STORE_lock is
another such API which is not safe to export as public API.)
Rather than leave all this to the caller to figure out, the API should
have returned a shallow copy of the list, refcounting the values. Then
it could be internally locked and the caller can freely inspect the
result without synchronization with the X509_STORE.
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23224)
2023-12-11 14:47:25 +08:00
|
|
|
STACK_OF(X509_OBJECT) *X509_STORE_get1_objects(X509_STORE *xs);
|
2022-07-20 21:33:51 +08:00
|
|
|
STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(const X509_STORE *xs);
|
|
|
|
|
STACK_OF(X509) *X509_STORE_get1_all_certs(X509_STORE *xs);
|
2016-04-20 03:11:30 +08:00
|
|
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
|
2022-07-20 21:33:51 +08:00
|
|
|
X509_STORE_set1_param() sets the verification parameters to I<pm> for I<xs>.
|
2016-04-20 03:11:30 +08:00
|
|
|
|
|
|
|
|
X509_STORE_get0_param() retrieves an internal pointer to the verification
|
2022-07-20 21:33:51 +08:00
|
|
|
parameters for I<xs>. The returned pointer must not be freed by the
|
2016-04-20 03:11:30 +08:00
|
|
|
calling application
|
|
|
|
|
|
Add X509_STORE_get1_objects
X509_STORE_get0_objects returns a pointer to the X509_STORE's storage,
but this function is a bit deceptive. It is practically unusable in a
multi-threaded program. See, for example, RUSTSEC-2023-0072, a security
vulnerability caused by this OpenSSL API.
One might think that, if no other threads are mutating the X509_STORE,
it is safe to read the resulting list. However, the documention does not
mention that other logically-const operations on the X509_STORE, notably
certifcate verifications when a hash_dir is installed, will, under a
lock, write to the X509_STORE. The X509_STORE also internally re-sorts
the list on the first query.
If the caller knows to call X509_STORE_lock and X509_STORE_unlock, it
can work around this. But this is not obvious, and the documentation
does not discuss how X509_STORE_lock is very rarely safe to use. E.g.
one cannot call any APIs like X509_STORE_add_cert or
X509_STORE_CTX_get1_issuer while holding the lock because those
functions internally expect to take the lock. (X509_STORE_lock is
another such API which is not safe to export as public API.)
Rather than leave all this to the caller to figure out, the API should
have returned a shallow copy of the list, refcounting the values. Then
it could be internally locked and the caller can freely inspect the
result without synchronization with the X509_STORE.
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23224)
2023-12-11 14:47:25 +08:00
|
|
|
X509_STORE_get1_objects() returns a snapshot of all objects in the store's X509
|
|
|
|
|
cache. The cache contains B<X509> and B<X509_CRL> objects. The caller is
|
|
|
|
|
responsible for freeing the returned list.
|
|
|
|
|
|
2020-02-15 21:57:32 +08:00
|
|
|
X509_STORE_get0_objects() retrieves an internal pointer to the store's
|
2016-04-20 03:11:30 +08:00
|
|
|
X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The
|
Add X509_STORE_get1_objects
X509_STORE_get0_objects returns a pointer to the X509_STORE's storage,
but this function is a bit deceptive. It is practically unusable in a
multi-threaded program. See, for example, RUSTSEC-2023-0072, a security
vulnerability caused by this OpenSSL API.
One might think that, if no other threads are mutating the X509_STORE,
it is safe to read the resulting list. However, the documention does not
mention that other logically-const operations on the X509_STORE, notably
certifcate verifications when a hash_dir is installed, will, under a
lock, write to the X509_STORE. The X509_STORE also internally re-sorts
the list on the first query.
If the caller knows to call X509_STORE_lock and X509_STORE_unlock, it
can work around this. But this is not obvious, and the documentation
does not discuss how X509_STORE_lock is very rarely safe to use. E.g.
one cannot call any APIs like X509_STORE_add_cert or
X509_STORE_CTX_get1_issuer while holding the lock because those
functions internally expect to take the lock. (X509_STORE_lock is
another such API which is not safe to export as public API.)
Rather than leave all this to the caller to figure out, the API should
have returned a shallow copy of the list, refcounting the values. Then
it could be internally locked and the caller can freely inspect the
result without synchronization with the X509_STORE.
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23224)
2023-12-11 14:47:25 +08:00
|
|
|
returned pointer must not be freed by the calling application. If the store is
|
|
|
|
|
shared across multiple threads, it is not safe to use the result of this
|
|
|
|
|
function. Use X509_STORE_get1_objects() instead, which avoids this problem.
|
2016-04-20 03:11:30 +08:00
|
|
|
|
2020-02-15 21:57:32 +08:00
|
|
|
X509_STORE_get1_all_certs() returns a list of all certificates in the store.
|
|
|
|
|
The caller is responsible for freeing the returned list.
|
2016-04-20 03:11:30 +08:00
|
|
|
|
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
|
|
|
|
|
|
X509_STORE_get0_param() returns a pointer to an
|
|
|
|
|
B<X509_VERIFY_PARAM> structure.
|
|
|
|
|
|
|
|
|
|
X509_STORE_set1_param() returns 1 for success and 0 for failure.
|
|
|
|
|
|
Add X509_STORE_get1_objects
X509_STORE_get0_objects returns a pointer to the X509_STORE's storage,
but this function is a bit deceptive. It is practically unusable in a
multi-threaded program. See, for example, RUSTSEC-2023-0072, a security
vulnerability caused by this OpenSSL API.
One might think that, if no other threads are mutating the X509_STORE,
it is safe to read the resulting list. However, the documention does not
mention that other logically-const operations on the X509_STORE, notably
certifcate verifications when a hash_dir is installed, will, under a
lock, write to the X509_STORE. The X509_STORE also internally re-sorts
the list on the first query.
If the caller knows to call X509_STORE_lock and X509_STORE_unlock, it
can work around this. But this is not obvious, and the documentation
does not discuss how X509_STORE_lock is very rarely safe to use. E.g.
one cannot call any APIs like X509_STORE_add_cert or
X509_STORE_CTX_get1_issuer while holding the lock because those
functions internally expect to take the lock. (X509_STORE_lock is
another such API which is not safe to export as public API.)
Rather than leave all this to the caller to figure out, the API should
have returned a shallow copy of the list, refcounting the values. Then
it could be internally locked and the caller can freely inspect the
result without synchronization with the X509_STORE.
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23224)
2023-12-11 14:47:25 +08:00
|
|
|
X509_STORE_get1_objects() returns a pointer to a stack of the retrieved
|
|
|
|
|
objects on success, else NULL.
|
|
|
|
|
|
2016-04-20 03:11:30 +08:00
|
|
|
X509_STORE_get0_objects() returns a pointer to a stack of B<X509_OBJECT>.
|
|
|
|
|
|
2020-02-15 21:57:32 +08:00
|
|
|
X509_STORE_get1_all_certs() returns a pointer to a stack of the retrieved
|
|
|
|
|
certificates on success, else NULL.
|
|
|
|
|
|
2016-04-20 03:11:30 +08:00
|
|
|
=head1 SEE ALSO
|
|
|
|
|
|
|
|
|
|
L<X509_STORE_new(3)>
|
|
|
|
|
|
|
|
|
|
=head1 HISTORY
|
|
|
|
|
|
|
|
|
|
B<X509_STORE_get0_param> and B<X509_STORE_get0_objects> were added in
|
2017-07-15 21:39:45 +08:00
|
|
|
OpenSSL 1.1.0.
|
2020-02-15 21:57:32 +08:00
|
|
|
B<X509_STORE_get1_certs> was added in OpenSSL 3.0.
|
Add X509_STORE_get1_objects
X509_STORE_get0_objects returns a pointer to the X509_STORE's storage,
but this function is a bit deceptive. It is practically unusable in a
multi-threaded program. See, for example, RUSTSEC-2023-0072, a security
vulnerability caused by this OpenSSL API.
One might think that, if no other threads are mutating the X509_STORE,
it is safe to read the resulting list. However, the documention does not
mention that other logically-const operations on the X509_STORE, notably
certifcate verifications when a hash_dir is installed, will, under a
lock, write to the X509_STORE. The X509_STORE also internally re-sorts
the list on the first query.
If the caller knows to call X509_STORE_lock and X509_STORE_unlock, it
can work around this. But this is not obvious, and the documentation
does not discuss how X509_STORE_lock is very rarely safe to use. E.g.
one cannot call any APIs like X509_STORE_add_cert or
X509_STORE_CTX_get1_issuer while holding the lock because those
functions internally expect to take the lock. (X509_STORE_lock is
another such API which is not safe to export as public API.)
Rather than leave all this to the caller to figure out, the API should
have returned a shallow copy of the list, refcounting the values. Then
it could be internally locked and the caller can freely inspect the
result without synchronization with the X509_STORE.
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23224)
2023-12-11 14:47:25 +08:00
|
|
|
B<X509_STORE_get1_objects> was added in OpenSSL 3.3.
|
2016-04-20 03:11:30 +08:00
|
|
|
|
2016-05-18 23:44:05 +08:00
|
|
|
=head1 COPYRIGHT
|
|
|
|
|
|
2020-04-23 20:55:52 +08:00
|
|
|
Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
|
2016-05-18 23:44:05 +08:00
|
|
|
|
2018-12-06 21:04:44 +08:00
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
2016-05-18 23:44:05 +08:00
|
|
|
this file except in compliance with the License. You can obtain a copy
|
|
|
|
|
in the file LICENSE in the source distribution or at
|
|
|
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
|
|
|
|
|
|
=cut
|
