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