X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/blobdiff_plain/65b98162743cd1fcfedf9731ad9c57f55d94268a..74dab6c26c95f946056bc3d9fdafe48458c31891:/secure/lib/libcrypto/man/engine.3 diff --git a/secure/lib/libcrypto/man/engine.3 b/secure/lib/libcrypto/man/engine.3 index a6d54005c2..75c08c2951 100644 --- a/secure/lib/libcrypto/man/engine.3 +++ b/secure/lib/libcrypto/man/engine.3 @@ -1,9 +1,9 @@ -.\" Automatically generated by Pod::Man version 1.15 -.\" Wed Feb 19 16:43:04 2003 -.\" -.\" Standard preamble: -.\" ====================================================================== -.de Sh \" Subsection heading +.rn '' }` +''' $RCSfile$$Revision$$Date$ +''' +''' $Log$ +''' +.de Sh .br .if t .Sp .ne 5 @@ -11,106 +11,150 @@ \fB\\$1\fR .PP .. -.de Sp \" Vertical space (when we can't use .PP) +.de Sp .if t .sp .5v .if n .sp .. -.de Ip \" List item +.de Ip .br .ie \\n(.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. -.de Vb \" Begin verbatim text +.de Vb .ft CW .nf .ne \\$1 .. -.de Ve \" End verbatim text +.de Ve .ft R .fi .. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used -.\" to do unbreakable dashes and therefore won't be available. \*(C` and -.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> +''' +''' +''' Set up \*(-- to give an unbreakable dash; +''' string Tr holds user defined translation string. +''' Bell System Logo is used as a dummy character. +''' .tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" +.ds -- \(*W- +.ds PI pi +.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +.ds L" "" +.ds R" "" +''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of +''' \*(L" and \*(R", except that they are used on ".xx" lines, +''' such as .IP and .SH, which do another additional levels of +''' double-quote interpretation +.ds M" """ +.ds S" """ +.ds N" """"" +.ds T" """"" +.ds L' ' +.ds R' ' +.ds M' ' +.ds S' ' +.ds N' ' +.ds T' ' 'br\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' +.ds -- \(em\| +.tr \*(Tr +.ds L" `` +.ds R" '' +.ds M" `` +.ds S" '' +.ds N" `` +.ds T" '' +.ds L' ` +.ds R' ' +.ds M' ` +.ds S' ' +.ds N' ` +.ds T' ' +.ds PI \(*p 'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr -.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and -.\" index entries marked with X<> in POD. Of course, you'll have to process -.\" the output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" +.\" If the F register is turned on, we'll generate +.\" index entries out stderr for the following things: +.\" TH Title +.\" SH Header +.\" Sh Subsection +.\" Ip Item +.\" X<> Xref (embedded +.\" Of course, you have to process the output yourself +.\" in some meaninful fashion. +.if \nF \{ +.de IX +.tm Index:\\$1\t\\n%\t"\\$2" .. -. nr % 0 -. rr F +.nr % 0 +.rr F .\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it -.\" makes way too many mistakes in technical documents. -.hy 0 +.TH engine 3 "0.9.7d" "2/Sep/2004" "OpenSSL" +.UC +.if n .hy 0 .if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.de CQ \" put $1 in typewriter font +.ft CW +'if n "\c +'if t \\&\\$1\c +'if n \\&\\$1\c +'if n \&" +\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 +'.ft R +.. +.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 +. \" AM - accent mark definitions .bd B 3 -. \" fudge factors for nroff and troff +. \" fudge factors for nroff and troff .if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP .\} .if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& .\} -. \" simple accents for nroff and troff +. \" simple accents for nroff and troff .if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds ? ? +. ds ! ! +. ds / +. ds q .\} .if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' +. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' .\} -. \" troff and (daisy-wheel) nroff accents +. \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] +.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' +.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' +.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' @@ -118,32 +162,35 @@ .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff +.ds oe o\h'-(\w'o'u*4/10)'e +.ds Oe O\h'-(\w'O'u*4/10)'E +. \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) +. \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE +. ds : e +. ds 8 ss +. ds v \h'-1'\o'\(aa\(ga' +. ds _ \h'-1'^ +. ds . \h'-1'. +. ds 3 3 +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +. ds oe oe +. ds Oe OE .\} .rm #[ #] #H #V #F C -.\" ====================================================================== -.\" -.IX Title "engine 3" -.TH engine 3 "0.9.7a" "2003-02-19" "OpenSSL" -.UC .SH "NAME" -engine \- \s-1ENGINE\s0 cryptographic module support +engine \- ENGINE cryptographic module support .SH "SYNOPSIS" -.IX Header "SYNOPSIS" +.PP .Vb 1 \& #include .Ve @@ -295,14 +342,13 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& void ENGINE_add_conf_module(void); .Ve .SH "DESCRIPTION" -.IX Header "DESCRIPTION" These functions create, manipulate, and use cryptographic modules in the -form of \fB\s-1ENGINE\s0\fR objects. These objects act as containers for +form of \fBENGINE\fR objects. These objects act as containers for implementations of cryptographic algorithms, and support a reference-counted mechanism to allow them to be dynamically loaded in and out of the running application. .PP -The cryptographic functionality that can be provided by an \fB\s-1ENGINE\s0\fR +The cryptographic functionality that can be provided by an \fBENGINE\fR implementation includes the following abstractions; .PP .Vb 5 @@ -313,14 +359,13 @@ implementation includes the following abstractions; \& key-loading - loading public and/or private EVP_PKEY keys .Ve .Sh "Reference counting and handles" -.IX Subsection "Reference counting and handles" Due to the modular nature of the \s-1ENGINE\s0 \s-1API\s0, pointers to ENGINEs need to be treated as handles \- ie. not only as pointers, but also as references to the underlying \s-1ENGINE\s0 object. Ie. you should obtain a new reference when making copies of an \s-1ENGINE\s0 pointer if the copies will be used (and released) independantly. .PP -\&\s-1ENGINE\s0 objects have two levels of reference-counting to match the way in +\s-1ENGINE\s0 objects have two levels of reference-counting to match the way in which the objects are used. At the most basic level, each \s-1ENGINE\s0 pointer is inherently a \fBstructural\fR reference \- you need a structural reference simply to refer to the pointer value at all, as this kind of reference is @@ -332,12 +377,12 @@ been initiliased to be usable to perform any of its cryptographic implementations \- and indeed it's quite possible that most ENGINEs will not initialised at all on standard setups, as ENGINEs are typically used to support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a -\&\fBfunctional\fR reference. This kind of reference can be considered a +\fBfunctional\fR reference. This kind of reference can be considered a specialised form of structural reference, because each functional reference implicitly contains a structural reference as well \- however to avoid difficult-to-find programming bugs, it is recommended to treat the two kinds of reference independantly. If you have a functional reference to an -\&\s-1ENGINE\s0, you have a guarantee that the \s-1ENGINE\s0 has been initialised ready to +\s-1ENGINE\s0, you have a guarantee that the \s-1ENGINE\s0 has been initialised ready to perform cryptographic operations and will not be uninitialised or cleaned up until after you have released your reference. .PP @@ -346,7 +391,7 @@ tell which one you are dealing with at any given point in time (after all they are both simply (\s-1ENGINE\s0 *) pointers, the difference is in the way they are used). .PP -\&\fIStructural references\fR +\fIStructural references\fR .PP This basic type of reference is typically used for creating new ENGINEs dynamically, iterating across OpenSSL's internal linked-list of loaded @@ -355,10 +400,10 @@ reference is sufficient if you only need to query or manipulate the data of an \s-1ENGINE\s0 implementation rather than use its functionality. .PP The \fIENGINE_new()\fR function returns a structural reference to a new (empty) -\&\s-1ENGINE\s0 object. Other than that, structural references come from return +\s-1ENGINE\s0 object. Other than that, structural references come from return values to various \s-1ENGINE\s0 \s-1API\s0 functions such as; \fIENGINE_by_id()\fR, -\&\fIENGINE_get_first()\fR, \fIENGINE_get_last()\fR, \fIENGINE_get_next()\fR, -\&\fIENGINE_get_prev()\fR. All structural references should be released by a +\fIENGINE_get_first()\fR, \fIENGINE_get_last()\fR, \fIENGINE_get_next()\fR, +\fIENGINE_get_prev()\fR. All structural references should be released by a corresponding to call to the \fIENGINE_free()\fR function \- the \s-1ENGINE\s0 object itself will only actually be cleaned up and deallocated when the last structural reference is released. @@ -370,11 +415,11 @@ the function has returned. Eg. the function to add a new \s-1ENGINE\s0 to OpenSSL's internal list is \fIENGINE_add()\fR \- if this function returns success, then OpenSSL will have stored a new structural reference internally so the caller is still responsible for freeing their own reference with -\&\fIENGINE_free()\fR when they are finished with it. In a similar way, some +\fIENGINE_free()\fR when they are finished with it. In a similar way, some functions will automatically release the structural reference passed to it if part of the function's job is to do so. Eg. the \fIENGINE_get_next()\fR and -\&\fIENGINE_get_prev()\fR functions are used for iterating across the internal -\&\s-1ENGINE\s0 list \- they will return a new structural reference to the next (or +\fIENGINE_get_prev()\fR functions are used for iterating across the internal +\s-1ENGINE\s0 list \- they will return a new structural reference to the next (or previous) \s-1ENGINE\s0 in the list or \s-1NULL\s0 if at the end (or beginning) of the list, but in either case the structural reference passed to the function is released on behalf of the caller. @@ -383,7 +428,7 @@ To clarify a particular function's handling of references, one should always consult that function's documentation \*(L"man\*(R" page, or failing that the openssl/engine.h header file includes some hints. .PP -\&\fIFunctional references\fR +\fIFunctional references\fR .PP As mentioned, functional references exist when the cryptographic functionality of an \s-1ENGINE\s0 is required to be available. A functional @@ -408,21 +453,20 @@ function. .PP The second way to get a functional reference is by asking OpenSSL for a default implementation for a given task, eg. by \fIENGINE_get_default_RSA()\fR, -\&\fIENGINE_get_default_cipher_engine()\fR, etc. These are discussed in the next +\fIENGINE_get_default_cipher_engine()\fR, etc. These are discussed in the next section, though they are not usually required by application programmers as they are used automatically when creating and using the relevant algorithm-specific types in OpenSSL, such as \s-1RSA\s0, \s-1DSA\s0, \s-1EVP_CIPHER_CTX\s0, etc. .Sh "Default implementations" -.IX Subsection "Default implementations" For each supported abstraction, the \s-1ENGINE\s0 code maintains an internal table of state to control which implementations are available for a given abstraction and which should be used by default. These implementations are -registered in the tables separated-out by an 'nid' index, because +registered in the tables separated-out by an \*(L'nid\*(R' index, because abstractions like \s-1EVP_CIPHER\s0 and \s-1EVP_DIGEST\s0 support many distinct algorithms and modes \- ENGINEs will support different numbers and combinations of these. In the case of other abstractions like \s-1RSA\s0, \s-1DSA\s0, etc, there is only one \*(L"algorithm\*(R" so all implementations implicitly -register using the same 'nid' index. ENGINEs can be \fBregistered\fR into +register using the same \*(L'nid\*(R' index. ENGINEs can be \fBregistered\fR into these tables to make themselves available for use automatically by the various abstractions, eg. \s-1RSA\s0. For illustrative purposes, we continue with the \s-1RSA\s0 example, though all comments apply similarly to the other @@ -430,7 +474,7 @@ abstractions (they each get their own table and linkage to the corresponding section of openssl code). .PP When a new \s-1RSA\s0 key is being created, ie. in \fIRSA_new_method()\fR, a -\&\*(L"get_default\*(R" call will be made to the \s-1ENGINE\s0 subsystem to process the \s-1RSA\s0 +\*(L"get_default\*(R" call will be made to the \s-1ENGINE\s0 subsystem to process the \s-1RSA\s0 state table and return a functional reference to an initialised \s-1ENGINE\s0 whose \s-1RSA_METHOD\s0 should be used. If no \s-1ENGINE\s0 should (or can) be used, it will return \s-1NULL\s0 and the \s-1RSA\s0 key will operate with a \s-1NULL\s0 \s-1ENGINE\s0 handle by @@ -439,7 +483,7 @@ behave the way it used to before the \s-1ENGINE\s0 \s-1API\s0 existed \- for det RSA_new_method(3)). .PP Each state table has a flag to note whether it has processed this -\&\*(L"get_default\*(R" query since the table was last modified, because to process +\*(L"get_default\*(R" query since the table was last modified, because to process this question it must iterate across all the registered ENGINEs in the table trying to initialise each of them in turn, in case one of them is operational. If it returns a functional reference to an \s-1ENGINE\s0, it will @@ -448,20 +492,20 @@ needing to iterate across the table). Likewise, it will cache a \s-1NULL\s0 response if no \s-1ENGINE\s0 was available so that future queries won't repeat the same iteration unless the state table changes. This behaviour can also be changed; if the \s-1ENGINE_TABLE_FLAG_NOINIT\s0 flag is set (using -\&\fIENGINE_set_table_flags()\fR), no attempted initialisations will take place, -instead the only way for the state table to return a non-NULL \s-1ENGINE\s0 to the -\&\*(L"get_default\*(R" query will be if one is expressly set in the table. Eg. -\&\fIENGINE_set_default_RSA()\fR does the same job as \fIENGINE_register_RSA()\fR except +\fIENGINE_set_table_flags()\fR), no attempted initialisations will take place, +instead the only way for the state table to return a non-\s-1NULL\s0 \s-1ENGINE\s0 to the +\*(L"get_default\*(R" query will be if one is expressly set in the table. Eg. +\fIENGINE_set_default_RSA()\fR does the same job as \fIENGINE_register_RSA()\fR except that it also sets the state table's cached response for the \*(L"get_default\*(R" query. .PP In the case of abstractions like \s-1EVP_CIPHER\s0, where implementations are -indexed by 'nid', these flags and cached-responses are distinct for each -\&'nid' value. +indexed by \*(L'nid\*(R', these flags and cached-responses are distinct for each +\&'nid\*(R' value. .PP It is worth illustrating the difference between \*(L"registration\*(R" of ENGINEs into these per-algorithm state tables and using the alternative -\&\*(L"set_default\*(R" functions. The latter handles both \*(L"registration\*(R" and also +\*(L"set_default\*(R" functions. The latter handles both \*(L"registration\*(R" and also setting the cached \*(L"default\*(R" \s-1ENGINE\s0 in each relevant state table \- so registered ENGINEs will only have a chance to be initialised for use as a default if a default \s-1ENGINE\s0 wasn't already set for the same state table. @@ -487,13 +531,12 @@ The results would be as follows; \& assert(e5 == NULL); .Ve .Sh "Application requirements" -.IX Subsection "Application requirements" This section will explain the basic things an application programmer should support to make the most useful elements of the \s-1ENGINE\s0 functionality available to the user. The first thing to consider is whether the programmer wishes to make alternative \s-1ENGINE\s0 modules available to the application and user. OpenSSL maintains an internal linked list of -\&\*(L"visible\*(R" ENGINEs from which it has to operate \- at start-up, this list is +\*(L"visible\*(R" ENGINEs from which it has to operate \- at start-up, this list is empty and in fact if an application does not call any \s-1ENGINE\s0 \s-1API\s0 calls and it uses static linking against openssl, then the resulting application binary will not contain any alternative \s-1ENGINE\s0 code at all. So the first @@ -522,7 +565,7 @@ mention an important \s-1API\s0 function; .Ve If no \s-1ENGINE\s0 \s-1API\s0 functions are called at all in an application, then there are no inherent memory leaks to worry about from the \s-1ENGINE\s0 functionality, -however if any ENGINEs are \*(L"load\*(R"ed, even if they are never registered or +however if any ENGINEs are \*(L"load"ed, even if they are never registered or used, it is necessary to use the \fIENGINE_cleanup()\fR function to correspondingly cleanup before program exit, if the caller wishes to avoid memory leaks. This mechanism uses an internal callback registration table @@ -536,7 +579,7 @@ linker. .PP The fact that ENGINEs are made visible to OpenSSL (and thus are linked into the program and loaded into memory at run-time) does not mean they are -\&\*(L"registered\*(R" or called into use by OpenSSL automatically \- that behaviour +\*(L"registered\*(R" or called into use by OpenSSL automatically \- that behaviour is something for the application to have control over. Some applications will want to allow the user to specify exactly which \s-1ENGINE\s0 they want used if any is to be used at all. Others may prefer to load all support and have @@ -548,7 +591,7 @@ things, so we will simply illustrate the consequences as they apply to a couple of simple cases and leave developers to consider these and the source code to openssl's builtin utilities as guides. .PP -\&\fIUsing a specific \s-1ENGINE\s0 implementation\fR +\fIUsing a specific \s-1ENGINE\s0 implementation\fR .PP Here we'll assume an application has been configured by its user or admin to want to use the \*(L"\s-1ACME\s0\*(R" \s-1ENGINE\s0 if it is available in the version of @@ -581,7 +624,7 @@ illustrates how to approach this; \& /* Release the structural reference from ENGINE_by_id() */ \& ENGINE_free(e); .Ve -\&\fIAutomatically using builtin \s-1ENGINE\s0 implementations\fR +\fIAutomatically using builtin \s-1ENGINE\s0 implementations\fR .PP Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations bundled with OpenSSL, such that for any cryptographic algorithm required by @@ -595,14 +638,13 @@ it should be used. The following code illustrates how this can work; \& ENGINE_register_all_complete(); .Ve That's all that's required. Eg. the next time OpenSSL tries to set up an -\&\s-1RSA\s0 key, any bundled ENGINEs that implement \s-1RSA_METHOD\s0 will be passed to -\&\fIENGINE_init()\fR and if any of those succeed, that \s-1ENGINE\s0 will be set as the +\s-1RSA\s0 key, any bundled ENGINEs that implement \s-1RSA_METHOD\s0 will be passed to +\fIENGINE_init()\fR and if any of those succeed, that \s-1ENGINE\s0 will be set as the default for use with \s-1RSA\s0 from then on. .Sh "Advanced configuration support" -.IX Subsection "Advanced configuration support" There is a mechanism supported by the \s-1ENGINE\s0 framework that allows each -\&\s-1ENGINE\s0 implementation to define an arbitrary set of configuration -\&\*(L"commands\*(R" and expose them to OpenSSL and any applications based on +\s-1ENGINE\s0 implementation to define an arbitrary set of configuration +\*(L"commands\*(R" and expose them to OpenSSL and any applications based on OpenSSL. This mechanism is entirely based on the use of name-value pairs and and assumes \s-1ASCII\s0 input (no unicode or \s-1UTF\s0 for now!), so it is ideal if applications want to provide a transparent way for users to provide @@ -632,7 +674,7 @@ in same cases both. \s-1ENGINE\s0 implementations should provide indications of this in the descriptions attached to builtin control commands and/or in external product documentation. .PP -\&\fIIssuing control commands to an \s-1ENGINE\s0\fR +\fIIssuing control commands to an \s-1ENGINE\s0\fR .PP Let's illustrate by example; a function for which the caller supplies the name of the \s-1ENGINE\s0 it wishes to use, a table of string-pairs for use before @@ -688,9 +730,9 @@ failure if the \s-1ENGINE\s0 supported the given command name but failed while executing it, if the \s-1ENGINE\s0 doesn't support the command name it will simply return success without doing anything. In this case we assume the user is only supplying commands specific to the given \s-1ENGINE\s0 so we set this to -\&\s-1FALSE\s0. +\s-1FALSE\s0. .PP -\&\fIDiscovering supported control commands\fR +\fIDiscovering supported control commands\fR .PP It is possible to discover at run-time the names, numerical-ids, descriptions and input parameters of the control commands supported from a structural @@ -698,7 +740,7 @@ reference to any \s-1ENGINE\s0. It is first important to note that some control commands are defined by OpenSSL itself and it will intercept and handle these control commands on behalf of the \s-1ENGINE\s0, ie. the \s-1ENGINE\s0's \fIctrl()\fR handler is not used for the control command. openssl/engine.h defines a symbol, -\&\s-1ENGINE_CMD_BASE\s0, that all control commands implemented by ENGINEs from. Any +\s-1ENGINE_CMD_BASE\s0, that all control commands implemented by ENGINEs from. Any command value lower than this symbol is considered a \*(L"generic\*(R" command is handled directly by the OpenSSL core routines. .PP @@ -746,9 +788,9 @@ identifier or fails if there are no more, \s-1ENGINE_CMD_FROM_NAME\s0 takes a st name for a command and returns the corresponding identifier or fails if no such command name exists, and the remaining commands take a command identifier and return properties of the corresponding commands. All except -\&\s-1ENGINE_CTRL_GET_FLAGS\s0 return the string length of a command name or description, +\s-1ENGINE_CTRL_GET_FLAGS\s0 return the string length of a command name or description, or populate a supplied character buffer with a copy of the command name or -description. \s-1ENGINE_CTRL_GET_FLAGS\s0 returns a bitwise-OR'd mask of the following +description. \s-1ENGINE_CTRL_GET_FLAGS\s0 returns a bitwise-\s-1OR\s0'd mask of the following possible values; .PP .Vb 4 @@ -760,7 +802,7 @@ possible values; If the \s-1ENGINE_CMD_FLAG_INTERNAL\s0 flag is set, then any other flags are purely informational to the caller \- this flag will prevent the command being usable for any higher-level \s-1ENGINE\s0 functions such as \fIENGINE_ctrl_cmd_string()\fR. -\&\*(L"\s-1INTERNAL\s0\*(R" commands are not intended to be exposed to text-based configuration +\*(L"\s-1INTERNAL\s0\*(R" commands are not intended to be exposed to text-based configuration by applications, administrations, users, etc. These can support arbitrary operations via \fIENGINE_ctrl()\fR, including passing to and/or from the control commands data of any arbitrary type. These commands are supported in the @@ -770,15 +812,36 @@ might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOG and \s-1ENGINE\s0 could therefore decide whether or not to support this \*(L"foo\*(R"\-specific extension). .Sh "Future developments" -.IX Subsection "Future developments" The \s-1ENGINE\s0 \s-1API\s0 and internal architecture is currently being reviewed. Slated for possible release in 0.9.8 is support for transparent loading of \*(L"dynamic\*(R" ENGINEs (built as self-contained shared-libraries). This would allow \s-1ENGINE\s0 implementations to be provided independantly of OpenSSL libraries and/or -OpenSSL-based applications, and would also remove any requirement for +OpenSSL\-based applications, and would also remove any requirement for applications to explicitly use the \*(L"dynamic\*(R" \s-1ENGINE\s0 to bind to shared-library implementations. .SH "SEE ALSO" -.IX Header "SEE ALSO" rsa(3), dsa(3), dh(3), rand(3), RSA_new_method(3) + +.rn }` '' +.IX Title "engine 3" +.IX Name "engine - ENGINE cryptographic module support" + +.IX Header "NAME" + +.IX Header "SYNOPSIS" + +.IX Header "DESCRIPTION" + +.IX Subsection "Reference counting and handles" + +.IX Subsection "Default implementations" + +.IX Subsection "Application requirements" + +.IX Subsection "Advanced configuration support" + +.IX Subsection "Future developments" + +.IX Header "SEE ALSO" +