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 CryptoArchitectureKit
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
44extern "C" {
45#endif
46
47/**
48 * @brief Define the cipher param type.
49 *
50 * @since 12
51 */
52typedef 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 */
66typedef struct OH_CryptoSymCipher OH_CryptoSymCipher;
67
68/**
69 * @brief Define the symmetric key cipher params structure.
70 *
71 * @since 12
72 */
73typedef 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 */
86OH_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 */
101OH_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 */
110void 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 */
125OH_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 */
143OH_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 */
161OH_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 */
178OH_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 */
187const 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 */
195void OH_CryptoSymCipher_Destroy(OH_CryptoSymCipher *ctx);
196
197
198#ifdef __cplusplus
199}
200#endif
201
202/** @} */
203#endif /* CRYPTO_SYM_CIPHER_H */
204