訊息摘要演算法定義¶

這些資料結構定義了模組化的訊息摘要演算法實現，透過 crypto_register_ahash()、crypto_register_shash()、crypto_unregister_ahash() 和 crypto_unregister_shash() 進行管理。

struct ahash_alg¶: 非同步訊息摘要定義

定義:

struct ahash_alg {
    int (*init)(struct ahash_request *req);
    int (*update)(struct ahash_request *req);
    int (*final)(struct ahash_request *req);
    int (*finup)(struct ahash_request *req);
    int (*digest)(struct ahash_request *req);
    int (*export)(struct ahash_request *req, void *out);
    int (*import)(struct ahash_request *req, const void *in);
    int (*export_core)(struct ahash_request *req, void *out);
    int (*import_core)(struct ahash_request *req, const void *in);
    int (*setkey)(struct crypto_ahash *tfm, const u8 *key, unsigned int keylen);
    int (*init_tfm)(struct crypto_ahash *tfm);
    void (*exit_tfm)(struct crypto_ahash *tfm);
    int (*clone_tfm)(struct crypto_ahash *dst, struct crypto_ahash *src);
    struct hash_alg_common halg;
};

成員

init: [mandatory] 初始化轉換上下文。僅用於在開始時初始化 HASH 轉換的狀態。這應填充整個轉換期間使用的內部結構。此時不進行資料處理。驅動程式程式碼實現不得使用 req->result。
update: [mandatory] 將資料塊推送到驅動程式以進行轉換。此函式實際上將來自上層的資料塊推送到驅動程式中，然後驅動程式將其傳遞給硬體。此函式不得透過計算最終訊息摘要來完成 HASH 轉換，因為這隻會向轉換中新增更多資料。此函式不得修改轉換上下文，因為可以與同一轉換物件並行呼叫此函式。資料處理可以在此時同步 [SHASH] 或非同步 [AHASH] 進行。驅動程式不得使用 req->result。對於僅塊演算法，update 必須返回要儲存在 API 部分塊緩衝區中的位元組數。
final: [mandatory] 從驅動程式檢索結果。此函式完成轉換並從驅動程式檢索結果雜湊，然後將其推回上層。除非硬體需要完成轉換（然後處理裝置驅動程式緩衝的資料），否則此時不進行資料處理。
finup: [optional] update 和 final 的組合。此函式實際上是按順序發出的 update 和 final 呼叫的組合。由於某些硬體無法單獨執行 update 和 final，因此添加了此回撥以允許至少 IPsec 使用此類硬體。資料處理可以在此時同步 [SHASH] 或非同步 [AHASH] 進行。
digest: init 和 update 和 final 的組合。此函式實際上充當整個操作鏈，即按順序發出的 init、update 和 final。就像 finup 一樣，新增此功能是為了硬體甚至無法執行 finup，但只能一次執行整個轉換。資料處理可以在此時同步 [SHASH] 或非同步 [AHASH] 進行。
export: 匯出轉換的部分狀態。此函式將正在進行的轉換的整個狀態轉儲到提供的資料塊中，以便稍後可以 import 回來。如果要儲存處理一定量資料後轉換的部分結果，並在以後多次重新載入此部分結果以進行多次重用，這將非常有用。此時不進行資料處理。驅動程式不得使用 req->result。
import: 匯入轉換的部分狀態。此函式從提供的資料塊載入正在進行的轉換的整個狀態，以便轉換可以從此點繼續。此時不進行資料處理。驅動程式不得使用 req->result。
export_core: 匯出沒有部分塊的部分狀態。僅為非僅塊演算法定義。
import_core: 匯入沒有部分塊的部分狀態。僅為非僅塊演算法定義。
setkey: 設定雜湊演算法使用的可選金鑰。旨在將雜湊演算法使用的可選金鑰從上層推送到驅動程式中。此函式可以將金鑰儲存在轉換上下文中，也可以直接將其程式設計到硬體中。在前一種情況下，必須小心地在適當的時間將金鑰程式設計到硬體中，並且必須小心 .setkey() 可以在轉換物件的存在期間多次呼叫。並非所有雜湊演算法都實現了此函式，因為它僅對金鑰訊息摘要是必需的。 SHAx/MDx/CRCx 不實現此函式。 HMAC(MDx)/HMAC(SHAx)/CMAC(AES) 實現了此函式。必須在呼叫任何其他 init、update、final、finup、digest 之前呼叫此函式。此時不進行資料處理。
init_tfm: 初始化加密轉換物件。此函式僅在例項化時呼叫一次，就在轉換上下文分配之後。如果加密硬體有一些需要軟體處理的特殊要求，則此函式應檢查轉換的精確要求，並放置任何軟體回退。
exit_tfm: 取消初始化加密轉換物件。這是 init_tfm 的對應物，用於刪除在 init_tfm 中設定的各種更改。
clone_tfm: 將轉換複製到新物件中，可能會分配記憶體。
halg: 請參閱 struct hash_alg_common

