1# crypto_mac.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 12Define message authentication code (MAC) APIs. 13 14**Header file**: <CryptoArchitectureKit/crypto_mac.h> 15 16**Library**: libohcrypto.so 17 18**System capability**: SystemCapability.Security.CryptoFramework 19 20**Since**: 20 21 22**Related Module**: [CryptoMacApi](capi-cryptomacapi.md) 23 24## Summary 25 26### Structs 27 28| Name| typedef Keyword| Description| 29| -- | -- | -- | 30| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) | OH_CryptoMac | Defines a struct for a MAC.| 31 32### Enums 33 34| Name| typedef Keyword| Description| 35| -- | -- | -- | 36| [CryptoMac_ParamType](#cryptomac_paramtype) | CryptoMac_ParamType | Defines the parameter type for the MAC algorithm.| 37 38### Functions 39 40| Name| Description| 41| -- | -- | 42| [OH_Crypto_ErrCode OH_CryptoMac_Create(const char *algoName, OH_CryptoMac **ctx)](#oh_cryptomac_create) | Creates a MAC instance based on the given algorithm name.| 43| [OH_Crypto_ErrCode OH_CryptoMac_SetParam(OH_CryptoMac *ctx, CryptoMac_ParamType type, const Crypto_DataBlob *value)](#oh_cryptomac_setparam) | Sets MAC parameters.| 44| [OH_Crypto_ErrCode OH_CryptoMac_Init(OH_CryptoMac *ctx, const OH_CryptoSymKey *key)](#oh_cryptomac_init) | Initializes a MAC instance using a symmetric key.| 45| [OH_Crypto_ErrCode OH_CryptoMac_Update(OH_CryptoMac *ctx, const Crypto_DataBlob *in)](#oh_cryptomac_update) | Updates a MAC instance.| 46| [OH_Crypto_ErrCode OH_CryptoMac_Final(OH_CryptoMac *ctx, Crypto_DataBlob *out)](#oh_cryptomac_final) | Finalizes a MAC operation.| 47| [OH_Crypto_ErrCode OH_CryptoMac_GetLength(OH_CryptoMac *ctx, uint32_t *length)](#oh_cryptomac_getlength) | Obtains the MAC length.| 48| [void OH_CryptoMac_Destroy(OH_CryptoMac *ctx)](#oh_cryptomac_destroy) | Destroys a MAC instance.| 49 50## Enum Description 51 52### CryptoMac_ParamType 53 54``` 55enum CryptoMac_ParamType 56``` 57 58**Description** 59 60Defines the parameter type for the MAC algorithm. 61 62**Since**: 20 63 64| Enum Item| Description| 65| -- | -- | 66| CRYPTO_MAC_DIGEST_NAME_STR = 0 | Algorithm name of the digest function used by the HMAC, for example, **SHA256**.| 67| CRYPTO_MAC_CIPHER_NAME_STR = 1 | Name of the symmetric encryption algorithm used by the CMAC, for example, **AES256.**| 68 69 70## Function Description 71 72### OH_CryptoMac_Create() 73 74``` 75OH_Crypto_ErrCode OH_CryptoMac_Create(const char *algoName, OH_CryptoMac **ctx) 76``` 77 78**Description** 79 80Creates a MAC instance based on the given algorithm name. 81 82**Since**: 20 83 84 85**Parameters** 86 87| Name| Description| 88| -- | -- | 89| const char *algoName | Pointer to the algorithm used to generate the MAC instance.<br> For example, **HMAC** or **CMAC**.| 90| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) **ctx | MAC instance.| 91 92**Returns** 93 94| Type| Description| 95| -- | -- | 96| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERATION_ERROR**: An error occurs when the API of a third-party algorithm library is called.| 97 98### OH_CryptoMac_SetParam() 99 100``` 101OH_Crypto_ErrCode OH_CryptoMac_SetParam(OH_CryptoMac *ctx, CryptoMac_ParamType type, const Crypto_DataBlob *value) 102``` 103 104**Description** 105 106Sets MAC parameters. 107 108**Since**: 20 109 110 111**Parameters** 112 113| Name| Description| 114| -- | -- | 115| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) *ctx | MAC instance.| 116| [CryptoMac_ParamType](#cryptomac_paramtype) type | MAC parameter type.| 117| [const Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *value | MAC parameters.| 118 119**Returns** 120 121| Type| Description| 122| -- | -- | 123| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERATION_ERROR**: An error occurs when the API of a third-party algorithm library is called.| 124 125### OH_CryptoMac_Init() 126 127``` 128OH_Crypto_ErrCode OH_CryptoMac_Init(OH_CryptoMac *ctx, const OH_CryptoSymKey *key) 129``` 130 131**Description** 132 133Initializes a MAC instance using a symmetric key. 134 135**Since**: 20 136 137 138**Parameters** 139 140| Name| Description| 141| -- | -- | 142| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) *ctx | MAC instance.| 143| [const OH_CryptoSymKey](capi-cryptosymkeyapi-oh-cryptosymkey.md) *key | Symmetric key obtained.| 144 145**Returns** 146 147| Type| Description| 148| -- | -- | 149| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERATION_ERROR**: An error occurs when the API of a third-party algorithm library is called.| 150 151**Reference** 152 153[OH_CryptoMac_Update](#oh_cryptomac_update) 154 155[OH_CryptoMac_Final](#oh_cryptomac_final) 156 157 158### OH_CryptoMac_Update() 159 160``` 161OH_Crypto_ErrCode OH_CryptoMac_Update(OH_CryptoMac *ctx, const Crypto_DataBlob *in) 162``` 163 164**Description** 165 166Updates a MAC instance. 167 168**Since**: 20 169 170 171**Parameters** 172 173| Name| Description| 174| -- | -- | 175| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) *ctx | MAC instance.| 176| [const Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | Data to be updated.| 177 178**Returns** 179 180| Type| Description| 181| -- | -- | 182| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERATION_ERROR**: An error occurs when the API of a third-party algorithm library is called.| 183 184**Reference** 185 186[OH_CryptoMac_Init](#oh_cryptomac_init) 187 188[OH_CryptoMac_Final](#oh_cryptomac_final) 189 190 191### OH_CryptoMac_Final() 192 193``` 194OH_Crypto_ErrCode OH_CryptoMac_Final(OH_CryptoMac *ctx, Crypto_DataBlob *out) 195``` 196 197**Description** 198 199Finalizes a MAC operation. 200 201**Since**: 20 202 203 204**Parameters** 205 206| Name| Description| 207| -- | -- | 208| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) *ctx | MAC instance.| 209| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | MAC value.| 210 211**Returns** 212 213| Type| Description| 214| -- | -- | 215| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERATION_ERROR**: An error occurs when the API of a third-party algorithm library is called.| 216 217**Reference** 218 219[OH_CryptoMac_Init](#oh_cryptomac_init) 220 221[OH_CryptoMac_Update](#oh_cryptomac_update) 222 223 224### OH_CryptoMac_GetLength() 225 226``` 227OH_Crypto_ErrCode OH_CryptoMac_GetLength(OH_CryptoMac *ctx, uint32_t *length) 228``` 229 230**Description** 231 232Obtains the MAC length. 233 234**Since**: 20 235 236 237**Parameters** 238 239| Name| Description| 240| -- | -- | 241| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) *ctx | MAC instance.| 242| uint32_t *length | MAC length.| 243 244**Returns** 245 246| Type| Description| 247| -- | -- | 248| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERATION_ERROR**: An error occurs when the API of a third-party algorithm library is called.| 249 250### OH_CryptoMac_Destroy() 251 252``` 253void OH_CryptoMac_Destroy(OH_CryptoMac *ctx) 254``` 255 256**Description** 257 258Destroys a MAC instance. 259 260**Since**: 20 261 262 263**Parameters** 264 265| Name| Description| 266| -- | -- | 267| [OH_CryptoMac](capi-cryptomacapi-oh-cryptomac.md) *ctx | MAC instance.| 268