diff options
Diffstat (limited to 'secure/lib/libcrypto/man/engine.3')
| -rw-r--r-- | secure/lib/libcrypto/man/engine.3 | 87 |
1 files changed, 48 insertions, 39 deletions
diff --git a/secure/lib/libcrypto/man/engine.3 b/secure/lib/libcrypto/man/engine.3 index 6e4ef5f14bc0..6176e7300190 100644 --- a/secure/lib/libcrypto/man/engine.3 +++ b/secure/lib/libcrypto/man/engine.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.23) +.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== @@ -38,6 +38,8 @@ . ds PI \(*p . ds L" `` . ds R" '' +. ds C` +. ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. @@ -48,17 +50,24 @@ .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. -.ie \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX .. -. nr % 0 -. rr F -.\} -.el \{\ -. de IX +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{ +. if \nF \{ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" .. +. if !\nF==2 \{ +. nr % 0 +. nr F 2 +. \} +. \} .\} +.rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -124,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "engine 3" -.TH engine 3 "2013-02-11" "1.0.1e" "OpenSSL" +.TH engine 3 "2015-01-15" "1.0.1l" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -308,7 +317,7 @@ implementation includes the following abstractions; .Ve .SS "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 +Due to the modular nature of the \s-1ENGINE API,\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. one should obtain a new reference when making copies of an \s-1ENGINE\s0 pointer if the copies will be used (and @@ -330,7 +339,7 @@ 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 independently. 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 remain uninitialised until after you have released your reference. .PP @@ -338,19 +347,19 @@ until after you have released your reference. .PP This basic type of reference is used for instantiating new ENGINEs, iterating across OpenSSL's internal linked-list of loaded -ENGINEs, reading information about an \s-1ENGINE\s0, etc. Essentially a structural +ENGINEs, reading information about an \s-1ENGINE,\s0 etc. Essentially a structural 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. There are other \s-1ENGINE\s0 \s-1API\s0 functions that return structural +\&\s-1ENGINE\s0 object. There are other \s-1ENGINE API\s0 functions that return structural references 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 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. .PP -It should also be noted that many \s-1ENGINE\s0 \s-1API\s0 function calls that accept a +It should also be noted that many \s-1ENGINE API\s0 function calls that accept a structural reference will internally obtain another reference \- typically this happens whenever the supplied \s-1ENGINE\s0 will be needed by OpenSSL after the function has returned. Eg. the function to add a new \s-1ENGINE\s0 to @@ -375,7 +384,7 @@ the openssl/engine.h header file includes some hints. As mentioned, functional references exist when the cryptographic functionality of an \s-1ENGINE\s0 is required to be available. A functional reference can be obtained in one of two ways; from an existing structural -reference to the required \s-1ENGINE\s0, or by asking OpenSSL for the default +reference to the required \s-1ENGINE,\s0 or by asking OpenSSL for the default operational \s-1ENGINE\s0 for a given cryptographic purpose. .PP To obtain a functional reference from an existing structural reference, @@ -383,7 +392,7 @@ call the \fIENGINE_init()\fR function. This returns zero if the \s-1ENGINE\s0 wa already operational and couldn't be successfully initialised (eg. lack of system drivers, no special hardware attached, etc), otherwise it will return non-zero to indicate that the \s-1ENGINE\s0 is now operational and will -have allocated a new \fBfunctional\fR reference to the \s-1ENGINE\s0. All functional +have allocated a new \fBfunctional\fR reference to the \s-1ENGINE.\s0 All functional references are released by calling \fIENGINE_finish()\fR (which removes the implicit structural reference as well). .PP @@ -392,7 +401,7 @@ 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 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. +algorithm-specific types in OpenSSL, such as \s-1RSA, DSA, EVP_CIPHER_CTX,\s0 etc. .SS "Default implementations" .IX Subsection "Default implementations" For each supported abstraction, the \s-1ENGINE\s0 code maintains an internal table @@ -401,7 +410,7 @@ abstraction and which should be used by default. These implementations are registered in the tables and indexed by an 'nid' value, because abstractions like \s-1EVP_CIPHER\s0 and \s-1EVP_DIGEST\s0 support many distinct algorithms and modes, and ENGINEs can support arbitrarily many of them. -In the case of other abstractions like \s-1RSA\s0, \s-1DSA\s0, etc, there is only one +In the case of other abstractions like \s-1RSA, DSA,\s0 etc, there is only one \&\*(L"algorithm\*(R" so all implementations implicitly register using the same 'nid' index. .PP @@ -410,15 +419,15 @@ when calling RSA_new_method(\s-1NULL\s0)), a \*(L"get_default\*(R" call will be \&\s-1ENGINE\s0 subsystem to process the corresponding state table and return a functional reference to an initialised \s-1ENGINE\s0 whose implementation should be used. If no \s-1ENGINE\s0 should (or can) be used, it will return \s-1NULL\s0 and the caller -will operate with a \s-1NULL\s0 \s-1ENGINE\s0 handle \- this usually equates to using the +will operate with a \s-1NULL ENGINE\s0 handle \- this usually equates to using the conventional software implementation. In the latter case, OpenSSL will from -then on behave the way it used to before the \s-1ENGINE\s0 \s-1API\s0 existed. +then on behave the way it used to before the \s-1ENGINE API\s0 existed. .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 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 +operational. If it returns a functional reference to an \s-1ENGINE,\s0 it will also cache another reference to speed up processing future queries (without 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 @@ -429,7 +438,7 @@ instead the only way for the state table to return a non-NULL \s-1ENGINE\s0 to t \&\*(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. In the case of abstractions like \s-1EVP_CIPHER\s0, where implementations are +query. 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. .SS "Application requirements" @@ -440,7 +449,7 @@ 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 -empty and in fact if an application does not call any \s-1ENGINE\s0 \s-1API\s0 calls and +empty and in fact if an application does not call any \s-1ENGINE API\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 consideration is whether any/all available \s-1ENGINE\s0 implementations should be @@ -468,13 +477,13 @@ mention an important \s-1API\s0 function; \& void ENGINE_cleanup(void); .Ve .PP -If no \s-1ENGINE\s0 \s-1API\s0 functions are called at all in an application, then there +If no \s-1ENGINE API\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 loaded, 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 -so that any \s-1ENGINE\s0 \s-1API\s0 functionality that knows it requires cleanup can +so that any \s-1ENGINE API\s0 functionality that knows it requires cleanup can register its cleanup details to be called during \fIENGINE_cleanup()\fR. This approach allows \fIENGINE_cleanup()\fR to clean up after any \s-1ENGINE\s0 functionality at all that your program uses, yet doesn't automatically create linker @@ -499,9 +508,9 @@ source code to openssl's builtin utilities as guides. \&\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 +to want to use the \*(L"\s-1ACME\*(R" ENGINE\s0 if it is available in the version of OpenSSL the application was compiled with. If it is available, it should be -used by default for all \s-1RSA\s0, \s-1DSA\s0, and symmetric cipher operation, otherwise +used by default for all \s-1RSA, DSA,\s0 and symmetric cipher operation, otherwise OpenSSL should use its builtin software as per usual. The following code illustrates how to approach this; .PP @@ -574,7 +583,7 @@ so that it can be initialised for use. This could include the path to any driver or config files it needs to load, required network addresses, smart-card identifiers, passwords to initialise protected devices, logging information, etc etc. This class of commands typically needs to be -passed to an \s-1ENGINE\s0 \fBbefore\fR attempting to initialise it, ie. before +passed to an \s-1ENGINE \s0\fBbefore\fR attempting to initialise it, ie. before calling \fIENGINE_init()\fR. The other class of commands consist of settings or operations that tweak certain behaviour or cause certain operations to take place, and these commands may work either before or after \fIENGINE_init()\fR, or @@ -589,8 +598,8 @@ name of the \s-1ENGINE\s0 it wishes to use, a table of string-pairs for use befo initialisation, and another table for use after initialisation. Note that the string-pairs used for control commands consist of a command \*(L"name\*(R" followed by the command \*(L"parameter\*(R" \- the parameter could be \s-1NULL\s0 in some -cases but the name can not. This function should initialise the \s-1ENGINE\s0 -(issuing the \*(L"pre\*(R" commands beforehand and the \*(L"post\*(R" commands afterwards) +cases but the name can not. This function should initialise the \s-1ENGINE +\&\s0(issuing the \*(L"pre\*(R" commands beforehand and the \*(L"post\*(R" commands afterwards) and set it as the default for everything except \s-1RAND\s0 and then return a boolean success or failure. .PP @@ -639,7 +648,7 @@ 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 .PP @@ -647,14 +656,14 @@ It is possible to discover at run-time the names, numerical-ids, descriptions and input parameters of the control commands supported by an \s-1ENGINE\s0 using a structural reference. 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 an index, \s-1ENGINE_CMD_BASE\s0, that all control commands +\&\s-1ENGINE,\s0 ie. the \s-1ENGINE\s0's \fIctrl()\fR handler is not used for the control command. +openssl/engine.h defines an index, \s-1ENGINE_CMD_BASE,\s0 that all control commands implemented by ENGINEs should be numbered from. Any command value lower than this symbol is considered a \*(L"generic\*(R" command is handled directly by the OpenSSL core routines. .PP It is using these \*(L"core\*(R" control commands that one can discover the control -commands implemented by a given \s-1ENGINE\s0, specifically the commands; +commands implemented by a given \s-1ENGINE,\s0 specifically the commands; .PP .Vb 9 \& #define ENGINE_HAS_CTRL_FUNCTION 10 @@ -693,7 +702,7 @@ OpenSSL framework code will work with the following rules; .PP If the \s-1ENGINE\s0's array of control commands is empty then all other commands will fail, otherwise; \s-1ENGINE_CTRL_GET_FIRST_CMD_TYPE\s0 returns the identifier of -the first command supported by the \s-1ENGINE\s0, \s-1ENGINE_GET_NEXT_CMD_TYPE\s0 takes the +the first command supported by the \s-1ENGINE, ENGINE_GET_NEXT_CMD_TYPE\s0 takes the identifier of a command supported by the \s-1ENGINE\s0 and returns the next command identifier or fails if there are no more, \s-1ENGINE_CMD_FROM_NAME\s0 takes a string name for a command and returns the corresponding identifier or fails if no such @@ -714,18 +723,18 @@ 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\*(R"\s0 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 discovery mechanisms simply to allow applications determinie if an \s-1ENGINE\s0 supports certain specific commands it might want to use (eg. application \*(L"foo\*(R" -might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOGO_GIF\s0\*(R" \- +might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOGO_GIF\*(R" \-\s0 and \s-1ENGINE\s0 could therefore decide whether or not to support this \*(L"foo\*(R"\-specific extension). .SS "Future developments" .IX Subsection "Future developments" -The \s-1ENGINE\s0 \s-1API\s0 and internal architecture is currently being reviewed. Slated for +The \s-1ENGINE API\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 independently of OpenSSL libraries and/or |