1 /* 2 * Copyright (C) 2024 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 CryptoSymCipherApi 18 * @{ 19 * 20 * @brief Describe the functions provided by the openHarmony symmetric key encryption 21 * and decryption interface for applications. 22 * 23 * @since 12 24 */ 25 26 /** 27 * @file crypto_sym_cipher.h 28 * 29 * @brief Defines the symmetric key cipher APIs. 30 * 31 * @library libohcrypto.so 32 * @kit Crypto Architecture Kit 33 * @syscap SystemCapability.Security.CryptoFramework 34 * @since 12 35 */ 36 37 #ifndef CRYPTO_SYM_CIPHER_H 38 #define CRYPTO_SYM_CIPHER_H 39 40 #include "crypto_common.h" 41 #include "crypto_sym_key.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Define the cipher param type. 49 * 50 * @since 12 51 */ 52 typedef enum { 53 /** Indicates the parameters such as iv. */ 54 CRYPTO_IV_DATABLOB = 100, 55 /** Indicates the additional Authenticated Data in GCM mode. */ 56 CRYPTO_AAD_DATABLOB = 101, 57 /** Indicates the output tag from the encryption operation. The tag is used for integrity check. */ 58 CRYPTO_TAG_DATABLOB = 102, 59 } CryptoSymCipher_ParamsType; 60 61 /** 62 * @brief Define the symmetric key cipher structure. 63 * 64 * @since 12 65 */ 66 typedef struct OH_CryptoSymCipher OH_CryptoSymCipher; 67 68 /** 69 * @brief Define the symmetric key cipher params structure. 70 * 71 * @since 12 72 */ 73 typedef struct OH_CryptoSymCipherParams OH_CryptoSymCipherParams; 74 75 /** 76 * @brief Create a symmetric key cipher params. 77 * 78 * @param params Indicates the pointer to the cipher params context. 79 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 80 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 81 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 82 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 83 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 84 * @since 12 85 */ 86 OH_Crypto_ErrCode OH_CryptoSymCipherParams_Create(OH_CryptoSymCipherParams **params); 87 88 /** 89 * @brief Set a parameter to the cipher params context. 90 * 91 * @param params Indicates the parameters context. 92 * @param paramsType Set cipher parameters. 93 * @param value Indicates the setParam result. 94 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 95 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 96 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 97 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 98 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 99 * @since 12 100 */ 101 OH_Crypto_ErrCode OH_CryptoSymCipherParams_SetParam(OH_CryptoSymCipherParams *params, 102 CryptoSymCipher_ParamsType paramsType, Crypto_DataBlob *value); 103 104 /** 105 * @brief Destroy the cipher params context. 106 * 107 * @param params Indicates the parameters context. 108 * @since 12 109 */ 110 void OH_CryptoSymCipherParams_Destroy(OH_CryptoSymCipherParams *params); 111 112 /** 113 * @brief Create a symmetric key cipher context according to the given algorithm name. 114 * 115 * @param algoName Indicates the algorithm name used to generate the symmetric key cipher context. 116 * Example AES128|GCM|PKCS7. 117 * @param ctx Indicates the pointer to the symmetric key cipher context. 118 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 119 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 120 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 121 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 122 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 123 * @since 12 124 */ 125 OH_Crypto_ErrCode OH_CryptoSymCipher_Create(const char *algoName, OH_CryptoSymCipher **ctx); 126 127 /** 128 * @brief Init the crypto operation with the given crypto mode, key and parameters. 129 * 130 * @param ctx Indicates the symmetric key cipher context. 131 * @param mod Indicates the crypto mode is encryption or decryption. 132 * @param key Indicates the symmetric key or the asymmetric key. 133 * @param params Indicates the algorithm parameters such as IV. 134 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 135 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 136 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 137 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 138 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 139 * @see OH_CryptoSymCipher_Update 140 * @see OH_CryptoSymCipher_Final 141 * @since 12 142 */ 143 OH_Crypto_ErrCode OH_CryptoSymCipher_Init(OH_CryptoSymCipher *ctx, Crypto_CipherMode mod, 144 OH_CryptoSymKey *key, OH_CryptoSymCipherParams *params); 145 146 /** 147 * @brief Update the crypto operation with the input data, and feed back the encrypted or decrypted data. 148 * 149 * @param ctx Indicates the symmetric key cipher context. 150 * @param in Indicates the data to be encrypted or decrypted. 151 * @param out Indicates the data to be update encrypted or decrypted. 152 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 153 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 154 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 155 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 156 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 157 * @see OH_CryptoSymCipher_Init 158 * @see OH_CryptoSymCipher_Final 159 * @since 12 160 */ 161 OH_Crypto_ErrCode OH_CryptoSymCipher_Update(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out); 162 163 /** 164 * @brief Finish the crypto operation, encrypt or decrypt the input data, and then feed back the output data. 165 * 166 * @param ctx Indicates the symmetric key cipher context. 167 * @param in Indicates the data to be encrypted or decrypted. 168 * @param out Indicates the data to be finally encrypted or decrypted. 169 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 170 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 171 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 172 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 173 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 174 * @see OH_CryptoSymCipher_Init 175 * @see OH_CryptoSymCipher_Update 176 * @since 12 177 */ 178 OH_Crypto_ErrCode OH_CryptoSymCipher_Final(OH_CryptoSymCipher *ctx, Crypto_DataBlob *in, Crypto_DataBlob *out); 179 180 /** 181 * @brief Get the algorithm name of the symmetric key cipher context. 182 * 183 * @param ctx Indicates the symmetric key context. 184 * @return Return symmetric key cipher algorithm name. 185 * @since 12 186 */ 187 const char *OH_CryptoSymCipher_GetAlgoName(OH_CryptoSymCipher *ctx); 188 189 /** 190 * @brief Destroy the symmetric key cipher context. 191 * 192 * @param ctx Indicates the symmetric key context. 193 * @since 12 194 */ 195 void OH_CryptoSymCipher_Destroy(OH_CryptoSymCipher *ctx); 196 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 /** @} */ 203 #endif /* CRYPTO_SYM_CIPHER_H */ 204