166 lines
8.2 KiB
HTML
Executable File
166 lines
8.2 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>EVP_PKEY_new</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>EVP_PKEY_new,
|
|
EVP_PKEY_up_ref,
|
|
EVP_PKEY_free,
|
|
EVP_PKEY_new_raw_private_key,
|
|
EVP_PKEY_new_raw_public_key,
|
|
EVP_PKEY_new_CMAC_key,
|
|
EVP_PKEY_new_mac_key,
|
|
EVP_PKEY_get_raw_private_key,
|
|
EVP_PKEY_get_raw_public_key
|
|
- public/private key allocation and raw key handling functions</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/evp.h></pre>
|
|
<pre>
|
|
EVP_PKEY *EVP_PKEY_new(void);
|
|
int EVP_PKEY_up_ref(EVP_PKEY *key);
|
|
void EVP_PKEY_free(EVP_PKEY *key);</pre>
|
|
<pre>
|
|
EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e,
|
|
const unsigned char *key, size_t keylen);
|
|
EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e,
|
|
const unsigned char *key, size_t keylen);
|
|
EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv,
|
|
size_t len, const EVP_CIPHER *cipher);
|
|
EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key,
|
|
int keylen);</pre>
|
|
<pre>
|
|
int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv,
|
|
size_t *len);
|
|
int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub,
|
|
size_t *len);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The <code>EVP_PKEY_new()</code> function allocates an empty <strong>EVP_PKEY</strong> structure which is
|
|
used by OpenSSL to store public and private keys. The reference count is set to
|
|
<strong>1</strong>.</p>
|
|
<p><code>EVP_PKEY_up_ref()</code> increments the reference count of <strong>key</strong>.</p>
|
|
<p><code>EVP_PKEY_free()</code> decrements the reference count of <strong>key</strong> and, if the reference
|
|
count is zero, frees it up. If <strong>key</strong> is NULL, nothing is done.</p>
|
|
<p><code>EVP_PKEY_new_raw_private_key()</code> allocates a new <strong>EVP_PKEY</strong>. If <strong>e</strong> is non-NULL
|
|
then the new <strong>EVP_PKEY</strong> structure is associated with the engine <strong>e</strong>. The
|
|
<strong>type</strong> argument indicates what kind of key this is. The value should be a NID
|
|
for a public key algorithm that supports raw private keys, i.e. one of
|
|
<strong>EVP_PKEY_HMAC</strong>, <strong>EVP_PKEY_POLY1305</strong>, <strong>EVP_PKEY_SIPHASH</strong>, <strong>EVP_PKEY_X25519</strong>,
|
|
<strong>EVP_PKEY_ED25519</strong>, <strong>EVP_PKEY_X448</strong> or <strong>EVP_PKEY_ED448</strong>. <strong>key</strong> points to the
|
|
raw private key data for this <strong>EVP_PKEY</strong> which should be of length <strong>keylen</strong>.
|
|
The length should be appropriate for the type of the key. The public key data
|
|
will be automatically derived from the given private key data (if appropriate
|
|
for the algorithm type).</p>
|
|
<p><code>EVP_PKEY_new_raw_public_key()</code> works in the same way as
|
|
<code>EVP_PKEY_new_raw_private_key()</code> except that <strong>key</strong> points to the raw public key
|
|
data. The <strong>EVP_PKEY</strong> structure will be initialised without any private key
|
|
information. Algorithm types that support raw public keys are
|
|
<strong>EVP_PKEY_X25519</strong>, <strong>EVP_PKEY_ED25519</strong>, <strong>EVP_PKEY_X448</strong> or <strong>EVP_PKEY_ED448</strong>.</p>
|
|
<p><code>EVP_PKEY_new_CMAC_key()</code> works in the same way as <code>EVP_PKEY_new_raw_private_key()</code>
|
|
except it is only for the <strong>EVP_PKEY_CMAC</strong> algorithm type. In addition to the
|
|
raw private key data, it also takes a cipher algorithm to be used during
|
|
creation of a CMAC in the <strong>cipher</strong> argument.</p>
|
|
<p><code>EVP_PKEY_new_mac_key()</code> works in the same way as <code>EVP_PKEY_new_raw_private_key()</code>.
|
|
New applications should use <code>EVP_PKEY_new_raw_private_key()</code> instead.</p>
|
|
<p><code>EVP_PKEY_get_raw_private_key()</code> fills the buffer provided by <strong>priv</strong> with raw
|
|
private key data. The number of bytes written is populated in <strong>*len</strong>. If the
|
|
buffer <strong>priv</strong> is NULL then <strong>*len</strong> is populated with the number of bytes
|
|
required to hold the key. The calling application is responsible for ensuring
|
|
that the buffer is large enough to receive the private key data. This function
|
|
only works for algorithms that support raw private keys. Currently this is:
|
|
<strong>EVP_PKEY_HMAC</strong>, <strong>EVP_PKEY_POLY1305</strong>, <strong>EVP_PKEY_SIPHASH</strong>, <strong>EVP_PKEY_X25519</strong>,
|
|
<strong>EVP_PKEY_ED25519</strong>, <strong>EVP_PKEY_X448</strong> or <strong>EVP_PKEY_ED448</strong>.</p>
|
|
<p><code>EVP_PKEY_get_raw_public_key()</code> fills the buffer provided by <strong>pub</strong> with raw
|
|
public key data. The number of bytes written is populated in <strong>*len</strong>. If the
|
|
buffer <strong>pub</strong> is NULL then <strong>*len</strong> is populated with the number of bytes
|
|
required to hold the key. The calling application is responsible for ensuring
|
|
that the buffer is large enough to receive the public key data. This function
|
|
only works for algorithms that support raw public keys. Currently this is:
|
|
<strong>EVP_PKEY_X25519</strong>, <strong>EVP_PKEY_ED25519</strong>, <strong>EVP_PKEY_X448</strong> or <strong>EVP_PKEY_ED448</strong>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>The <strong>EVP_PKEY</strong> structure is used by various OpenSSL functions which require a
|
|
general private key without reference to any particular algorithm.</p>
|
|
<p>The structure returned by <code>EVP_PKEY_new()</code> is empty. To add a private or public
|
|
key to this empty structure use the appropriate functions described in
|
|
<em>EVP_PKEY_set1_RSA(3)</em>, <em>EVP_PKEY_set1_DSA(3)</em>, <em>EVP_PKEY_set1_DH(3)</em> or
|
|
<em>EVP_PKEY_set1_EC_KEY(3)</em>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>EVP_PKEY_new()</code>, <code>EVP_PKEY_new_raw_private_key()</code>, <code>EVP_PKEY_new_raw_public_key()</code>,
|
|
<code>EVP_PKEY_new_CMAC_key()</code> and <code>EVP_PKEY_new_mac_key()</code> return either the newly
|
|
allocated <strong>EVP_PKEY</strong> structure or <strong>NULL</strong> if an error occurred.</p>
|
|
<p><code>EVP_PKEY_up_ref()</code>, <code>EVP_PKEY_get_raw_private_key()</code> and
|
|
<code>EVP_PKEY_get_raw_public_key()</code> return 1 for success and 0 for failure.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>EVP_PKEY_set1_RSA(3)</em>, <em>EVP_PKEY_set1_DSA(3)</em>, <em>EVP_PKEY_set1_DH(3)</em> or
|
|
<em>EVP_PKEY_set1_EC_KEY(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>The
|
|
<code>EVP_PKEY_new()</code> and <code>EVP_PKEY_free()</code> functions exist in all versions of OpenSSL.</p>
|
|
<p>The <code>EVP_PKEY_up_ref()</code> function was added in OpenSSL 1.1.0.</p>
|
|
<p>The
|
|
<code>EVP_PKEY_new_raw_private_key()</code>, <code>EVP_PKEY_new_raw_public_key()</code>,
|
|
<code>EVP_PKEY_new_CMAC_key()</code>, <code>EVP_PKEY_new_raw_private_key()</code> and
|
|
<code>EVP_PKEY_get_raw_public_key()</code> functions were added in OpenSSL 1.1.1.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|