/docs/man3.3/man7/provider-cipher.html

provider-cipher

名称

provider-cipher - 密钥库 <-> 提供程序函数

语法

#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>

/*
 * None of these are actual functions, but are displayed like this for
 * the function signatures for functions that are offered as function
 * pointers in OSSL_DISPATCH arrays.
 */

/* Context management */
void *OSSL_FUNC_cipher_newctx(void *provctx);
void OSSL_FUNC_cipher_freectx(void *cctx);
void *OSSL_FUNC_cipher_dupctx(void *cctx);

/* Encryption/decryption */
int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key,
                                  size_t keylen, const unsigned char *iv,
                                  size_t ivlen, const OSSL_PARAM params[]);
int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key,
                                  size_t keylen, const unsigned char *iv,
                                  size_t ivlen, const OSSL_PARAM params[]);
int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl,
                            size_t outsize, const unsigned char *in, size_t inl);
int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl,
                           size_t outsize);
int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl,
                            size_t outsize, const unsigned char *in, size_t inl);

/* Cipher parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx);

/* Cipher operation parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx,
                                                       void *provctx);
const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx,
                                                       void *provctx);

/* Cipher parameters */
int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]);

/* Cipher operation parameters */
int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]);
int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]);

描述

本文档主要针对提供程序作者。有关更多信息，请参阅 provider(7)。

CIPHER 操作使提供程序能够实现密码算法，并通过 API 函数 EVP_EncryptInit_ex(3)、EVP_EncryptUpdate(3) 和 EVP_EncryptFinal(3)（以及解密等效项和其他相关函数）使应用程序能够使用这些算法。

此处提到的所有“函数”都作为函数指针在 OSSL_DISPATCH(3) 数组中在libcrypto和提供程序之间传递，并通过提供程序的 provider_query_operation() 函数返回的 OSSL_ALGORITHM(3) 数组传递（请参阅 provider-base(7)中的“提供程序函数”）。

所有这些“函数”都有一个对应的函数类型定义，名为OSSL_FUNC_{name}_fn，以及一个从 OSSL_DISPATCH(3) 元素中检索函数指针的辅助函数，名为OSSL_FUNC_{name}。例如，“函数”OSSL_FUNC_cipher_newctx() 具有以下内容：

typedef void *(OSSL_FUNC_cipher_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_cipher_newctx_fn
    OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) 数组通过数字进行索引，这些数字在 openssl-core_dispatch.h(7)中作为宏提供，如下所示：

OSSL_FUNC_cipher_newctx               OSSL_FUNC_CIPHER_NEWCTX
OSSL_FUNC_cipher_freectx              OSSL_FUNC_CIPHER_FREECTX
OSSL_FUNC_cipher_dupctx               OSSL_FUNC_CIPHER_DUPCTX

OSSL_FUNC_cipher_encrypt_init         OSSL_FUNC_CIPHER_ENCRYPT_INIT
OSSL_FUNC_cipher_decrypt_init         OSSL_FUNC_CIPHER_DECRYPT_INIT
OSSL_FUNC_cipher_update               OSSL_FUNC_CIPHER_UPDATE
OSSL_FUNC_cipher_final                OSSL_FUNC_CIPHER_FINAL
OSSL_FUNC_cipher_cipher               OSSL_FUNC_CIPHER_CIPHER

OSSL_FUNC_cipher_get_params           OSSL_FUNC_CIPHER_GET_PARAMS
OSSL_FUNC_cipher_get_ctx_params       OSSL_FUNC_CIPHER_GET_CTX_PARAMS
OSSL_FUNC_cipher_set_ctx_params       OSSL_FUNC_CIPHER_SET_CTX_PARAMS

OSSL_FUNC_cipher_gettable_params      OSSL_FUNC_CIPHER_GETTABLE_PARAMS
OSSL_FUNC_cipher_gettable_ctx_params  OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS
OSSL_FUNC_cipher_settable_ctx_params  OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS

密码算法实现可能不会实现所有这些函数。为了成为一组一致的函数，必须至少有一组完整的“加密”函数，或一组完整的“解密”函数，或一个“密码”函数。在所有情况下，都必须存在 OSSL_FUNC_cipher_newctx 和 OSSL_FUNC_cipher_freectx 函数。所有其他函数都是可选的。

上下文管理函数

OSSL_FUNC_cipher_newctx() 应该创建并返回指向提供程序端结构的指针，用于在密码操作期间保存上下文信息。指向此上下文的指针将在许多其他密码操作函数调用中传递回来。参数provctx是在提供程序初始化期间生成的提供程序上下文（请参阅 provider(7)）。

OSSL_FUNC_cipher_freectx() 会将指向提供程序端密码上下文的指针传递给cctx参数。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_cipher_dupctx() 应该复制cctx参数中的提供程序端密码上下文，并返回副本。

加密/解密函数

OSSL_FUNC_cipher_encrypt_init() 初始化用于加密的密码操作，给定cctx参数中新创建的提供程序端密码上下文。要使用的密钥在key中给出，长度为keylen字节。要使用的 IV 在iv中给出，长度为ivlen字节。如果params不为 NULL，则应以类似于使用 OSSL_FUNC_cipher_set_ctx_params() 的方式将其设置为上下文。

OSSL_FUNC_cipher_decrypt_init() 与 OSSL_FUNC_cipher_encrypt_init() 相同，只是它初始化用于解密操作的上下文。

