delete engine(3); nothing of value left in that page

2 files changed, 1 insertions, 537 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 695485aeeb8..c8e5d51fd6e 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.140 2018/04/15 17:02:03 schwarze Exp $
+# $OpenBSD: Makefile,v 1.141 2018/04/18 01:13:37 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -302,7 +302,6 @@ MAN=	\
 	d2i_X509_REQ.3 \
 	d2i_X509_SIG.3 \
 	des_read_pw.3 \
-	engine.3 \
 	evp.3 \
 	get_rfc3526_prime_8192.3 \
 	i2d_PKCS7_bio_stream.3 \
diff --git a/lib/libcrypto/man/engine.3 b/lib/libcrypto/man/engine.3
deleted file mode 100644
index ebcc95f3102..00000000000
--- a/lib/libcrypto/man/engine.3
+++ /dev/null
@@ -1,535 +0,0 @@
-.\" $OpenBSD: engine.3,v 1.16 2018/04/15 17:02:03 schwarze Exp $
-.\" full merge up to: OpenSSL crypto/engine e6390aca Jul 21 10:06:03 2015 -0400
-.\" selective merge up to: man3/ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
-.\"
-.\" This file was written by Geoff Thorpe <geoff@openssl.org>
-.\" with contributions from Paul Yang <yang.yang@baishancloud.com>.
-.\" Copyright (c) 2002, 2004, 2007, 2015, 2017 The OpenSSL Project.
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\"
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in
-.\"    the documentation and/or other materials provided with the
-.\"    distribution.
-.\"
-.\" 3. All advertising materials mentioning features or use of this
-.\"    software must display the following acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
-.\"
-.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
-.\"    endorse or promote products derived from this software without
-.\"    prior written permission. For written permission, please contact
-.\"    openssl-core@openssl.org.
-.\"
-.\" 5. Products derived from this software may not be called "OpenSSL"
-.\"    nor may "OpenSSL" appear in their names without prior written
-.\"    permission of the OpenSSL Project.
-.\"
-.\" 6. Redistributions of any form whatsoever must retain the following
-.\"    acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
-.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
-.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-.\" OF THE POSSIBILITY OF SUCH DAMAGE.
-.\"
-.Dd $Mdocdate: April 15 2018 $
-.Dt ENGINE 3
-.Os
-.Sh NAME
-.Nm engine
-.Nd ENGINE cryptographic module support
-.Sh DESCRIPTION
-These functions create, manipulate, and use cryptographic modules
-in the form of
-.Vt ENGINE
-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
-.Vt ENGINE
-implementation includes the following abstractions:
-.Pp
-.Bl -bullet -compact
-.It
-.Vt RSA_METHOD :
-for providing alternative RSA implementations
-.It
-.Vt DSA_METHOD , DH_METHOD , RAND_METHOD , ECDH_METHOD ,
-.Vt ECDSA_METHOD , STORE_METHOD :
-similarly for other OpenSSL APIs
-.It
-.Vt EVP_CIPHER :
-potentially multiple cipher algorithms (indexed by 'nid')
-.It
-.Vt EVP_DIGEST :
-potentially multiple hash algorithms (indexed by 'nid')
-.It
-key-loading: loading public and/or private EVP_PKEY keys
-.El
-.Ss Reference counting and handles
-Due to the modular nature of the
-.Nm engine
-API, pointers to
-.Vt ENGINE Ns s
-need to be treated as handles - i.e. not only as pointers, but also
-as references to the underlying
-.Vt ENGINE
-object.
-One should obtain a new reference when making copies of an
-.Vt ENGINE
-pointer if the copies will be used (and released) independently.
-.Pp
-.Vt ENGINE
-objects have two levels of reference-counting to match the way in
-which the objects are used.
-At the most basic level, each
-.Vt ENGINE
-pointer is inherently a
-.Sy structural
-reference - a structural reference is required to use the pointer value
-at all, as this kind of reference is a guarantee that the structure cannot
-be deallocated until the reference is released.
-.Pp
-However, a structural reference provides no guarantee that the
-.Vt ENGINE
-is initialised and able to use any of its cryptographic implementations.
-Indeed it's quite possible that most
-.Vt ENGINE Ns s
-will not initialise at all in typical environments, as
-.Vt ENGINE Ns s
-are typically used to support specialised hardware.
-To use an
-.Vt ENGINE Ap s
-functionality, you need a
-.Sy functional
-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 independently.
-If you have a functional reference to an
-.Vt ENGINE ,
-you have a guarantee that the
-.Vt ENGINE
-has been initialised and is ready to perform cryptographic operations and
-will remain uninitialised until after you have released your
-reference.
-.Pp
-.Em Structural references
-.Pp
-This basic type of reference is used for instantiating new
-.Vt ENGINE Ns s ,
-iterating across OpenSSL's internal linked-list of loaded
-.Vt ENGINE Ns s ,
-reading information about an
-.Vt ENGINE ,
-etc.
-Essentially a structural reference is sufficient if you only need to
-query or manipulate the data of an
-.Vt ENGINE
-implementation rather than use its functionality.
-.Ss Application requirements
-This section will explain the basic things an application programmer
-should support to make the most useful elements of the
-.Nm engine
-functionality available to the user.
-The first thing to consider is whether the programmer wishes to make
-alternative
-.Vt ENGINE
-modules available to the application and user.
-OpenSSL maintains an internal linked list of "visible"
-.Vt ENGINE Ns s
-from which it has to operate.
-At start-up, this list is empty, and in fact if an application does
-not call any
-.Nm engine
-API calls and it uses static
-linking against openssl, then the resulting application binary will
-not contain any alternative
-.Nm engine
-code at all.
-So the first consideration is whether any/all available
-.Vt ENGINE
-implementations should be made visible to OpenSSL.
-.Pp
-Having called any of these functions,
-.Vt ENGINE
-objects would have been dynamically allocated and populated with
-these implementations and linked into OpenSSL's internal linked
-list.
-.Pp
-The fact that
-.Vt ENGINE Ns s
-are made visible to OpenSSL (and thus are linked into the program
-and loaded into memory at run-time) does not mean they are "registered"
-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
-.Vt ENGINE
-they want used if any is to be used at all.
-Others may prefer to load all support and have OpenSSL automatically use
-at run-time any
-.Vt ENGINE
-that is able to successfully initialised - i.e. to assume that this
-corresponds to acceleration hardware attached to the machine or
-some such thing.
-There are probably numerous other ways in which applications may prefer
-to handle 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
-.Em Using a specific ENGINE implementation
-.Pp
-Here we'll assume an application has been configured by its user or
-admin to want to use the "ACME"
-.Vt ENGINE
-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 RSA, DSA, and
-symmetric cipher operations, otherwise OpenSSL should use its builtin
-software as usual.
-The following code illustrates how to approach this:
-.Bd -literal
-ENGINE *e;
-const char *engine_id = "ACME";
-ENGINE_load_builtin_engines();
-e = ENGINE_by_id(engine_id);
-if (!e)
-	/* the engine isn't available */
-	return;
-if (!ENGINE_init(e)) {
-	/* the engine couldn't initialise, release 'e' */
-	ENGINE_free(e);
-	return;
-}
-if (!ENGINE_set_default_RSA(e))
-	/* This should only happen when 'e' can't initialise, but the previous
-	 * statement suggests it did. */
-	abort();
-ENGINE_set_default_DSA(e);
-ENGINE_set_default_ciphers(e);
-/* Release the functional reference from ENGINE_init() */
-ENGINE_finish(e);
-/* Release the structural reference from ENGINE_by_id() */
-ENGINE_free(e);
-.Ed
-.Pp
-.Em Automatically using builtin ENGINE implementations
-.Pp
-Here we'll assume we want to load and register all
-.Vt ENGINE
-implementations bundled with OpenSSL, such that for any cryptographic
-algorithm required by OpenSSL - if there is an
-.Vt ENGINE
-that implements it and can be initialised, it should be used.
-The following code illustrates how this can work;
-.Bd -literal
-/* Load all bundled ENGINEs into memory and make them visible */
-ENGINE_load_builtin_engines();
-/* Register all of them for every algorithm they collectively implement */
-ENGINE_register_all_complete();
-.Ed
-.Pp
-That's all that's required.
-For example, the next time OpenSSL tries to set up an RSA key, any bundled
-.Vt ENGINE Ns s
-that implement
-.Vt RSA_METHOD
-will be passed to
-.Xr ENGINE_init 3
-and if any of those succeed, that
-.Vt ENGINE
-will be set as the default for RSA use from then on.
-.Ss Advanced configuration support
-There is a mechanism supported by the
-.Nm engine
-framework that allows each
-.Vt ENGINE
-implementation to define an arbitrary set of configuration
-"commands" and expose them to OpenSSL and any applications based on
-OpenSSL.
-This mechanism is entirely based on the use of name-value pairs
-and assumes ASCII input (no unicode or UTF for now!), so it is ideal if
-applications want to provide a transparent way for users to provide
-arbitrary configuration "directives" directly to such
-.Vt ENGINE Ns s .
-It is also possible for the application to dynamically interrogate the
-loaded
-.Vt ENGINE
-implementations for the names, descriptions, and input flags of
-their available "control commands", providing a more flexible
-configuration scheme.
-However, if the user is expected to know which
-.Vt ENGINE
-device he/she is using (in the case of specialised hardware, this
-goes without saying) then applications may not need to concern
-themselves with discovering the supported control commands and
-simply prefer to pass settings into
-.Vt ENGINE s
-exactly as they are provided by the user.
-.Pp
-Before illustrating how control commands work, it is worth mentioning
-what they are typically used for.
-Broadly speaking there are two uses for control commands; the first is
-to provide the necessary details to the implementation (which may know
-nothing at all specific to the host system) 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.
-This class of commands typically needs to be passed to an
-.Vt ENGINE
-.Sy before
-attempting to initialise it, i.e. before calling
-.Xr ENGINE_init 3 .
-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
-.Xr ENGINE_init 3 ,
-or in some cases both.
-.Vt ENGINE
-implementations should provide indications of this in the descriptions
-attached to builtin control commands and/or in external product
-documentation.
-.Pp
-.Em Issuing control commands to an ENGINE
-.Pp
-Let's illustrate by example; a function for which the caller supplies
-the name of the
-.Vt ENGINE
-it wishes to use, a table of string-pairs for use before initialisation,
-and another table for use after initialisation.
-Note that the string-pairs used for control commands consist of a
-command "name" followed by the command "parameter" - the parameter
-could be
-.Dv NULL
-in some cases but the name cannot.
-This function should initialise the
-.Vt ENGINE
-(issuing the "pre" commands beforehand and the "post" commands
-afterwards) and set it as the default for everything except RAND
-and then return a boolean success or failure.
-.Bd -literal
-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--) {
-		if (!ENGINE_ctrl_cmd_string(e,
-		    pre_cmds[0], pre_cmds[1], 0)) {
-			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;
-		}
-		pre_cmds += 2;
-	}
-	if (!ENGINE_init(e)) {
-		fprintf(stderr, "Failed initialisation\en");
-		ENGINE_free(e);
-		return 0;
-	}
-	/*
-	 * ENGINE_init() returned a functional reference,
-	 * so free the structural reference from
-	 * ENGINE_by_id().
-	 */
-	ENGINE_free(e);
-	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, post_cmds[0],
-			    post_cmds[1] ? post_cmds[1] : "(NULL)");
-			ENGINE_finish(e);
-			return 0;
-		}
-		post_cmds += 2;
-	}
-	ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
-	/* Success */
-	return 1;
-}
-.Ed
-.Pp
-Note that
-.Fn ENGINE_ctrl_cmd_string
-accepts a boolean argument that can relax the semantics of the function.
-If set to non-zero it will only return failure if the
-.Vt ENGINE
-supported the given command name but failed while executing it, if the
-.Vt ENGINE
-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
-.Vt ENGINE
-so we set this to FALSE.
-.Pp
-.Em Discovering supported control commands
-.Pp
-It is possible to discover at run-time the names, numerical-ids,
-descriptions and input parameters of the control commands supported by an
-.Vt ENGINE
-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
-.Vt ENGINE ,
-i.e. the
-.Vt ENGINE Ap s
-ctrl() handler is not used for the control command.
-.In openssl/engine.h
-defines an index,
-.Dv ENGINE_CMD_BASE ,
-that all control commands implemented by
-.Vt ENGINE Ns s
-should be numbered from.
-Any command value lower than this symbol is considered a "generic"
-command is handled directly by the OpenSSL core routines.
-.Pp
-It is using these "core" control commands that one can discover the
-control commands implemented by a given
-.Vt ENGINE ,
-specifically the commands:
-.Bd -literal
-#define ENGINE_HAS_CTRL_FUNCTION		10
-#define ENGINE_CTRL_GET_FIRST_CMD_TYPE		11
-#define ENGINE_CTRL_GET_NEXT_CMD_TYPE		12
-#define ENGINE_CTRL_GET_CMD_FROM_NAME		13
-#define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD	14
-#define ENGINE_CTRL_GET_NAME_FROM_CMD		15
-#define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD	16
-#define ENGINE_CTRL_GET_DESC_FROM_CMD		17
-#define ENGINE_CTRL_GET_CMD_FLAGS		18
-.Ed
-.Pp
-Whilst these commands are automatically processed by the OpenSSL
-framework code, they use various properties exposed by each
-.Vt ENGINE
-to process these queries.
-An
-.Vt ENGINE
-has 3 properties it exposes that can affect how this behaves;
-it can supply a ctrl() handler, it can specify
-.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
-in the
-.Vt ENGINE Ap s
-flags, and it can expose an array of control command descriptions.
-If an
-.Vt ENGINE
-specifies the
-.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
-flag, then it will simply pass all these "core" control commands
-directly to the
-.Vt ENGINE Ap s
-ctrl() handler (and thus, it must have supplied one), so it is up
-to the
-.Vt ENGINE
-to reply to these "discovery" commands itself.
-If that flag is not set, then the OpenSSL framework code will work with
-the following rules;
-.Bl -tag -width Ds
-.It If no ctrl() handler is supplied:
-.Dv ENGINE_HAS_CTRL_FUNCTION
-returns FALSE (zero), all other commands fail.
-.It If a ctrl() handler was supplied but no array of control commands:
-.Dv ENGINE_HAS_CTRL_FUNCTION
-returns TRUE, all other commands fail.
-.It If a ctrl() handler and array of control commands was supplied:
-.Dv ENGINE_HAS_CTRL_FUNCTION
-returns TRUE, all other commands proceed processing...
-.El
-.Pp
-If the
-.Vt ENGINE Ns s
-array of control commands is empty, then all other commands will fail.
-Otherwise
-.Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE
-returns the identifier of the first command supported by the
-.Vt ENGINE ,
-.Dv ENGINE_GET_NEXT_CMD_TYPE
-takes the identifier of a command supported by the
-.Vt ENGINE
-and returns the next command identifier or fails if there are no more,
-.Dv ENGINE_CMD_FROM_NAME
-takes a string 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
-.Dv ENGINE_CTRL_GET_FLAGS
-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.
-.Dv ENGINE_CTRL_GET_FLAGS
-returns a bitwise-OR'd mask of the following possible values:
-.Bd -literal
-#define ENGINE_CMD_FLAG_NUMERIC		(unsigned int)0x0001
-#define ENGINE_CMD_FLAG_STRING		(unsigned int)0x0002
-#define ENGINE_CMD_FLAG_NO_INPUT	(unsigned int)0x0004
-#define ENGINE_CMD_FLAG_INTERNAL	(unsigned int)0x0008
-.Ed
-.Pp
-If the
-.Dv ENGINE_CMD_FLAG_INTERNAL
-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
-.Vt ENGINE
-functions such as
-.Fn ENGINE_ctrl_cmd_string .
-"INTERNAL" commands are not intended to be exposed to text-based
-configuration by applications, administrations, users, etc.
-These can support arbitrary operations via
-.Fn ENGINE_ctrl ,
-including passing to and/or from the control commands data of any
-arbitrary type.
-These commands are supported in the discovery mechanisms simply allow
-applications to determine if an
-.Vt ENGINE
-supports certain specific commands it might want to use (e.g.
-application "foo" might query various
-.Vt ENGINE Ns s
-to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - and
-.Vt ENGINE
-could therefore decide whether or not to support this "foo"-specific
-extension).
-.Sh SEE ALSO
-.Xr DH_new 3 ,
-.Xr DSA_new 3 ,
-.Xr ENGINE_add_conf_module 3 ,
-.Xr ENGINE_set_ex_data 3 ,
-.Xr RSA_new 3
-.Sh HISTORY
-The engine API first appeared in OpenSSL 0.9.7
-and has been available since
-.Ox 3.2 .