EVP_PKEY_OpenSSL中文网

EVP_PKEY

NAME

EVP_PKEY、EVP_PKEY_new、EVP_PKEY_up_ref、EVP_PKEY_dup、EVP_PKEY_free、EVP_PKEY_new_raw_private_key_ex、EVP_PKEY_new_raw_private_key、EVP_PKEY_new_raw_public_key_ex、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 - 公钥/私钥分配和原始密钥处理函数

SYNOPSIS

 #include <openssl/evp.h>

typedef evp_pkey_st EVP_PKEY;

EVP_PKEY *EVP_PKEY_new(void);
int EVP_PKEY_up_ref(EVP_PKEY *key);
EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key);
void EVP_PKEY_free(EVP_PKEY *key);

EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx,
                                          const char *keytype,
                                          const char *propq,
                                          const unsigned char *key,
                                          size_t keylen);
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_ex(OSSL_LIB_CTX *libctx,
                                         const char *keytype,
                                         const char *propq,
                                         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_mac_key(int type, ENGINE *e, const unsigned char *key,
                               int keylen);

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);

自 OpenSSL 3.0 起，以下函数已被弃用，并且可以通过使用合适的版本值定义OPENSSL_API_COMPAT 来完全隐藏，请参阅openssl_user_macros(7)：

 EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv,
                                size_t len, const EVP_CIPHER *cipher);

DESCRIPTION

EVP_PKEY是保存各种类型的非对称密钥（也称为“密钥对”）的通用结构，可用于多种操作，例如签名、验证签名、密钥派生等。非对称密钥本身通常称为“内部密钥”，并由后端处理，例如提供者（通过EVP_KEYMGMT(3)）或ENGINE。

从概念上讲，EVP_PKEY内部密钥可以保存私钥、公钥或两者（密钥对），以及密钥参数（如果密钥类型需要）。这些组件的存在决定了可以进行哪些操作；例如，签名通常需要存在私钥，而验证通常需要存在公钥。

EVP_PKEY也已用于 MAC 算法，该算法被认为是生成签名，尽管不是公钥算法；“POLY1305”、“SIPHASH”、“HMAC”、“CMAC”。这种用法被认为是遗留的，不鼓励使用EVP_MAC(3) API。

EVP_PKEY_new() 函数分配一个空的EVP_PKEY结构，OpenSSL 使用该结构来存储公钥和私钥。引用计数设置为1。

EVP_PKEY_up_ref() 增加key 的引用计数。

EVP_PKEY_dup() 复制密钥。密钥不得是基于 ENGINE 的密钥或原始密钥，否则复制将失败。

EVP_PKEY_free() 减少key 的引用计数，如果引用计数为零，则释放它。如果key为 NULL，则不执行任何操作。

EVP_PKEY_new_raw_private_key_ex() 分配一个新的EVP_PKEY。除非应将引擎用于密钥类型，否则将使用库上下文libctx和属性查询字符串propq找到密钥的提供程序。keytype参数指示这是什么类型的密钥。该值应该是支持原始私钥的公钥算法的字符串，即“X25519”、“ED25519”、“X448”或“ED448”之一。key指向此EVP_PKEY的原始私钥数据，其长度应为keylen。长度应适合密钥的类型。公钥数据将从给定的私钥数据自动派生（如果适用于算法类型）。

EVP_PKEY_new_raw_private_key() 与 EVP_PKEY_new_raw_private_key_ex() 的作用相同，只是使用默认库上下文和默认属性查询。如果e为非 NULL，则新的EVP_PKEY结构与引擎e相关联。type参数指示这是什么类型的键。该值应该是支持原始私钥的公钥算法的 NID，即EVP_PKEY_X25519、EVP_PKEY_ED25519、EVP_PKEY_X448或EVP_PKEY_ED448之一。

EVP_PKEY_new_raw_private_key_ex() 和 EVP_PKEY_new_raw_private_key() 也可以与大多数实现为公钥算法的 MAC 一起使用，因此也接受 “HMAC”、“POLY1305”、“SIPHASH”等密钥类型或其 NID 形式 EVP_PKEY_POLY1305 、 EVP_PKEY_SIPHASH 、 EVP_PKEY_HMAC 。如上所述，不鼓励使用EVP_MAC(3) API。

EVP_PKEY_new_raw_public_key_ex() 的工作方式与 EVP_PKEY_new_raw_private_key_ex() 相同，只是密钥指向原始公钥数据。EVP_PKEY结构将在没有任何私钥信息的情况下初始化。支持原始公钥的算法类型为“X25519”、“ED25519”、“X448”或“ED448”。

