1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
=pod
=head1 NAME
EVP_PKEY - an internal description
=head1 SYNOPSIS
#include "crypto/evp.h"
typedef struct evp_pkey_st EVP_PKEY;
=head1 DESCRIPTION
I<This is not a complete description yet>
B<EVP_PKEY> is a complex type that's essentially a container for
private/public key pairs, but has had other uses as well.
=for comment "uses" could as well be "abuses"...
The private/public key pair that an B<EVP_PKEY> contains is refered to
as its "internal key" or "origin" (the reason for "origin" is
explained further down, in L</Export cache for provider operations>),
and it can take one of the following forms:
=over 4
=item legacy origin
This is the form that an B<EVP_PKEY> in OpenSSL prior to 3.0 had. The
internal key in the B<EVP_PKEY> is a pointer to the low-level key
types, such as B<RSA>, B<DSA> and B<EC>, or an engine driven
structure, and is governed by an associated L<EVP_PKEY_METHOD(3)> and
an L<EVP_PKEY_ASN1_METHOD(3)>.
The functions available through those two method structures get full
access to the B<EVP_PKEY> and therefore have a lot of freedom to
modify whatever they want. This also means that an B<EVP_PKEY> is a
shared structure between libcrypto and any ENGINE that serves such
methods.
=item provider-native origin
This is a new form in OpenSSL 3.0, which permits providers to hold the
key data (see L<provider-keymgmt(7)>). The internal key in the
B<EVP_PKEY> is a pointer to that key data held by the provider, and
is governed by an associated L<EVP_KEYMGMT(3)> method structure.
The functions available through the L<EVP_KEYMGMT(3)> have no access
to the B<EVP_PKEY>, and can therefore not make any direct changes.
Similarly, the key data that the B<EVP_PKEY> points at is only known
to the functions pointed at in the L<EVP_KEYMGMT(3)>.
=back
These two forms can never co-exist in the same B<EVP_PKEY>, the main
reason being that having both at the same time will create problems
with synchronising between the two forms, and potentially make it
confusing which one of the two is the origin.
=head2 Key mutability
The B<EVP_PKEY> internal keys are mutable.
This is especially visible with internal legacy keys, since they can
be extracted with functions like L<EVP_PKEY_get0_RSA(3)> and then
modified at will with functions like L<RSA_set0_key(3)>. Note that if the
internal key is a provider key then the return value from functions such as
L<EVP_PKEY_get0_RSA(3)> 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<EVP_KEYMGMT(3)> implementation allows it. This is done
with L<EVP_PKEY_set_params(3)> and its specialised derivatives. The
OpenSSL providers allow it for the following:
=over 4
=item DH, EC, X25519, X448:
It's possible to set the encoded public key. This is supported in
particular through L<EVP_PKEY_set1_encoded_public_key(3)>.
=item EC:
It's possible to flip the ECDH cofactor mode.
=back
Every time the B<EVP_PKEY> internal key mutates, an internal dirty
count is incremented. The need for a dirty count is explained further
in L</Export cache for provider operations>.
For provider native origin keys, this doesn't require any help from
the L<EVP_KEYMGMT(3)>, the dirty count is maintained in the B<EVP_PKEY>
itself, and is incremented every time L<EVP_PKEY_set_params(3)> or its
specialised derivatives are called.
For legacy origin keys, this requires the associated
L<EVP_PKEY_ASN1_METHOD(3)> to implement the dirty_cnt() function. All
of OpenSSL's built-in L<EVP_PKEY_ASN1_METHOD(3)> implement this
function.
=head2 Export cache for provider operations
OpenSSL 3.0 can handle operations such as signing, encrypting, etc in
diverse providers, potentially others than the provider of the
L<EVP_KEYMGMT(3)>. Two providers, possibly from different vendors,
can't be expected to share internal key structures. There are
therefore instances where key data will need to be exported to the
provider that is going to perform the operation (this also implies
that every provider that implements a key pair based operation must
also implement an L<EVP_KEYMGMT(3)>).
For performance reasons, libcrypto tries to minimize the need to
perform such an export, so it maintains a cache of such exports in the
B<EVP_PKEY>. Each cache entry has two items, a pointer to the
provider side key data and the associated L<EVP_KEYMGMT(3)>.
I<This cache is often referred to as the "operation key cache", and
the key data that the cached keys came from is the "origin", and since
there are two forms of the latter, we have the "legacy origin" and the
"provider native origin".>
The export to the operation key cache can be performed independent of
what form the origin has.
For a legacy origin, this requires that the associated
L<EVP_PKEY_ASN1_METHOD(3)> implements the functions export_to() and
dirty_cnt().
For a provider native origin, this requires that the associated
L<EVP_KEYMGMT(3)> implements the OSSL_FUNC_keymgmt_export() function
(see L<provider-keymgmt(7)>).
In all cases, the receiving L<EVP_KEYMGMT(3)> (the one associated with
the exported key data) must implement OSSL_FUNC_keymgmt_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).
=head3 Exporting implementation details
Exporting a key to the operation cache involves the following:
=over 4
=item 1.
Check if the dirty count for the internal origin key has changed since
the previous time. This is done by comparing it with a copy of the
dirty count, which is maintained by the export function.
If the dirty count has changed, the export cache is cleared.
=item 2.
Check if there's an entry in the export cache with the same
L<EVP_KEYMGMT(3)> that's the same provider that an export is to be
made to (which is the provider that's going to perform an operation
for which the current B<EVP_PKEY> is going to be used).
If such an entry is found, nothing more is done, the key data and
L<EVP_KEYMGMT(3)> found in that export cache entry will be used for
the operation to be performed.
=item 3.
Export the internal origin key to the provider, using the appropriate
method.
For legacy origin keys, that's done with the help of the
L<EVP_PKEY_ASN1_METHOD(3)> export_to() function.
For provider native origin keys, that's done by retrieving the key
data in L<OSSL_PARAM(3)> form from the origin keys, using the
OSSL_FUNC_keymgmt_export() functions of the associated
L<EVP_KEYMGMT(3)>, and sending that data to the L<EVP_KEYMGMT(3)> of
the provider that's to perform the operation, using its
OSSL_FUNC_keymgmt_import() function.
=back
=head2 Changing a key origin
It is never possible to change the origin of a key. An B<EVP_PKEY> with a legacy
origin will I<never> be upgraded to become an B<EVP_PKEY> with a provider
native origin. Instead, we have the operation cache as described above, that
takes care of the needs of the diverse operation the application may want to
perform.
Similarly an B<EVP_PKEY> with a provider native origin, will I<never> be
I<transformed> into an B<EVP_PKEY> 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
L<provider-keymgmt(7)>
=head1 COPYRIGHT
Copyright 2020-2021 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<https://www.openssl.org/source/license.html>.
=cut
|
