OpenSSL

密碼學和 SSL/TLS 工具包

provider-asym_cipher

名稱

provider-asym_cipher - asym_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_asym_cipher_newctx(void *provctx);
void OSSL_FUNC_asym_cipher_freectx(void *ctx);
void *OSSL_FUNC_asym_cipher_dupctx(void *ctx);

/* Encryption */
int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey,
                                       const OSSL_PARAM params[]);
int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen,
                                  size_t outsize, const unsigned char *in,
                                  size_t inlen);

/* Decryption */
int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey,
                                       const OSSL_PARAM params[]);
int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen,
                                  size_t outsize, const unsigned char *in,
                                  size_t inlen);

/* Asymmetric Cipher parameters */
int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void *provctx);
int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void *provctx);

說明

此文件主要針對提供者作者。請參閱 provider(7) 以取得進一步資訊。

非對稱加密演算法 (OSSL_OP_ASYM_CIPHER) 作業讓提供者能夠實作非對稱加密演算法，並透過 API 函式 EVP_PKEY_encrypt(3)、EVP_PKEY_decrypt(3) 和其他相關函式讓應用程式使用這些演算法。

這裡提到的所有「函式」都以函式指標的形式在 libcrypto 和提供者之間傳遞，傳遞方式是透過 OSSL_DISPATCH(3) 陣列中的 OSSL_ALGORITHM(3) 陣列，而這些陣列是由提供者的 provider_query_operation() 函式傳回的 (請參閱 provider-base(7) 中的「提供者函式」)。

所有這些「函式」都有對應的函式類型定義，名稱為 OSSL_FUNC_{name}_fn，以及一個輔助函式，用於從 OSSL_DISPATCH(3) 元素中擷取函式指標，名稱為 OSSL_FUNC_{name}。例如，「函式」OSSL_FUNC_asym_cipher_newctx() 有這些

typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn
    OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) 陣列的索引是數字，這些數字在 openssl-core_dispatch.h(7) 中以巨集提供，如下所示

OSSL_FUNC_asym_cipher_newctx               OSSL_FUNC_ASYM_CIPHER_NEWCTX
OSSL_FUNC_asym_cipher_freectx              OSSL_FUNC_ASYM_CIPHER_FREECTX
OSSL_FUNC_asym_cipher_dupctx               OSSL_FUNC_ASYM_CIPHER_DUPCTX

OSSL_FUNC_asym_cipher_encrypt_init         OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT
OSSL_FUNC_asym_cipher_encrypt              OSSL_FUNC_ASYM_CIPHER_ENCRYPT

OSSL_FUNC_asym_cipher_decrypt_init         OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT
OSSL_FUNC_asym_cipher_decrypt              OSSL_FUNC_ASYM_CIPHER_DECRYPT

OSSL_FUNC_asym_cipher_get_ctx_params       OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS
OSSL_FUNC_asym_cipher_gettable_ctx_params  OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS
OSSL_FUNC_asym_cipher_set_ctx_params       OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS
OSSL_FUNC_asym_cipher_settable_ctx_params  OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS

非對稱加密演算法實作可能不會實作所有這些函式。為了讓函式組保持一致，提供者必須實作 OSSL_FUNC_asym_cipher_newctx 和 OSSL_FUNC_asym_cipher_freectx。它還必須同時實作 OSSL_FUNC_asym_cipher_encrypt_init 和 OSSL_FUNC_asym_cipher_encrypt，或同時實作 OSSL_FUNC_asym_cipher_decrypt_init 和 OSSL_FUNC_asym_cipher_decrypt。OSSL_FUNC_asym_cipher_get_ctx_params 是選用的，但如果存在，則 OSSL_FUNC_asym_cipher_gettable_ctx_params 也必須存在。類似地，OSSL_FUNC_asym_cipher_set_ctx_params 是選用的，但如果存在，則 OSSL_FUNC_asym_cipher_settable_ctx_params 也必須存在。

非對稱加密演算法也必須實作某種機制，透過金鑰管理 (OSSL_OP_KEYMGMT) 作業來產生、載入或匯入金鑰。請參閱 provider-keymgmt(7) 以取得進一步詳細資料。

內容管理函式

OSSL_FUNC_asym_cipher_newctx() 應該建立一個指標，指向提供者端結構，用於在非對稱加密作業期間儲存內容資訊，並傳回該指標。這個內容的指標將在其他許多非對稱加密作業函式呼叫中傳回。參數 provctx 是在提供者初始化期間產生的提供者內容 (請參閱 provider(7))。

OSSL_FUNC_asym_cipher_freectx() 會在 ctx 參數中傳遞一個指標，指向提供者端的非對稱加密內容。此函式應該釋放與該內容相關聯的任何資源。

OSSL_FUNC_asym_cipher_dupctx() 應複製 ctx 參數中的提供者端非對稱密碼文脈，並傳回複製的副本。

加密函式

