voltmx.crypto Namespace

This API encrypts the input string and returns the encrypted text. This API is available from V9 SP2 onwards.

Syntax

voltmx.crypto.asymmetricEncrypt(alias, inputstring, propertiesTable)

Input Parameters

Example

asymmetricEncrypt: function() {
    var key = this.view.tbxasyencrypt.text;

    //#ifdef iphone
    encryptedobject = voltmx.crypto.asymmetricEncrypt("VoltMX", key, {
        "transformation": "RSA:OAEP:SHA1"
    });
    var encryptBase64foriOS = voltmx.convertToBase64(encryptedobject);
    alert("The Encrypted text is as follows " + encryptBase64foriOS);
    //#endif
    //#ifdef andorid
    encryptedobject = voltmx.crypto.asymmetricEncrypt("VoltMX", key, {
        "transformation": "RSA/ECB/PKCS1Padding"
    });
    var encryptBase64forAndroid = voltmx.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

• If you build a Web or Native App with strict mode enabled, the SHA1, MD2, MD4, and MD5 hashing algorithms are not supported. If you use any of those algorithms in strict mode, you will receive an “Unsupported algorithm” error message.
• RSA can only encrypt data to a maximum amount of your keysize (256 bytes) – padding)/header data.
• keytype is not considered for Android.
• transformation is not considered for Windows.
• 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
• Windows

This API decrypts the input encrypted string. This API is available from V9 SP2 onwards.

Syntax

voltmx.crypto.asymmetricDecrypt(alias, encryptedContent, propertiesTable)

Input Parameters

Example

asymmetricDecrypt: function() {
    if (voltmx.os.deviceInfo().name == "iPhone") {
        var decryptedForiOS = voltmx.crypto.asymmetricDecrypt("VoltMX", encryptedobject, {
            "transformation": "RSA:OAEP:SHA1"
        });
        alert("The Decrypted Message is as follows " + decryptedForiOS);
    } else {
        var decryptedForAndroid = voltmx.crypto.asymmetricDecrypt("VoltMX", encryptedobject, {
            "transformation": "RSA/ECB/PKCS1Padding"
        });
        alert("The Decrypted Message is as follows " + decryptedForAndroid);
    }
},

Return Value [String]

Returns the decrypted/cipher text.

Limitations

• If you build a Web or Native App with strict mode enabled, the SHA1, MD2, MD4, and MD5 hashing algorithms are not supported. If you use any of those algorithms in strict mode, you will receive an “Unsupported algorithm” error message.
• transformation is not considered for Windows.
• 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
• Windows

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

voltmx.crypto.createHash(  
    algo,  
    inputstring,options)

Input Parameters

Example

createHash: function() {  
var algo="sha256";  
var inputstr="pleasecreatehash";  
 var options = {"returnBase64String":"true"};  
var myHashValue = voltmx.crypto.createHash(algo,inputstr,options);  
voltmx.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.

Exceptions

If an error occurs, this function throws on of the following errors.

Remarks

The voltmx.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.

Note: If you build a Web or Native App with strict mode enabled, the SHA1, MD2, MD4, and MD5 hashing algorithms are not supported. If you use any of those algorithms in strict mode, you will receive an “Unsupported algorithm” error message.

Note: md5, sha1, sha256, sha384, and sha512 are supported for Windows.

Platform Availability

Available on all platforms.

This function generates a hash-based message authentication code (HMAC) that verifies the data integrity and authenticity of the data.

Syntax

voltmx.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 = voltmx.crypto.createHMacHash(algo, hMacHashKey, message,options);
    voltmx.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.

Exceptions

This function throws the following exceptions.

Remarks

The following table lists algorithms supported for each platform.

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 Volt MX Iris)	MD5, SHA1, SHA224, SHA256, SHA384, SHA512
iOS	MD5,SHA1,SHA224,SHA256,SHA384,SHA512

Note: If you build a Web or Native App with strict mode enabled, the SHA1, MD2, MD4, and MD5 hashing algorithms are not supported. If you use any of those algorithms in strict mode, you will receive an “Unsupported algorithm” error message.

Note: From Volt MX IrisV9 release, the MD5 support is done through Java and not through the Bundle OpenSSL Library.

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 Volt MX Iris, 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

Available on iOS and Android.

The voltmx.crypto.createPBKDF2Key function creates a Password-Based Key Derivation Function 2 (PBKDF2) key for protecting passwords and other similar tasks.

Syntax

voltmx.crypto.createPBKDF2Key(  
    algo,  
    password,  
    salt,  
    iteration,  
    klen)

Input Parameters

Example

