Bondi logo

The Bondi crypto Module - Version 1.5

February 2010

Authors


Abstract

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).

Table of Contents


Summary of Methods

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

1. Introduction

2. Type Definitions

2.1. CipherArray

Array that contains representations of available ciphers.

        typedef sequence<Cipher> CipherArray;

2.2. HashArray

Array that contains representations of available hash algorithms.

        typedef sequence<Hash> HashArray;

2.3. SignatureArray

Array that contains representations of available signature algorithms.

        typedef sequence<Signature> SignatureArray;

3. Interfaces

3.1. 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);
        };

Methods

onSuccess

The success callback for encrypted/decrypted data.

Signature
void onSuccess(in DOMString message);
Parameters
  • message: Encrypted/decrypted data.

3.2. 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);
        };

Methods

onSuccess

The success callback for hash value calculation.

Signature
void onSuccess(in DOMString hashValue);
Parameters
  • hashValue: The calculated hash value as a base64 string.

3.3. 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);
        };

Methods

onSuccess

The success callback for signature calculation.

Signature
void onSuccess(in DOMString signatureValue);
Parameters
  • signatureValue: The calculated signature as a base64 string.

3.4. 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);
        };

Methods

onSuccess

The success callback for signature verification.

Signature
void onSuccess(in boolean verificationResult);
Parameters
  • verificationResult: A boolean value stating whether the signature was verified.

3.5. 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;
        };

Constants

unsigned short CRYPTO_CIPHER_ERROR

Error thrown if encryption or decryption of data failed.

unsigned short CRYPTO_PARAMETER_COMBINATION_INVALID

Error thrown if all parameters were individually valid, but the specific combination was not.

unsigned short CRYPTO_KEY_INVALID

Error thrown if the passed in key is not valid for the called function or algorithm.

3.6. 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

Code example
 ...
 

Constants

short CIPHER_ALGORITHM_AES

Enumeration value for using the Advanced Encryption Standard (AES) algorithm for encrypting/decrypting data.

short CIPHER_ALGORITHM_DES

Enumeration value for using the Triple DES algorithm for encrypting/decrypting data.

short CIPHER_ALGORITHM_RC4

Enumeration value for using the RC4 Standard algorithm for encrypting/decrypting data.

short CIPHER_ALGORITHM_HMAC_SHA_256

Enumeration value for using the HMAC SHA-256 algorithm for encrypting/decrypting information, used for creating Message Authentication Code.

short CIPHER_ALGORITHM_HMAC_SHA_1

Enumeration value for using the HMAC SHA-1 algorithm for encrypting/decrypting information, used for creating Message Authentication Code.

short CIPHER_ALGORITHM_HMAC_SHA_128

Enumeration value for using the HMAC SHA-128 algorithm for encrypting/decrypting information, used for creating Message Authentication Code.

short SIGNATURE_ALGORITHM_PKCS1

Enumeration value for the signature algorithm PKCS1 (RSA-SHA1).

short SIGNATURE_ALGORITHM_DSA

Enumeration value for the signature algorithm DSA.

short SIGNATURE_ALGORITHM_ECDSA

Enumeration value for the signature algorithm Elliptic Curve DSA.

short CIPHER_MODE_ECB

Enumeration 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_CBC

Enumeration value for using the Cipher-block chaining (CBC) cipher mode for encrypting/decrypting data.

short CIPHER_MODE_CTR

Enumeration value for using the block Counter (CTR) cipher mode for encrypting/decrypting data.

short CIPHER_MODE_GCM

Enumeration value for using the Galois/Counter Mode (GCM) cipher mode for encrypting/decrypting data.

short CIPHER_MODE_CMAC

Enumeration value for using the CMAC mode for encrypting/decrypting for MAC handling.

short CIPHER_MODE_CBC_CMAC

Enumeration value for using the CBC_CMAX mode for encrypting/decrypting for MAC handling.

short CIPHER_PADDING_NONE

Enumeration value for using no padding.

short CIPHER_PADDING_PKCS5

Enumeration value for using Public Key Cryptography Standards #5 specification padding.

short HASH_ALGORITHM_SHA256

Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 256 bits (SHA-2/256).

short HASH_ALGORITHM_SHA512

Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 512 bits (SHA-2/512).

Methods

getCipher

This function returns a Cipher object that can be used for encryption and decryption of data.

Signature
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.

Parameters
  • algorithm: Specifies the algorithm to be used, e.g. AES-128, AES-256, RSA-1024, RSA-2048.
  • mode: Specifies a specific encryption mode, e.g. CBC, ECB.
  • padding: Specifies the padding to be used, e.g. PKCS#5.
Return value
Cipher object for encryption and decryption of data.
Exceptions
  • DeviceAPIError:
  • CryptoAPIError:

    CRYPTO_PARAMETER_COMBINATION_INVALID if specific combination of parameters is invalid.

    INVALID_ARGUMENT_ERROR if given parameters are invalid.

getAvailableCiphers

