EVP_PKEY_derive.pod 2.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293
  1. =pod
  2. =head1 NAME
  3. EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret.
  4. =head1 SYNOPSIS
  5. #include <openssl/evp.h>
  6. int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
  7. int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
  8. int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
  9. =head1 DESCRIPTION
  10. The EVP_PKEY_derive_init() function initializes a public key algorithm
  11. context using key B<pkey> for shared secret derivation.
  12. The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
  13. be a public key.
  14. The EVP_PKEY_derive() derives a shared secret using B<ctx>.
  15. If B<key> is B<NULL> then the maximum size of the output buffer is written to
  16. the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
  17. B<keylen> parameter should contain the length of the B<key> buffer, if the call
  18. is successful the shared secret is written to B<key> and the amount of data
  19. written to B<keylen>.
  20. =head1 NOTES
  21. After the call to EVP_PKEY_derive_init() algorithm specific control
  22. operations can be performed to set any appropriate parameters for the
  23. operation.
  24. The function EVP_PKEY_derive() can be called more than once on the same
  25. context if several operations are performed using the same parameters.
  26. =head1 RETURN VALUES
  27. EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
  28. or a negative value for failure. In particular a return value of -2
  29. indicates the operation is not supported by the public key algorithm.
  30. =head1 EXAMPLE
  31. Derive shared secret (for example DH or EC keys):
  32. #include <openssl/evp.h>
  33. #include <openssl/rsa.h>
  34. EVP_PKEY_CTX *ctx;
  35. unsigned char *skey;
  36. size_t skeylen;
  37. EVP_PKEY *pkey, *peerkey;
  38. /* NB: assumes pkey, peerkey have been already set up */
  39. ctx = EVP_PKEY_CTX_new(pkey);
  40. if (!ctx)
  41. /* Error occurred */
  42. if (EVP_PKEY_derive_init(ctx) <= 0)
  43. /* Error */
  44. if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
  45. /* Error */
  46. /* Determine buffer length */
  47. if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
  48. /* Error */
  49. skey = OPENSSL_malloc(skeylen);
  50. if (!skey)
  51. /* malloc failure */
  52. if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
  53. /* Error */
  54. /* Shared secret is skey bytes written to buffer skey */
  55. =head1 SEE ALSO
  56. L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
  57. L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
  58. L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
  59. L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
  60. L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
  61. L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
  62. =head1 HISTORY
  63. These functions were first added to OpenSSL 1.0.0.
  64. =cut