From b9d919f697270ea38818239b18eb71eb6b5e4d8c Mon Sep 17 00:00:00 2001 From: Dmitry Belyavskiy Date: Thu, 9 Jan 2025 19:19:10 +0100 Subject: [PATCH] EVP_SKEY documentation Signed-off-by: Dmitry Belyavskiy Signed-off-by: Simo Sorce Reviewed-by: Tomas Mraz Reviewed-by: Tim Hudson (Merged from https://github.com/openssl/openssl/pull/26753) --- CHANGES.md | 5 + doc/build.info | 18 +++ doc/man3/EVP_EncryptInit.pod | 26 +++-- doc/man3/EVP_SKEY.pod | 142 +++++++++++++++++++++++ doc/man3/EVP_SKEYMGMT.pod | 151 +++++++++++++++++++++++++ doc/man7/provider-cipher.pod | 21 +++- doc/man7/provider-skeymgmt.pod | 200 +++++++++++++++++++++++++++++++++ util/other.syms | 2 + 8 files changed, 556 insertions(+), 9 deletions(-) create mode 100644 doc/man3/EVP_SKEY.pod create mode 100644 doc/man3/EVP_SKEYMGMT.pod create mode 100644 doc/man7/provider-skeymgmt.pod diff --git a/CHANGES.md b/CHANGES.md index 2c47f5efa31..88989b0dee1 100644 --- a/CHANGES.md +++ b/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 diff --git a/doc/build.info b/doc/build.info index 5f273c2452a..2748d0e0496 100644 --- a/doc/build.info +++ b/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 \ diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 85bb803e139..03c212bab14 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/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 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 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 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 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 B 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 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 B 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 to B would result in a NULL pointer dereference, rather than a 0 return value indicating an error. diff --git a/doc/man3/EVP_SKEY.pod b/doc/man3/EVP_SKEY.pod new file mode 100644 index 00000000000..580d26ac056 --- /dev/null +++ b/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 + + 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 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. + +Conceptually, an B 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 object and +initializes it according to the B argument. + +The EVP_SKEY_import() function allocates an empty B structure +which is used by OpenSSL to store symmetric keys, assigns the +B object associated with the key, and initializes the object from +the B argument. + +The EVP_SKEY_import_raw_key() function is a helper that creates an B object +containing the raw byte representation of the symmetric keys. + +The EVP_SKEY_export() function extracts values from a key I using the +I. I is described below. It uses a callback I +that gets passed the value of I. See L for +more information about the callback. Note that the L 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. + +EVP_SKEY_free() decrements the reference count of I and, if the reference +count is zero, frees it. If I is NULL, nothing is done. + +=head2 Selections + +The following constants can be used for I: + +=over 4 + +=item B + +Only the raw key representation will be selected. + +=item B + +Only the key parameters will be selected. This includes optional key +parameters. + +=item B + +All parameters will be selected. + +=back + +=head1 NOTES + +The B 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 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, L, L + +=head1 HISTORY + +The B 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. + +=cut diff --git a/doc/man3/EVP_SKEYMGMT.pod b/doc/man3/EVP_SKEYMGMT.pod new file mode 100644 index 00000000000..f0e687cfa92 --- /dev/null +++ b/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 + + 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 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 given by I, having the +name given by I and the properties given by I. + +EVP_SKEYMGMT_up_ref() increments the reference count for the given +B I. + +EVP_SKEYMGMT_free() decrements the reference count for the given +B I, 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 is an implementation of an +algorithm that's identified by I. + +EVP_SKEYMGMT_get0_name() returns the algorithm name from the provided +implementation for the given I. Note that the I 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 object and should not be freed by the caller. + +EVP_SKEYMGMT_names_do_all() traverses all names for the I, and +calls I with each name and I. + +EVP_SKEYMGMT_get0_description() returns a description of the I, meant +for display and human consumption. The description is at the discretion +of the I implementation. + +EVP_SKEYMGMT_do_all_provided() traverses all key I implementations by +all activated providers in the library context I, and for each +of the implementations, calls I with the implementation method and +I as arguments. + +EVP_SKEYMGMT_get0_gen_settable_params() and EVP_SKEYMGMT_get0_imp_settable_params() +get a constant L 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 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, L, L + +=head1 HISTORY + +B 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. + +=cut diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index 8f23aae0daa..c3d0f5f9f3e 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -29,6 +29,12 @@ provider-cipher - The cipher library E-E 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, 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 which is I bytes long. The I, 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, L 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. diff --git a/doc/man7/provider-skeymgmt.pod b/doc/man7/provider-skeymgmt.pod new file mode 100644 index 00000000000..2763de162c7 --- /dev/null +++ b/doc/man7/provider-skeymgmt.pod @@ -0,0 +1,200 @@ +=pod + +=head1 NAME + +provider-skeymgmt - The SKEYMGMT library E-E provider functions + +=head1 SYNOPSIS + + #include + + /* + * 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 and the provider in L arrays via +L arrays that are returned by the provider's +provider_query_operation() function +(see L). + +All these "functions" have a corresponding function type definition +named B, and a helper function to retrieve the +function pointer from a L element named +B. + +L arrays are indexed by numbers that are provided as +macros in L, 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 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). + +With the export SKEYMGMT function, it's possible to select a specific +subset of data to handle, governed by the bits in a I +indicator. The bits are: + +=over 4 + +=item B + +Indicating that the secret key raw bytes in a key object should be +included. + +=item B + +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 + +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. + +=head2 Key Object Import and Export Functions + +OSSL_FUNC_skeymgmt_import() should import data into I with values +taken from the L array I. It allocates the I +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 +from I, create an L array with them and call +I with that array as well as the given I. +The passed L array is transient and is freed upon the return from I. + +=head2 Key Object Generation Functions + +OSSL_FUNC_skeymgmt_generate() creates a new key according to the values +taken from the L array I. It allocates the I +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 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) + +The value represents symmetric key as a byte array. + +=item "key-length" (B) + +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 which can be NULL if there are +no settable parameters. + +=head1 SEE ALSO + +L, L, L + +=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. + +=cut diff --git a/util/other.syms b/util/other.syms index 5ae03f4e1a8..a0b85606078 100644 --- a/util/other.syms +++ b/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 -- 2.47.3