---
name: "libressl-EVP_PKEY_CTX_ctrl"
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_CTX_ctrl"
---

# libressl-EVP\_PKEY\_CTX\_ctrl(3)

algorithm specific control operations

## NAME

**EVP\_PKEY\_CTX\_ctrl**, **EVP\_PKEY\_CTX\_ctrl\_str**, **EVP\_PKEY\_CTX\_set\_signature\_md**, **EVP\_PKEY\_CTX\_get\_signature\_md**, **EVP\_PKEY\_CTX\_set\_dsa\_paramgen\_bits**, **EVP\_PKEY\_CTX\_set\_dh\_paramgen\_prime\_len**, **EVP\_PKEY\_CTX\_set\_dh\_paramgen\_generator**, **EVP\_PKEY\_CTX\_set\_ec\_paramgen\_curve\_nid**, **EVP\_PKEY\_CTX\_set\_ec\_param\_enc**, **EVP\_PKEY\_CTX\_set\_ecdh\_cofactor\_mode**, **EVP\_PKEY\_CTX\_get\_ecdh\_cofactor\_mode**, **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_type**, **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_type**, **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_md**, **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_md**, **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_outlen**, **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_outlen**, **EVP\_PKEY\_CTX\_set0\_ecdh\_kdf\_ukm**, **EVP\_PKEY\_CTX\_get0\_ecdh\_kdf\_ukm**, **EVP\_PKEY\_CTX\_set1\_id**, **EVP\_PKEY\_CTX\_get1\_id**, **EVP\_PKEY\_CTX\_get1\_id\_len** – algorithm specific control operations

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

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

*int*\

**EVP\_PKEY\_CTX\_ctrl**(*EVP\_PKEY\_CTX \*ctx*, *int keytype*, *int optype*, *int cmd*, *int p1*, *void \*p2*);

*int*\

**EVP\_PKEY\_CTX\_ctrl\_str**(*EVP\_PKEY\_CTX \*ctx*, *const char \*type*, *const char \*value*);

*int*\

**EVP\_PKEY\_CTX\_set\_signature\_md**(*EVP\_PKEY\_CTX \*ctx*, *const EVP\_MD \*md*);

*int*\

**EVP\_PKEY\_CTX\_get\_signature\_md**(*EVP\_PKEY\_CTX \*ctx*, *const EVP\_MD \*\*pmd*);

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

*int*\

**EVP\_PKEY\_CTX\_set\_dsa\_paramgen\_bits**(*EVP\_PKEY\_CTX \*ctx*, *int nbits*);

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

*int*\

**EVP\_PKEY\_CTX\_set\_dh\_paramgen\_prime\_len**(*EVP\_PKEY\_CTX \*ctx*, *int len*);

*int*\

**EVP\_PKEY\_CTX\_set\_dh\_paramgen\_generator**(*EVP\_PKEY\_CTX \*ctx*, *int gen*);

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

*int*\

**EVP\_PKEY\_CTX\_set\_ec\_paramgen\_curve\_nid**(*EVP\_PKEY\_CTX \*ctx*, *int nid*);

*int*

**EVP\_PKEY\_CTX\_set\_ec\_param\_enc**(*EVP\_PKEY\_CTX \*ctx*, *int param\_enc*);

*int*\

**EVP\_PKEY\_CTX\_set\_ecdh\_cofactor\_mode**(*EVP\_PKEY\_CTX \*ctx*, *int cofactor\_mode*);

*int*\

**EVP\_PKEY\_CTX\_get\_ecdh\_cofactor\_mode**(*EVP\_PKEY\_CTX \*ctx*);

*int*\

**EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_type**(*EVP\_PKEY\_CTX \*ctx*, *int kdf*);

*int*\

**EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_type**(*EVP\_PKEY\_CTX \*ctx*);

*int*\

**EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_md**(*EVP\_PKEY\_CTX \*ctx*, *const EVP\_MD \*md*);

*int*\

**EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_md**(*EVP\_PKEY\_CTX \*ctx*, *const EVP\_MD \*\*pmd*);

