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 CryptoDigestApi
18 * @{
19 *
20 * @brief Describe openHarmony digest interfaces provide for applications.
21 *
22 * @since 12
23 */
24
25/**
26 * @file crypto_digest.h
27 *
28 * @brief Defines the digest APIs.
29 *
30 * @library libohcrypto.so
31 * @kit CryptoArchitectureKit
32 * @syscap SystemCapability.Security.CryptoFramework
33 * @since 12
34 */
35
36#ifndef CRYPTO_DIGEST_H
37#define CRYPTO_DIGEST_H
38
39#include "crypto_common.h"
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/**
46 * @brief Define the digest structure.
47 *
48 * @since 12
49 */
50typedef struct OH_CryptoDigest OH_CryptoDigest;
51
52/**
53 * @brief Create a digest context according to the given algorithm name.
54 *
55 * @param algoName Indicates the algorithm name for generating the digest context. Example SHA256.
56 * @param ctx Indicates the pointer to the md context.
57 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
58 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
59 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
60 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
61 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
62 * @since 12
63 */
64OH_Crypto_ErrCode OH_CryptoDigest_Create(const char *algoName, OH_CryptoDigest **ctx);
65
66/**
67 * @brief Update digest with dataBlob.
68 *
69 * @param ctx Indicates the digest context.
70 * @param in Indicates the dataBlob.
71 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
72 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
73 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
74 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
75 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
76 * @see OH_CryptoDigest_Final
77 * @since 12
78 */
79OH_Crypto_ErrCode OH_CryptoDigest_Update(OH_CryptoDigest *ctx, Crypto_DataBlob *in);
80
81/**
82 * @brief Final digest with dataBlob.
83 *
84 * @param ctx Indicates the digest context.
85 * @param out Indicates the result as dataBlob.
86 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
87 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
88 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
89 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
90 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
91 * @see OH_CryptoDigest_Update
92 * @since 12
93 */
94OH_Crypto_ErrCode OH_CryptoDigest_Final(OH_CryptoDigest *ctx, Crypto_DataBlob *out);
95
96/**
97 * @brief Get the digest length of the digest context.
98 *
99 * @param ctx Indicates the digest context.
100 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
101 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
102 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
103 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
104 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
105 * @since 12
106 */
107uint32_t OH_CryptoDigest_GetLength(OH_CryptoDigest *ctx);
108
109/**
110 * @brief Get the algorithm name of the digest context.
111 *
112 * @param ctx Indicates the digest context.
113 * @return Return md algorithm name.
114 * @since 12
115 */
116const char *OH_CryptoDigest_GetAlgoName(OH_CryptoDigest *ctx);
117
118/**
119 * @brief Destroy the digest context.
120 *
121 * @param ctx Indicates the digest context.
122 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
123 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
124 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
125 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
126 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
127 * @since 12
128 */
129void OH_DigestCrypto_Destroy(OH_CryptoDigest *ctx);
130
131#ifdef __cplusplus
132}
133#endif
134
135/** @} */
136#endif /* CRYPTO_DIGEST_H */