对称算法运算类

本章节主要描述了对称算法运算类接口定义与规格限制。

对称算法运算类接口支持如下：接口定义符合GM/T 0018-2012和GM/T 0018-2023（获取链接）标准，接口参数与返回值可参考标准文档，算法标识描述可参考GM/T 0006-2012。

其中SDF_Encrypt接口中的puiEncDataLength大于等于输入的明文长度，SDF_Decrypt接口中的puiDataLength大于等于输入的密文长度。

int SDF_Encrypt(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucIV, unsigned char *pucData, unsigned int uiDataLength, unsigned char *pucEncData, unsigned int *puiEncDataLength);
int SDF_Decrypt(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucIV, unsigned char *pucEncData, unsigned int uiEncDataLength, unsigned char *pucData, unsigned int *puiDataLength);
int SDF_CalculateMAC(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucIV, unsigned char *pucData, unsigned int uiDataLength, unsigned char *pucMAC, unsigned int *puiMACLength);
int SDF_CalculateMACInit(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucIV, unsigned int uiIVLength);
int SDF_CalculateMACUpdate(void *hSessionHandle, unsigned char *pucData, unsigned int uiDataLength);
int SDF_CalculateMACFinal(void *hSessionHandle, unsigned char *pucMac, unsigned int *puiMacLength);

参考GM/T 0018-2023标准实现了单包可鉴别加解密接口，数据类型与2012版保持一致，为无符号整型。

其中SDF_AuthEnc接口中的puiEncDataLength需要大于等于输入的明文长度，SDF_AuthDec接口中的puiDataLength需要大于等于输入的密文长度。

int SDF_AuthEnc(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucStartVar, unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength, unsigned char *pucData, unsigned int uiDataLength, unsigned char *pucEncData, unsigned int *puiEncDataLength, unsigned char *pucAuthData, unsigned int *uiAuthDataLength);
int SDF_AuthDec(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucStartVar, unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength, unsigned char *pucAuthData, unsigned int *puiAuthDataLength, unsigned char *pucEncData, unsigned int uiEncDataLength, unsigned char *pucData, unsigned int *puiDataLength);

参考GM/T 0018-2023标准实现了多包可鉴别加解密接口。

int SDF_AuthEncInit(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucStartVar,
unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength, unsigned int uiDataLength);
int SDF_AuthEncUpdate(void *hSessionHandle, unsigned char *pucData, unsigned int uiDataLength,
unsigned char *putEncData, unsigned int *puiEncDataLength);
int SDF_AuthEncFinal(void *hSessionHandle, unsigned char *pucLastEncData, unsigned int *puiLastEncDataLength,
unsigned char *pucAuthData, unsigned int *puiAuthDataLength);
int SDF_AuthDecInit(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucStartVar,
unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength, unsigned char *pucAuthData,
unsigned int uiAuthDataLength, unsigned int uiDataLength);
int SDF_AuthDecUpdate(void *hSessionHandle, unsigned char *pucEncData, unsigned int uiEncDataLength,
unsigned char *pucData, unsigned int *puiDataLength);
int SDF_AuthDecFinal(void *hSessionHandle, unsigned char *pucLastData, unsigned int *puiLastDataLength);

参考GM/T 0018-2023标准实现了多包加解密接口。

int SDF_EncryptInit(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucIV,
unsigned int uiIVLength);
int SDF_EncryptUpdate(void *hSessionHandle, unsigned char *pucData, unsigned int uiDataLength,
unsigned char *pucEncData, unsigned int *puiEncDataLength);
int SDF_EncryptFinal(void *hSessionHandle, unsigned char *pucLastEncData, unsigned int *puiLastEncDataLength);
int SDF_DecryptInit(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, unsigned char *pucIV,
unsigned int uiIVLength);
int SDF_DecryptUpdate(void *hSessionHandle, unsigned char *pucEncData, unsigned int uiEncDataLength,
unsigned char *pucData, unsigned int *puiDataLength);
int SDF_DecryptFinal(void *hSessionHandle, unsigned char *pucLastData, unsigned int *puiLastDataLength);

外部对称算法运算类自定义接口如下：

