2. Symmetric Cryptography
2.1加解密步骤
其中<Alg>指具体的密码算法,<Mode>指ECB、CBC、OFB、CFB、CTR模式。
执行步骤:
步骤1. 获取ctx大小:ipps<Alg>GetSize(int* pSize);其中<Alg>指具体的密码算法。
步骤2. 内存分配:pCtx = malloc(Size),分配Size字节内存给密码算法的pCtx;
步骤3. 初始化(密钥扩展):ipps<Alg>Init,需指定密钥。
步骤4. 加解密:调用ipps<Alg>Encrypt<Mode>或者ipps<Alg>Decrypt<Mode>,这里要设定IV,且IV在执行后会变化。
步骤5. 反初始化(数据清除):调用ipps<Alg>Init,但让key置为NULL。
步骤6. 内存释放:free(pCtx)。
注:
1. 还有个ipps<Alg>SetKey用于重新设定密钥,功能与ipps<Alg>Init类似;两者差异未知,猜测可能Init涉及一些别的特殊操作。
2.2 支持的密码算法和工作模式
表X 支持的密码算法和工作模式
模式算法 | AES | TDES/DES | SM4 | ARCFour |
ECB | Y | Y | Y | RC4为流密码 |
CBC | Y | Y | Y | |
CFB | Y | Y | Y | |
OFB | Y | Y | Y | |
CTR | Y | Y | Y | |
CCM | Y | X | Y(2018版) | |
GCM | Y | X | X | |
XTS | Y | X | X | |
SIV | Y | X | X |
补充说明
- TDES = DES加密(K1) → DES解密(K2) → DES加密(K1) 。
- ARCFour即RC4算法。
- CCM、GCM、SIV为认证加密模式;XTS为磁盘加密模式。
2.3 函数说明
2.3.1 获取上下文大小GetSize
IppStatus ippsAESGetSize(int* pSize);
IppStatus ippsDESGetSize(int* pSize);
IppStatus ippsSMS4GetSize(int* pSize);
IppStatus ippsARCFourGetSize(int* pSize);
参数说明
- pSize:OUT,CTX大小,单位字节。
2.3.2 初始化和反初始化Init
IppStatus ippsAESInit(const Ipp8u* pKey, int keylen, IppsAESSpec* pCtx, int ctxSize);
IppStatus ippsDESInit(const Ipp8u* pKey, IppsDESSpec* pCtx);
IppStatus ippsSMS4Init(const Ipp8u* pKey, int keyLen, IppsSMS4Spec* pCtx, int ctxSize);
IppStatus ippsARCFourInit(const Ipp8u* pKey, int keyLen, IppsARCFourState* pCtx);
参数说明
- pKey:IN,密钥。
- keyLen:IN,密钥字节长度。
- pCtx:OUT,密码算法上下文。
- ctxSize:IN,CTX大小,单位字节。
补充说明
- SM4的密钥长度必须是16。RC4密钥长度为1—256字节。
- 将pKey设置为NULL则执行反初始化。
- TDES需要对三个密钥各执行ippsDESInit以初始化三个IppsDESSpec*。
2.3.3 重置密钥SetKey
仅AES和SM4有重置密钥函数
IppStatus ippsAESSetKey(const Ipp8u* pKey, int keylen, IppsAESSpec* pCtx);
IppStatus ippsSMS4SetKey(const Ipp8u* pKey, int keyLen, IppsSMS4Spec* pCtx);
参数说明
- pKey:IN,密钥。
- keyLen:IN,密钥字节长度。
- pCtx:OUT,密码算法上下文。
补充说明
- pCtx必须是已经Init了的才能调用此函数。
2.3.4 上下文导入导出Pack/Unpack
SM4无上下文导入导出。
IppStatus ippsAESPack (const IppsAESSpec* pCtx, Ipp8u* pBuffer, int bufSize);
IppStatus ippsAESUnpack (const Ipp8u* pBuffer, IppsAESSpec* pCtx, int ctxSize);
IppStatus ippsDESPack (const IppsDESSpec* pCtx, Ipp8u* pBuffer);
IppStatus ippsDESUnpack (const Ipp8u* pBuffer, IppsDESSpec* pCtx);
IppStatus ippsARCFourPack (const IppsARCFourState* pCtx, Ipp8u* pBuffer);
IppStatus ippsARCFourUnpack (const Ipp8u* pBuffer, IppsARCFourState* pCtx);
参数说明
(A)导出/Pack时
- pCtx:IN,上下文。
- pBuffer:OUT,导出缓冲区。
- bufSize:IN,有的函数无。
(B)导入/Unpack时
- pBuffer:IN,导入缓冲区。
- pCtx:OUT,上下文。
- ctxSize:IN,上下文。
备注:
- 无论缓冲区pBuffer字节大小还是上下文pCtx字节大小,都调用ipps***GetSize获得。
- SM4无上下文导入导出。
- AES有bufSize和ctxSize是因为AES的密钥有三种长度,使得其buf和ctx不定长。
2.3.5 AES加解密
IppStatus ippsAESEncryptECB( const Ipp8u *pSrc, Ipp8u *pDst, int srclen, const IppsAESSpec* pCtx);
IppStatus ippsAESDecryptECB( const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx);
IppStatus ippsAESEncryptCBC( const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
IppStatus ippsAESDecryptCBC( const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
IppStatus ippsAESEncryptCFB( const Ipp8u* pSrc, Ipp8u* pDst, int srcLen, int cfbBlkSize, const IppsAESSpec* pCtx, const Ipp8u *pIV);
IppStatus ippsAESDecryptCFB( const Ipp8u* pSrc, Ipp8u* pDst, int srclen, int cfbBlkSize, const IppsAESSpec* pCtx, const Ipp8u*pIV);
IppStatus ippsAESEncryptOFB ( const Ipp8u* pSrc, Ipp8u* pDst, int srclen, int ofbBlkSize, const IppsAESSpec* pCtx, Ipp8u* pIV);
IppStatus ippsAESDecryptOFB ( const Ipp8u* pSrc, Ipp8u* pDst, int srclen, int ofbBlkSize, const IppsAESSpec* pCtx, Ipp8u* pIV);
IppStatus ippsAESEncryptCTR( const Ipp8u* pSrc, Ipp8u* pDst, int srcLen,const IppsAESSpec* pCtx, Ipp8u* pCtrValue , int ctrNumBitSize);
IppStatus ippsAESDecryptCTR( const Ipp8u* pSrc, Ipp8u* pDst, int srcLen,const IppsAESSpec* pCtx, Ipp8u* pCtrValue, int ctrNumBitSize);
以下是在2018版中发现的新增接口,CBC的CS模式,2017版无。
IppStatus ippsAESEncryptCBC_CS1 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
IppStatus ippsAESEncryptCBC_CS2 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
IppStatus ippsAESEncryptCBC_CS3 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
IppStatus ippsAESDecryptCBC_CS1 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
IppStatus ippsAESDecryptCBC_CS2 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
IppStatus ippsAESDecryptCBC_CS3 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsAESSpec* pCtx, const Ipp8u* pIV);
表X 参数列表
AES | pSrc | pDst | srcLen | pCtx | pIV | 其它 |
ECB | Y | Y | Y | Y | — | — |
CBC | Y | Y | Y | Y | Y | — |
CBC_CS1 | Y | Y | Y | Y | Y | — |
CBC_CS2 | Y | Y | Y | Y | Y | — |
CBC_CS3 | Y | Y | Y | Y | Y | — |
CFB | Y | Y | Y | Y | Y | cfbBlkSize |
OFB | Y | Y | Y | Y | Y | ofbBlkSize |
CTR | Y | Y | Y | Y | — | pCtrValue ctrNumBitSize |
参数说明
- pSrc:IN,加密时为明文,解密时为密文。
- srclen:IN,Src的字节长度。
- pDst:OUT,加密时为密文,解密时为明文。长度等于srclen。
- pCtx:IO,密码算法上下文。
- pIV:IO,初始化向量,长度同分组大小,调用后会改变。ECB无。
- pCtrValue:IO,CTR的计数器,相当于其它模式的初始化向量。
- ctrNumBitSize:IN,计数器中有效的计数比特长度(从右端计)。
- cfbBlkSize/ ofbBlkSize:CFB/OFB每拍输出的密钥流字节数,小于分组大小。
备注1:CBC_CS采用密文偷取技术,使得数据多次加密时使用不便。因此,建议这种模式下一次性输入完毕明文/密文。
备注2:srcLen长度说明。
表X srcLen说明
AES | srcLen |
ECB | 16 | srcLen |
CBC | 16 | srcLen |
CFB | cfbBlkSize | srcLen |
OFB | ofbBlkSize | srcLen |
CTR | 任意长度。 但非最后一次调用时都要求16 | srcLen |
CTR中srcLen长度的进一步说明
若srcLen不是16的整数倍,则生成的多余的密钥流会被丢弃。下次再送入数据时,会用新的CTR值加密作为密钥流。
例如,第1次送入33字节,第二次再送入31字节。第一次生成48字节密钥流,前33字节密钥流用于加密,后15字节密钥流丢弃;第二次重新产生32字节,前31字节密钥流用于加密,后1字节密钥流丢弃。这样一来,由于第一次加密时丢弃了15字节密钥流,就导致了其加密结果和我们期望的结果不一致。
2.3.6 AES其它模式
AES加密认证涉及CCM、GCM、SIV,详情参见官方文档。本文档略。
AES磁盘加密涉及XTS模式,详情参见官方文档。本文档略。
2.3.7 TDES加解密
IppStatus ippsTDESEncryptECB(const Ipp8u *pSrc, Ipp8u *pDst, int srclen, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec * pCtx3, IppsCPPadding padding);
IppStatus ippsTDESDecryptECB(const Ipp8u *pSrc, Ipp8u *pDst, int srclen, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec * pCtx3, IppsCPPadding padding);
IppStatus ippsTDESEncryptCBC(const Ipp8u *pSrc, Ipp8u *pDst, int srclen, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec * pCtx3, const Ipp8u *pIV, IppsCPPadding padding);
IppStatus ippsTDESDecryptCBC(const Ipp8u *pSrc, Ipp8u *pDst, int srclen, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec * pCtx3, const Ipp8u *pIV, IppsCPPadding padding);
IppStatus ippsTDESEncryptCFB(const Ipp8u *pSrc, Ipp8u *pDst, int srclen, int cfbBlkSize, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec *pCtx3, const Ipp8u *pIV, IppsCPPadding padding);
IppStatus ippsTDESDecryptCFB(const Ipp8u *pSrc, Ipp8u *pDst, int srclen, int cfbBlkSize, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec *pCtx3, const Ipp8u *pIV, IppsCPPadding padding);
IppStatus ippsTDESEncryptOFB (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, int ofbBlkSize, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec *pCtx3, Ipp8u* pIV);
IppStatus ippsTDESDecryptOFB (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, int ofbBlkSize, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec *pCtx3, Ipp8u* pIV);
IppStatus ippsTDESEncryptCTR(const Ipp8u *pSrc, Ipp8u *pDst, int srclen, const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec *pCtx3,Ipp8u *pCtrValue, int ctrNumBitSize);
IppStatus ippsTDESDecryptCTR(const Ipp8u *pSrc, Ipp8u *pDst, int srcLen,const IppsDESSpec *pCtx1, const IppsDESSpec *pCtx2, const IppsDESSpec *pCtx3, Ipp8u *pCtrValue, int ctrNumBitSize);
表X 参数列表
TDES | pSrc | pDst | srcLen | pCtx1-3 | pIV | padding | 其它 |
ECB | Y | Y | Y | Y | — | Y | — |
CBC | Y | Y | Y | Y | Y | Y | — |
CFB | Y | Y | Y | Y | Y | Y | cfbBlkSize |
OFB | Y | Y | Y | Y | Y | — | ofbBlkSize |
CTR | Y | Y | Y | Y | — | — | pCtrValue ctrNumBitSize |
参数说明
- pSrc:IN,加密时为明文,解密时为密文。
- srclen:IN,Src的字节长度。
- pDst:OUT,加密时为密文,解密时为明文。长度等于srclen。
- pCtx1,pCtx2,pCtx3:IO,密码算法上下文,三个密钥对应三个上下文。
- pIV:IO,初始化向量,长度同分组大小,调用后会改变。ECB无。
- padding:IN,目前好像只支持IppsPaddingNONE(不填充)。具体待查。
- pCtrValue:IO,CTR的计数器,相当于其它模式的初始化向量。
- ctrNumBitSize:IN,计数器中有效的计数比特长度(从右端计)。
- cfbBlkSize/ ofbBlkSize:CFB/OFB每拍输出的密钥流字节数,小于分组大小。
备注:
- padding:具体待查。
2.3.8 SM4加解密
IppStatus ippsSMS4EncryptECB(const Ipp8u *pSrc, Ipp8u *pDst, int len, const IppsSMS4Spec* pCtx);
IppStatus ippsSMS4DecryptECB(const Ipp8u* pSrc, Ipp8u* pDst, int len, const IppsSMS4Spec* pCtx);
IppStatus ippsSMS4EncryptCBC(const Ipp8u* pSrc, Ipp8u* pDst, int len, const IppsSMS4Spec* pCtx, const Ipp8u* pIV);
IppStatus ippsSMS4DecryptCBC(const Ipp8u* pSrc, Ipp8u* pDst, int len, const IppsSMS4Spec* pCtx, const Ipp8u* pIV);
IppStatus ippsSMS4EncryptCFB(const Ipp8u* pSrc, Ipp8u* pDst, int len, int cfbBlkSize, const IppsSMS4Spec* pCtx, const Ipp8u *pIV);
IppStatus ippsSMS4DecryptCFB(const Ipp8u* pSrc, Ipp8u* pDst, int len, int cfbBlkSize, const IppsSMS4Spec* pCtx, const Ipp8u* pIV);
IppStatus ippsSMS4EncryptOFB (const Ipp8u* pSrc, Ipp8u* pDst, int len, int ofbBlkSize, const IppsSMS4Spec* pCtx, Ipp8u* pIV);
IppStatus ippsSMS4DecryptOFB (const Ipp8u* pSrc, Ipp8u* pDst, int len, int ofbBlkSize, const IppsSMS4Spec* pCtx, Ipp8u* pIV);
IppStatus ippsSMS4EncryptCTR(const Ipp8u* pSrc, Ipp8u* pDst, int len, const IppsSMS4Spec* pCtx, Ipp8u* pCtrValue , int ctrNumBitSize);
IppStatus ippsSMS4DecryptCTR(const Ipp8u* pSrc, Ipp8u* pDst, int len, const IppsSMS4Spec * pCtx, Ipp8u* pCtrValue, int ctrNumBitSize);
以下是在2018版中发现的新增接口,CBC的CS模式,2017版无。
IppStatus ipps SMS4EncryptCBC_CS1 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsSMS4Spec * pCtx, const Ipp8u* pIV);
IppStatus ipps SMS4EncryptCBC_CS2 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsSMS4Spec * pCtx, const Ipp8u* pIV);
IppStatus ipps SMS4EncryptCBC_CS3 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsSMS4Spec * pCtx, const Ipp8u* pIV);
IppStatus ipps SMS4DecryptCBC_CS1 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsSMS4Spec * pCtx, const Ipp8u* pIV);
IppStatus ipps SMS4DecryptCBC_CS2 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsSMS4Spec * pCtx, const Ipp8u* pIV);
IppStatus ipps SMS4DecryptCBC_CS3 (const Ipp8u* pSrc, Ipp8u* pDst, int srclen, const IppsSMS4Spec * pCtx, const Ipp8u* pIV);
表X 参数列表
SM4 | pSrc | pDst | srcLen | pCtx | pIV | 其它 |
ECB | Y | Y | Y | Y | — | — |
CBC | Y | Y | Y | Y | Y | — |
CBC-CS1 | Y | Y | Y | Y | Y | — |
CBC-CS2 | Y | Y | Y | Y | Y | — |
CBC-CS3 | Y | Y | Y | Y | Y | — |
CFB | Y | Y | Y | Y | Y | cfbBlkSize |
OFB | Y | Y | Y | Y | Y | ofbBlkSize |
CTR | Y | Y | Y | Y | — | pCtrValue ctrNumBitSize |
参数说明
- pSrc:IN,加密时为明文,解密时为密文。
- srclen:IN,Src的字节长度。
- pDst:OUT,加密时为密文,解密时为明文。长度等于srclen。
- pCtx:IO,密码算法上下文。
- pIV:IO,初始化向量,长度同分组大小,调用后会改变。ECB无。
- pCtrValue:IO,CTR的计数器,相当于其它模式的初始化向量。
- ctrNumBitSize:IN,计数器中有效的计数比特长度(从右端计)。
- cfbBlkSize/ ofbBlkSize:CFB/OFB每拍输出的密钥流字节数,小于分组大小。
备注1:CBC_CS采用密文偷取技术,使得数据多次加密时使用不便。因此,建议这种模式下一次性输入完毕明文/密文。
备注2:srcLen长度说明。
表X srcLen说明
AES | srcLen |
ECB | 16 | srcLen |
CBC | 16 | srcLen |
CFB | cfbBlkSize | srcLen |
OFB | ofbBlkSize | srcLen |
CTR | 任意长度。 但非最后一次调用时都要求16 | srcLen |
CTR中srcLen长度的进一步说明
若srcLen不是16的整数倍,则生成的多余的密钥流会被丢弃。下次再送入数据时,会用新的CTR值加密作为密钥流。
例如,第1次送入33字节,第二次再送入31字节。第一次生成48字节密钥流,前33字节密钥流用于加密,后15字节密钥流丢弃;第二次重新产生32字节,前31字节密钥流用于加密,后1字节密钥流丢弃。这样一来,由于第一次加密时丢弃了15字节密钥流,就导致了其加密结果和我们期望的结果不一致。
2.3.8 SM4-CCM加解认证
在2018版中发现有SM4-CCM,但是SM4执行CCM的可能性较低,所以本部分略。
2.3.9 ARCFour加解密
ARCFour即RC4流密码。本部分略。
2.4 示例代码
2.4.1 AES示例代码
#include “ippcp.h”
// use of the CTR mode
int AES_sample(void)
{
// secret key
Ipp8u key[] = "\x00\x01\x02\x03\x04\x05\x06\x07"
"\x08\x09\x10\x11\x12\x13\x14\x15";
// define and setup AES cipher
int ctxSize;
ippsAESGetSize(&ctxSize);
IppsAESSpec* pAES = (IppsAESSpec*)( new Ipp8u [ctxSize] );
ippsAESInit(key, sizeof(key)-1, pAES, ctxSize);
// message to be encrypted
Ipp8u msg[] = "the quick brown fox jumps over the lazy dog";
// and initial counter
Ipp8u ctr0[] = "\xff\xee\xdd\xcc\xbb\xaa\x99\x88"
"\x77\x66\x55\x44\x33\x22\x11\x00";
// counter
Ipp8u ctr[16];
// init counter before encryption
memcpy(ctr, ctr0, sizeof(ctr));
// encrypted message
Ipp8u ctext[sizeof(msg)];
// encryption
ippsAESEncryptCTR(msg, ctext, sizeof(msg), pAES, ctr, 64);
// init counter before decryption
memcpy(ctr, ctr0, sizeof(ctr));
// decrypted message
Ipp8u rtext[sizeof(ctext)];
// decryption
ippsAESDecryptCTR(ctext, rtext, sizeof(ctext), pAES, ctr, 64);
// remove secret and release resource
ippsAESInit(0, sizeof(key)-1, pAES, ctxSize);
delete [] (Ipp8u*)pAES;
int error = memcmp(rtext, msg, sizeof(msg));
return 0==error;
}
2.4.2 TDES示例代码
// Use of the ECB mode
void TDES_sample(void){
// size of the TDES algorithm block is equal to 8
const int tdesBlkSize = 8;
// get size of the context needed for the encryption/decryption operation
int ctxSize;
ippsDESGetSize(&ctxSize);
// and allocate one
IppsDESSpec* pCtx1 = (IppsDESSpec*)( new Ipp8u [ctxSize] );
IppsDESSpec* pCtx2 = (IppsDESSpec*)( new Ipp8u [ctxSize] );
IppsDESSpec* pCtx3 = (IppsDESSpec*)( new Ipp8u [ctxSize] );
// define the key
Ipp8u key1[] = {0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08};
Ipp8u key2[] = {0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18};
Ipp8u key3[] = {0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28};
Ipp8u keyX[] = {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00};
// and prepare the context for the TDES usage
ippsDESInit(key1, pCtx1);
ippsDESInit(key2, pCtx2);
ippsDESInit(key3, pCtx3);
// define the message to be encrypted
Ipp8u ptext[] = {"the quick brown fox jumps over the lazy dog"};
// allocate enough memory for the ciphertext
// note that
// the size of ciphertext is always a multiple of the cipher block size
Ipp8u ctext[(sizeof(ptext)+desBlkSize-1) &~(desBlkSize-1)];
// encrypt (ECB mode) ptext message
// pay attention to the 'length' parameter
// it defines the number of bytes to be encrypted
ippsTDESEncryptECB(ptext, ctext, sizeof(ctext), pCtx1, pCtx2, pCtx3, IppsCPPaddingNONE);
// allocate memory for the decrypted message
Ipp8u rtext[sizeof(ctext)];
// decrypt (ECB mode) ctext message
// pay attention to the 'length' parameter
// it defines the number of bytes to be decrypted
ippsTDESDecryptECB(ctext, rtext, sizeof(ctext), pCtx1, pCtx2, pCtx3, IppsCPPaddingNONE);
// remove actual secret from contexts
ippsDESInit(keyX, pCtx1);
ippsDESInit(keyX, pCtx2);
ippsDESInit(keyX, pCtx3);
// release resources
delete (Ipp8u*)pCtx1;
delete (Ipp8u*)pCtx2;
delete (Ipp8u*)pCtx3;
}