A minimal sodium plugin for Cordova - for iOS and Android

A minimal build of the libsodium library, as a plugin for Cordova applications on iOS and Android.

Bound methods and constants

Secretbox construction

• crypto_secretbox_easy
• crypto_secretbox_open_easy
• crypto_secretbox_KEYBYTES
• crypto_secretbox_MACBYTES
• crypto_secretbox_NONCEBYTES

Public key signatures (Ed25519)

• crypto_sign
• crypto_sign_open
• crypto_sign_detached
• crypto_sign_verify_detached
• crypto_sign_keypair
• crypto_sign_seed_keypair
• crypto_sign_ed25519_sk_to_pk
• crypto_sign_ed25519_sk_to_seed
• crypto_sign_BYTES
• crypto_sign_PUBLICKEYBYTES
• crypto_sign_SECRETKEYBYTES
• crypto_sign_SEEDBYTES

Key exchange (Curve25519)

• crypto_scalarmult
• crypto_scalarmult_base
• crypto_scalarmult_BYTES
• crypto_scalarmult_SCALARBYTES

X25519 (Ed25519 -> Curve25519 conversion)

• crypto_sign_ed25519_pk_to_curve25519
• crypto_sign_ed25519_sk_to_curve25519

Memory-hard password derivation (Scrypt)

• crypto_pwhash_scryptsalsa208sha256
• crypto_pwhash_scryptsalsa208sha256_ll
• crypto_pwhash_scryptsalsa208sha256_SALTBYTES
• crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_INTERACTIVE
• crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_INTERACTIVE

NOTE: the constants crypto_pwhash_scryptsalsa208sha256_*_SENSITIVE have not been bound. Not that they were forgotten, but it's a design choice. A standard smartphone will most likely be too slow if these constants are used in scrypt. These values are not forbidden though...

Box construction

• crypto_box_keypair
• crypto_box_easy
• crypto_box_open_easy
• crypto_box_PUBLICKEYBYTES
• crypto_box_SECRETKEYBYTES
• crypto_box_NONCEBYTES
• crypto_box_SEEDBYTES
• crypto_box_MACBYTES

Sealed box construction

• crypto_box_seal
• crypto_box_seal_open
• crypto_box_SEALBYTES

Generic hashing

• crypto_generichash
• crypto_generichash_BYTES
• crypto_generichash_BYTES_MIN
• crypto_generichash_BYTES_MAX
• crypto_generichash_KEYBYTES
• crypto_generichash_KEYBYTES_MIN
• crypto_generichash_KEYBYTES_MAX

Helper methods

HexString <-> Uint8Array conversion

• to_hex
• from_hex

UTF8String <-> Uint8Array conversion

• to_string
• from_string

Base64String <-> Uint8Array conversion

• to_base64
• from_base64

Installation

cordova plugin add cordova-plugin-minisodium

Note: This plugin is not built for Android API levels below 21. To set the minSdkVersion property in your Cordova app (if needed), add the following line in config.xml:

<preference name="android-minSdkVersion" value="21"/>

Usage

Once the plugin is installed, all the methods of this plugin are available in window.plugins.MiniSodium.

Results of these methods are not returned, but rather passed to a callback function. The callback function will receive 2 parameters : (err, result), where:

• err is an error (either a string or an Error instance), defined if an error occurred in the method
• result is the result of the method call (such as a ciphertext, a plaintext, a derived key, a key pair,...). Results are always Uint8Array instances, except for keypair generation methods, where result is a {pk, sk} object (pk and sk are Uint8Array containing the public and private/secret keys respectively)

Raw data parameters (e.g: message, ciphertext, keys, nonces, hashes,...) must provided either as Uint8Array instances or as hexadecimal strings.

The order of parameters in the bound methods is nearly respected (compared to the original libsodium library)

If you have questions about the parameters of the methods, we advise you to read the documentation of the original library

Anyway, here is this plugin's API:

Secretbox

• MiniSodium.crypto_secretbox_easy(message, nonce, key, callback)
• MiniSodium.crypto_secretbox_open_easy(ciphertext, nonce, key, callback)

Sign

• MiniSodium.crypto_sign_keypair(callback)
• MiniSodium.crypto_sign_seed_keypair(seed, callback)
• MiniSodium.crypto_sign(message, secretKey, callback)
• MiniSodium.crypto_sign_open(signedMessage, publicKey, callback) NOTE: This method passes the message (without the signature) to the callback if the signature is valid. If the signature is invalid it passes 0 or false instead
• MiniSodium.crypto_sign_detached(message, secretKey, callback)
• MiniSodium.crypto_sign_verify_detached(signature, message, publicKey, callback) NOTE: The result of this method is a boolean. The callback receives true or 1 if the signature is valid false or 0 otherwise
• MiniSodium.crypto_sign_ed25519_sk_to_seed(secretKey, callback)
• MiniSodium.crypto_sign_ed25519_sk_to_pk(secretKey, callback)

Ed25519 -> Curve25519 conversion

• MiniSodium.crypto_sign_ed25519_pk_to_curve25519(ed25519Pk, callback)
• MiniSodium.crypto_sign_ed25519_sk_to_curve25519(ed25519Sk, callback)

Scalarmult (Curve25519)

• MiniSodium.crypto_scalarmult_base(n, callback)
• MiniSodium.crypto_scalarmult(n, p, callback)

Password-hashing (Scrypt)

• MiniSodium.crypto_pwhash_scryptsalsa208sha256(keyLength, password, salt, opsLimit, memLimit, callback)
• MiniSodium.crypto_pwhash_scryptsalsa208sha256_ll(password, salt, opsLimit, r, p, keyLength, callback)

Box

• MiniSodium.crypto_box_keypair(callback)
• MiniSodium.crypto_box_easy(message, nonce, receiverPk, senderSk, callback)
• MiniSodium.crypto_box_open_easy(cipher, nonce, senderPk, receiverSk, callback)

Sealed box

• MiniSodium.crypto_box_seal(message, receiverPk, callback)
• MiniSodium.crypto_box_seal_open(message, receiverPk, receiverSk, callback)

Generic hashing

• MiniSodium.crypto_generichash(hashLength, message, [key], callback) Please note that key is an optional parameter. If omitted, you should put undefined or null in its place when calling this method

Testing

1. Create a Cordova/Phonegap application
2. Add the iOS and/or the Android platforms
3. Add the testing framework and bind its page as the main page of the app
4. Add the following preference in config.xml

<preference name="android-minSdkVersion" value="21"/>

5. Add this plugin
6. Add this plugin's test cases, by adding the plugin located in the tests folder

	phonegap plugin add https://github.com/LockateMe/cordova-plugin-minisodium.git#:/tests

License

MIT license