• 外部单包加密接口。

  int SDF_ExternalKeyEncrypt(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID, unsigned int uiPaddingMode, unsigned char *pucIV, unsigned char *pucData, unsigned int uiDataLength, unsigned char *pucEncData, unsigned int *puiEncDataLength);

  表1 参数说明

  参数	描述
  hSessionHandle[in]	会话句柄（单包接口可忽略或用于内部复用ctx）。
  pucKey[in]	对称密钥SM4（SM4 通常16字节）
  uikeyLen[in]	密钥长度（字节）。
  uiAlgID[in]	算法标识（应映射到SM4_CBC/SM4_ECB）。
  uiPaddingMode[in]	padding 模式（仅ECB/CBC使用）。
  pucIV[in]	IV指针（CBC需要16字节；ECB不使用，可为NULL）。
  pucData[in]	明文指针（可为NULL，当uiDataLength=0）。
  uiDataLength[in]	明文长度（字节）。
  pucEncData[out]	密文输出缓冲区。
  puiEncDataLength[out]	入参=输出缓冲区容量；出参=实际使用长度。

  表2 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 外部单包解密接口。

  int SDF_ExternalKeyDecrypt(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID,unsigned int uiPaddingMode, unsigned char *pucIV, unsigned char *pucEncData, unsigned int uiEncDataLength,unsigned char *pucData, unsigned int *puiDataLength);

  表3 参数说明

  参数	描述
  hSessionHandle[in]	会话句柄（单包接口可忽略或用于内部复用ctx）
  pucKey[in]	对称密钥（SM4通常16字节）
  uikeyLen[in]	密钥长度（字节）。
  uiAlgID[in]	算法标识（应映射到SM4_CBC/SM4_ECB）。
  uiPaddingMode[in]	padding 模式（仅ECB/CBC使用）。
  pucIV[in]	IV 指针（CBC需要16字节；ECB不使用，可为NULL）。
  pucEncData[in]	密文指针（可为NULL，当uiEncDataLength=0）。
  pucEncDataLength[in]	密文长度（字节）。
  pucEncData[out]	明文输出缓冲区。
  puiEncDataLength[out]	入参=输出缓冲区容量；出参=实际使用长度。

  表4 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 外部单包可鉴别加密接口。

  int SDF_ExternalAuthEnc(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID,unsigned char *pucStartVar, unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength,unsigned char *pucData, unsigned int uiDataLength, unsigned char *pucEncData, unsigned int *puiEncDataLength,unsigned char *pucAuthData, unsigned int *puiAuthDataLength);

  表5 参数说明

  参数	描述
  hSessionHandle[in]	会话句柄（单包接口可忽略或用于内部复用ctx）。
  pucKey[in]	对称密钥（SM4通常16字节）。
  uikeyLen[in]	密钥长度（字节）。
  uiAlgID[in]	算法标识（应映射到SM4_GCM）。
  pucStartVar[in]	IV/Nonce。
  uiStartVarLength[in]	IV/Nonce长度（字节）。
  pucAad[in]	AAD（Additional Authenticated Data，附加认证数据） 指针（可为NULL，当uiAadLength=0）。
  uiAadLength[in]	AAD长度（字节）。
  pucData[in]	明文指针（可为NULL，当uiDataLength=0）。
  uiDataLength[in]	明文长度（字节）。
  pucEncData[out]	密文输出缓冲区。
  puiEncDataLength[out]	入参=输出缓冲区容量；出参=实际密文长度。
  pucAuthData[out]	TAG输出缓冲区。
  puiAuthDataLength[out]	入参=TAG期望收到的tagLen(最大16)；出参=实际输出的tagLen。

  表6 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 外部单包可鉴别解密接口。

  int SDF_ExternalAuthDec(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID,unsigned char *pucStartVar, unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength,unsigned char *pucAuthData, unsigned int uiAuthDataLength, unsigned char *pucEncData,unsigned int uiEncDataLength, unsigned char *pucData, unsigned int *puiDataLength);

  表7 参数说明

  参数	描述
  hSessionHandle[in]	会话句柄（单包接口可忽略或用于内部复用ctx）。
  pucKey[in]	对称密钥（SM4通常16字节）。
  uikeyLen[in]	密钥长度（字节）。
  uiAlgID[in]	算法标识（应映射到SM4_GCM）。
  pucStartVar[in]	IV/Nonce。
  uiStartVarLength[in]	IV/Nonce长度（字节）。
  pucAad[in]	AAD 指针（可为NULL，当uiAadLength=0）。
  uiAadLength[in]	AAD长度（字节）。
  pucAuthData[in]	期望/输入的TAG（独立字段传入）。
  uiAuthDataLength[in]	TAG长度（字节）。
  pucEncData[in]	密文指针（可为NULL，当uiEncDataLength=0）。
  uiEncDataLength[in]	密文长度（字节）。
  pucData[out]	明文输出缓冲区。
  puiDataLength[out]	入参=输出缓冲区容量；出参=实际明文长度。

  表8 返回值说明

  返回值	说明
  0	成功
  非0	失败，返回错误码

• 外部多包可鉴别加解密接口。

int SDF_ExternalAuthEncInit(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID,unsigned char *pucStartVar, unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength);

int SDF_ExternalAuthEncUpdate(void *hSessionHandle, unsigned char *pucData, unsigned int uiDataLength,unsigned char *pucEncData, unsigned int *puiEncDataLength);

int SDF_ExternalAuthEncFinal(void *hSessionHandle, unsigned char *pucAuthData, unsigned int *puiAuthDataLength,unsigned char *pucLastData, unsigned int *puiLastDataLength);

int SDF_ExternalAuthDecInit(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID,unsigned char *pucStartVar, unsigned int uiStartVarLength, unsigned char *pucAad, unsigned int uiAadLength);

int SDF_ExternalAuthDecUpdate(void *hSessionHandle, unsigned char *pucEncData, unsigned int uiEncDataLength,unsigned char *pucData, unsigned int *puiDataLength);

int SDF_ExternalAuthDecFinal(void *hSessionHandle, unsigned char *pucAuthData, unsigned int uiAuthDataLength,unsigned char *pucLastData, unsigned int *puiLastDataLength);

• 外部多包加解密接口。

int SDF_ExternalKeyEncryptInit(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID,unsigned int uiPaddingMode, unsigned char *pucIV, unsigned int uiIVLength);

int SDF_ExternalKeyEncryptUpdate(void *hSessionHandle, unsigned char *pucData, unsigned int uiDataLength,unsigned char *pucEncData, unsigned int *puiEncDataLength);

int SDF_ExternalKeyEncryptFinal(void *hSessionHandle, unsigned char *pucLastEncData,unsigned int *puiLastEncDataLength);

int SDF_ExternalKeyDecryptInit(void *hSessionHandle, unsigned char *pucKey, unsigned int uikeyLen, unsigned int uiAlgID,unsigned int uiPaddingMode, unsigned char *pucIV, unsigned int uiIVLength);

int SDF_ExternalKeyDecryptUpdate(void *hSessionHandle, unsigned char *pucEncData, unsigned int uiEncDataLength,unsigned char *pucData, unsigned int *puiDataLength);

int SDF_ExternalKeyDecryptFinal(void *hSessionHandle, unsigned char *pucLastData, unsigned int *puiLastDataLength);