OSSL_STORE_SEARCH(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 OSSL_STORE_SEARCH — the 3ossl manual, but make it make sense

okay so bestie, buckle up 🎀 this is the OpenSSL page for OSSL_STORE_SEARCH and friends — literally the type and functions you use to create OSSL_STORE search criteria. it's giving "how do i find my stuff without only using the URI" energy and honestly? iconic.

✨ 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 exist to hand over search criteria — like, ways to hunt down specific objects through names other than just the URI you already gave to OSSL_STORE_open(). highkey useful if your app got handed a URI and now wants to add extra search criteria in a uniform, supported way. no cap, that's the whole vibe. 🦋

🧚 Types

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

bestie listen 💀 the calling application owns the allocation of an OSSL_STORE_SEARCH at all times, so please be careful and do not deallocate it before OSSL_STORE_close() has been called for the OSSL_STORE context you gave it to. that's a whole mess you don't want.

🍓 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() 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 right?).
  • OSSL_STORE_SEARCH_free() frees the OSSL_STORE_SEARCH. if the argument is NULL, nothing happens — it literally just vibes. 💅
⚠️ important detail, don't skip: the parameters you provide 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. periodt.

👑 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() retrieve different data from an OSSL_STORE_SEARCH, as available for each type. for the deets, peek at "SUPPORTED CRITERION TYPES" below 👇

🔥 SUPPORTED CRITERION TYPES 🔥

currently supported criterion types are:

🌈 OSSL_STORE_SEARCH_BY_NAME

search by exact match of subject name. the subject name itself is an X509_NAME pointer. you create this with OSSL_STORE_SEARCH_by_name(), and grab the actual subject name back with OSSL_STORE_SEARCH_get0_name().

🌈 OSSL_STORE_SEARCH_BY_ISSUER_SERIAL

search by exact match of both issuer name and serial number. the issuer name is an X509_NAME pointer and the serial number is an ASN1_INTEGER pointer. created with OSSL_STORE_SEARCH_by_issuer_serial(), and you retrieve the actual issuer name and serial number with OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial().

🌈 OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT

search by exact match of key fingerprint. the key fingerprint itself is a string of bytes plus its length, plus the algorithm used to compute it. the digest can be left unspecified (NULL), and in that case the loader has to decide on a default digest and compare fingerprints accordingly. created with OSSL_STORE_SEARCH_by_key_fingerprint(); retrieve the actual fingerprint and its length with OSSL_STORE_SEARCH_get0_bytes(). the digest comes back via OSSL_STORE_SEARCH_get0_digest().

🌈 OSSL_STORE_SEARCH_BY_ALIAS

search by match of an alias of some kind. the alias is a simple C string. created with OSSL_STORE_SEARCH_by_alias(), and the actual alias comes back 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 an 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 — slay, one less thing to check.
  • OSSL_STORE_SEARCH_get0_name() returns an X509_NAME pointer on success, or NULL when the given OSSL_STORE_SEARCH was of a different type.
  • OSSL_STORE_SEARCH_get0_serial() returns an 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 string's 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 here and means the store loader default will be used when applicable. not a bug, it's a feature 💅

👀 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. vintage but still eating ✨

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

okay that's the whole page bestie, you're officially an OSSL_STORE_SEARCH girlie now 🫶 go find your objects. this was OpenSSL 3.5.0, dated 2026-09-25, and that's the OSSL_STORE_SEARCH(3ossl) tea ☕💜

📦 where this page comes from