> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/files/dir_9ae62d232e1f8555f5337bbbbe2033a3/dir_a8642344d1890ac34080367e6f4e78c5/provider__keyservice_8h.md). # provider\_keyservice.h [Macros](#define-members) | [Typedefs](#typedef-members) | [Enumerations](#enum-members) `#include ` Include dependency graph for provider\_keyservice.h: ![](/files/ra7hvbndPLAiaNsBIQTp) [Go to the source code of this file.](/adk-5.0-programmers-guide/provider__keyservice_8h_source.md) | | | | ------- | --------------------------------------------------------------------------- | | Macros | | | #define | [KS\_PKEY\_PARAM\_CERT](#a3e45f26965d540a9d3ee3bc819aee24a) "certificate" | | #define | [KS\_PKEY\_PARAM\_KEYREF](#a8fe4cc4f8a3660c1bee76ca198d07dff) "keyref" | | | | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Typedefs | | | typedef void(\* | [ks\_trace\_callback](#afcf7437404424f6e27c15778b5b2af10)) (const char \*file, unsigned line, const char \*str) | | typedef int(\* | [ks\_set\_trace\_callback\_fn](#a3155d8d7753fe341f84753a990552aee)) (OSSL\_PROVIDER \*provider, enum [KsTraceCbType](#a6dcf784787180282d6ccafb17d2ef9ac) type, [ks\_trace\_callback](#afcf7437404424f6e27c15778b5b2af10) callback) | | | | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enumerations | | | enum | [KsTraceCbType](#a6dcf784787180282d6ccafb17d2ef9ac) { [KsTraceErrorCb](#a6dcf784787180282d6ccafb17d2ef9acaf2b5b019dc7988c692e4e0a2efd34492) = 0, [KsTraceDebugCb](#a6dcf784787180282d6ccafb17d2ef9acaf84edbc5d330254877fb82d9bc7e7302) = 1 } | ### MacroDefinition Documentation ### KS\_PKEY\_PARAM\_CERT \#define KS\_PKEY\_PARAM\_CERT \\"certificate\\" name of parameter certificate ### KS\_PKEY\_PARAM\_KEYREF \#define KS\_PKEY\_PARAM\_KEYREF \\"keyref\\" name of parameter key reference Parameters KS\_PKEY\_PARAM\_KEYREF and KS\_PKEY\_PARAM\_CERT are used to load the key pair and to read the certificate with the keyservice provider. Example code using a key reference `key_name` (C-string): ```cpp // load the provider OSSL_LIB_CTX *prov_libctx = OSSL_LIB_CTX_new(); OSSL_PROVIDER *prov = OSSL_PROVIDER_load(prov_libctx, "provider_keyservice_sdi"); // load key pair by keyref EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(prov_libctx, "RSA", "provider=keyservice_sdi"); OSSL_PARAM params[2]; params[0] = OSSL_PARAM_construct_utf8_string(KS_PKEY_PARAM_KEYREF, (char *)key_name, 0); params[1] = OSSL_PARAM_construct_end(); EVP_PKEY *pkey = NULL; EVP_PKEY_fromdata_init(ctx); EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params); EVP_PKEY_CTX_free(ctx); // export key parameters to get certificate OSSL_PARAM *export_params = NULL; EVP_PKEY_todata(pkey, EVP_PKEY_PUBLIC_KEY, &export_params); EVP_PKEY_free(pkey); // extract certificate from exported parameters const OSSL_PARAM *cert_param = OSSL_PARAM_locate_const(export_params, KS_PKEY_PARAM_CERT); const unsigned char *cert_data = NULL; size_t cert_len = 0; OSSL_PARAM_get_octet_string_ptr(cert_param, (const void **)&cert_data, &cert_len); ``` {% hint style="info" %} This example code does not consider error cases of used functions! Do not copy it without additional checks of returned values! {% endhint %} ### TypedefDocumentation ### ks\_set\_trace\_callback\_fn typedef int(\\\* ks\_set\_trace\_callback\_fn) (OSSL\_PROVIDER \\\*provider, enum \[KsTraceCbType]\(#a6dcf784787180282d6ccafb17d2ef9ac) type, \[ks\_trace\_callback]\(#afcf7437404424f6e27c15778b5b2af10) callback) Set a trace function into the keyservice provider to activate logging callbacks. This can be called after OSSL\_PROVIDER\_load() with the returned provider handle. **Parameters** \[in] **provider** handle of the loaded provider \[in] **callback** The callback function to be invoke invoked for logging messages #### Returns 1 for success, 0 for failure Example code using a key reference `key_name` (C-string): ```cpp // load the provider OSSL_LIB_CTX *prov_libctx = OSSL_LIB_CTX_new(); OSSL_PROVIDER *prov = OSSL_PROVIDER_load(prov_libctx, "provider_keyservice_sdi"); void *lib_handle = dlopen("provider_keyservice_sdi.so", RTLD_NOLOAD | RTLD_LAZY); // get function pointer from the loaded provider library to set trace callbacks ks_set_trace_callback_fn set_trace_cb = (ks_set_trace_callback_fn)dlsym(lib_handle, "ks_set_trace_callback"); set_trace_cb(prov, KsTraceErrorCb, keyservice_error_cb); // keyservice_error_cb is of type ks_trace_callback set_trace_cb(prov, KsTraceDebugCb, keyservice_debug_cb); // keyservice_debug_cb is of type ks_trace_callback dlclose(lib_handle); // no unload, just decrease reference counter ``` {% hint style="info" %} This example code does not consider error cases of used functions! Do not copy it without additional checks of returned values! OpenSSL 3.0 lacks of support for passing arguments to the provider context with or after of OSSL\_PROVIDER\_load(). Thus, provider\_keyservice\_sdi (and provider\_keyservice only invocation used for system processes like SDI) additionally export function "ks\_set\_trace\_callback", which allows to set the callbacks. Since OSSL\_PROVIDER\_load() already has used dlopen() on the provider library, it is recommended to use dlopen() with flag RTLD\_NOLOAD, which prevents loading the libray at twice. {% endhint %} ### ks\_trace\_callback typedef void(\\\* ks\_trace\_callback) (const char \\\*file, unsigned line, const char \\\*str) callback trace function invoked, if keyservice provider calls the internal logging function to trace out debug information. This function can eiter be set with function ks\_set\_trace\_callback\_fn either using KsTraceErrorCb to trace error conditions or KsTraceDebugCb to trace informational debug-level messages. {% hint style="info" %} Only process flow information is logged, key contents are never logged. {% endhint %} \*\*Parameters\*\* \[in] **file** filename of the module containing the trace point \[in] **line** source line of the module containing the trace point \[in] **str** logging information as zero-terminated string ### EnumerationType Documentation ### KsTraceCbType enum \[KsTraceCbType]\(#a6dcf784787180282d6ccafb17d2ef9ac) trace callback function types optionally supported by provider | | | | -------------- | ------------------------------------ | | Enumerator | | | KsTraceErrorCb | used to set the error trace callback | | KsTraceDebugCb | used set the debug trace callback | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/files/dir_9ae62d232e1f8555f5337bbbbe2033a3/dir_a8642344d1890ac34080367e6f4e78c5/provider__keyservice_8h.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.