Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / engine.3
index a6d5400..75c08c2 100644 (file)
@@ -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
 \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'
 .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 <openssl/engine.h>
 .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"
+