/* * Licensed to OMTP Ltd. (OMTP) under one or more contributor license agreements. * See the NOTICE file distributed with this work for additional information regarding * copyright ownership. * * The Reference Implementation (save for such parts of the reference implementation made * available under separate terms and conditions) is made available under the terms of the * Apache License, version 2.0, subject to the condition that any "Works" and "Derivative * Works" used or distributed for commercial purposes must be and remain compliant with the * BONDI specification as promulgated by OMTP in each release. Your implementation of the * Reference Implementation (whether object or source) must maintain these conditions, and * you must notify any recipient of this condition in a conspicuous way. * * You may not use this BONDI Reference Implementation except in compliance with the License. * * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 or at * http://bondi.omtp.org/BONDI-LICENSE-2.0 */ /** * \brief 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). * * \author André Paul <andre.paul@fokus.fraunhofer.de> * \author Christian Fuhrhop <christian.fuhrhop@fokus.fraunhofer.de> * \version 1.5 */ module crypto { /** * \brief Array that contains representations of available ciphers. */ typedef sequence CipherArray; /** * \brief Array that contains representations of available hash algorithms. */ typedef sequence HashArray; /** * \brief Array that contains representations of available signature algorithms. */ typedef sequence SignatureArray; /** * \brief 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 { /** * \brief The success callback for encrypted/decrypted data. * * \param message Encrypted/decrypted data. */ void onSuccess(in DOMString message); }; /** * \brief 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 { /** * \brief The success callback for hash value calculation. * * \param hashValue The calculated hash value as a base64 string. */ void onSuccess(in DOMString hashValue); }; /** * \brief 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 { /** * \brief The success callback for signature calculation. * * \param signatureValue The calculated signature as a base64 string. */ void onSuccess(in DOMString signatureValue); }; /** * \brief 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 { /** * \brief The success callback for signature verification. * * \param verificationResult A boolean value stating whether the signature was verified. */ void onSuccess(in boolean verificationResult); }; /** * \brief The crypto error interface defines error codes that are specific to * the crypto API. */ interface CryptoAPIError : GenericError { /** * \brief Error thrown if encryption or decryption of data failed. */ const unsigned short CRYPTO_CIPHER_ERROR = 1; /** * \brief Error thrown if all parameters were individually valid, but the specific combination was not. */ const unsigned short CRYPTO_PARAMETER_COMBINATION_INVALID = 2; /** * \brief Error thrown if the passed in key is not valid for the called function or algorithm. */ const unsigned short CRYPTO_KEY_INVALID = 3; }; /** * \brief 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 * * \code * ... * \endcode */ interface CryptoManager { /** * \brief Enumeration value for using the Advanced Encryption Standard (AES) algorithm for encrypting/decrypting data. */ const short CIPHER_ALGORITHM_AES = 1; /** * \brief Enumeration value for using the Triple DES algorithm for encrypting/decrypting data. */ const short CIPHER_ALGORITHM_DES = 2; /** * \brief Enumeration value for using the RC4 Standard algorithm for encrypting/decrypting data. */ const short CIPHER_ALGORITHM_RC4 = 3; /** * \brief 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_256 = 4; /** * \brief 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_1 = 5; /** * \brief Enumeration value for using the HMAC SHA-128 algorithm for encrypting/decrypting information, used for creating Message Authentication Code. */ const short CIPHER_ALGORITHM_HMAC_SHA_128 = 6; /** * \brief Enumeration value for the signature algorithm PKCS1 (RSA-SHA1). */ const short SIGNATURE_ALGORITHM_PKCS1 = 1; /** * \brief Enumeration value for the signature algorithm DSA. */ const short SIGNATURE_ALGORITHM_DSA = 2; /** * \brief Enumeration value for the signature algorithm Elliptic Curve DSA. */ const short SIGNATURE_ALGORITHM_ECDSA = 3; /** * \brief 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_ECB = 1; /** * \brief Enumeration value for using the Cipher-block chaining (CBC) cipher mode for encrypting/decrypting data. */ const short CIPHER_MODE_CBC = 2; /** * \brief Enumeration value for using the block Counter (CTR) cipher mode for encrypting/decrypting data. */ const short CIPHER_MODE_CTR = 3; /** * \brief Enumeration value for using the Galois/Counter Mode (GCM) cipher mode for encrypting/decrypting data. */ const short CIPHER_MODE_GCM = 4; /** * \brief Enumeration value for using the CMAC mode for encrypting/decrypting for MAC handling. */ const short CIPHER_MODE_CMAC = 5; /** * \brief Enumeration value for using the CBC_CMAX mode for encrypting/decrypting for MAC handling. */ const short CIPHER_MODE_CBC_CMAC = 6; /** * \brief Enumeration value for using no padding. */ const short CIPHER_PADDING_NONE = 1; /** * \brief Enumeration value for using Public Key Cryptography Standards #5 specification padding. */ const short CIPHER_PADDING_PKCS5 = 2; /** * \brief Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 256 bits (SHA-2/256). */ const short HASH_ALGORITHM_SHA256 = 1; /** * \brief Enumeration value for the hash algorithm Secure Hash Algorithm 2 with a length of 512 bits (SHA-2/512). */ const short HASH_ALGORITHM_SHA512 = 2; /** * \brief 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. * * \param algorithm Specifies the algorithm to be used, e.g. AES-128, AES-256, RSA-1024, RSA-2048. * \param mode Specifies a specific encryption mode, e.g. CBC, ECB. * \param padding Specifies the padding to be used, e.g. PKCS#5. * \return Cipher object for encryption and decryption of data. * \throw CryptoAPIError INVALID_ARGUMENT_ERROR if given parameters are invalid. * \throw CryptoAPIError CRYPTO_PARAMETER_COMBINATION_INVALID if specific combination of parameters is invalid. */ Cipher getCipher(in short algorithm, [Optional] in short mode, [Optional] in short padding) raises(DeviceAPIError, CryptoAPIError); /** * \brief Returns a list of all available ciphers including their padding/mode permutations * */ CipherArray getAvailableCiphers(); /** * \brief This function returns a Hash object that can be used calculating the hash value for data. * * \param algorithm Specifies the hashing algorithm to be used, e.g. MD5, SHA-1, SHA2 * \return Hash object for message digest calculation. * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters or input values are invalid. */ Hash getHash(in short algorithm) raises(DeviceAPIError); /** * \brief Returns a list of all available hash algorithms. * */ HashArray getAvailableHashes(); /** * \brief This function returns a Signature object that can be used for calculating and verifying signatures. * * \param algorithm Specifies the signature algorithm to be used, e.g. DSA or PKCS1 * \return Signature object for signature creation and verification. * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters or input values are invalid. */ Signature getSignature(in short algorithm) raises(DeviceAPIError); /** * \brief Returns a list of all available signature algorithms. * */ SignatureArray getAvailableSignatures(); /** * \brief Get a key object. * * Gets a key object that can hold the private and public keys required * for crypto functions. */ Key getKey(); }; /** * \brief Cipher provides access to functions for encrypting/decrypting data. * A Cipher object can be optained by calling the getCipher function of CryptoManager * * \code * //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); * \endcode */ interface Cipher { /** * \brief The value for the cipher algorithm to be used. */ readonly attribute short cipherAlgorithmID; /** * \brief The value for the padding method to be used. */ readonly attribute short cipherPaddingID; /** * \brief The value for the cipher mode to be used. */ readonly attribute short cipherModeID; /** * \brief The commonly used short name of the algorithm, e.g., RSA or AES */ readonly attribute DOMString cipherAlgorithmShortName; /** * \brief The commonly used short name of the transformation to use, e.g., CBC or ECB */ readonly attribute DOMString cipherModeShortName; /** * \brief The commonly used short name of the padding to use, e.g., NONE or PKCS5 */ readonly attribute DOMString cipherPaddingShortName; /** * \brief Encrypts data. * * \param successCallback The callback handler that is fired * when the a encryption was successful and the encrypted data is ready for use. * \param errorCallback The callback handler that is fired if any error occurs. * \param privateKey The key for encryption. The private key element is used during ecryption. * \param message Gives the data to be encrypted * \return PendingOperation in order to cancel the async call. * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters or input values are invalid. * \throw CryptoAPIError CRYPTO_KEY_INVALID if the key is invalid * \throw CryptoAPIError CRYPTO_ENCRYPTION_FAILED if encryption process fails. */ PendingOperation encrypt(in CipherSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message, in Key privateKey) raises(DeviceAPIError, CryptoAPIError); /** * \brief Decrypts data. * * \param successCallback The callback handler that is fired * when the a decryption was successful and the decrypted data is ready for use. * \param errorCallback The callback handler that is fired if any error occurs. * \param publicKey The key for decryption. The public key element is used during ecryption. * \param message Gives the data to be decrypted. * \return PendingOperation in order to cancel the async call. * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters or input values are invalid. * \throw CryptoAPIError CRYPTO_KEY_INVALID if the key is invalid * \throw CryptoAPIError CRYPTO_DECRYPTION_FAILED if decryption process fails. */ PendingOperation decrypt(in CipherSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message, in Key publicKey) raises(DeviceAPIError, CryptoAPIError); }; /** * \brief 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 * * \code * // 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); * \endcode */ interface Hash { /** * \brief The value for the hash algorithm to be used. */ readonly attribute short hashAlgorithmID; /** * \brief The commonly used short name of the algorithm, e.g., MD5 or SHA1 */ readonly attribute DOMString hashAlgorithmShortName; /** * \brief Hash provides a function to calculate the hash value for data. * * \param successCallback The callback handler that is fired * when the hashing was successful and the hash value is available. * \param errorCallback The callback handler that is fired if any error occurs. * \param message Gives the data for which the hash value will be calculated. * \return PendingOperation in order to cancel the async call. * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters or input values are invalid. */ PendingOperation calculate(in HashSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message) raises(DeviceAPIError); }; /** * \brief Signature provides access to functions to create and verify a signature. * A Signature object can be optained by calling the getSignature function of CryptoManager * * \code * // 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); * \endcode */ interface Signature { /** * \brief The value for the signature algorithm to be used. */ readonly attribute short signatureAlgorithmID; /** * \brief The commonly used short name of the algorithm, e.g., DSA or PKCS1 */ readonly attribute DOMString signatureAlgorithmShortName; /** * \brief This provides a function to generating a signature for data. * * \param successCallback The callback handler that is fired * when the signing was successful and the signature value is available. * \param errorCallback The callback handler that is fired if any error occurs. * \param privateKey The key for signing. The privateKey part of the Key object is used. * \param message Gives the data to be signed. * \return PendingOperation in order to cancel the async call. * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters or input values are invalid. * \throw CryptoAPIError CRYPTO_KEY_INVALID if the key is invalid * \throw CryptoAPIError CRYPTO_ENCRYPTION_FAILED if encryption process during signing fails. */ PendingOperation sign(in SigningSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString message, in Key privateKey) raises(DeviceAPIError, CryptoAPIError); /** * \brief This provides a function to verify a signature.. * * \param successCallback The callback handler that is fired * when the the verification function optained a result. * \param errorCallback The callback handler that is fired if any error occurs. * \param publicKey The key for verifying (uses the public key from the key object). * \param signature Gives the signature to be verified. * \return PendingOperation in order to cancel the async call. * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters or input values are invalid. * \throw CryptoAPIError CRYPTO_KEY_INVALID if the key is invalid * \throw CryptoAPIError CRYPTO_DECRYPTION_FAILED if decryption process during verifying fails. */ PendingOperation verify(in VerificationSuccessCallback successCallback,in ErrorCallback errorCallback, in DOMString signature, in DOMString message, in Key publicKey) raises(DeviceAPIError, CryptoAPIError); }; /** * \brief 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. * * \code * * \endcode */ interface Key { /** * \brief The key length of the key. */ attribute short keyLength; /** * \brief The private exponent. */ attribute DOMString privateKey; /** * \brief The public key. */ attribute DOMString publicKey; }; };