mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-04-06 20:20:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

EVP_SKEY documentation

Browse Source 
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)
This commit is contained in:
Dmitry Belyavskiy 2025-01-09 19:19:10 +01:00
parent 9422ab6a7e
commit b9d919f697
8 changed files with 556 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
CHANGES.md
View File

@ -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

18
doc/build.info
View File

@ -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 \

26
doc/man3/EVP_EncryptInit.pod
View File

@ -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
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()
@ -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
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.
@ -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.

142
doc/man3/EVP_SKEY.pod Normal file
View File

@ -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

151
doc/man3/EVP_SKEYMGMT.pod Normal file
View File

@ -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

21
doc/man7/provider-cipher.pod
View File

@ -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
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.
@ -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.

200
doc/man7/provider-skeymgmt.pod Normal file
View File

@ -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

2
util/other.syms
View File

@ -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