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 CryptoAsymKeyApi 18 * @{ 19 * 20 * @brief Describe the features provided by the openHarmony asymmetric key related interface for applications. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file crypto_asym_key.h 27 * 28 * @brief Defines the AsymKey APIs. 29 * 30 * @library libohcrypto.so 31 * @kit Crypto Architecture Kit 32 * @syscap SystemCapability.Security.CryptoFramework 33 * @since 12 34 */ 35 36 #ifndef CRYPTO_ASYM_KEY_H 37 #define CRYPTO_ASYM_KEY_H 38 39 #include "crypto_common.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Define the key pair structure. 47 * 48 * @since 12 49 */ 50 typedef struct OH_CryptoKeyPair OH_CryptoKeyPair; 51 52 /** 53 * @brief Define the public Key structure. 54 * 55 * @since 12 56 */ 57 typedef struct OH_CryptoPubKey OH_CryptoPubKey; 58 59 /** 60 * @brief Define the asymmetric key parameter types. 61 * 62 * @since 12 63 */ 64 typedef enum { 65 /** Indicates the DSA prime p. */ 66 CRYPTO_DSA_P_DATABLOB = 101, 67 /** Indicates the DSA sub-prime q. */ 68 CRYPTO_DSA_Q_DATABLOB = 102, 69 /** Indicates the DSA base g. */ 70 CRYPTO_DSA_G_DATABLOB = 103, 71 /** Indicates the DSA private key. */ 72 CRYPTO_DSA_SK_DATABLOB = 104, 73 /** Indicates the DSA public key. */ 74 CRYPTO_DSA_PK_DATABLOB = 105, 75 76 /** Indicates the prime p of an elliptic curve (EC) prime finite field. */ 77 CRYPTO_ECC_FP_P_DATABLOB = 201, 78 /** Indicates the first coefficient a of this elliptic curve. */ 79 CRYPTO_ECC_A_DATABLOB = 202, 80 /** Indicates the second coefficient b of this elliptic curve. */ 81 CRYPTO_ECC_B_DATABLOB = 203, 82 /** Indicates the affine x-coordinate of base point g. */ 83 CRYPTO_ECC_G_X_DATABLOB = 204, 84 /** Indicates the affine y-coordinate of base point g. */ 85 CRYPTO_ECC_G_Y_DATABLOB = 205, 86 /** Indicates the order of the base point g. */ 87 CRYPTO_ECC_N_DATABLOB = 206, 88 /** Indicates the cofactor of the elliptic curve. */ 89 CRYPTO_ECC_H_INT = 207, 90 /** Indicates the private value of the ECC private key. */ 91 CRYPTO_ECC_SK_DATABLOB = 208, 92 /** Indicates the affine x-coordinate of a point, which is the public point of an ECC public key. */ 93 CRYPTO_ECC_PK_X_DATABLOB = 209, 94 /** Indicates the affine y-coordinate of a point, which is the public point of an ECC public key. */ 95 CRYPTO_ECC_PK_Y_DATABLOB = 210, 96 /** Indicates an elliptic curve finite field type. */ 97 CRYPTO_ECC_FIELD_TYPE_STR = 211, 98 /** Indicates the field size in bits. */ 99 CRYPTO_ECC_FIELD_SIZE_INT = 212, 100 /** Indicates the curve name according to SECG (Standards for Efficient Cryptography Group). */ 101 CRYPTO_ECC_CURVE_NAME_STR = 213, 102 103 /** Indicates the modulus n of RSA algorithm. */ 104 CRYPTO_RSA_N_DATABLOB = 301, 105 /** Indicates the private exponent d of RSA algorithm. */ 106 CRYPTO_RSA_D_DATABLOB = 302, 107 /** Indicates the public exponent e of RSA algorithm. */ 108 CRYPTO_RSA_E_DATABLOB = 303, 109 110 /** Indicates the prime p of DH algorithm. */ 111 CRYPTO_DH_P_DATABLOB = 401, 112 /** Indicates the generator g of DH algorithm. */ 113 CRYPTO_DH_G_DATABLOB = 402, 114 /** Indicates the number of bits of the private key length used in the DH algorithm. */ 115 CRYPTO_DH_L_INT = 403, 116 /** Indicates the private value of the DH private key. */ 117 CRYPTO_DH_SK_DATABLOB = 404, 118 /** Indicates the public value of the DH public key. */ 119 CRYPTO_DH_PK_DATABLOB = 405, 120 121 /** Indicates the private value of the ED25519 private key. */ 122 CRYPTO_ED25519_SK_DATABLOB = 501, 123 /** Indicates the public value of the ED25519 public key. */ 124 CRYPTO_ED25519_PK_DATABLOB = 502, 125 /** Indicates the private value of the X25519 private key. */ 126 CRYPTO_X25519_SK_DATABLOB = 601, 127 /** Indicates the public value of the X25519 public key. */ 128 CRYPTO_X25519_PK_DATABLOB = 602, 129 } CryptoAsymKey_ParamType; 130 131 /** 132 * @brief Define the encoding type. 133 * 134 * @since 12 135 */ 136 typedef enum { 137 /** PEM format */ 138 CRYPTO_PEM = 0, 139 /** DER format */ 140 CRYPTO_DER = 1, 141 } Crypto_EncodingType; 142 143 /** 144 * @brief Define the asymmetric key generator structure. 145 * 146 * @since 12 147 */ 148 typedef struct OH_CryptoAsymKeyGenerator OH_CryptoAsymKeyGenerator; 149 150 /** 151 * @brief Create an asymmetric key generator according to the given algorithm name. 152 * 153 * @param algoName Indicates the algorithm name for generating the generator. Example RSA1024|PRIMES_2. 154 * @param ctx Indicates the pointer to asymmetric key generator context. 155 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 156 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 157 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 158 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 159 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 160 * @since 12 161 */ 162 OH_Crypto_ErrCode OH_CryptoAsymKeyGenerator_Create(const char *algoName, OH_CryptoAsymKeyGenerator **ctx); 163 164 /** 165 * @brief Generate an asymmetric key(a key pair). 166 * 167 * @param ctx Indicates the asymmetric key generator context. 168 * @param keyCtx Indicates the pointer to the asyKey context. 169 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 170 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 171 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 172 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 173 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 174 * @since 12 175 */ 176 OH_Crypto_ErrCode OH_CryptoAsymKeyGenerator_Generate(OH_CryptoAsymKeyGenerator *ctx, OH_CryptoKeyPair **keyCtx); 177 178 /** 179 * @brief Convert the asymmetric key data to a key pair. 180 * 181 * @param ctx Indicates the asymmetric key generator context. 182 * @param type Indicates the encryption encoding type. 183 * @param pubKeyData Indicates the public key data. 184 * @param priKeyData Indicates the private key data. 185 * @param keyCtx Indicates the pointer to the keyPair instance. 186 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 187 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 188 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 189 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 190 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 191 * @since 12 192 */ 193 OH_Crypto_ErrCode OH_CryptoAsymKeyGenerator_Convert(OH_CryptoAsymKeyGenerator *ctx, Crypto_EncodingType type, 194 Crypto_DataBlob *pubKeyData, Crypto_DataBlob *priKeyData, OH_CryptoKeyPair **keyCtx); 195 196 /** 197 * @brief Get the algorithm name of the asymmetric key generator. 198 * 199 * @param ctx Indicates the asymmetric key generator context. 200 * @return Returns the asymmetric key algorithm name. 201 * @since 12 202 */ 203 const char *OH_CryptoAsymKeyGenerator_GetAlgoName(OH_CryptoAsymKeyGenerator *ctx); 204 205 /** 206 * @brief Destroy the asymmetric key generator. 207 * 208 * @param ctx Indicates the asymmetric key generator context. 209 * @since 12 210 */ 211 void OH_CryptoAsymKeyGenerator_Destroy(OH_CryptoAsymKeyGenerator *ctx); 212 213 /** 214 * @brief Destroy the key pair. 215 * 216 * @param keyCtx Indicates the keyPair context. 217 * @since 12 218 */ 219 void OH_CryptoKeyPair_Destroy(OH_CryptoKeyPair *keyCtx); 220 221 /** 222 * @brief Get the public key of the key pair. 223 * 224 * @param keyCtx Indicates the keyPair context. 225 * @return Return the public key context from the key pair. 226 * @since 12 227 */ 228 OH_CryptoPubKey *OH_CryptoKeyPair_GetPubKey(OH_CryptoKeyPair *keyCtx); 229 230 /** 231 * @brief Encode the public key. 232 * 233 * @param key Indicates the public key. 234 * @param type Indicates the pubkey type. 235 * @param encodingStandard Indicates the encoding standard . 236 * @param out Indicates the encoded result. 237 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 238 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 239 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 240 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 241 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 242 * @since 12 243 */ 244 OH_Crypto_ErrCode OH_CryptoPubKey_Encode(OH_CryptoPubKey *key, Crypto_EncodingType type, 245 const char *encodingStandard, Crypto_DataBlob *out); 246 247 /** 248 * @brief Get the specified param of the public key. 249 * 250 * @param key Indicates the public key. 251 * @param item Indicates the asymmetric key param type. 252 * @param value Indicates the output data. 253 * @return {@link OH_Crypto_ErrCode#CRYPTO_SUCCESS} 0 - If the operation is successful. 254 * {@link OH_Crypto_ErrCode#CRYPTO_INVALID_PARAMS} 401 - If parameter is invalid. 255 * {@link OH_Crypto_ErrCode#CRYPTO_NOT_SUPPORTED} 801 - If the operation is not supported. 256 * {@link OH_Crypto_ErrCode#CRYPTO_MEMORY_ERROR} 17620001 - If memory operation failed. 257 * {@link OH_Crypto_ErrCode#CRYPTO_OPERTION_ERROR} 17630001 - If crypto opertion failed. 258 * @since 12 259 */ 260 OH_Crypto_ErrCode OH_CryptoPubKey_GetParam(OH_CryptoPubKey *key, CryptoAsymKey_ParamType item, Crypto_DataBlob *value); 261 262 #ifdef __cplusplus 263 } 264 #endif 265 266 /** @} */ 267 #endif /* CRYPTO_ASYM_KEY_H */ 268