Rewrite the ENGINE_*(3) documentation from scratch - step 2,

covering the remaining functions that were documented in engine(3),
except for seven functions that are completely pointless and that
were merely listed but not really documented.

8 files changed, 633 insertions, 395 deletions

diff --git a/src/lib/libcrypto/man/ENGINE_add.3 b/src/lib/libcrypto/man/ENGINE_add.3
index faecb8a2ab..c54fa5cf05 100644
--- a/src/lib/libcrypto/man/ENGINE_add.3
+++ b/src/lib/libcrypto/man/ENGINE_add.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ENGINE_add.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $
+.\" $OpenBSD: ENGINE_add.3,v 1.2 2018/04/15 17:02:03 schwarze Exp $
 .\" content checked up to: OpenSSL 1f13ad31 Dec 25 17:50:39 2017 +0800
 .\"
 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -20,7 +20,12 @@
 .Os
 .Sh NAME
 .Nm ENGINE_add ,
+.Nm ENGINE_set_id ,
+.Nm ENGINE_get_id ,
+.Nm ENGINE_set_name ,
+.Nm ENGINE_get_name ,
 .Nm ENGINE_remove ,
+.Nm ENGINE_cleanup ,
 .Nm ENGINE_get_first ,
 .Nm ENGINE_get_last ,
 .Nm ENGINE_get_next ,
@@ -34,9 +39,29 @@
 .Fa "ENGINE *e"
 .Fc
 .Ft int
+.Fo ENGINE_set_id
+.Fa "ENGINE *e"
+.Fa "const char *id"
+.Fc
+.Ft const char *
+.Fo ENGINE_get_id
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_name
+.Fa "ENGINE *e"
+.Fa "const char *name"
+.Fc
+.Ft const char *
+.Fo ENGINE_get_name
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
 .Fo ENGINE_remove
 .Fa "ENGINE *e"
 .Fc
+.Ft void
+.Fn ENGINE_cleanup void
 .Ft ENGINE *
 .Fn ENGINE_get_first void
 .Ft ENGINE *
@@ -63,12 +88,12 @@ appends
 .Fa e
 to the end of the list
 and increments its structural reference count by 1.
-The name and identifier of
+A unique identifier and a name of
 .Fa e
 have to be set with
-.Xr ENGINE_set_name 3
+.Fn ENGINE_set_id
 and
-.Xr ENGINE_set_id 3
+.Fn ENGINE_set_name
 before calling this function.
 .Fn ENGINE_add
 fails if the list already contains an
@@ -84,6 +109,26 @@ If successful, it calls
 on
 .Fa e .
 .Pp
+.Fn ENGINE_cleanup
+calls
+.Xr ENGINE_finish 3
+on all
+.Vt ENGINE
+objects that were selected as default engines, for example using the
+functions documented in the
+.Xr ENGINE_set_default 3
+and
+.Xr ENGINE_get_default_RSA 3
+manual pages, and it calls
+.Fn ENGINE_remove
+on all
+.Vt ENGINE
+objects that were added to the global list with
+.Fn ENGINE_add .
+Calling this function is required at the end of each program using
+.Fn ENGINE_add ,
+even if no engines are explicitly registered or used.
+.Pp
 .Fn ENGINE_get_first
 and
 .Fn ENGINE_get_last
@@ -109,13 +154,40 @@ searches the list for an
 .Vt ENGINE
 object with a matching
 .Fa id .
-If found, it increments  the structural reference count of the
+If found, it increments the structural reference count of the
 retrieved object by 1.
+If
+.Dv ENGINE_FLAGS_BY_ID_COPY
+was set on
+.Fa e
+with
+.Xr ENGINE_set_flags 3 ,
+it returns a shallow copy of the object rather than incrementing
+the reference count and returning a pointer to the original.
 .Sh RETURN VALUES
-.Fn ENGINE_add
+.Fn ENGINE_add ,
+.Fn ENGINE_set_id ,
+.Fn ENGINE_set_name ,
 and
 .Fn ENGINE_remove
 return 1 on success or 0 on error.
+.Fn ENGINE_set_id
+and
+.Fn ENGINE_set_name
+can only fail if the supplied
+.Fa id
+or
+.Fa name
+is
+.Dv NULL .
+.Pp
+.Fn ENGINE_get_id
+and
+.Fn ENGINE_get_name
+return a pointer to an internal string
+representing the identifier and the name of
+.Fa e ,
+respectively.
 .Pp
 .Fn ENGINE_get_first
 and