*int*\

**EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_outlen**(*EVP\_PKEY\_CTX \*ctx*, *int len*);

*int*\

**EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_outlen**(*EVP\_PKEY\_CTX \*ctx*, *int \*plen*);

*int*\

**EVP\_PKEY\_CTX\_set0\_ecdh\_kdf\_ukm**(*EVP\_PKEY\_CTX \*ctx*, *unsigned char \*ukm*, *int len*);

*int*\

**EVP\_PKEY\_CTX\_get0\_ecdh\_kdf\_ukm**(*EVP\_PKEY\_CTX \*ctx*, *unsigned char \*\*pukm*);

*int*\

**EVP\_PKEY\_CTX\_set1\_id**(*EVP\_PKEY\_CTX \*ctx*, *void \*id*, *size\_t id\_len*);

*int*\

**EVP\_PKEY\_CTX\_get1\_id**(*EVP\_PKEY\_CTX \*ctx*, *void \*id*);

*int*\

**EVP\_PKEY\_CTX\_get1\_id\_len**(*EVP\_PKEY\_CTX \*ctx*, *size\_t \*pid\_len*);

## DESCRIPTION

The function **EVP\_PKEY\_CTX\_ctrl**() sends a control operation to the context *ctx*. The key type used must match *keytype* if it is not -1. The parameter *optype* is a mask indicating which operations the control can be applied to. The control command is indicated in *cmd* and any additional arguments in *p1* and *p2*.

Applications will not normally call **EVP\_PKEY\_CTX\_ctrl**() directly but will instead call one of the algorithm specific macros described below and in RSA\_pkey\_ctx\_ctrl(3).

The function **EVP\_PKEY\_CTX\_ctrl\_str**() allows an application to send an algorithm specific control operation to a context *ctx* in string form. This is intended to be used for options specified on the command line or in text files. The commands supported are documented in the [openssl(1)](/openssl/1.md) utility command line pages for the option **-pkeyopt** which is supported by the **pkeyutl**, **genpkey**, and **req** commands.

All the remaining "functions" are implemented as macros.

The **EVP\_PKEY\_CTX\_set\_signature\_md**() and **EVP\_PKEY\_CTX\_get\_signature\_md**() macros set and get the message digest type used in a signature. They can be used with the RSA, DSA, and ECDSA algorithms. If the key is of the type EVP\_PKEY\_RSA\_PSS and has usage restrictions, an error occurs if an attempt is made to set the digest to anything other than the restricted value.

These two macros expand to **EVP\_PKEY\_CTX\_ctrl**() with an *optype* of EVP\_PKEY\_OP\_TYPE\_SIG and the following command arguments:

| | |
| --- | --- |
| *cmd* constant | corresponding macro |
| EVP\_PKEY\_CTRL\_MD | **EVP\_PKEY\_CTX\_set\_signature\_md**() |
| EVP\_PKEY\_CTRL\_GET\_MD | **EVP\_PKEY\_CTX\_get\_signature\_md**() |

### DSA parameters

The macro **EVP\_PKEY\_CTX\_set\_dsa\_paramgen\_bits**() sets the number of bits used for DSA parameter generation to *nbits*. If not specified, 1024 is used.

### DH parameters

The macro **EVP\_PKEY\_CTX\_set\_dh\_paramgen\_prime\_len**() sets the length of the DH prime parameter *len* for DH parameter generation. It only accepts lengths greater than or equal to 256. If this macro is not called, then 1024 is used.

The **EVP\_PKEY\_CTX\_set\_dh\_paramgen\_generator**() macro sets DH generator to *gen* for DH parameter generation. If not specified, 2 is used.

### EC parameters

The **EVP\_PKEY\_CTX\_set\_ec\_paramgen\_curve\_nid**() macro sets the EC curve for EC parameter generation to *nid*. For EC parameter generation, this macro must be called or an error occurs because there is no default curve.

