在铜锁中使用 SM2&SM3&SM4 算法的教程

铜锁提供了一系列API来支持应用程序使用 SM2，SM3 和 SM4 算法。本文对这些用法进行整理，以方面用户更好的参考使用。

为了节省篇幅，头文件统一描述。

#include <openssl/evp.h>
#include <openssl/err.h>
#include <openssl/ec.h>

SM2

SM2 算法涉及的操作有：密钥生成、加密、解密、签名、验签

SM2密钥生成

SM2 的密钥是一个公私钥对，根据铜锁版本的不同，SM2 密钥对的生成也存在区别。铜锁中使用 EVP_PKEY 数据结构来表示一对 SM2 密钥，该结构同时存放 SM2 的私钥和公钥。

铜锁 8.3.x 和 8.2.x 系列

采用传统的 OpenSSL 风格的非对称密钥生成方式进行 SM2 的密钥生成

EVP_PKEY_CTX *sm2_ctx = NULL;
EVP_PKEY *sm2_key = NULL;

sm2_ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_EC, NULL);
if (sm2_ctx == NULL) {
    /* 错误处理 */
}
if (!EVP_PKEY_keygen_init(sm2_ctx)) {
    /* 错误处理 */
}
if (!EVP_PKEY_CTX_set_ec_paramgen_curve_nid(sm2_ctx, OBJ_sn2nid("SM2"))) {
    /* 错误处理 */
}
if (!EVP_PKEY_keygen(sm2_ctx, &sm2_key)) {
    /* 错误处理 */
}
if (!EVP_PKEY_set_alias_type(sm2_key, EVP_PKEY_SM2)) {
    /* 错误处理 */
}

铜锁 8.4.x 系列

铜锁 8.4.0 提供了简易的 API 来实现 SM2 密钥对的生成

EVP_PKEY *sm2_key = NULL;

sm2_key = EVP_PKEY_Q_keygen(NULL, NULL, "SM2");
if (sm2_key == NULL) {
    /* 错误处理 */
}

执行成功之后，就可以获得一个可在后续使用的 EVP_PKEY 结构。

此外，8.4.x 版本的铜锁，也兼容 8.3.x 和 8.2.x 版本的 SM2 密钥生成方式。

导出密钥

如果需要将内存中的密钥（EVP_PKEY）导出到文件，例如常用的PEM格式，则可使用：PEM_write_bio_PrivateKey 函数进行导出。

导入密钥

相比于直接生成新的 SM2 密钥对，一种更加常见的方式可能是从现有的密钥文件中读取密钥（例如公钥或者私钥）。TBD...

SM2 加密

在拥有 SM2 密钥（即 EVP_PKEY 对象）之后，就可以使用该密钥进行一系列的 SM2 密码学原语操作。现在从 SM2 加密算法开始，介绍 EVP_PKEY 对象的使用方式。

EVP_PKEY_CTX *pctx = NULL;
unsigned char msg[] = "Winter Is Coming";
unsigned char *out = NULL;
size_t outlen = 0, inlen = 0;

/* 假设sm2_key已经提前设置好 */

pctx = EVP_PKEY_CTX_new(sm2_key, NULL);
if (pctx == NULL) {
    /* 错误处理 */
}
if (EVP_PKEY_encrypt_init(pctx) <= 0) {
    /* 错误处理 */
}
inlen = strlen((char *)msg);
if (EVP_PKEY_encrypt(pctx, NULL, &outlen, msg, inlen) <= 0) {
    /* 错误处理 */
}
out = OPENSSL_malloc(outlen);
if (out == NULL) {
    /* 错误处理 */
}
if (EVP_PKEY_encrypt(pctx, out, &outlen, msg, inlen) <= 0) {
    /* 错误处理 */
}
EVP_PKEY_CTX_free(pctx);
EVP_PKEY_free(sm2_key);

