---
name: "libressl-EVP_PKEY_new"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-EVP_PKEY_new"
---

# libressl-EVP\_PKEY\_new(3)

public and private key allocation and raw key handling functions

## NAME

**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\_mac\_key**, **EVP\_PKEY\_get\_raw\_private\_key**, **EVP\_PKEY\_get\_raw\_public\_key** – public and private key allocation and raw key handling functions

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#include \<openssl/evp.h\>**

*EVP\_PKEY* *\**\

**EVP\_PKEY\_new**(*void*);

*int*\

**EVP\_PKEY\_up\_ref**(*EVP\_PKEY \*pkey*);

*void*\

**EVP\_PKEY\_free**(*EVP\_PKEY \*pkey*);

*EVP\_PKEY* *\**\

**EVP\_PKEY\_new\_raw\_private\_key**(*int type*, *ENGINE \*engine*, *const unsigned char \*rawpriv*, *size\_t rawlen*);

*EVP\_PKEY* *\**\

**EVP\_PKEY\_new\_raw\_public\_key**(*int type*, *ENGINE \*engine*, *const unsigned char \*rawpub*, *size\_t rawlen*);

*EVP\_PKEY* *\**\

**EVP\_PKEY\_new\_mac\_key**(*int type*, *ENGINE \*engine*, *const unsigned char \*rawpriv*, *int rawlen*);

*int*\

**EVP\_PKEY\_get\_raw\_private\_key**(*const EVP\_PKEY \*pkey*, *unsigned char \*rawpriv*, *size\_t \*rawlen*);

*int*\

**EVP\_PKEY\_get\_raw\_public\_key**(*const EVP\_PKEY \*pkey*, *unsigned char \*rawpub*, *size\_t \*rawlen*);

## DESCRIPTION

The *EVP\_PKEY* structure is used by various OpenSSL functions which require a general private or public key without reference to any particular algorithm.

The **EVP\_PKEY\_new**() function allocates an empty *EVP\_PKEY* structure. The reference count is set to 1. To add a private or public key to it, use the functions described in EVP\_PKEY\_set1\_RSA(3).

**EVP\_PKEY\_up\_ref**() increments the reference count of *pkey* by 1.

**EVP\_PKEY\_free**() decrements the reference count of *pkey* by 1, and if the reference count reaches zero, frees it up. If *pkey* is a NULL pointer, no action occurs.

**EVP\_PKEY\_new\_raw\_private\_key**() allocates a new *EVP\_PKEY*. The NID of a public key algorithm that supports raw private keys, i.e. EVP\_PKEY\_HMAC, EVP\_PKEY\_X25519, or EVP\_PKEY\_ED25519, is provided in the *type* argument and *rawlen* bytes of raw private key data of that type in *rawpriv*. The public key data is automatically derived from the given private key data, if appropriate for the algorithm type. The *ENGINE*, *\*engine* argument is always ignored and passing NULL is recommended.

**EVP\_PKEY\_new\_raw\_public\_key**() works in the same way as **EVP\_PKEY\_new\_raw\_private\_key**() except that *rawpub* points to the raw public key data. The *EVP\_PKEY* structure is initialised without any private key information. Algorithm types that support raw public keys are EVP\_PKEY\_X25519 and EVP\_PKEY\_ED25519.

**EVP\_PKEY\_new\_mac\_key**() is a deprecated function that achieves the same effect as **EVP\_PKEY\_new\_raw\_private\_key**() in a more complicated way and only works with a *type* of EVP\_PKEY\_HMAC.

**EVP\_PKEY\_get\_raw\_private\_key**() writes up to \**rawlen* bytes of raw private key data to the buffer starting at *rawpriv* and stores the number of bytes written in \**rawlen*. The calling application is responsible for ensuring that the buffer is large enough to receive the private key data. If the *rawpriv* argument is NULL, the number of bytes required to hold the key is stored in \**rawlen*. This function only works for algorithms that support raw private keys. Currently these are EVP\_PKEY\_HMAC, EVP\_PKEY\_X25519, and EVP\_PKEY\_ED25519.