diff --git a/src/lib/libcrypto/man/ENGINE_new.3 b/src/lib/libcrypto/man/ENGINE_new.3
new file mode 100644
index 0000000000..ab875ce662
--- /dev/null
+++ b/src/lib/libcrypto/man/ENGINE_new.3
@@ -0,0 +1,154 @@
+.\" $OpenBSD: ENGINE_new.3,v 1.1 2018/04/15 17:02:03 schwarze Exp $
+.\" content checked up to:
+.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
+.\"
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 15 2018 $
+.Dt ENGINE_NEW 3
+.Os
+.Sh NAME
+.Nm ENGINE_new ,
+.Nm ENGINE_up_ref ,
+.Nm ENGINE_free ,
+.Nm ENGINE_set_destroy_function ,
+.Nm ENGINE_get_destroy_function
+.Nd create and destroy ENGINE objects
+.Sh SYNOPSIS
+.In openssl/engine.h
+.Ft ENGINE *
+.Fn ENGINE_new void
+.Ft int
+.Fo ENGINE_up_ref
+.Fa "ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_free
+.Fa "ENGINE *e"
+.Fc
+.Ft typedef int
+.Fo (*ENGINE_GEN_INT_FUNC_PTR)
+.Fa "ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_destroy_function
+.Fa "ENGINE *e"
+.Fa "ENGINE_GEN_INT_FUNC_PTR destroy_f"
+.Fc
+.Ft ENGINE_GEN_INT_FUNC_PTR
+.Fo ENGINE_get_destroy_function
+.Fa "const ENGINE *e"
+.Fc
+.Sh DESCRIPTION
+.Fn ENGINE_new
+allocates and initializes an empty
+.Vt ENGINE
+object and sets its structural reference count to 1
+and its functional reference count to 0.
+For more information about the functional reference count, see the
+.Xr ENGINE_init 3
+manual page.
+.Pp
+Many functions increment the structural reference count by 1
+when successful.
+Some of them, including
+.Xr ENGINE_get_first 3 ,
+.Xr ENGINE_get_last 3 ,
+.Xr ENGINE_get_next 3 ,
+.Xr ENGINE_get_prev 3 ,
+and
+.Xr ENGINE_by_id 3 ,
+do so because they return a structural reference to the user.
+Other functions, including
+.Xr ENGINE_add 3 ,
+.Xr ENGINE_init 3 ,
+.Xr ENGINE_get_cipher_engine 3 ,
+.Xr ENGINE_get_digest_engine 3 ,
+and the
+.Xr ENGINE_get_default_RSA 3
+and
+.Xr ENGINE_set_default 3
+families of functions
+do so when they store a structural refence internally.
+.Pp
+.Fn ENGINE_up_ref
+explicitly increment the structural reference count by 1.
+.Pp
+.Fn ENGINE_free
+decrements the structural reference count by 1,
+and if it reaches 0, the optional
+.Fa destroy_f
+previously installed with
+.Fn ENGINE_set_destroy_function
+is called, if one is installed, and both the memory used internally by
+.Fa e
+and
+.Fa e
+itself are freed.
+If
+.Fa e
+is a
+.Dv NULL
+pointer, no action occurs.
+.Pp
+Many functions internally call the equivalent of
+.Fn ENGINE_free .
+Some of them, including
+.Xr ENGINE_get_next 3
+and
+.Xr ENGINE_get_prev 3 ,
+thus invalidate the structural reference passed in by the user.
+Other functions, including
+.Xr ENGINE_finish 3 ,
+.Xr ENGINE_remove 3 ,
+and the
+.Xr ENGINE_set_default 3
+family of functions
+do so when an internally stored structural reference is no longer needed.
+.Pp
+.Fn ENGINE_set_destroy_function
+installs a callback function that will be called by
+.Fn ENGINE_free ,
+but only when
+.Fa e
+actually gets destroyed,
+not when only its reference count gets decremented.
+The value returned from the
+.Fa destroy_f
+will be ignored.
+.Sh RETURN VALUES
+.Fn ENGINE_new
+returns a structural reference to the new
+.Vt ENGINE
+object or
+.Dv NULL
+if an error occurs.
+.Pp
+.Fn ENGINE_up_ref
+returns 0 if
+.Fa e
+is
+.Dv NULL
+and 1 otherwise.
+.Pp
+.Fn ENGINE_free
+and
+.Fn ENGINE_set_destroy_function
+always return 1.
+.Pp
+.Fn ENGINE_get_destroy_function
+returns a function pointer to the callback, or
+.Dv NULL
+if none is installed.
diff --git a/src/lib/libcrypto/man/ENGINE_register_all_RSA.3 b/src/lib/libcrypto/man/ENGINE_register_all_RSA.3
index f92a12b2f9..cb9a41f2a9 100644
--- a/src/lib/libcrypto/man/ENGINE_register_all_RSA.3
+++ b/src/lib/libcrypto/man/ENGINE_register_all_RSA.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ENGINE_register_all_RSA.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $
+.\" $OpenBSD: ENGINE_register_all_RSA.3,v 1.2 2018/04/15 17:02:03 schwarze Exp $
 .\" content checked up to:
 .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
 .\"
@@ -29,7 +29,9 @@
 .Nm ENGINE_register_all_STORE ,
 .Nm ENGINE_register_all_ciphers ,
 .Nm ENGINE_register_all_digests ,
