doc/crypto/EVP_PKEY_set1_RSA.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
   6 EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
   7 EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
   8 EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY,
   9 EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id - EVP_PKEY assignment functions.
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/evp.h>
  14
  15  int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key);
  16  int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key);
  17  int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key);
  18  int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);
  19
  20  RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
  21  DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
  22  DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
  23  EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
  24
  25  RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey);
  26  DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey);
  27  DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey);
  28  EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey);
  29
  30  int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key);
  31  int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key);
  32  int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key);
  33  int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);
  34
  35  int EVP_PKEY_id(const EVP_PKEY *pkey);
  36  int EVP_PKEY_base_id(const EVP_PKEY *pkey);
  37  int EVP_PKEY_type(int type);
  38
  39 =head1 DESCRIPTION
  40
  41 EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
  42 EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>.
  43
  44 EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
  45 EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
  46 B<NULL> if the key is not of the correct type.
  47
  48 EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and
  49 EVP_PKEY_get0_EC_KEY() also return the referenced key in B<pkey> or
  50 B<NULL> if the key is not of the correct type but the reference
  51 count of the returned key is B<not> incremented and so must not
  52 be freed up after use.
  53
  54 EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
  55 and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
  56 however these use the supplied B<key> internally and so B<key>
  57 will be freed when the parent B<pkey> is freed.
  58
  59 EVP_PKEY_base_id() returns the type of B<pkey>. For example
  60 an RSA key will return B<EVP_PKEY_RSA>.
  61
  62 EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys
  63 using the same algorithm could use different OIDs. For example an RSA key could
  64 use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to
  65 B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of
  66 alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not
  67 often seen in practice.
  68
  69 EVP_PKEY_type() returns the underlying type of the NID B<type>. For example
  70 EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
  71
  72 =head1 NOTES
  73
  74 In accordance with the OpenSSL naming convention the key obtained
  75 from or assigned to the B<pkey> using the B<1> functions must be
  76 freed as well as B<pkey>.
  77
  78 EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
  79 and EVP_PKEY_assign_EC_KEY() are implemented as macros.
  80
  81 Most applications wishing to know a key type will simply call
  82 EVP_PKEY_base_id() and will not care about the actual type:
  83 which will be identical in almost all cases.
  84
  85 Previous versions of this document suggested using EVP_PKEY_type(pkey->type)
  86 to determine the type of a key. Since B<EVP_PKEY> is now opaque this
  87 is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
  88
  89 =head1 RETURN VALUES
  90
  91 EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
  92 EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
  93
  94 EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
  95 EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
  96 an error occurred.
  97
  98 EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
  99 and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
 100
 101 EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key
 102 type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error.
 103
 104 =head1 SEE ALSO
 105
 106 L<EVP_PKEY_new(3)>
 107
 108 =cut