struct shash_alg¶: 同步訊息摘要定義

定義:

struct shash_alg {
    int (*init)(struct shash_desc *desc);
    int (*update)(struct shash_desc *desc, const u8 *data, unsigned int len);
    int (*final)(struct shash_desc *desc, u8 *out);
    int (*finup)(struct shash_desc *desc, const u8 *data, unsigned int len, u8 *out);
    int (*digest)(struct shash_desc *desc, const u8 *data, unsigned int len, u8 *out);
    int (*export)(struct shash_desc *desc, void *out);
    int (*import)(struct shash_desc *desc, const void *in);
    int (*export_core)(struct shash_desc *desc, void *out);
    int (*import_core)(struct shash_desc *desc, const void *in);
    int (*setkey)(struct crypto_shash *tfm, const u8 *key, unsigned int keylen);
    int (*init_tfm)(struct crypto_shash *tfm);
    void (*exit_tfm)(struct crypto_shash *tfm);
    int (*clone_tfm)(struct crypto_shash *dst, struct crypto_shash *src);
    unsigned int descsize;
    union {
        struct HASH_ALG_COMMON;
        struct hash_alg_common halg;
    };
};

成員

init: 請參閱 struct ahash_alg
update: 請參閱 struct ahash_alg
final: 請參閱 struct ahash_alg
finup: 請參閱 struct ahash_alg
digest: 請參閱 struct ahash_alg
export: 請參閱 struct ahash_alg
import: 請參閱 struct ahash_alg
export_core: 請參閱 struct ahash_alg
import_core: 請參閱 struct ahash_alg
setkey: 請參閱 struct ahash_alg
init_tfm: 初始化加密轉換物件。此函式僅在例項化時呼叫一次，就在轉換上下文分配之後。如果加密硬體有一些需要軟體處理的特殊要求，則此函式應檢查轉換的精確要求，並放置任何軟體回退。
exit_tfm: 取消初始化加密轉換物件。這是 init_tfm 的對應物，用於刪除在 init_tfm 中設定的各種更改。
clone_tfm: 將轉換複製到新物件中，可能會分配記憶體。
descsize: 訊息摘要的操作狀態的大小。此狀態大小是需要為 shash_desc.__ctx 分配的記憶體大小
{unnamed_union}: anonymous
HASH_ALG_COMMON: 請參閱 struct hash_alg_common
halg: 請參閱 struct hash_alg_common

非同步訊息摘要 API¶

非同步訊息摘要 API 與 CRYPTO_ALG_TYPE_AHASH 型別的密碼一起使用（在 /proc/crypto 中列為 “ahash” 型別）

為 CRYPTO_ALG_TYPE_SKCIPHER API 提供的非同步密碼操作討論也適用於此處。

struct crypto_ahash *crypto_alloc_ahash(const char *alg_name, u32 type, u32 mask)¶: 分配 ahash 密碼控制代碼

引數

const char *alg_name: 是 ahash 密碼的 cra_name / name 或 cra_driver_name / driver name
u32 type: 指定密碼的型別
u32 mask: 指定密碼的掩碼

描述

為 ahash 分配密碼控制代碼。返回的 struct crypto_ahash 是任何後續 API 呼叫該 ahash 所需的密碼控制代碼。

返回

