
© 2009-2010 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.
The crypto API provides cryptographic functions like hashing, signature verification, encrypting and decrypting to allow exchanging data between a server and a BONDI client securely (encrypting/decrypting), protecting data integrity (one-way hashing) and verifying the authentity of data (digital signatures).
CipherArray
HashArray
SignatureArray
CipherSuccessCallback
HashSuccessCallback
SigningSuccessCallback
VerificationSuccessCallback
CryptoAPIError
CryptoManager
Cipher
Hash
Signature
Key
| Interface | Method |
|---|---|
| CipherSuccessCallback | void onSuccess(DOMString message) |
| HashSuccessCallback | void onSuccess(DOMString hashValue) |
| SigningSuccessCallback | void onSuccess(DOMString signatureValue) |
| VerificationSuccessCallback | void onSuccess(boolean verificationResult) |
| CryptoAPIError | |
| CryptoManager | Cipher getCipher(short algorithm, short mode, short padding) CipherArray getAvailableCiphers() Hash getHash(short algorithm) HashArray getAvailableHashes() Signature getSignature(short algorithm) SignatureArray getAvailableSignatures() Key getKey() |
| Cipher | PendingOperation encrypt(CipherSuccessCallback successCallback, ErrorCallback errorCallback, DOMString message, Key privateKey) PendingOperation decrypt(CipherSuccessCallback successCallback, ErrorCallback errorCallback, DOMString message, Key publicKey) |
| Hash | PendingOperation calculate(HashSuccessCallback successCallback, ErrorCallback errorCallback, DOMString message) |
| Signature | PendingOperation sign(SigningSuccessCallback successCallback, ErrorCallback errorCallback, DOMString message, Key privateKey) PendingOperation verify(VerificationSuccessCallback successCallback, ErrorCallback errorCallback, DOMString signature, DOMString message, Key publicKey) |
| Key |
CipherArray
Array that contains representations of available ciphers.
typedef sequence<Cipher> CipherArray;
HashArray
Array that contains representations of available hash algorithms.
typedef sequence<Hash> HashArray;
SignatureArray
Array that contains representations of available signature algorithms.
typedef sequence<Signature> SignatureArray;
CipherSuccessCallback
The encryption/decryption success callback. On successful encrypting or decrypting, this function will be called with the encrypted or decypted data.
[Callback=FunctionOnly, NoInterfaceObject] interface CipherSuccessCallback {
void onSuccess(in DOMString message);
};
onSuccessThe success callback for encrypted/decrypted data.
void onSuccess(in DOMString message);
HashSuccessCallback
The hash success callback. On successful calculation of a hash value, this function will be called with the resulting value as a base64 string
[Callback=FunctionOnly, NoInterfaceObject] interface HashSuccessCallback {
void onSuccess(in DOMString hashValue);
};
onSuccessThe success callback for hash value calculation.
void onSuccess(in DOMString hashValue);
SigningSuccessCallback
The signing success callback. On successful calculation of a signature, this function will be called with the resulting signature value as a base64 string.
[Callback=FunctionOnly, NoInterfaceObject] interface SigningSuccessCallback {
void onSuccess(in DOMString signatureValue);
};
onSuccessThe success callback for signature calculation.
void onSuccess(in DOMString signatureValue);
VerificationSuccessCallback
The verification success callback. On successful verification of a signature, this function will be called with the verification value as a boolean value. Note that the calling of this function does not, in itself, mean that the signature was verified, but only that the verification test was successfully performed. Whether the actual signature was verified is determined by the value of the verificationResult parameter.
[Callback=FunctionOnly, NoInterfaceObject] interface VerificationSuccessCallback {
void onSuccess(in boolean verificationResult);
};
onSuccessThe success callback for signature verification.
void onSuccess(in boolean verificationResult);
CryptoAPIError
The crypto error interface defines error codes that are specific to the crypto API.
interface CryptoAPIError : GenericError {
const unsigned short CRYPTO_CIPHER_ERROR = 1;
const unsigned short CRYPTO_PARAMETER_COMBINATION_INVALID = 2;
const unsigned short CRYPTO_KEY_INVALID = 3;
};
unsigned short CRYPTO_CIPHER_ERRORError thrown if encryption or decryption of data failed.
unsigned short CRYPTO_PARAMETER_COMBINATION_INVALIDError thrown if all parameters were individually valid, but the specific combination was not.
unsigned short CRYPTO_KEY_INVALIDError thrown if the passed in key is not valid for the called function or algorithm.
CryptoManager
Crypto Manager provides access to the crypto API functions.
interface CryptoManager {
const short CIPHER_ALGORITHM_AES = 1;
const short CIPHER_ALGORITHM_DES = 2;
const short CIPHER_ALGORITHM_RC4 = 3;
const short CIPHER_ALGORITHM_HMAC_SHA_256 = 4;
const short CIPHER_ALGORITHM_HMAC_SHA_1 = 5;
const short CIPHER_ALGORITHM_HMAC_SHA_128 = 6;
const short SIGNATURE_ALGORITHM_PKCS1 = 1;
const short SIGNATURE_ALGORITHM_DSA = 2;
const short SIGNATURE_ALGORITHM_ECDSA = 3;
const short CIPHER_MODE_ECB = 1;
const short CIPHER_MODE_CBC = 2;
const short CIPHER_MODE_CTR = 3;
const short CIPHER_MODE_GCM = 4;
const short CIPHER_MODE_CMAC = 5;
const short CIPHER_MODE_CBC_CMAC = 6;
const short CIPHER_PADDING_NONE = 1;
const short CIPHER_PADDING_PKCS5 = 2;
const short HASH_ALGORITHM_SHA256 = 1;
const short HASH_ALGORITHM_SHA512 = 2;
Cipher getCipher(in short algorithm, [Optional] in short mode, [Optional] in short padding)
raises(DeviceAPIError, CryptoAPIError);
CipherArray getAvailableCiphers();
Hash getHash(in short algorithm)
raises(DeviceAPIError);
HashArray getAvailableHashes();
Signature getSignature(in short algorithm)
raises(DeviceAPIError);
SignatureArray getAvailableSignatures();
Key getKey();
};
The CryptoManager provides access to the APIs cipher, hashing, and signature handling functionalities while providing constants for selecting mandatory algorithms as well as padding and cipher modes.
The following algorithms and key length combinations are mandatory: AES 128 bits AES 256 bits HMAC SHA 256 (used for MAC handling)
The following encryption modes are mandatory: ECB CBC GCM CMAC (for MAC handling)
The following hash algorithm / key length combination is mandatory: SHA-256
The following signature algorithm / key length combination is mandatory: RSA PKCS #1 2048 bits
...
short CIPHER_ALGORITHM_AESEnumeration value for using the Advanced Encryption Standard (AES) algorithm for encrypting/decrypting data.
short CIPHER_ALGORITHM_DESEnumeration value for using the Triple DES algorithm for encrypting/decrypting data.
short CIPHER_ALGORITHM_RC4Enumeration value for using the RC4 Standard algorithm for encrypting/decrypting data.
short CIPHER_ALGORITHM_HMAC_SHA_256Enumeration value for using the HMAC SHA-256 algorithm for encrypting/decrypting information, used for creating Message Authentication Code.
short CIPHER_ALGORITHM_HMAC_SHA_1Enumeration value for using the HMAC SHA-1 algorithm for encrypting/decrypting information, used for creating Message Authentication Code.
short CIPHER_ALGORITHM_HMAC_SHA_128Enumeration value for using the HMAC SHA-128 algorithm for encrypting/decrypting information, used for creating Message Authentication Code.
short SIGNATURE_ALGORITHM_PKCS1Enumeration value for the signature algorithm PKCS1 (RSA-SHA1).
short SIGNATURE_ALGORITHM_DSAEnumeration value for the signature algorithm DSA.
short SIGNATURE_ALGORITHM_ECDSAEnumeration value for the signature algorithm Elliptic Curve DSA.
short CIPHER_MODE_ECBEnumeration value for using the Electronic codebook (ECB) cipher mode for encrypting/decrypting data. NOTE: We need to decide whether we want to restrict this to the most common modes or whether we want to allow other modes such as PCBC, CFB, OFB,CTR.
short CIPHER_MODE_CBCEnumeration value for using the Cipher-block chaining (CBC) cipher mode for encrypting/decrypting data.
short CIPHER_MODE_CTREnumeration value for using the block Counter (CTR) cipher mode for encrypting/decrypting data.
short CIPHER_MODE_GCMEnumeration value for using the Galois/Counter Mode (GCM) cipher mode for encrypting/decrypting data.
short CIPHER_MODE_CMACEnumeration value for using the CMAC mode for encrypting/decrypting for MAC handling.
short CIPHER_MODE_CBC_CMACEnumeration value for using the CBC_CMAX mode for encrypting/decrypting for MAC handling.
short CIPHER_PADDING_NONEEnumeration value for using no padding.
short CIPHER_PADDING_PKCS5Enumeration value for using Public Key Cryptography Standards #5 specification padding.
short HASH_ALGORITHM_SHA256Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 256 bits (SHA-2/256).
short HASH_ALGORITHM_SHA512Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 512 bits (SHA-2/512).
getCipherThis function returns a Cipher object that can be used for encryption and decryption of data.
Cipher getCipher(in short algorithm, in short mode, in short padding);
If mode and padding are not given ECB and PKCS#5 is used as default.
CRYPTO_PARAMETER_COMBINATION_INVALID if specific combination of parameters is invalid.
INVALID_ARGUMENT_ERROR if given parameters are invalid.
getAvailableCiphersReturns a list of all available ciphers including their padding/mode permutations
CipherArray getAvailableCiphers();
getHashThis function returns a Hash object that can be used calculating the hash value for data.
Hash getHash(in short algorithm);
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
getAvailableHashesReturns a list of all available hash algorithms.
HashArray getAvailableHashes();
getSignatureThis function returns a Signature object that can be used for calculating and verifying signatures.
Signature getSignature(in short algorithm);
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
getAvailableSignaturesReturns a list of all available signature algorithms.
SignatureArray getAvailableSignatures();
getKeyGet a key object.
Key getKey();
Gets a key object that can hold the private and public keys required for crypto functions.
Cipher
Cipher provides access to functions for encrypting/decrypting data. A Cipher object can be optained by calling the getCipher function of CryptoManager
interface Cipher {
readonly attribute short cipherAlgorithmID;
readonly attribute short cipherPaddingID;
readonly attribute short cipherModeID;
readonly attribute DOMString cipherAlgorithmShortName;
readonly attribute DOMString cipherModeShortName;
readonly attribute DOMString cipherPaddingShortName;
PendingOperation encrypt(in CipherSuccessCallback successCallback,in ErrorCallback errorCallback,
in DOMString message, in Key privateKey)
raises(DeviceAPIError, CryptoAPIError);
PendingOperation decrypt(in CipherSuccessCallback successCallback,in ErrorCallback errorCallback,
in DOMString message, in Key publicKey)
raises(DeviceAPIError, CryptoAPIError);
};
//Use the crypto API to encrypt and decrypt a string.
// We're using 128 bit AES in Electronic Cookbook Mode (ECB) without padding.
var clearText="This is a text I don't want anyone to read during transmission.";
var myKey=bondi.crypto.getCipher.getKey();
myKey.privateKey = "password";
var myCipherObject;
// this function handles the error case
function onError(error) {
alert(error.code);
}
// this function is called on successful decryption
function onDecryptionSuccess(decryptedText) {
alert("Decrypted text is "+decryptedText+" original text was "+clearText+" both should be identical.");
}
// this function is called on successful encryption
function onEncryptionSuccess(encryptedText) {
alert("Encrypted text is: " + encryptedText);
// decrypt it
myCipherObject.decrypt(onDecryptionSuccess, onError, cipherText, myKey);
}
var useAlgorithm = bondi.crypto.CIPHER_ALGORITHM_AES;
var useMode = bondi.crypto.CIPHER_MODE_ECB;
var usePadding = bondi.crypto.CIPHER_PADDING_NONE;
myCipherObject=bondi.crypto.getCipher(useAlgorithm, useMode, usePadding);
// encrypt the clear text
myCipherObject.encrypt(onEncryptionSuccess, onError, clearText, myKey);
readonly
short cipherAlgorithmIDThe value for the cipher algorithm to be used.
readonly
short cipherPaddingIDThe value for the padding method to be used.
readonly
short cipherModeIDThe value for the cipher mode to be used.
readonly
DOMString cipherAlgorithmShortNameThe commonly used short name of the algorithm, e.g., RSA or AES
readonly
DOMString cipherModeShortNameThe commonly used short name of the transformation to use, e.g., CBC or ECB
readonly
DOMString cipherPaddingShortNameThe commonly used short name of the padding to use, e.g., NONE or PKCS5
encryptEncrypts data.
PendingOperation encrypt(in CipherSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message, in Key privateKey);
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
CRYPTO_ENCRYPTION_FAILED if encryption process fails.
CRYPTO_KEY_INVALID if the key is invalid
decryptDecrypts data.
PendingOperation decrypt(in CipherSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message, in Key publicKey);
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
CRYPTO_DECRYPTION_FAILED if decryption process fails.
CRYPTO_KEY_INVALID if the key is invalid
Hash
Hash provides access to a function to calculate a hash value for arbitrary-sized data for message digesting. A Hash object can be optained by calling the getHash function of CryptoManager
interface Hash {
readonly attribute short hashAlgorithmID;
readonly attribute DOMString hashAlgorithmShortName;
PendingOperation calculate(in HashSuccessCallback successCallback,in ErrorCallback errorCallback,
in DOMString message)
raises(DeviceAPIError);
};
// Use the crypto API to hash data in a string.
// We're using 256 bit SHA 2 hashing in this example.
var hashText="This is the text that I want to know the hash value of.";
// this function handles the error case
function onError(error) {
alert(error.code);
}
// this function is called on successful hashing
function onHashSuccess(hashValue) {
alert("Hash value for text "+hashText+" is "+hashValue);
}
var useHashAlgorithm=bondi.crypto.HASH_ALGORITHM_SHA256;
var myHashObject=bondi.crypto.getHash(useHashAlgorithm);
// calculate hash value for the text
myHashObject.calculate(onHashSuccess, onError, hashText);
readonly
short hashAlgorithmIDThe value for the hash algorithm to be used.
readonly
DOMString hashAlgorithmShortNameThe commonly used short name of the algorithm, e.g., MD5 or SHA1
calculateHash provides a function to calculate the hash value for data.
PendingOperation calculate(in HashSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message);
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
Signature
Signature provides access to functions to create and verify a signature. A Signature object can be optained by calling the getSignature function of CryptoManager
interface Signature {
readonly attribute short signatureAlgorithmID;
readonly attribute DOMString signatureAlgorithmShortName;
PendingOperation sign(in SigningSuccessCallback successCallback,in ErrorCallback errorCallback,
in DOMString message, in Key privateKey)
raises(DeviceAPIError, CryptoAPIError);
PendingOperation verify(in VerificationSuccessCallback successCallback,in ErrorCallback errorCallback,
in DOMString signature, in DOMString message, in Key publicKey)
raises(DeviceAPIError, CryptoAPIError);
};
// Use the crypto API to sign a string and verify it afterwards.
// We're using DSA with a 2048 bit key as the signature algorithm
var signText="This is the text that I want to sign.";
var myDSAKey ... // for the setting of a key, please refer to the key interface
var mySignatureObject;
// this function handles the error case
function onError(error) {
alert(error.code);
}
// this function is called on completion of signature verification function
function onVerificationSuccess(verificationResult) {
if(verificationResult)alert("Signature for "+signText+" has been verified.");
else alert("Signature verification for "+signText+" failed!");
}
// this function is called on successful signing
function onSignatureSuccess(signatureValue) {
alert("Signature value for text "+signText+" is "+signatureValue);
// the verification uses the public key from the Key object
mySignatureObject.verify(onVerificationSuccess, onError, signatureValue, signText, myDSAKey);
}
var useSignatureAlgorithm=bondi.crypto.SIGNATURE_ALGORITHM_DSA;
mySignatureObject=bondi.crypto.getSignature(useSignatureAlgorithm);
// calculate signature value for the text - thus uses the private key from the Key object
mySignatureObject.sign(onSignatureSuccess, onError, signText, myDSAKey);
readonly
short signatureAlgorithmIDThe value for the signature algorithm to be used.
readonly
DOMString signatureAlgorithmShortNameThe commonly used short name of the algorithm, e.g., DSA or PKCS1
signThis provides a function to generating a signature for data.
PendingOperation sign(in SigningSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message, in Key privateKey);
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
CRYPTO_ENCRYPTION_FAILED if encryption process during signing fails.
CRYPTO_KEY_INVALID if the key is invalid
verifyThis provides a function to verify a signature..
PendingOperation verify(in VerificationSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString signature, in DOMString message, in Key publicKey);
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
CRYPTO_DECRYPTION_FAILED if decryption process during verifying fails.
CRYPTO_KEY_INVALID if the key is invalid
Key
The Key interface represents a key related to a specific algorithm to be used for encryption/decryption and signing/verification. The public and private keys are represented as stings in X509 format.
interface Key {
attribute short keyLength;
attribute DOMString privateKey;
attribute DOMString publicKey;
};
short keyLengthThe key length of the key.
DOMString privateKeyThe private exponent.
DOMString publicKeyThe public key.