其中，在铜锁中公钥密码学算法的操作和运算，是基于EVP_PKEY_CTX对象展开的。因此首先需要基于EVP_PKEY创建一个EVP_PKEY_CTX，即上例中的pctx变量，然后对pctx进行加密初始化。上例中，明文消息被存放在msg变量中，是一个字符串，当然也可以是任何其他的数据或内容。然后是一个典型的两次调用过程，即对实际的加密函数EVP_PKEY_encrypt进行两次调用，第一次调用时密文buffer为空，旨在获取加密后的密文长度，然后根据此长度进行内存分配，即上例中对out指针分配内存。第二次调用是实际执行的SM2加密操作，即对明文msg，使用sm2_key进行加密，得到密文out。

SM2 解密

SM2 的解密操作和 SM2 加密操作类似，几乎就是将 encrypt 的相关函数替换为解密的 decrypt 函数。

EVP_PKEY_CTX *pctx = NULL;
unsigned char *out = NULL;
size_t outlen = 0, inlen = 0;

/* 假设sm2_key, 密文cipher_text, 密文长度inlen已经提前准备好 */
pctx = EVP_PKEY_CTX_new(sm2_key, NULL);
if (pctx == NULL) {
    /* 错误处理 */
}
if (EVP_PKEY_decrypt_init(pctx) <= 0) {
    /* 错误处理 */
}
if (EVP_PKEY_decrypt(pctx, NULL, &outlen, cipher_text, inlen) <= 0) {
    /* 错误处理 */
}
out = OPENSSL_malloc(outlen);
if (out == NULL) {
    /* 错误处理 */
}
if (EVP_PKEY_decrypt(pctx, out, &outlen, cipher_text, inlen) <= 0) {
    /* 错误处理 */
}
EVP_PKEY_CTX_free(pctx);
EVP_PKEY_free(sm2_key);

由上例可见，SM2 解密的流程和加密类似，经过两次调用 EVP_PKEY_decrypt 实现对密文的解密，解密后的明文存放在 out 指向的内存中。对于不再需要使用的 PKEY 和 PKEY_CTX，需要显式的调用对应的 _free 函数进行释放。

SM2 签名

SM2 签名操作的整体流程类似于加密操作。

EVP_PKEY_CTX *pctx = NULL;
unsigned char md[EVP_MAX_MD_SIZE];
unsigned char *sig = NULL;
size_t mdlen = EVP_MAX_MD_SIZE, siglen = 0;

/* 假设sm2_key, md, mdlen已经提前准备好*/
pctx = EVP_PKEY_CTX_new(sm2_key, NULL);
if (pctx == NULL) {
    /* 错误处理 */
}
if (EVP_PKEY_sign_init(pctx) <= 0) {
    /* 错误处理 */
}
if (EVP_PKEY_sign(pctx, NULL, &siglen, md, mdlen) <= 0) {
    /* 错误处理 */
}
sig = OPENSSL_malloc(siglen);
if (sig == NULL) {
    /* 错误处理 */
}
if (EVP_PKEY_sign(pctx, sig, &siglen, md, mdlen) <= 0) {
    /* 错误处理 */
}

整个流程也是调用两次 EVP_PKEY_sign，对 md 中存储的数据进行签名。这里用 md，是 message digest 的意思，即对消息的摘要进行签名，是目前SM2签名算法的典型使用方式。得到的签名值会存储在 sig 指针所指向的内存中，其长度为 siglen。在使用的时候一般会将消息原文和签名值共同发出，供接收方验签使用。

SM2 验签

SM2 验签是针对 SM2 签名和原文进行验证的过程，因此输入的数据需要有原文和签名值，返回的结果是成功或失败，其中成功是指经过SM2验签发现原文没有被篡改，签名值 OK。失败则代表验签出现了问题，原文可能被篡改、或签名值损坏等原因导致。

EVP_PKEY sm2_key；
EVP_PKEY_CTX *pctx;
unsigned char *md, *sig;
size_t mdlen, siglen;