createPBKDF2KEY: function() {
    var algo = "SHA1";
    var password = this.view.txtPBKDF2Key.text;
    var PBKDF2Key = voltmx.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 .

Remarks

voltmx.crypto.createPBKDF2Key API does not support md5 algorithm from Volt MX IrisV9 release.

If you build a Web or Native App with strict mode enabled, the SHA1, MD2, MD4, and MD5 hashing algorithms are not supported. If you use any of those algorithms in strict mode, you will receive an “Unsupported algorithm” error message.

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 voltmx.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 Volt MX Iris)	SHA1, SHA224, SHA256, SHA384, SHA512
iOS	SHA1 , SHA224, SHA256, SHA384, SHA512
Windows	SHA1, SHA256, SHA384, SHA512, and MD5.

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 Volt MX Iris, implementation in OpenSSL library is used.
• If the Bundle OpenSSL Library option is not selected in Volt MX Iris, 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.

Platform Availability

Available in iOS, Android , and Windows.

This function provides the ability to decrypt the encrypted text with the specified key and algorithm. The API returns the decrypted text.

Syntax

voltmx.crypto.decrypt(  
    algo,  
    generatedkey,  
    encryptedRawbytes,  
    propertiesTable)

Input Parameters

Example

decrypt: function() {
    try {
        var algo = "aes";
        var myEncryptedTextRa = "";

        var encryptDecryptKey = voltmx.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;
        //convertToRawBytes is not supported in SPA
        // 		if(voltmx.os.deviceInfo().name == "thinclient")
        // 		{
        // 			 myEncryptedTextRa = myEncryptedTextRaw;
        // 		}
        // 		else
        myEncryptedTextRa = voltmx.convertToRawBytes(str.substring(17));
        var myClearText = voltmx.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.

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.

For more information on padding, modes, and initialization vectors, see Concepts in the Cryptography API overviews.

Platform Availability

Available on all platforms except J2ME.

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

voltmx.crypto.deleteKey([uniqueID](#uniqueID))

Input Parameters

Example

deleteKey: function() {
    voltmx.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.

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

voltmx.crypto.encrypt([algo](#algo_encrypt), [generatedkey](#generatedkey), [inputstring](#inputstring_encrypt), [propertiesTable](#propertiesTable_encrypt))

Input Parameters

Examples

Encrypt: function() {
    try {
        var algo = "aes";
        var inputstr = "";
        var encryptDecryptKey = voltmx.crypto.newKey("passphrase", 128, {
            passphrasetext: ["inputstring1"],
            subalgo: "aes",
            passphrasehashalgo: "md5"
        });

        if (this.view.textEncrypt.text === "" || this.view.textEncrypt.text === null) {
            this.view.lblEncrypt.text = "Please enter the text to encrypt";
            return;
        } else {
            inputstr = this.view.textEncrypt.text;
        }

        var prptobj = {
            padding: "pkcs5",
            mode: "cbc",
            initializationvector: "1234567890123456"
        };
        myEncryptedTextRaw = voltmx.crypto.encrypt(algo, encryptDecryptKey, inputstr, prptobj);
        var myEncryptedText = voltmx.convertToBase64(myEncryptedTextRaw);

        // 		if(voltmx.os.deviceInfo().name == "Windows 10")
        // 		{
        // 			this.view.lblEncrypt.text = "Encrypted text = "+myEncryptedTextRaw.toString();
        // 		}
        // 		else
        // 		{
        this.view.lblEncrypt.text = "Encrypted text = " + myEncryptedText.toString();
        // 		}

    } catch (err) {
        alert(typeof err);
        alert("Error in callbackEncryptAes : " + err);
    }
},

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.

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 V9 SP2 onwards.

Syntax

voltmx.crypto.generateAsymmetricKeyPair(propertiesTable)

Input Parameters

Example

generateAsymmetricKeyPair: function() {
    var isGenerated = voltmx.crypto.generateAsymmetricKeyPair({
        "alias": "VoltMX",
        "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

• If you build a Web or Native App with strict mode enabled, the SHA1, MD2, MD4, and MD5 hashing algorithms are not supported. If you use any of those algorithms in strict mode, you will receive an “Unsupported algorithm” error message.
• For iOS
  • publicexponent, padding, digest, and mode are not considered for key generation.
  • This API is supported on devices with iOS 10.0 or later.
• For Android
  • This API does not work on devices with API level earlier than 18.

  • Supported publicexponent values: 3 and 65537.

  • Possible digest values: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512. If there is no digest required, use an empty string as the digest value.

  • Possible mode value: ECB.
• For Windows

  • The ‘None’ padding is not supported.

  • publicexponent and mode are not considered.

  • SHA-224 is not supported.

  • Typical key sizes are 512 bits, 1024 bits, 2048 bits, or 4096 bits.

Platform Availability

• iOS
• Android
• Windows

This API is used to generate cryptographically secure random numbers. This API is available from V9 SP2 onwards.

Syntax

voltmx.crypto.generateSecureRandom(propertiesTable)

Input Parameters

• type [String]: The possible values for the type key are ‘bytes’ and ‘base64.’
• size [bytes]: The length of the random key to be generated.

Example

voltmx.crypto.generateSecureRandom({
    type:”bytes”, 
    size: < length >
});

Return Value [Object]

Secure random key of the bytes array or Base64 string of the specified length.

Limitations

• For Android
  • This API does not work on devices with API level earlier than 18.

Platform Availability

• Android
• iOS
• Windows

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

voltmx.crypto.newKey([algo](#algo), [keystrength](#keystrength), [propertiesTable](#propertiesTable))

Input Parameters

| Parameters | Description | | — | — | | algo [String] - Mandatory | Scheme using which the key is to be created. Possible values are: securerandom - uses a secure random number as the scheme to generate a key. This scheme always produces a unique key. random - uses a random number as the scheme to generate a key. This scheme always produces a unique key.> Note: random and securerandom are supported only on iPhone.> Note: There is no differentiation between securerandom and random on Android. passphrase - if this is the scheme, you need to pass the exact passphrase using which the key needs to be generated. The passphrasetext (an array of strings) is passed in the properties (JavaScript) parameter. The passphrase scheme always produces the same key for the same passphrase text. > Note: Only Passphrase is supported on SPA. | | keystrength [Number] - Mandatory | Number of bits that indicate the key strength. If the subalgo is: aes - possible value is 128, 192, 256. tripledes - possible value is 192.

Important:   tripledes Algorithm is not supported in Windows Platforms. On iPhone platform, keystrength of 192 is supported only if the algorithm is random or securerandom. You cannot apply a passphrasehashlogo to the key when the algorithm is random or securerandom. tripledes - In Android and iOS, if the supplied key length is not equal to 192 an exception will be thrown with error message Invalid Keystrength and error code 104.

Example

createNewKey: function() {
    newKey = voltmx.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.

Limitations

• If you build a Web or Native App with strict mode enabled, the SHA1, MD2, MD4, and MD5 hashing algorithms are not supported. If you use any of those algorithms in strict mode, you will receive an “Unsupported algorithm” error message.

This API provides you the ability to read the key from the device store.

Note: From V9 SP2 onwards, the readKey data for a Volt MX App child app is stored in child app data and not under the parent app. This feature is applicable for iOS, Windows, 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

voltmx.crypto.readKey([uniqueID](#uniqueID_Read))

Input Parameters

Example

readKey: function() {
    var read = voltmx.crypto.readKey(saveKey);
    this.view.lblKey.text = JSON.stringify(read);
}

The constants.VOLTMX_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED parameter is an optional parameter. It indicates when a keychain item is accessible.

The following values are supported:

• constants.VOLTMX_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED : The data in the keychain item can be accessed when a device is unlocked by the user.
• constants.VOLTMX_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.VOLTMX_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.VOLTMX_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.VOLTMX_KEYCHAIN_ITEM_ACCESSIBLE_ALWAYS: The data in the keychain item can always be accessed regardless of whether a device is locked.
• constants.VOLTMX_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.VOLTMX_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.

This API returns the public key for the alias that you provide. This API is available from V9 SP2 onwards.

Syntax

voltmx.crypto.retrieveAsymmetricPublicKey(alias)

Input Parameters

Example

retrieveAsymmetricKey: function() {
    var key = voltmx.crypto.retrieveAsymmetricPublicKey("VoltMX");
    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
• Windows

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.

Note: Due to security reasons, Thin Client or Mobile Web applications cannot access public/private keys or certificates that are on the server.

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

voltmx.crypto.retrievePublicKey([algo](#algo_retrievepk), [inputsource](#inputsource_retrievepk), [islocalresource](#islocalresource_retrievepk))

Input Parameters

Example

var myKey = voltmx.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 Windows, Service Side Mobile Web, Desktop Web, and SPA.

This function allows your app to save a generated key on the device’s storage.

Note: From V9 SP2 onwards, the saveKey data for a Volt MX App child app is stored in child app data and not under the parent app. This feature is applicable for iOS, Windows, and Android platforms.

Syntax

voltmx.crypto.saveKey(  
    name,  
    key)

Input Parameters

Example

saveTheKey: function() {
    saveKey = voltmx.crypto.saveKey("SavedKey", newKey, constants.VOLTMX_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED);
    this.view.lblKey.text = "The Key is Saved";
},

The constants.VOLTMX_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED parameter is an optional parameter. It indicates when a keychain item is accessible.

The following values are supported:

• constants.VOLTMX_KEYCHAIN_ITEM_ACCESSIBLE_WHEN_UNLOCKED : The data in the keychain item can be accessed when a device is unlocked by the user.
• constants.VOLTMX_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.VOLTMX_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.VOLTMX_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.VOLTMX_KEYCHAIN_ITEM_ACCESSIBLE_ALWAYS: The data in the keychain item can always be accessed regardless of whether a device is locked.
• constants.VOLTMX_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.VOLTMX_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.

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 voltmx.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, Volt MX Iris recommends that your app use a unique application-specific identifier while saving and reading keys.

Platform Availability

Available on all platforms.