*/
/* Functions offered by libcrypto to the providers */
- const OSSL_ITEM *core_gettable_params(const OSSL_PROVIDER *prov);
- int core_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]);
- int core_thread_start(const OSSL_PROVIDER *prov,
+ const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle);
+ int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]);
+ int core_thread_start(const OSSL_CORE_HANDLE *handle,
OSSL_thread_stop_handler_fn handfn);
- OPENSSL_CTX *core_get_library_context(const OSSL_PROVIDER *prov);
- void core_new_error(const OSSL_PROVIDER *prov);
- void core_set_error_debug(const OSSL_PROVIDER *prov,
+ OPENSSL_CORE_CTX *core_get_library_context(const OSSL_CORE_HANDLE *handle);
+ void core_new_error(const OSSL_CORE_HANDLE *handle);
+ void core_set_error_debug(const OSSL_CORE_HANDLE *handle,
const char *file, int line, const char *func);
- void core_vset_error(const OSSL_PROVIDER *prov,
+ void core_vset_error(const OSSL_CORE_HANDLE *handle,
uint32_t reason, const char *fmt, va_list args);
/*
const char *file, int line);
int CRYPTO_secure_allocated(const void *ptr);
void OPENSSL_cleanse(void *ptr, size_t len);
- unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
+
+ OSSL_CORE_BIO * BIO_new_file(const char *filename, const char *mode)
+ OSSL_CORE_BIO * BIO_new_membuf(const void *buf, int len)
+ int BIO_read_ex(OSSL_CORE_BIO *bio, void *data, size_t data_len,
+ size_t *bytes_read))
+ int BIO_write_ex(OSSL_CORE_BIO *bio, const void *data, size_t data_len,
+ size_t *written)
+ int BIO_free(OSSL_CORE_BIO *bio))
+ int BIO_vprintf(OSSL_CORE_BIO *bio, const char *format, va_list args)
+ int BIO_vsnprintf(char *buf, size_t n, const char *fmt, va_list args)
+
+ void self_test_cb(OPENSSL_CORE_CTX *ctx, OSSL_CALLBACK **cb, void **cbarg)
+
/* Functions offered by the provider to libcrypto */
void provider_teardown(void *provctx);
int operation_id,
const int *no_store);
const OSSL_ITEM *provider_get_reason_strings(void *provctx);
+ int provider_get_capabilities(void *provctx, const char *capability,
+ OSSL_CALLBACK *cb, void *arg);
=head1 DESCRIPTION
B<OSSL_get_{name}>.
For example, the "function" core_gettable_params() has these:
- typedef OSSL_ITEM *
- (OSSL_core_gettable_params_fn)(const OSSL_PROVIDER *prov);
+ typedef OSSL_PARAM *
+ (OSSL_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle);
static ossl_inline OSSL_NAME_core_gettable_params_fn
OSSL_get_core_gettable_params(const OSSL_DISPATCH *opf);
BIO_free OSSL_FUNC_BIO_FREE
BIO_vprintf OSSL_FUNC_BIO_VPRINTF
OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE
- OPENSSL_hexstr2buf OSSL_FUNC_OPENSSL_HEXSTR2BUF
OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB
For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
provider_get_params OSSL_FUNC_PROVIDER_GET_PARAMS
provider_query_operation OSSL_FUNC_PROVIDER_QUERY_OPERATION
provider_get_reason_strings OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
+ provider_get_capabilities OSSL_FUNC_PROVIDER_GET_CAPABILITIES
=head2 Core functions
core_gettable_params() returns a constant array of descriptor
B<OSSL_PARAM>, for parameters that core_get_params() can handle.
-core_get_params() retrieves I<prov> parameters from the core.
+core_get_params() retrieves parameters from the core for the given I<handle>.
See L</Core parameters> below for a description of currently known
parameters.
=for comment core_thread_start() TBA
-core_get_library_context() retrieves the library context in which the
-B<OSSL_PROVIDER> object I<prov> is stored.
+core_get_library_context() retrieves the library context in which the library
+object for the current provider is stored, accessible through the I<handle>.
This may sometimes be useful if the provider wishes to store a
reference to its context in the same library context.
core_new_error(), core_set_error_debug() and core_set_error() are
building blocks for reporting an error back to the core, with
-reference to the provider object I<prov>.
+reference to the I<handle>.
=over 4
BIO_vprintf(), OPENSSL_cleanse(), and OPENSSL_hexstr2buf()
correspond exactly to the public functions with the same name.
As a matter of fact, the pointers in the B<OSSL_DISPATCH> array are
-direct pointers to those public functions.
+direct pointers to those public functions. Note that the BIO functions take an
+B<OSSL_CORE_BIO> type rather than the standard B<BIO> type. This is to ensure
+that a provider does not mix BIOs from the core with BIOs used on the provider
+side (the two are not compatible).
OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be
passed into a provider. This may be ignored by a provider.
array that provides reason strings for reason codes the provider may
use when reporting errors using core_put_error().
+The provider_get_capabilities() function should call the callback I<cb> passing
+it a set of B<OSSL_PARAM>s and the caller supplied argument I<arg>. The
+B<OSSL_PARAM>s should provide details about the capability with the name given
+in the I<capability> argument relevant for the provider context I<provctx>. If a
+provider supports multiple capabilities with the given name then it may call the
+callback multipe times (one for each capability). Capabilities can be useful for
+describing the services that a provider can offer. For further details see the
+L</CAPABILITIES> section below. It should return 1 on success or 0 on error.
+
None of these functions are mandatory, but a provider is fairly
useless without at least provider_query_operation(), and
provider_gettable_params() is fairly useless if not accompanied by
provider_get_params().
+=head2 Provider parameters
+
+provider_get_params() can return the following provider parameters to the core:
+
+=over 4
+
+=item "name" (B<OSSL_PROV_PARAM_NAME>) <UTF8_ptr>
+
+This points to a string that should give a unique name for the provider.
+
+=item "version" (B<OSSL_PROV_PARAM_VERSION>) <UTF8_ptr>
+
+This points to a string that is a version number associated with this provider.
+OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different
+for any third party provider. This string is for informational purposes only.
+
+=item "buildinfo" (B<OSSL_PROV_PARAM_BUILDINFO>) <UTF8_ptr>
+
+This points to a string that is a build information associated with this provider.
+OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be
+different for any third party provider.
+
+=back
+
+provider_gettable_params() should return the above parameters.
+
+
=head2 Core parameters
-core_get_params() understands the following known parameters:
+core_get_params() can retrieve the following core parameters for each provider:
=over 4
-=item "openssl-version"
+=item "openssl-version" (B<OSSL_PROV_PARAM_CORE_VERSION>) <UTF8_ptr>
-This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
-OpenSSL libraries' full version string, i.e. the string expanded from
-the macro B<OPENSSL_VERSION_STR>.
+This points to the OpenSSL libraries' full version string, i.e. the string
+expanded from the macro B<OPENSSL_VERSION_STR>.
-=item "provider-name"
+=item "provider-name" (B<OSSL_PROV_PARAM_CORE_PROV_NAME>) <UTF8_ptr>
-This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
-OpenSSL libraries' idea of what the calling provider is called.
+This points to the OpenSSL libraries' idea of what the calling provider is named.
+
+=item "module-filename" (B<OSSL_PROV_PARAM_CORE_MODULE_FILENAME>) <UTF8_ptr>
+
+This points to a string containing the full filename of the providers
+module file.
=back
For more information on handling parameters, see L<OSSL_PARAM(3)> as
L<OSSL_PARAM_int(3)>.
+=head1 CAPABILITIES
+
+Capabilties describe some of the services that a provider can offer.
+Applications can query the capabilities to discover those services.
+
+=head3 "TLS-GROUP" Capability
+
+The "TLS-GROUP" capability can be queried by libssl to discover the list of
+TLS groups that a provider can support. Each group supported can be used for
+key exchange during a TLS handshake. TLS clients can advertise the list of
+TLS groups they support in the supported_groups extension, and TLS servers can
+select a group from the offered list that they also support. In this way a
+provider can add to the list of groups that libssl already supports with
+additional ones.
+
+Each TLS group that a provider supports should be described via the callback
+passed in through the provider_get_capabilities function. Each group should have
+the following details supplied (all are mandatory):
+
+=over 4
+
+=item "tls-group-name" (B<OSSL_CAPABILITY_TLS_GROUP_NAME>) <utf8 string>
+
+The name of the group as given in the IANA TLS Supported Groups registry
+L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>.
+
+=item "tls-group-name-internal" (B<OSSL_CAPABILITY_TLS_GROUP_NAME_INTERNAL>) <utf8 string>
+
+The name of the group as known by the provider. This could be the same as the
+"tls-group-name", but does not have to be.
+
+=item "tls-group-id" (B<OSSL_CAPABILITY_TLS_GROUP_ID>) <unsigned integer>
+
+The TLS group id value as given in the IANA TLS Supported Groups registry.
+
+=item "tls-group-alg" (B<OSSL_CAPABILITY_TLS_GROUP_ALG>) <utf8 string>
+
+The name of a Key Management algorithm that the provider offers and that should
+be used with this group. Keys created should be able to support key exchange.
+The algorithm must support key and parameter generation as well as the
+key/parameter generation parameter, B<OSSL_PKEY_PARAM_GROUP_NAME>. The group
+name given via "tls-group-name-internal" above will be passed via
+B<OSSL_PKEY_PARAM_GROUP_NAME> when libssl wishes to generate keys/parameters.
+
+=item "tls-group-sec-bits" (B<OSSL_CAPABILITY_TLS_GROUP_SECURITY_BITS>) <unsigned integer>
+
+The number of bits of security offered by keys in this group. The number of bits
+should be comparable with the ones given in table 2 and 3 of the NIST SP800-57
+document.
+
+=item "tls-min-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_TLS>) <integer>
+
+=item "tls-max-tls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_TLS>) <integer>
+
+=item "tls-min-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MIN_DTLS>) <integer>
+
+=item "tls-max-dtls" (B<OSSL_CAPABILITY_TLS_GROUP_MAX_DTLS>) <integer>
+
+These parameters can be used to describe the minimum and maximum TLS and DTLS
+versions supported by the group. The values equate to the on-the-wire encoding
+of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and
+TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum
+or maximum. A -1 indicates that the group should not be used in that protocol.
+
+=back
+
=head1 EXAMPLES
This is an example of a simple provider made available as a
/* Provider context */
struct prov_ctx_st {
- OSSL_PROVIDER *prov;
+ OSSL_CORE_HANDLE *handle;
}
/* operation context for the algorithm FOO */
if (fooctx != NULL)
fooctx->provctx = provctx;
else
- c_put_error(provctx->prov, E_MALLOC, __FILE__, __LINE__);
+ c_put_error(provctx->handle, E_MALLOC, __FILE__, __LINE__);
return fooctx;
}
{ 0, NULL }
};
- int OSSL_provider_init(const OSSL_PROVIDER *provider,
+ int OSSL_provider_init(const OSSL_CORE_HANDLE *handle,
const OSSL_DISPATCH *in,
const OSSL_DISPATCH **out,
void **provctx)
* ALEA IACTA EST, if the core retrieves the reason table
* regardless, that string will be displayed, otherwise not.
*/
- c_put_error(provider, E_MALLOC, __FILE__, __LINE__);
+ c_put_error(handle, E_MALLOC, __FILE__, __LINE__);
return 0;
}
+ pctx->handle = handle;
return 1;
}
projects / oweals / openssl.git / blobdiff