/* 假设sm2_key, md, mdlen, sig, siglen都已经准备好 */
EVP_PKEY_CTX_free(pctx);
pctx = EVP_PKEY_CTX_new(sm2_key, NULL);
if (pctx == NULL) {
    /* 错误处理 */
}
if (EVP_PKEY_verify_init(pctx) <= 0) {
    /* 错误处理 */
}
ret = EVP_PKEY_verify(pctx, sig, siglen, md, mdlen);
if (ret == 1) {
    /* 验签成功 */
} else if (ret == 0) {
    /* 验签失败 */
} else if (ret < 0) {
    /* 错误处理 */
} else {
    /* will never happen */
}

SM2 验签的整体流程类似于签名流程，唯一值得注意的事 EVP_PKEY_verify 函数的返回值。不同于其他函数，EVP_PKEY_verify 返回值只有在小于0的时候，才是发生了错误，需要进行错误处理。而返回0的时候，则只是说明验签失败，而非其他常规错误。

SM3

SM3 是计算消息摘要的商用密码算法，也叫做密码杂凑算法或哈希算法。SM3算法不需要密钥，可直接针对消息进行计算从而得到其摘要值。根据铜锁版本的不同，SM3算法也有不同的使用方式。

铜锁 8.3.x 和 8.2.x 系列

EVP_MD_CTX *mdctx = NULL;
unsigned int mdlen = 0;

/* 假设msg, inlen, md都已设置好 */
mdctx = EVP_MD_CTX_new();
if (mdctx == NULL) {
    /* 错误处理 */
}
if (!EVP_DigestInit_ex(mdctx, EVP_sm3(), NULL)) {
    /* 错误处理 */
}
if (!EVP_DigestUpdate(mdctx, msg, inlen)) {
    /* 错误处理 */
}
if (!EVP_DigestFinal_ex(mdctx, md, &mdlen)) {
    /* 错误处理 */
}
EVP_MD_CTX_free(mdctd);

其中，EVP_DigestUpdate 可以调用多次，实现对数据流进行哈希。

铜锁 8.4.x 系列

unsigned char data[] = "Winter Is Coming", *md;
size_t len = 0, mdlen = 0;

/* 假设各项数据都已经准备好 */
if (!EVP_Q_digest(NULL, "SM3", NULL, data, len, md, &mdlen)) {
    /* 错误处理 */
}

在 8.4.x 的铜锁中也可以时候用老版本的方式进行SM3计算，例如进行流式数据输入的场景下。

SM4

SM4 是分组加密算法，因此存在加密和解密两种计算。但是因为分组加密涉及到加密模式的问题（mode of operation），尤其是对 AEAD 相关模式的使用，也存在不用的调用方式，因此需要额外注意。

SM4加密

非AEAD模式

即诸如 ECB，CBC 等模式的使用方式。

EVP_CIPHER_CTX *sm4_ctx = NULL;
unsigned char key[] = { 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF,
                        0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54, 0x32, 0x10 };
unsigned char iv[] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 
                       0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F };

/* 假设msg, msglen, out, outlen均定义完毕 */
sm4_ctx = EVP_CIPHER_CTX_new();
if (sm4_ctx == NULL) {
    /* 错误处理 */
}
if (!EVP_EncryptInit_ex(sm4_ctx, EVP_sm4_cbc(), NULL, key, iv)) {
    /* 错误处理 */
}
if (!EVP_EncryptUpdate(sm4_ctx, out, (int *)&outlen, msg, msglen)) {
    /* 错误处理 */
}
if (!EVP_EncryptFinal_ex(sm4_ctx, out + outlen, (int *)&tmplen)) {
    /* 错误处理 */
}
EVP_CIPHER_CTX_free(sm4_ctx);

SM4 算法的密钥是16个字节长，即128位。在上例中，因为使用了CBC模式，因此还需要额外准备IV值。SM4加密的整体流程也是Init-Update-Final的形式。如果需要使用其他加密模式，则需对应调整 EVP_sm4_cbc() 函数为其他模式，例如 EVP_sm4_ecb 等。