在成功的情況下分配的密碼控制代碼；如果 IS_ERR() 為 true，則: 出現錯誤，PTR_ERR() 返回錯誤程式碼。

void crypto_free_ahash(struct crypto_ahash *tfm)¶: 清零並釋放 ahash 控制代碼

引數

struct crypto_ahash *tfm: 要釋放的密碼控制代碼

描述

如果 tfm 是 NULL 或錯誤指標，則此函式不執行任何操作。

unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm)¶: 獲取訊息摘要大小

引數

struct crypto_ahash *tfm: 密碼控制代碼

描述

返回使用密碼控制代碼引用的訊息摘要密碼建立的訊息摘要的大小。

返回

密碼的訊息摘要大小

unsigned int crypto_ahash_statesize(struct crypto_ahash *tfm)¶: 獲取 ahash 狀態的大小

引數

struct crypto_ahash *tfm: 密碼控制代碼

描述

返回 ahash 狀態的大小。使用 crypto_ahash_export() 函式，呼叫者可以將狀態匯出到緩衝區中，該緩衝區的大小使用此函式定義。

返回

ahash 狀態的大小

struct crypto_ahash *crypto_ahash_reqtfm(struct ahash_request *req)¶: 從請求獲取密碼控制代碼

引數

struct ahash_request *req: 非同步請求控制代碼，其中包含對 ahash 密碼控制代碼的引用

描述

返回註冊到非同步請求控制代碼 ahash_request 的 ahash 密碼控制代碼。

返回

ahash 密碼控制代碼

unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm)¶: 獲取請求資料結構的大小

引數

struct crypto_ahash *tfm: 密碼控制代碼

返回

請求資料的大小

int crypto_ahash_setkey(struct crypto_ahash *tfm, const u8 *key, unsigned int keylen)¶: 為密碼控制代碼設定金鑰

引數

struct crypto_ahash *tfm: 密碼控制代碼
const u8 *key: 儲存金鑰的緩衝區
unsigned int keylen: 金鑰的長度（以位元組為單位）

描述

為 ahash 密碼設定呼叫者提供的金鑰。密碼控制代碼必須指向金鑰雜湊，此函式才能成功。

返回

如果金鑰設定成功，則為 0；如果發生錯誤，則為 < 0

int crypto_ahash_finup(struct ahash_request *req)¶: 更新並完成訊息摘要

引數

struct ahash_request *req: 引用 ahash_request 控制代碼，該控制代碼儲存執行密碼操作所需的所有資訊

描述

此函式是 crypto_ahash_update 和 crypto_ahash_final 函式呼叫的“簡寫”。這些引數的含義與為這些單獨函式討論的含義相同。

返回

請參閱 crypto_ahash_final()

int crypto_ahash_final(struct ahash_request *req)¶: 計算訊息摘要

引數

struct ahash_request *req: 引用 ahash_request 控制代碼，該控制代碼儲存執行密碼操作所需的所有資訊

描述

完成訊息摘要操作並基於新增到密碼控制代碼的所有資料建立訊息摘要。訊息摘要放置在使用 ahash_request 控制代碼註冊的輸出緩衝區中。

返回

如果訊息摘要計算成功，則為 0；如果資料被饋送到硬體 (DMA) 或排隊以供稍後使用，則為 -EINPROGRESS；如果佇列已滿且應稍後重新提交請求，則為 -EBUSY；如果發生錯誤，則為其他 < 0

int crypto_ahash_digest(struct ahash_request *req)¶: 計算緩衝區的訊息摘要

引數

struct ahash_request *req: 引用 ahash_request 控制代碼，該控制代碼儲存執行密碼操作所需的所有資訊

描述

此函式是 crypto_ahash_init、crypto_ahash_update 和 crypto_ahash_final 函式呼叫的“簡寫”。這些引數的含義與為這三個單獨函式討論的含義相同。

返回

請參閱 crypto_ahash_final()

int crypto_ahash_export(struct ahash_request *req, void *out)¶: 提取當前訊息摘要狀態

引數

struct ahash_request *req: 引用其狀態被匯出的 ahash_request 控制代碼
void *out: 具有足夠大小的輸出緩衝區，可以儲存雜湊狀態

描述