OSSL_FUNC_cipher_update() 被调用以提供要加密/解密的数据，作为先前初始化的密码操作的一部分。cctx参数包含指向先前初始化的提供程序端上下文的指针。OSSL_FUNC_cipher_update() 应该加密/解密in指向的位置处的inl字节数据。加密后的数据应存储在out中，写入的数据量应存储在*outl中，该值不应超过outsize字节。可以对单个密码操作多次调用 OSSL_FUNC_cipher_update()。密码实现负责处理不是块长度倍数的输入长度。在这种情况下，密码实现通常会缓存输入数据的部分块，直到获得完整的块。指针out和in可以指向相同的位置，在这种情况下，加密必须就地完成。如果out和in指向不同的位置，则 EVP_EncryptUpdate(3) 和 EVP_DecryptUpdate(3) 的要求保证这两个缓冲区是不相交的。类似地，EVP_EncryptUpdate(3) 和 EVP_DecryptUpdate(3) 的要求确保out指向的缓冲区包含执行操作所需的足够空间。

OSSL_FUNC_cipher_final() 完成通过先前的 OSSL_FUNC_cipher_encrypt_init() 或 OSSL_FUNC_cipher_decrypt_init() 和 OSSL_FUNC_cipher_update() 调用启动的加密或解密。cctx参数包含指向提供程序端上下文的指针。任何最终的加密/解密输出都应写入out，写入的数据量应存储在*outl中，该值不应超过outsize字节。对outsize的期望与 EVP_EncryptFinal(3) 和 EVP_DecryptFinal(3) 中记录的期望相同。

OSSL_FUNC_cipher_cipher() 使用cctx参数中的提供程序端密码上下文执行加密/解密，该上下文应该已通过调用 OSSL_FUNC_cipher_encrypt_init() 或 OSSL_FUNC_cipher_decrypt_init() 进行初始化。这应该调用原始底层密码函数，没有任何填充。这将在提供程序中作为应用程序调用 EVP_Cipher(3) 的结果被调用。应用程序负责确保输入是块长度的倍数。要加密/解密的数据将在in中，长度为inl字节。加密/解密的输出应存储在out中，存储的数据量应放入*outl中，该值不应超过outsize字节。

密码参数

有关这些函数使用的参数结构的更多详细信息，请参阅 OSSL_PARAM(3)。

OSSL_FUNC_cipher_get_params() 获取算法实现的详细信息并将其存储在params中。

OSSL_FUNC_cipher_set_ctx_params() 将提供程序端密码上下文cctx的密码操作参数设置为params。任何参数设置都是对之前设置的任何参数的补充。将 NULL 传递给params应该返回 true。

OSSL_FUNC_cipher_get_ctx_params() 从给定的提供程序端密码上下文cctx中获取密码操作详细信息，并将其存储在params中。将 NULL 传递给params应该返回 true。

OSSL_FUNC_cipher_gettable_params()、OSSL_FUNC_cipher_gettable_ctx_params() 和 OSSL_FUNC_cipher_settable_ctx_params() 都返回常量 OSSL_PARAM(3) 数组作为 OSSL_FUNC_cipher_get_params()、OSSL_FUNC_cipher_get_ctx_params() 和 OSSL_FUNC_cipher_set_ctx_params() 可以分别处理的参数的描述符。如果cctx不为 NULL，则 OSSL_FUNC_cipher_gettable_ctx_params() 和 OSSL_FUNC_cipher_settable_ctx_params() 将返回与其当前状态关联的参数。否则，它们将返回与提供程序端算法provctx关联的参数。

内置密码当前识别的参数在 EVP_EncryptInit(3)中的“参数”中列出。并非所有参数都与所有密码相关或被所有密码理解。

返回值

OSSL_FUNC_cipher_newctx() 和 OSSL_FUNC_cipher_dupctx() 应该返回新创建的提供程序端密码上下文，或者在失败时返回 NULL。

OSSL_FUNC_cipher_encrypt_init()、OSSL_FUNC_cipher_decrypt_init()、OSSL_FUNC_cipher_update()、OSSL_FUNC_cipher_final()、OSSL_FUNC_cipher_cipher()、OSSL_FUNC_cipher_get_params()、OSSL_FUNC_cipher_get_ctx_params() 和 OSSL_FUNC_cipher_set_ctx_params() 应该在成功时返回 1，在错误时返回 0。

OSSL_FUNC_cipher_gettable_params()、OSSL_FUNC_cipher_gettable_ctx_params() 和 OSSL_FUNC_cipher_settable_ctx_params() 应该返回一个常量 OSSL_PARAM(3) 数组，或者如果没有提供则返回 NULL。

参见

provider(7)、OSSL_PROVIDER-FIPS(7)、OSSL_PROVIDER-default(7)、OSSL_PROVIDER-legacy(7)、EVP_CIPHER-AES(7)、EVP_CIPHER-ARIA(7)、EVP_CIPHER-BLOWFISH(7)、EVP_CIPHER-CAMELLIA(7)、EVP_CIPHER-CAST(7)、EVP_CIPHER-CHACHA(7)、EVP_CIPHER-DES(7)、EVP_CIPHER-IDEA(7)、EVP_CIPHER-RC2(7)、EVP_CIPHER-RC4(7)、EVP_CIPHER-RC5(7)、EVP_CIPHER-SEED(7)、EVP_CIPHER-SM4(7)、EVP_CIPHER-NULL(7)、life_cycle-cipher(7)、EVP_EncryptInit(3)

历史

提供程序 CIPHER 接口是在 OpenSSL 3.0 中引入的。

版权

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