AEAD 模式

铜锁支持的 SM4 的 AEAD 模式有 GCM 和 CCM。这两种模式在铜锁中的加密方式基本类似于非 AEAD 模式，但是由于 AEAD 增加了额外的认证信息，因此需要增加新的 API。

unsigned char key[] = { 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF,
                        0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54, 0x32, 0x10 };
unsigned char iv_gcm[] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 
                           0x08, 0x09, 0x0A, 0x0B };
unsigned char aad[] = "Winter has come";
size_t aadlen = strlen((char *)aad);
unsigned char tag[16];

sm4_ctx = EVP_CIPHER_CTX_new();
if (sm4_ctx == NULL) {
    /* 错误处理 */
}
if (!EVP_EncryptInit_ex(sm4_ctx, EVP_sm4_gcm(), NULL, key, iv)) {
    /* 错误处理 */
}
if (!EVP_EncryptUpdate(sm4_ctx, NULL, (int *)&outlen, aad, aadlen)) {
    /* 错误处理 */
}
if (!EVP_EncryptUpdate(sm4_ctx, out, (int *)&outlen, msg, msglen)) {
    /* 错误处理 */
}
if (!EVP_EncryptFinal_ex(sm4_ctx, out + outlen, (int *)&tmplen)) {
    /* 错误处理 */
}
if (!EVP_CIPHER_CTX_ctrl(sm4_ctx, EVP_CTRL_GCM_GET_TAG, 16, tag)) {
    /* 错误处理 */
}
EVP_CIPHER_CTX_free(sm4_ctx);

以 SM4 GCM 为例，在上例中，主要有两处需要注意之处。第一点是在out设置为NULL的情况下调用 EVP_EncryptUpdate 函数设置 AAD（即Additional Authenticated Data），此步骤为可选，即可以不提供 AAD。第二点就是需要使用 EVP_CIPHER_CTX_ctrl 获取tag。这个tag将在解密的时候来判断密文是否被篡改。

SM4解密

非AEAD模式

非 AEAD 模式下的 SM4 算法的解密流程和加密一致，只不过把 encrypt 函数替换成对应的 decrypt 函数即可。为了节省篇幅，这里就不赘述。

AEAD 模式

因为涉及到 tag 的使用，因此 AEAD 模式的解密，例如 GCM，需要额外对 tag 进行处理。

unsigned char key[] = { 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF,
                        0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54, 0x32, 0x10 };
unsigned char iv_gcm[] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 
                           0x08, 0x09, 0x0A, 0x0B };
unsigned char aad[] = "Winter has come";
size_t aadlen = strlen((char *)aad);

/* 假设tag已从额外渠道获取 */
sm4_ctx = EVP_CIPHER_CTX_new();
if (sm4_ctx == NULL) {
    /* 错误处理 */
}
if (!EVP_DecryptInit_ex(sm4_ctx, EVP_sm4_gcm(), NULL, key, iv)) {
    /* 错误处理 */
}
if (!EVP_DecryptUpdate(sm4_ctx, NULL, (int *)&outlen, aad, aadlen)) {
    /* 错误处理 */
}
if (!EVP_DecryptUpdate(sm4_ctx, out, (int *)&outlen, msg, msglen)) {
    /* 错误处理 */
}
if (!EVP_CIPHER_CTX_ctrl(sm4_ctx, EVP_CTRL_GCM_SET_TAG, 16, tag)) {
    /* 错误处理 */
}
if (!EVP_DecryptFinal_ex(sm4_ctx, out + outlen, (int *)&tmplen)) {
    /* 错误处理 */
}
EVP_CIPHER_CTX_free(sm4_ctx);

和 GCM 模式的加密相比，解密操作最大不同就是需要在 EVP_DecryptFinal_ex 之前，进行 tag 的设置，从而使得铜锁可以判断信息是否遭到了篡改。