summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man')
-rw-r--r--src/lib/libcrypto/man/Makefile3
-rw-r--r--src/lib/libcrypto/man/engine.3535
2 files changed, 1 insertions, 537 deletions
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 695485aeeb..c8e5d51fd6 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.140 2018/04/15 17:02:03 schwarze Exp $ 1# $OpenBSD: Makefile,v 1.141 2018/04/18 01:13:37 schwarze Exp $
2 2
3.include <bsd.own.mk> 3.include <bsd.own.mk>
4 4
@@ -302,7 +302,6 @@ MAN= \
302 d2i_X509_REQ.3 \ 302 d2i_X509_REQ.3 \
303 d2i_X509_SIG.3 \ 303 d2i_X509_SIG.3 \
304 des_read_pw.3 \ 304 des_read_pw.3 \
305 engine.3 \
306 evp.3 \ 305 evp.3 \
307 get_rfc3526_prime_8192.3 \ 306 get_rfc3526_prime_8192.3 \
308 i2d_PKCS7_bio_stream.3 \ 307 i2d_PKCS7_bio_stream.3 \
diff --git a/src/lib/libcrypto/man/engine.3 b/src/lib/libcrypto/man/engine.3
deleted file mode 100644
index ebcc95f310..0000000000
--- a/src/lib/libcrypto/man/engine.3
+++ /dev/null
@@ -1,535 +0,0 @@
1.\" $OpenBSD: engine.3,v 1.16 2018/04/15 17:02:03 schwarze Exp $
2.\" full merge up to: OpenSSL crypto/engine e6390aca Jul 21 10:06:03 2015 -0400
3.\" selective merge up to: man3/ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
4.\"
5.\" This file was written by Geoff Thorpe <geoff@openssl.org>
6.\" with contributions from Paul Yang <yang.yang@baishancloud.com>.
7.\" Copyright (c) 2002, 2004, 2007, 2015, 2017 The OpenSSL Project.
8.\" All rights reserved.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\"
14.\" 1. Redistributions of source code must retain the above copyright
15.\" notice, this list of conditions and the following disclaimer.
16.\"
17.\" 2. Redistributions in binary form must reproduce the above copyright
18.\" notice, this list of conditions and the following disclaimer in
19.\" the documentation and/or other materials provided with the
20.\" distribution.
21.\"
22.\" 3. All advertising materials mentioning features or use of this
23.\" software must display the following acknowledgment:
24.\" "This product includes software developed by the OpenSSL Project
25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
26.\"
27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
28.\" endorse or promote products derived from this software without
29.\" prior written permission. For written permission, please contact
30.\" openssl-core@openssl.org.
31.\"
32.\" 5. Products derived from this software may not be called "OpenSSL"
33.\" nor may "OpenSSL" appear in their names without prior written
34.\" permission of the OpenSSL Project.
35.\"
36.\" 6. Redistributions of any form whatsoever must retain the following
37.\" acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
40.\"
41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
52.\" OF THE POSSIBILITY OF SUCH DAMAGE.
53.\"
54.Dd $Mdocdate: April 15 2018 $
55.Dt ENGINE 3
56.Os
57.Sh NAME
58.Nm engine
59.Nd ENGINE cryptographic module support
60.Sh DESCRIPTION
61These functions create, manipulate, and use cryptographic modules
62in the form of
63.Vt ENGINE
64objects.
65These objects act as containers for implementations of cryptographic
66algorithms, and support a reference-counted mechanism to allow them to
67be dynamically loaded in and out of the running application.
68.Pp
69The cryptographic functionality that can be provided by an
70.Vt ENGINE
71implementation includes the following abstractions:
72.Pp
73.Bl -bullet -compact
74.It
75.Vt RSA_METHOD :
76for providing alternative RSA implementations
77.It
78.Vt DSA_METHOD , DH_METHOD , RAND_METHOD , ECDH_METHOD ,
79.Vt ECDSA_METHOD , STORE_METHOD :
80similarly for other OpenSSL APIs
81.It
82.Vt EVP_CIPHER :
83potentially multiple cipher algorithms (indexed by 'nid')
84.It
85.Vt EVP_DIGEST :
86potentially multiple hash algorithms (indexed by 'nid')
87.It
88key-loading: loading public and/or private EVP_PKEY keys
89.El
90.Ss Reference counting and handles
91Due to the modular nature of the
92.Nm engine
93API, pointers to
94.Vt ENGINE Ns s
95need to be treated as handles - i.e. not only as pointers, but also
96as references to the underlying
97.Vt ENGINE
98object.
99One should obtain a new reference when making copies of an
100.Vt ENGINE
101pointer if the copies will be used (and released) independently.
102.Pp
103.Vt ENGINE
104objects have two levels of reference-counting to match the way in
105which the objects are used.
106At the most basic level, each
107.Vt ENGINE
108pointer is inherently a
109.Sy structural
110reference - a structural reference is required to use the pointer value
111at all, as this kind of reference is a guarantee that the structure cannot
112be deallocated until the reference is released.
113.Pp
114However, a structural reference provides no guarantee that the
115.Vt ENGINE
116is initialised and able to use any of its cryptographic implementations.
117Indeed it's quite possible that most
118.Vt ENGINE Ns s
119will not initialise at all in typical environments, as
120.Vt ENGINE Ns s
121are typically used to support specialised hardware.
122To use an
123.Vt ENGINE Ap s
124functionality, you need a
125.Sy functional
126reference.
127This kind of reference can be considered a specialised form of
128structural reference, because each functional reference implicitly
129contains a structural reference as well - however to avoid
130difficult-to-find programming bugs, it is recommended to treat the two
131kinds of reference independently.
132If you have a functional reference to an
133.Vt ENGINE ,
134you have a guarantee that the
135.Vt ENGINE
136has been initialised and is ready to perform cryptographic operations and
137will remain uninitialised until after you have released your
138reference.
139.Pp
140.Em Structural references
141.Pp
142This basic type of reference is used for instantiating new
143.Vt ENGINE Ns s ,
144iterating across OpenSSL's internal linked-list of loaded
145.Vt ENGINE Ns s ,
146reading information about an
147.Vt ENGINE ,
148etc.
149Essentially a structural reference is sufficient if you only need to
150query or manipulate the data of an
151.Vt ENGINE
152implementation rather than use its functionality.
153.Ss Application requirements
154This section will explain the basic things an application programmer
155should support to make the most useful elements of the
156.Nm engine
157functionality available to the user.
158The first thing to consider is whether the programmer wishes to make
159alternative
160.Vt ENGINE
161modules available to the application and user.
162OpenSSL maintains an internal linked list of "visible"
163.Vt ENGINE Ns s
164from which it has to operate.
165At start-up, this list is empty, and in fact if an application does
166not call any
167.Nm engine
168API calls and it uses static
169linking against openssl, then the resulting application binary will
170not contain any alternative
171.Nm engine
172code at all.
173So the first consideration is whether any/all available
174.Vt ENGINE
175implementations should be made visible to OpenSSL.
176.Pp
177Having called any of these functions,
178.Vt ENGINE
179objects would have been dynamically allocated and populated with
180these implementations and linked into OpenSSL's internal linked
181list.
182.Pp
183The fact that
184.Vt ENGINE Ns s
185are made visible to OpenSSL (and thus are linked into the program
186and loaded into memory at run-time) does not mean they are "registered"
187or called into use by OpenSSL automatically - that behaviour is
188something for the application to control.
189Some applications will want to allow the user to specify exactly which
190.Vt ENGINE
191they want used if any is to be used at all.
192Others may prefer to load all support and have OpenSSL automatically use
193at run-time any
194.Vt ENGINE
195that is able to successfully initialised - i.e. to assume that this
196corresponds to acceleration hardware attached to the machine or
197some such thing.
198There are probably numerous other ways in which applications may prefer
199to handle things, so we will simply illustrate the consequences as they
200apply to a couple of simple cases and leave developers to consider these
201and the source code to openssl's builtin utilities as guides.
202.Pp
203.Em Using a specific ENGINE implementation
204.Pp
205Here we'll assume an application has been configured by its user or
206admin to want to use the "ACME"
207.Vt ENGINE
208if it is available in the version of OpenSSL the application was
209compiled with.
210If it is available, it should be used by default for all RSA, DSA, and
211symmetric cipher operations, otherwise OpenSSL should use its builtin
212software as usual.
213The following code illustrates how to approach this:
214.Bd -literal
215ENGINE *e;
216const char *engine_id = "ACME";
217ENGINE_load_builtin_engines();
218e = ENGINE_by_id(engine_id);
219if (!e)
220 /* the engine isn't available */
221 return;
222if (!ENGINE_init(e)) {
223 /* the engine couldn't initialise, release 'e' */
224 ENGINE_free(e);
225 return;
226}
227if (!ENGINE_set_default_RSA(e))
228 /* This should only happen when 'e' can't initialise, but the previous
229 * statement suggests it did. */
230 abort();
231ENGINE_set_default_DSA(e);
232ENGINE_set_default_ciphers(e);
233/* Release the functional reference from ENGINE_init() */
234ENGINE_finish(e);
235/* Release the structural reference from ENGINE_by_id() */
236ENGINE_free(e);
237.Ed
238.Pp
239.Em Automatically using builtin ENGINE implementations
240.Pp
241Here we'll assume we want to load and register all
242.Vt ENGINE
243implementations bundled with OpenSSL, such that for any cryptographic
244algorithm required by OpenSSL - if there is an
245.Vt ENGINE
246that implements it and can be initialised, it should be used.
247The following code illustrates how this can work;
248.Bd -literal
249/* Load all bundled ENGINEs into memory and make them visible */
250ENGINE_load_builtin_engines();
251/* Register all of them for every algorithm they collectively implement */
252ENGINE_register_all_complete();
253.Ed
254.Pp
255That's all that's required.
256For example, the next time OpenSSL tries to set up an RSA key, any bundled
257.Vt ENGINE Ns s
258that implement
259.Vt RSA_METHOD
260will be passed to
261.Xr ENGINE_init 3
262and if any of those succeed, that
263.Vt ENGINE
264will be set as the default for RSA use from then on.
265.Ss Advanced configuration support
266There is a mechanism supported by the
267.Nm engine
268framework that allows each
269.Vt ENGINE
270implementation to define an arbitrary set of configuration
271"commands" and expose them to OpenSSL and any applications based on
272OpenSSL.
273This mechanism is entirely based on the use of name-value pairs
274and assumes ASCII input (no unicode or UTF for now!), so it is ideal if
275applications want to provide a transparent way for users to provide
276arbitrary configuration "directives" directly to such
277.Vt ENGINE Ns s .
278It is also possible for the application to dynamically interrogate the
279loaded
280.Vt ENGINE
281implementations for the names, descriptions, and input flags of
282their available "control commands", providing a more flexible
283configuration scheme.
284However, if the user is expected to know which
285.Vt ENGINE
286device he/she is using (in the case of specialised hardware, this
287goes without saying) then applications may not need to concern
288themselves with discovering the supported control commands and
289simply prefer to pass settings into
290.Vt ENGINE s
291exactly as they are provided by the user.
292.Pp
293Before illustrating how control commands work, it is worth mentioning
294what they are typically used for.
295Broadly speaking there are two uses for control commands; the first is
296to provide the necessary details to the implementation (which may know
297nothing at all specific to the host system) so that it can be
298initialised for use.
299This could include the path to any driver or config files it needs to
300load, required network addresses, smart-card identifiers, passwords to
301initialise protected devices, logging information, etc.
302This class of commands typically needs to be passed to an
303.Vt ENGINE
304.Sy before
305attempting to initialise it, i.e. before calling
306.Xr ENGINE_init 3 .
307The other class of commands consist of settings or operations that tweak
308certain behaviour or cause certain operations to take place, and these
309commands may work either before or after
310.Xr ENGINE_init 3 ,
311or in some cases both.
312.Vt ENGINE
313implementations should provide indications of this in the descriptions
314attached to builtin control commands and/or in external product
315documentation.
316.Pp
317.Em Issuing control commands to an ENGINE
318.Pp
319Let's illustrate by example; a function for which the caller supplies
320the name of the
321.Vt ENGINE
322it wishes to use, a table of string-pairs for use before initialisation,
323and another table for use after initialisation.
324Note that the string-pairs used for control commands consist of a
325command "name" followed by the command "parameter" - the parameter
326could be
327.Dv NULL
328in some cases but the name cannot.
329This function should initialise the
330.Vt ENGINE
331(issuing the "pre" commands beforehand and the "post" commands
332afterwards) and set it as the default for everything except RAND
333and then return a boolean success or failure.
334.Bd -literal
335int
336generic_load_engine_fn(const char *engine_id,
337 const char **pre_cmds, int pre_num,
338 const char **post_cmds, int post_num)
339{
340 ENGINE *e = ENGINE_by_id(engine_id);
341
342 if (!e)
343 return 0;
344 while (pre_num--) {
345 if (!ENGINE_ctrl_cmd_string(e,
346 pre_cmds[0], pre_cmds[1], 0)) {
347 fprintf(stderr,
348 "Failed command (%s - %s:%s)\en",
349 engine_id, pre_cmds[0],
350 pre_cmds[1] ? pre_cmds[1] : "(NULL)");
351 ENGINE_free(e);
352 return 0;
353 }
354 pre_cmds += 2;
355 }
356 if (!ENGINE_init(e)) {
357 fprintf(stderr, "Failed initialisation\en");
358 ENGINE_free(e);
359 return 0;
360 }
361 /*
362 * ENGINE_init() returned a functional reference,
363 * so free the structural reference from
364 * ENGINE_by_id().
365 */
366 ENGINE_free(e);
367 while (post_num--) {
368 if (!ENGINE_ctrl_cmd_string(e,
369 post_cmds[0], post_cmds[1], 0)) {
370 fprintf(stderr,
371 "Failed command (%s - %s:%s)\en",
372 engine_id, post_cmds[0],
373 post_cmds[1] ? post_cmds[1] : "(NULL)");
374 ENGINE_finish(e);
375 return 0;
376 }
377 post_cmds += 2;
378 }
379 ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
380 /* Success */
381 return 1;
382}
383.Ed
384.Pp
385Note that
386.Fn ENGINE_ctrl_cmd_string
387accepts a boolean argument that can relax the semantics of the function.
388If set to non-zero it will only return failure if the
389.Vt ENGINE
390supported the given command name but failed while executing it, if the
391.Vt ENGINE
392doesn't support the command name it will simply return success without
393doing anything.
394In this case we assume the user is only supplying commands specific to
395the given
396.Vt ENGINE
397so we set this to FALSE.
398.Pp
399.Em Discovering supported control commands
400.Pp
401It is possible to discover at run-time the names, numerical-ids,
402descriptions and input parameters of the control commands supported by an
403.Vt ENGINE
404using a structural reference.
405Note that some control commands are defined by OpenSSL itself and it
406will intercept and handle these control commands on behalf of the
407.Vt ENGINE ,
408i.e. the
409.Vt ENGINE Ap s
410ctrl() handler is not used for the control command.
411.In openssl/engine.h
412defines an index,
413.Dv ENGINE_CMD_BASE ,
414that all control commands implemented by
415.Vt ENGINE Ns s
416should be numbered from.
417Any command value lower than this symbol is considered a "generic"
418command is handled directly by the OpenSSL core routines.
419.Pp
420It is using these "core" control commands that one can discover the
421control commands implemented by a given
422.Vt ENGINE ,
423specifically the commands:
424.Bd -literal
425#define ENGINE_HAS_CTRL_FUNCTION 10
426#define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11
427#define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12
428#define ENGINE_CTRL_GET_CMD_FROM_NAME 13
429#define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14
430#define ENGINE_CTRL_GET_NAME_FROM_CMD 15
431#define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16
432#define ENGINE_CTRL_GET_DESC_FROM_CMD 17
433#define ENGINE_CTRL_GET_CMD_FLAGS 18
434.Ed
435.Pp
436Whilst these commands are automatically processed by the OpenSSL
437framework code, they use various properties exposed by each
438.Vt ENGINE
439to process these queries.
440An
441.Vt ENGINE
442has 3 properties it exposes that can affect how this behaves;
443it can supply a ctrl() handler, it can specify
444.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
445in the
446.Vt ENGINE Ap s
447flags, and it can expose an array of control command descriptions.
448If an
449.Vt ENGINE
450specifies the
451.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
452flag, then it will simply pass all these "core" control commands
453directly to the
454.Vt ENGINE Ap s
455ctrl() handler (and thus, it must have supplied one), so it is up
456to the
457.Vt ENGINE
458to reply to these "discovery" commands itself.
459If that flag is not set, then the OpenSSL framework code will work with
460the following rules;
461.Bl -tag -width Ds
462.It If no ctrl() handler is supplied:
463.Dv ENGINE_HAS_CTRL_FUNCTION
464returns FALSE (zero), all other commands fail.
465.It If a ctrl() handler was supplied but no array of control commands:
466.Dv ENGINE_HAS_CTRL_FUNCTION
467returns TRUE, all other commands fail.
468.It If a ctrl() handler and array of control commands was supplied:
469.Dv ENGINE_HAS_CTRL_FUNCTION
470returns TRUE, all other commands proceed processing...
471.El
472.Pp
473If the
474.Vt ENGINE Ns s
475array of control commands is empty, then all other commands will fail.
476Otherwise
477.Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE
478returns the identifier of the first command supported by the
479.Vt ENGINE ,
480.Dv ENGINE_GET_NEXT_CMD_TYPE
481takes the identifier of a command supported by the
482.Vt ENGINE
483and returns the next command identifier or fails if there are no more,
484.Dv ENGINE_CMD_FROM_NAME
485takes a string name for a command and returns the corresponding
486identifier or fails if no such command name exists, and the remaining
487commands take a command identifier and return properties of the
488corresponding commands.
489All except
490.Dv ENGINE_CTRL_GET_FLAGS
491return the string length of a command name or description, or
492populate a supplied character buffer with a copy of the command
493name or description.
494.Dv ENGINE_CTRL_GET_FLAGS
495returns a bitwise-OR'd mask of the following possible values:
496.Bd -literal
497#define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001
498#define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002
499#define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004
500#define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008
501.Ed
502.Pp
503If the
504.Dv ENGINE_CMD_FLAG_INTERNAL
505flag is set, then any other flags are purely informational to the caller.
506This flag will prevent the command being usable for any higher-level
507.Vt ENGINE
508functions such as
509.Fn ENGINE_ctrl_cmd_string .
510"INTERNAL" commands are not intended to be exposed to text-based
511configuration by applications, administrations, users, etc.
512These can support arbitrary operations via
513.Fn ENGINE_ctrl ,
514including passing to and/or from the control commands data of any
515arbitrary type.
516These commands are supported in the discovery mechanisms simply allow
517applications to determine if an
518.Vt ENGINE
519supports certain specific commands it might want to use (e.g.
520application "foo" might query various
521.Vt ENGINE Ns s
522to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - and
523.Vt ENGINE
524could therefore decide whether or not to support this "foo"-specific
525extension).
526.Sh SEE ALSO
527.Xr DH_new 3 ,
528.Xr DSA_new 3 ,
529.Xr ENGINE_add_conf_module 3 ,
530.Xr ENGINE_set_ex_data 3 ,
531.Xr RSA_new 3
532.Sh HISTORY
533The engine API first appeared in OpenSSL 0.9.7
534and has been available since
535.Ox 3.2 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-10-27 07:19:47 +0000