OSSL_STORE_SEARCH(3ossl) OpenSSL OSSL_STORE_SEARCH(3ossl)
NAME
OSSL_STORE_SEARCH, OSSL_STORE_SEARCH_by_name,
OSSL_STORE_SEARCH_by_issuer_serial,
OSSL_STORE_SEARCH_by_key_fingerprint, OSSL_STORE_SEARCH_by_alias,
OSSL_STORE_SEARCH_free, OSSL_STORE_SEARCH_get_type,
OSSL_STORE_SEARCH_get0_name, OSSL_STORE_SEARCH_get0_serial,
OSSL_STORE_SEARCH_get0_bytes, OSSL_STORE_SEARCH_get0_string,
OSSL_STORE_SEARCH_get0_digest - Type and functions to create OSSL_STORE
search criteria
SYNOPSIS
#include <openssl/store.h>
typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
const ASN1_INTEGER
*serial);
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
const unsigned char
*bytes, int len);
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
*criterion);
const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
*criterion, size_t *length);
const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
*criterion);
DESCRIPTION
These functions are used to specify search criteria to help search for
specific objects through other names than just the URI that's given to
OSSL_STORE_open(). For example, this can be useful for an application
that has received a URI and then wants to add on search criteria in a
uniform and supported manner.
Types
OSSL_STORE_SEARCH is an opaque type that holds the constructed search
criterion, and that can be given to an OSSL_STORE context with
OSSL_STORE_find().
The calling application owns the allocation of an OSSL_STORE_SEARCH at
all times, and should therefore be careful not to deallocate it before
OSSL_STORE_close() has been called for the OSSL_STORE context it was
given to.
Application Functions
OSSL_STORE_SEARCH_by_name(), OSSL_STORE_SEARCH_by_issuer_serial(),
OSSL_STORE_SEARCH_by_key_fingerprint(), and
OSSL_STORE_SEARCH_by_alias() are used to create an OSSL_STORE_SEARCH
from a subject name, an issuer name and serial number pair, a key
fingerprint, and an alias (for example a friendly name). The
parameters that are provided are not copied, only referred to in a
criterion, so they must have at least the same life time as the created
OSSL_STORE_SEARCH.
OSSL_STORE_SEARCH_free() is used to free the OSSL_STORE_SEARCH. If the
argument is NULL, nothing is done.
Loader Functions
OSSL_STORE_SEARCH_get_type() returns the criterion type for the given
OSSL_STORE_SEARCH.
OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(), and
OSSL_STORE_SEARCH_get0_digest() are used to retrieve different data
from a OSSL_STORE_SEARCH, as available for each type. For more
information, see "SUPPORTED CRITERION TYPES" below.
SUPPORTED CRITERION TYPES
Currently supported criterion types are:
OSSL_STORE_SEARCH_BY_NAME
This criterion supports a search by exact match of subject name.
The subject name itself is a X509_NAME pointer. A criterion of
this type is created with OSSL_STORE_SEARCH_by_name(), and the
actual subject name is retrieved with
OSSL_STORE_SEARCH_get0_name().
OSSL_STORE_SEARCH_BY_ISSUER_SERIAL
This criterion supports a search by exact match of both issuer name
and serial number. The issuer name itself is a X509_NAME pointer,
and the serial number is a ASN1_INTEGER pointer. A criterion of
this type is created with OSSL_STORE_SEARCH_by_issuer_serial() and
the actual issuer name and serial number are retrieved with
OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial().
OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT
This criterion supports a search by exact match of key fingerprint.
The key fingerprint in itself is a string of bytes and its length,
as well as the algorithm that was used to compute the fingerprint.
The digest may be left unspecified (NULL), and in that case, the
loader has to decide on a default digest and compare fingerprints
accordingly. A criterion of this type is created with
OSSL_STORE_SEARCH_by_key_fingerprint() and the actual fingerprint
and its length can be retrieved with
OSSL_STORE_SEARCH_get0_bytes(). The digest can be retrieved with
OSSL_STORE_SEARCH_get0_digest().
OSSL_STORE_SEARCH_BY_ALIAS
This criterion supports a search by match of an alias of some kind.
The alias in itself is a simple C string. A criterion of this type
is created with OSSL_STORE_SEARCH_by_alias() and the actual alias
is retrieved with OSSL_STORE_SEARCH_get0_string().
RETURN VALUES
OSSL_STORE_SEARCH_by_name(), OSSL_STORE_SEARCH_by_issuer_serial(),
OSSL_STORE_SEARCH_by_key_fingerprint(), and
OSSL_STORE_SEARCH_by_alias() return a OSSL_STORE_SEARCH pointer on
success, or NULL on failure.
OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
OSSL_STORE_SEARCH. There is no error value.
OSSL_STORE_SEARCH_get0_name() returns a X509_NAME pointer on success,
or NULL when the given OSSL_STORE_SEARCH was of a different type.
OSSL_STORE_SEARCH_get0_serial() returns a ASN1_INTEGER pointer on
success, or NULL when the given OSSL_STORE_SEARCH was of a different
type.
OSSL_STORE_SEARCH_get0_bytes() returns a const unsigned char pointer
and sets *length to the strings length on success, or NULL when the
given OSSL_STORE_SEARCH was of a different type.
OSSL_STORE_SEARCH_get0_string() returns a const char pointer on
success, or NULL when the given OSSL_STORE_SEARCH was of a different
type.
OSSL_STORE_SEARCH_get0_digest() returns a const EVP_MD pointer. NULL
is a valid value and means that the store loader default will be used
when applicable.
SEE ALSO
ossl_store(7), OSSL_STORE_supports_search(3), OSSL_STORE_find(3)
HISTORY
OSSL_STORE_SEARCH, OSSL_STORE_SEARCH_by_name(),
OSSL_STORE_SEARCH_by_issuer_serial(),
OSSL_STORE_SEARCH_by_key_fingerprint(), OSSL_STORE_SEARCH_by_alias(),
OSSL_STORE_SEARCH_free(), OSSL_STORE_SEARCH_get_type(),
OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
OSSL_STORE_SEARCH_get0_bytes(), and OSSL_STORE_SEARCH_get0_string()
were added in OpenSSL 1.1.1.
COPYRIGHT
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
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
3.3.2 2024-09-04 OSSL_STORE_SEARCH(3ossl)
openssl 3.3.2 - Generated Tue Sep 17 18:34:36 CDT 2024