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.

1 files changed, 2 insertions, 383 deletions

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 ,