Cryptography API

Cryptography is the process of securing the information. It can be defined as the conversion of data into scrambled text to conceal its readability and meaning, and deciphering it using a key. This data can be sent across safely over public and private networks.

When your app has to transmit sensitive or critical information over the network (private or public), it needs to encrypt the information to ensure information security. A decryption mechanism is used to convert the encrypted text into a readable format.

There are two types of cryptography:

Symmetric Cryptography: A single key is generated. The same key is used in encryption and decryption.
Asymmetric or Public Key Cryptography: A public key and a private key are generated. The public key is used for encryption and the private key is used for decryption. The public key is available in a trusted certificate, whereas the private key is confidential and not shared. Encryption is done on the device and decryption on the server (that has access to the private key). As the private key is not exposed, we support only encryption using asymmetric cryptography.

The Cryptography API enables your app to provide information and services in a secure way. It uses the kony.crypto namespace and the following API elements.

Function	Description
`kony.crypto.asymmetricEncrypt`	Encrypts the input string and returns the encrypted text. This API is available from V8 SP3 onwards.
`kony.crypto.asymmetricDecrypt`	Decrypts the input encrypted string. This API is available from V8 SP3 onwards.
`kony.crypto.createHash`	Provides your app with the ability to create a hash value in hexadecimal format for a given input string using a specified algorithm.
`kony.crypto.createHMacHash`	Generates a hash-based message authentication code (HMAC) that verifies the data integrity and authenticity of the data.
`kony.crypto.createPBKDF2Key`	Creates a Password-Based Key Derivation Function 2 (PBKDF2) key for protecting passwords and other similar tasks.
`kony.crypto.decrypt`	Provides the ability to decrypt the encrypted text with the specified key and algorithm. The API returns the decrypted text.
`kony.crypto.deleteKey`	Provides you the ability to delete a key from the device store.
`kony.crypto.encrypt`	Provides the ability to encrypt the input text with the specified key and algorithm. The rawbytes of the encrypted text are returned.
`kony.crypto.generateAsymmetricKeyPair`	Generates public and private keys for encryption and decryption processes.
`kony.crypto.generateSecureRandom`	Generates cryptographically secure random numbers. This API is available from V8 SP3 onwards.
`kony.crypto.newKey`	Creates a key for cryptography using the specified algorithm. The key created using this API is used for encrypting clear text and decrypting the encrypted data.
`kony.crypto.readKey`	Provides you the ability to read the key from the device store.
`kony.crypto.retrieveAsymmetricPublicKey`	Returns the public key for the alias that you provide. This API is available from V8 SP3 onwards.
`kony.crypto.retrievePublicKey`	Provides the ability to extract the public key from a base64 string of encoded X509 certificate or a locally packaged X509 certificate.
`kony.crypto.saveKey`	Enables your app to save a generated key on the device's storage.

The Cryptography API enables your app to provide information and services in a secure way.

For symmetric cryptography, create a new key by using the kony.crypto.newKey function, then save the key to the device’s local storage using the kony.crypto.saveKey function. To read the key, use the kony.crypto.readKey function. With the generated key, you can now encode the input data by using the kony.crypto.encrypt function. Then, to decrypt the encoded data, use the kony.crypto.decrypt function. If you want to delete any key from the device store, use the kony.crypto.deleteKey function.

For asymmetric cryptography, generate public and private keys using the kony.crypto.generateAsymmetricKeyPair function. Retrieve the generated keys by using the kony.crypto.retrieveAsymmetricPublicKey or kony.crypto.retrievePublicKey functions. With the generated public key, you can now encode the input data using the kony.crypto.asymmetricEncrypt function. Then, to decrypt the encoded data, use the kony.crypto.asymmetricDecrypt function.

Hashing is a one-way encryption process unlike the cryptography. The generated hash value cannot be decrypted. For Hashing, generate a Password-Based Key Derivation Function 2 (PBKDF2) key using the kony.crypto.createPBKDF2Keyfunction. With the generated key, you can encrypt the input text using the kony.crypto.createHashfunction. Once the hash value is generated, you can check the authenticity of the data using the kony.crypto.createHMacHash function.

Concepts

To understand how the Quantum Visualizer Cryptography API works, you must be familiar with some basic concepts.

Ciphers

Apps encrypt and decrypt data using ciphers. A cipher is an algorithm for performing encryption and decryption. The Quantum Visualizer Cryptography API supports block ciphers.A block cipher is a symmetric key cipher that operates on fixed-length groups of bits called blocks. For example, a block cipher encryption algorithm takes a 128-bit block of plain text as input, and produces an output of a corresponding 128-bit block of cipher text. The process of transformation is governed by a secret key. Decryption is a similar process. The decryption algorithm takes a 128-bit block (in this example) of cipher text along with the secret key, and yields the original 128-bit block of plain text.

