DOCS: Add internal docs for EVP_PKEY and the export functions
[openssl.git] / doc / internal / man7 / EVP_PKEY.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_PKEY - an internal description
6
7 =head1 SYNOPSIS
8
9  #include "crypto/evp.h"
10
11  struct evp_pkey_st;
12
13 =head1 DESCRIPTION
14
15 I<This is not a complete description yet>
16
17 B<EVP_PKEY> is a complex type that's essentially a container for
18 private/public key key pairs, but has had other uses as well.
19
20 =for comment "uses" could as well be "abuses"...
21
22 It can contain the legacy form of keys -- i.e. pointers to the low
23 level key types, such as B<RSA>, B<DSA> and B<EC> --, but also the
24 provided form of keys -- i.e. pointers to provider side key data.
25 Those two forms are mutually exclusive; an B<EVP_PKEY> instance can't
26 contain both a key in legacy form and in provided form.  Regardless of
27 form, this key is commonly refered to as the "origin".
28
29 An B<EVP_PKEY> also contains a cache of provider side copies of the
30 key, each adapted for the provider that is going to use that copy to
31 perform some operation.
32 For a legacy "origin", the B<EVP_PKEY_ASN1_METHOD>'s functions
33 export_to() and dirty_cnt() must be implemented for such caching to be
34 possible.  For a provider side "origin", the B<EVP_KEYMGMT>'s function
35 OP_keymgmt_export() must be implemented.  In all cases, the receiving
36 B<EVP_KEYMGMT> must have an implemented OP_keygmt_import().
37
38 If such caching isn't supported, the operations that can be performed
39 with that key are limited to the same backend as the "origin" key
40 (ENGINE for legacy "origin" keys, provider for provider side "origin"
41 keys).
42
43 =head1 SEE ALSO
44
45 L<provider-keymgmt(7)>
46
47 =head1 COPYRIGHT
48
49 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
50
51 Licensed under the Apache License 2.0 (the "License").  You may not use
52 this file except in compliance with the License.  You can obtain a copy
53 in the file LICENSE in the source distribution or at
54 L<https://www.openssl.org/source/license.html>.
55
56 =cut