EVP_SKEY documentation

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_import.html]=man3/EVP_SKEY_import.pod
+GENERATE[html/man3/EVP_SKEY_import.html]=man3/EVP_SKEY_import.pod
+DEPEND[man/man3/EVP_SKEY_import.3]=man3/EVP_SKEY_import.pod
+GENERATE[man/man3/EVP_SKEY_import.3]=man3/EVP_SKEY_import.pod
+DEPEND[html/man3/EVP_SKEY_new.html]=man3/EVP_SKEY_new.pod
+GENERATE[html/man3/EVP_SKEY_new.html]=man3/EVP_SKEY_new.pod
+DEPEND[man/man3/EVP_SKEY_new.3]=man3/EVP_SKEY_new.pod
+GENERATE[man/man3/EVP_SKEY_new.3]=man3/EVP_SKEY_new.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
@@ -3344,6 +3352,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_import.html \
+html/man3/EVP_SKEY_new.html \
 html/man3/EVP_SealInit.html \
 html/man3/EVP_SignInit.html \
 html/man3/EVP_VerifyInit.html \
@@ -4007,6 +4017,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_import.3 \
+man/man3/EVP_SKEY_new.3 \
 man/man3/EVP_SealInit.3 \
 man/man3/EVP_SignInit.3 \
 man/man3/EVP_VerifyInit.3 \

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,
@@ -137,6 +138,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,
+                         const EVP_SKEY *skey, const unsigned char *iv,
+                         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);
@@ -428,6 +432,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 an opaque
+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
@@ -509,11 +518,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
-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()
 
@@ -1304,8 +1314,9 @@ 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 failure.
-EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
+EVP_CipherInit_ex2(), EVP_CipherInit_skey() and EVP_CipherUpdate() return 1 for
+success and 0 for failure.  EVP_CipherFinal_ex() returns 0 for a decryption
+failure or 1 for success.
 
 EVP_Cipher() returns 1 on success and <= 0 on failure, if the flag
 B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher, or if the cipher has
@@ -1855,6 +1866,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.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.

doc/man3/EVP_SKEY_import.pod

@@ -0,0 +1,83 @@
+=pod
+
+=head1 NAME
+
+EVP_SKEY_import, EVP_SKEY_export
+- functions to create opaque symmetric keys from user data and export keydata
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_SKEY_import(EVP_SKEY *skey, const OSSL_PARAM *params);
+ int EVP_SKEY_export(const EVP_SKEY *skey, int selection,
+                     OSSL_CALLBACK *export_cb, void *export_cbarg);
+
+=head1 DESCRIPTION
+
+The functions described here are used to create new keys from user
+provided key data, such as I<n>, I<e> and I<d> for a minimal RSA
+keypair.
+
+EVP_SKEY_import() creates the structure to store a key to a B<EVP_SKEY> object
+created by EVP_SKEY_new() The exact key data that the user can pass depends on
+the key type and the provider in use.  These are passed as an L<OSSL_PARAM(3)>
+array.
+
+Parameters in the I<params> array that are not among the settable parameters
+for the given I<selection> are ignored.
+
+EVP_SKEY_export() 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.
+
+L<OSSL_PARAM_free(3)> should be used to free the returned parameters in
+I<*params>.
+
+=head2 Selections
+
+The following constants can be used for I<selection>:
+
+=over 4
+
+=item B<OSSL_KEYMGMT_SELECT_SECRET_KEY>
+
+Only raw key representation will be selected.
+
+=item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS>
+
+Only key parameters will be selected. This includes optional key
+parameters.
+
+=item B<OSSL_KEYMGMT_SELECT_ALL>
+
+All parameters will be selected.
+
+=back
+
+=head1 RETURN VALUES
+
+EVP_SKEY_import() and EVP_SKEY_export() return 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<EVP_SKEY_new(3)>, L<provider(7)>, L<OSSL_PARAM(3)>
+
+=head1 HISTORY
+
+These functions were added 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
+

doc/man3/EVP_SKEY_new.pod

@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+EVP_SKEY,
+EVP_SKEY_new,
+EVP_SKEY_up_ref,
+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_new(void);
+ 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 through L<EVP_KEYMGMT(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_new() function allocates an empty B<EVP_SKEY> structure which is
+used by OpenSSL to store public and private keys. The reference count is set to
+B<1>.
+
+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 up. If I<key> is NULL, nothing is done.
+
+=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_new() returns either the newly
+allocated B<EVP_SKEY> structure or NULL if an error occurred.
+
+EVP_SKEY_up_ref() returns 1 for success and 0 for failure.
+
+=head1 HISTORY
+
+The B<EVP_SKEY> API 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