kony.crypto Namespace
The kony.crypto namespace provides the following API elements.
Functions
The kony.crypto namespace contains the following functions.
kony.crypto.asymmetricEncrypt
This API encrypts the input string and returns the encrypted text. This API is available from V8 SP3 onwards.
Syntax
kony.crypto.asymmetricEncrypt(alias, inputstring, propertiesTable);
Input Parameters
| Parameters | Description |
|---|---|
| alias [String] - Mandatory |
You can generate the value of the alias parameter by using generateAsymmetricKeyPair API. |
| inputstring[String/ RawBytes] - Mandatory |
The input text to be encrypted. NOTE: RawBytes are only accepted on the Android platform. The content type of the RawBytes must be |
| propertiesTable [Object] - Mandatory |
The applicable values for this parameter are as follows:
|
Example
asymmetricEncrypt: function() {
var key = this.view.tbxasyencrypt.text;
//#ifdef iphone
encryptedobject = kony.crypto.asymmetricEncrypt("Kony", key, {
"transformation": "RSA:OAEP:SHA1"
});
var encryptBase64foriOS = kony.convertToBase64(encryptedobject);
alert("The Encrypted text is as follows " + encryptBase64foriOS);
//#endif
//#ifdef andorid
encryptedobject = kony.crypto.asymmetricEncrypt("Kony", key, {
"transformation": "RSA/ECB/PKCS1Padding"
});
var encryptBase64forAndroid = kony.convertToBase64(encryptedobject);
alert("The Encrypted text is as follows " + encryptBase64forAndroid);
//#endif
},
Return Value
rawbytes [Object] - The rawbytes for the encrypted version of the input text.
Limitations
- RSA can only encrypt data to a maximum amount of your keysize (256 bytes) – padding)/header data.
-
keytype is not considered for Android.
-
This API throws exceptions.
-
This API does not work on Android devices with API level earlier than 18.
-
On Android devices with API level 18 to 22 (both inclusive), only PKCS1Padding is supported ("RSA/ECB/PKCS1Padding" works on all devices with API level 18 and later).
-
Both PKCS1Padding and OAEPPadding are supported on Android devices with API level 23 and later.
-
OAEPPadding transformations are not supported on all Android devices, as there is no documentation from Android for this limitation.
- For iOS, this API works on devices with iOS 10 or later.
Platform Availability
- iOS
- Android
kony.crypto.asymmetricDecrypt
This API decrypts the input encrypted string. This API is available from V8 SP3 onwards.
Syntax
kony.crypto.asymmetricDecrypt(alias, encryptedContent, propertiesTable);
Input Parameters
| Parameters | Description |
|---|---|
| alias [String] - Mandatory |
You can generate the value of the alias parameter by using generateAsymmetricKeyPair API. |
| encryptedContent [Object] - Mandatory |
An object that contains the encrypted text to be decrypted. |
| propertiesTable [Object] - Mandatory |
The applicable values for this parameter are as follows:
|
Example
asymmetricDecrypt: function() {
if (kony.os.deviceInfo().name == "iPhone") {
var decryptedForiOS = kony.crypto.asymmetricDecrypt("Kony", encryptedobject, {
"transformation": "RSA:OAEP:SHA1"
});
alert("The Decrypted Message is as follows " + decryptedForiOS);
} else {
var decryptedForAndroid = kony.crypto.asymmetricDecrypt("Kony", encryptedobject, {
"transformation": "RSA/ECB/PKCS1Padding"
});
alert("The Decrypted Message is as follows " + decryptedForAndroid);
}
},
Return Value [String]
Returns the decrypted/ cipher text.
Limitations
- keytype is not considered for Android
- This API does not work on Android devices with API level earlier than 18.
- On Android devices with API level 18 to 22 (both inclusive), only PKCS1Padding is supported ("RSA/ECB/PKCS1Padding" works on all devices with API level 18 and later).
- Both PKCS1Padding and OAEPPadding are supported on Android devices with API level 23 and later.
- OAEPPadding transformations are not supported on all Android devices, as there is no documentation from Android for this limitation.
- For iOS, this API works on devices with iOS 10 or later.
Platform Availability
- iOS
- Android
kony.crypto.createHash
This function provides your app with the ability to create a hash value in hexadecimal format for a given input string using a specified algorithm.
Syntax
kony.crypto.createHash(algo, inputstring, options);
Input Parameters
Example
createHash: function() {
var algo="sha256";
var inputstr="pleasecreatehash";
var options = {"returnBase64String":"true"};
var myHashValue = kony.crypto.createHash(algo,inputstr,options);
kony.print(“hash value ::”+myHashValue);
},
Return Values
This function returns a string containing the hash value of the inputstring parameter created using the algorithm specified in the algo parameter. This string is in hexadecimal format. The length of the string in bytes is as follows.
| Hashing Algorithm | Result Length (in bytes) | Result Length (in hexadecimal characters) |
|---|---|---|
| sha1 | 20 | 40 |
| sha224 | 28 | 56 |
| sha256 | 32 | 64 |
| sha384 | 48 | 96 |
| sha512 | 64 | 128 |
| md2 | 16 | 32 |
| md4 | 16 | 32 |
| md5 | 16 | 32 |
Exceptions
If an error occurs, this function throws on of the following errors.
| Error Code | Description |
|---|---|
| 2001 | An unsupported algorithm was specified for the algo parameter. |
| 2002 | An invalid key strength was specified. |
| 2003 | A buffer of insufficient was provided for specified operation. |
| 2004 | A memory allocation failure occurred. |
| 2005 | The input data did not encode or encrypt properly. |
| 2006 | The specified name already exists. |
| 2007 | A key with the specified unique ID is not found. |
Remarks
The kony.crypto.createHash function encrypts data by creating a hash of it. The first parameter to this function specifies the cipher. or the encryption algorithm, to use on the data. The algo parameter can be one of the following values.
| Algorithm | Description |
|---|---|
| sha1 | Secure Hash Algorithm 1 (SHA-1) |
| sha224 | Secure Hash Algorithm 224 (SHA-224). |
| sha256 | Secure Hash Algorithm 224 (SHA-256). |
| sha384 | Secure Hash Algorithm 224 (SHA-384). |
| sha512 | Secure Hash Algorithm 224 (SHA-512). |
| md2 | Message-Digest Algorithm 2 (MD2). |
| md4 | Message-Digest Algorithm 4 (MD4). |
| md5 | Message-Digest Algorithm 5 (MD5). |
Platform Availability
Available on all platforms.
kony.crypto.createHMacHash
This function generates a hash-based message authentication code (HMAC) that verifies the data integrity and authenticity of the data.
Syntax
kony.crypto.createHMacHash(algo, key, message,options);
Input Parameters
Example
createHMacHash: function() {
var algo = "sha1";
var message="test message to generate hash ";
var key=”key1”
var options = {"returnBase64String":"true"};
var myHashValue = kony.crypto.createHMacHash(algo, hMacHashKey, message,options);
kony.print("myHash :" + myHash);
},
Return Values
This function returns a string that holds the hash value created using the specified algorithm for the given input string. This string is in a hexadecimal format. The length of the string in bytes is as follows.
| Hashing Algorithm | Result Length (in bytes) | Result Length (in hexadecimal characters) |
|---|---|---|
| sha1 | 20 | 40 |
| sha224 | 28 | 56 |
| sha256 | 32 | 64 |
| sha384 | 48 | 96 |
| sha512 | 64 | 128 |
| md2 | 16 | 32 |
| md4 | 16 | 32 |
| md5 | 16 | 32 |
Exceptions
This function throws the following exceptions.
| Error Code | Description |
|---|---|
| 100 | One or more input parameters are invalid. |
| 101 | An unsupported algorithm was specified for the algo parameter. |
| 102 | An unknown error occurred. |
| 104 | The key strength was invalid. |
| 105 | A mandatory algorithm parameter is missing. |
| 109 | The specified item could not be found. |
Remarks
The following table lists algorithms supported for each platform.
NOTE: From Quantum VisualizerV8 release, the MD5 support is done through Java and not through the Bundle OpenSSL Library.
| Platform Name | Supported Algorithms |
|---|---|
| Android Default Implementation | MD5, SHA1, SHA224, SHA256, SHA384, SHA512 ( SHA224 supported only on API level 21 and above) |
| Android OpenSSL Implementation (Bundle OpenSSL Library option is selected in Quantum Visualizer) | MD5, SHA1, SHA224, SHA256, SHA384, SHA512 |
| iOS | MD5,SHA1,SHA224,SHA256,SHA384,SHA512 |
On Android, the Bundle OpenSSL Library option is available in the Application Properties > Native > Android section. If this option is selected, OpenSSL library is bundled along with the application and use by this function. If the Bundle OpenSSL Library option is not selected in Quantum Visualizer, the default Java implementation offered by the underlying native Android platform is used.
If the device under testing does not support a the hashing algorithm your app selects, this function throws an exception.
Platform Availability
- iOS
- Android
kony.crypto.createPBKDF2Key
The kony.crypto.createPBKDF2Key function creates a Password-Based Key Derivation Function 2 (PBKDF2) key for protecting passwords and other similar tasks.
Syntax
kony.crypto.createPBKDF2Key(algo, password, salt, iteration, klen);
Input Parameters
Example
createPBKDF2KEY: function() {
var algo = "SHA1";
var password = this.view.txtPBKDF2Key.text;
var PBKDF2Key = kony.crypto.createPBKDF2Key(algo, password, "salt", 10000, 256);
this.view.lblPBKDF2Key.text = PBKDF2Key;
},
Return Values
Returns the key created using the PBKDF2 algorithm.
Exceptions
The following table shows the error codes for the exceptions that this function throws, as well as their descriptions .
| Error Code | Description |
|---|---|
| 100 | Invalid Input parameters |
| 101 | Unsupported algorithm |
| 102 | Unknown error |
| 104 | Invalid key strength |
| 105 | Sub algorithm parameter is mandatory |
| 109 | The specified item could not be found. |
Remarks
NOTE: kony.crypto.createPBKDF2Key API does not support md5 algorithm from Quantum VisualizerV8 release.
The Password-Based Key Derivation Function 2 (PBKDF2) is a key derivation function that generates encryption keys of different lengths to protect passwords.
PBKDF2 applies a hash function (chosen by algo parameter) to the input password or passphrase (specified in the password parameter), along with a salt value and repeats the process as many times as is specified in the iteration parameter to produce a derived key that is of the length given in the klen parameter, if a value for klen is provided. The resultant key is used as a cryptographic key in subsequent operations. The added computational work caused by a high number of iterations, or key stretching, makes it more difficult to crack a password. So when you specify the number of iterations, you need to balance security against app performance.
The following table lists algorithms supported for a specific platform. When your app calls the kony.crypto.createPBKDF2Key function, it must select one of the algorithms given in the table for the value of the algo parameter.
| Platform Name | Supported Algorithms |
|---|---|
| Android Default Implementation | SHA1 |
| Android OpenSSL Implementation (Bundle Open SSL Library option is selected in Quantum Visualizer) | SHA1, SHA224, SHA256, SHA384, SHA512 |
| iOS | SHA1 , SHA224, SHA256, SHA384, SHA512 |
| Responsive Web | MD5, SHA1, SHA256, SHA512 |
In Android, the Bundle OpenSSL Library option is available in Application Properties > Native > Android section. If this option is selected, the OpenSSL library is bundled along with the application.
- If the Bundle OpenSSL Library option is selected in Quantum Visualizer, implementation in OpenSSL library is used.
- If the Bundle OpenSSL Library option is not selected in Quantum Visualizer, default Java implementation offered by the native Android platform is used.
If the klen parameter is provided to this function, you must make sure that this key length is supported by a corresponding encryption or decryption algorithm. For aes ciphers, the supported key lengths are 128, 192, or 256 bits. For tripledes ciphers, the possible key length is 192.
The PBKDF2 key that you create in a Responsive Web app cannot be used across other platforms.
Platform Availability
- iOS
- Android
- Responsive Web
kony.crypto.decrypt
This function provides the ability to decrypt the encrypted text with the specified key and algorithm. The API returns the decrypted text.
Syntax
kony.crypto.decrypt(algo, generatedkey, encryptedRawbytes, propertiesTable);
Input Parameters
| Parameters | Description |
|---|---|
| algo |
A string that specifies the decryption algorithm. For possible values, see the Remarks section below. |
| generatedkey |
An object that holds the key to be used for decryption. |
| encryptedRawbytes |
An object that contains the rawbytes of the encrypted text to be decrypted. |
| propertiesTable [Table] - Mandatory | A JavaScript object that contains key-value pairs necessary for decryption. For details, see the Remarks section below. |
Example
decrypt: function() {
try {
var algo = "aes";
var myEncryptedTextRa = "";
var encryptDecryptKey = kony.crypto.newKey("passphrase", 128, {
passphrasetext: ["inputstring1"],
subalgo: "aes",
passphrasehashalgo: "md5"
});
var prptobj = {
padding: "pkcs5",
mode: "cbc",
initializationvector: "1234567890123456"
};
if (this.view.lblEncrypt.text === "" || this.view.lblEncrypt.text === null || this.view.lblEncrypt.text === "Please enter the text to encrypt") {
this.view.lblDecrypt.text = "There is no encrypted text";
return;
}
var str = this.view.lblEncrypt.text;
// if(kony.os.deviceInfo().name == "thinclient")
// {
// myEncryptedTextRa = myEncryptedTextRaw;
// }
// else
myEncryptedTextRa = kony.convertToRawBytes(str.substring(17));
var myClearText = kony.crypto.decrypt(algo, encryptDecryptKey, myEncryptedTextRa, prptobj);
this.view.lblDecrypt.text = "Decrypted text = " + myClearText.toString();
} catch (err) {
alert(typeof err);
alert("Error in callbackDecryptAes : " + err);
}
},
Return Values
Returns a string chat holds the clear text decrypted from the encrypted rawbytes.
Exceptions
CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.
- 2001 - unsupported algorithm.
- 2002 - invalid key strength specified.
- 2003 - insufficient buffer provided for specified operation.
- 2004 - memory allocation failure.
- 2005 - input data did not encode or encrypt properly.
- 2006 - specified name already exists.
- 2007 - key with the specified unique ID is not found.
Remarks
The values that your app can use for the algo parameter are as follows.
| Constant | Description |
|---|---|
| aes | Selects AES encryption. |
| tripledes | Selects Triple DES encryption. |
| rsa | Selects RSA encryption. |
The JavaScript object in the propertiesTable parameter must have the following format.
The padding property of the object that is passed into this function through the propertiesTable parameter is used to pad the encrypted text so that the size of the encrypted text is the same as the block size used in the encryption/decryption algorithm selected in the algo parameter to this function. The block size for the available algorithms is as follows.
| Property | Description |
|---|---|
| aes | 128 bits |
| tripledes | 64 bits |
| initializationvector | 1024 or 2048 bits |
For more information on padding, modes, and initialization vectors, see Concepts in the Cryptography API overviews.
Platform Availability
Available on all platforms except J2ME.
kony.crypto.deleteKey
This API provides you the ability to delete a key from the device store.
Use Cases
You can delete the key from the device store if you are sure that you do not need that key anymore in the application.
Syntax
kony.crypto.deleteKey(uniqueID);
Input Parameters
| Parameters | |
|---|---|
| uniqueID [String] - Mandatory | Unique ID represents the key on the device store (this is the ID returned by kony.crypto.saveKey API). |
Example
deleteKey: function() {
kony.crypto.deleteKey(saveKey);
this.view.lblKey.text = "The key is deleted";
},
Return Values
None
API Usage
You can use this API only to delete the keys that you have saved earlier on the device store,which is keys that have a unique ID associated with it.
Exceptions
CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.
- 2001 - unsupported algorithm.
- 2002 - invalid key strength specified.
- 2003 - insufficient buffer provided for specified operation.
- 2004 - memory allocation failure.
- 2005 - input data did not encode or encrypt properly.
- 2006 - specified name already exists.
- 2007 - key with the specified unique ID is not found.
Platform Availability
Available on all platforms.
NOTE: You can use this API only to delete the keys that you have saved earlier on the device store, i.e., keys that have a unique ID associated with them.
kony.crypto.encrypt
Converting data into an encoded format using a key is known as encryption. Encryption of data is done through symmetric cryptography. We support both symmetric and asymmetric encryption.
This API provides the ability to encrypt the input text with the specified key and algorithm. The rawbytes of the encrypted text are returned.
Use Cases
You need to use encryption when you pass sensitive data like:
- passwords
- account numbers
- account information
- credit card information, and so on.
Syntax
kony.crypto.encrypt(algo, generatedkey, inputstring, propertiesTable);
Input Parameters
Examples
Return Values
rawbytes [Object] - userdata
The rawbytes for the encrypted version of the input text.
Exceptions
CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.
- 2001 - unsupported algorithm.
- 2002 - invalid key strength specified.
- 2003 - insufficient buffer provided for specified operation.
- 2004 - memory allocation failure.
- 2005 - input data did not encode or encrypt properly .
- 2006 - specified name already exists.
- 2007 - key with the specified unique ID is not found.
Platform Availability
Available on all platforms.
kony.crypto.generateAsymmetricKeyPair
This API is used to generate public and private keys for encryption and decryption processes. Typically, you can use the Public key to verify the digital signature and plain text data, whereas you can use the Private key to create a digital signature and to decrypt the text. This API is available from V8 SP3 onwards.
Syntax
kony.crypto.generateAsymmetricKeyPair(propertiesTable);
Input Parameters
| Parameters | Description |
|---|---|
| propertiesTable [Object] - Mandatory |
A key-value pair that you can use to generate asymmetric key pairs. The following input values are applicable for this parameter:
|
Example
generateAsymmetricKeyPair: function() {
var isGenerated = kony.crypto.generateAsymmetricKeyPair({
"alias": "Kony",
"algo": "RSA",
"padding": "PKCS1Padding",
"cipher": "RSA",
"mode": "ECB",
"digest": "",
"keysize": "2048",
"publicexponent": 3
});
alert("The Generated Key is " + isGenerated);
},
Return Value [Boolean]
Status of the key value generation.
Limitations
- For iOS
- The
publicexponent,padding,digest, andmodeattributes are not considered for key generation. - This API is supported on devices with iOS 10.0 or later.
- The
- For Android
- This API does not work on devices with API level earlier than 18.
The following values are supported for
publicexponentattribute: 3 and 65537.The following values are supported for
digestattribute: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512.
If thedigestattribute is not required, use an empty string as the digest value.The following value is supported for the
mode: ECB.- You cannot provide the value
Noneto thepaddingattribute.
Platform Availability
- iOS
- Android
kony.crypto.generateSecureRandom
This API is used to generate a cryptographically secure random key.
Support for this API is available from the Quantum Visualizer V8 SP3 release onwards.
Syntax
kony.crypto.generateSecureRandom(propertiesTable);
Input Parameters
| Parameters | Description |
|---|---|
| propertiesTable [Object] - Mandatory |
A key-value pair that you can use to send the type and size of the key, in order to generate secure random cryptographic numbers.
|
Example
kony.crypto.generateSecureRandom({
type:”bytes”,
size: < length >
});
Return Value [Object]
Secure random key of the bytes array or Base64 string of the specified length.
- On the Android platform, this API returns a combination of alphanumeric and special characters.
- On the iOS platform, this API returns numeric characters.
Limitations
- For Android
- This API does not work on devices with API level earlier than 18.
Platform Availability
- Android
- iOS
kony.crypto.newKey
This API allows you to create 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.
Use Case
You can use this API to generate cryptographic keys when you want to transmit information in a secured manner over the private or public networks.
Syntax
kony.crypto.newKey(algo, keystrength, propertiesTable);
Input Parameters
Example
createNewKey: function() {
newKey = kony.crypto.newKey("passphrase", 128, {
passphrasetext: ["inputstring1"],
subalgo: "aes",
passphrasehashalgo: "md2"
});
this.view.lblKey.text = JSON.stringify(newKey);
},
Exceptions
CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.
- 2001 - unsupported algorithm.
- 2002 - invalid key strength specified.
- 2003 - insufficient buffer provided for specified operation.
- 2004 - memory allocation failure.
- 2005 - input data did not encode or encrypt properly .
- 2006 - specified name already exists.
- 2007 - key with the specified unique ID is not found.
Return Values
The following are the return values for this API:
key [userdata] - object
The key that is created using the specified algorithm.
API Usage
The recommended key strengths are as follows for this API:
- aes - 128
- tripledes - 192.
Platform Availability
Available on all platforms except J2ME.
kony.crypto.readKey
This API provides you the ability to read the key from the device store.
NOTE: From V8 SP4 onwards, the readKey data for a Quantum App child app is stored in child app data and not under the parent app. This feature is applicable for iOS and Android platforms.
NOTE: Device store in case of iOS is Keychain. Keychain in iOS is the most secured place to store the crypto keys. saveKey and readKey APIs save and read from the Keychain. The Keychain can be shared between the applications provisioned and signed by the same certificate vendor.
IMPORTANT: To avoid accidental overwrite of one application content by the other application content, it is recommended to use the unique application specific identifier while saving and reading the crypto keys using saveKey and readKey APIs.
Use Cases
You can read the key from the device store if you want to use that key for encryption or decryption.
Syntax
kony.crypto.readKey(uniqueID);
Input Parameters
| Parameters | Description |
|---|---|
| uniqueID [String] - Mandatory |
Unique ID represents the key on the device store (this is the ID returned by kony.crypto.saveKey API). |
Example
readKey: function() {
var read = kony.crypto.readKey(saveKey);
this.view.lblKey.text = JSON.stringify(read);
}
The constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED parameter is an optional parameter. It indicates when a keychain item is accessible.
The following values are supported:
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED : The data in the keychain item can be accessed when a device is unlocked by the user.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED_THIS_DEVICE_ONLY: The data in the keychain item can be accessed only when a specific device is unlocked by the user
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_ALWAYS_THIS_DEVICE_ONLY: The data in the keychain item can always be accessed regardless of whether a specific device is locked.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_PASSCODE_SET_THIS_DEVICE_ONLY: The data in the keychain can only be accessed when the device is unlocked. This is only available if a passcode is set on the device.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_ALWAYS: The data in the keychain item can always be accessed regardless of whether a device is locked.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_AFTER_FIRST_UNLOCK: The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY: The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.
Return Values
The following are the return values for this API:
key [rawbytes - object]
This key is generated using aes, tripledes, or RSA algorithms and saved on the device store.
API Usage
You can use this API only to read the keys that you have saved earlier on the device store, i.e., keys that have a unique ID associated with them.
Exceptions
CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.
- 2001 - unsupported algorithm.
- 2002 - invalid key strength specified.
- 2003 - insufficient buffer provided for specified operation.
- 2004 - memory allocation failure.
- 2005 - input data did not encode or encrypt properly.
- 2006 - specified name already exists.
- 2007 - key with the specified unique ID is not found.
Platform Availability
Available on all platforms.
kony.crypto.retrieveAsymmetricPublicKey
This API returns the public key for the alias that you provide. This API is available from V8 SP3 onwards.
Syntax
kony.crypto.retrieveAsymmetricPublicKey(alias);
Input Parameters
| Parameters | Description |
|---|---|
| alias [String] |
The alias value generated by using generateAsymmetricKeyPair API. |
Example
retrieveAsymmetricKey: function() {
var key = kony.crypto.retrieveAsymmetricPublicKey("Kony");
alert("The Asymmetric key is " + key);
}
Return Value [String]
Returns the public part of the asymmetric key-pair for the provided alias.
Limitations
- For iOS
- This API works on devices with iOS 10 or later.
- For Android
- This API does not work on devices with API level earlier than 18.
Platform Availability
- iOS
- Android
kony.crypto.retrievePublicKey
Public Key Infrastructure (PKI) is the mechanism to secure the public networks (like Internet) to safely and securely transmit data with the use of keys. PKI assumes the use of public key cryptography (asymmetric cryptography). PKI is the most common method to authenticate the message sender or encrypt the message. PKI consists of a Certificate Authority (CA) that issues and verifies digital certificates (trusted certificates). A certificate includes the public key or information about the public key.
This API provides the ability to extract the public key from a base64 string of encoded X509 certificate or a locally packaged X509 certificate.
Syntax
kony.crypto.retrievePublicKey(algo, inputsource, islocalresource);
Input Parameters
| Parameters | Description |
|---|---|
| algo [String] - Mandatory |
The algorithm used for the public key. Possible values are:
|
| inputsource [String] - Mandatory |
This parameter indicates the name of the input source certificate from which the key needs to be retrieved. NOTE: The certificate must be present in the resources folder. NOTE: In case of the Android platform, place the .cer file at the ../resources/mobile/native/android/assets/ location. |
| islocalresource [Boolean] - Mandatory |
This flag defines how the inputsource string needs to be interpreted.
|
Example
var myKey = kony.crypto.retrievePublicKey("rsa", "public.cer", true);
Return Values
publickey - userdata [Object]
The public key extracted from the certificate.
Rules and Restrictions
- Self-signed certificates are not supported on Android.
- iOS supports only Distinguished Encoding Rules (DER) representation of an X.509 certificate, when input source is certificate.
Exceptions
CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.
- 2001 - unsupported algorithm.
- 2002 - invalid key strength specified.
- 2003 - insufficient buffer provided for specified operation.
- 2004 - memory allocation failure.
- 2005 - input data did not encode or encrypt properly.
- 2006 - specified name already exists.
- 2007 - key with the specified unique ID is not found.
Platform Availability
Available on all platforms except Desktop Web.
kony.crypto.saveKey
This function allows your app to save a generated key on the device's storage.
NOTE: From V8 SP4 onwards, the saveKey data for a Quantum App child app is stored in child app data and not under the parent app. This feature is applicable for iOS and Android platforms.
Syntax
kony.crypto.saveKey(name, key);
Input Parameters
| Parameters | Description |
|---|---|
| name | A string that specifies a unique name with which you want to save the key on the device store. |
| key |
An object that holds the key that you want to save on the device. |
Example
saveTheKey: function() {
saveKey = kony.crypto.saveKey("SavedKey", newKey, constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED);
this.view.lblKey.text = "The Key is Saved";
},
The constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED parameter is an optional parameter. It indicates when a keychain item is accessible.
The following values are supported:
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED : The data in the keychain item can be accessed when a device is unlocked by the user.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED_THIS_DEVICE_ONLY: The data in the keychain item can be accessed only when a specific device is unlocked by the user.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_ALWAYS_THIS_DEVICE_ONLY: The data in the keychain item can always be accessed regardless of whether a specific device is locked.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_PASSCODE_SET_THIS_DEVICE_ONLY: The data in the keychain can only be accessed when the device is unlocked. This is only available if a passcode is set on the device.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_ALWAYS: The data in the keychain item can always be accessed regardless of whether a device is locked.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_AFTER_FIRST_UNLOCK: The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.
- constants.KONY_KEYCHAIN_ITEM_ACCESSIBLE_AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY: The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.
Return Values
Returns a string containing a unique ID that represents the saved key on the device's storage. Your app can access the key from the device's storage using this unique ID. The unique ID is determined by the system. On some platforms it might be the same as the name in the name parameter. However, that is not the case on all platforms.
Exceptions
CryptoError: Thrown by Crypto API.Various error conditions related to CryptoError will be covered through the following error codes.
| Constant | Description |
|---|---|
| 2001 | The encryption algorithm is unsupported on the device. |
| 2002 | An invalid key length was specified. |
| 2003 | Insufficient buffer space was provided for operation. |
| 2004 | There was a memory allocation failure. |
| 2005 | The input data did not encode or encrypt properly. |
| 2006 | The specified name already exists |
| 2007 | A key with the specified unique ID is not found. |
Remarks
Your app can use this function to save the generated symmetric keys. If a key does not exist with the given name, this function creates a key. If a key exists with the given name, this function saves the key onto the device's storage.
The device store on iOS is the keychain. The keychain on iOS is the most secure place to store the cryptographic keys. saveKey and readKey APIs save to and read from the keychain. The keychain can be shared between applications that are provisioned and signed by the same certificate vendor.
In Android, the kony.crypto.saveKey saves the crypto key in the application's private file system. This crypto key is encrypted.
IMPORTANT: To avoid accidentally overwriting one application's keys by another application, Quantum Visualizer recommends that your app use a unique application-specific identifier while saving and reading keys.
Platform Availability
Available on all platforms.