此函式將 ahash_request 控制代碼的雜湊狀態匯出到呼叫者分配的輸出緩衝區 out 中，該緩衝區必須具有足夠的大小（例如，透過呼叫 crypto_ahash_statesize()）。

返回

如果匯出成功，則為 0；如果發生錯誤，則為 < 0

int crypto_ahash_import(struct ahash_request *req, const void *in)¶: 匯入訊息摘要狀態

引數

struct ahash_request *req: 引用將匯入狀態的 ahash_request 控制代碼
const void *in: 儲存狀態的緩衝區

描述

此函式將雜湊狀態從輸入緩衝區匯入到 ahash_request 控制代碼中。該緩衝區應已使用 crypto_ahash_export 函式生成。

返回

如果匯入成功，則為 0；如果發生錯誤，則為 < 0

int crypto_ahash_init(struct ahash_request *req)¶: （重新）初始化訊息摘要控制代碼

引數

struct ahash_request *req: ahash_request 控制代碼，已使用 ahash_request_* API 函式使用所有必要資料進行初始化

描述

呼叫（重新）初始化 ahash_request 控制代碼引用的訊息摘要。丟棄先前操作建立的任何可能存在的狀態。

返回

請參閱 crypto_ahash_final()

非同步雜湊請求控制代碼¶

ahash_request 資料結構包含非同步密碼操作所需的所有資料指標。這包括密碼控制代碼（可由多個 ahash_request 例項使用）、指向明文和訊息摘要輸出緩衝區的指標、非同步回撥函式等。它充當 ahash_request_* API 呼叫的控制代碼，類似於 ahash 控制代碼到 crypto_ahash_* API 呼叫的控制代碼。

void ahash_request_set_tfm(struct ahash_request *req, struct crypto_ahash *tfm)¶: 更新請求中的密碼控制代碼引用

引數

struct ahash_request *req: 要修改的請求控制代碼
struct crypto_ahash *tfm: 要新增到請求控制代碼的密碼控制代碼

描述

允許呼叫者使用不同的密碼控制代碼替換請求資料結構中現有的 ahash 控制代碼。

struct ahash_request *ahash_request_alloc(struct crypto_ahash *tfm, gfp_t gfp)¶: 分配請求資料結構

引數

struct crypto_ahash *tfm: 要使用請求註冊的密碼控制代碼
gfp_t gfp: 記憶體分配標誌，由 API 呼叫傳遞給 kmalloc。

描述

分配必須與 ahash 訊息摘要 API 呼叫一起使用的請求資料結構。在分配期間，提供的 ahash 控制代碼在請求資料結構中註冊。

返回

在成功的情況下分配的請求控制代碼，如果記憶體不足，則為 NULL

void ahash_request_free(struct ahash_request *req)¶: 清零並釋放請求資料結構

引數

struct ahash_request *req: 要釋放的請求資料結構密碼控制代碼

void ahash_request_set_callback(struct ahash_request *req, u32 flags, crypto_completion_t compl, void *data)¶: 設定非同步回撥函式

引數

struct ahash_request *req: 請求控制代碼
u32 flags: 指定零或標誌 CRYPTO_TFM_REQ_MAY_BACKLOG 的 ORing 請求佇列可能會積壓，並將等待佇列增加到超出初始最大大小； CRYPTO_TFM_REQ_MAY_SLEEP 請求處理可能會休眠
crypto_completion_t compl: 要使用請求控制代碼註冊的回撥函式指標
void *data: 資料指標引用核心加密 API 未使用的記憶體，而是提供給回撥函式以供使用。在這裡，呼叫者可以提供對回撥函式可以操作的記憶體的引用。由於回撥函式與相關功能非同步呼叫，因此可能需要訪問可以使用此指標引用的相關功能的資料結構。回撥函式可以透過提供給回撥函式的 crypto_async_request 資料結構中的“data”欄位訪問記憶體。

描述

此函式允許設定密碼操作完成後觸發的回撥函式。

回撥函式使用 ahash_request 控制代碼註冊，並且必須符合以下模板

void callback_function(struct crypto_async_request *req, int error)

