diff --git a/CHANGES.md b/CHANGES.md index b9ce4e8657..0ff517f2d0 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -23,6 +23,24 @@ OpenSSL 3.0 ### Changes between 1.1.1 and 3.0 [xx XXX xxxx] + * The deprecated functions EVP_PKEY_get0(), EVP_PKEY_get0_RSA(), + EVP_PKEY_get0_DSA(), EVP_PKEY_get0_EC_KEY(), EVP_PKEY_get0_DH(), + EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305() and EVP_PKEY_get0_siphash() as + well as the similarly named "get1" functions behave slightly differently in + OpenSSL 3.0. Previously they returned a pointer to the low-level key used + internally by libcrypto. From OpenSSL 3.0 this key may now be held in a + provider. Calling these functions will only return a handle on the internal + key where the EVP_PKEY was constructed using this key in the first place, for + example using a function or macro such as EVP_PKEY_assign_RSA(), + EVP_PKEY_set1_RSA(), etc. Where the EVP_PKEY holds a provider managed key, + then these functions now return a cached copy of the key. Changes to + the internal provider key that take place after the first time the cached key + is accessed will not be reflected back in the cached copy. Similarly any + changed made to the cached copy by application code will not be reflected + back in the internal provider key. + + *Matt Caswell* + * A number of functions handling low level keys or engines were deprecated including EVP_PKEY_set1_engine(), EVP_PKEY_get0_engine(), EVP_PKEY_assign(), EVP_PKEY_get0(), EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305() and @@ -701,12 +719,12 @@ OpenSSL 3.0 time. Instead applications should use L, L and L. - Finaly functions that assign or obtain DH objects from an EVP_PKEY such as + Finaly functions that assign or obtain DSA objects from an EVP_PKEY such as `EVP_PKEY_assign_DSA()`, `EVP_PKEY_get0_DSA()`, `EVP_PKEY_get1_DSA()`, and `EVP_PKEY_set1_DSA()` are also deprecated. Applications should instead either read or write an - EVP_PKEY directly using the OSSL_DECODER and OSSL_ENCODER APIs. - Or load an EVP_PKEY directly from DSA data using `EVP_PKEY_fromdata()`. + EVP_PKEY directly using the OSSL_DECODER and OSSL_ENCODER APIs, + or load an EVP_PKEY directly from DSA data using `EVP_PKEY_fromdata()`. *Paul Dale* diff --git a/doc/internal/man3/evp_pkey_export_to_provider.pod b/doc/internal/man3/evp_pkey_export_to_provider.pod index 65fb7109e0..833ff44d53 100644 --- a/doc/internal/man3/evp_pkey_export_to_provider.pod +++ b/doc/internal/man3/evp_pkey_export_to_provider.pod @@ -2,7 +2,7 @@ =head1 NAME -evp_pkey_export_to_provider, evp_pkey_copy_downgraded, evp_pkey_downgrade +evp_pkey_export_to_provider, evp_pkey_copy_downgraded, evp_pkey_get_legacy - internal EVP_PKEY support functions for providers =head1 SYNOPSIS @@ -14,7 +14,7 @@ evp_pkey_export_to_provider, evp_pkey_copy_downgraded, evp_pkey_downgrade EVP_KEYMGMT **keymgmt, const char *propquery); int evp_pkey_copy_downgraded(EVP_PKEY **dest, const EVP_PKEY *src); - int evp_pkey_downgrade(EVP_PKEY *pk); + void *evp_pkey_get_legacy(EVP_PKEY *pk); =head1 DESCRIPTION @@ -37,11 +37,14 @@ For example, L uses this to try its best to get "traditional" PEM output even if the input B has a provider-native internal key. -evp_pkey_downgrade() converts an B with a provider side "origin" key -to one with a legacy "origin", if there's a corresponding legacy implementation. -This clears the operation cache, except for the provider side "origin" key. -This function is used in spots where provider side keys aren't yet supported, -in an attempt to keep operating with available implementations. +evp_pkey_get_legacy() obtains and returns a legacy key structure. If the +EVP_PKEY already contains a legacy key then it is simply returned. If it is a +provider based key, then a new legacy key is constructed based on the provider +key. The legacy key is cached inside the EVP_PKEY and its value returned from +this function. Subsequent calls to evp_pkey_get_legacy() will return the cached +key. Subsequent changes to the provider key are not reflected back in the +legacy key. Similarly changes to the legacy key are not reflected back in the +provider key. =head1 RETURN VALUES @@ -49,7 +52,7 @@ evp_pkey_export_to_provider() returns the provider key data if there was any allocated. It also either sets I<*keymgmt> to the B associated with the returned key data, or NULL on error. -evp_pkey_downgrade() returns 1 on success or 0 on error. +evp_pkey_get_legacy() returns the legacy key or NULL on error. =head1 NOTES diff --git a/doc/internal/man7/EVP_PKEY.pod b/doc/internal/man7/EVP_PKEY.pod index 7088b6cc08..cc738b9c28 100644 --- a/doc/internal/man7/EVP_PKEY.pod +++ b/doc/internal/man7/EVP_PKEY.pod @@ -65,7 +65,10 @@ The B internal keys are mutable. This is especially visible with internal legacy keys, since they can be extracted with functions like L and then -modified at will with functions like L. +modified at will with functions like L. Note that if the +internal key is a provider key then the return value from functions such as +L is a cached copy of the key. Changes to the cached +copy are not reflected back in the provider key. Internal provider native keys are also possible to be modified, if the associated L implementation allows it. This is done @@ -187,11 +190,11 @@ takes care of the needs of the diverse operation the application may want to perform. Similarly an B with a provider native origin, will I be -downgraded to be I into an B with a legacy origin. -Instead we may have a cached copy of the provider key in legacy form. Once the -cached copy is created it is never updated. Changes made to the provider key -are not reflected back in the cached legacy copy. Similarly changes made to the -cached legacy copy are not reflected back in the provider key. +I into an B with a legacy origin. Instead we may have a +cached copy of the provider key in legacy form. Once the cached copy is created +it is never updated. Changes made to the provider key are not reflected back in +the cached legacy copy. Similarly changes made to the cached legacy copy are not +reflected back in the provider key. =head1 SEE ALSO diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod index 32b1e1b8d5..85cf5b6fe4 100644 --- a/doc/man3/EVP_PKEY_set1_RSA.pod +++ b/doc/man3/EVP_PKEY_set1_RSA.pod @@ -84,7 +84,7 @@ L. EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key in I or NULL if the -key is not of the correct type. The returned key must be freed after use. +key is not of the correct type. The returned key must be freed after use. These functions are deprecated. Applications should instead use the EVP_PKEY directly where possible. If access to the low level key parameters is required then applications should use L and other similar @@ -94,14 +94,29 @@ L). EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() return the referenced key in I or NULL if the -key is not of the correct type but the reference count of the returned key -is B incremented and so must not be freed after use. These functions are -deprecated. Applications should instead use the EVP_PKEY directly where +key is not of the correct type. The reference count of the returned key is +B incremented and so the key must not be freed after use. These functions +are deprecated. Applications should instead use the EVP_PKEY directly where possible. If access to the low level key parameters is required then applications should use L and other similar functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see L). +Note that if an EVP_PKEY was not constructed using one of the deprecated +functions such as EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() +or EVP_PKEY_set1_EC_KEY(), or via the similarly named B macros +described above then the internal key will be managed by a provider (see +L). In that case the key returned by EVP_PKEY_get1_RSA(), +EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_EC_KEY(), +EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), +EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() or +EVP_PKEY_get0_EC_KEY() will be a cached copy of the provider's key. Subsequent +updates to the provider's key will not be reflected back in the cached copy, and +updates made by an application to the returned key will not be reflected back in +the provider's key. Subsequent calls to EVP_PKEY_get1_RSA(), +EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() will always +return the cached copy returned by the first call. + EVP_PKEY_get0_engine() returns a reference to the ENGINE handling I. This function is deprecated. Applications should use providers instead of engines (see L for details). diff --git a/doc/man7/evp.pod b/doc/man7/evp.pod index d8f5a2c1d3..c97abba3dd 100644 --- a/doc/man7/evp.pod +++ b/doc/man7/evp.pod @@ -29,7 +29,7 @@ The BI functions provide a high-level interface to asymmetric algorithms. To create a new EVP_PKEY see L. EVP_PKEYs can be associated with a private key of a particular algorithm by using the functions -described on the L page, or +described on the L page, or new keys can be generated using L. EVP_PKEYs can be compared using L, or printed using L. @@ -90,7 +90,7 @@ L, L, L, L, -L, +L, L, L, L,