1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup CryptoMacApi 18 * @{ 19 * 20 * @brief Describes the MAC algorithm interface provided to applications. 21 * 22 * @since 20 23 */ 24 25 /** 26 * @file crypto_mac.h 27 * 28 * @brief Defines the MAC algorithm APIs. 29 * 30 * @library libohcrypto.so 31 * @kit CryptoArchitectureKit 32 * @syscap SystemCapability.Security.CryptoFramework 33 * @since 20 34 */ 35 36 #ifndef CRYPTO_MAC_H 37 #define CRYPTO_MAC_H 38 39 #include "crypto_common.h" 40 #include "crypto_sym_key.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @brief Defines the MAC structure. 48 * 49 * @since 20 50 */ 51 typedef struct OH_CryptoMac OH_CryptoMac; 52 53 /** 54 * @brief Defines the MAC algorithm parameter type. 55 * 56 * @since 20 57 */ 58 typedef enum { 59 /** Indicates the algorithm name of the message digest function for HMAC. e.g. "SHA256".*/ 60 CRYPTO_MAC_DIGEST_NAME_STR = 0, 61 62 /** Indicates the algorithm name of the symmetric cipher function for CMAC. e.g. "AES256".*/ 63 CRYPTO_MAC_CIPHER_NAME_STR = 1, 64 } CryptoMac_ParamType; 65 66 /** 67 * @brief Creates a MAC context according to the given algorithm name. 68 * 69 * @param algoName Indicates the algorithm name for generating the MAC context. e.g. "HMAC", "CMAC". 70 * @param ctx Indicates the pointer to the MAC context. 71 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 72 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 73 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 74 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 75 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 76 * @since 20 77 */ 78 OH_Crypto_ErrCode OH_CryptoMac_Create(const char *algoName, OH_CryptoMac **ctx); 79 80 /** 81 * @brief Sets the specified parameter to the MAC context. 82 * 83 * @param ctx Indicates the MAC context. 84 * @param type Indicates the MAC parameter type. 85 * @param value Indicates the parameter value. 86 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 87 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 88 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 89 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 90 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 91 * @since 20 92 */ 93 OH_Crypto_ErrCode OH_CryptoMac_SetParam(OH_CryptoMac *ctx, CryptoMac_ParamType type, const Crypto_DataBlob *value); 94 95 /** 96 * @brief Initializes the MAC context with a symmetric key. 97 * 98 * @param ctx Indicates the MAC context. 99 * @param key Indicates the symmetric key. 100 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 101 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 102 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 103 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 104 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 105 * @see OH_CryptoMac_Update 106 * @see OH_CryptoMac_Final 107 * @since 20 108 */ 109 OH_Crypto_ErrCode OH_CryptoMac_Init(OH_CryptoMac *ctx, const OH_CryptoSymKey *key); 110 111 /** 112 * @brief Updates the MAC context with data. 113 * 114 * @param ctx Indicates the MAC context. 115 * @param in Indicates the data to update. 116 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 117 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 118 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 119 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 120 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 121 * @see OH_CryptoMac_Init 122 * @see OH_CryptoMac_Final 123 * @since 20 124 */ 125 OH_Crypto_ErrCode OH_CryptoMac_Update(OH_CryptoMac *ctx, const Crypto_DataBlob *in); 126 127 /** 128 * @brief Finalizes the MAC operation. 129 * 130 * @param ctx Indicates the MAC context. 131 * @param out Indicates the MAC result. 132 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 133 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 134 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 135 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 136 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 137 * @see OH_CryptoMac_Init 138 * @see OH_CryptoMac_Update 139 * @since 20 140 */ 141 OH_Crypto_ErrCode OH_CryptoMac_Final(OH_CryptoMac *ctx, Crypto_DataBlob *out); 142 143 /** 144 * @brief Gets the length of the MAC. 145 * 146 * @param ctx Indicates the MAC context. 147 * @param length Indicates the MAC length. 148 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 149 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 150 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 151 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 152 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 153 * @since 20 154 */ 155 OH_Crypto_ErrCode OH_CryptoMac_GetLength(OH_CryptoMac *ctx, uint32_t *length); 156 157 /** 158 * @brief Destroys the MAC context. 159 * 160 * @param ctx Indicates the MAC context. 161 * @since 20 162 */ 163 void OH_CryptoMac_Destroy(OH_CryptoMac *ctx); 164 165 #ifdef __cplusplus 166 } 167 #endif 168 169 #endif /* CRYPTO_MAC_H */ 170 /** @} */ 171