-.Nm ENGINE_register_all_complete
+.Nm ENGINE_register_all_complete ,
+.Nm ENGINE_load_builtin_engines ,
+.Nm ENGINE_load_dynamic
 .Nd register all engines as implementing an algorithm
 .Sh SYNOPSIS
 .In openssl/engine.h
@@ -53,6 +55,10 @@
 .Fn ENGINE_register_all_digests void
 .Ft int
 .Fn ENGINE_register_all_complete void
+.Ft void
+.Fn ENGINE_load_builtin_engines void
+.Ft void
+.Fn ENGINE_load_dynamic void
 .Sh DESCRIPTION
 These functions loop over all the
 .Vt ENGINE
@@ -70,4 +76,21 @@ in this way, except that it skips those
 .Vt ENGINE
 objects that have the
 .Dv ENGINE_FLAGS_NO_REGISTER_ALL
-flag set.
+flag set with
+.Xr ENGINE_set_flags 3 .
+.Pp
+.Fn ENGINE_load_builtin_engines
+calls
+.Xr OPENSSL_init_crypto 3
+with no options, loads any built-in engines
+that are enabled by default, and calls
+.Fn ENGINE_register_all_complete .
+Currently, LibreSSL does not provide any engines.
+.Sy GOST
+and
+.Sy aesni
+support is provided by the crypto library itself
+and does not require any engines, not even built-in ones.
+.Pp
+.Fn ENGINE_load_dynamic
+has no effect and is only provided for compatibility.
diff --git a/src/lib/libcrypto/man/ENGINE_set_RSA.3 b/src/lib/libcrypto/man/ENGINE_set_RSA.3
new file mode 100644
index 0000000000..d795f55c72
--- /dev/null
+++ b/src/lib/libcrypto/man/ENGINE_set_RSA.3
@@ -0,0 +1,288 @@
+.\" $OpenBSD: ENGINE_set_RSA.3,v 1.1 2018/04/15 17:02:03 schwarze Exp $
+.\" content checked up to:
+.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
+.\"
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 15 2018 $
+.Dt ENGINE_SET_RSA 3
+.Os
+.Sh NAME
+.Nm ENGINE_set_RSA ,
+.Nm ENGINE_get_RSA ,
+.Nm ENGINE_set_DSA ,
+.Nm ENGINE_get_DSA ,
+.Nm ENGINE_set_ECDH ,
+.Nm ENGINE_get_ECDH ,
+.Nm ENGINE_set_ECDSA ,
+.Nm ENGINE_get_ECDSA ,
+.Nm ENGINE_set_DH ,
+.Nm ENGINE_get_DH ,
+.Nm ENGINE_set_RAND ,
+.Nm ENGINE_get_RAND ,
+.Nm ENGINE_set_STORE ,
+.Nm ENGINE_get_STORE ,
+.Nm ENGINE_set_ciphers ,
+.Nm ENGINE_get_ciphers ,
+.Nm ENGINE_get_cipher ,
+.Nm ENGINE_set_digests ,
+.Nm ENGINE_get_digests ,
+.Nm ENGINE_get_digest
+.Nd install and retrieve function tables of crypto engines
+.Sh SYNOPSIS
+.In openssl/engine.h
+.Ft int
+.Fo ENGINE_set_RSA
+.Fa "ENGINE *e"
+.Fa "const RSA_METHOD *rsa_meth"
+.Fc
+.Ft const RSA_METHOD *
+.Fo ENGINE_get_RSA
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_DSA
+.Fa "ENGINE *e"
+.Fa "const DSA_METHOD *dsa_meth"
+.Fc
+.Ft const DSA_METHOD *
+.Fo ENGINE_get_DSA
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_ECDH
+.Fa "ENGINE *e"
+.Fa "const ECDH_METHOD *dh_meth"
+.Fc
+.Ft const ECDH_METHOD *
+.Fo ENGINE_get_ECDH
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_ECDSA
+.Fa "ENGINE *e"
+.Fa "const ECDSA_METHOD *dh_meth"
+.Fc
+.Ft const ECDSA_METHOD *
+.Fo ENGINE_get_ECDSA
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_DH
+.Fa "ENGINE *e"
+.Fa "const DH_METHOD *dh_meth"
+.Fc
+.Ft const DH_METHOD *
+.Fo ENGINE_get_DH
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_RAND
+.Fa "ENGINE *e"
+.Fa "const RAND_METHOD *rand_meth"
+.Fc
+.Ft const RAND_METHOD *
+.Fo ENGINE_get_RAND
+.Fa "const ENGINE *e"
+.Fc
+.Ft int
+.Fo ENGINE_set_STORE
+.Fa "ENGINE *e"
+.Fa "const STORE_METHOD *rand_meth"
+.Fc
+.Ft const STORE_METHOD *
+.Fo ENGINE_get_STORE
+.Fa "const ENGINE *e"
+.Fc
+.Ft typedef int
+.Fo (*ENGINE_CIPHERS_PTR)
+.Fa "ENGINE *e"
+.Fa "const EVP_CIPHER **impl"
+.Fa "const int **nids"
+.Fa "int nid"
+.Fc
+.Ft int
+.Fo ENGINE_set_ciphers
+.Fa "ENGINE *e"
+.Fa "ENGINE_CIPHERS_PTR f"
+.Fc
+.Ft ENGINE_CIPHERS_PTR
+.Fo ENGINE_get_ciphers
+.Fa "const ENGINE *e"
+.Fc
+.Ft const EVP_CIPHER *
+.Fo ENGINE_get_cipher
+.Fa "ENGINE *e"
+.Fa "int nid"
+.Fc
+.Ft typedef int
+.Fo (*ENGINE_DIGESTS_PTR)
+.Fa "ENGINE *e"
+.Fa "const EVP_MD **impl"
+.Fa "const int **nids"
+.Fa "int nid"
+.Fc
+.Ft int
+.Fo ENGINE_set_digests
+.Fa "ENGINE *e"
+.Fa "ENGINE_DIGESTS_PTR f"
+.Fc
+.Ft ENGINE_DIGESTS_PTR
+.Fo ENGINE_get_digests
+.Fa "const ENGINE *e"
+.Fc
+.Ft const EVP_MD *
+.Fo ENGINE_get_digest
+.Fa "ENGINE *e"
+.Fa "int nid"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn ENGINE_set_*
+functions install a table of function pointers
+implementing the respective algorithm in
+.Fa e .
+Partial information about the various method objects is available from
+.Xr RSA_meth_new 3 ,
+.Xr RSA_get_default_method 3 ,
+.Xr DSA_meth_new 3 ,
+.Xr DSA_get_default_method 3 ,
+.Fn ECDH_get_default_method ,
+.Xr ECDSA_get_default_method 3 ,
+.Xr DH_get_default_method 3 ,
+.Xr RAND_get_rand_method 3 ,
+.Xr EVP_get_cipherbynid 3 ,
+and
+.Xr EVP_get_digestbynid 3 .
+.Vt STORE_METHOD
+is an incomplete type, and the pointers to it are not used for anything.
+For complete descriptions of these types,
+refer to the respective header files.
+.Pp
+The functions described in the
+.Xr ENGINE_register_RSA 3
+and
+.Xr ENGINE_set_default 3
+manual pages only have an effect after function pointers
+were installed using the functions decribed here.
+.Pp
+.Fn ENGINE_set_ciphers
+and
+.Fn ENGINE_set_digests
+are special in so far as the
+.Vt ENGINE
+structure does not provide fields to store function pointers
+implementing ciphers or digests.
+Instead, these two functions only install a callback to
+retrieve implementations.
+Where the pointers to the implementations are stored internally,
+how they get initialized, and how the
+.Vt ENGINE_CIPHERS_PTR
+and
+.Vt ENGINE_DIGESTS_PTR
+callbacks retrieve them
+is up to the implementation of each individual engine.
+.Pp
+If the
+.Vt ENGINE_CIPHERS_PTR
+and
+.Vt ENGINE_DIGESTS_PTR
+callbacks are called with a non-zero
+.Fa nid ,
+they retrieve the implementation of that cipher or digest,
+respectively.
+In this case, a
+.Dv NULL
+pointer can be passed as the
+.Fa nids
+argument.
+.Fn ENGINE_get_cipher
+and
+.Fn ENGINE_get_digest
+call the callbacks installed in
+.Fa e
+in this way.
+.Pp
+If 0 is passed as the
+.Fa nid
+argument, an internal pointer
+to the array of implementations available in
+.Fa e
+is returned in
+.Pf * Fa impl ,
+and an internal pointer
+to the array of corresponding identifiers in
+.Pf * Fa nids .
+The return value of the callback indicates
+the number of implementations returned.
+.Pp
+The
+.Fn ENGINE_get_*
+functions retrieve the previously installed function tables.
+They are used when constructing basic cryptographic objects
+as shown in the following table:
+.Bl -column "ENGINE_get_digestMM"
+.It Accessor: Ta Called by:
+.It Fn ENGINE_get_RSA Ta Xr RSA_new_method 3 , Xr RSA_new 3
+.It Fn ENGINE_get_DSA Ta Xr DSA_new_method 3 , Xr DSA_new 3
+.It Fn ENGINE_get_ECDH Ta Fn ECDH_set_method , Fn ECDH_compute_key
+.It Fn ENGINE_get_ECDSA Ta Xr ECDSA_set_method 3 , Xr ECDSA_sign_setup 3 ,
+.Xr ECDSA_do_sign_ex 3 , Xr ECDSA_do_verify 3
+.It Fn ENGINE_get_DH Ta Xr DH_new_method 3 , Xr DH_new 3
+.It Fn ENGINE_get_RAND Ta unused
+.It Fn ENGINE_get_STORE Ta unused
+.It Fn ENGINE_get_cipher Ta Xr EVP_CipherInit_ex 3
+.It Fn ENGINE_get_digest Ta Xr EVP_DigestInit_ex 3
+.El
+.Sh RETURN VALUES
+The
+.Fn ENGINE_set_*
+functions return 1 on success or 0 on error.
+Currently, they cannot fail.
+.Pp
+The
+.Fn ENGINE_get_*
+functions return a method object for the respective algorithm, or
+.Dv NULL
+if none is installed.
+.Pp
+.Fn ENGINE_get_ciphers
+and
+.Fn ENGINE_get_digests
+return a function pointer to the respective callback, or
+.Dv NULL
+if none is installed.
+.Pp
+.Fn ENGINE_get_cipher
+returns an
+.Vt EVP_CIPHER
+object implementing the cipher
+.Fa nid
+or
+.Dv NULL
+if
+.Fa e
+does not implement that cipher.
+.Pp
+.Fn ENGINE_get_digest
+returns an
+.Vt EVP_MD
+object implementing the digest
+.Fa nid
+or
+.Dv NULL
+if
+.Fa e
+does not implement that digest.
diff --git a/src/lib/libcrypto/man/ENGINE_set_flags.3 b/src/lib/libcrypto/man/ENGINE_set_flags.3
new file mode 100644
index 0000000000..a4ac107f9e
--- /dev/null
+++ b/src/lib/libcrypto/man/ENGINE_set_flags.3
@@ -0,0 +1,79 @@
+.\" $OpenBSD: ENGINE_set_flags.3,v 1.1 2018/04/15 17:02:03 schwarze Exp $
+.\" content checked up to: 
+.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
+.\"
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 15 2018 $
+.Dt ENGINE_SET_FLAGS 3
+.Os
+.Sh NAME
+.Nm ENGINE_set_flags ,
+.Nm ENGINE_get_flags
+.Nd modify the behaviour of an ENGINE object
+.Sh SYNOPSIS
+.In openssl/engine.h
+.Ft int
+.Fo ENGINE_set_flags
+.Fa "ENGINE *e"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo ENGINE_get_flags
+.Fa "const ENGINE *e"
+.Fc
+.Sh DESCRIPTION
+.Fn ENGINE_set_flags
+sets the flags attribute of
+.Fa e
+to the new
+.Fa flags .
+The previous state of the flags attribute is overwritten.
+Flags that were previously set are cleared
+unless they are also present in the new
+.Fa flags .
+.Pp
+The
+.Fa flags
+argument can be the bitwise OR of zero or more
+of the following constants:
+.Bl -tag -width Ds
+.It Dv ENGINE_FLAGS_BY_ID_COPY
+.Xr ENGINE_by_id 3
+returns a shallow copy of the
+.Vt ENGINE
+object it found rather than incrementing the reference count
+and returning a pointer to the original.
+.It Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
+.Xr ENGINE_ctrl 3
+lets the function installed with
+.Xr ENGINE_set_ctrl_function 3
+handle all commands except
+.Dv ENGINE_CTRL_HAS_CTRL_FUNCTION ,
+even the builtin commands.
+.It Dv ENGINE_FLAGS_NO_REGISTER_ALL
+.Xr ENGINE_register_all_complete 3
+skips
+.Fa e .
+.El
+.Sh RETURN VALUES
+.Fn ENGINE_set_flags
+always returns 1.
+.Pp
+.Fn ENGINE_get_flags
+returns the
+.Fa flags
+attribute of
+.Fa e .
diff --git a/src/lib/libcrypto/man/ENGINE_unregister_RSA.3 b/src/lib/libcrypto/man/ENGINE_unregister_RSA.3
index c596554e86..698bfe105d 100644
--- a/src/lib/libcrypto/man/ENGINE_unregister_RSA.3
+++ b/src/lib/libcrypto/man/ENGINE_unregister_RSA.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ENGINE_unregister_RSA.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $
+.\" $OpenBSD: ENGINE_unregister_RSA.3,v 1.2 2018/04/15 17:02:03 schwarze Exp $
 .\" content checked up to:
 .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
 .\"
