1# crypto_asym_cipher.h 2 3<!--Kit: Crypto Architecture Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @zxz--3--> 6<!--Designer: @lanming--> 7<!--Tester: @PAFT--> 8<!--Adviser: @zengyawen--> 9 10## Overview 11 12Defines APIs for encrypting and decrypting asymmetric keys. 13 14**Header file**: <CryptoArchitectureKit/crypto_asym_cipher.h> 15 16**Library**: libohcrypto.so 17 18**System capability**: SystemCapability.Security.CryptoFramework 19 20**Since**: 20 21 22**Related Module**: [CryptoAsymCipherApi](capi-cryptoasymcipherapi.md) 23 24## Summary 25 26### Structs 27 28| Name| typedef Keyword| Description| 29| -- | -- | -- | 30| [OH_CryptoAsymCipher](capi-cryptoasymcipherapi-oh-cryptoasymcipher.md) | OH_CryptoAsymCipher | Defines a struct for asymmetric encryption.| 31| [OH_CryptoSm2CiphertextSpec](capi-cryptoasymcipherapi-oh-cryptosm2ciphertextspec.md) | OH_CryptoSm2CiphertextSpec | Defines a struct for SM2 ciphertext specifications.| 32 33### Enums 34 35| Name| typedef Keyword| Description| 36| -- | -- | -- | 37| [CryptoSm2CiphertextSpec_item](#cryptosm2ciphertextspec_item) | CryptoSm2CiphertextSpec_item | Defines the type of SM2 ciphertext specification items.| 38 39### Functions 40 41| Name| Description| 42| -- | -- | 43| [OH_Crypto_ErrCode OH_CryptoAsymCipher_Create(const char *algoName, OH_CryptoAsymCipher **ctx)](#oh_cryptoasymcipher_create) | Creates an asymmetric encryption instance based on the given algorithm name.| 44| [OH_Crypto_ErrCode OH_CryptoAsymCipher_Init(OH_CryptoAsymCipher *ctx, Crypto_CipherMode mode, OH_CryptoKeyPair *key)](#oh_cryptoasymcipher_init) | Initializes asymmetric encryption.| 45| [OH_Crypto_ErrCode OH_CryptoAsymCipher_Final(OH_CryptoAsymCipher *ctx, const Crypto_DataBlob *in,Crypto_DataBlob *out)](#oh_cryptoasymcipher_final) | Finalizes asymmetric encryption.| 46| [void OH_CryptoAsymCipher_Destroy(OH_CryptoAsymCipher *ctx)](#oh_cryptoasymcipher_destroy) | Destroys an asymmetric encryption context.| 47| [OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_Create(Crypto_DataBlob *sm2Ciphertext, OH_CryptoSm2CiphertextSpec **spec)](#oh_cryptosm2ciphertextspec_create) | Creates SM2 ciphertext specifications.| 48| [OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_GetItem(OH_CryptoSm2CiphertextSpec *spec,CryptoSm2CiphertextSpec_item item, Crypto_DataBlob *out)](#oh_cryptosm2ciphertextspec_getitem) | Obtains a specified item in SM2 ciphertext specifications.| 49| [OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_SetItem(OH_CryptoSm2CiphertextSpec *spec,CryptoSm2CiphertextSpec_item item, Crypto_DataBlob *in)](#oh_cryptosm2ciphertextspec_setitem) | Sets a specified item in SM2 ciphertext specifications.| 50| [OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_Encode(OH_CryptoSm2CiphertextSpec *spec, Crypto_DataBlob *out)](#oh_cryptosm2ciphertextspec_encode) | Encodes SM2 ciphertext specifications into DER ciphertext.| 51| [void OH_CryptoSm2CiphertextSpec_Destroy(OH_CryptoSm2CiphertextSpec *spec)](#oh_cryptosm2ciphertextspec_destroy) | Destroys SM2 ciphertext specifications.| 52 53## Enum Description 54 55### CryptoSm2CiphertextSpec_item 56 57``` 58enum CryptoSm2CiphertextSpec_item 59``` 60 61**Description** 62 63Defines the type of SM2 ciphertext specification items. 64 65**Since**: 20 66 67| Enum Item| Description| 68| -- | -- | 69| CRYPTO_SM2_CIPHERTEXT_C1_X = 0 | Public key x, also called C1x.| 70| CRYPTO_SM2_CIPHERTEXT_C1_Y = 1 | Public key y, also called C1y.| 71| CRYPTO_SM2_CIPHERTEXT_C2 = 2 | Hash value, also called C2.| 72| CRYPTO_SM2_CIPHERTEXT_C3 = 3 | Ciphertext data, also called C3.| 73 74 75## Function Description 76 77### OH_CryptoAsymCipher_Create() 78 79``` 80OH_Crypto_ErrCode OH_CryptoAsymCipher_Create(const char *algoName, OH_CryptoAsymCipher **ctx) 81``` 82 83**Description** 84 85Creates an asymmetric encryption instance based on the given algorithm name. 86 87**Since**: 20 88 89 90**Parameters** 91 92| Name| Description| 93| -- | -- | 94| const char *algoName | Pointer to the algorithm used to generate an encryption instance.<br>For example, **'RSA\|PKCS1_OAEP\|SHA384\|MGF1_SHA384'**, **'SM2\|SM3'**| | | | | 95| [OH_CryptoAsymCipher](capi-cryptoasymcipherapi-oh-cryptoasymcipher.md) **ctx | Pointer to the asymmetric encryption context.| 96 97**Returns** 98 99| Type| Description| 100| -- | -- | 101| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 102 103### OH_CryptoAsymCipher_Init() 104 105``` 106OH_Crypto_ErrCode OH_CryptoAsymCipher_Init(OH_CryptoAsymCipher *ctx, Crypto_CipherMode mode, OH_CryptoKeyPair *key) 107``` 108 109**Description** 110 111Initializes asymmetric encryption. 112 113**Since**: 20 114 115 116**Parameters** 117 118| Name| Description| 119| -- | -- | 120| [OH_CryptoAsymCipher](capi-cryptoasymcipherapi-oh-cryptoasymcipher.md) *ctx | Pointer to the asymmetric encryption context.| 121| [Crypto_CipherMode](capi-crypto-common-h.md#crypto_ciphermode) mode | Cipher mode (encryption or decryption).| 122| [OH_CryptoKeyPair](capi-cryptoasymkeyapi-oh-cryptokeypair.md) *key | Pointer to the asymmetric key.| 123 124**Returns** 125 126| Type| Description| 127| -- | -- | 128| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 129 130**Reference** 131 132[OH_CryptoAsymCipher_Final](#oh_cryptoasymcipher_final) 133 134 135### OH_CryptoAsymCipher_Final() 136 137``` 138OH_Crypto_ErrCode OH_CryptoAsymCipher_Final(OH_CryptoAsymCipher *ctx, const Crypto_DataBlob *in,Crypto_DataBlob *out) 139``` 140 141**Description** 142 143Finalizes asymmetric encryption. 144 145**Since**: 20 146 147 148**Parameters** 149 150| Name| Description| 151| -- | -- | 152| [OH_CryptoAsymCipher](capi-cryptoasymcipherapi-oh-cryptoasymcipher.md) *ctx | Pointer to the asymmetric encryption context.| 153| [const Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | Pointer to the data to be encrypted or decrypted.| 154| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the encrypted or decrypted data.| 155 156**Returns** 157 158| Type| Description| 159| -- | -- | 160| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 161 162**Reference** 163 164[OH_CryptoAsymCipher_Init](#oh_cryptoasymcipher_init) 165 166 167### OH_CryptoAsymCipher_Destroy() 168 169``` 170void OH_CryptoAsymCipher_Destroy(OH_CryptoAsymCipher *ctx) 171``` 172 173**Description** 174 175Destroys an asymmetric encryption context. 176 177**Parameters** 178 179| Name| Description| 180| -- | -- | 181| [OH_CryptoAsymCipher](capi-cryptoasymcipherapi-oh-cryptoasymcipher.md) *ctx | Pointer to the asymmetric encryption context.| 182 183### OH_CryptoSm2CiphertextSpec_Create() 184 185``` 186OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_Create(Crypto_DataBlob *sm2Ciphertext, OH_CryptoSm2CiphertextSpec **spec) 187``` 188 189**Description** 190 191Creates SM2 ciphertext specifications. 192 193**Since**: 20 194 195 196**Parameters** 197 198| Name| Description| 199| -- | -- | 200| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *sm2Ciphertext | Pointer to the SM2 ciphertext in DER format. If the value is **NULL**, an empty SM2 ciphertext specification is created.| 201| [OH_CryptoSm2CiphertextSpec](capi-cryptoasymcipherapi-oh-cryptosm2ciphertextspec.md) **spec | Pointer to the output SM2 ciphertext specifications.| 202 203**Returns** 204 205| Type| Description| 206| -- | -- | 207| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 208 209### OH_CryptoSm2CiphertextSpec_GetItem() 210 211``` 212OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_GetItem(OH_CryptoSm2CiphertextSpec *spec,CryptoSm2CiphertextSpec_item item, Crypto_DataBlob *out) 213``` 214 215**Description** 216 217Obtains a specified item in SM2 ciphertext specifications. 218 219**Since**: 20 220 221 222**Parameters** 223 224| Name| Description| 225| -- | -- | 226| [OH_CryptoSm2CiphertextSpec](capi-cryptoasymcipherapi-oh-cryptosm2ciphertextspec.md) *spec | Pointer to the SM2 ciphertext specifications.| 227| [CryptoSm2CiphertextSpec_item](#cryptosm2ciphertextspec_item) item | SM2 ciphertext specification item.| 228| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the output data.| 229 230**Returns** 231 232| Type| Description| 233| -- | -- | 234| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 235 236### OH_CryptoSm2CiphertextSpec_SetItem() 237 238``` 239OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_SetItem(OH_CryptoSm2CiphertextSpec *spec,CryptoSm2CiphertextSpec_item item, Crypto_DataBlob *in) 240``` 241 242**Description** 243 244Sets a specified item in SM2 ciphertext specifications. 245 246**Since**: 20 247 248 249**Parameters** 250 251| Name| Description| 252| -- | -- | 253| [OH_CryptoSm2CiphertextSpec](capi-cryptoasymcipherapi-oh-cryptosm2ciphertextspec.md) *spec | Pointer to the SM2 ciphertext specifications.| 254| [CryptoSm2CiphertextSpec_item](#cryptosm2ciphertextspec_item) item | SM2 ciphertext specification item.| 255| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *in | Pointer to the input data.| 256 257**Returns** 258 259| Type| Description| 260| -- | -- | 261| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 262 263### OH_CryptoSm2CiphertextSpec_Encode() 264 265``` 266OH_Crypto_ErrCode OH_CryptoSm2CiphertextSpec_Encode(OH_CryptoSm2CiphertextSpec *spec, Crypto_DataBlob *out) 267``` 268 269**Description** 270 271Encodes SM2 ciphertext specifications into DER ciphertext. 272 273**Since**: 20 274 275 276**Parameters** 277 278| Name| Description| 279| -- | -- | 280| [OH_CryptoSm2CiphertextSpec](capi-cryptoasymcipherapi-oh-cryptosm2ciphertextspec.md) *spec | Pointer to the SM2 ciphertext specifications.| 281| [Crypto_DataBlob](capi-cryptocommonapi-crypto-datablob.md) *out | Pointer to the output data.| 282 283**Returns** 284 285| Type| Description| 286| -- | -- | 287| [OH_Crypto_ErrCode](capi-crypto-common-h.md#oh_crypto_errcode) | **CRYPTO_SUCCESS**: The operation is successful.<br> **CRYPTO_NOT_SUPPORTED**: The operation is not supported.<br> **CRYPTO_MEMORY_ERROR**: A memory error occurs.<br> **CRYPTO_PARAMETER_CHECK_FAILED**: The parameter check failed.<br> **CRYPTO_OPERTION_ERROR**: Failed to call an API of a third-party algorithm library.| 288 289### OH_CryptoSm2CiphertextSpec_Destroy() 290 291``` 292void OH_CryptoSm2CiphertextSpec_Destroy(OH_CryptoSm2CiphertextSpec *spec) 293``` 294 295**Description** 296 297Destroys SM2 ciphertext specifications. 298 299**Since**: 20 300 301 302**Parameters** 303 304| Name| Description| 305| -- | -- | 306| [OH_CryptoSm2CiphertextSpec](capi-cryptoasymcipherapi-oh-cryptosm2ciphertextspec.md) *spec | Pointer to the SM2 ciphertext specifications.| 307