diff options
Diffstat (limited to 'secure/lib/libcrypto/man/engine.3')
| -rw-r--r-- | secure/lib/libcrypto/man/engine.3 | 82 |
1 files changed, 50 insertions, 32 deletions
diff --git a/secure/lib/libcrypto/man/engine.3 b/secure/lib/libcrypto/man/engine.3 index 7acbabe..9fcafc5 100644 --- a/secure/lib/libcrypto/man/engine.3 +++ b/secure/lib/libcrypto/man/engine.3 @@ -1,8 +1,7 @@ -.\" Automatically generated by Pod::Man version 1.15 -.\" Wed Mar 17 09:38:43 2004 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 .\" .\" Standard preamble: -.\" ====================================================================== +.\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp @@ -15,12 +14,6 @@ .if t .sp .5v .if n .sp .. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. .de Vb \" Begin verbatim text .ft CW .nf @@ -28,15 +21,14 @@ .. .de Ve \" End verbatim text .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<> +.\" 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<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ @@ -56,10 +48,10 @@ . ds R" '' '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 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" @@ -68,14 +60,13 @@ . rr F .\} .\" -.\" For nroff, turn off justification. Always turn off hyphenation; it -.\" makes way too many mistakes in technical documents. +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. .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. -.bd B 3 . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 @@ -135,35 +126,39 @@ . ds Ae AE .\} .rm #[ #] #H #V #F C -.\" ====================================================================== +.\" ======================================================================== .\" .IX Title "engine 3" -.TH engine 3 "0.9.7d" "2004-03-17" "OpenSSL" -.UC +.TH engine 3 "2005-02-24" "0.9.7d" "OpenSSL" .SH "NAME" -engine \- \s-1ENGINE\s0 cryptographic module support +engine \- ENGINE cryptographic module support .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/engine.h> .Ve +.PP .Vb 4 \& ENGINE *ENGINE_get_first(void); \& ENGINE *ENGINE_get_last(void); \& ENGINE *ENGINE_get_next(ENGINE *e); \& ENGINE *ENGINE_get_prev(ENGINE *e); .Ve +.PP .Vb 2 \& int ENGINE_add(ENGINE *e); \& int ENGINE_remove(ENGINE *e); .Ve +.PP .Vb 1 \& ENGINE *ENGINE_by_id(const char *id); .Ve +.PP .Vb 2 \& int ENGINE_init(ENGINE *e); \& int ENGINE_finish(ENGINE *e); .Ve +.PP .Vb 12 \& void ENGINE_load_openssl(void); \& void ENGINE_load_dynamic(void); @@ -178,9 +173,11 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& void ENGINE_load_openbsd_dev_crypto(void); \& void ENGINE_load_builtin_engines(void); .Ve +.PP .Vb 1 \& void ENGINE_cleanup(void); .Ve +.PP .Vb 6 \& ENGINE *ENGINE_get_default_RSA(void); \& ENGINE *ENGINE_get_default_DSA(void); @@ -189,6 +186,7 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& ENGINE *ENGINE_get_cipher_engine(int nid); \& ENGINE *ENGINE_get_digest_engine(int nid); .Ve +.PP .Vb 7 \& int ENGINE_set_default_RSA(ENGINE *e); \& int ENGINE_set_default_DSA(ENGINE *e); @@ -198,13 +196,16 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& int ENGINE_set_default_digests(ENGINE *e); \& int ENGINE_set_default_string(ENGINE *e, const char *list); .Ve +.PP .Vb 1 \& int ENGINE_set_default(ENGINE *e, unsigned int flags); .Ve +.PP .Vb 2 \& unsigned int ENGINE_get_table_flags(void); \& void ENGINE_set_table_flags(unsigned int flags); .Ve +.PP .Vb 20 \& int ENGINE_register_RSA(ENGINE *e); \& void ENGINE_unregister_RSA(ENGINE *e); @@ -227,6 +228,7 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& int ENGINE_register_complete(ENGINE *e); \& int ENGINE_register_all_complete(void); .Ve +.PP .Vb 6 \& int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)()); \& int ENGINE_cmd_is_executable(ENGINE *e, int cmd); @@ -235,18 +237,22 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, \& int cmd_optional); .Ve +.PP .Vb 2 \& int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); \& void *ENGINE_get_ex_data(const ENGINE *e, int idx); .Ve +.PP .Vb 2 \& int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, \& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); .Ve +.PP .Vb 2 \& ENGINE *ENGINE_new(void); \& int ENGINE_free(ENGINE *e); .Ve +.PP .Vb 16 \& int ENGINE_set_id(ENGINE *e, const char *id); \& int ENGINE_set_name(ENGINE *e, const char *name); @@ -265,6 +271,7 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& int ENGINE_set_flags(ENGINE *e, int flags); \& int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); .Ve +.PP .Vb 18 \& const char *ENGINE_get_id(const ENGINE *e); \& const char *ENGINE_get_name(const ENGINE *e); @@ -285,12 +292,14 @@ engine \- \s-1ENGINE\s0 cryptographic module support \& int ENGINE_get_flags(const ENGINE *e); \& const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); .Ve +.PP .Vb 4 \& EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, \& UI_METHOD *ui_method, void *callback_data); \& EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, \& UI_METHOD *ui_method, void *callback_data); .Ve +.PP .Vb 1 \& void ENGINE_add_conf_module(void); .Ve @@ -436,7 +445,7 @@ whose \s-1RSA_METHOD\s0 should be used. If no \s-1ENGINE\s0 should (or can) be u will return \s-1NULL\s0 and the \s-1RSA\s0 key will operate with a \s-1NULL\s0 \s-1ENGINE\s0 handle by using the conventional \s-1RSA\s0 implementation in OpenSSL (and will from then on behave the way it used to before the \s-1ENGINE\s0 \s-1API\s0 existed \- for details see -RSA_new_method(3)). +\&\fIRSA_new_method\fR\|(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 @@ -477,6 +486,7 @@ ciphers {A} and \s-1DSA\s0, and the following code is executed; \& e4 = ENGINE_get_default_DSA(); \& e5 = ENGINE_get_cipher_engine(C); .Ve +.PP The results would be as follows; .PP .Vb 5 @@ -493,7 +503,7 @@ 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 @@ -512,6 +522,7 @@ functions, eg. \& /* Make ALL ENGINE implementations bundled with OpenSSL available */ \& void ENGINE_load_builtin_engines(void); .Ve +.PP Having called any of these functions, \s-1ENGINE\s0 objects would have been dynamically allocated and populated with these implementations and linked into OpenSSL's internal linked list. At this point it is important to @@ -520,6 +531,7 @@ mention an important \s-1API\s0 function; .Vb 1 \& void ENGINE_cleanup(void); .Ve +.PP 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 @@ -535,7 +547,7 @@ callbacks required by the functionality you do use will be required by the 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 +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 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 @@ -581,6 +593,7 @@ illustrates how to approach this; \& /* Release the structural reference from ENGINE_by_id() */ \& ENGINE_free(e); .Ve +.PP \&\fIAutomatically using builtin \s-1ENGINE\s0 implementations\fR .PP Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations @@ -594,6 +607,7 @@ it should be used. The following code illustrates how this can work; \& /* Register all of them for every algorithm they collectively implement */ \& ENGINE_register_all_complete(); .Ve +.PP 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 @@ -682,6 +696,7 @@ boolean success or failure. \& return 1; \& } .Ve +.PP Note that \fIENGINE_ctrl_cmd_string()\fR accepts a boolean argument that can relax the semantics of the function \- if set non-zero it will only return failure if the \s-1ENGINE\s0 supported the given command name but failed while @@ -692,7 +707,7 @@ only supplying commands specific to the given \s-1ENGINE\s0 so we set this to .PP \&\fIDiscovering supported control commands\fR .PP -It is possible to discover at run-time the names, numerical-ids, descriptions +It is possible to discover at run-time the names, numerical\-ids, descriptions and input parameters of the control commands supported from a structural 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 @@ -716,6 +731,7 @@ commands implemented by a given \s-1ENGINE\s0, specifically the commands; \& #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 \& #define ENGINE_CTRL_GET_CMD_FLAGS 18 .Ve +.PP Whilst these commands are automatically processed by the OpenSSL framework code, they use various properties exposed by each \s-1ENGINE\s0 by which to process these queries. An \s-1ENGINE\s0 has 3 properties it exposes that can affect this behaviour; @@ -738,6 +754,7 @@ OpenSSL framework code will work with the following rules; \& ENGINE_HAS_CTRL_FUNCTION returns TRUE, \& all other commands proceed processing ... .Ve +.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 @@ -748,7 +765,7 @@ 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, 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\-OR'd mask of the following possible values; .PP .Vb 4 @@ -757,6 +774,7 @@ possible values; \& #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 \& #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 .Ve +.PP 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. @@ -773,12 +791,12 @@ extension). .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 +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 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) +\&\fIrsa\fR\|(3), \fIdsa\fR\|(3), \fIdh\fR\|(3), \fIrand\fR\|(3), +\&\fIRSA_new_method\fR\|(3) |
