doc/man7/provider-object.pod

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