Block cipher algorithms like DES require their input to be an exact multiple of the block size. If the plain text to be encrypted is not an exact multiple, your app must add padding before encrypting the data.

The following table describes the supported padding for different cipher algorithms:

Algorithm	Platform	Possible Padding
AES/TripleDES	iPhone	pkcs7(default)
AES/TripleDES	Android/Android Tablet	none,pkcs1,pkcs5(default)
RSA	iPhone	none,pkcs1(default)
RSA	Android/Android Tablet	none,pkcs5,pkcs1(default)

RSA is an algorithm for public-key cryptography. It is the first algorithm known for both signing and encryption. This algorithm involves a public key and a private key. The public key can be known to everyone and is used for encrypting messages. Messages encrypted with the public key can only be decrypted using the private key.

Modes

Ciphers are controlled by specific encryption modes. The mode specifies how the data will be encrypted and decrypted . The Quantum Visualizer Cryptography API supports the following standard modes.

Electronic Codebook (ECB) mode
Cipher Block Chaining (CBC) mode
Cipher Feedback (CFB) mode
Output Feedback (OFB) mode
ECB and CBC are valid modes for the Block ciphers

Because these are standard modes, you can find extensive information on the Internet about them if you are not familiar with them.

The following table describes the supported modes for various ciphers.

Algorithm	Platform	Possible Modes
AES/TripleDES	iPhone	ecb,cbc(default)
	Android	ecb,cbc(default)
	SPA	ecb, cfb, ofb, cbc, ctr
RSA	iPhone	ecb(default)
RSA	Android/Android Tablet	ecb(default)

Initialization Vectors

The initialization vector (IV) adds randomness to the cipher text. As a result, if the same message is encrypted twice with the same key, the resulting cipher texts will be different, as long as your app uses different initialization vectors.

The length in bytes of the IV should be the same as the block size of the algorithm (AES and TripleDES). For AES the IV has to be 16 bytes (128 bits). For TripleDES the IV has to be 8 bytes (64 bits).

Supported Algorithms

The Quantum Visualizer Cryptography API provides the following algorithms.

Symmetric Algorithms

For symmetric encryption and decryption, your app can use the following algorithms.

Algorithm Supported Key Strengths (in bits) Description

Algorithm	Supported Key Strengths (in bits)	Description
aes	128, 192, and 256	Advanced Encryption Standard (AES).
tripledes	Triple Data Encryption Standard	Triple Data Encryption Standard. This algorithm uses two keys for encryption and one key for decryption. The algorithm works as follows: `encryptedtext = E_K3(D_K2(E_K1(text to be encrypted)))` The text is encrypted with key1, decrypted with key2, and then again encrypted with key3. Decryption is the reverse: `decryptedtext = D_K3(E_K2(D_K1(text to be decrypted)))` tripledes applies the DES cipher algorithm three times to each data block. The following are the three different combinations of using this algorithm: Option 1: K1, K2, and K3 are different (all three keys are independent) Option 2: K1 and K2 are different; K3=K1 (two keys are independent) Option 3: K1=K2=K3 (all three keys are identical) NOTE: Quantum Visualizer recommends using Option 1 as it is more secure than the other two options.

aes

128, 192, and 256

Advanced Encryption Standard (AES).

tripledes

Triple Data Encryption Standard

Triple Data Encryption Standard. This algorithm uses two keys for encryption and one key for decryption. The algorithm works as follows:

encryptedtext = E_K3(D_K2(E_K1(text to be encrypted)))

The text is encrypted with key1, decrypted with key2, and then again encrypted with key3. Decryption is the reverse:

decryptedtext = D_K3(E_K2(D_K1(text to be decrypted)))

tripledes applies the DES cipher algorithm three times to each data block.

The following are the three different combinations of using this algorithm:

Option 1: K1, K2, and K3 are different (all three keys are independent)
Option 2: K1 and K2 are different; K3=K1 (two keys are independent)
Option 3: K1=K2=K3 (all three keys are identical)

NOTE: Quantum Visualizer recommends using Option 1 as it is more secure than the other two options.

Asymmetric Algorithms

For asymmetric encryption, the Quantum Visualizer Cryptography API supports the RSA algorithm, which is the industry standard. The key length for RSA must be 1024 bits or more.

Platform Limitations

SPA does not support the RSA algorithm.

To view the functionality of the Cryptography API in action, download the sample application from the link below. Once the application is downloaded, build and preview the application using the Quantum App.