1 /* 2 * Copyright (c) 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 CryptoAsymCipherApi 18 * @{ 19 * 20 * @brief Describes the asymmetric encryption and decryption algorithm interface provided to applications. 21 * 22 * @since 20 23 */ 24 25 /** 26 * @file crypto_asym_cipher.h 27 * 28 * @brief Defines the asymmetric cipher APIs. 29 * 30 * @library libohcrypto.so 31 * @kit CryptoArchitectureKit 32 * @syscap SystemCapability.Security.CryptoFramework 33 * @since 20 34 */ 35 36 #ifndef CRYPTO_ASYM_CIPHER_H 37 #define CRYPTO_ASYM_CIPHER_H 38 39 #include "crypto_common.h" 40 #include "crypto_asym_key.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @brief Defines the asymmetric cipher structure. 48 * 49 * @since 20 50 */ 51 typedef struct OH_CryptoAsymCipher OH_CryptoAsymCipher; 52 53 /** 54 * @brief Creates an asymmetric cipher context according to the given algorithm name. 55 * 56 * @param algoName Indicates the algorithm name used to generate the asymmetric cipher context. e.g. "RSA|PKCS1", 57 * "RSA|PKCS1_OAEP|SHA384|MGF1_SHA384", "SM2|SM3". 58 * @param ctx Indicates the pointer to the asymmetric cipher context. 59 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 60 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 61 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 62 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 63 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 64 * @since 20 65 */ 66 OH_Crypto_ErrCode OH_CryptoAsymCipher_Create(const char *algoName, OH_CryptoAsymCipher **ctx); 67 68 /** 69 * @brief Initializes the asymmetric cipher context with the given crypto mode, key and parameters. 70 * 71 * @param ctx Indicates the asymmetric cipher context. 72 * @param mode Indicates the crypto mode is encryption or decryption. 73 * @param key Indicates the asymmetric key. 74 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 75 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 76 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 77 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 78 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 79 * @see OH_CryptoAsymCipher_Final 80 * @since 20 81 */ 82 OH_Crypto_ErrCode OH_CryptoAsymCipher_Init(OH_CryptoAsymCipher *ctx, Crypto_CipherMode mode, OH_CryptoKeyPair *key); 83 84 /** 85 * @brief Finalizes the encryption or decryption operation. 86 * 87 * @param ctx Indicates the asymmetric cipher context. 88 * @param in Indicates the input data to be encrypted or decrypted. 89 * @param out Indicates the result of encryption or decryption. 90 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 91 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 92 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 93 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 94 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 95 * @see OH_CryptoAsymCipher_Init 96 * @since 20 97 */ 98 OH_Crypto_ErrCode OH_CryptoAsymCipher_Final(OH_CryptoAsymCipher *ctx, const Crypto_DataBlob *in, 99 Crypto_DataBlob *out); 100 101 /** 102 * @brief Destroys the asymmetric cipher context. 103 * 104 * @param ctx Indicates the asymmetric cipher context. 105 * @since 20 106 */ 107 void OH_CryptoAsymCipher_Destroy(OH_CryptoAsymCipher *ctx); 108 109 /** 110 * @brief Defines the SM2 ciphertext spec structure. 111 * 112 * @since 20 113 */ 114 typedef struct OH_CryptoSm2CiphertextSpec OH_CryptoSm2CiphertextSpec; 115 116 /** 117 * @brief Defines the SM2 ciphertext spec item type. 118 * 119 * @since 20 120 */ 121 typedef enum { 122 /** Public key x, also known as C1x. */ 123 CRYPTO_SM2_CIPHERTEXT_C1_X = 0, 124 /** Public key y, also known as C1y. */ 125 CRYPTO_SM2_CIPHERTEXT_C1_Y = 1, 126 /** Hash, also known as C2. */ 127 CRYPTO_SM2_CIPHERTEXT_C2 = 2, 128 /** Ciphertext data, also known as C3. */ 129 CRYPTO_SM2_CIPHERTEXT_C3 = 3, 130 } CryptoSm2CiphertextSpec_item; 131 132 /** 133 * @brief Creates a SM2 ciphertext spec. 134 * 135 * @param sm2Ciphertext Indicates the SM2 ciphertext in DER format, if sm2Ciphertext param is NULL, 136 * an empty SM2 ciphertext spec will be created. 137 * @param spec Indicates the output SM2 ciphertext spec. 138 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 139 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 140 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 141 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 142 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 143 * @since 20 144 */ 145 OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_Create(Crypto_DataBlob *sm2Ciphertext, OH_CryptoSm2CiphertextSpec **spec); 146 147 /** 148 * @brief Gets the specified item of the SM2 ciphertext. 149 * 150 * @param spec Indicates the SM2 ciphertext spec. 151 * @param item Indicates the SM2 ciphertext spec item. 152 * @param out Indicates the output data. 153 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 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_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 157 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 158 * @since 20 159 */ 160 OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_GetItem(OH_CryptoSm2CiphertextSpec *spec, 161 CryptoSm2CiphertextSpec_item item, Crypto_DataBlob *out); 162 163 /** 164 * @brief Sets the specified item to the SM2 ciphertext spec. 165 * 166 * @param spec Indicates the SM2 ciphertext spec. 167 * @param item Indicates the SM2 ciphertext spec item. 168 * @param in Indicates the input data. 169 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 170 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 171 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 172 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 173 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 174 * @since 20 175 */ 176 OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_SetItem(OH_CryptoSm2CiphertextSpec *spec, 177 CryptoSm2CiphertextSpec_item item, Crypto_DataBlob *in); 178 179 /** 180 * @brief Encodes the SM2 ciphertext spec to ciphertext in DER format. 181 * 182 * @param spec Indicates the SM2 ciphertext spec. 183 * @param out Indicates the output data. 184 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 185 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 186 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 187 * {@link OH_Crypto_ErrCode#CRYPTO_PARAMETER_CHECK_FAILED} 17620003 - If parameter check failed. 188 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto operation failed. 189 * @since 20 190 */ 191 OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_Encode(OH_CryptoSm2CiphertextSpec *spec, Crypto_DataBlob *out); 192 193 /** 194 * @brief Destroys the SM2 ciphertext spec. 195 * 196 * @param spec Indicates the SM2 ciphertext spec. 197 * @since 20 198 */ 199 void OH_CryptoSm2CiphertextSpec_Destroy(OH_CryptoSm2CiphertextSpec *spec); 200 201 #ifdef __cplusplus 202 } 203 #endif 204 205 #endif /* CRYPTO_ASYM_CIPHER_H */ 206 /** @} */ 207