PROVIDER-OBJECT(7SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

🌸 NAME 🌸

provider-object — a whole spec for how we describe a provider-native object abstraction, bestie. It's the group chat rules for shipping objects around 💅

✨ SYNOPSIS ✨

#include <openssl/core_object.h>
#include <openssl/core_names.h>

🦋 DESCRIPTION 🦋

okay so the provider-native object abstraction is literally just a set of OSSL_PARAM(3) keys and values 🎀 You use them to pass provider-native objects over to OpenSSL library code, or between different provider operation implementations — with a lil assist from OpenSSL library code. Teamwork fr fr 🫶

The whole point (the intention, if we're being formal ✨) is that certain provider-native operations get to pass any sort of object that belongs with other operations, or with OpenSSL library code. No gatekeeping.

An object can be passed in these two ways:

  1. By value 💖

This means the object data itself gets passed as an octet string or a UTF8 string, and other provided implementations can handle it in all sorts of diverse ways. The encoding depends on the context it's used in — for example, OSSL_DECODER(3) allows multiple encodings, depending on which decoders exist. And if central OpenSSL library functionality is the one handling the data directly, then it must be encoded in DER for all object types except for OSSL_OBJECT_NAME (peep "Parameter reference" below 👀), where it's assumed to be a plain UTF8 string.

  1. By reference 🎀

This means the object data is not passed directly, bestie — an object reference goes instead. It's an octet string that only the correct provider understands correctly. If you don't get it, no hard feelings, it wasn't for you 🙈

Objects by value can be used by anything that handles DER encoded objects. Easy. Slay.

Objects by reference need a higher level of cooperation between the implementation where the object originated (let's call it X) and its target implementation (Y):

  1. An object loading function in the target implementation 🔥

The target implementation (Y) may have a function that can take an object reference. This can only be used if the target implementation is from the same provider as the one originating the object abstraction in question (X). Same-house energy only, no cap.

Which exact target implementation to use is determined from the object type and possibly the object data type. For example, when the OpenSSL library receives an object abstraction with the object type OSSL_OBJECT_PKEY, it will fetch a provider-keymgmt(7) using the object data type as its key type (the second argument in EVP_KEYMGMT_fetch(3)). Iconic behaviour honestly.

  1. An object exporter in the originating implementation 💜

The originating implementation (X) may have an exporter function. This exporter function can be used to export the object in OSSL_PARAM(3) form, which can then be imported by the target implementation's imported function.

You reach for this when it's not possible to fetch the target implementation (Y) from the same provider. Long-distance relationship, but make it work 🦋

🧚 Parameter reference 🧚

A provider-native object abstraction is an OSSL_PARAM(3) with a selection of the following parameters:

  • "data" (OSSL_OBJECT_PARAM_DATA) — <octet string> or <UTF8 string>. The object data that's passed by value.
  • "reference" (OSSL_OBJECT_PARAM_REFERENCE) — <octet string>. The object data that's passed by reference.
  • "type" (OSSL_OBJECT_PARAM_TYPE) — <integer>. The object type, a number that may have any of the following values (all defined in <openssl/core_object.h>):
    • OSSL_OBJECT_NAME — the object data may only be passed by value, and should be a UTF8 string. This is useful for provider-storemgmt(7) when a URI load results in new URIs. ✨
    • OSSL_OBJECT_PKEY — the object data is suitable as provider-native EVP_PKEY key data. The object data may be passed by value or passed by reference. Either way, queen 💅
    • OSSL_OBJECT_CERT — the object data is suitable as X509 data. The object data for this object type can only be passed by value, and should be an octet string. Since there's no provider-native X.509 object, OpenSSL libraries that receive this object abstraction are expected to convert the data to a X509 object with d2i_X509().
    • OSSL_OBJECT_CRL — the object data is suitable as X509_CRL data. The object data can only be passed by value, and should be an octet string. Since there's no provider-native X.509 CRL object, OpenSSL libraries that receive this object abstraction are expected to convert the data to a X509_CRL object with d2i_X509_CRL().
  • "data-type" (OSSL_OBJECT_PARAM_DATA_TYPE) — <UTF8 string>. The specific type of the object content. Legitimate values depend on the object type; if it is OSSL_OBJECT_PKEY, the data type is expected to be a key type suitable for fetching a provider-keymgmt(7) that can handle the data. 🗝️
  • "data-structure" (OSSL_OBJECT_PARAM_DATA_STRUCTURE) — <UTF8 string>. The outermost structure of the object content. Legitimate values depend on the object type.
  • "desc" (OSSL_OBJECT_PARAM_DESC) — <UTF8 string>. A human readable text that describes extra details on the object. (A lil caption for your object, basically 🎀)
⚠️ the rules, bestie: when a provider-native object abstraction is used, it must contain object data in at least one form — either object data passed by value (the "data" item) or object data passed by reference (the "reference" item). Both may be present at once, in which case the OpenSSL library code that receives this will use the most optimal variant. And for objects with the object type OSSL_OBJECT_NAME, that object type must be given. No skipping, fr fr.

🌈 SEE ALSO 🌈

provider(7), OSSL_DECODER(3)

👑 HISTORY 👑

The concept of providers and everything surrounding them was introduced in OpenSSL 3.0. A whole era began, honestly.

Copyright 2020-2022 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.

k that's the whole page, bestie 🫶 this was PROVIDER-OBJECT(7SSL) from the OpenSSL fam, version 4.0.3, dated 2026-09-29. go forth and abstract your objects responsibly ✨🍓

📦 where this page comes from