void ahash_request_set_crypt(struct ahash_request *req, struct scatterlist *src, u8 *result, unsigned int nbytes)¶: 設定資料緩衝區

引數

struct ahash_request *req: 要更新的 ahash_request 控制代碼
struct scatterlist *src: 源分散/收集列表
u8 *result: 用訊息摘要填充的緩衝區 - 呼叫者必須確保緩衝區具有足夠的空間，例如，透過呼叫 crypto_ahash_digestsize()
unsigned int nbytes: 要從源分散/收集列表處理的位元組數

描述

透過使用此呼叫，呼叫者引用源分散/收集列表。源分散/收集列表指向要計算訊息摘要的資料。

同步訊息摘要 API¶

同步訊息摘要 API 與 CRYPTO_ALG_TYPE_SHASH 型別的密碼一起使用（在 /proc/crypto 中列為 “shash” 型別）

訊息摘要 API 能夠維護呼叫者的狀態資訊。

同步訊息摘要 API 可以在其 shash_desc 請求資料結構中儲存使用者相關上下文。

struct crypto_shash *crypto_alloc_shash(const char *alg_name, u32 type, u32 mask)¶: 分配訊息摘要控制代碼

引數

const char *alg_name: 是訊息摘要密碼的 cra_name / name 或 cra_driver_name / driver name
u32 type: 指定密碼的型別
u32 mask: 指定密碼的掩碼

描述

為訊息摘要分配密碼控制代碼。返回的 struct crypto_shash 是該訊息摘要任何後續 API 呼叫所需的密碼控制代碼。

返回

在成功的情況下分配的密碼控制代碼；如果 IS_ERR() 為 true，則: 出現錯誤，PTR_ERR() 返回錯誤程式碼。

void crypto_free_shash(struct crypto_shash *tfm)¶: 清零並釋放訊息摘要控制代碼

引數

struct crypto_shash *tfm: 要釋放的密碼控制代碼

描述

如果 tfm 是 NULL 或錯誤指標，則此函式不執行任何操作。

unsigned int crypto_shash_blocksize(struct crypto_shash *tfm)¶: 獲取密碼的塊大小

引數

struct crypto_shash *tfm: 密碼控制代碼

描述

返回使用密碼控制代碼引用的訊息摘要密碼的塊大小。

返回

密碼的塊大小

unsigned int crypto_shash_digestsize(struct crypto_shash *tfm)¶: 獲取訊息摘要大小

引數

struct crypto_shash *tfm: 密碼控制代碼

描述

返回使用密碼控制代碼引用的訊息摘要密碼建立的訊息摘要的大小。

返回

密碼的摘要大小

unsigned int crypto_shash_descsize(struct crypto_shash *tfm)¶: 獲取操作狀態大小

引數

struct crypto_shash *tfm: 密碼控制代碼

描述

返回密碼在操作期間所需的操作狀態的大小，該密碼使用密碼控制代碼引用。需要此大小才能計算記憶體需求，以允許呼叫者為操作狀態分配足夠的記憶體。

操作狀態使用 struct shash_desc 定義，其中該資料結構的大小將計算為 sizeof(struct shash_desc) + crypto_shash_descsize(alg)

返回

操作狀態的大小

int crypto_shash_setkey(struct crypto_shash *tfm, const u8 *key, unsigned int keylen)¶: 為訊息摘要設定金鑰

引數

struct crypto_shash *tfm: 密碼控制代碼
const u8 *key: 儲存金鑰的緩衝區
unsigned int keylen: 金鑰的長度（以位元組為單位）

描述

呼叫者提供的金鑰已設定為帶金鑰的訊息摘要密碼。密碼控制代碼必須指向一個帶金鑰的訊息摘要密碼，此函式才能成功。

上下文

軟中斷或程序上下文。

返回

如果金鑰設定成功，則為 0；如果發生錯誤，則為 < 0

int crypto_shash_digest(struct shash_desc *desc, const u8 *data, unsigned int len, u8 *out)¶: 計算緩衝區的訊息摘要

引數

struct shash_desc *desc: 請參閱 crypto_shash_final()
const u8 *data: 請參閱 crypto_shash_update()
unsigned int len: 請參閱 crypto_shash_update()
u8 *out: 請參閱 crypto_shash_final()

