=head1 SYNOPSIS
- #include <openssl/core_numbers.h>
+ #include <openssl/core_dispatch.h>
/*
* None of these are actual functions, but are displayed like this for
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_CORE_CTX *core_get_library_context(const OSSL_CORE_HANDLE *handle);
+ OPENSSL_CORE_CTX *core_get_libctx(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);
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
All these "functions" have a corresponding function type definition
named B<OSSL_{name}_fn>, and a helper function to retrieve the
function pointer from a B<OSSL_DISPATCH> element named
-B<OSSL_get_{name}>.
+B<OSSL_FUNC_{name}>.
For example, the "function" core_gettable_params() has these:
typedef OSSL_PARAM *
- (OSSL_core_gettable_params_fn)(const OSSL_CORE_HANDLE *handle);
+ (OSSL_FUNC_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);
+ OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf);
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
-macros in L<openssl-core_numbers.h(7)>, as follows:
+macros in L<openssl-core_dispatch.h(7)>, as follows:
For I<in> (the B<OSSL_DISPATCH> array passed from F<libcrypto> to the
provider):
core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS
core_get_params OSSL_FUNC_CORE_GET_PARAMS
core_thread_start OSSL_FUNC_CORE_THREAD_START
- core_get_library_context OSSL_FUNC_CORE_GET_LIBRARY_CONTEXT
+ core_get_libctx OSSL_FUNC_CORE_GET_LIBCTX
core_new_error OSSL_FUNC_CORE_NEW_ERROR
core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG
core_set_error OSSL_FUNC_CORE_SET_ERROR
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
+ provider_self_test OSSL_FUNC_PROVIDER_SELF_TEST
=head2 Core functions
=for comment core_thread_start() TBA
-core_get_library_context() retrieves the library context in which the library
+core_get_libctx() 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.
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 multiple 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.
+
+The provider_self_test() function should perform known answer tests on a subset
+of the algorithms that it uses, and may also verify the integrity of the
+provider module. It should return 1 on success or 0 on error. It will return 1
+if this function is not used.
+
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.
+
+=item "status" (B<OSSL_PROV_PARAM_STATUS>) <unsigned integer>
+
+This returns 0 if the provider has entered an error state, otherwise it returns
+1.
+
+=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 points to the OpenSSL libraries' full version string, i.e. the string
+expanded from the macro B<OPENSSL_VERSION_STR>.
+
+=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' full version string, i.e. the string expanded from
-the macro B<OPENSSL_VERSION_STR>.
+This points to the OpenSSL libraries' idea of what the calling provider is named.
-=item "provider-name"
+=item "module-filename" (B<OSSL_PROV_PARAM_CORE_MODULE_FILENAME>) <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 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
+
+Capabilities 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
+I<key exchange> (KEX) or I<key encapsulation method> (KEM) 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, except
+B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>):
+
+=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 I<key exchange>
+or I<key encapsulation method> (KEM), as implied by the optional
+B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM> flag.
+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-group-is-kem" (B<OSSL_CAPABILITY_TLS_GROUP_IS_KEM>) <unsigned integer>
+
+Boolean flag to describe if the group should be used in I<key exchange> (KEX)
+mode (0, default) or in I<key encapsulation method> (KEM) mode (1).
+
+This parameter is optional: if not specified, KEX mode is assumed as the default
+mode for the group.
+
+In KEX mode, in a typical Diffie-Hellman fashion, both sides execute I<keygen>
+then I<derive> against the peer public key. To operate in KEX mode, the group
+implementation must support the provider functions as described in
+L<provider-keyexch(7)>.
+
+In KEM mode, the client executes I<keygen> and sends its public key, the server
+executes I<encapsulate> using the client's public key and sends back the
+resulting I<ciphertext>, finally the client executes I<decapsulate> to retrieve
+the same I<shared secret> generated by the server's I<encapsulate>. To operate
+in KEM mode, the group implementation must support the provider functions as
+described in L<provider-kem(7)>.
+
+Both in KEX and KEM mode, the resulting I<shared secret> is then used according
+to the protocol specification.
+
+=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
#include <malloc.h>
#include <openssl/core.h>
- #include <openssl/core_numbers.h>
+ #include <openssl/core_dispatch.h>
/* Errors used in this provider */
#define E_MALLOC 1
/*
* To ensure we get the function signature right, forward declare
- * them using function types provided by openssl/core_numbers.h
+ * them using function types provided by openssl/core_dispatch.h
*/
- OSSL_OP_bar_newctx_fn foo_newctx;
- OSSL_OP_bar_freectx_fn foo_freectx;
- OSSL_OP_bar_init_fn foo_init;
- OSSL_OP_bar_update_fn foo_update;
- OSSL_OP_bar_final_fn foo_final;
+ OSSL_FUNC_bar_newctx_fn foo_newctx;
+ OSSL_FUNC_bar_freectx_fn foo_freectx;
+ OSSL_FUNC_bar_init_fn foo_init;
+ OSSL_FUNC_bar_update_fn foo_update;
+ OSSL_FUNC_bar_final_fn foo_final;
- OSSL_provider_query_operation_fn p_query;
- OSSL_provider_get_reason_strings_fn p_reasons;
- OSSL_provider_teardown_fn p_teardown;
+ OSSL_FUNC_provider_query_operation_fn p_query;
+ OSSL_FUNC_provider_get_reason_strings_fn p_reasons;
+ OSSL_FUNC_provider_teardown_fn p_teardown;
OSSL_provider_init_fn OSSL_provider_init;
- OSSL_core_put_error *c_put_error = NULL;
+ OSSL_FUNC_core_put_error *c_put_error = NULL;
/* Provider context */
struct prov_ctx_st {
for (; in->function_id != 0; in++)
switch (in->function_id) {
case OSSL_FUNC_CORE_PUT_ERROR:
- c_put_error = OSSL_get_core_put_error(in);
+ c_put_error = OSSL_FUNC_core_put_error(in);
break;
}
return 1;
}
-This relies on a few things existing in F<openssl/core_numbers.h>:
+This relies on a few things existing in F<openssl/core_dispatch.h>:
#define OSSL_OP_BAR 4711
#define OSSL_FUNC_BAR_NEWCTX 1
- typedef void *(OSSL_OP_bar_newctx_fn)(void *provctx);
- static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
- { return (OSSL_OP_bar_newctx_fn *)opf->function; }
+ typedef void *(OSSL_FUNC_bar_newctx_fn)(void *provctx);
+ static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf)
+ { return (OSSL_FUNC_bar_newctx_fn *)opf->function; }
#define OSSL_FUNC_BAR_FREECTX 2
- typedef void (OSSL_OP_bar_freectx_fn)(void *ctx);
- static ossl_inline OSSL_get_bar_newctx(const OSSL_DISPATCH *opf)
- { return (OSSL_OP_bar_freectx_fn *)opf->function; }
+ typedef void (OSSL_FUNC_bar_freectx_fn)(void *ctx);
+ static ossl_inline OSSL_FUNC_bar_newctx(const OSSL_DISPATCH *opf)
+ { return (OSSL_FUNC_bar_freectx_fn *)opf->function; }
#define OSSL_FUNC_BAR_INIT 3
- typedef void *(OSSL_OP_bar_init_fn)(void *ctx);
- static ossl_inline OSSL_get_bar_init(const OSSL_DISPATCH *opf)
- { return (OSSL_OP_bar_init_fn *)opf->function; }
+ typedef void *(OSSL_FUNC_bar_init_fn)(void *ctx);
+ static ossl_inline OSSL_FUNC_bar_init(const OSSL_DISPATCH *opf)
+ { return (OSSL_FUNC_bar_init_fn *)opf->function; }
#define OSSL_FUNC_BAR_UPDATE 4
- typedef void *(OSSL_OP_bar_update_fn)(void *ctx,
+ typedef void *(OSSL_FUNC_bar_update_fn)(void *ctx,
unsigned char *in, size_t inl);
- static ossl_inline OSSL_get_bar_update(const OSSL_DISPATCH *opf)
- { return (OSSL_OP_bar_update_fn *)opf->function; }
+ static ossl_inline OSSL_FUNC_bar_update(const OSSL_DISPATCH *opf)
+ { return (OSSL_FUNC_bar_update_fn *)opf->function; }
#define OSSL_FUNC_BAR_FINAL 5
- typedef void *(OSSL_OP_bar_final_fn)(void *ctx);
- static ossl_inline OSSL_get_bar_final(const OSSL_DISPATCH *opf)
- { return (OSSL_OP_bar_final_fn *)opf->function; }
+ typedef void *(OSSL_FUNC_bar_final_fn)(void *ctx);
+ static ossl_inline OSSL_FUNC_bar_final(const OSSL_DISPATCH *opf)
+ { return (OSSL_FUNC_bar_final_fn *)opf->function; }
=head1 SEE ALSO
projects / openssl.git / blobdiff