956d6990028eebac9be33592ebb90fc47a56639b
[openssl.git] / doc / man3 / EVP_PKEY_new.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_free - private key allocation functions
6
7 =head1 SYNOPSIS
8
9  #include <openssl/evp.h>
10
11  EVP_PKEY *EVP_PKEY_new(void);
12  int EVP_PKEY_up_ref(EVP_PKEY *key);
13  void EVP_PKEY_free(EVP_PKEY *key);
14
15
16 =head1 DESCRIPTION
17
18 The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is
19 used by OpenSSL to store private keys. The reference count is set to B<1>.
20
21 EVP_PKEY_up_ref() increments the reference count of B<key>.
22
23 EVP_PKEY_free() decrements the reference count of B<key> and, if the reference
24 count is zero, frees it up. If B<key> is NULL, nothing is done.
25
26 =head1 NOTES
27
28 The B<EVP_PKEY> structure is used by various OpenSSL functions which require a
29 general private key without reference to any particular algorithm.
30
31 The structure returned by EVP_PKEY_new() is empty. To add a private key to this
32 empty structure the functions described in L<EVP_PKEY_set1_RSA(3)> should be
33 used.
34
35 =head1 RETURN VALUES
36
37 EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> structure or
38 B<NULL> if an error occurred.
39
40 EVP_PKEY_up_ref() returns 1 for success and 0 for failure.
41
42 =head1 SEE ALSO
43
44 L<EVP_PKEY_set1_RSA(3)>
45
46 =head1 HISTORY
47
48 EVP_PKEY_new() and EVP_PKEY_free() exist in all versions of OpenSSL.
49
50 EVP_PKEY_up_ref() was first added to OpenSSL 1.1.0.
51
52 =head1 COPYRIGHT
53
54 Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
55
56 Licensed under the OpenSSL license (the "License").  You may not use
57 this file except in compliance with the License.  You can obtain a copy
58 in the file LICENSE in the source distribution or at
59 L<https://www.openssl.org/source/license.html>.
60
61 =cut