描述

此函式是 crypto_shash_init、crypto_shash_update 和 crypto_shash_final 函式呼叫的“簡寫”。這些引數的含義與針對這三個單獨函式討論的含義相同。

上下文

軟中斷或程序上下文。

返回

如果訊息摘要建立成功，則為 0；如果發生錯誤，則 < 0: 發生

int crypto_shash_export(struct shash_desc *desc, void *out)¶: 提取訊息摘要的運算狀態

引數

struct shash_desc *desc: 指向要匯出狀態的運算狀態控制代碼的引用
void *out: 具有足夠大小的輸出緩衝區，可以儲存雜湊狀態

描述

此函式將運算狀態控制代碼的雜湊狀態匯出到呼叫者分配的輸出緩衝區 out 中，該緩衝區必須具有足夠的尺寸（例如，透過呼叫 crypto_shash_descsize）。

上下文

軟中斷或程序上下文。

返回

如果匯出建立成功，則為 0；如果發生錯誤，則 < 0

int crypto_shash_import(struct shash_desc *desc, const void *in)¶: 匯入運算狀態

引數

struct shash_desc *desc: 指向要匯入狀態的運算狀態控制代碼的引用
const void *in: 儲存狀態的緩衝區

描述

此函式將雜湊狀態從輸入緩衝區匯入到運算狀態控制代碼中。該緩衝區應已使用 crypto_ahash_export 函式生成。

上下文

軟中斷或程序上下文。

返回

如果匯入成功，則為 0；如果發生錯誤，則為 < 0

int crypto_shash_init(struct shash_desc *desc)¶: （重新）初始化訊息摘要

引數

struct shash_desc *desc: 已填充的運算狀態控制代碼

描述

呼叫會（重新）初始化運算狀態控制代碼引用的訊息摘要。由先前操作建立的任何可能存在的狀態都將被丟棄。

上下文

軟中斷或程序上下文。

返回

如果訊息摘要初始化成功，則為 0；如果出現錯誤，則 < 0: 發生錯誤

int crypto_shash_finup(struct shash_desc *desc, const u8 *data, unsigned int len, u8 *out)¶: 計算緩衝區的訊息摘要

引數

struct shash_desc *desc: 請參閱 crypto_shash_final()
const u8 *data: 請參閱 crypto_shash_update()
unsigned int len: 請參閱 crypto_shash_update()
u8 *out: 請參閱 crypto_shash_final()

描述

此函式是 crypto_shash_update 和 crypto_shash_final 函式呼叫的“簡寫”。這些引數的含義與針對這些單獨函式討論的含義相同。

上下文

軟中斷或程序上下文。

返回

如果訊息摘要建立成功，則為 0；如果發生錯誤，則 < 0: 發生

int crypto_shash_update(struct shash_desc *desc, const u8 *data, unsigned int len)¶: 將資料新增到訊息摘要以進行處理

引數

struct shash_desc *desc: 已初始化的運算狀態控制代碼
const u8 *data: 要新增到訊息摘要的輸入資料
unsigned int len: 輸入資料的長度

描述

更新運算狀態控制代碼的訊息摘要狀態。

上下文

軟中斷或程序上下文。

返回

如果訊息摘要更新成功，則為 0；如果出現錯誤，則 < 0: 發生

int crypto_shash_final(struct shash_desc *desc, u8 *out)¶: 計算訊息摘要

引數

struct shash_desc *desc: 已填充資料的運算狀態控制代碼
u8 *out: 填充了訊息摘要的輸出緩衝區

描述

完成訊息摘要操作，並根據新增到密碼控制代碼的所有資料建立訊息摘要。訊息摘要放置在輸出緩衝區中。呼叫者必須透過使用 crypto_shash_digestsize 來確保輸出緩衝區足夠大。

上下文

軟中斷或程序上下文。

返回

如果訊息摘要建立成功，則為 0；如果發生錯誤，則 < 0: 發生

Linux 核心

目錄

本頁

訊息摘要演算法定義¶

非同步訊息摘要 API¶

非同步雜湊請求控制代碼¶

同步訊息摘要 API¶