module crypto { typedef sequence<Cipher> CipherArray; typedef sequence<Hash> HashArray; typedef sequence<Signature> SignatureArray; [Callback=FunctionOnly, NoInterfaceObject] interface CipherSuccessCallback { void onSuccess(in DOMString message); }; [Callback=FunctionOnly, NoInterfaceObject] interface HashSuccessCallback { void onSuccess(in DOMString hashValue); }; [Callback=FunctionOnly, NoInterfaceObject] interface SigningSuccessCallback { void onSuccess(in DOMString signatureValue); }; [Callback=FunctionOnly, NoInterfaceObject] interface VerificationSuccessCallback { void onSuccess(in boolean verificationResult); }; 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; }; 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(); }; 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); }; interface Hash { readonly attribute short hashAlgorithmID; readonly attribute DOMString hashAlgorithmShortName; PendingOperation calculate(in HashSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message) raises(DeviceAPIError); }; 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); }; interface Key { attribute short keyLength; attribute DOMString privateKey; attribute DOMString publicKey; }; }; 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). André Paul <andre.paul@fokus.fraunhofer.de> Christian Fuhrhop <christian.fuhrhop@fokus.fraunhofer.de> 1.5 typedef sequence<Cipher> CipherArray; Array that contains representations of available ciphers. typedef sequence<Hash> HashArray; Array that contains representations of available hash algorithms. typedef sequence<Signature> SignatureArray; Array that contains representations of available signature algorithms. [Callback=FunctionOnly, NoInterfaceObject] interface CipherSuccessCallback { void onSuccess(in DOMString message); }; The encryption/decryption success callback. On successful encrypting or decrypting, this function will be called with the encrypted or decypted data. void onSuccess(in DOMString message); The success callback for encrypted/decrypted data.

Encrypted/decrypted data.

[Callback=FunctionOnly, NoInterfaceObject] interface HashSuccessCallback { void onSuccess(in DOMString hashValue); }; The hash success callback. On successful calculation of a hash value, this function will be called with the resulting value as a base64 string void onSuccess(in DOMString hashValue); The success callback for hash value calculation.

The calculated hash value as a base64 string.

[Callback=FunctionOnly, NoInterfaceObject] interface SigningSuccessCallback { void onSuccess(in DOMString signatureValue); }; The signing success callback. On successful calculation of a signature, this function will be called with the resulting signature value as a base64 string. void onSuccess(in DOMString signatureValue); The success callback for signature calculation.

The calculated signature as a base64 string.

[Callback=FunctionOnly, NoInterfaceObject] interface VerificationSuccessCallback { void onSuccess(in boolean verificationResult); }; 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. void onSuccess(in boolean verificationResult); The success callback for signature verification.

A boolean value stating whether the signature was verified.

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; }; The crypto error interface defines error codes that are specific to the crypto API. const unsigned short CRYPTO_CIPHER_ERROR = 1; Error thrown if encryption or decryption of data failed. const unsigned short CRYPTO_PARAMETER_COMBINATION_INVALID = 2; Error thrown if all parameters were individually valid, but the specific combination was not. const unsigned short CRYPTO_KEY_INVALID = 3; Error thrown if the passed in key is not valid for the called function or algorithm. 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(); }; Crypto Manager provides access to the crypto API functions.

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

...

const short CIPHER_ALGORITHM_AES = 1; Enumeration value for using the Advanced Encryption Standard (AES) algorithm for encrypting/decrypting data. const short CIPHER_ALGORITHM_DES = 2; Enumeration value for using the Triple DES algorithm for encrypting/decrypting data. const short CIPHER_ALGORITHM_RC4 = 3; Enumeration value for using the RC4 Standard algorithm for encrypting/decrypting data. const short CIPHER_ALGORITHM_HMAC_SHA_256 = 4; Enumeration value for using the HMAC SHA-256 algorithm for encrypting/decrypting information, used for creating Message Authentication Code. const short CIPHER_ALGORITHM_HMAC_SHA_1 = 5; Enumeration value for using the HMAC SHA-1 algorithm for encrypting/decrypting information, used for creating Message Authentication Code. const short CIPHER_ALGORITHM_HMAC_SHA_128 = 6; Enumeration value for using the HMAC SHA-128 algorithm for encrypting/decrypting information, used for creating Message Authentication Code. const short SIGNATURE_ALGORITHM_PKCS1 = 1; Enumeration value for the signature algorithm PKCS1 (RSA-SHA1). const short SIGNATURE_ALGORITHM_DSA = 2; Enumeration value for the signature algorithm DSA. const short SIGNATURE_ALGORITHM_ECDSA = 3; Enumeration value for the signature algorithm Elliptic Curve DSA. const short CIPHER_MODE_ECB = 1; 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. const short CIPHER_MODE_CBC = 2; Enumeration value for using the Cipher-block chaining (CBC) cipher mode for encrypting/decrypting data. const short CIPHER_MODE_CTR = 3; Enumeration value for using the block Counter (CTR) cipher mode for encrypting/decrypting data. const short CIPHER_MODE_GCM = 4; Enumeration value for using the Galois/Counter Mode (GCM) cipher mode for encrypting/decrypting data. const short CIPHER_MODE_CMAC = 5; Enumeration value for using the CMAC mode for encrypting/decrypting for MAC handling. const short CIPHER_MODE_CBC_CMAC = 6; Enumeration value for using the CBC_CMAX mode for encrypting/decrypting for MAC handling. const short CIPHER_PADDING_NONE = 1; Enumeration value for using no padding. const short CIPHER_PADDING_PKCS5 = 2; Enumeration value for using Public Key Cryptography Standards #5 specification padding. const short HASH_ALGORITHM_SHA256 = 1; Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 256 bits (SHA-2/256). const short HASH_ALGORITHM_SHA512 = 2; Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 512 bits (SHA-2/512). Cipher getCipher(in short algorithm, [Optional] in short mode, [Optional] in short padding) raises(DeviceAPIError, CryptoAPIError); This function returns a Cipher object that can be used for encryption and decryption of data.