Returns a list of all available ciphers including their padding/mode permutations

Signature
CipherArray getAvailableCiphers();
getHash

This function returns a Hash object that can be used calculating the hash value for data.

Signature
Hash getHash(in short algorithm);
Parameters
  • algorithm: Specifies the hashing algorithm to be used, e.g. MD5, SHA-1, SHA2
Return value
Hash object for message digest calculation.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

getAvailableHashes

Returns a list of all available hash algorithms.

Signature
HashArray getAvailableHashes();
getSignature

This function returns a Signature object that can be used for calculating and verifying signatures.

Signature
Signature getSignature(in short algorithm);
Parameters
  • algorithm: Specifies the signature algorithm to be used, e.g. DSA or PKCS1
Return value
Signature object for signature creation and verification.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

getAvailableSignatures

Returns a list of all available signature algorithms.

Signature
SignatureArray getAvailableSignatures();
getKey

Get a key object.

Signature
Key getKey();

Gets a key object that can hold the private and public keys required for crypto functions.

3.7. 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);                 
        };
Code example
 //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);
 

Attributes

readonly short cipherAlgorithmID

The value for the cipher algorithm to be used.

readonly short cipherPaddingID

The value for the padding method to be used.

readonly short cipherModeID

The value for the cipher mode to be used.

readonly DOMString cipherAlgorithmShortName

The commonly used short name of the algorithm, e.g., RSA or AES

readonly DOMString cipherModeShortName

The commonly used short name of the transformation to use, e.g., CBC or ECB

readonly DOMString cipherPaddingShortName

The commonly used short name of the padding to use, e.g., NONE or PKCS5

Methods

encrypt

Encrypts data.

Signature
PendingOperation encrypt(in CipherSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message, in Key privateKey);
Parameters
  • successCallback: The callback handler that is fired when the a encryption was successful and the encrypted data is ready for use.
  • errorCallback: The callback handler that is fired if any error occurs.
  • message: Gives the data to be encrypted
  • privateKey: The key for encryption. The private key element is used during ecryption.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

  • CryptoAPIError:

    CRYPTO_ENCRYPTION_FAILED if encryption process fails.

    CRYPTO_KEY_INVALID if the key is invalid

decrypt

Decrypts data.

Signature
PendingOperation decrypt(in CipherSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message, in Key publicKey);
Parameters
  • successCallback: The callback handler that is fired when the a decryption was successful and the decrypted data is ready for use.
  • errorCallback: The callback handler that is fired if any error occurs.
  • message: Gives the data to be decrypted.
  • publicKey: The key for decryption. The public key element is used during ecryption.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

  • CryptoAPIError:

    CRYPTO_DECRYPTION_FAILED if decryption process fails.

    CRYPTO_KEY_INVALID if the key is invalid

3.8. 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);
        };
Code example
 // 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);
 

Attributes

readonly short hashAlgorithmID

The value for the hash algorithm to be used.

readonly DOMString hashAlgorithmShortName

The commonly used short name of the algorithm, e.g., MD5 or SHA1

Methods

calculate

Hash provides a function to calculate the hash value for data.

Signature
PendingOperation calculate(in HashSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message);
Parameters
  • successCallback: The callback handler that is fired when the hashing was successful and the hash value is available.
  • errorCallback: The callback handler that is fired if any error occurs.
  • message: Gives the data for which the hash value will be calculated.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

3.9. 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);
        };
Code example
 // 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);
 

Attributes

readonly short signatureAlgorithmID

The value for the signature algorithm to be used.

readonly DOMString signatureAlgorithmShortName

The commonly used short name of the algorithm, e.g., DSA or PKCS1

Methods

sign

This provides a function to generating a signature for data.

Signature
PendingOperation sign(in SigningSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString message, in Key privateKey);
Parameters
  • successCallback: The callback handler that is fired when the signing was successful and the signature value is available.
  • errorCallback: The callback handler that is fired if any error occurs.
  • message: Gives the data to be signed.
  • privateKey: The key for signing. The privateKey part of the Key object is used.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

  • CryptoAPIError:

    CRYPTO_ENCRYPTION_FAILED if encryption process during signing fails.

    CRYPTO_KEY_INVALID if the key is invalid

verify

This provides a function to verify a signature..

Signature
PendingOperation verify(in VerificationSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString signature, in DOMString message, in Key publicKey);
Parameters
  • successCallback: The callback handler that is fired when the the verification function optained a result.
  • errorCallback: The callback handler that is fired if any error occurs.
  • signature: Gives the signature to be verified.
  • message:
  • publicKey: The key for verifying (uses the public key from the key object).
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

  • CryptoAPIError:

    CRYPTO_DECRYPTION_FAILED if decryption process during verifying fails.

    CRYPTO_KEY_INVALID if the key is invalid

3.10. 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;          
                
        };
Code example

 

Attributes

short keyLength

The key length of the key.

DOMString privateKey

The private exponent.

DOMString publicKey

The public key.