**EVP\_PKEY\_get\_raw\_public\_key**() is similar to **EVP\_PKEY\_get\_raw\_private\_key**() except that it writes raw public key data. This function only works for algorithms that support raw public keys. Currently these are EVP\_PKEY\_X25519 and EVP\_PKEY\_ED25519.

## RETURN VALUES

**EVP\_PKEY\_new**(), **EVP\_PKEY\_new\_raw\_private\_key**(), **EVP\_PKEY\_new\_raw\_public\_key**(), and **EVP\_PKEY\_new\_mac\_key**() return either the newly allocated *EVP\_PKEY* structure or NULL if an error occurred.

**EVP\_PKEY\_up\_ref**(), **EVP\_PKEY\_get\_raw\_private\_key**(), and **EVP\_PKEY\_get\_raw\_public\_key**() return 1 for success or 0 for failure.

## EXAMPLES

The following code digests a message with HMAC-SHA256:

```
/* Bogus key: would normally be set from another source */
const unsigned char *key = "key";
const size_t key_len = strlen(key);
const char *msg = "The quick brown fox jumps over the lazy dog";
const size_t msg_len = strlen(msg);
unsigned char *out_mac;
size_t out_len, i;
EVP_PKEY *pkey;
EVP_MD_CTX *md_ctx;
pkey = EVP_PKEY_new_raw_private_key(EVP_PKEY_HMAC, NULL,
    key, key_len);
if (pkey == NULL)
	err(1, "EVP_PKEY_new_raw_private_key");
md_ctx = EVP_MD_CTX_new();
if (md_ctx == NULL)
	err(1, "EVP_MD_CTX_new");
if (EVP_DigestSignInit(md_ctx, NULL, EVP_sha256(), NULL, pkey) == 0)
	err(1, "EVP_DigestSignInit");
if (EVP_DigestSign(md_ctx, NULL, &out_len, msg, msg_len) == 0)
	err(1, "EVP_DigestSign(NULL)");
if ((out_mac = calloc(1, out_len)) == NULL)
	err(1, "calloc");
if (EVP_DigestSign(md_ctx, out_mac, &out_len, msg, msg_len) == 0)
	err(1, "EVP_DigestSign(MAC)");
EVP_MD_CTX_free(md_ctx);
EVP_PKEY_free(pkey);
printf(" MAC = ");
for (i = 0; i < out_len; i++)
	printf("%02x", out_mac[i]);
printf("\n");
free(out_mac);
```

Even though the type name *EVP\_PKEY* was originally intended to stand for “private key” and the EVP\_DigestSignInit(3) API was designed for digital signatures in the context of public key cryptography, both are also used here because a MAC also requires a key, even though that is a symmetric key.

The same code can be used for signing with Ed25519 by making the key ED25519\_PRIVATE\_KEY\_LENGTH = 32 bytes long, replacing EVP\_PKEY\_HMAC with EVP\_PKEY\_ED25519, and replacing the call to EVP\_sha256(3) with NULL.

## SEE ALSO

CMAC\_Init(3), d2i\_PrivateKey(3), evp(3), EVP\_PKCS82PKEY(3), EVP\_PKEY\_cmp(3), EVP\_PKEY\_CTX\_new(3), EVP\_PKEY\_get\_default\_digest\_nid(3), EVP\_PKEY\_new\_CMAC\_key(3), EVP\_PKEY\_print\_private(3), EVP\_PKEY\_set1\_RSA(3), EVP\_PKEY\_size(3), X509\_get\_pubkey\_parameters(3)

## HISTORY

**EVP\_PKEY\_new**() and **EVP\_PKEY\_free**() first appeared in SSLeay 0.6.0 and have been available since OpenBSD 2.4.

**EVP\_PKEY\_new\_mac\_key**() first appeared in OpenSSL 1.0.0 and has been available since OpenBSD 4.9.

**EVP\_PKEY\_up\_ref**() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3.

**EVP\_PKEY\_new\_raw\_private\_key**(), **EVP\_PKEY\_new\_raw\_public\_key**(), **EVP\_PKEY\_get\_raw\_private\_key**(), and **EVP\_PKEY\_get\_raw\_public\_key**() first appeared in OpenSSL 1.1.1 and have been available since OpenBSD 7.3.