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 CryptoSymKeyApi
18 * @{
19 *
20 * @brief Describe openHarmony symmetric key related features interfaces provide for applications.
21 *
22 * @since 12
23 */
24
25/**
26 * @file crypto_sym_key.h
27 *
28 * @brief Defines the symmetric key APIs.
29 *
30 * @library libohcrypto.so
31 * @kit CryptoArchitectureKit
32 * @syscap SystemCapability.Security.CryptoFramework
33 * @since 12
34 */
35
36#ifndef CRYPTO_SYM_KEY_H
37#define CRYPTO_SYM_KEY_H
38
39#include "crypto_common.h"
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/**
46 * @brief Define the symmetric key structure.
47 *
48 * @since 12
49 */
50typedef struct OH_CryptoSymKey OH_CryptoSymKey;
51
52/**
53 * @brief Define the symmetric key generator structure.
54 *
55 * @since 12
56 */
57typedef struct OH_CryptoSymKeyGenerator OH_CryptoSymKeyGenerator;
58
59/**
60 * @brief Create a symmetric key generator according to the given algorithm name. Example AES256.
61 *
62 * @param algoName Indicates the algorithm name for generating the generator.
63 * @param ctx Indicates the pointer to the symmetric key generator context.
64 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
65 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
66 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
67 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
68 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
69 * @since 12
70 */
71OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Create(const char *algoName, OH_CryptoSymKeyGenerator **ctx);
72
73/**
74 * @brief Generate a symmetric key.
75 *
76 * @param ctx Indicates the Symmetric key generator context.
77 * @param keyCtx Indicates the pointer to the symmetric key context.
78 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
79 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
80 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
81 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
82 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
83 * @since 12
84 */
85OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Generate(OH_CryptoSymKeyGenerator *ctx, OH_CryptoSymKey **keyCtx);
86
87/**
88 * @brief Convert the symmetric key data to a key.
89 *
90 * @param ctx Indicates the symmetric key generator context.
91 * @param keyData Indicates the data to generate the Symkey.
92 * @param keyCtx Indicates the pointer to the symmetric key context.
93 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
94 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
95 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
96 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
97 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
98 * @since 12
99 */
100OH_Crypto_ErrCode OH_CryptoSymKeyGenerator_Convert(OH_CryptoSymKeyGenerator *ctx,
101    const Crypto_DataBlob *keyData, OH_CryptoSymKey **keyCtx);
102
103/**
104 * @brief Get the algorithm name of the symmetric key generator.
105 *
106 * @param ctx Indicates the symmetric key generator context.
107 * @return Return symmetric key algorithm name.
108 * @since 12
109 */
110const char *OH_CryptoSymKeyGenerator_GetAlgoName(OH_CryptoSymKeyGenerator *ctx);
111
112/**
113 * @brief Destroy the symmetric key generator.
114 *
115 * @param ctx Indicates the symmetric key generator context.
116 * @since 12
117 */
118void OH_CryptoSymKeyGenerator_Destroy(OH_CryptoSymKeyGenerator *ctx);
119
120/**
121 * @brief Get the symmetric key algorithm name from a symmetric key.
122 *
123 * @param keyCtx Indicates the symmetric key context.
124 * @return Return algorithm name.
125 * @since 12
126 */
127const char *OH_CryptoSymKey_GetAlgoName(OH_CryptoSymKey *keyCtx);
128
129/**
130 * @brief Get the symmetric key data from a symmetric key.
131 *
132 * @param keyCtx Indicates the symmetric key context.
133 * @param out Indicate to obtain the result.
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 * @since 12
140 */
141OH_Crypto_ErrCode OH_CryptoSymKey_GetKeyData(OH_CryptoSymKey *keyCtx, Crypto_DataBlob *out);
142
143/**
144 * @brief Destroy the symmetric key.
145 *
146 * @param keyCtx Indicates the symmetric key context.
147 * @since 12
148 */
149void OH_CryptoSymKey_Destroy(OH_CryptoSymKey *keyCtx);
150
151#ifdef __cplusplus
152}
153#endif
154
155/** @} */
156#endif /* CRYPTO_SYM_KEY_H */
157