$NetBSD: provider-object.7,v 1.5 2024/09/08 13:08:39 christos Exp $

-*- mode: troff; coding: utf-8 -*-
Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)

Standard preamble:
========================================================================
..

..

.. \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` "" . ds C' "" 'br\} . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF ========================================================================

Title "PROVIDER-OBJECT 7" For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
provider-object - A specification for a provider-native object abstraction Header "SYNOPSIS" .Vb 2 #include <openssl/core_object.h> #include <openssl/core_names.h> .Ve Header "DESCRIPTION" The provider-native object abstraction is a set of OSSL_PARAM\|(3) keys and values that can be used to pass provider-native objects to OpenSSL library code or between different provider operation implementations with the help of OpenSSL library code.

The intention is that certain provider-native operations can pass any sort of object that belong with other operations, or with OpenSSL library code.

An object may be passed in the following manners:

\fIBy value .Sp This means that the object data is passed as an octet string or an UTF8 string, which can be handled in diverse ways by other provided implementations. The encoding of the object depends on the context it's used in; for example, \fBOSSL_DECODER\|(3) allows multiple encodings, depending on existing decoders. If central OpenSSL library functionality is to handle the data directly, it \fBmust be encoded in DER for all object types except for OSSL_OBJECT_NAME (see "Parameter reference" below), where it's assumed to a plain UTF8 string. \fIBy reference .Sp This means that the object data isn't passed directly, an object reference is passed instead. It's an octet string that only the correct provider understands correctly.

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

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

\fIAn object loading function in the target implementation .Sp 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). .Sp The 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 \fIobject type OSSL_OBJECT_PKEY, it will fetch a provider-keymgmt\|(7) using the object data type as its key type (the second argument in \fBEVP_KEYMGMT_fetch\|(3)). \fIAn object exporter in the originating implementation .Sp The originating implementation (X) may have an exporter function. This exporter function can be used to export the object in OSSL_PARAM\|(3) form, that can then be imported by the target implementation's imported function. .Sp This can be used when it's not possible to fetch the target implementation (Y) from the same provider. Subsection "Parameter reference" A provider-native object abstraction is an OSSL_PARAM\|(3) with a selection of the following parameters: Item """data"" (OSSL_OBJECT_PARAM_DATA) <octet string> or <UTF8 string>" The object data passed by value. Item """reference"" (OSSL_OBJECT_PARAM_REFERENCE) <octet string>" The object data passed by reference. Item """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>): Item """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. Item """data-structure"" (OSSL_OBJECT_PARAM_DATA_STRUCTURE) <UTF8 string>" The outermost structure of the object content. Legitimate values depend on the object type. Item """desc"" (OSSL_OBJECT_PARAM_DESC) <UTF8 string>" A human readable text that describes extra details on the object.

When a provider-native object abstraction is used, it must contain object data in at least one form (object data passed by value, i.e. the "data" item, or object data passed by reference, i.e. 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.

For objects with the object type OSSL_OBJECT_NAME, that object type \fImust be given.

Header "SEE ALSO" \fBprovider\|(7), OSSL_DECODER\|(3) Header "HISTORY" The concept of providers and everything surrounding them was introduced in OpenSSL 3.0. Header "COPYRIGHT" Copyright 2020-2023 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>.