Commit aa09c243 authored by Dr. Stephen Henson's avatar Dr. Stephen Henson
Browse files

Document EVP_PKEY_set1_engine() 



Reviewed-by: default avatarMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4503)

(cherry picked from commit 8e826a33)
parent b30d184a

doc/crypto/EVP_PKEY_set1_RSA.pod

+15 −4
Original line number Original line Diff line number Diff line
@@ -5,10 +5,9 @@ 
EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,

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_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_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_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,

EVP_PKEY_get0_hmac,

EVP_PKEY_assign_EC_KEY, EVP_PKEY_get0_hmac, EVP_PKEY_type, EVP_PKEY_id,

EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id

EVP_PKEY_base_id, EVP_PKEY_set1_engine - EVP_PKEY assignment functions

- EVP_PKEY assignment functions





=head1 SYNOPSIS

=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_base_id(const EVP_PKEY *pkey);

 int EVP_PKEY_type(int type);

 int EVP_PKEY_type(int type);





 int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);



=head1 DESCRIPTION

=head1 DESCRIPTION





EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and

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() 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_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

=head1 NOTES





In accordance with the OpenSSL naming convention the key obtained

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

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).

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

=head1 RETURN VALUES





EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and

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

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.

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

=head1 SEE ALSO





L<EVP_PKEY_new(3)>

L<EVP_PKEY_new(3)>