消息摘要算法定义

这些数据结构定义了模块化的消息摘要算法实现，通过 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

发生