| cryptoCert | createX509Cert(inStream : EncodingBlob, callback : AsyncCallback<X509Cert>) : void | Parses certificate data to create an **X509Cert** instance. This API uses an asynchronous callback to return the result.|
| cryptoCert | createX509Cert(inStream : EncodingBlob, callback : AsyncCallback\<X509Cert>) : void | Parses certificate data to create an **X509Cert** instance. This API uses an asynchronous callback to return the result.|
| cryptoCert | createX509Cert(inStream : EncodingBlob) : Promise<X509Cert> | Parses certificate data to create an **X509Cert** instance. This API uses a promise to return the result. |
| cryptoCert | createX509Cert(inStream : EncodingBlob) : Promise\<X509Cert> | Parses certificate data to create an **X509Cert** instance. This API uses a promise to return the result. |
| X509Cert | verify(key : cryptoFramework.PubKey, callback : AsyncCallback<void>) : void | Verifies the certificate signature. This API uses an asynchronous callback to return the result. |
| X509Cert | verify(key : cryptoFramework.PubKey, callback : AsyncCallback\<void>) : void | Verifies the certificate signature. This API uses an asynchronous callback to return the result. |
| X509Cert | verify(key : cryptoFramework.PubKey) : Promise<void> | Verifies the certificate signature. This API uses a promise to return the result. |
| X509Cert | verify(key : cryptoFramework.PubKey) : Promise\<void> | Verifies the certificate signature. This API uses a promise to return the result. |
| X509Cert | getEncoded(callback : AsyncCallback<EncodingBlob>) : void | Obtains serialized certificate data. This API uses an asynchronous callback to return the result. |
| X509Cert | getEncoded(callback : AsyncCallback\<EncodingBlob>) : void | Obtains serialized certificate data. This API uses an asynchronous callback to return the result. |
| X509Cert | getEncoded() : Promise<EncodingBlob> | Obtains serialized certificate data. This API uses a promise to return the result. |
| X509Cert | getEncoded() : Promise\<EncodingBlob> | Obtains serialized certificate data. This API uses a promise to return the result. |
| X509Cert | getPublicKey(callback : AsyncCallback<cryptoFramework.PubKey>) : void | Obtains the certificate public key. This API uses an asynchronous callback to return the result. |
| X509Cert | getPublicKey() : cryptoFramework.PubKey | Obtains the certificate public key. |
| X509Cert | getPublicKey() : Promise<cryptoFramework.PubKey> | Obtains the certificate public key. This API uses a promise to return the result. |
| X509Cert | checkValidityWithDate(date: string, callback : AsyncCallback<void>) : void | Verifies the certificate validity period. This API uses an asynchronous callback to return the result. |
| X509Cert | checkValidityWithDate(date: string) : Promise<void> | Verifies the certificate validity period. This API uses a promise to return the result. |
| X509Cert | getVersion() : number | Obtains the certificate version. |
| X509Cert | getVersion() : number | Obtains the certificate version. |
| X509Cert | getSerialNumber() : number | Obtains the certificate serial number. |
| X509Cert | getSerialNumber() : number | Obtains the certificate serial number. |
| cryptoCert | createX509Crl(inStream : EncodingBlob, callback : AsyncCallback<X509Crl>) : void | Parses the X.509 CRL data to create an **X509Crl** instance. This API uses an asynchronous callback to return the result.|
| cryptoCert | createX509Crl(inStream : EncodingBlob, callback : AsyncCallback\<X509Crl>) : void | Parses the X.509 CRL data to create an **X509Crl** instance. This API uses an asynchronous callback to return the result.|
| cryptoCert | createX509Crl(inStream : EncodingBlob) : Promise<X509Crl> | Parses the X.509 CRL data to create an **X509Crl** instance. This API uses a promise to return the result. |
| cryptoCert | createX509Crl(inStream : EncodingBlob) : Promise\<X509Crl> | Parses the X.509 CRL data to create an **X509Crl** instance. This API uses a promise to return the result. |
| X509Crl | isRevoked(cert : X509Cert, callback : AsyncCallback<boolean>) : void | Checks whether the certificate is revoked. This API uses an asynchronous callback to return the result. |
| X509Crl | isRevoked(cert : X509Cert) : boolean | Checks whether the certificate is revoked. |
| X509Crl | isRevoked(cert : X509Cert) : Promise<boolean> | Checks whether the certificate is revoked. This API uses a promise to return the result. |
| X509Crl | getEncoded(callback : AsyncCallback\<EncodingBlob>) : void | Obtains the serialized CRL data. This API uses an asynchronous callback to return the result. |
| X509Crl | getEncoded(callback : AsyncCallback<EncodingBlob>) : void | Obtains the serialized CRL data. This API uses an asynchronous callback to return the result. |
| X509Crl | getEncoded() : Promise\<EncodingBlob> | Obtains the serialized CRL data. This API uses a promise to return the result. |
| X509Crl | getEncoded() : Promise<EncodingBlob> | Obtains the serialized CRL data. This API uses a promise to return the result. |
| X509Crl | verify(key : cryptoFramework.PubKey, callback : AsyncCallback\<void>) : void | Verifies the CRL signature. This API uses an asynchronous callback to return the result. |
| X509Crl | verify(key : cryptoFramework.PubKey, callback : AsyncCallback<void>) : void | Verifies the CRL signature. This API uses an asynchronous callback to return the result. |
| X509Crl | verify(key : cryptoFramework.PubKey) : Promise\<void> | Verifies the CRL signature. This API uses a promise to return the result. |
| X509Crl | verify(key : cryptoFramework.PubKey) : Promise<void> | Verifies the CRL signature. This API uses a promise to return the result. |
| X509Crl | getVersion() : number | Obtains the CRL version. |
| X509Crl | getVersion() : number | Obtains the CRL version. |
| X509Crl | getLastUpdate() : string | Obtains the date when the CRL was last updated. |
| X509Crl | getLastUpdate() : string | Obtains the date when the CRL was last updated. |
| X509Crl | getNextUpdate() : string | Obtains the next update date of the CRL. |
| X509Crl | getNextUpdate() : string | Obtains the next update date of the CRL. |
| X509Crl | getRevokedCert(serialNumber : number, callback : AsyncCallback<X509CrlEntry>) : void | Obtains the revoked certificate in the CRL based on the specified serial number. This API uses an asynchronous callback to return the result. |
| X509Crl | getRevokedCert(serialNumber : number) : X509CrlEntry | Obtains the revoked certificate in the CRL based on the serial number. |
| X509Crl | getRevokedCert(serialNumber : number) : Promise<X509CrlEntry> | Obtains the revoked certificate in the CRL based on the specified serial number. This API uses a promise to return the result. |
| X509Crl | getRevokedCertWithCert(cert : X509Cert) : X509CrlEntry | Obtains the revoked certificate in the CRL based on the X.509 certificate. |
| X509Crl | getRevokedCertWithCert(cert : X509Cert, callback : AsyncCallback<X509CrlEntry>) : void | Obtains the specified X.509 certificate from the CRL. This API uses an asynchronous callback to return the result. |
| X509Crl | getRevokedCerts(callback : AsyncCallback\<Array\<X509CrlEntry>>) : void | Obtains all revoked certificates in the CRL. This API uses an asynchronous callback to return the result. |
| X509Crl | getRevokedCertWithCert(cert : X509Cert) : Promise<X509CrlEntry> | Obtains the specified X.509 certificate from the CRL. This API uses a promise to return the result. |
| X509Crl | getRevokedCerts() : Promise\<Array\<X509CrlEntry>> | Obtains all revoked certificates in the CRL. This API uses a promise to return the result. |
| X509Crl | getRevokedCerts(callback : AsyncCallback<Array<X509CrlEntry>>) : void | Obtains all revoked certificates in the CRL. This API uses an asynchronous callback to return the result. |
| X509Crl | getTbsInfo() : DataBlob | Obtains **tbsCertList** of the CRL. |
| X509Crl | getRevokedCerts() : Promise<Array<X509CrlEntry>> | Obtains all revoked certificates in the CRL. This API uses a promise to return the result. |
| X509Crl | getTbsInfo(callback : AsyncCallback<DataBlob>) : void | Obtains the tbsCertList of the CRL. This API uses an asynchronous callback to return the result. |
| X509Crl | getTbsInfo() : Promise<DataBlob> | Obtains the tbsCertList of the CRL. This API uses a promise to return the result. |
| CertChainValidator | validate(certChain : CertChainData, callback : AsyncCallback<void>) : void | Verifies the certificate chain. This API uses an asynchronous callback to return the result. |
| CertChainValidator | validate(certChain : CertChainData, callback : AsyncCallback\<void>) : void | Verifies the certificate chain. This API uses an asynchronous callback to return the result. |
| CertChainValidator | validate(certChain : CertChainData) : Promise<void> | Verifies the certificate chain. This API uses a promise to return the result. |
| CertChainValidator | validate(certChain : CertChainData) : Promise\<void> | Verifies the certificate chain. This API uses a promise to return the result. |
| X509CrlEntry | getEncoded(callback : AsyncCallback<EncodingBlob>) : void; | Obtains the serialized data of the revoked certificate. This API uses an asynchronous callback to return the result.|
| X509CrlEntry | getEncoded(callback : AsyncCallback\<EncodingBlob>) : void; | Obtains the serialized data of the revoked certificate. This API uses an asynchronous callback to return the result.|
| X509CrlEntry | getEncoded() : Promise<EncodingBlob>; | Obtains the serialized data of the revoked certificate. This API uses a promise to return the result. |
| X509CrlEntry | getEncoded() : Promise\<EncodingBlob>; | Obtains the serialized data of the revoked certificate. This API uses a promise to return the result. |
| X509CrlEntry | getSerialNumber() : number; | Obtains the serial number of the revoked certificate. |
| X509CrlEntry | getSerialNumber() : number; | Obtains the serial number of the revoked certificate. |
| X509CrlEntry | getCertIssuer(callback : AsyncCallback<DataBlob>) : void; | Obtains the issuer of the revoked certificate. This API uses an asynchronous callback to return the result. |
| X509CrlEntry | getCertIssuer() : DataBlob; | Obtains the issuer of the revoked certificate. |
| X509CrlEntry | getCertIssuer() : Promise<DataBlob>; | Obtains the issuer of the revoked certificate. This API uses a promise to return the result. |
| X509CrlEntry | getRevocationDate() : string; | Obtains the revocation date of the revoked certificate. |
| X509CrlEntry | getRevocationDate(callback : AsyncCallback<string>) : void; | Obtains the revocation date of the certificate. This API uses an asynchronous callback to return the result. |
| X509CrlEntry | getRevocationDate() : Promise<string>; | Obtains the issuer of the revoked certificate. This API uses a promise to return the result. |
**How to Develop**
**How to Develop**
...
@@ -456,39 +433,32 @@ function crlEntrySample() {
...
@@ -456,39 +433,32 @@ function crlEntrySample() {
// Obtain a revoked certificate instance. In this example, the instance is obtained by using getRevokedCert().
// Obtain a revoked certificate instance. In this example, the instance is obtained by using getRevokedCert().
@@ -32,10 +32,10 @@ The table below describes the APIs used in this guide.
...
@@ -32,10 +32,10 @@ The table below describes the APIs used in this guide.
|AsyKeyGenerator|generateKeyPair() : Promise\<KeyPair>|Generates an asymmetric key pair randomly. This API uses a promise to return the result.|
|AsyKeyGenerator|generateKeyPair() : Promise\<KeyPair>|Generates an asymmetric key pair randomly. This API uses a promise to return the result.|
|SymKeyGenerator|generateSymKey(callback : AsyncCallback\<SymKey>) : void|Generates a symmetric key randomly. This API uses an asynchronous callback to return the result.|
|SymKeyGenerator|generateSymKey(callback : AsyncCallback\<SymKey>) : void|Generates a symmetric key randomly. This API uses an asynchronous callback to return the result.|
|SymKeyGenerator|generateSymKey() : Promise\<SymKey>|Generates a symmetric key randomly. This API uses a promise to return the result.|
|SymKeyGenerator|generateSymKey() : Promise\<SymKey>|Generates a symmetric key randomly. This API uses a promise to return the result.|
| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\<KeyPair>) : void | Converts binary data into a key pair. This API uses an asynchronous callback to return the result.<br>(**pubKey** or **priKey** can be **null**. That is, you can pass in only **pubKey** or **priKey**. As a result, the return **KeyPair** instance contains only the public or private key.)|
| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\<KeyPair>) : void | Converts the binary data into a key pair. This API uses an asynchronous callback to return the result.<br>(**pubKey** or **priKey** can be **null**. That is, you can pass in only **pubKey** or **priKey**. As a result, the return **KeyPair** instance contains only the public or private key.) |
| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair> | Converts the binary data into a key pair. This API uses a promise to return the result.<br>(**pubKey** or **priKey** can be **null**. That is, you can pass in only **pubKey** or **priKey**. As a result, the returned **KeyPair** instance contains only the public or private key.)|
| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair> | Converts the binary data into a key pair. This API uses a promise to return the result.<br>(**pubKey** or **priKey** can be **null**. That is, you can pass in only **pubKey** or **priKey**. As a result, the returned **KeyPair** instance contains only the public or private key.)|
| SymKeyGenerator | convertKey(key : DataBlob, callback : AsyncCallback\<SymKey>) : void| Converts binary data into a symmetric key. This API uses an asynchronous callback to return the result.|
| SymKeyGenerator | convertKey(key : DataBlob, callback : AsyncCallback\<SymKey>) : void| Converts the binary data into a symmetric key. This API uses an asynchronous callback to return the result. |
| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair>| Converts binary data into a symmetric key. This API uses a promise to return the result.|
| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair>| Converts the binary data into a symmetric key. This API uses a promise to return the result. |
| Key | getEncoded() : DataBlob; | Obtains the binary data of a key. (The child class instances of **Key** include **SymKey**, **PubKey**, and **PriKey**.)|
| Key | getEncoded() : DataBlob; | Obtains the binary data of a key. (The child class instances of **Key** include **SymKey**, **PubKey**, and **PriKey**.)|
**How to Develop**
**How to Develop**
...
@@ -121,11 +121,11 @@ function convertAsyKey() {
...
@@ -121,11 +121,11 @@ function convertAsyKey() {
}
}
```
```
**NOTE**
> **NOTE**
>
The public key returned by **convertKey()** must be in the DER format complying with X.509 specifications, and the private key must be in the DER format complying with PKCS #8 specifications.
> The public key returned by **convertKey()** must be in the DER format complying with X.509 specifications, and the private key must be in the DER format complying with PKCS #8 specifications.
Example 4: Generate an asymmetric key pair from the binary ECC key data.
Example 4: Generate an asymmetric key pair from the binary ECC key data.
1. Obtain the ECC binary key data and encapsulate it into a **DataBlob** instance.
1. Obtain the ECC binary key data and encapsulate it into a **DataBlob** instance.
2. Call **convertKey()** to convert the key binary data (data of the private or public key, or both) passed in to a **KeyPair** instance.
2. Call **convertKey()** to convert the key binary data (data of the private or public key, or both) passed in to a **KeyPair** instance.
...
@@ -492,17 +492,9 @@ function test3DesEcb() {
...
@@ -492,17 +492,9 @@ function test3DesEcb() {
Example 2: Encrypt and decrypt data using an asymmetric key pair.
Example 2: Encrypt and decrypt data using an asymmetric key pair.
1. Generate an RSA key pair.
1. Generate an RSA key pair.<br> Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an RSA asymmetric key pair.
2. Create a **Cipher** instance.<br> Call **createCipher()** to create a **Cipher** instance, and set the key and encryption/decryption mode.
Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an RSA asymmetric key pair.
3. Perform encryption and decryption operations.<br> Call **doFinal()** provided by the **Cipher** instance to encrypt data or decrypt data.
2. Create a **Cipher** instance.
Call **createCipher()** to create a **Cipher** instance, and set the key and encryption/decryption mode.
3. Perform encryption and decryption operations.
Call **doFinal()** provided by the **Cipher** instance to encrypt data or decrypt data.
@@ -548,19 +540,19 @@ function encryptMessageCallback() {
...
@@ -548,19 +540,19 @@ function encryptMessageCallback() {
}
}
```
```
**NOTE**
> **NOTE**
>
- In RSA encryption and decryption, **init()** cannot be repeatedly called to initialize the **Cipher** instance. You must create a **Cipher** instance for each of encryption and decryption.
> - In RSA encryption and decryption, **init()** cannot be repeatedly called to initialize the **Cipher** instance. You must create a **Cipher** instance for each of encryption and decryption.
- The RSA encryption has a limit on the length of the plaintext to be encrypted. For details, see "Basic Concepts" in [Crypto Framework Overview](cryptoFramework-overview.md).
> - The RSA encryption has a limit on the length of the plaintext to be encrypted. For details, see "Basic Concepts" in [Crypto Framework Overview](cryptoFramework-overview.md).
- In RSA decryption, the length of the ciphertext to be decrypted each time is the number of bits of the RSA key divided by 8.
> - In RSA decryption, the length of the ciphertext to be decrypted each time is the number of bits of the RSA key divided by 8.
## Signing Data and Verifying Signatures
## Signing Data and Verifying Signatures
**When to Use**
**When to Use**
A digital signature can be used to verify the authenticity of a message. Typical signing and signature verification operations involve the following:
A digital signature can be used to verify the authenticity of a message. Typical signing and signature verification operations involve the following:
The cryptographic (crypto for shot) framework shields the implementation differences of third-party cryptographic algorithm libraries and implements encryption and decryption, signing and signature verification, message authentication code (MAC), hash, and secure random number. You can use the APIs provided by this framework to implement cipher development quickly.
The cryptographic (crypto for shot) framework shields the implementation differences of third-party cryptographic algorithm libraries and implements encryption and decryption, signing and signature verification, message authentication code (MAC), hashes, and secure random numbers. You can use the APIs provided by this framework to implement cipher development quickly.
## Working Principles
## Working Principles
The crypto framework provides components in the following layers:
The crypto framework provides components in the following layers:
- Framework layer: flexibly loads the plugins in the plugin layer to adapt to third-party algorithm libraries and shields the implement differences between the third-party algorithm libraries.
- Framework layer: flexibly loads the plugins in the plugin layer to adapt to third-party algorithm libraries and shields the implementation differences between these libraries.
## Basic Concepts
## Basic Concepts
### Symmetric Key
**Symmetric Key**
A symmetric key is a key used both to encrypt and decrypt data. In symmetric encryption, the sender converts information in plaintext into ciphertext using a key and certain algorithm for security purposes. The receiver converts the ciphertext into plaintext using the same key and algorithm.
A symmetric key is a key used both to encrypt and decrypt data. In symmetric encryption, the sender converts information in plaintext into ciphertext using a key and certain algorithm for security purposes. The receiver converts the ciphertext into plaintext using the same key and algorithm.
...
@@ -19,7 +19,7 @@ A symmetric key is a key used both to encrypt and decrypt data. In symmetric enc
...
@@ -19,7 +19,7 @@ A symmetric key is a key used both to encrypt and decrypt data. In symmetric enc
Triple Data Encryption Standard (3DES), also called 3DESede or Triple DES, applies the DES cipher three times to each data block. It uses three 64-bit keys to encrypt a data block three times. Compared with DES, 3DES provides higher security due to longer key length, but its processing speed is lower. The AES is faster and more secure than 3DES.
Triple Data Encryption Standard (3DES), also called 3DESede or Triple DES, applies the DES cipher three times to each data block. It uses three 64-bit keys to encrypt a data block three times. Compared with DES, 3DES provides higher security due to longer key length, but its processing speed is lower. The AES is faster and more secure than 3DES.
### Asymmetric Key
**Asymmetric Key**
In the asymmetric cryptography, a private and public key pair is required. The private key is used to encrypt the plaintext, and the public key is used to decrypt the ciphertext. The public key is public and open to anyone in the system, while the private key is private. For signing and signature verification, the private key is used to sign the plaintext, and the public key is used to verify the signature data.
In the asymmetric cryptography, a private and public key pair is required. The private key is used to encrypt the plaintext, and the public key is used to decrypt the ciphertext. The public key is public and open to anyone in the system, while the private key is private. For signing and signature verification, the private key is used to sign the plaintext, and the public key is used to verify the signature data.
...
@@ -27,7 +27,7 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -27,7 +27,7 @@ In the asymmetric cryptography, a private and public key pair is required. The p
The security of RSA relies on the factoring problem, that is, the difficulty of factoring the product of two large prime numbers. The keys for the RSA algorithm are generated as follows:
The security of RSA relies on the factoring problem, that is, the difficulty of factoring the product of two large prime numbers. The keys for the RSA algorithm are generated as follows:
1. Generate two large prime numbers **p** and **q**.
1. Generate two large prime numbers **p** and **q**.
2. Compute **n** = **p** x **q**.
2. Compute **n** = **p** x **q**.
...
@@ -41,44 +41,37 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -41,44 +41,37 @@ In the asymmetric cryptography, a private and public key pair is required. The p
The public key consists of the modulus **n** and the public exponent **e**. The private key consists of **n** and the private exponent **d**.
The public key consists of the modulus **n** and the public exponent **e**. The private key consists of **n** and the private exponent **d**.
In addition to the default RSA key generation from two primes, the crypto framework provides key generation from multiple primes. You can set the **primes** parameter (PRIMES_2, PRIMES_3, PRIMES_4, PRIMES_5) to specify the number of primes during key generation. The keys generated from multiple primes help reduce the computation workload in decryption and signing (Chinese remainder theorem). However, such keys are weak. The algorithm library defines specifications based on the rules for using OpenSSL prime numbers. For details, see **Constraints**.
In addition to the default RSA key generation from two primes, the crypto framework provides key generation from multiple primes. You can set the **primes** parameter (PRIMES_2, PRIMES_3, PRIMES_4, PRIMES_5) to specify the number of primes during key generation. The keys generated from multiple primes help reduce the computation workload in decryption and signing (Chinese remainder theorem). However, such keys are weak. The algorithm library defines specifications based on the rules for using OpenSSL prime numbers. For details, see [**Constraints**](#constraints).
- ECC key
- ECC key
Elliptic-Curve Cryptography (ECC) is a public-key encryption based on the algebraic structure of elliptic curve over finite fields. The crypto framework provides a variety of ECC key generation capabilities.
Elliptic-Curve Cryptography (ECC) is a public-key encryption based on the algebraic structure of elliptic curve over finite fields. The crypto framework provides a variety of ECC key generation capabilities.
### Encryption and Decryption
**Encryption and Decryption**
- Symmetric AES encryption and decryption
- Symmetric AES encryption and decryption
The algorithm library provides the following cipher modes of operation for AES: ECB, CBC, OFB, CFB, CTR, GCM, and CCM.
The algorithm library provides the following cipher modes of operation for AES: ECB, CBC, OFB, CFB, CTR, GCM, and CCM. AES is a block cipher, with a fixed block size of 128 bits. In actual applications, the last block of plaintext may be less than 128 bits and needs to be padded. The padding options are as follows:
AES is a block cipher, with a fixed block size of 128 bits. In actual applications, the last block of plaintext may be less than 128 bits and needs to be padded. The padding options are as follows:
-**NoPadding**: no padding.
-**NoPadding**: no padding.
-**PKCS5**: pads a block cipher with a block size of 8 bytes.
-**PKCS5**: pads a block cipher with a block size of 8 bytes.
-**PKCS7**: The PKCS #7 padding scheme is the same as that of PKCS #5 padding except that PKCS #5 padding is defined for 8-byte block sizes, while PKCS #5 padding works for any block size from 1 to 255 bytes.
-**PKCS7**: The PKCS #7 padding scheme is the same as that of PKCS #5 padding except that PKCS #5 padding is defined for 8-byte block sizes, while PKCS #5 padding works for any block size from 1 to 255 bytes.
> **NOTE**
>
> In ECB and CBC modes, the plaintext length is not an integer multiple of 128 bits and must be padded.
- Symmetric 3DES encryption and decryption
3DES encryption and decryption apply the DES cipher three times to each data block obtain the ciphertext or plaintext.
The algorithm library provides the following cipher modes of operation for 3DES encryption and decryption: ECB, CBC, OFB, and CFB.
> **NOTE**
>
> In ECB and CBC, the plaintext must be padded if its length is not an integer multiple of 128 bits. <br>Since the plaintext is padded to the block size, the PKCS #5 and PKCS #7 used in the algorithm library use the block size as the padding length. That is, data is padded to 16 bytes in AES encryption.
- Symmetric 3DES encryption and decryption
DES is a block cipher, with a fixed block size of 64 bits. In actual applications, the last block of plaintext may be less than 64 bits and needs to be padded. The padding options are as follows:
3DES encryption and decryption apply the DES cipher three times to each data block to obtain the ciphertext or plaintext.
The algorithm library provides the following cipher modes of operation for 3DES encryption and decryption: ECB, CBC, OFB, and CFB. DES is a block cipher, with a fixed block size of 64 bits. In actual applications, the last block of plaintext may be less than 64 bits and needs to be padded. The padding options are as follows:
-**NoPadding**: no padding.
-**NoPadding**: no padding.
-**PKCS5**: pads a block cipher with a block size of 8 bytes.
-**PKCS5**: pads a block cipher with a block size of 8 bytes.
-**PKCS7**: The PKCS #7 padding scheme is the same as that of PKCS #5 padding except that PKCS #5 padding is defined for 8-byte block sizes, while PKCS #5 padding works for any block size from 1 to 255 bytes.
-**PKCS7**: The PKCS #7 padding scheme is the same as that of PKCS #5 padding except that PKCS #5 padding is defined for 8-byte block sizes, while PKCS #5 padding works for any block size from 1 to 255 bytes.
> **NOTE**
> **NOTE**
>
>
> In ECB and CBC, the plaintext length is not an integer multiple of 64 bits and must be padded.
> In ECB and CBC, the plaintext must be padded if its length is not an integer multiple of 64 bits. <br>Since the plaintext is padded to the block size, the PKCS #5 and PKCS #7 used in the algorithm library use the block size as the padding length. That is, data is padded to 8 bytes in 3DES encryption.
- Asymmetric RSA encryption and decryption
- Asymmetric RSA encryption and decryption
...
@@ -90,21 +83,17 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -90,21 +83,17 @@ In the asymmetric cryptography, a private and public key pair is required. The p
Plaintext = Ciphertext ^ **d** mod **n**
Plaintext = Ciphertext ^ **d** mod **n**
The algorithm library provides the following modes of operation for RSA encryption and decryption: **PKCS1**, **PKCS1_ OAEP**, and **NoPadding**.
The algorithm library provides the following modes of operation for RSA encryption and decryption: **PKCS1**, **PKCS1_ OAEP**, and **NoPadding**. RSA is a block cipher, with fixed-length blocks. In actual applications, diverse padding modes are used. The padding options are as follows:
RSA is a block cipher, with fixed-length blocks. In actual applications, diverse padding modes are used. The padding options are as follows:
-**NoPadding**: No padding is required. The length of the input or output data must be the same as that of the RSA key modulus.
-**NoPadding**: No padding is required. The length of the input or output data must be the same as that of the RSA key modulus.
-**PKCS1**: PKCS #1 v1.5 is the default padding mode for RSA encryption and decryption. The length of the input data must be less than or equal to the RSA key modulus minus 11, and the length of the output data must be the same as that of the RSA key modulus.
-**PKCS1**: PKCS #1 v1.5 is the default padding mode for RSA encryption and decryption. The length of the input data must be less than or equal to the RSA key modulus minus 11, and the length of the output data must be the same as that of the RSA key modulus.
-**PKCS1_OAEP**: The RSA_PKCS1_OAEP_PADDING is a new padding mode provided by PKCS #1. In this mode, two digests (**md** and **mgf1_md**) must be set. The length of the input data must be less than RSA key modulus length minus the **md** length, **mgf1_md** length, and two. The length of the output data must be the same as that of the RSA key modulus.
-**PKCS1_OAEP**: The RSA_PKCS1_OAEP_PADDING is a new padding mode provided by PKCS #1. In this mode, two digests (**md** and **mgf1_md**) must be set. The length of the input data must be less than RSA key modulus length minus **md** length, **mgf1_md** length, and two. The length of the output data must be the same as that of the RSA key modulus.
> **NOTE**
>
**NOTE**
> Length of the RSA key modulus = (Number of RSA bits + 7)/8
Length of the RSA key modulus = (Number of RSA bits + 7)/8
### Signing and Signature Verification
**Signing and Signature Verification**
- RSA signing and signature verification
- RSA signing and signature verification
...
@@ -116,41 +105,41 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -116,41 +105,41 @@ In the asymmetric cryptography, a private and public key pair is required. The p
Message = Signature ^ **d** mod **n**
Message = Signature ^ **d** mod **n**
The sender sends the message and the signature signed by the private key. The receiver decrypts the signature using the public key to verify the signature. Generally, the message sent is longer than the RSA key modulus. Therefore, the crypto framework provides two padding modes to extract the hash value of the message digest and then sign the message. The crypto framework provides the following padding modes for signing and signature verification:
The sender sends the message and the signature signed by the private key. The receiver decrypts the signature using the public key to verify the signature. Generally, the message sent is longer than the RSA key modulus. Therefore, the crypto framework provides two padding modes to extract the hash value of the message digest before signing the message. The crypto framework provides the following padding modes for signing and signature verification:
-**PKCS1**: PKCS #1 v1.5 is the default padding mode for RSA encryption and decryption. When this mode is used, the digest (**md**) must be set.
-**PKCS1**: PKCS #1 v1.5 is the default padding mode for RSA encryption and decryption. When this mode is used, the digest (**md**) must be set.
-**PSS**: The PSS mode is a padding algorithm based on the RSA algorithm. When it is used, the digest (**md**) and mask function (**mgf1_md**) are required.
-**PSS**: The PSS mode is a padding algorithm based on the RSA algorithm. When it is used, the digest (**md**) and mask function (**mgf1_md**) are required.
- ECDSA
- ECDSA
The Elliptic Curve Digital Signature Algorithm (ECDSA) is a Digital Signature Algorithm (DSA) that uses the ECC. Compared with the ordinary Discrete Logarithm Problem (DLP) and Integer Factorization Problem (IFP), the unit bit strength of ECC is higher than that of other public-key cryptographic systems. The crypto framework provides the ECDSA that combines multiple elliptic curve and digest algorithms.
The Elliptic Curve Digital Signature Algorithm (ECDSA) is a Digital Signature Algorithm (DSA) that uses the ECC. Compared with the ordinary Discrete Logarithm Problem (DLP) and Integer Factorization Problem (IFP), the ECC provides a higher unit bit strength than other public-key cryptographic systems. The crypto framework provides the ECDSA that combines multiple elliptic curve and digest algorithms.
### Key Agreement
**Key Agreement**
**ECDH**
-**ECDH**
Elliptic Curve Diffie-Hellman (ECDH) allows two parties to establish a shared secret over an insecure channel. The crypto framework provides a variety of ECDH capabilities based on the open-source algorithm library.
Elliptic Curve Diffie-Hellman (ECDH) allows two parties to establish a shared secret over an insecure channel. The crypto framework provides a variety of ECDH capabilities based on the open-source algorithm library.
### Digest
**Digest**
The message digest algorithm allows a fixed-length digest to be generated from data of arbitrary size by using the hash algorithm. The message digest algorithm is used for sensitive information encryption because it is infeasible to invert or reverse the computation. The MD algorithm is also referred to as a hash algorithm or a one-way hash algorithm.
The message digest algorithm allows a fixed-length digest to be generated from data of arbitrary size by using the hash algorithm. It is used for sensitive information encryption because it is infeasible to invert or reverse the computation. The MD algorithm is also referred to as a hash algorithm or a one-way hash algorithm.
When the same digest algorithm is used, the generated digest (hash value) has the following features:
When the same digest algorithm is used, the generated digest (hash value) has the following features:
- The same message always results in the same hash value.
- The same message always results in the same hash value.
- The digest generated is of the fixed length no matter the length of messages. (The digest length is determined by the algorithm used).
- The digest generated is of the fixed length no matter the length of messages. (The digest length is determined by the algorithm used).
- It is almost impossible to find two different messages with the same hash value (the probability still exists, depending on the length of the digest).
- It is almost impossible to find two different messages with the same hash value. (The probability still exists, depending on the length of the digest.)
There are three types of message digest algorithms: MD, SHA, and MAC. For details, see section "**HMAC**".
There are three types of message digest algorithms: MD, SHA, and MAC. For details, see section **HMAC**.
MD algorithms include MD2, MD4, and MD5.
MD algorithms include MD2, MD4, and MD5.
Major SHA algorithms include SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512.
Major SHA algorithms include SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512.
### HMAC
**HMAC**
Hash-based Message Authentication Code (HMAC) is a key-based message authentication code algorithm. HMAC provides authentication using a shared secret instead of using a digital signature. The MAC generated can be used to verify both the integrity and authenticity of the message. The length of the MAC generated by HMAC is fixed.
Hash-based Message Authentication Code (HMAC) is a key-based message authentication code algorithm. HMAC provides authentication using a shared secret instead of using a digital signature. The MAC generated can be used to verify the integrity and authenticity of the message. The length of the MAC generated by HMAC is fixed. Compared with MAC, HMAC introduces the shared secret, which ensures data correctness.
### Random Number
**Random Number**
Random numbers are mainly used to generate temporary session keys or keys in asymmetric encryption. Random numbers can be generated by a hardware random number generator or software-based pseudo-random number generator. In encryption and decryption, a secure random number generator must feature randomness, repeatability, and unpredictability. The random numbers generated by the Cryptography Secure Random Number Generator (CSPRNG) meet the requirements of cryptography security pseudo-randomness.
Random numbers are mainly used to generate temporary session keys or keys in asymmetric encryption. They are generated by a hardware random number generator or software-based pseudo-random number generator. In encryption and decryption, a secure random number generator must feature randomness, unrepeatability, and unpredictability. The random numbers generated by the Cryptography Secure Random Number Generator (CSPRNG) meet the requirements of cryptography security pseudo-randomness.
- Internal state
- Internal state
...
@@ -163,7 +152,7 @@ Random numbers are mainly used to generate temporary session keys or keys in asy
...
@@ -163,7 +152,7 @@ Random numbers are mainly used to generate temporary session keys or keys in asy
## Constraints
## Constraints
-The crypto framework does not support concurrent operations of multiple threads.
The crypto framework does not support concurrent operations of multiple threads.
### Key Generation Specifications
### Key Generation Specifications
...
@@ -171,19 +160,24 @@ Random numbers are mainly used to generate temporary session keys or keys in asy
...
@@ -171,19 +160,24 @@ Random numbers are mainly used to generate temporary session keys or keys in asy
The following parameters are supported:
The following parameters are supported:
|Symmetric Key Algorithm|Key Length|String for Generating a Key|
> **String Parameter** is a combination of **Symmetric Key Algorithm** and **Key Length**. It specifies the key specifications when a symmetric key generator is created.
**Asymmetric Key Generation Specifications**
**Asymmetric Key Generation Specifications**
-**RSA key generation**
-**RSA key generation**
The following parameters are supported:
The following parameters are supported:
|Asymmetric Key Algorithm|Key Length|Number of Primes|String for Generating a Key|
|Asymmetric Key Algorithm|Key Length (Bit)|Number of Primes|String Parameter|
|---|---|---|---|
|---|---|---|---|
|RSA|512|2|RSA512\|PRIMES_2|
|RSA|512|2|RSA512\|PRIMES_2|
|RSA|768|2|RSA768\|PRIMES_2|
|RSA|768|2|RSA768\|PRIMES_2|
...
@@ -203,7 +197,7 @@ The following parameters are supported:
...
@@ -203,7 +197,7 @@ The following parameters are supported:
> **NOTE**
> **NOTE**
>
>
> When the RSA asymmetric key is generated, the default number of primes is 2 and the **PRIMES_2** parameter can be omitted.
> When an RSA asymmetric key is generated, the default prime number is 2, and **PRIMES_2** is optional.
-**ECC key generation**
-**ECC key generation**
...
@@ -214,7 +208,7 @@ The following parameters are supported:
...
@@ -214,7 +208,7 @@ The following parameters are supported:
|ECC|ECC224|
|ECC|ECC224|
|ECC|ECC256|
|ECC|ECC256|
|ECC|ECC384|
|ECC|ECC384|
|ECC|ECC512|
|ECC|ECC521|
### Encryption and Decryption Specifications
### Encryption and Decryption Specifications
...
@@ -222,7 +216,7 @@ The following parameters are supported:
...
@@ -222,7 +216,7 @@ The following parameters are supported:
The following symmetric encryption algorithms are supported:
The following symmetric encryption algorithms are supported:
> - The options included in the square brackets ([]) are mutually exclusive.
> The options included in the square brackets ([]) are mutually exclusive.
> - **String Parameter** is a combination of **Algorithm** (including the key length), **Block Cipher Mode**, and padding mode. It specifies the symmetric encryption/decryption algorithm specifications when a symmetric encryption/decryption instance is created.
**Asymmetric RSA Encryption and Decryption**
**Asymmetric RSA Encryption and Decryption**
The following padding modes are involved in RSA encryption and decryption: **NoPadding**, **PKCS1**, and **PKCS1_OAEP**.
The crypto framework provides three padding modes for RSA encryption/decryption: **NoPadding**, **PKCS1**, and **PKCS1_OAEP**.
-When **NoPadding** is used, you can specify the following parameters:
-If **NoPadding** is used, specify the parameter as follows:
OpenHarmony Universal KeyStore (HUKS) provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. HUKS also provides APIs for applications to import or generate keys.
OpenHarmony Universal KeyStore (HUKS) provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. HUKS also provides APIs for applications to import or generate keys.
> **NOTE**<br>
> **NOTE**
>
>
> This document is based on API version 9 and applies only to ArkTS development.
> This document is based on API version 9 and applies only to ArkTS development.
...
@@ -20,9 +20,9 @@ Generate a key for an application by specifying the alias and key parameters.
...
@@ -20,9 +20,9 @@ Generate a key for an application by specifying the alias and key parameters.
> **NOTE**
> **NOTE**
>
>
> 1. When a key is used if the parameters passed in does not comply with the parameters passed in during the key generation, the parameter verification will fail.
> - When a key is used if the parameters passed in does not comply with the parameters passed in during the key generation, the parameter verification will fail.
>
>
> 2. If an optional parameter required by the algorithm is not passed in during the key generation process, it must be passed in when the key is used.
> - If an optional parameter required by the algorithm is not passed in during the key generation process, it must be passed in when the key is used.
@@ -16,7 +16,7 @@ Facial recognition establishes a secure channel between a camera and a trusted e
...
@@ -16,7 +16,7 @@ Facial recognition establishes a secure channel between a camera and a trusted e
Facial characteristics are stored in the TEE, which uses strong cryptographic algorithms to encrypt and protect the integrity of facial characteristics. The collected and stored facial characteristics will not be transferred out of the TEE without user authorization. This ensures that system or third-party applications cannot obtain facial characteristics, or send or back them up to any external storage medium.
Facial characteristics are stored in the TEE, which uses strong cryptographic algorithms to encrypt and protect the integrity of facial characteristics. The collected and stored facial characteristics will not be transferred out of the TEE without user authorization. This ensures that system or third-party applications cannot obtain facial characteristics, or send or back them up to any external storage medium.
## Limitations and Constraints
## Constraints
- OpenHarmony only supports facial recognition and local authentication, and does not support an authentication UI.
- OpenHarmony only supports facial recognition and local authentication, and does not support an authentication UI.
- To use biometric recognition, a device must have a camera with a face image pixel greater than 100x100.
- To use biometric recognition, a device must have a camera with a face image pixel greater than 100x100.
