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)（以及解密等效函式和其他相關函式）讓應用程式使用。
此處提到的所有「函式」都以函式指標的形式在 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_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 位元組。與 EVP_EncryptFinal(3) 和 EVP_DecryptFinal(3) 所記錄的 outsize 適用相同的預期。
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() 會傳回與提供者端文脈 cctx 相關聯的參數，並維持其目前狀態。否則，它們會傳回與提供者端演算法 provctx 相關聯的參數。
內建密碼文目前辨識的參數會列於 EVP_EncryptInit(3) 中的「PARAMETERS」。並非所有參數都與所有密碼文相關，或為所有密碼文所理解。
傳回值
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 中引入。
版權
Copyright 2019-2023 The OpenSSL Project Authors。保留所有權利。
根據 Apache 授權條款 2.0（「授權條款」）授權。您不得在不遵守授權條款的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案中取得副本，或在 https://www.openssl.org/source/license.html 取得副本。