1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre Proncheryprovider-object - A specification for a provider-native object abstraction 6b077aed3SPierre Pronchery 7b077aed3SPierre Pronchery=head1 SYNOPSIS 8b077aed3SPierre Pronchery 9b077aed3SPierre Pronchery=for openssl multiple includes 10b077aed3SPierre Pronchery 11b077aed3SPierre Pronchery #include <openssl/core_object.h> 12b077aed3SPierre Pronchery #include <openssl/core_names.h> 13b077aed3SPierre Pronchery 14b077aed3SPierre Pronchery=head1 DESCRIPTION 15b077aed3SPierre Pronchery 16b077aed3SPierre ProncheryThe provider-native object abstraction is a set of L<OSSL_PARAM(3)> keys and 17b077aed3SPierre Proncheryvalues that can be used to pass provider-native objects to OpenSSL library 18b077aed3SPierre Proncherycode or between different provider operation implementations with the help 19b077aed3SPierre Proncheryof OpenSSL library code. 20b077aed3SPierre Pronchery 21b077aed3SPierre ProncheryThe intention is that certain provider-native operations can pass any sort 22b077aed3SPierre Proncheryof object that belong with other operations, or with OpenSSL library code. 23b077aed3SPierre Pronchery 24b077aed3SPierre ProncheryAn object may be passed in the following manners: 25b077aed3SPierre Pronchery 26b077aed3SPierre Pronchery=over 4 27b077aed3SPierre Pronchery 28b077aed3SPierre Pronchery=item 1. 29b077aed3SPierre Pronchery 30b077aed3SPierre ProncheryI<By value> 31b077aed3SPierre Pronchery 32b077aed3SPierre ProncheryThis means that the I<object data> is passed as an octet string or an UTF8 33b077aed3SPierre Proncherystring, which can be handled in diverse ways by other provided implementations. 34b077aed3SPierre ProncheryThe encoding of the object depends on the context it's used in; for example, 35b077aed3SPierre ProncheryL<OSSL_DECODER(3)> allows multiple encodings, depending on existing decoders. 36b077aed3SPierre ProncheryIf central OpenSSL library functionality is to handle the data directly, it 37b077aed3SPierre ProncheryB<must> be encoded in DER for all object types except for B<OSSL_OBJECT_NAME> 38b077aed3SPierre Pronchery(see L</Parameter reference> below), where it's assumed to a plain UTF8 string. 39b077aed3SPierre Pronchery 40b077aed3SPierre Pronchery=for comment A future extension might be to be able to specify encoding as a 41b077aed3SPierre Proncheryseparate parameter. 42b077aed3SPierre Pronchery 43b077aed3SPierre Pronchery=item 2. 44b077aed3SPierre Pronchery 45b077aed3SPierre ProncheryI<By reference> 46b077aed3SPierre Pronchery 47b077aed3SPierre ProncheryThis means that the I<object data> isn't passed directly, an I<object 48b077aed3SPierre Proncheryreference> is passed instead. It's an octet string that only the correct 49b077aed3SPierre Proncheryprovider understands correctly. 50b077aed3SPierre Pronchery 51b077aed3SPierre Pronchery=back 52b077aed3SPierre Pronchery 53b077aed3SPierre ProncheryObjects I<by value> can be used by anything that handles DER encoded 54b077aed3SPierre Proncheryobjects. 55b077aed3SPierre Pronchery 56b077aed3SPierre ProncheryObjects I<by reference> need a higher level of cooperation from the 57b077aed3SPierre Proncheryimplementation where the object originated (let's call it X) and its target 58b077aed3SPierre Proncheryimplementation (let's call it Y): 59b077aed3SPierre Pronchery 60b077aed3SPierre Pronchery=over 4 61b077aed3SPierre Pronchery 62b077aed3SPierre Pronchery=item 1. 63b077aed3SPierre Pronchery 64b077aed3SPierre ProncheryI<An object loading function in the target implementation> 65b077aed3SPierre Pronchery 66b077aed3SPierre ProncheryThe target implementation (Y) may have a function that can take an I<object 67b077aed3SPierre Proncheryreference>. This can only be used if the target implementation is from the 68b077aed3SPierre Proncherysame provider as the one originating the object abstraction in question (X). 69b077aed3SPierre Pronchery 70b077aed3SPierre ProncheryThe exact target implementation to use is determined from the I<object type> 71b077aed3SPierre Proncheryand possibly the I<object data type>. 72b077aed3SPierre ProncheryFor example, when the OpenSSL library receives an object abstraction with the 73b077aed3SPierre ProncheryI<object type> B<OSSL_OBJECT_PKEY>, it will fetch a L<provider-keymgmt(7)> 74b077aed3SPierre Proncheryusing the I<object data type> as its key type (the second argument in 75b077aed3SPierre ProncheryL<EVP_KEYMGMT_fetch(3)>). 76b077aed3SPierre Pronchery 77b077aed3SPierre Pronchery=item 2. 78b077aed3SPierre Pronchery 79b077aed3SPierre ProncheryI<An object exporter in the originating implementation> 80b077aed3SPierre Pronchery 81b077aed3SPierre ProncheryThe originating implementation (X) may have an exporter function. This 82b077aed3SPierre Proncheryexporter function can be used to export the object in L<OSSL_PARAM(3)> form, 83b077aed3SPierre Proncherythat can then be imported by the target implementation's imported function. 84b077aed3SPierre Pronchery 85b077aed3SPierre ProncheryThis can be used when it's not possible to fetch the target implementation 86b077aed3SPierre Pronchery(Y) from the same provider. 87b077aed3SPierre Pronchery 88b077aed3SPierre Pronchery=back 89b077aed3SPierre Pronchery 90b077aed3SPierre Pronchery=head2 Parameter reference 91b077aed3SPierre Pronchery 92b077aed3SPierre ProncheryA provider-native object abstraction is an L<OSSL_PARAM(3)> with a selection 93b077aed3SPierre Proncheryof the following parameters: 94b077aed3SPierre Pronchery 95b077aed3SPierre Pronchery=over 4 96b077aed3SPierre Pronchery 97b077aed3SPierre Pronchery=item "data" (B<OSSL_OBJECT_PARAM_DATA>) <octet string> or <UTF8 string> 98b077aed3SPierre Pronchery 99b077aed3SPierre ProncheryThe object data I<passed by value>. 100b077aed3SPierre Pronchery 101b077aed3SPierre Pronchery=item "reference" (B<OSSL_OBJECT_PARAM_REFERENCE>) <octet string> 102b077aed3SPierre Pronchery 103b077aed3SPierre ProncheryThe object data I<passed by reference>. 104b077aed3SPierre Pronchery 105b077aed3SPierre Pronchery=item "type" (B<OSSL_OBJECT_PARAM_TYPE>) <integer> 106b077aed3SPierre Pronchery 107b077aed3SPierre ProncheryThe I<object type>, a number that may have any of the following values (all 108b077aed3SPierre Proncherydefined in F<< <openssl/core_object.h> >>): 109b077aed3SPierre Pronchery 110b077aed3SPierre Pronchery=over 4 111b077aed3SPierre Pronchery 112b077aed3SPierre Pronchery=item B<OSSL_OBJECT_NAME> 113b077aed3SPierre Pronchery 114b077aed3SPierre ProncheryThe object data may only be I<passed by value>, and should be a UTF8 115b077aed3SPierre Proncherystring. 116b077aed3SPierre Pronchery 117b077aed3SPierre ProncheryThis is useful for L<provider-storemgmt(7)> when a URI load results in new 118b077aed3SPierre ProncheryURIs. 119b077aed3SPierre Pronchery 120b077aed3SPierre Pronchery=item B<OSSL_OBJECT_PKEY> 121b077aed3SPierre Pronchery 122b077aed3SPierre ProncheryThe object data is suitable as provider-native B<EVP_PKEY> key data. The 123b077aed3SPierre Proncheryobject data may be I<passed by value> or I<passed by reference>. 124b077aed3SPierre Pronchery 125b077aed3SPierre Pronchery=item B<OSSL_OBJECT_CERT> 126b077aed3SPierre Pronchery 127b077aed3SPierre ProncheryThe object data is suitable as B<X509> data. The object data for this 128b077aed3SPierre Proncheryobject type can only be I<passed by value>, and should be an octet string. 129b077aed3SPierre Pronchery 130b077aed3SPierre ProncherySince there's no provider-native X.509 object, OpenSSL libraries that 131b077aed3SPierre Proncheryreceive this object abstraction are expected to convert the data to a 132b077aed3SPierre ProncheryB<X509> object with d2i_X509(). 133b077aed3SPierre Pronchery 134b077aed3SPierre Pronchery=item B<OSSL_OBJECT_CRL> 135b077aed3SPierre Pronchery 136b077aed3SPierre ProncheryThe object data is suitable as B<X509_CRL> data. The object data can 137b077aed3SPierre Proncheryonly be I<passed by value>, and should be an octet string. 138b077aed3SPierre Pronchery 139b077aed3SPierre ProncherySince there's no provider-native X.509 CRL object, OpenSSL libraries that 140b077aed3SPierre Proncheryreceive this object abstraction are expected to convert the data to a 141b077aed3SPierre ProncheryB<X509_CRL> object with d2i_X509_CRL(). 142b077aed3SPierre Pronchery 143b077aed3SPierre Pronchery=back 144b077aed3SPierre Pronchery 145b077aed3SPierre Pronchery=item "data-type" (B<OSSL_OBJECT_PARAM_DATA_TYPE>) <UTF8 string> 146b077aed3SPierre Pronchery 147b077aed3SPierre ProncheryThe specific type of the object content. Legitimate values depend on the 148b077aed3SPierre Proncheryobject type; if it is B<OSSL_OBJECT_PKEY>, the data type is expected to be a 149b077aed3SPierre Proncherykey type suitable for fetching a L<provider-keymgmt(7)> that can handle the 150b077aed3SPierre Proncherydata. 151b077aed3SPierre Pronchery 152b077aed3SPierre Pronchery=for comment For objects with an unknown object type (OSSL_OBJECT_PARAM_TYPE 153b077aed3SPierre Proncheryis either missing or has the value OSSL_OBJECT_UNKNOWN), libcrypto 154b077aed3SPierre Proncheryinterprets the object data type as the input type for a decoder. 155b077aed3SPierre Pronchery 156b077aed3SPierre Pronchery=item "data-structure" (B<OSSL_OBJECT_PARAM_DATA_STRUCTURE>) <UTF8 string> 157b077aed3SPierre Pronchery 158b077aed3SPierre ProncheryThe outermost structure of the object content. Legitimate values depend on 159b077aed3SPierre Proncherythe object type. 160b077aed3SPierre Pronchery 161b077aed3SPierre Pronchery=item "desc" (B<OSSL_OBJECT_PARAM_DESC>) <UTF8 string> 162b077aed3SPierre Pronchery 163b077aed3SPierre ProncheryA human readable text that describes extra details on the object. 164b077aed3SPierre Pronchery 165b077aed3SPierre Pronchery=back 166b077aed3SPierre Pronchery 167*aa795734SPierre ProncheryWhen a provider-native object abstraction is used, it I<must> contain object 168b077aed3SPierre Proncherydata in at least one form (object data I<passed by value>, i.e. the "data" 169b077aed3SPierre Proncheryitem, or object data I<passed by reference>, i.e. the "reference" item). 170b077aed3SPierre ProncheryBoth may be present at once, in which case the OpenSSL library code that 171b077aed3SPierre Proncheryreceives this will use the most optimal variant. 172b077aed3SPierre Pronchery 173b077aed3SPierre ProncheryFor objects with the object type B<OSSL_OBJECT_NAME>, that object type 174b077aed3SPierre ProncheryI<must> be given. 175b077aed3SPierre Pronchery 176b077aed3SPierre Pronchery=head1 SEE ALSO 177b077aed3SPierre Pronchery 178b077aed3SPierre ProncheryL<provider(7)>, L<OSSL_DECODER(3)> 179b077aed3SPierre Pronchery 180b077aed3SPierre Pronchery=head1 HISTORY 181b077aed3SPierre Pronchery 182b077aed3SPierre ProncheryThe concept of providers and everything surrounding them was 183b077aed3SPierre Proncheryintroduced in OpenSSL 3.0. 184b077aed3SPierre Pronchery 185b077aed3SPierre Pronchery=head1 COPYRIGHT 186b077aed3SPierre Pronchery 187*aa795734SPierre ProncheryCopyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 188b077aed3SPierre Pronchery 189b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 190b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 191b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 192b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 193b077aed3SPierre Pronchery 194b077aed3SPierre Pronchery=cut 195