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 CryptoSignatureApi
18 * @{
19 *
20 * @brief Describe openHarmony signature verification interfaces provide for applications.
21 *
22 * @since 12
23 */
24
25/**
26 * @file crypto_signature.h
27 *
28 * @brief Defines the Signature APIs.
29 *
30 * @library libohcrypto.so
31 * @kit CryptoArchitectureKit
32 * @syscap SystemCapability.Security.CryptoFramework
33 * @since 12
34 */
35
36#ifndef CRYPTO_SIGNATURE_H
37#define CRYPTO_SIGNATURE_H
38
39#include "crypto_common.h"
40#include "crypto_asym_key.h"
41#include <stdbool.h>
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48 * @brief Define the signature param type.
49 *
50 * @since 12
51 */
52typedef enum {
53    /** Indicates the algorithm name of the message digest function.*/
54    CRYPTO_PSS_MD_NAME_STR = 100,
55    /** Indicates the algorithm name for the mask generation function. */
56    CRYPTO_PSS_MGF_NAME_STR = 101,
57    /** Indicates the message digest parameter for the MGF1 mask generation function. */
58    CRYPTO_PSS_MGF1_NAME_STR = 102,
59    /** Indicates the salt length in bits. */
60    CRYPTO_PSS_SALT_LEN_INT = 103,
61    /** Indicates the value for the trailer field. */
62    CRYPTO_PSS_TRAILER_FIELD_INT = 104,
63    /** Indicates the value for user id. */
64    CRYPTO_SM2_USER_ID_DATABLOB = 105,
65} CryptoSignature_ParamType;
66
67/**
68 * @brief Define the verify structure.
69 *
70 * @since 12
71 */
72typedef struct OH_CryptoVerify OH_CryptoVerify;
73
74/**
75 * @brief Create a verify context according to the given algorithm name.
76 *
77 * @param algoName Indicates the algorithm name for generating the verify context. Example RSA1024|PKCS1|SHA256.
78 * @param ctx Indicates the pointer to the verify 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_CryptoVerify_Create(const char *algoName, OH_CryptoVerify **verify);
87
88/**
89 * @brief Init verify context with given public Key.
90 *
91 * @param ctx Indicates the verify context.
92 * @param pubKey indicates the public Key
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 * @see OH_CryptoVerify_Update
99 * @see OH_CryptoVerify_Final
100 * @since 12
101 */
102OH_Crypto_ErrCode OH_CryptoVerify_Init(OH_CryptoVerify *ctx, OH_CryptoPubKey *pubKey);
103
104/**
105 * @brief Used to append the message that needs to be verified.
106 *
107 * @param ctx Indicates the verify context.
108 * @param in Indicates the data need to be verified.
109 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
110 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
111 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
112 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
113 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
114 * @see OH_CryptoVerify_Init
115 * @see OH_CryptoVerify_Final
116 * @since 12
117 */
118OH_Crypto_ErrCode OH_CryptoVerify_Update(OH_CryptoVerify *ctx, Crypto_DataBlob *in);
119
120/**
121 * @brief Used to verify the message.
122 *
123 * @param ctx Indicates the verify context.
124 * @param in Indicates the data need to be verified.
125 * @param signData Indicates the signature data.
126 * @return Return result use bool value.
127 * @see OH_CryptoVerify_Init
128 * @see OH_CryptoVerify_Update
129 * @since 12
130 */
131bool OH_CryptoVerify_Final(OH_CryptoVerify *ctx, Crypto_DataBlob *in, Crypto_DataBlob *signData);
132
133/**
134 * @brief Used to recover signed data.
135 *
136 * @param ctx Indicates the verify context.
137 * @param signData Indicates the signature data.
138 * @param rawSignData Indicates the raw sign data.
139 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
140 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
141 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
142 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
143 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
144 * @since 12
145 */
146OH_Crypto_ErrCode OH_CryptoVerify_Recover(OH_CryptoVerify *ctx, Crypto_DataBlob *signData,
147    Crypto_DataBlob *rawSignData);
148
149/**
150 * @brief Get the algorithm name of the verify context.
151 *
152 * @param ctx Indicates the verify context.
153 * @return Return verify algorithm name.
154 * @since 12
155 */
156const char *OH_CryptoVerify_GetAlgoName(OH_CryptoVerify *ctx);
157
158/**
159 * @brief Set the specified parameter to the verify context.
160 *
161 * @param ctx Indicates the verify context.
162 * @param type Indicates the verify signature_paramType.
163 * @param value Indicates the verify result.
164 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
165 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
166 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
167 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
168 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
169 * @since 12
170 */
171OH_Crypto_ErrCode OH_CryptoVerify_SetParam(OH_CryptoVerify *ctx, CryptoSignature_ParamType type,
172    Crypto_DataBlob *value);
173
174/**
175 * @brief Get the specified parameter from the verify context.
176 *
177 * @param ctx Indicates the verify context.
178 * @param type Indicates the verify signature_paramType.
179 * @param value Indicates the verify result.
180 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful.
181 *         {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid.
182 *         {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported.
183 *         {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed.
184 *         {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed.
185 * @since 12
186 */
187OH_Crypto_ErrCode OH_CryptoVerify_GetParam(OH_CryptoVerify *ctx, CryptoSignature_ParamType type,
188    Crypto_DataBlob *value);
189
190/**
191 * @brief Destroy the verify context.
192 *
193 * @param ctx Indicates the verify context.
194 * @since 12
195 */
196void OH_CryptoVerify_Destroy(OH_CryptoVerify *ctx);
197
198#ifdef __cplusplus
199}
200#endif
201
202/** @} */
203#endif /* CRYPTO_SIGNATURE_H */
204