OSSL_STORE_SEARCH(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 OSSL_STORE_SEARCH(3ossl) — bestie, let's go searching 💖

okay so this is the OpenSSL manual page for the OSSL_STORE_SEARCH fam — the type and the functions that let you build search criteria for OSSL_STORE. it's giving "i know the URI but i want to be picky about what i pull out of it." let's get into it 🎀

✨ 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 💅

so these functions are how you specify search criteria so you can hunt for specific objects through other names besides just the URI you handed to OSSL_STORE_open(). bestie, this is so useful when an app got a URI and then wants to add on search criteria in a uniform, supported way. no cap. ✨

🎀 Types 🎀

OSSL_STORE_SEARCH is an opaque type that holds the constructed search criterion, and you can hand it to an OSSL_STORE context with OSSL_STORE_find().

The calling application owns the allocation of an OSSL_STORE_SEARCH at all times, so be careful — do not deallocate it before OSSL_STORE_close() has been called for the OSSL_STORE context it was given to. seriously. that's the rule. 🙈

🌈 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 the girlies that create an OSSL_STORE_SEARCH from, respectively: a subject name, an issuer name + serial number pair, a key fingerprint, and an alias (like a friendly name, cute 💖).

⚠️ the parameters you provide are not copied, only referred to in a criterion — so they must live at least as long as the OSSL_STORE_SEARCH you created. keep them alive bestie, no premature goodbye 😭

OSSL_STORE_SEARCH_free() frees the OSSL_STORE_SEARCH. If the argument is NULL, nothing happens. iconic, no drama. 💅

⭐ 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 an OSSL_STORE_SEARCH, as available for each type. for the deets, scroll to "SUPPORTED CRITERION TYPES" below 👇

👑 SUPPORTED CRITERION TYPES 👑

currently supported criterion types are, and yes they all ate:

  • 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(). two for one, we love a bundle 💖
  • 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. slay or flop, no in-between 💀

OSSL_STORE_SEARCH_get_type() returns the criterion type of the given OSSL_STORE_SEARCH. There is no error value. it just is what it is.

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. so don't panic if you see NULL here, it's lowkey intentional 🫶

🔥 SEE ALSO 🔥

ossl_store(7), OSSL_STORE_supports_search(3), OSSL_STORE_find(3)

go read those next bestie, iykyk 💜

🌸 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. a little vintage moment, we respect it ✨

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

and that's the whole page, bestie!! this was OSSL_STORE_SEARCH(3ossl) from OpenSSL 3.5.9, dated 2026-09-29 🎀 mwah, go search something cute 💅💖🦋

📦 where this page comes from