#use wml::openssl-macros area=docs page=EVP_PKEY_derive

<title>Documents, EVP_PKEY_derive(3)</title>

<h1>EVP_PKEY_derive(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#EXAMPLE">EXAMPLE</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#HISTORY">HISTORY</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive
public key algorithm shared secret.

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/evp.h&gt;
</PRE>
<PRE> 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);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
The <CODE>EVP_PKEY_derive_init()</CODE> function initializes a public key
algorithm context using key <STRONG>pkey</STRONG> for shared secret derivation.

</P>
<P>
The <CODE>EVP_PKEY_derive_set_peer()</CODE> function sets the peer key:
this will normally be a public key.

</P>
<P>
The <CODE>EVP_PKEY_derive()</CODE> derives a shared secret using <STRONG>ctx</STRONG>. If <STRONG>key</STRONG> is <STRONG>NULL</STRONG> then the maximum size of the output buffer is written to the <STRONG>keylen</STRONG> parameter. If <STRONG>key</STRONG> is not <STRONG>NULL</STRONG> then before the call the
<STRONG>keylen</STRONG> parameter should contain the length of the <STRONG>key</STRONG> buffer, if the call is successful the shared secret is written to <STRONG>key</STRONG> and the amount of data written to <STRONG>keylen</STRONG>.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
After the call to <CODE>EVP_PKEY_derive_init()</CODE> algorithm specific
control operations can be performed to set any appropriate parameters for
the operation.

</P>
<P>
The function <CODE>EVP_PKEY_derive()</CODE> can be called more than once on
the same context if several operations are performed using the same
parameters.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>EVP_PKEY_derive_init()</CODE> and <CODE>EVP_PKEY_derive()</CODE>
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.

</P>
<P>
<HR>
<H1><A NAME="EXAMPLE">EXAMPLE</A></H1>
<P>
Derive shared secret (for example DH or EC keys):

</P>
<PRE> #include &lt;openssl/evp.h&gt;
 \#include &lt;openssl/rsa.h&gt;
</PRE>
<PRE> EVP_PKEY_CTX *ctx;
 unsigned char *skey;
 size_t skeylen;
 EVP_PKEY *pkey, *peerkey;
 /* NB: assumes pkey, peerkey have been already set up */
</PRE>
<PRE> ctx = EVP_PKEY_CTX_new(pkey);
 if (!ctx)
        /* Error occurred */
 if (EVP_PKEY_derive_init(ctx) &lt;= 0)
        /* Error */
 if (EVP_PKEY_derive_set_peer(ctx, peerkey) &lt;= 0)
        /* Error */
</PRE>
<PRE> /* Determine buffer length */
 if (EVP_PKEY_derive(ctx, NULL, &amp;skeylen) &lt;= 0)
        /* Error */
</PRE>
<PRE> skey = OPENSSL_malloc(skeylen);
</PRE>
<PRE> if (!skey)
        /* malloc failure */
 
 if (EVP_PKEY_derive(ctx, skey, &amp;skeylen) &lt;= 0)
        /* Error */
</PRE>
<PRE> /* Shared secret is skey bytes written to buffer skey */
</PRE>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../crypto/EVP_PKEY_CTX_new.html#">EVP_PKEY_CTX_new(3)</A>,
<A HREF="../crypto/EVP_PKEY_encrypt.html#">EVP_PKEY_encrypt(3)</A>,
<A HREF="../crypto/EVP_PKEY_decrypt.html#">EVP_PKEY_decrypt(3)</A>,
<A HREF="../crypto/EVP_PKEY_sign.html#">EVP_PKEY_sign(3)</A>,
<A HREF="../crypto/EVP_PKEY_verify.html#">EVP_PKEY_verify(3)</A>,
<A HREF="../crypto/EVP_PKEY_verify_recover.html#">EVP_PKEY_verify_recover(3)</A>,

</P>
<P>
<HR>
<H1><A NAME="HISTORY">HISTORY</A></H1>
<P>
These functions were first added to OpenSSL 1.0.0.

</P>
:}