@@ -85,7 +85,7 @@ as described in the
 and
 .Fn ENGINE_get_default_RSA 3
 manual pages,
-.Xr ENGINE_finish
+.Xr ENGINE_finish 3
 is also called.
 .Pp
 .Fn ENGINE_unregister_ciphers
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index a83ae5d3ed..695485aeeb 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.139 2018/04/15 01:43:45 schwarze Exp $
+# $OpenBSD: Makefile,v 1.140 2018/04/15 17:02:03 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -101,9 +101,12 @@ MAN=	\
         ENGINE_ctrl.3 \
         ENGINE_get_default_RSA.3 \
         ENGINE_init.3 \
+        ENGINE_new.3 \
         ENGINE_register_RSA.3 \
         ENGINE_register_all_RSA.3 \
+        ENGINE_set_RSA.3 \
         ENGINE_set_default.3 \
+        ENGINE_set_flags.3 \
         ENGINE_unregister_RSA.3 \
         ERR.3 \
         ERR_GET_LIB.3 \
diff --git a/src/lib/libcrypto/man/engine.3 b/src/lib/libcrypto/man/engine.3
index fac4fa13e1..ebcc95f310 100644
--- a/src/lib/libcrypto/man/engine.3
+++ b/src/lib/libcrypto/man/engine.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: engine.3,v 1.15 2018/04/15 01:43:45 schwarze Exp $
+.\" $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
 .\"
