From e33b132a1ae744614bb7cf568d197574dbafe1bb Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Mon, 24 Feb 2020 14:36:09 +0100 Subject: [PATCH] DOCS: Add internal docs for EVP_PKEY and the export functions Functions covered: - evp_pkey_export_to_provider() - evp_pkey_upgrade_to_provider() Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/11148) --- .../man3/evp_pkey_export_to_provider.pod | 75 +++++++++++++++++++ doc/internal/man3/evp_pkey_make_provided.pod | 63 ---------------- doc/internal/man7/EVP_PKEY.pod | 56 ++++++++++++++ 3 files changed, 131 insertions(+), 63 deletions(-) create mode 100644 doc/internal/man3/evp_pkey_export_to_provider.pod delete mode 100644 doc/internal/man3/evp_pkey_make_provided.pod create mode 100644 doc/internal/man7/EVP_PKEY.pod diff --git a/doc/internal/man3/evp_pkey_export_to_provider.pod b/doc/internal/man3/evp_pkey_export_to_provider.pod new file mode 100644 index 0000000000..31e8ad02e4 --- /dev/null +++ b/doc/internal/man3/evp_pkey_export_to_provider.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + +evp_pkey_export_to_provider, evp_pkey_upgrade_to_provider +- internal EVP_PKEY support functions for providers + +=head1 SYNOPSIS + + /* Only for EVP source */ + #include "evp_local.h" + + void *evp_pkey_export_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx, + EVP_KEYMGMT **keymgmt, + const char *propquery); + void *evp_pkey_upgrade_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx, + EVP_KEYMGMT **keymgmt, + const char *propquery); + +=head1 DESCRIPTION + +This manual uses the term "origin", which is explained in internal +L. + +evp_pkey_export_to_provider() exports the "origin" key contained in I +to its operation cache to make it suitable for an B given either +with I<*keymgmt> or with an implicit fetch using I (NULL means the +default context), the name of the legacy type of I, and the I +(NULL means the default property query settings). + +If I isn't NULL but I<*keymgmt> is, and the "origin" was successfully +exported, then I<*keymgmt> is assigned the implicitly fetched B. + +evp_pkey_upgrade_to_provider() exports the legacy "origin" key contained in +I to it's provider side counterpart, then clears the legacy "origin" key +along with other legacy data, and resets all the caches. Otherwise, it works +like evp_pkey_export_to_provider(). + +I +Most of the time, it's sufficient to use evp_pkey_export_to_provider(), but in +case the key needs modification with data coming from a provided key, the key +will need an upgrade. + +=head1 RETURN VALUES + +evp_pkey_export_to_provider() and evp_pkey_upgrade_to_provider() both return +the provider key data that was exported if the "origin" was successfully +exported to its target. Otherwise, NULL is returned. + +=head1 NOTES + +Some functions calling evp_pkey_export_to_provider() or +evp_pkey_upgrade_to_provider() may have received a const key, and may +therefore have to cast the key to non-const form to call this function. Since +B is always dynamically allocated, this is OK. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The functions described here were all added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2020 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/internal/man3/evp_pkey_make_provided.pod b/doc/internal/man3/evp_pkey_make_provided.pod deleted file mode 100644 index 3eb17e707b..0000000000 --- a/doc/internal/man3/evp_pkey_make_provided.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -evp_pkey_make_provided - internal EVP_PKEY support functions for providers - -=head1 SYNOPSIS - - /* Only for EVP source */ - #include "evp_local.h" - - void *evp_pkey_make_provided(EVP_PKEY *pk, OPENSSL_CTX *libctx, - EVP_KEYMGMT **keymgmt, const char *propquery); - -=head1 DESCRIPTION - -evp_pkey_make_provided() ensures that the B I is provided within -the library context I (NULL means the default context). I -may point at a reference to a B, and works as an input/output -parameter. -As input to this function, it can be used to specify a B to be -used for exporting. If not (I<*keymgmt> is NULL), then this function will -fetch an B implicitly, using I as property query string. -As output from this function, I<*keymgmt> will be assigned the B -that was used, if the export was successful, otherwise it will be assigned NULL. - -If I has an assigned legacy key, a check is done to see if any of -its key material has changed since last export, by comparing the -result of the legacy key's dirty_cnt() method with a copy of that -result from last time evp_pkey_make_provided() was run with this -B. -If it has, the cache of already exported keys is cleared, and a new -export is made with the new legacy key material. - -=head1 RETURN VALUES - -evp_pkey_make_provided() returns the provider key data that was exported if -I was successfully provided. Otherwise, NULL is returned. - -=head1 NOTES - -Some functions calling evp_pkey_make_provided() may have received a const -key, and may therefore have to cast the key to non-const form to call this -function. Since B is always dynamically allocated, this is OK. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -The functions described here were all added in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2020 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/internal/man7/EVP_PKEY.pod b/doc/internal/man7/EVP_PKEY.pod new file mode 100644 index 0000000000..a37ca9eecc --- /dev/null +++ b/doc/internal/man7/EVP_PKEY.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +EVP_PKEY - an internal description + +=head1 SYNOPSIS + + #include "crypto/evp.h" + + struct evp_pkey_st; + +=head1 DESCRIPTION + +I + +B is a complex type that's essentially a container for +private/public key key pairs, but has had other uses as well. + +=for comment "uses" could as well be "abuses"... + +It can contain the legacy form of keys -- i.e. pointers to the low +level key types, such as B, B and B --, but also the +provided form of keys -- i.e. pointers to provider side key data. +Those two forms are mutually exclusive; an B instance can't +contain both a key in legacy form and in provided form. Regardless of +form, this key is commonly refered to as the "origin". + +An B also contains a cache of provider side copies of the +key, each adapted for the provider that is going to use that copy to +perform some operation. +For a legacy "origin", the B's functions +export_to() and dirty_cnt() must be implemented for such caching to be +possible. For a provider side "origin", the B's function +OP_keymgmt_export() must be implemented. In all cases, the receiving +B must have an implemented OP_keygmt_import(). + +If such caching isn't supported, the operations that can be performed +with that key are limited to the same backend as the "origin" key +(ENGINE for legacy "origin" keys, provider for provider side "origin" +keys). + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2020 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 -- 2.25.1