From 8e826a339f8cda20a4311fa88a1de782972cf40d Mon Sep 17 00:00:00 2001
From: "Dr. Stephen Henson" <steve@openssl.org>
Date: Tue, 10 Oct 2017 13:42:24 +0100
Subject: [PATCH] Document EVP_PKEY_set1_engine()

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4503)
---
 doc/man3/EVP_PKEY_set1_RSA.pod | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod
index e1b7110fe5..884cf91cb7 100644
--- a/doc/man3/EVP_PKEY_set1_RSA.pod
+++ b/doc/man3/EVP_PKEY_set1_RSA.pod
@@ -5,10 +5,9 @@
 EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
 EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
 EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
-EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY,
-EVP_PKEY_get0_hmac,
-EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id
-- EVP_PKEY assignment functions
+EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
+EVP_PKEY_assign_EC_KEY, EVP_PKEY_get0_hmac, EVP_PKEY_type, EVP_PKEY_id,
+EVP_PKEY_base_id, EVP_PKEY_set1_engine - EVP_PKEY assignment functions
 
 =head1 SYNOPSIS
 
@@ -39,6 +38,8 @@ EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id
  int EVP_PKEY_base_id(const EVP_PKEY *pkey);
  int EVP_PKEY_type(int type);
 
+ int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
+
 =head1 DESCRIPTION
 
 EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
@@ -72,6 +73,11 @@ often seen in practice.
 EVP_PKEY_type() returns the underlying type of the NID B<type>. For example
 EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
 
+EVP_PKEY_set1_engine() sets the ENGINE handling B<pkey> to B<engine>. It
+must be called after the key algorithm and components are set up.
+If B<engine> does not include an B<EVP_PKEY_METHOD> for B<pkey> an
+error occurs.
+
 =head1 NOTES
 
 In accordance with the OpenSSL naming convention the key obtained
@@ -89,6 +95,9 @@ Previous versions of this document suggested using EVP_PKEY_type(pkey->type)
 to determine the type of a key. Since B<EVP_PKEY> is now opaque this
 is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
 
+EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM
+key as part of its routine to load a private key.
+
 =head1 RETURN VALUES
 
 EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
@@ -104,6 +113,8 @@ and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
 EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key
 type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error.
 
+EVP_PKEY_set1_engine() returns 1 for success and 0 for failure.
+
 =head1 SEE ALSO
 
 L<EVP_PKEY_new(3)>
-- 
2.25.1