*Simo Sorce*
+ * Initial support for opaque symmetric keys objects. These replace the ad-hoc byte
+ arrays that are pervasive throughout the library.
+
+ *Dmitry Belyavskiy and Simo Sorce*
+
* For TLSv1.3: Add capability for a client to send multiple key shares. Extend the scope of
`SSL_OP_CIPHER_SERVER_PREFERENCE` to cover server-side key exchange group selection.
Extend the server-side key exchange group selection algorithm and related group list syntax
GENERATE[html/man3/EVP_SIGNATURE.html]=man3/EVP_SIGNATURE.pod
DEPEND[man/man3/EVP_SIGNATURE.3]=man3/EVP_SIGNATURE.pod
GENERATE[man/man3/EVP_SIGNATURE.3]=man3/EVP_SIGNATURE.pod
+DEPEND[html/man3/EVP_SKEY.html]=man3/EVP_SKEY.pod
+GENERATE[html/man3/EVP_SKEY.html]=man3/EVP_SKEY.pod
+DEPEND[man/man3/EVP_SKEY.3]=man3/EVP_SKEY.pod
+GENERATE[man/man3/EVP_SKEY.3]=man3/EVP_SKEY.pod
+DEPEND[html/man3/EVP_SKEYMGMT.html]=man3/EVP_SKEYMGMT.pod
+GENERATE[html/man3/EVP_SKEYMGMT.html]=man3/EVP_SKEYMGMT.pod
+DEPEND[man/man3/EVP_SKEYMGMT.3]=man3/EVP_SKEYMGMT.pod
+GENERATE[man/man3/EVP_SKEYMGMT.3]=man3/EVP_SKEYMGMT.pod
DEPEND[html/man3/EVP_SealInit.html]=man3/EVP_SealInit.pod
GENERATE[html/man3/EVP_SealInit.html]=man3/EVP_SealInit.pod
DEPEND[man/man3/EVP_SealInit.3]=man3/EVP_SealInit.pod
html/man3/EVP_PKEY_verify_recover.html \
html/man3/EVP_RAND.html \
html/man3/EVP_SIGNATURE.html \
+html/man3/EVP_SKEY.html \
+html/man3/EVP_SKEYMGMT.html \
html/man3/EVP_SealInit.html \
html/man3/EVP_SignInit.html \
html/man3/EVP_VerifyInit.html \
man/man3/EVP_PKEY_verify_recover.3 \
man/man3/EVP_RAND.3 \
man/man3/EVP_SIGNATURE.3 \
+man/man3/EVP_SKEY.3 \
+man/man3/EVP_SKEYMGMT.3 \
man/man3/EVP_SealInit.3 \
man/man3/EVP_SignInit.3 \
man/man3/EVP_VerifyInit.3 \
GENERATE[html/man7/provider-signature.html]=man7/provider-signature.pod
DEPEND[man/man7/provider-signature.7]=man7/provider-signature.pod
GENERATE[man/man7/provider-signature.7]=man7/provider-signature.pod
+DEPEND[html/man7/provider-skeymgmt.html]=man7/provider-skeymgmt.pod
+GENERATE[html/man7/provider-skeymgmt.html]=man7/provider-skeymgmt.pod
+DEPEND[man/man7/provider-skeymgmt.7]=man7/provider-skeymgmt.pod
+GENERATE[man/man7/provider-skeymgmt.7]=man7/provider-skeymgmt.pod
DEPEND[html/man7/provider-storemgmt.html]=man7/provider-storemgmt.pod
GENERATE[html/man7/provider-storemgmt.html]=man7/provider-storemgmt.pod
DEPEND[man/man7/provider-storemgmt.7]=man7/provider-storemgmt.pod
html/man7/provider-object.html \
html/man7/provider-rand.html \
html/man7/provider-signature.html \
+html/man7/provider-skeymgmt.html \
html/man7/provider-storemgmt.html \
html/man7/provider.html \
html/man7/proxy-certificates.html \
man/man7/provider-object.7 \
man/man7/provider-rand.7 \
man/man7/provider-signature.7 \
+man/man7/provider-skeymgmt.7 \
man/man7/provider-storemgmt.7 \
man/man7/provider.7 \
man/man7/proxy-certificates.7 \
EVP_DecryptFinal_ex,
EVP_CipherInit_ex,
EVP_CipherInit_ex2,
+EVP_CipherInit_SKEY,
EVP_CipherUpdate,
EVP_CipherFinal_ex,
EVP_CIPHER_CTX_set_key_length,
int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
const unsigned char *key, const unsigned char *iv,
int enc, const OSSL_PARAM params[]);
+ int EVP_CipherInit_SKEY(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher,
+ EVP_SKEY *skey, const unsigned char *iv, size_t iv_len,
+ int enc, const OSSL_PARAM params[]);
int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, const unsigned char *in, int inl);
int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
for encryption, 0 for decryption and -1 to leave the value unchanged
(the actual value of 'enc' being supplied in a previous call).
+=item EVP_CipherInit_SKEY()
+
+This function is similar to EVP_CipherInit_ex2() but accepts a
+symmetric key object of type I<EVP_SKEY> as a key.
+
=item EVP_CIPHER_CTX_reset()
Clears all information from a cipher context and free up any allocated memory
Enables or disables padding. This function should be called after the context
is set up for encryption or decryption with EVP_EncryptInit_ex2(),
-EVP_DecryptInit_ex2() or EVP_CipherInit_ex2(). By default encryption operations
-are padded using standard block padding and the padding is checked and removed
-when decrypting. If the I<pad> parameter is zero then no padding is
-performed, the total amount of data encrypted or decrypted must then
-be a multiple of the block size or an error will occur. I<x> B<MUST NOT> be NULL.
+EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(), or EVP_CipherInit_SKEY(). By
+default encryption operations are padded using standard block padding and the
+padding is checked and removed when decrypting. If the I<pad> parameter is zero
+then no padding is performed, the total amount of data encrypted or decrypted
+must then be a multiple of the block size or an error will occur. I<x> B<MUST
+NOT> be NULL.
=item EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length()
EVP_DecryptInit_ex2() and EVP_DecryptUpdate() return 1 for success and 0 for failure.
EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
-EVP_CipherInit_ex2() and EVP_CipherUpdate() return 1 for success and 0 for
-failure.
+EVP_CipherInit_ex2(), EVP_CipherInit_SKEY() and EVP_CipherUpdate() return 1 for
+success and 0 for failure.
EVP_CipherFinal_ex() returns 0 for an encryption/decryption failure or 1 for
success.
EVP_CIPHER_CTX_dup() was added in OpenSSL 3.2.
+EVP_CipherInit_SKEY() was added in OpenSSL 3.5.
+
Prior to OpenSSL 3.5, passing a NULL I<ctx> to
B<EVP_CIPHER_CTX_get_block_size()> would result in a NULL pointer dereference,
rather than a 0 return value indicating an error.
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_SKEY, EVP_SKEY_generate,
+EVP_SKEY_import, EVP_SKEY_import_raw_key, EVP_SKEY_up_ref,
+EVP_SKEY_export, EVP_SKEY_get_raw_key, EVP_SKEY_get0_key_id,
+EVP_SKEY_get0_skeymgmt_name, EVP_SKEY_get0_provider_name,
+EVP_SKEY_free
+- opaque symmetric key allocation and handling functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ typedef evp_skey_st EVP_SKEY;
+
+ EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
+ const char *propquery, const OSSL_PARAM *params);
+ EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
+ const char *propquery,
+ int selection, const OSSL_PARAM *params);
+ EVP_SKEY *EVP_SKEY_import_raw_key(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
+ unsigned char *key, size_t *len,
+ const char *propquery);
+ int EVP_SKEY_export(const EVP_SKEY *skey, int selection,
+ OSSL_CALLBACK *export_cb, void *export_cbarg);
+ int EVP_SKEY_get_raw_key(const EVP_SKEY *skey, const unsigned char **key,
+ size_t *len);
+ const char *EVP_SKEY_get0_key_id(const EVP_SKEY *skey);
+
+ const char *EVP_SKEY_get0_skeymgmt_name(const EVP_SKEY *skey);
+ const char *EVP_SKEY_get0_provider_name(const EVP_SKEY *skey);
+
+ int EVP_SKEY_up_ref(EVP_SKEY *key);
+ void EVP_SKEY_free(EVP_SKEY *key);
+
+=head1 DESCRIPTION
+
+B<EVP_SKEY> is a generic structure to hold symmetric keys as opaque objects.
+The keys themselves are often referred to as the "internal key", and are handled by
+providers using L<EVP_SKEYMGMT(3)>.
+
+Conceptually, an B<EVP_SKEY> internal key may hold a symmetric key, and along
+with those, key parameters if the key type requires them.
+
+The EVP_SKEY_generate() functions creates a new B<EVP_SKEY> object and
+initializes it according to the B<params> argument.
+
+The EVP_SKEY_import() function allocates an empty B<EVP_SKEY> structure
+which is used by OpenSSL to store symmetric keys, assigns the
+B<EVP_SKEYMGMT> object associated with the key, and initializes the object from
+the B<params> argument.
+
+The EVP_SKEY_import_raw_key() function is a helper that creates an B<EVP_SKEY> object
+containing the raw byte representation of the symmetric keys.
+
+The EVP_SKEY_export() function extracts values from a key I<skey> using the
+I<selection>. I<selection> is described below. It uses a callback I<export_cb>
+that gets passed the value of I<export_cbarg>. See L<openssl-core.h(7)> for
+more information about the callback. Note that the L<OSSL_PARAM(3)> array that
+is passed to the callback is not persistent after the callback returns.
+
+The EVP_SKEY_get_raw_key() function copies raw key bytes to the passed buffer
+and sets the key len. The operation can fail when the underlying key
+management doesn't support export of the secret key.
+
+The EVP_SKEY_get0_key_id() returns a NUL-terminated string providing some
+human-readable identifier of the key if provided by the underlying key
+management. The pointer becomes invalid after freeing the EVP_SKEY object.
+
+The EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() return the
+names of the associated EVP_SKEYMGMT object and its provider correspondingly.
+
+EVP_SKEY_up_ref() increments the reference count of I<key>.
+
+EVP_SKEY_free() decrements the reference count of I<key> and, if the reference
+count is zero, frees it. If I<key> is NULL, nothing is done.
+
+=head2 Selections
+
+The following constants can be used for I<selection>:
+
+=over 4
+
+=item B<OSSL_SKEYMGMT_SELECT_SECRET_KEY>
+
+Only the raw key representation will be selected.
+
+=item B<OSSL_SKEYMGMT_SELECT_PARAMETERS>
+
+Only the key parameters will be selected. This includes optional key
+parameters.
+
+=item B<OSSL_SKEYMGMT_SELECT_ALL>
+
+All parameters will be selected.
+
+=back
+
+=head1 NOTES
+
+The B<EVP_SKEY> structure is used by various OpenSSL functions which require a
+general symmetric key without reference to any particular algorithm.
+
+=head1 RETURN VALUES
+
+EVP_SKEY_generate(), EVP_SKEY_import() and EVP_SKEY_import_raw_key() return
+either the newly allocated B<EVP_SKEY> structure or NULL if an error occurred.
+
+EVP_SKEY_get0_key_id() returns either a valid pointer or NULL.
+
+EVP_SKEY_up_ref() returns 1 for success and 0 on failure.
+
+EVP_SKEY_export() and EVP_SKEY_get_raw_key() return 1 for success and 0 on failure.
+
+EVP_SKEY_get0_skeymgmt_name() and EVP_SKEY_get0_provider_name() return the
+names of the associated EVP_SKEYMGMT object and its provider correspondigly.
+
+=head1 SEE ALSO
+
+L<EVP_SKEYMGMT(3)>, L<provider(7)>, L<OSSL_PARAM(3)>
+
+=head1 HISTORY
+
+The B<EVP_SKEY> API and functions EVP_SKEY_export(),
+EVP_SKEY_free(), EVP_SKEY_get_raw_key(), EVP_SKEY_import(),
+EVP_SKEY_import_raw_key(), EVP_SKEY_up_ref(), EVP_SKEY_generate(),
+EVP_SKEY_get0_key_id(), EVP_SKEY_get0_provider_name(), and
+EVP_SKEY_get0_skeymgmt_name()
+were introduced in OpenSSL 3.5.
+
+=head1 COPYRIGHT
+
+Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_SKEYMGMT,
+EVP_SKEYMGMT_fetch,
+EVP_SKEYMGMT_up_ref,
+EVP_SKEYMGMT_free,
+EVP_SKEYMGMT_get0_provider,
+EVP_SKEYMGMT_is_a,
+EVP_SKEYMGMT_get0_description,
+EVP_SKEYMGMT_get0_name,
+EVP_SKEYMGMT_do_all_provided,
+EVP_SKEYMGMT_names_do_all,
+EVP_SKEYMGMT_get0_gen_settable_params,
+EVP_SKEYMGMT_get0_imp_settable_params
+- EVP key management routines for opaque symmetric keys
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ typedef struct evp_sskeymgmt_st EVP_SKEYMGMT;
+
+ EVP_SKEYMGMT *EVP_SKEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
+ const char *properties);
+ int EVP_SKEYMGMT_up_ref(EVP_SKEYMGMT *skeymgmt);
+ void EVP_SKEYMGMT_free(EVP_SKEYMGMT *skeymgmt);
+ const OSSL_PROVIDER *EVP_SKEYMGMT_get0_provider(const EVP_SKEYMGMT *skeymgmt);
+ int EVP_SKEYMGMT_is_a(const EVP_SKEYMGMT *skeymgmt, const char *name);
+ const char *EVP_SKEYMGMT_get0_name(const EVP_SKEYMGMT *skeymgmt);
+ const char *EVP_SKEYMGMT_get0_description(const EVP_SKEYMGMT *skeymgmt);
+
+ void EVP_SKEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
+ void (*fn)(EVP_SKEYMGMT *skeymgmt, void *arg),
+ void *arg);
+ int EVP_SKEYMGMT_names_do_all(const EVP_SKEYMGMT *skeymgmt,
+ void (*fn)(const char *name, void *data),
+ void *data);
+ const OSSL_PARAM *EVP_SKEYMGMT_get0_gen_settable_params(const EVP_SKEYMGMT *skeymgmt);
+ const OSSL_PARAM *EVP_SKEYMGMT_get0_imp_settable_params(const EVP_SKEYMGMT *skeymgmt);
+
+=head1 DESCRIPTION
+
+B<EVP_SKEYMGMT> is a method object that represents symmetric key management
+implementations for different cryptographic algorithms. This method object
+provides functionality to allow providers to import key material from the
+outside, as well as export key material to the outside.
+
+Most of the functionality can only be used internally and has no public
+interface, this opaque object is simply passed into other functions when
+needed.
+
+EVP_SKEYMGMT_fetch() looks for an algorithm within a provider that
+has been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the
+name given by I<algorithm> and the properties given by I<properties>.
+
+EVP_SKEYMGMT_up_ref() increments the reference count for the given
+B<EVP_SKEYMGMT> I<skeymgmt>.
+
+EVP_SKEYMGMT_free() decrements the reference count for the given
+B<EVP_SKEYMGMT> I<skeymgmt>, and when the count reaches zero, frees it.
+If the argument is NULL, nothing is done.
+
+EVP_SKEYMGMT_get0_provider() returns the provider that has this particular
+implementation.
+
+EVP_SKEYMGMT_is_a() checks if I<skeymgmt> is an implementation of an
+algorithm that's identified by I<name>.
+
+EVP_SKEYMGMT_get0_name() returns the algorithm name from the provided
+implementation for the given I<skeymgmt>. Note that the I<skeymgmt> may have
+multiple synonyms associated with it. In this case the first name from the
+algorithm definition is returned. Ownership of the returned string is
+retained by the I<skeymgmt> object and should not be freed by the caller.
+
+EVP_SKEYMGMT_names_do_all() traverses all names for the I<skeymgmt>, and
+calls I<fn> with each name and I<data>.
+
+EVP_SKEYMGMT_get0_description() returns a description of the I<skeymgmt>, meant
+for display and human consumption. The description is at the discretion
+of the I<skeymgmt> implementation.
+
+EVP_SKEYMGMT_do_all_provided() traverses all key I<skeymgmt> implementations by
+all activated providers in the library context I<libctx>, and for each
+of the implementations, calls I<fn> with the implementation method and
+I<data> as arguments.
+
+EVP_SKEYMGMT_get0_gen_settable_params() and EVP_SKEYMGMT_get0_imp_settable_params()
+get a constant L<OSSL_PARAM(3)> array that describes the settable parameters
+that can be used with EVP_SKEY_generate() and EVP_SKEY_import() correspondingly.
+
+=head1 NOTES
+
+EVP_SKEYMGMT_fetch() may be called implicitly by other fetching
+functions, using the same library context and properties.
+Any other API that uses symmetric keys will typically do this.
+
+=head1 RETURN VALUES
+
+EVP_SKEYMGMT_fetch() returns a pointer to the key management
+implementation represented by an EVP_SKEYMGMT object, or NULL on
+error.
+
+EVP_SKEYMGMT_up_ref() returns 1 on success, or 0 on error.
+
+EVP_SKEYMGMT_names_do_all() returns 1 if the callback was called for all
+names. A return value of 0 means that the callback was not called for any names.
+
+EVP_SKEYMGMT_free() doesn't return any value.
+
+EVP_SKEYMGMT_get0_provider() returns a pointer to a provider object, or NULL
+on error.
+
+EVP_SKEYMGMT_is_a() returns 1 if I<skeymgmt> was identifiable, otherwise 0.
+
+EVP_SKEYMGMT_get0_name() returns the algorithm name, or NULL on error.
+
+EVP_SKEYMGMT_get0_description() returns a pointer to a description, or NULL if
+there isn't one.
+
+=head1 SEE ALSO
+
+L<EVP_SKEY(3)>, L<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)>
+
+=head1 HISTORY
+
+B<EVP_SKEYMGMT> structure and functions
+EVP_SKEYMGMT_fetch(),
+EVP_SKEYMGMT_up_ref(),
+EVP_SKEYMGMT_free(),
+EVP_SKEYMGMT_get0_provider(),
+EVP_SKEYMGMT_is_a(),
+EVP_SKEYMGMT_get0_description(),
+EVP_SKEYMGMT_get0_name(),
+EVP_SKEYMGMT_do_all_provided(),
+EVP_SKEYMGMT_names_do_all(),
+EVP_SKEYMGMT_get0_gen_settable_params(),
+EVP_SKEYMGMT_get0_imp_settable_params()
+were added in OpenSSL 3.5.
+
+=head1 COPYRIGHT
+
+Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key,
size_t keylen, const unsigned char *iv,
size_t ivlen, const OSSL_PARAM params[]);
+ int OSSL_FUNC_cipher_encrypt_skey_init(void *cctx, void *skeydata,
+ const unsigned char *iv, size_t ivlen,
+ const OSSL_PARAM params[]);
+ int OSSL_FUNC_cipher_encrypt_skey_init(void *cctx, void *skeydata,
+ const unsigned char *iv, size_t ivlen,
+ const OSSL_PARAM params[]);
int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl,
size_t outsize, const unsigned char *in, size_t inl);
int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl,
OSSL_FUNC_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT
OSSL_FUNC_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT
+ OSSL_FUNC_cipher_encrypt_skey_init OSSL_FUNC_CIPHER_ENCRYPT_SKEY_INIT
+ OSSL_FUNC_cipher_decrypt_skey_init OSSL_FUNC_CIPHER_DECRYPT_SKEY_INIT
OSSL_FUNC_cipher_update OSSL_FUNC_CIPHER_UPDATE
OSSL_FUNC_cipher_final OSSL_FUNC_CIPHER_FINAL
OSSL_FUNC_cipher_cipher OSSL_FUNC_CIPHER_CIPHER
The I<params>, if not NULL, should be set on the context in a manner similar to
using OSSL_FUNC_cipher_set_ctx_params().
-OSSL_FUNC_cipher_decrypt_init() is the same as OSSL_FUNC_cipher_encrypt_init() except that it
-initialises the context for a decryption operation.
+OSSL_FUNC_cipher_decrypt_init() is the same as OSSL_FUNC_cipher_encrypt_init()
+except that it initialises the context for a decryption operation.
+
+OSSL_FUNC_cipher_encrypt_skey_init() and
+OSSL_FUNC_cipher_decrypt_skey_init() are variants of
+OSSL_FUNC_cipher_encrypt_init() and OSSL_FUNC_cipher_decrypt_init() for working with
+opaque objects containing provider-specific key handles instead of raw bytes.
OSSL_FUNC_cipher_update() is called to supply data to be encrypted/decrypted as part of
a previously initialised cipher operation.
OSSL_FUNC_cipher_encrypt_init(), OSSL_FUNC_cipher_decrypt_init(), OSSL_FUNC_cipher_update(),
OSSL_FUNC_cipher_final(), OSSL_FUNC_cipher_cipher(),
+OSSL_FUNC_cipher_encrypt_skey_init(), OSSL_FUNC_cipher_decrypt_skey_init(),
OSSL_FUNC_cipher_pipeline_encrypt_init(), OSSL_FUNC_cipher_pipeline_decrypt_init(),
OSSL_FUNC_cipher_pipeline_update(), OSSL_FUNC_cipher_pipeline_final(),
OSSL_FUNC_cipher_get_params(), OSSL_FUNC_cipher_get_ctx_params() and
The provider CIPHER interface was introduced in OpenSSL 3.0.
+The OSSL_FUNC_cipher_encrypt_skey_init() and
+OSSL_FUNC_cipher_decrypt_skey_init() were introduced in OpenSSL 3.5.
+
=head1 COPYRIGHT
Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
--- /dev/null
+=pod
+
+=head1 NAME
+
+provider-skeymgmt - The SKEYMGMT library E<lt>-E<gt> provider functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/core_dispatch.h>
+
+ /*
+ * None of these are actual functions, but are displayed like this for
+ * the function signatures for functions that are offered as function
+ * pointers in OSSL_DISPATCH arrays.
+ */
+
+ /* Key object destruction */
+ void OSSL_FUNC_skeymgmt_free(void *keydata);
+
+ /* Key object import and export functions */
+ void *OSSL_FUNC_skeymgmt_import(void *provctx, int selection,
+ const OSSL_PARAM params[]);
+ int OSSL_FUNC_skeymgmt_export(void *keydata, int selection,
+ OSSL_CALLBACK *param_cb, void *cbarg);
+ void *OSSL_FUNC_skeymgmt_generate(void *provctx,
+ const OSSL_PARAM params[]);
+ const OSSL_PARAM *OSSL_FUNC_skeymgmt_gen_settable_params(void *provctx);
+ const OSSL_PARAM *OSSL_FUNC_skeymgmt_imp_settable_params(void *provctx);
+ const char *OSSL_FUNC_skeymgmt_get_key_id(void *keydata);
+
+=head1 DESCRIPTION
+
+The SKEYMGMT operation doesn't have much public visibility in the OpenSSL
+libraries, rather it is an internal operation that is designed to work
+with operations that use opaque symmetric keys objects.
+
+The SKEYMGMT operation shares knowledge with the operations it works with,
+therefore the SKEYMGMT and the algorithms which use it must belong to the same
+provider. The OpenSSL libraries will ensure that they do.
+
+The primary responsibility of the SKEYMGMT operation is to hold the
+provider side key data for the OpenSSL library EVP_SKEY structure.
+
+All "functions" mentioned here are passed as function pointers between
+F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via
+L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's
+provider_query_operation() function
+(see L<provider-base(7)/Provider Functions>).
+
+All these "functions" have a corresponding function type definition
+named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the
+function pointer from a L<OSSL_DISPATCH(3)> element named
+B<OSSL_FUNC_{name}>.
+
+L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as
+macros in L<openssl-core_dispatch.h(7)>, as follows:
+
+ OSSL_FUNC_skeymgmt_free OSSL_FUNC_SKEYMGMT_FREE
+
+ OSSL_FUNC_skeymgmt_import OSSL_FUNC_SKEYMGMT_IMPORT
+ OSSL_FUNC_skeymgmt_export OSSL_FUNC_SKEYMGMT_EXPORT
+
+ OSSL_FUNC_skeymgmt_generate OSSL_FUNC_SKEYMGMT_GENERATE
+
+ OSSL_FUNC_skeymgmt_get_key_id OSSL_FUNC_SKEYMGMT_GET_KEY_ID
+ OSSL_FUNC_skeymgmt_imp_settable_params OSSL_FUNC_SKEYMGMT_IMP_SETTABLE_PARAMS
+ OSSL_FUNC_skeymgmt_gen_settable_params OSSL_FUNC_SKEYMGMT_GEN_SETTABLE_PARAMS
+
+The SKEYMGMT management is inspired by KEYMGMT but is simpler.
+
+=head2 Key Objects
+
+A key object is a collection of data for an symmetric key, and is
+represented as I<keydata> in this manual.
+
+The exact contents of a key object are defined by the provider, and it
+is assumed that different operations in one and the same provider use
+the exact same structure to represent this collection of data, so that
+for example, a key object that has been created using the SKEYMGMT
+interface can be passed as is to other algorithms from the same provider
+operations, such as OSSL_FUNC_mac_init_opaque() (see
+L<provider-mac(7)>).
+
+With the export SKEYMGMT function, it's possible to select a specific
+subset of data to handle, governed by the bits in a I<selection>
+indicator. The bits are:
+
+=over 4
+
+=item B<OSSL_SKEYMGMT_SELECT_SECRET_KEY>
+
+Indicating that the secret key raw bytes in a key object should be
+included.
+
+=item B<OSSL_SKEYMGMT_SELECT_PARAMETERS>
+
+Indicating that the parameters in a key object should be
+included.
+
+=back
+
+Combined selector bits are also defined for easier use:
+
+=over 4
+
+=item B<OSSL_SKEYMGMT_SELECT_ALL>
+
+Indicating that everything in a key object should be included.
+
+=back
+
+The exact interpretation of those bits or how they combine is left to
+each function where you can specify a selector.
+
+=head2 Destructing Function
+
+OSSL_FUNC_skeymgmt_free() should free the passed I<keydata>.
+
+=head2 Key Object Import and Export Functions
+
+OSSL_FUNC_skeymgmt_import() should import data into I<keydata> with values
+taken from the L<OSSL_PARAM(3)> array I<params>. It allocates the I<keydata>
+object (there is no separate allocation function).
+
+OSSL_FUNC_skeymgmt_imp_settable_params() returns a list of parameters that can
+be provided to the OSSL_FUNC_skeymgmt_import() function.
+
+OSSL_FUNC_skeymgmt_export() should extract values indicated by I<selection>
+from I<keydata>, create an L<OSSL_PARAM(3)> array with them and call
+I<param_cb> with that array as well as the given I<cbarg>.
+The passed L<OSSL_PARAM(3)> array is transient and is freed upon the return from I<param_cb>.
+
+=head2 Key Object Generation Functions
+
+OSSL_FUNC_skeymgmt_generate() creates a new key according to the values
+taken from the L<OSSL_PARAM(3)> array I<params>. It allocates the I<keydata>
+object.
+
+OSSL_FUNC_skeymgmt_gen_settable_params() returns a list of parameters that can
+be provided to the OSSL_FUNC_skeymgmt_generate() function.
+
+=head2 Key Object Information functions
+
+OSSL_FUNC_skeymgmt_get_key_id() returns a NUL-terminated string identifying the
+particular key. The returned string will be freed by a call to EVP_SKEY_free()
+so callers need to copy it themselves if they want to preserve the value past
+the key lifetime. The purpose of this function is providing a printable string
+that can help users to access the specific key. The content of this string is
+provider-specific.
+
+=head2 Common Import and Export Parameters
+
+See L<OSSL_PARAM(3)> for further details on the parameters structure.
+
+Common information parameters currently recognised by built-in
+skeymgmt algorithms are as follows:
+
+=over 4
+
+=item "raw-bytes" (B<SKEY_PARAM_RAW_BYTES>) <octet string>
+
+The value represents symmetric key as a byte array.
+
+=item "key-length" (B<SKEY_PARAM_KEY_LENGTH>) <integer>
+
+The value is the byte length of the given key.
+
+=back
+
+=head1 RETURN VALUES
+
+OSSL_FUNC_skeymgmt_import() and OSSL_FUNC_skeymgmt_generate() return a pointer
+to an allocated object on success and NULL on error.
+
+OSSL_FUNC_skeymgmt_export() returns 1 for success or 0 on error.
+
+OSSL_FUNC_skeymgmt_get_key_id() returns a pointer to a 0-terminated string or NULL.
+
+OSSL_FUNC_skeymgmt_gen_settable_params() and OSSL_FUNC_skeymgmt_imp_settable_params()
+return references to an array of B<OSSL_PARAM> which can be NULL if there are
+no settable parameters.
+
+=head1 SEE ALSO
+
+L<provider(7)>, L<EVP_SKEY(3)>, L<EVP_KEYMGMT(3)>
+
+=head1 HISTORY
+
+The SKEYMGMT interface was introduced in OpenSSL 3.5.
+
+=head1 COPYRIGHT
+
+Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
EVP_RAND datatype
EVP_RAND_CTX datatype
EVP_SIGNATURE datatype
+EVP_SKEYMGMT datatype
+EVP_SKEY datatype
GEN_SESSION_CB datatype
GENERAL_NAME datatype
NAMING_AUTHORITY datatype
projects / thirdparty / openssl.git / commitdiff
