xref: /freebsd/crypto/openssl/doc/man3/EVP_SKEYMGMT.pod (revision e7be843b4a162e68651d3911f0357ed464915629) 
1*e7be843bSPierre Pronchery=pod
2*e7be843bSPierre Pronchery
3*e7be843bSPierre Pronchery=head1 NAME
4*e7be843bSPierre Pronchery
5*e7be843bSPierre ProncheryEVP_SKEYMGMT,
6*e7be843bSPierre ProncheryEVP_SKEYMGMT_fetch,
7*e7be843bSPierre ProncheryEVP_SKEYMGMT_up_ref,
8*e7be843bSPierre ProncheryEVP_SKEYMGMT_free,
9*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_provider,
10*e7be843bSPierre ProncheryEVP_SKEYMGMT_is_a,
11*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_description,
12*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_name,
13*e7be843bSPierre ProncheryEVP_SKEYMGMT_do_all_provided,
14*e7be843bSPierre ProncheryEVP_SKEYMGMT_names_do_all,
15*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_gen_settable_params,
16*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_imp_settable_params
17*e7be843bSPierre Pronchery- EVP key management routines for opaque symmetric keys
18*e7be843bSPierre Pronchery
19*e7be843bSPierre Pronchery=head1 SYNOPSIS
20*e7be843bSPierre Pronchery
21*e7be843bSPierre Pronchery #include <openssl/evp.h>
22*e7be843bSPierre Pronchery
23*e7be843bSPierre Pronchery typedef struct evp_sskeymgmt_st EVP_SKEYMGMT;
24*e7be843bSPierre Pronchery
25*e7be843bSPierre Pronchery EVP_SKEYMGMT *EVP_SKEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
26*e7be843bSPierre Pronchery                                  const char *properties);
27*e7be843bSPierre Pronchery int EVP_SKEYMGMT_up_ref(EVP_SKEYMGMT *skeymgmt);
28*e7be843bSPierre Pronchery void EVP_SKEYMGMT_free(EVP_SKEYMGMT *skeymgmt);
29*e7be843bSPierre Pronchery const OSSL_PROVIDER *EVP_SKEYMGMT_get0_provider(const EVP_SKEYMGMT *skeymgmt);
30*e7be843bSPierre Pronchery int EVP_SKEYMGMT_is_a(const EVP_SKEYMGMT *skeymgmt, const char *name);
31*e7be843bSPierre Pronchery const char *EVP_SKEYMGMT_get0_name(const EVP_SKEYMGMT *skeymgmt);
32*e7be843bSPierre Pronchery const char *EVP_SKEYMGMT_get0_description(const EVP_SKEYMGMT *skeymgmt);
33*e7be843bSPierre Pronchery
34*e7be843bSPierre Pronchery void EVP_SKEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
35*e7be843bSPierre Pronchery                                   void (*fn)(EVP_SKEYMGMT *skeymgmt, void *arg),
36*e7be843bSPierre Pronchery                                   void *arg);
37*e7be843bSPierre Pronchery int EVP_SKEYMGMT_names_do_all(const EVP_SKEYMGMT *skeymgmt,
38*e7be843bSPierre Pronchery                               void (*fn)(const char *name, void *data),
39*e7be843bSPierre Pronchery                               void *data);
40*e7be843bSPierre Pronchery const OSSL_PARAM *EVP_SKEYMGMT_get0_gen_settable_params(const EVP_SKEYMGMT *skeymgmt);
41*e7be843bSPierre Pronchery const OSSL_PARAM *EVP_SKEYMGMT_get0_imp_settable_params(const EVP_SKEYMGMT *skeymgmt);
42*e7be843bSPierre Pronchery
43*e7be843bSPierre Pronchery=head1 DESCRIPTION
44*e7be843bSPierre Pronchery
45*e7be843bSPierre ProncheryB<EVP_SKEYMGMT> is a method object that represents symmetric key management
46*e7be843bSPierre Proncheryimplementations for different cryptographic algorithms.  This method object
47*e7be843bSPierre Proncheryprovides functionality to allow providers to import key material from the
48*e7be843bSPierre Proncheryoutside, as well as export key material to the outside.
49*e7be843bSPierre Pronchery
50*e7be843bSPierre ProncheryMost of the functionality can only be used internally and has no public
51*e7be843bSPierre Proncheryinterface, this opaque object is simply passed into other functions when
52*e7be843bSPierre Proncheryneeded.
53*e7be843bSPierre Pronchery
54*e7be843bSPierre ProncheryEVP_SKEYMGMT_fetch() looks for an algorithm within a provider that
55*e7be843bSPierre Proncheryhas been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the
56*e7be843bSPierre Proncheryname given by I<algorithm> and the properties given by I<properties>.
57*e7be843bSPierre Pronchery
58*e7be843bSPierre ProncheryEVP_SKEYMGMT_up_ref() increments the reference count for the given
59*e7be843bSPierre ProncheryB<EVP_SKEYMGMT> I<skeymgmt>.
60*e7be843bSPierre Pronchery
61*e7be843bSPierre ProncheryEVP_SKEYMGMT_free() decrements the reference count for the given
62*e7be843bSPierre ProncheryB<EVP_SKEYMGMT> I<skeymgmt>, and when the count reaches zero, frees it.
63*e7be843bSPierre ProncheryIf the argument is NULL, nothing is done.
64*e7be843bSPierre Pronchery
65*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_provider() returns the provider that has this particular
66*e7be843bSPierre Proncheryimplementation.
67*e7be843bSPierre Pronchery
68*e7be843bSPierre ProncheryEVP_SKEYMGMT_is_a() checks if I<skeymgmt> is an implementation of an
69*e7be843bSPierre Proncheryalgorithm that's identified by I<name>.
70*e7be843bSPierre Pronchery
71*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_name() returns the algorithm name from the provided
72*e7be843bSPierre Proncheryimplementation for the given I<skeymgmt>. Note that the I<skeymgmt> may have
73*e7be843bSPierre Proncherymultiple synonyms associated with it. In this case the first name from the
74*e7be843bSPierre Proncheryalgorithm definition is returned. Ownership of the returned string is
75*e7be843bSPierre Proncheryretained by the I<skeymgmt> object and should not be freed by the caller.
76*e7be843bSPierre Pronchery
77*e7be843bSPierre ProncheryEVP_SKEYMGMT_names_do_all() traverses all names for the I<skeymgmt>, and
78*e7be843bSPierre Proncherycalls I<fn> with each name and I<data>.
79*e7be843bSPierre Pronchery
80*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_description() returns a description of the I<skeymgmt>, meant
81*e7be843bSPierre Proncheryfor display and human consumption.  The description is at the discretion
82*e7be843bSPierre Proncheryof the I<skeymgmt> implementation.
83*e7be843bSPierre Pronchery
84*e7be843bSPierre ProncheryEVP_SKEYMGMT_do_all_provided() traverses all key I<skeymgmt> implementations by
85*e7be843bSPierre Proncheryall activated providers in the library context I<libctx>, and for each
86*e7be843bSPierre Proncheryof the implementations, calls I<fn> with the implementation method and
87*e7be843bSPierre ProncheryI<data> as arguments.
88*e7be843bSPierre Pronchery
89*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_gen_settable_params() and EVP_SKEYMGMT_get0_imp_settable_params()
90*e7be843bSPierre Proncheryget a constant L<OSSL_PARAM(3)> array that describes the settable parameters
91*e7be843bSPierre Proncherythat can be used with EVP_SKEY_generate() and EVP_SKEY_import() correspondingly.
92*e7be843bSPierre Pronchery
93*e7be843bSPierre Pronchery=head1 NOTES
94*e7be843bSPierre Pronchery
95*e7be843bSPierre ProncheryEVP_SKEYMGMT_fetch() may be called implicitly by other fetching
96*e7be843bSPierre Proncheryfunctions, using the same library context and properties.
97*e7be843bSPierre ProncheryAny other API that uses symmetric keys will typically do this.
98*e7be843bSPierre Pronchery
99*e7be843bSPierre Pronchery=head1 RETURN VALUES
100*e7be843bSPierre Pronchery
101*e7be843bSPierre ProncheryEVP_SKEYMGMT_fetch() returns a pointer to the key management
102*e7be843bSPierre Proncheryimplementation represented by an EVP_SKEYMGMT object, or NULL on
103*e7be843bSPierre Proncheryerror.
104*e7be843bSPierre Pronchery
105*e7be843bSPierre ProncheryEVP_SKEYMGMT_up_ref() returns 1 on success, or 0 on error.
106*e7be843bSPierre Pronchery
107*e7be843bSPierre ProncheryEVP_SKEYMGMT_names_do_all() returns 1 if the callback was called for all
108*e7be843bSPierre Proncherynames. A return value of 0 means that the callback was not called for any names.
109*e7be843bSPierre Pronchery
110*e7be843bSPierre ProncheryEVP_SKEYMGMT_free() doesn't return any value.
111*e7be843bSPierre Pronchery
112*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_provider() returns a pointer to a provider object, or NULL
113*e7be843bSPierre Proncheryon error.
114*e7be843bSPierre Pronchery
115*e7be843bSPierre ProncheryEVP_SKEYMGMT_is_a() returns 1 if I<skeymgmt> was identifiable, otherwise 0.
116*e7be843bSPierre Pronchery
117*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_name() returns the algorithm name, or NULL on error.
118*e7be843bSPierre Pronchery
119*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_description() returns a pointer to a description, or NULL if
120*e7be843bSPierre Proncherythere isn't one.
121*e7be843bSPierre Pronchery
122*e7be843bSPierre Pronchery=head1 SEE ALSO
123*e7be843bSPierre Pronchery
124*e7be843bSPierre ProncheryL<EVP_SKEY(3)>, L<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)>
125*e7be843bSPierre Pronchery
126*e7be843bSPierre Pronchery=head1 HISTORY
127*e7be843bSPierre Pronchery
128*e7be843bSPierre ProncheryB<EVP_SKEYMGMT> structure and functions
129*e7be843bSPierre ProncheryEVP_SKEYMGMT_fetch(),
130*e7be843bSPierre ProncheryEVP_SKEYMGMT_up_ref(),
131*e7be843bSPierre ProncheryEVP_SKEYMGMT_free(),
132*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_provider(),
133*e7be843bSPierre ProncheryEVP_SKEYMGMT_is_a(),
134*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_description(),
135*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_name(),
136*e7be843bSPierre ProncheryEVP_SKEYMGMT_do_all_provided(),
137*e7be843bSPierre ProncheryEVP_SKEYMGMT_names_do_all(),
138*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_gen_settable_params(),
139*e7be843bSPierre ProncheryEVP_SKEYMGMT_get0_imp_settable_params()
140*e7be843bSPierre Proncherywere added in OpenSSL 3.5.
141*e7be843bSPierre Pronchery
142*e7be843bSPierre Pronchery=head1 COPYRIGHT
143*e7be843bSPierre Pronchery
144*e7be843bSPierre ProncheryCopyright 2025 The OpenSSL Project Authors. All Rights Reserved.
145*e7be843bSPierre Pronchery
146*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
147*e7be843bSPierre Proncherythis file except in compliance with the License.  You can obtain a copy
148*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at
149*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>.
150*e7be843bSPierre Pronchery
151*e7be843bSPierre Pronchery=cut
152