EVP_SKEY documentation

Signed-off-by: Dmitry Belyavskiy <beldmit@gmail.com>
Signed-off-by: Simo Sorce <simo@redhat.com>

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/26753)

CHANGES.md

@@ -56,6 +56,11 @@ OpenSSL 3.5
 
    *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

doc/build.info

@@ -1363,6 +1363,14 @@ DEPEND[html/man3/EVP_SIGNATURE.html]=man3/EVP_SIGNATURE.pod
 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
@@ -3356,6 +3364,8 @@ html/man3/EVP_PKEY_verify.html \
 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 \
@@ -4022,6 +4032,8 @@ man/man3/EVP_PKEY_verify.3 \
 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 \
@@ -5073,6 +5085,10 @@ DEPEND[html/man7/provider-signature.html]=man7/provider-signature.pod
 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
@@ -5242,6 +5258,7 @@ html/man7/provider-mac.html \
 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 \
@@ -5393,6 +5410,7 @@ man/man7/provider-mac.7 \
 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 \

doc/man3/EVP_EncryptInit.pod

@@ -20,6 +20,7 @@ EVP_DecryptUpdate,
 EVP_DecryptFinal_ex,
 EVP_CipherInit_ex,
 EVP_CipherInit_ex2,
+EVP_CipherInit_SKEY,
 EVP_CipherUpdate,
 EVP_CipherFinal_ex,
 EVP_CIPHER_CTX_set_key_length,
@@ -142,6 +143,9 @@ EVP_CIPHER_CTX_mode
  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);
@@ -449,6 +453,11 @@ performed depends on the value of the I<enc> parameter. It should be set to 1
 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
@@ -575,11 +584,12 @@ L</PARAMETERS> instead.
 
 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
+EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(), or EVP_CipherInit_SKEY(). By
-are padded using standard block padding and the padding is checked and removed
+default encryption operations are padded using standard block padding and the
-when decrypting. If the I<pad> parameter is zero then no padding is
+padding is checked and removed when decrypting. If the I<pad> parameter is zero
-performed, the total amount of data encrypted or decrypted must then
+then no padding is performed, the total amount of data encrypted or decrypted
-be a multiple of the block size or an error will occur. I<x> B<MUST NOT> be NULL.
+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()
 
@@ -1380,8 +1390,8 @@ return 1 for success and 0 for failure.
 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
+EVP_CipherInit_ex2(), EVP_CipherInit_SKEY() and EVP_CipherUpdate() return 1 for
-failure.
+success and 0 for failure.
 EVP_CipherFinal_ex() returns 0 for an encryption/decryption failure or 1 for
 success.
 
@@ -1942,6 +1952,8 @@ The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0.
 
 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.

doc/man3/EVP_SKEY.pod

@@ -0,0 +1,142 @@
+=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

doc/man3/EVP_SKEYMGMT.pod

@@ -0,0 +1,151 @@
+=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

doc/man7/provider-cipher.pod

@@ -29,6 +29,12 @@ provider-cipher - The cipher library E<lt>-E<gt> provider functions
  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,
@@ -104,6 +110,8 @@ macros in L<openssl-core_dispatch.h(7)>, as follows:
 
  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
@@ -155,8 +163,13 @@ The IV to be used is given in I<iv> which is I<ivlen> bytes long.
 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
+OSSL_FUNC_cipher_decrypt_init() is the same as OSSL_FUNC_cipher_encrypt_init()
-initialises the context for a decryption operation.
+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.
@@ -250,6 +263,7 @@ provider side cipher context, or NULL on failure.
 
 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
@@ -275,6 +289,9 @@ L<life_cycle-cipher(7)>, L<EVP_EncryptInit(3)>
 
 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.

doc/man7/provider-skeymgmt.pod

@@ -0,0 +1,200 @@
+=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

util/other.syms

@@ -53,6 +53,8 @@ EVP_PKEY_ASN1_METHOD                    datatype
 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