@@ -55,227 +55,8 @@
 .Dt ENGINE 3
 .Os
 .Sh NAME
-.Nm ENGINE_load_openssl ,
-.Nm ENGINE_load_dynamic ,
-.Nm ENGINE_load_builtin_engines ,
-.Nm ENGINE_cleanup ,
-.Nm ENGINE_new ,
-.Nm ENGINE_free ,
-.Nm ENGINE_up_ref ,
-.Nm ENGINE_set_id ,
-.Nm ENGINE_set_name ,
-.Nm ENGINE_set_RSA ,
-.Nm ENGINE_set_DSA ,
-.Nm ENGINE_set_ECDH ,
-.Nm ENGINE_set_ECDSA ,
-.Nm ENGINE_set_DH ,
-.Nm ENGINE_set_RAND ,
-.Nm ENGINE_set_STORE ,
-.Nm ENGINE_set_destroy_function ,
-.Nm ENGINE_set_load_privkey_function ,
-.Nm ENGINE_set_load_pubkey_function ,
-.Nm ENGINE_set_ciphers ,
-.Nm ENGINE_set_digests ,
-.Nm ENGINE_set_flags ,
-.Nm ENGINE_get_id ,
-.Nm ENGINE_get_name ,
-.Nm ENGINE_get_RSA ,
-.Nm ENGINE_get_DSA ,
-.Nm ENGINE_get_ECDH ,
-.Nm ENGINE_get_ECDSA ,
-.Nm ENGINE_get_DH ,
-.Nm ENGINE_get_RAND ,
-.Nm ENGINE_get_STORE ,
-.Nm ENGINE_get_destroy_function ,
-.Nm ENGINE_get_load_privkey_function ,
-.Nm ENGINE_get_load_pubkey_function ,
-.Nm ENGINE_get_ciphers ,
-.Nm ENGINE_get_digests ,
-.Nm ENGINE_get_cipher ,
-.Nm ENGINE_get_digest ,
-.Nm ENGINE_get_flags ,
-.Nm ENGINE_load_private_key ,
-.Nm ENGINE_load_public_key
+.Nm engine
 .Nd ENGINE cryptographic module support