If mode and padding are not given ECB and PKCS#5 is used as default.

Cipher object for encryption and decryption of data.

Specifies the algorithm to be used, e.g. AES-128, AES-256, RSA-1024, RSA-2048.

Specifies a specific encryption mode, e.g. CBC, ECB.

Specifies the padding to be used, e.g. PKCS#5.

CRYPTO_PARAMETER_COMBINATION_INVALID if specific combination of parameters is invalid.

INVALID_ARGUMENT_ERROR if given parameters are invalid.

CipherArray getAvailableCiphers(); Returns a list of all available ciphers including their padding/mode permutations Hash getHash(in short algorithm) raises(DeviceAPIError); This function returns a Hash object that can be used calculating the hash value for data.

Hash object for message digest calculation.

Specifies the hashing algorithm to be used, e.g. MD5, SHA-1, SHA2

INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

HashArray getAvailableHashes(); Returns a list of all available hash algorithms. Signature getSignature(in short algorithm) raises(DeviceAPIError); This function returns a Signature object that can be used for calculating and verifying signatures.

Signature object for signature creation and verification.

Specifies the signature algorithm to be used, e.g. DSA or PKCS1

INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

SignatureArray getAvailableSignatures(); Returns a list of all available signature algorithms. Key getKey(); Get a key object.

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

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); }; Cipher provides access to functions for encrypting/decrypting data. A Cipher object can be optained by calling the getCipher function of CryptoManager


 //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 attribute short cipherAlgorithmID; The value for the cipher algorithm to be used. readonly attribute short cipherPaddingID; The value for the padding method to be used. readonly attribute short cipherModeID; The value for the cipher mode to be used. readonly attribute DOMString cipherAlgorithmShortName; The commonly used short name of the algorithm, e.g., RSA or AES readonly attribute DOMString cipherModeShortName; The commonly used short name of the transformation to use, e.g., CBC or ECB readonly attribute DOMString cipherPaddingShortName; The commonly used short name of the padding to use, e.g., NONE or PKCS5 PendingOperation encrypt(in CipherSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message, in Key privateKey) raises(DeviceAPIError, CryptoAPIError); Encrypts data.

PendingOperation in order to cancel the async call.

The callback handler that is fired when the a encryption was successful and the encrypted data is ready for use.

The callback handler that is fired if any error occurs.

Gives the data to be encrypted

The key for encryption. The private key element is used during ecryption.

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

PendingOperation decrypt(in CipherSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message, in Key publicKey) raises(DeviceAPIError, CryptoAPIError); Decrypts data.

PendingOperation in order to cancel the async call.

The callback handler that is fired when the a decryption was successful and the decrypted data is ready for use.

The callback handler that is fired if any error occurs.

Gives the data to be decrypted.

The key for decryption. The public key element is used during ecryption.

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

interface Hash { readonly attribute short hashAlgorithmID; readonly attribute DOMString hashAlgorithmShortName; PendingOperation calculate(in HashSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message) raises(DeviceAPIError); }; 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


 // 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 attribute short hashAlgorithmID; The value for the hash algorithm to be used. readonly attribute DOMString hashAlgorithmShortName; The commonly used short name of the algorithm, e.g., MD5 or SHA1 PendingOperation calculate(in HashSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message) raises(DeviceAPIError); Hash provides a function to calculate the hash value for data.

PendingOperation in order to cancel the async call.

The callback handler that is fired when the hashing was successful and the hash value is available.

The callback handler that is fired if any error occurs.

Gives the data for which the hash value will be calculated.

INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.

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); }; Signature provides access to functions to create and verify a signature. A Signature object can be optained by calling the getSignature function of CryptoManager


 // 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 attribute short signatureAlgorithmID; The value for the signature algorithm to be used. readonly attribute DOMString signatureAlgorithmShortName; The commonly used short name of the algorithm, e.g., DSA or PKCS1 PendingOperation sign(in SigningSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message, in Key privateKey) raises(DeviceAPIError, CryptoAPIError); This provides a function to generating a signature for data.

PendingOperation in order to cancel the async call.

The callback handler that is fired when the signing was successful and the signature value is available.

The callback handler that is fired if any error occurs.

Gives the data to be signed.

The key for signing. The privateKey part of the Key object is used.

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

PendingOperation verify(in VerificationSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString signature, in DOMString message, in Key publicKey) raises(DeviceAPIError, CryptoAPIError); This provides a function to verify a signature..

PendingOperation in order to cancel the async call.

The callback handler that is fired when the the verification function optained a result.

The callback handler that is fired if any error occurs.

Gives the signature to be verified.

The key for verifying (uses the public key from the key object).

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

interface Key { attribute short keyLength; attribute DOMString privateKey; attribute DOMString publicKey; }; 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.

attribute short keyLength; The key length of the key. attribute DOMString privateKey; The private exponent. attribute DOMString publicKey; The public key.