OSSL_FUNC_asym_cipher_encrypt_init() 初始化非對稱加密的文脈，提供 ctx 參數中的提供者端非對稱密碼文脈，以及 provkey 參數中提供者金鑰物件的指標。如果 params 非 NULL，應以類似於使用 OSSL_FUNC_asym_cipher_set_ctx_params() 的方式設定在文脈中。金鑰物件應先前使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入提供者 (請參閱 provider-keymgmt(7))。OSSL_FUNC_asym_cipher_encrypt() 執行實際的加密。先前初始化的非對稱密碼文脈傳遞在 ctx 參數中。要加密的資料由 in 參數指向，其長度為 inlen 位元組。除非 out 為 NULL，否則應將加密資料寫入 out 參數指向的位置，且其長度不應超過 outsize 位元組。應將加密資料的長度寫入 *outlen。如果 out 為 NULL，則應將加密資料的最大長度寫入 *outlen。

解密函式

OSSL_FUNC_asym_cipher_decrypt_init() 初始化非對稱解密的文脈，提供 ctx 參數中的提供者端非對稱密碼文脈，以及 provkey 參數中提供者金鑰物件的指標。如果 params 非 NULL，應以類似於使用 OSSL_FUNC_asym_cipher_set_ctx_params() 的方式設定在文脈中。金鑰物件應先前使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入提供者 (請參閱 provider-keymgmt(7))。

OSSL_FUNC_asym_cipher_decrypt() 執行實際的解密。先前初始化的非對稱密碼文脈傳遞在 ctx 參數中。要解密的資料由 in 參數指向，其長度為 inlen 位元組。除非 out 為 NULL，否則應將解密資料寫入 out 參數指向的位置，且其長度不應超過 outsize 位元組。應將解密資料的長度寫入 *outlen。如果 out 為 NULL，則應將解密資料的最大長度寫入 *outlen。

非對稱密碼參數

請參閱 OSSL_PARAM(3) 以進一步了解 OSSL_FUNC_asym_cipher_get_ctx_params() 和 OSSL_FUNC_asym_cipher_set_ctx_params() 函式所使用的參數結構。

OSSL_FUNC_asym_cipher_get_ctx_params() 取得與給定的提供者端非對稱密碼文脈 ctx 相關的非對稱密碼參數，並將它們儲存在 params 中。傳遞 NULL 給 params 應傳回 true。

OSSL_FUNC_asym_cipher_set_ctx_params() 會將與給定的提供者端非對稱密碼演算法相關聯的非對稱密碼演算法參數設定為 params。任何參數設定都會附加到先前設定的任何參數。傳遞 NULL 給 params 應傳回 true。

內建非對稱密碼演算法目前辨識的參數如下。並非所有參數都與所有非對稱密碼演算法相關，或為所有非對稱密碼演算法所理解

"pad-mode" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <UTF8 字串> 或 <整數>

要使用的填補類型。此值的詮釋會根據使用的演算法而有所不同。

"digest" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 字串>

在使用 OAEP 填補時，取得或設定所使用的 OAEP 摘要演算法名稱。

"digest" (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 字串>

取得或設定演算法所使用的摘要演算法名稱（如適用）。

"digest-props" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 字串>

在擷取 OAEP 摘要演算法時，取得或設定要使用的屬性。

"digest-props" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 字串>

在擷取密碼摘要演算法時，取得或設定要使用的屬性。

"mgf1-digest" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 字串>

在使用 OAEP 或 PSS 填補時，取得或設定所使用的 MGF1 摘要演算法名稱。

"mgf1-digest-props" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8 字串>

在擷取 MGF1 摘要演算法時，取得或設定要使用的屬性。

"oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <八位元組字串指標>

在使用 OAEP 填補時，取得所使用的 OAEP 標籤。

"oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <八位元組字串>

在使用 OAEP 填補時，設定所使用的 OAEP 標籤。

"tls-client-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <未簽署整數>

客戶端首次要求的 TLS 協定版本。

"tls-negotiated-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <未簽署整數>

協商的 TLS 協定版本。

"implicit-rejection" (OSSL_PKEY_PARAM_IMPLICIT_REJECTION) <未簽署整數>

取得或設定 RSA PKCS#1 v1.5 解密所使用的隱式拒絕機制。設定時（非零值），如果 PKCS#1 v1.5 填補檢查失敗，解密 API 會傳回確定性亂數值。這會讓 Bleichenbacher 的利用變得更困難，即使使用 RSA 解密 API 的程式碼並未以無側信道的方式實作。預設設定。需要提供者支援。

OSSL_FUNC_asym_cipher_gettable_ctx_params() 和 OSSL_FUNC_asym_cipher_settable_ctx_params() 會取得一個常數 OSSL_PARAM(3) 陣列，用來描述可取得和可設定的參數，亦即可用於 OSSL_FUNC_asym_cipherget_ctx_params() 和 OSSL_FUNC_asym_cipher_set_ctx_params() 的參數。

傳回值

OSSL_FUNC_asym_cipher_newctx() 和 OSSL_FUNC_asym_cipher_dupctx() 應傳回新建立的提供者端非對稱密碼內容，或在失敗時傳回 NULL。

所有其他函式應傳回 1 表示成功，或在錯誤時傳回 0。

另請參閱

provider(7)

歷程

provider ASYM_CIPHER 介面於 OpenSSL 3.0 中引入。

Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.

根據 Apache License 2.0（「授權」）授權。您只能在遵守授權的條件下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案中取得一份副本，或在 https://www.openssl.org/source/license.html 取得。