Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / engine.3
index 2005121..8118455 100644 (file)
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.12 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 ..
 .\" 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.  \*(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-
+.\" 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
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
 .    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
+.\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
 .    \" fudge factors for nroff and troff
 .\" ========================================================================
 .\"
 .IX Title "engine 3"
-.TH engine 3 "2007-10-24" "0.9.8g" "OpenSSL"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
+.TH engine 3 "2008-09-06" "0.9.8h" "OpenSSL"
 .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
@@ -164,9 +175,13 @@ 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);
@@ -175,7 +190,9 @@ 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);
@@ -185,12 +202,18 @@ 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);
@@ -220,24 +243,34 @@ 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);
@@ -257,7 +290,9 @@ 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);
@@ -279,12 +314,16 @@ 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"
@@ -299,12 +338,12 @@ 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 'nid')
+\& EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid')
+\& key-loading - loading public and/or private EVP_PKEY keys
 .Ve
 .Sh "Reference counting and handles"
 .IX Subsection "Reference counting and handles"
@@ -312,7 +351,7 @@ Due to the modular nature of the \s-1ENGINE\s0 \s-1API\s0, pointers to ENGINEs n
 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
-released) independantly.
+released) independently.
 .PP
 \&\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
@@ -329,7 +368,7 @@ support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need
 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
+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
 perform cryptographic operations and will remain uninitialised
 until after you have released your reference.
@@ -439,7 +478,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
@@ -483,7 +522,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
@@ -505,7 +544,7 @@ 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 10
+.Vb 22
 \& ENGINE *e;
 \& const char *engine_id = "ACME";
 \& ENGINE_load_builtin_engines();
@@ -594,16 +633,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 10
+.Vb 36
 \& 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;
@@ -618,9 +657,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;
@@ -643,7 +682,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
@@ -701,7 +740,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
@@ -727,8 +766,8 @@ 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
-implementations to be provided independantly of OpenSSL libraries and/or
+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
 implementations.