1 /* 2 * Copyright (C) 2024-2025 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 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Define the signature param type. 49 * 50 * @since 12 51 */ 52 typedef 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 */ 72 typedef struct OH_CryptoVerify OH_CryptoVerify; 73 74 /** 75 * @brief Defines the sign structure. 76 * 77 * @since 20 78 */ 79 typedef struct OH_CryptoSign OH_CryptoSign; 80 81 /** 82 * @brief Create a verify context according to the given algorithm name. 83 * 84 * @param algoName Indicates the algorithm name for generating the verify context. Example RSA1024|PKCS1|SHA256. 85 * @param verify Indicates the pointer to the verify context. 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 * @since 12 92 */ 93 OH_Crypto_ErrCode OH_CryptoVerify_Create(const char *algoName, OH_CryptoVerify **verify); 94 95 /** 96 * @brief Init verify context with given public Key. 97 * 98 * @param ctx Indicates the verify context. 99 * @param pubKey indicates the public Key 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 * @see OH_CryptoVerify_Update 106 * @see OH_CryptoVerify_Final 107 * @since 12 108 */ 109 OH_Crypto_ErrCode OH_CryptoVerify_Init(OH_CryptoVerify *ctx, OH_CryptoPubKey *pubKey); 110 111 /** 112 * @brief Used to append the message that needs to be verified. 113 * 114 * @param ctx Indicates the verify context. 115 * @param in Indicates the data need to be verified. 116 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 117 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 118 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 119 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 120 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 121 * @see OH_CryptoVerify_Init 122 * @see OH_CryptoVerify_Final 123 * @since 12 124 */ 125 OH_Crypto_ErrCode OH_CryptoVerify_Update(OH_CryptoVerify *ctx, Crypto_DataBlob *in); 126 127 /** 128 * @brief Used to verify the message. 129 * 130 * @param ctx Indicates the verify context. 131 * @param in Indicates the data need to be verified. 132 * @param signData Indicates the signature data. 133 * @return Return result use bool value. 134 * @see OH_CryptoVerify_Init 135 * @see OH_CryptoVerify_Update 136 * @since 12 137 */ 138 bool OH_CryptoVerify_Final(OH_CryptoVerify *ctx, Crypto_DataBlob *in, Crypto_DataBlob *signData); 139 140 /** 141 * @brief Used to recover signed data. 142 * 143 * @param ctx Indicates the verify context. 144 * @param signData Indicates the signature data. 145 * @param rawSignData Indicates the raw sign data. 146 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 147 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 148 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 149 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 150 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 151 * @since 12 152 */ 153 OH_Crypto_ErrCode OH_CryptoVerify_Recover(OH_CryptoVerify *ctx, Crypto_DataBlob *signData, 154 Crypto_DataBlob *rawSignData); 155 156 /** 157 * @brief Get the algorithm name of the verify context. 158 * 159 * @param ctx Indicates the verify context. 160 * @return Return verify algorithm name. 161 * @since 12 162 */ 163 const char *OH_CryptoVerify_GetAlgoName(OH_CryptoVerify *ctx); 164 165 /** 166 * @brief Set the specified parameter to the verify context. 167 * 168 * @param ctx Indicates the verify context. 169 * @param type Indicates the verify parameter type. 170 * @param value Indicates the input data. 171 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 172 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 173 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 174 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 175 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 176 * @since 12 177 */ 178 OH_Crypto_ErrCode OH_CryptoVerify_SetParam(OH_CryptoVerify *ctx, CryptoSignature_ParamType type, 179 Crypto_DataBlob *value); 180 181 /** 182 * @brief Get the specified parameter from the verify context. 183 * 184 * @param ctx Indicates the verify context. 185 * @param type Indicates the verify parameter type. 186 * @param value Indicates the output data. 187 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 188 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 189 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 190 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 191 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 192 * @since 12 193 */ 194 OH_Crypto_ErrCode OH_CryptoVerify_GetParam(OH_CryptoVerify *ctx, CryptoSignature_ParamType type, 195 Crypto_DataBlob *value); 196 197 /** 198 * @brief Destroy the verify context. 199 * 200 * @param ctx Indicates the verify context. 201 * @since 12 202 */ 203 void OH_CryptoVerify_Destroy(OH_CryptoVerify *ctx); 204 205 /** 206 * @brief Creates a sign context according to the given algorithm name. 207 * 208 * @param algoName Indicates the algorithm name for generating the sign context. e.g. "RSA|PKCS1|SHA384", "ECC|SHA384". 209 * @param sign Indicates the sign context. 210 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 211 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 212 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 213 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 214 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 215 * @since 20 216 */ 217 OH_Crypto_ErrCode OH_CryptoSign_Create(const char *algoName, OH_CryptoSign **sign); 218 219 /** 220 * @brief Initializes the sign context. 221 * 222 * @param ctx Indicates the sign context. 223 * @param privKey Indicates the private key. 224 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 225 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 226 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 227 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 228 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 229 * @see OH_CryptoSign_Update 230 * @see OH_CryptoSign_Final 231 * @since 20 232 */ 233 OH_Crypto_ErrCode OH_CryptoSign_Init(OH_CryptoSign *ctx, OH_CryptoPrivKey *privKey); 234 235 /** 236 * @brief Updates the data to be signed. 237 * 238 * @param ctx Indicates the sign context. 239 * @param in Indicates the data to be signed. 240 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 241 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 242 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 243 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 244 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 245 * @see OH_CryptoSign_Init 246 * @see OH_CryptoSign_Final 247 * @since 20 248 */ 249 OH_Crypto_ErrCode OH_CryptoSign_Update(OH_CryptoSign *ctx, const Crypto_DataBlob *in); 250 251 /** 252 * @brief Finalizes the sign operation. 253 * 254 * @param ctx Indicates the sign context. 255 * @param in Indicates the data to be signed, if OH_CryptoSign_Update has been called, this parameter can be NULL. 256 * @param out Indicates the sign result. 257 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 258 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 259 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 260 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 261 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 262 * @see OH_CryptoSign_Init 263 * @see OH_CryptoSign_Update 264 * @since 20 265 */ 266 OH_Crypto_ErrCode OH_CryptoSign_Final(OH_CryptoSign *ctx, const Crypto_DataBlob *in, Crypto_DataBlob *out); 267 268 /** 269 * @brief Gets the algorithm name of the sign context. 270 * 271 * @param ctx Indicates the sign context. 272 * @return Return signature algorithm name. 273 * @since 20 274 */ 275 const char *OH_CryptoSign_GetAlgoName(OH_CryptoSign *ctx); 276 277 /** 278 * @brief Sets the specified parameter to the sign context. 279 * 280 * @param ctx Indicates the sign context. 281 * @param type Indicates the signature parameter type. 282 * @param value Indicates the input data. 283 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 284 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 285 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 286 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 287 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 288 * @since 20 289 */ 290 OH_Crypto_ErrCode OH_CryptoSign_SetParam(OH_CryptoSign *ctx, CryptoSignature_ParamType type, 291 const Crypto_DataBlob *value); 292 293 /** 294 * @brief Gets the specified parameter from the sign context. 295 * 296 * @param ctx Indicates the sign context. 297 * @param type Indicates the signature parameter type. 298 * @param value Indicates the output data. 299 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 300 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 301 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 302 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 303 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 304 * @since 20 305 */ 306 OH_Crypto_ErrCode OH_CryptoSign_GetParam(OH_CryptoSign *ctx, CryptoSignature_ParamType type, Crypto_DataBlob *value); 307 308 /** 309 * @brief Destroys the sign context. 310 * 311 * @param ctx Indicates the sign context. 312 * @since 20 313 */ 314 void OH_CryptoSign_Destroy(OH_CryptoSign *ctx); 315 316 /** 317 * @brief Defines the ECC signature spec. 318 * 319 * @since 20 320 */ 321 typedef struct OH_CryptoEccSignatureSpec OH_CryptoEccSignatureSpec; 322 323 /** 324 * @brief Creates the ECC signature spec, also support SM2 signature. 325 * 326 * @param eccSignature Indicates the ECC signature in DER format, if eccSignature parameter is NULL, 327 * an empty ECC signature spec will be created. 328 * @param spec Indicates the output ECC signature spec. 329 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 330 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 331 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 332 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 333 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 334 * @since 20 335 */ 336 OH_Crypto_ErrCode OH_CryptoEccSignatureSpec_Create(Crypto_DataBlob *eccSignature, 337 OH_CryptoEccSignatureSpec **spec); 338 339 /** 340 * @brief Gets the r and s value from the ECC signature spec. 341 * 342 * @param spec Indicates the ECC signature spec. 343 * @param r Indicates the output r value. 344 * @param s Indicates the output s value. 345 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 346 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 347 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 348 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 349 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 350 * @since 20 351 */ 352 OH_Crypto_ErrCode OH_CryptoEccSignatureSpec_GetRAndS(OH_CryptoEccSignatureSpec *spec, Crypto_DataBlob *r, 353 Crypto_DataBlob *s); 354 355 /** 356 * @brief Sets the r and s value to the ECC signature spec. 357 * 358 * @param spec Indicates the ECC signature spec. 359 * @param r Indicates the input r value. 360 * @param s Indicates the input s value. 361 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 362 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 363 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 364 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 365 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 366 * @since 20 367 */ 368 OH_Crypto_ErrCode OH_CryptoEccSignatureSpec_SetRAndS(OH_CryptoEccSignatureSpec *spec, Crypto_DataBlob *r, 369 Crypto_DataBlob *s); 370 371 /** 372 * @brief Encodes the ECC signature spec to signature data in DER format. 373 * 374 * @param spec Indicates the ECC signature spec. 375 * @param out Indicates the output data blob. 376 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 377 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 378 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 379 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 380 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 381 * @since 20 382 */ 383 OH_Crypto_ErrCode OH_CryptoEccSignatureSpec_Encode(OH_CryptoEccSignatureSpec *spec, Crypto_DataBlob *out); 384 385 /** 386 * @brief Destroys the ECC signature spec. 387 * 388 * @param spec Indicates the ECC signature spec. 389 * @since 20 390 */ 391 void OH_CryptoEccSignatureSpec_Destroy(OH_CryptoEccSignatureSpec *spec); 392 393 394 #ifdef __cplusplus 395 } 396 #endif 397 398 /** @} */ 399 #endif /* CRYPTO_SIGNATURE_H */ 400