-.Sh SYNOPSIS
-.In openssl/engine.h
-.Ft void
-.Fn ENGINE_load_openssl void
-.Ft void
-.Fn ENGINE_load_dynamic void
-.Ft void
-.Fn ENGINE_load_builtin_engines void
-.Ft void
-.Fn ENGINE_cleanup void
-.Ft ENGINE *
-.Fn ENGINE_new void
-.Ft int
-.Fo ENGINE_free
-.Fa "ENGINE *e"
-.Fc
-.Ft int
-.Fo ENGINE_up_ref
-.Fa "ENGINE *e"
-.Fc
-.Ft int
-.Fo ENGINE_set_id
-.Fa "ENGINE *e"
-.Fa "const char *id"
-.Fc
-.Ft int
-.Fo ENGINE_set_name
-.Fa "ENGINE *e"
-.Fa "const char *name"
-.Fc
-.Ft int
-.Fo ENGINE_set_RSA
-.Fa "ENGINE *e"
-.Fa "const RSA_METHOD *rsa_meth"
-.Fc
-.Ft int
-.Fo ENGINE_set_DSA
-.Fa "ENGINE *e"
-.Fa "const DSA_METHOD *dsa_meth"
-.Fc
-.Ft int
-.Fo ENGINE_set_ECDH
-.Fa "ENGINE *e"
-.Fa "const ECDH_METHOD *dh_meth"
-.Fc
-.Ft int
-.Fo ENGINE_set_ECDSA
-.Fa "ENGINE *e"
-.Fa "const ECDSA_METHOD *dh_meth"
-.Fc
-.Ft int
-.Fo ENGINE_set_DH
-.Fa "ENGINE *e"
-.Fa "const DH_METHOD *dh_meth"
-.Fc
-.Ft int
-.Fo ENGINE_set_RAND
-.Fa "ENGINE *e"
-.Fa "const RAND_METHOD *rand_meth"
-.Fc
-.Ft int
-.Fo ENGINE_set_STORE
-.Fa "ENGINE *e"
-.Fa "const STORE_METHOD *rand_meth"
-.Fc
-.Ft int
-.Fo ENGINE_set_destroy_function
-.Fa "ENGINE *e"
-.Fa "ENGINE_GEN_INT_FUNC_PTR destroy_f"
-.Fc
-.Ft int
-.Fo ENGINE_set_load_privkey_function
-.Fa "ENGINE *e"
-.Fa "ENGINE_LOAD_KEY_PTR loadpriv_f"
-.Fc
-.Ft int
-.Fo ENGINE_set_load_pubkey_function
-.Fa "ENGINE *e"
-.Fa "ENGINE_LOAD_KEY_PTR loadpub_f"
-.Fc
-.Ft int
-.Fo ENGINE_set_ciphers
-.Fa "ENGINE *e"
-.Fa "ENGINE_CIPHERS_PTR f"
-.Fc
-.Ft int
-.Fo ENGINE_set_digests
-.Fa "ENGINE *e"
-.Fa "ENGINE_DIGESTS_PTR f"
-.Fc
-.Ft int
-.Fo ENGINE_set_flags
-.Fa "ENGINE *e"
-.Fa "int flags"
-.Fc
-.Ft const char *
-.Fo ENGINE_get_id
-.Fa "const ENGINE *e"
-.Fc
-.Ft const char *
-.Fo ENGINE_get_name
-.Fa "const ENGINE *e"
-.Fc
-.Ft const RSA_METHOD *
-.Fo ENGINE_get_RSA
-.Fa "const ENGINE *e"
-.Fc
-.Ft const DSA_METHOD *
-.Fo ENGINE_get_DSA
-.Fa "const ENGINE *e"
-.Fc
-.Ft const ECDH_METHOD *
-.Fo ENGINE_get_ECDH
-.Fa "const ENGINE *e"
-.Fc
-.Ft const ECDSA_METHOD *
-.Fo ENGINE_get_ECDSA
-.Fa "const ENGINE *e"
-.Fc
-.Ft const DH_METHOD *
-.Fo ENGINE_get_DH
-.Fa "const ENGINE *e"
-.Fc
-.Ft const RAND_METHOD *
-.Fo ENGINE_get_RAND
-.Fa "const ENGINE *e"
-.Fc
-.Ft const STORE_METHOD *
-.Fo ENGINE_get_STORE
-.Fa "const ENGINE *e"
-.Fc
-.Ft ENGINE_GEN_INT_FUNC_PTR
-.Fo ENGINE_get_destroy_function
-.Fa "const ENGINE *e"
-.Fc
-.Ft ENGINE_LOAD_KEY_PTR
-.Fo ENGINE_get_load_privkey_function
-.Fa "const ENGINE *e"
-.Fc
-.Ft ENGINE_LOAD_KEY_PTR
-.Fo ENGINE_get_load_pubkey_function
-.Fa "const ENGINE *e"
-.Fc
-.Ft ENGINE_CIPHERS_PTR
-.Fo ENGINE_get_ciphers
-.Fa "const ENGINE *e"
-.Fc
-.Ft ENGINE_DIGESTS_PTR
-.Fo ENGINE_get_digests
-.Fa "const ENGINE *e"
-.Fc
-.Ft const EVP_CIPHER *
-.Fo ENGINE_get_cipher
-.Fa "ENGINE *e"
-.Fa "int nid"
-.Fc
-.Ft const EVP_MD *
-.Fo ENGINE_get_digest
-.Fa "ENGINE *e"
-.Fa "int nid"
-.Fc
-.Ft int
-.Fo ENGINE_get_flags
-.Fa "const ENGINE *e"
-.Fc
-.Ft EVP_PKEY *
-.Fo ENGINE_load_private_key
-.Fa "ENGINE *e"
-.Fa "const char *key_id"
-.Fa "UI_METHOD *ui_method"
-.Fa "void *callback_data"
-.Fc
-.Ft EVP_PKEY *
-.Fo ENGINE_load_public_key
-.Fa "ENGINE *e"
-.Fa "const char *key_id"
-.Fa "UI_METHOD *ui_method"
-.Fa "void *callback_data"
-.Fc
 .Sh DESCRIPTION
 These functions create, manipulate, and use cryptographic modules
 in the form of
