1# crypto_sym_key.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## Overview 11 12Provides APIs for symmetric keys. 13 14**Header file**: <CryptoArchitectureKit/crypto_sym_key.h> 15 16**Library**: libohcrypto.so 17 18**System capability**: SystemCapability.Security.CryptoFramework 19 20**Since**: 12 21 22**Related module**: [CryptoSymKeyApi](capi-cryptosymkeyapi.md) 23 24## Summary 25 26### Structs 27 28| Name| typedef Keyword| Description| 29| -- | -- | -- | 30| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) | OH_CryptoSymKey | Defines a struct for a symmetric key generator.| 31| [OH_CryptoSymKeyGenerator](capi-cryptosymkeyapi-oh-cryptosymkeygenerator.md) | OH_CryptoSymKeyGenerator | Defines a struct for a symmetric key.| 32 33### Functions 34 35| Name| Description| 36| -- | -- | 37| [OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Create(const char *algoName, OH_CryptoSymKeyGenerator **ctx)](#oh_cryptosymkeygenerator_create) | Creates a symmetric key generator instance based on the given algorithm name.| 38| [OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Generate(OH_CryptoSymKeyGenerator *ctx, OH_CryptoSymKey **keyCtx)](#oh_cryptosymkeygenerator_generate) | Randomly generates a symmetric key.| 39| [OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Convert(OH_CryptoSymKeyGenerator *ctx,const Crypto_DataBlob *keyData, OH_CryptoSymKey **keyCtx)](#oh_cryptosymkeygenerator_convert) | Converts binary data into a symmetric key.| 40| [const char *OH_CryptoSymKeyGenerator_GetAlgoName(OH_CryptoSymKeyGenerator *ctx)](#oh_cryptosymkeygenerator_getalgoname) | Obtains the algorithm of a symmetric key generator instance.| 41| [void OH_CryptoSymKeyGenerator_Destroy(OH_CryptoSymKeyGenerator *ctx)](#oh_cryptosymkeygenerator_destroy) | Destroys a symmetric key generator instance.| 42| [const char *OH_CryptoSymKey_GetAlgoName(OH_CryptoSymKey *keyCtx)](#oh_cryptosymkey_getalgoname) | Obtains the algorithm of a symmetric key.| 43| [OH_Crypto_ErrCode OH_CryptoSymKey_GetKeyData(OH_CryptoSymKey *keyCtx, Crypto_DataBlob *out)](#oh_cryptosymkey_getkeydata) | Obtains symmetric key data from a key instance.| 44| [void OH_CryptoSymKey_Destroy(OH_CryptoSymKey *keyCtx)](#oh_cryptosymkey_destroy) | Destroys a symmetric key instance.| 45 46## Function Description 47 48### OH_CryptoSymKeyGenerator_Create() 49 50``` 51OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Create(const char *algoName, OH_CryptoSymKeyGenerator **ctx) 52``` 53 54**Description** 55 56Creates a symmetric key generator instance based on the given algorithm name. 57 58**Since**: 12 59 60 61**Parameters** 62 63| Name| Description| 64| -- | -- | 65| const char *algoName | Pointer the algorithm used to create a generator.<br> For example, **'AES256'**, **'AES128'**, and **'SM4'**.| 66| [OH_CryptoSymKeyGenerator](capi-cryptosymkeyapi-oh-cryptosymkeygenerator.md) **ctx | Double pointer to the symmetric key generator instance created.| 67 68**Returns** 69 70| Type| Description| 71| -- | -- | 72| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 73 74### OH_CryptoSymKeyGenerator_Generate() 75 76``` 77OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Generate(OH_CryptoSymKeyGenerator *ctx, OH_CryptoSymKey **keyCtx) 78``` 79 80**Description** 81 82Randomly generates a symmetric key. 83 84**Since**: 12 85 86 87**Parameters** 88 89| Name| Description| 90| -- | -- | 91| [OH_CryptoSymKeyGenerator](capi-cryptosymkeyapi-oh-cryptosymkeygenerator.md) *ctx | Pointer to the symmetric key generator instance.| 92| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) **keyCtx | Pointer to the symmetric key created.| 93 94**Returns** 95 96| Type| Description| 97| -- | -- | 98| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 99 100### OH_CryptoSymKeyGenerator_Convert() 101 102``` 103OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Convert(OH_CryptoSymKeyGenerator *ctx,const Crypto_DataBlob *keyData, OH_CryptoSymKey **keyCtx) 104``` 105 106**Description** 107 108Converts binary data into a symmetric key. 109 110**Since**: 12 111 112 113**Parameters** 114 115| Name| Description| 116| -- | -- | 117| [OH_CryptoSymKeyGenerator](capi-cryptosymkeyapi-oh-cryptosymkeygenerator.md) *ctx | Pointer to the symmetric key generator instance.| 118| [const Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *keyData | Pointer to the data to convert.| 119| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) **keyCtx | Pointer to the symmetric key obtained.| 120 121**Returns** 122 123| Type| Description| 124| -- | -- | 125| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 126 127### OH_CryptoSymKeyGenerator_GetAlgoName() 128 129``` 130const char *OH_CryptoSymKeyGenerator_GetAlgoName(OH_CryptoSymKeyGenerator *ctx) 131``` 132 133**Description** 134 135Obtains the algorithm of a symmetric key generator instance. 136 137**Since**: 12 138 139 140**Parameters** 141 142| Name| Description| 143| -- | -- | 144| [OH_CryptoSymKeyGenerator](capi-cryptosymkeyapi-oh-cryptosymkeygenerator.md) *ctx | Double pointer to the symmetric key generator instance created.| 145 146**Returns** 147 148| Type| Description| 149| -- | -- | 150| const char * | Algorithm of a symmetric key generator instance.| 151 152### OH_CryptoSymKeyGenerator_Destroy() 153 154``` 155void OH_CryptoSymKeyGenerator_Destroy(OH_CryptoSymKeyGenerator *ctx) 156``` 157 158**Description** 159 160Destroys a symmetric key generator instance. 161 162**Since**: 12 163 164 165**Parameters** 166 167| Name| Description| 168| -- | -- | 169| [OH_CryptoSymKeyGenerator](capi-cryptosymkeyapi-oh-cryptosymkeygenerator.md) *ctx | Double pointer to the symmetric key generator instance created.| 170 171### OH_CryptoSymKey_GetAlgoName() 172 173``` 174const char *OH_CryptoSymKey_GetAlgoName(OH_CryptoSymKey *keyCtx) 175``` 176 177**Description** 178 179Obtains the algorithm of a symmetric key. 180 181**Since**: 12 182 183 184**Parameters** 185 186| Name| Description| 187| -- | -- | 188| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) *keyCtx | Pointer to the symmetric key instance.| 189 190**Returns** 191 192| Type| Description| 193| -- | -- | 194| const char * | Symmetric key algorithm obtained.| 195 196### OH_CryptoSymKey_GetKeyData() 197 198``` 199OH_Crypto_ErrCode OH_CryptoSymKey_GetKeyData(OH_CryptoSymKey *keyCtx, Crypto_DataBlob *out) 200``` 201 202**Description** 203 204Obtains symmetric key data from a key instance. 205 206**Since**: 12 207 208 209**Parameters** 210 211| Name| Description| 212| -- | -- | 213| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) *keyCtx | Pointer to the symmetric key instance.| 214| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the data obtained.| 215 216**Returns** 217 218| Type| Description| 219| -- | -- | 220| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_INVALID_PARAMS**: A parameter is invalid.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 221 222### OH_CryptoSymKey_Destroy() 223 224``` 225void OH_CryptoSymKey_Destroy(OH_CryptoSymKey *keyCtx) 226``` 227 228**Description** 229 230Destroys a symmetric key instance. 231 232**Since**: 12 233 234 235**Parameters** 236 237| Name| Description| 238| -- | -- | 239| [OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) *keyCtx | Pointer to the symmetric key instance.| 240