The **EVP\_PKEY\_CTX\_set\_ec\_param\_enc**() macro sets the EC parameter encoding to *param\_enc* when generating EC parameters or an EC key. The encoding can be set to 0 for explicit parameters or to OPENSSL\_EC\_NAMED\_CURVE to use named curve form.

### ECDH parameters

The **EVP\_PKEY\_CTX\_set\_ecdh\_cofactor\_mode**() macro sets the cofactor mode to *cofactor\_mode* for ECDH key derivation. Possible values are 1 to enable cofactor key derivation, 0 to disable it, or -1 to clear the stored cofactor mode and fall back to the private key cofactor mode.

The **EVP\_PKEY\_CTX\_get\_ecdh\_cofactor\_mode**() macro returns the cofactor mode for *ctx* used for ECDH key derivation. Possible return values are 1 when cofactor key derivation is enabled or 0 otherwise.

### ECDH key derivation function parameters

The **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_type**() macro sets the key derivation function type to *kdf* for ECDH key derivation. Possible values are EVP\_PKEY\_ECDH\_KDF\_NONE or EVP\_PKEY\_ECDH\_KDF\_X9\_63 which uses the key derivation specified in X9.63. When using key derivation, the *kdf\_md* and *kdf\_outlen* parameters must also be specified.

The **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_type**() macro returns the key derivation function type for *ctx* used for ECDH key derivation. Possible return values are EVP\_PKEY\_ECDH\_KDF\_NONE or EVP\_PKEY\_ECDH\_KDF\_X9\_63.

The **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_md**() macro sets the key derivation function message digest to *md* for ECDH key derivation. Note that X9.63 specifies that this digest should be SHA-1, but OpenSSL tolerates other digests.

The **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_md**() macro gets the key derivation function message digest for *ctx* used for ECDH key derivation.

The **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_outlen**() macro sets the key derivation function output length to *len* for ECDH key derivation.

The **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_outlen**() macro gets the key derivation function output length for *ctx* used for ECDH key derivation.

The **EVP\_PKEY\_CTX\_set0\_ecdh\_kdf\_ukm**() macro sets the user key material to *ukm* for ECDH key derivation. This parameter is optional and corresponds to the shared info in X9.63 terms. The library takes ownership of the user key material, so the caller should not free the original memory pointed to by *ukm*.

The **EVP\_PKEY\_CTX\_get0\_ecdh\_kdf\_ukm**() macro gets the user key material for *ctx*. The return value is the user key material length. The resulting pointer is owned by the library and should not be freed by the caller.

### CMAC parameters

Application programs normally implement CMAC as described in EVP\_PKEY\_new\_CMAC\_key(3) and do not need the control commands documented here.

Alternatively, the call to EVP\_PKEY\_new\_CMAC\_key(3) can be replaced as follows, leaving the rest of the example code given there unchanged:

1. Create an empty *EVP\_PKEY\_CTX* object by passing the EVP\_PKEY\_CMAC constant to EVP\_PKEY\_CTX\_new\_id(3).

2. Initialize it with EVP\_PKEY\_keygen\_init(3).

3. Select the block cipher by calling **EVP\_PKEY\_CTX\_ctrl**() with an *optype* of EVP\_PKEY\_OP\_KEYGEN, a *cmd* of EVP\_PKEY\_CTRL\_CIPHER, and *p2* pointing to an *EVP\_CIPHER* object, which can be obtained from the functions in the CIPHER LISTING in EVP\_EncryptInit(3). The *p1* argument is ignored; passing 0 is recommended.

4. Call **EVP\_PKEY\_CTX\_ctrl**() again with an *optype* of EVP\_PKEY\_OP\_KEYGEN, a *cmd* of EVP\_PKEY\_CTRL\_SET\_MAC\_KEY, *p2* pointing to the symmetric key, and *p1* specifying the length of the symmetric key in bytes.

5. Extract the desired *EVP\_PKEY* object using EVP\_PKEY\_keygen(3), making sure the *ppkey* argument points to a storage location containing a NULL pointer.