@@ -369,64 +150,6 @@ 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.
-.Pp
-.Fn ENGINE_new
-allocates and initializes an empty
-.Vt ENGINE
-object and sets its structural reference count to 1
-and its functional reference count to 0.
-Many functions increment the structural reference count by 1
-when successful.
-Some of them, including
-.Xr ENGINE_by_id 3 ,
-.Xr ENGINE_get_first 3 ,
-.Xr ENGINE_get_last 3 ,
-.Xr ENGINE_get_next 3 ,
-and
-.Xr ENGINE_get_prev 3 ,
-do so because they return a structural reference to the user.
-Other functions, including
-.Xr ENGINE_add 3 ,
-.Xr ENGINE_init 3 ,
-.Xr ENGINE_get_cipher_engine 3 ,
-.Xr ENGINE_get_digest_engine 3 ,
-and the
-.Xr ENGINE_get_default_RSA 3
-and
-.Xr ENGINE_set_default 3
-families of functions
-do so because they store a structural refence internally.
-.Fn ENGINE_up_ref
-explicitly increment the structural reference count by 1.
-.Pp
-.Fn ENGINE_free
-decrements the structural reference count by 1,
-and if it reaches 0, the cleanup function associated with
-.Fa e
-is called, and both the memory used internally by
-.Fa e
-and
-.Fa e
-itself are freed.
-If
-.Fa e
-is a
-.Dv NULL
-pointer, no action occurs.
-Many functions internally call the equivalent of
-.Fn ENGINE_free .
-Some of them, including
-.Xr ENGINE_get_next 3
-and
-.Xr ENGINE_get_prev 3 ,
-thus invalidate the structural reference passed in by the user.
-Other functions, including
-.Xr ENGINE_finish 3 ,
-.Xr ENGINE_remove 3 ,
-and the
-.Xr ENGINE_set_default 3
-family of functions
-do so when an internally stored structural reference is no longer needed.
 .Ss Application requirements
 This section will explain the basic things an application programmer
 should support to make the most useful elements of the
