1# crypto_sym_cipher.h 2 3<!--Kit: Crypto Architecture Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @zxz--3--> 6<!--Designer: @lanming--> 7<!--Tester: @PAFT--> 8<!--Adviser: @zengyawen--> 9 10## 概述 11 12定义对称密钥加密API。 13 14**引用文件：** <CryptoArchitectureKit/crypto_sym_cipher.h> 15 16**库：** libohcrypto.so 17 18**系统能力：** SystemCapability.Security.CryptoFramework 19 20**起始版本：** 12 21 22**相关模块：** [CryptoSymCipherApi](capi-cryptosymcipherapi.md) 23 24## 汇总 25 26### 结构体 27 28| 名称 | typedef关键字 | 描述 | 29| -- | -- | -- | 30| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) | OH_CryptoSymCipher | 定义对称加解密结构体。 | 31| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) | OH_CryptoSymCipherParams | 定义对称加解密参数结构体。 | 32 33### 枚举 34 35| 名称 | typedef关键字 | 描述 | 36| -- | -- | -- | 37| [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) | CryptoSymCipher_ParamsType | 定义对称加解密参数类型。 | 38 39### 函数 40 41| 名称 | 描述 | 42| -- | -- | 43| [OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create(OH_CryptoSymCipherParams **params)](#oh_cryptosymcipherparams_create) | 创建对称密钥加解密参数实例。 | 44| [OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam(OH_CryptoSymCipherParams *params, CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value)](#oh_cryptosymcipherparams_setparam) | 设置对称密钥加解密参数。 | 45| [void OH_CryptoSymCipherParams_Destroy(OH_CryptoSymCipherParams *params)](#oh_cryptosymcipherparams_destroy) | 销毁对称密钥加解密参数实例。 | 46| [OH_Crypto_ErrCode OH_CryptoSymCipher_Create(const char *algoName, OH_CryptoSymCipher **ctx)](#oh_cryptosymcipher_create) | 根据给定的算法名称创建对称密钥加解密实例。 | 47| [OH_Crypto_ErrCode OH_CryptoSymCipher_Init(OH_CryptoSymCipher *ctx, Crypto_CipherMode mod, OH_CryptoSymKey *key, OH_CryptoSymCipherParams *params)](#oh_cryptosymcipher_init) | 初始化对称密钥加解密实例。 | 48| [OH_Crypto_ErrCode OH_CryptoSymCipher_Update(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out)](#oh_cryptosymcipher_update) | 更新加密或者解密数据操作。 | 49| [OH_Crypto_ErrCode OH_CryptoSymCipher_Final(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out)](#oh_cryptosymcipher_final) | 输出加/解密（分组模式产生的）剩余数据，最后结束加密或者解密数据操作。 | 50| [const char *OH_CryptoSymCipher_GetAlgoName(OH_CryptoSymCipher *ctx)](#oh_cryptosymcipher_getalgoname) | 获取对称密钥加解密实例的算法名称。 | 51| [void OH_CryptoSymCipher_Destroy(OH_CryptoSymCipher *ctx)](#oh_cryptosymcipher_destroy) | 销毁对称密钥加解密实例。 | 52 53## 枚举类型说明 54 55### CryptoSymCipher_ParamsType 56 57``` 58enum CryptoSymCipher_ParamsType 59``` 60 61**描述** 62 63定义对称加解密参数类型。 64 65**起始版本：** 12 66 67| 枚举项 | 描述 | 68| -- | -- | 69| CRYPTO_IV_DATABLOB = 100 | 表示iv等参数。 | 70| CRYPTO_AAD_DATABLOB = 101 | 表示GCM模式下的附加认证数据。 | 71| CRYPTO_TAG_DATABLOB = 102 | 表示加密操作的输出标签,用于完整性检查。 | 72 73 74## 函数说明 75 76### OH_CryptoSymCipherParams_Create() 77 78``` 79OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create(OH_CryptoSymCipherParams **params) 80``` 81 82**描述** 83 84创建对称密钥加解密参数实例。 85 86**起始版本：** 12 87 88 89**参数：** 90 91| 参数项 | 描述 | 92| -- | -- | 93| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) **params | 指向对称加解密参数实例的指针。 | 94 95**返回：** 96 97| 类型 | 说明 | 98| -- | -- | 99| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | CRYPTO_SUCCESS：操作成功。<br> CRYPTO_INVALID_PARAMS：参数无效。<br> CRYPTO_NOT_SUPPORTED：操作不支持。<br> CRYPTO_MEMORY_ERROR：内存错误。<br> CRYPTO_OPERTION_ERROR：调用三方算法库API出错。 | 100 101### OH_CryptoSymCipherParams_SetParam() 102 103``` 104OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam(OH_CryptoSymCipherParams *params,CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value) 105``` 106 107**描述** 108 109设置对称密钥加解密参数。 110 111**起始版本：** 12 112 113 114**参数：** 115 116| 参数项 | 描述 | 117| -- | -- | 118| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | 指向对称密钥加解密参数实例。 | 119| [CryptoSymCipher_ParamsType](#cryptosymcipher_paramstype) paramsType | 设置对称密钥加解密参数类型。 | 120| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *value | 设置的参数值。 | 121 122**返回：** 123 124| 类型 | 说明 | 125| -- | -- | 126| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | CRYPTO_SUCCESS：操作成功。<br> CRYPTO_INVALID_PARAMS：参数无效。<br> CRYPTO_NOT_SUPPORTED：操作不支持。<br> CRYPTO_MEMORY_ERROR：内存错误。<br> CRYPTO_OPERTION_ERROR：调用三方算法库API出错。 | 127 128### OH_CryptoSymCipherParams_Destroy() 129 130``` 131void OH_CryptoSymCipherParams_Destroy(OH_CryptoSymCipherParams *params) 132``` 133 134**描述** 135 136销毁对称密钥加解密参数实例。 137 138**起始版本：** 12 139 140 141**参数：** 142 143| 参数项 | 描述 | 144| -- | -- | 145| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | 指向对称密钥加解密参数实例。 | 146 147### OH_CryptoSymCipher_Create() 148 149``` 150OH_Crypto_ErrCode OH_CryptoSymCipher_Create(const char *algoName, OH_CryptoSymCipher **ctx) 151``` 152 153**描述** 154 155根据给定的算法名称创建对称密钥加解密实例。 156 157**起始版本：** 12 158 159 160**参数：** 161 162| 参数项 | 描述 | 163| -- | -- | 164| const char *algoName | 用于生成加密实例的算法名称。<br> 例如"AES128\|GCM\|PKCS7"。 | 165| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) **ctx | 指向对称密钥加密实例的指针。 | 166 167**返回：** 168 169| 类型 | 说明 | 170| -- | -- | 171| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | CRYPTO_SUCCESS：操作成功。<br> CRYPTO_INVALID_PARAMS：参数无效。<br> CRYPTO_NOT_SUPPORTED：操作不支持。<br> CRYPTO_MEMORY_ERROR：内存错误。<br> CRYPTO_OPERTION_ERROR：调用三方算法库API出错。 | 172 173### OH_CryptoSymCipher_Init() 174 175``` 176OH_Crypto_ErrCode OH_CryptoSymCipher_Init(OH_CryptoSymCipher *ctx, Crypto_CipherMode mod,OH_CryptoSymKey *key, OH_CryptoSymCipherParams *params) 177``` 178 179**描述** 180 181初始化对称密钥加解密实例。 182 183**起始版本：** 12 184 185 186**参数：** 187 188| 参数项 | 描述 | 189| -- | -- | 190| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | 对称密钥加密实例。 | 191| [Crypto_CipherMode](capi-crypto-common-h.md#crypto_ciphermode) mod | 加解密模式。 | 192| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) *key | 对称密钥。 | 193| [OH_CryptoSymCipherParams](capi-cryptosymcipherapi-oh-cryptosymcipherparams.md) *params | 指向对称密钥参数实例。 | 194 195**返回：** 196 197| 类型 | 说明 | 198| -- | -- | 199| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | CRYPTO_SUCCESS：操作成功。<br> CRYPTO_INVALID_PARAMS：参数无效。<br> CRYPTO_NOT_SUPPORTED：操作不支持。<br> CRYPTO_MEMORY_ERROR：内存错误。<br> CRYPTO_OPERTION_ERROR：调用三方算法库API出错。 | 200 201**参考：** 202 203[OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update) 204 205[OH_CryptoSymCipher_Final](#oh_cryptosymcipher_final) 206 207 208### OH_CryptoSymCipher_Update() 209 210``` 211OH_Crypto_ErrCode OH_CryptoSymCipher_Update(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out) 212``` 213 214**描述** 215 216更新加密或者解密数据操作。 217 218**起始版本：** 12 219 220 221**参数：** 222 223| 参数项 | 描述 | 224| -- | -- | 225| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | 指向对称密钥加解密实例。 | 226| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | 加密或者解密的数据。 | 227| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | 更新的结果。 | 228 229**返回：** 230 231| 类型 | 说明 | 232| -- | -- | 233| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | CRYPTO_SUCCESS：操作成功。<br> CRYPTO_INVALID_PARAMS：参数无效。<br> CRYPTO_NOT_SUPPORTED：操作不支持。<br> CRYPTO_MEMORY_ERROR：内存错误。<br> CRYPTO_OPERTION_ERROR：调用三方算法库API出错。 | 234 235**参考：** 236 237[OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init) 238 239[OH_CryptoSymCipher_Final](#oh_cryptosymcipher_final) 240 241 242### OH_CryptoSymCipher_Final() 243 244``` 245OH_Crypto_ErrCode OH_CryptoSymCipher_Final(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out) 246``` 247 248**描述** 249 250输出加/解密（分组模式产生的）剩余数据，最后结束加密或者解密数据操作。 251 252**起始版本：** 12 253 254 255**参数：** 256 257| 参数项 | 描述 | 258| -- | -- | 259| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | 对称密钥加密实例。 | 260| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | 要加密或解密的数据。 | 261| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | 返回剩余数据的加/解密结果。 | 262 263**返回：** 264 265| 类型 | 说明 | 266| -- | -- | 267| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | CRYPTO_SUCCESS：操作成功。<br> CRYPTO_INVALID_PARAMS：参数无效。<br> CRYPTO_NOT_SUPPORTED：操作不支持。<br> CRYPTO_MEMORY_ERROR：内存错误。<br> CRYPTO_OPERTION_ERROR：调用三方算法库API出错。 | 268 269**参考：** 270 271[OH_CryptoSymCipher_Init](#oh_cryptosymcipher_init) 272 273[OH_CryptoSymCipher_Update](#oh_cryptosymcipher_update) 274 275 276### OH_CryptoSymCipher_GetAlgoName() 277 278``` 279const char *OH_CryptoSymCipher_GetAlgoName(OH_CryptoSymCipher *ctx) 280``` 281 282**描述** 283 284获取对称密钥加解密实例的算法名称。 285 286**起始版本：** 12 287 288 289**参数：** 290 291| 参数项 | 描述 | 292| -- | -- | 293| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | 指向对称密钥加解密实例。 | 294 295**返回：** 296 297| 类型 | 说明 | 298| -- | -- | 299| const char * | 返回对称密钥加密算法名称。 | 300 301### OH_CryptoSymCipher_Destroy() 302 303``` 304void OH_CryptoSymCipher_Destroy(OH_CryptoSymCipher *ctx) 305``` 306 307**描述** 308 309销毁对称密钥加解密实例。 310 311**起始版本：** 12 312 313 314**参数：** 315 316| 参数项 | 描述 | 317| -- | -- | 318| [OH_CryptoSymCipher](capi-cryptosymcipherapi-oh-cryptosymcipher.md) *ctx | 指向对称密钥加解密实例。 | 319 320 321