6. Proceed with EVP\_MD\_CTX\_new(3), EVP\_DigestSignInit(3), and EVP\_DigestSign(3) as usual.

### HMAC parameters

Application programs normally implement HMAC as described in EVP\_PKEY\_new\_raw\_private\_key(3). While it is possible to instead use EVP\_PKEY\_CTRL\_SET\_MAC\_KEY directly, similar to the above description for CMAC, that is strongly discouraged. It's essentially what the deprecated function EVP\_PKEY\_new\_mac\_key(3) does internally, and compared to the direct approach with EVP\_PKEY\_new\_raw\_private\_key(3), it requires a lot of cumbersome and unnecessary work.

### Other parameters

The **EVP\_PKEY\_CTX\_set1\_id**(), **EVP\_PKEY\_CTX\_get1\_id**(), and **EVP\_PKEY\_CTX\_get1\_id\_len**() macros manipulate a special identifier field used for some specific signature algorithms such as SM2. The **EVP\_PKEY\_set1\_id**() macro sets the ID to a copy of *id* with the length *id\_len*. The caller can safely free the original memory pointed to by *id*. The **EVP\_PKEY\_CTX\_get1\_id\_len**() macro returns the length of the ID set via a previous call to **EVP\_PKEY\_set1\_id**(). That length is typically used to allocate memory for a subsequent call to **EVP\_PKEY\_CTX\_get1\_id**(), which copies the previously set ID into \**id*. The caller is responsible for allocating sufficient memory for *id* before calling **EVP\_PKEY\_CTX\_get1\_id**().

## RETURN VALUES

**EVP\_PKEY\_CTX\_ctrl**() and its macros return a positive value 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.

## SEE ALSO

DH\_new(3), EVP\_DigestInit(3), EVP\_PKEY\_CTX\_new(3), EVP\_PKEY\_decrypt(3), EVP\_PKEY\_derive(3), EVP\_PKEY\_encrypt(3), EVP\_PKEY\_get\_default\_digest\_nid(3), EVP\_PKEY\_keygen(3), EVP\_PKEY\_sign(3), EVP\_PKEY\_verify(3), EVP\_PKEY\_verify\_recover(3), RSA\_pkey\_ctx\_ctrl(3)

## HISTORY

The functions **EVP\_PKEY\_CTX\_ctrl**(), **EVP\_PKEY\_CTX\_ctrl\_str**(), **EVP\_PKEY\_CTX\_set\_signature\_md**(), **EVP\_PKEY\_CTX\_set\_dsa\_paramgen\_bits**(), **EVP\_PKEY\_CTX\_set\_dh\_paramgen\_prime\_len**(), **EVP\_PKEY\_CTX\_set\_dh\_paramgen\_generator**(), and **EVP\_PKEY\_CTX\_set\_ec\_paramgen\_curve\_nid**() first appeared in OpenSSL 1.0.0 and have been available since OpenBSD 4.9.

The functions **EVP\_PKEY\_CTX\_get\_signature\_md**(), **EVP\_PKEY\_CTX\_set\_ec\_param\_enc**(), **EVP\_PKEY\_CTX\_set\_ecdh\_cofactor\_mode**(), **EVP\_PKEY\_CTX\_get\_ecdh\_cofactor\_mode**(), **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_type**(), **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_type**(), **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_md**(), **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_md**(), **EVP\_PKEY\_CTX\_set\_ecdh\_kdf\_outlen**(), **EVP\_PKEY\_CTX\_get\_ecdh\_kdf\_outlen**(), **EVP\_PKEY\_CTX\_set0\_ecdh\_kdf\_ukm**(), and **EVP\_PKEY\_CTX\_get0\_ecdh\_kdf\_ukm**() first appeared in OpenSSL 1.0.2 and have been available since OpenBSD 6.6.

The functions **EVP\_PKEY\_CTX\_set1\_id**(), **EVP\_PKEY\_CTX\_get1\_id**(), and **EVP\_PKEY\_CTX\_get1\_id\_len**() first appeared in OpenSSL 1.1.1 and have been available since OpenBSD 6.6.