@@ -450,15 +173,6 @@ code at all.
 So the first consideration is whether any/all available
 .Vt ENGINE
 implementations should be made visible to OpenSSL.
-This is controlled by calling the various "load" functions, e.g.
-.Fn ENGINE_load_builtin_engines
-to make all
-.Vt ENGINE
-implementations bundled with OpenSSL available.
-.Pp
-Note that
-.Fn ENGINE_load_dynamic
-is a placeholder and does not enable dynamic engine loading support.
 .Pp
 Having called any of these functions,
 .Vt ENGINE
@@ -466,33 +180,6 @@ objects would have been dynamically allocated and populated with
 these implementations and linked into OpenSSL's internal linked
 list.
 .Pp
-If no
-.Nm engine
-API functions are called at all in an application, then there are
-no inherent memory leaks to worry about from the
-.Nm engine
-functionality, however if any
-.Vt ENGINE Ns s
-are loaded, even if they are never registered or used, it is necessary
-to use the
-.Fn ENGINE_cleanup
-function to correspondingly cleanup before program exit, if the caller
-wishes to avoid memory leaks.
-This mechanism uses an internal callback registration table so that any
-.Nm engine
-API functionality that knows it requires cleanup can register its
-cleanup details to be called during
-.Fn ENGINE_cleanup .
-This approach allows
-.Fn ENGINE_cleanup
-to clean up after any
-.Nm engine
-functionality at all that your program uses, yet doesn't automatically
-create linker dependencies to all possible
-.Nm engine
-functionality - only the cleanup callbacks required by the functionality
-you do use will be required by the linker.
-.Pp
 The fact that
 .Vt ENGINE Ns s
 are made visible to OpenSSL (and thus are linked into the program
@@ -836,74 +523,6 @@ 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 RETURN VALUES
-.Fn ENGINE_get_cipher_engine ,
-.Fn ENGINE_get_digest_engine ,
-and
-.Fn ENGINE_new
-return a valid
-.Vt ENGINE
-structure or
-.Dv NULL
-if an error occurred.
-.Pp
-.Fn ENGINE_free ,
-.Fn ENGINE_up_ref ,
-and all
-.Fn ENGINE_set_*
-functions return 1 on success or 0 on error.
-.Pp
-.Fn ENGINE_get_id
-and
-.Fn ENGINE_get_name
-return a pointer to an internal string representing the identifier
-and the name of
-.Fa e ,
-respectively.
-.Pp
-.Fn ENGINE_get_RSA ,
-.Fn ENGINE_get_DSA ,
-.Fn ENGINE_get_DH ,
-.Fn ENGINE_get_RAND ,
-and
-.Fn ENGINE_get_STORE
-return a method structure for the respective algorithm.
-.Pp
-.Fn ENGINE_get_destroy_function ,
-.Fn ENGINE_get_load_privkey_function ,
-.Fn ENGINE_get_load_pubkey_function ,
-.Fn ENGINE_get_ciphers ,
-and
-.Fn ENGINE_get_digests
-return a function pointer to the respective callback.
-.Pp
-.Fn ENGINE_get_cipher
-returns a valid
-.Vt EVP_CIPHER
-structure on success or
-.Dv NULL
-if an error occurred.
-.Pp
-.Fn ENGINE_get_digest
-returns a valid
-.Vt EVP_MD
-structure on success or
-.Dv NULL
-if an error occurred.
-.Pp
-.Fn ENGINE_get_flags
-returns an integer representing the flags
-which are used to control various behaviours of an
-.Vt ENGINE .
-.Pp
-.Fn ENGINE_load_private_key
-and
-.Fn ENGINE_load_public_key
-return a valid
-.Vt EVP_PKEY
-structure on success or
-.Dv NULL
-if an error occurred.
 .Sh SEE ALSO
 .Xr DH_new 3 ,
 .Xr DSA_new 3 ,