From a624f07c20dfa3a7a4112f5a8051db7848519592 Mon Sep 17 00:00:00 2001 From: Dmitry Belyavskiy Date: Thu, 14 Nov 2024 13:10:27 +0100 Subject: [PATCH] EVP_SKEY documentation --- doc/build.info | 12 ++++++ doc/man3/EVP_EncryptInit.pod | 27 +++++++++--- doc/man3/EVP_SKEY_import.pod | 83 ++++++++++++++++++++++++++++++++++++ doc/man3/EVP_SKEY_new.pod | 63 +++++++++++++++++++++++++++ 4 files changed, 178 insertions(+), 7 deletions(-) create mode 100644 doc/man3/EVP_SKEY_import.pod create mode 100644 doc/man3/EVP_SKEY_new.pod diff --git a/doc/build.info b/doc/build.info index 490422b5597e6..067241c37325f 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_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 \ diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 53ce50b19f80c..dd322be4efe8f 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, @@ -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 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 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 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() @@ -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 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. diff --git a/doc/man3/EVP_SKEY_import.pod b/doc/man3/EVP_SKEY_import.pod new file mode 100644 index 0000000000000..15103a0688e1b --- /dev/null +++ b/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 + + 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, I and I for a minimal RSA +keypair. + +EVP_SKEY_import() creates the structure to store a key to a B 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 +array. + +Parameters in the I array that are not among the settable parameters +for the given I are ignored. + +EVP_SKEY_export() 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. + +L should be used to free the returned parameters in +I<*params>. + +=head2 Selections + +The following constants can be used for I: + +=over 4 + +=item B + +Only raw key representation will be selected. + +=item B + +Only key parameters will be selected. This includes optional key +parameters. + +=item B + +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, L, L + +=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. + +=cut + diff --git a/doc/man3/EVP_SKEY_new.pod b/doc/man3/EVP_SKEY_new.pod new file mode 100644 index 0000000000000..bdab0eba3fbd5 --- /dev/null +++ b/doc/man3/EVP_SKEY_new.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +EVP_SKEY_new, +EVP_SKEY_up_ref, +EVP_SKEY_free +- opaque symmetric key allocation and handling functions + +=head1 SYNOPSIS + + #include + + 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 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. + +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_new() function allocates an empty B 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. + +EVP_SKEY_free() decrements the reference count of I and, if the reference +count is zero, frees it up. If I is NULL, nothing is done. + +=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_new() returns either the newly +allocated B structure or NULL if an error occurred. + +EVP_SKEY_up_ref() returns 1 for success and 0 for failure. + +=head1 HISTORY + +The B 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. + +=cut