From: Dr. Stephen Henson <steve@openssl.org>
Date: Sat, 8 Jul 2006 12:47:52 +0000 (+0000)
Subject: EVP_PKEY_derive() docs.
X-Git-Tag: OpenSSL_0_9_8k^2~1215
X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=ba702545fcab5e75181385c4415aa0d73a7022bb;hp=436369100d360d9119f2f77ed935d0c1f8f49d09

EVP_PKEY_derive() docs.
---

diff --git a/doc/crypto/EVP_PKEY_derive.pod b/doc/crypto/EVP_PKEY_derive.pod
new file mode 100644
index 0000000000..99fa3090ee
--- /dev/null
+++ b/doc/crypto/EVP_PKEY_derive.pod
@@ -0,0 +1,93 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret.
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
+ int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_derive_init() function initializes a public key algorithm
+context using key B<pkey> for shared secret derivation.
+
+The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
+be a public key.
+
+The EVP_PKEY_derive() derives a shared secret using B<ctx>.
+If B<key> is B<NULL> then the maximum size of the output buffer is written to
+the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
+B<keylen> parameter should contain the length of the B<key> buffer, if the call
+is successful the shared secret is written to B<key> and the amount of data
+written to B<keylen>.
+
+=head1 NOTES
+
+After the call to EVP_PKEY_derive_init() algorithm specific control
+operations can be performed to set any appropriate parameters for the
+operation.
+
+The function EVP_PKEY_derive() can be called more than once on the same
+context if several operations are performed using the same parameters.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
+or a negative value for failure. In particular a return value of -2
+indicates the operation is not supported by the public key algorithm.
+
+=head1 EXAMPLE
+
+Derive shared secret (for example DH or EC keys):
+
+ #include <openssl/evp.h>
+ #include <openssl/rsa.h>
+
+ EVP_PKEY_CTX *ctx;
+ unsigned char *skey;
+ size_t skeylen;
+ EVP_PKEY *pkey, *peerkey;
+ /* NB: assumes pkey, peerkey have been already set up */
+
+ ctx = EVP_PKEY_CTX_new(pkey);
+ if (!ctx)
+	/* Error occurred */
+ if (EVP_PKEY_derive_init(ctx) <= 0)
+	/* Error */
+ if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
+	/* Error */
+
+ /* Determine buffer length */
+ if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
+	/* Error */
+
+ skey = OPENSSL_malloc(skeylen);
+
+ if (!skey)
+	/* malloc failure */
+ 
+ if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
+	/* Error */
+
+ /* Shared secret is skey bytes written to buffer skey */
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
+
+=head1 HISTORY
+
+These functions were first added to OpenSSL 0.9.9.
+
+=cut