diff options
Diffstat (limited to 'secure/lib/libcrypto/man/engine.3')
| -rw-r--r-- | secure/lib/libcrypto/man/engine.3 | 169 |
1 files changed, 65 insertions, 104 deletions
diff --git a/secure/lib/libcrypto/man/engine.3 b/secure/lib/libcrypto/man/engine.3 index f0a63883..3c22397 100644 --- a/secure/lib/libcrypto/man/engine.3 +++ b/secure/lib/libcrypto/man/engine.3 @@ -1,15 +1,7 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37 +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) .\" .\" Standard preamble: .\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp @@ -25,11 +17,11 @@ .. .\" 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<>. -.tr \(*W-|\(bv\*(Tr +.\" double quote, and \*(R" will give a right double quote. \*(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- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- @@ -48,22 +40,25 @@ . ds R" '' 'br\} .\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" .\" 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 +.\" 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. -.if \nF \{\ +.ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na +.el \{\ +. de IX +.. +.\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,37 +124,31 @@ .\" ======================================================================== .\" .IX Title "engine 3" -.TH engine 3 "2010-03-24" "0.9.8n" "OpenSSL" +.TH engine 3 "2010-11-16" "0.9.8p" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh .SH "NAME" 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 15 +\& \& void ENGINE_load_openssl(void); \& void ENGINE_load_dynamic(void); \& #ifndef OPENSSL_NO_STATIC_ENGINE @@ -175,13 +164,9 @@ engine \- ENGINE cryptographic module support \& #endif \& void ENGINE_load_cryptodev(void); \& void ENGINE_load_builtin_engines(void); -.Ve -.PP -.Vb 1 +\& \& void ENGINE_cleanup(void); -.Ve -.PP -.Vb 8 +\& \& ENGINE *ENGINE_get_default_RSA(void); \& ENGINE *ENGINE_get_default_DSA(void); \& ENGINE *ENGINE_get_default_ECDH(void); @@ -190,9 +175,7 @@ engine \- ENGINE cryptographic module support \& ENGINE *ENGINE_get_default_RAND(void); \& ENGINE *ENGINE_get_cipher_engine(int nid); \& ENGINE *ENGINE_get_digest_engine(int nid); -.Ve -.PP -.Vb 9 +\& \& int ENGINE_set_default_RSA(ENGINE *e); \& int ENGINE_set_default_DSA(ENGINE *e); \& int ENGINE_set_default_ECDH(ENGINE *e); @@ -202,18 +185,12 @@ engine \- ENGINE cryptographic module support \& int ENGINE_set_default_ciphers(ENGINE *e); \& 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 29 +\& \& int ENGINE_register_RSA(ENGINE *e); \& void ENGINE_unregister_RSA(ENGINE *e); \& void ENGINE_register_all_RSA(void); @@ -243,34 +220,24 @@ engine \- ENGINE cryptographic module support \& void ENGINE_register_all_digests(void); \& 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)(void)); \& int ENGINE_cmd_is_executable(ENGINE *e, int cmd); \& int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, \& long i, void *p, void (*f)(void), int cmd_optional); \& 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 3 +\& \& ENGINE *ENGINE_new(void); \& int ENGINE_free(ENGINE *e); \& int ENGINE_up_ref(ENGINE *e); -.Ve -.PP -.Vb 19 +\& \& int ENGINE_set_id(ENGINE *e, const char *id); \& int ENGINE_set_name(ENGINE *e, const char *name); \& int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); @@ -290,9 +257,7 @@ engine \- ENGINE cryptographic module support \& int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); \& int ENGINE_set_flags(ENGINE *e, int flags); \& int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); -.Ve -.PP -.Vb 21 +\& \& const char *ENGINE_get_id(const ENGINE *e); \& const char *ENGINE_get_name(const ENGINE *e); \& const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); @@ -314,16 +279,12 @@ engine \- ENGINE cryptographic module support \& const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); \& 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 .SH "DESCRIPTION" @@ -338,14 +299,14 @@ The cryptographic functionality that can be provided by an \fB\s-1ENGINE\s0\fR implementation includes the following abstractions; .PP .Vb 6 -\& RSA_METHOD - for providing alternative RSA implementations +\& RSA_METHOD \- for providing alternative RSA implementations \& DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, -\& STORE_METHOD - similarly for other OpenSSL APIs -\& EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') -\& EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') -\& key-loading - loading public and/or private EVP_PKEY keys +\& STORE_METHOD \- similarly for other OpenSSL APIs +\& EVP_CIPHER \- potentially multiple cipher algorithms (indexed by \*(Aqnid\*(Aq) +\& EVP_DIGEST \- potentially multiple hash algorithms (indexed by \*(Aqnid\*(Aq) +\& key\-loading \- loading public and/or private EVP_PKEY keys .Ve -.Sh "Reference counting and handles" +.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 treated as handles \- ie. not only as pointers, but also as references to @@ -432,7 +393,7 @@ default implementation for a given task, eg. by \fIENGINE_get_default_RSA()\fR, 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" +.SS "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 @@ -471,14 +432,14 @@ 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 indexed by 'nid', these flags and cached-responses are distinct for each 'nid' value. -.Sh "Application requirements" +.SS "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 @@ -491,7 +452,7 @@ functions, eg. \& void ENGINE_load_dynamic(void); \& /* Make the CryptoSwift hardware acceleration support available */ \& void ENGINE_load_cswift(void); -\& /* Make support for nCipher's "CHIL" hardware available */ +\& /* Make support for nCipher\*(Aqs "CHIL" hardware available */ \& void ENGINE_load_chil(void); \& ... \& /* Make ALL ENGINE implementations bundled with OpenSSL available */ @@ -522,7 +483,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 control. Some applications will want to allow the user to specify exactly which \s-1ENGINE\s0 they want used @@ -544,21 +505,21 @@ used by default for all \s-1RSA\s0, \s-1DSA\s0, and symmetric cipher operation, OpenSSL should use its builtin software as per usual. The following code illustrates how to approach this; .PP -.Vb 22 +.Vb 10 \& ENGINE *e; \& const char *engine_id = "ACME"; \& ENGINE_load_builtin_engines(); \& e = ENGINE_by_id(engine_id); \& if(!e) -\& /* the engine isn't available */ +\& /* the engine isn\*(Aqt available */ \& return; \& if(!ENGINE_init(e)) { -\& /* the engine couldn't initialise, release 'e' */ +\& /* the engine couldn\*(Aqt initialise, release \*(Aqe\*(Aq */ \& ENGINE_free(e); \& return; \& } \& if(!ENGINE_set_default_RSA(e)) -\& /* This should only happen when 'e' can't initialise, but the previous +\& /* This should only happen when \*(Aqe\*(Aq can\*(Aqt initialise, but the previous \& * statement suggests it did. */ \& abort(); \& ENGINE_set_default_DSA(e); @@ -587,7 +548,7 @@ 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 default for \s-1RSA\s0 use from then on. -.Sh "Advanced configuration support" +.SS "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 @@ -633,16 +594,16 @@ cases but the name can not. This function should initialise the \s-1ENGINE\s0 and set it as the default for everything except \s-1RAND\s0 and then return a boolean success or failure. .PP -.Vb 36 +.Vb 10 \& int generic_load_engine_fn(const char *engine_id, \& const char **pre_cmds, int pre_num, \& const char **post_cmds, int post_num) \& { \& ENGINE *e = ENGINE_by_id(engine_id); \& if(!e) return 0; -\& while(pre_num--) { +\& while(pre_num\-\-) { \& if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { -\& fprintf(stderr, "Failed command (%s - %s:%s)\en", engine_id, +\& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, \& pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); \& ENGINE_free(e); \& return 0; @@ -657,9 +618,9 @@ boolean success or failure. \& /* ENGINE_init() returned a functional reference, so free the structural \& * reference from ENGINE_by_id(). */ \& ENGINE_free(e); -\& while(post_num--) { +\& while(post_num\-\-) { \& if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { -\& fprintf(stderr, "Failed command (%s - %s:%s)\en", engine_id, +\& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, \& post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); \& ENGINE_finish(e); \& return 0; @@ -682,7 +643,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 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 @@ -740,7 +701,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 @@ -762,11 +723,11 @@ supports certain specific commands it might want to use (eg. application \*(L"fo might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOGO_GIF\s0\*(R" \- and \s-1ENGINE\s0 could therefore decide whether or not to support this \*(L"foo\*(R"\-specific extension). -.Sh "Future developments" +.SS "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 +ENGINEs (built as self-contained shared-libraries). This would allow \s-1ENGINE\s0 implementations to be provided independently 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 |