EVP_PKEY_new_raw_public_key() 的工作方式与 EVP_PKEY_new_raw_private_key() 相同，只是密钥指向原始公钥数据。EVP_PKEY结构将在没有任何私钥信息的情况下初始化。支持原始公钥的算法类型有EVP_PKEY_X25519、EVP_PKEY_ED25519、EVP_PKEY_X448或EVP_PKEY_ED448。

EVP_PKEY_new_mac_key() 的工作方式与 EVP_PKEY_new_raw_private_key() 相同。新应用程序应使用 EVP_PKEY_new_raw_private_key() 代替。

EVP_PKEY_get_raw_private_key()用原始私钥数据填充priv 提供的缓冲区。进入函数和退出时priv缓冲区的大小应位于len中len将更新为实际写入的字节数。如果缓冲区priv为 NULL，则*len会填充保存密钥所需的字节数。调用应用程序负责确保缓冲区足够大以接收私钥数据。此函数仅适用于支持原始私钥的算法。目前这是：EVP_PKEY_HMAC、EVP_PKEY_POLY1305、EVP_PKEY_SIPHASH、EVP_PKEY_X25519、EVP_PKEY_ED25519、EVP_PKEY_X448或EVP_PKEY_ED448。

EVP_PKEY_get_raw_public_key()用原始公钥数据填充pub 提供的缓冲区。pub缓冲区的大小应在函数入口和退出时位于len中len将更新为实际写入的字节数。如果缓冲区pub为 NULL，则*len会填充保存密钥所需的字节数。调用应用程序负责确保缓冲区足够大以接收公钥数据。此函数仅适用于支持原始公钥的算法。目前是：EVP_PKEY_X25519、EVP_PKEY_ED25519、EVP_PKEY_X448或EVP_PKEY_ED448。

EVP_PKEY_new_CMAC_key() 的工作方式与 EVP_PKEY_new_raw_private_key() 相同，只是它仅适用于EVP_PKEY_CMAC算法类型。除了原始私钥数据之外，在密码参数中创建 CMAC 期间还需要使用密码算法。该密码应该是标准的仅加密密码。例如，不应使用 AEAD 和 XTS 密码。

应用程序应改用EVP_MAC(3) API，并使用所使用的密码名称在EVP_MAC_CTX对象上设置OSSL_MAC_PARAM_CIPHER参数。

NOTES

EVP_PKEY结构由各种 OpenSSL 函数使用，这些函数需要通用私钥，而不参考任何特定算法。

EVP_PKEY_new() 返回的结构为空。要向此空结构添加私钥或公钥，请使用EVP_PKEY_set1_RSA(3)、EVP_PKEY_set1_DSA(3)、EVP_PKEY_set1_DH(3)或EVP_PKEY_set1_EC_KEY(3)中描述的相应函数。

RETURN VALUES

EVP_PKEY_new()、EVP_PKEY_new_raw_private_key()、EVP_PKEY_new_raw_public_key()、EVP_PKEY_new_CMAC_key() 和 EVP_PKEY_new_mac_key() 返回新分配的EVP_PKEY结构，如果发生错误，则返回 NULL。

EVP_PKEY_dup() 返回密钥重复项，如果发生错误，则返回 NULL。

EVP_PKEY_up_ref()、EVP_PKEY_get_raw_private_key() 和 EVP_PKEY_get_raw_public_key() 返回 1 表示成功，返回 0 表示失败。

HISTORY

EVP_PKEY_new() 和 EVP_PKEY_free() 函数存在于 OpenSSL 的所有版本中。

OpenSSL 1.1.0 中添加了 EVP_PKEY_up_ref() 函数。

OpenSSL 1.1.1 中添加了 EVP_PKEY_new_raw_private_key()、EVP_PKEY_new_raw_public_key()、EVP_PKEY_new_CMAC_key()、EVP_PKEY_new_raw_private_key() 和 EVP_PKEY_get_raw_public_key() 函数。

OpenSSL 3.0 中添加了 EVP_PKEY_dup()、EVP_PKEY_new_raw_private_key_ex() 和 EVP_PKEY_new_raw_public_key_ex() 函数。

OpenSSL 3.0 中已弃用 EVP_PKEY_new_CMAC_key()。

EVP_PKEY 的文档在 OpenSSL 3.0 中进行了修改，允许存在密钥对的私有部分而没有公共部分，而这在以前是不允许的。

COPYRIGHT

根据 Apache License 2.0（“许可证”）获得许可。除非遵守许可证，否则您不得使用此文件。您可以在源代码分发版或/source/license.html的 LICENSE 文件中获取副本。

OpenSSL

密码学和 SSL/TLS 工具包