add a few new sentences regarding the big picture

2 files changed, 15 insertions, 2 deletions

diff --git a/lib/libcrypto/man/ENGINE_ctrl.3 b/lib/libcrypto/man/ENGINE_ctrl.3
index 1672f2976e8..6d64b9bb85c 100644
--- a/lib/libcrypto/man/ENGINE_ctrl.3
+++ b/lib/libcrypto/man/ENGINE_ctrl.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ENGINE_ctrl.3,v 1.1 2018/04/15 01:43:45 schwarze Exp $
+.\" $OpenBSD: ENGINE_ctrl.3,v 1.2 2018/04/15 17:44:59 schwarze Exp $
 .\" content checked up to:
 .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
 .\"
@@ -96,6 +96,11 @@ passing the arguments
 and
 .Fa p .
 .Pp
+User-defined commands can be used before
+.Xr ENGINE_init 3
+to provide data required for initialization
+or at any time to modify the behaviour of an engine.
+.Pp
 Most built-in commands operate on user-defined commands installed with
 .Fn ENGINE_set_cmd_defns ,
 either using the
diff --git a/lib/libcrypto/man/ENGINE_new.3 b/lib/libcrypto/man/ENGINE_new.3
index ab875ce662f..dce7e59f6ab 100644
--- a/lib/libcrypto/man/ENGINE_new.3
+++ b/lib/libcrypto/man/ENGINE_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ENGINE_new.3,v 1.1 2018/04/15 17:02:03 schwarze Exp $
+.\" $OpenBSD: ENGINE_new.3,v 1.2 2018/04/15 17:44:59 schwarze Exp $
 .\" content checked up to:
 .\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
 .\"
@@ -52,6 +52,14 @@
 .Fa "const ENGINE *e"
 .Fc
 .Sh DESCRIPTION
+.Vt ENGINE
+objects can be used to provide alternative implementations of
+cryptographic algorithms, to support additional algorithms, to
+support cryptographic hardware, and to switch among alternative
+implementations of algorithms at run time.
+LibreSSL generally avoids engines and prefers providing
+cryptographic functionality in the crypto library itself.
+.Pp
 .Fn ENGINE_new
 allocates and initializes an empty
 .Vt ENGINE