1/* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5#include "nsISupports.idl" 6interface nsIInputStream; 7interface nsIKeyObject; 8 9/** 10 * nsICryptoHMAC 11 * This interface provides HMAC signature algorithms. 12 */ 13 14[scriptable, uuid(8FEB4C7C-1641-4a7b-BC6D-1964E2099497)] 15interface nsICryptoHMAC : nsISupports 16{ 17 /** 18 * Hashing Algorithms. These values are to be used by the |init| method to 19 * indicate which hashing function to use. These values map onto the values 20 * defined in mozilla/security/nss/lib/softoken/pkcs11t.h and are switched 21 * to a CKM_*_HMAC constant. 22 */ 23 // 1 used to mean MD2. 24 const short MD5 = 2; 25 const short SHA1 = 3; 26 const short SHA256 = 4; 27 const short SHA384 = 5; 28 const short SHA512 = 6; 29 30 /** 31 * Initialize the hashing object. This method may be 32 * called multiple times with different algorithm types. 33 * 34 * @param aAlgorithm the algorithm type to be used. 35 * This value must be one of the above valid 36 * algorithm types. 37 * 38 * @param aKeyObject 39 * Object holding a key. To create the key object use for instance: 40 * var keyObject = Components.classes["@mozilla.org/security/keyobjectfactory;1"] 41 * .getService(Components.interfaces.nsIKeyObjectFactory) 42 * .keyFromString(Components.interfaces.nsIKeyObject.HMAC, rawKeyData); 43 * 44 * WARNING: This approach is not FIPS compliant. 45 * 46 * @throws NS_ERROR_INVALID_ARG if an unsupported algorithm 47 * type is passed. 48 * 49 * NOTE: This method must be called before any other method on this 50 * interface is called. 51 */ 52 [must_use] 53 void init(in unsigned long aAlgorithm, in nsIKeyObject aKeyObject); 54 55 /** 56 * @param aData a buffer to calculate the hash over 57 * 58 * @param aLen the length of the buffer |aData| 59 * 60 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called. 61 */ 62 [must_use] 63 void update([const, array, size_is(aLen)] in octet aData, in unsigned long aLen); 64 65 /** 66 * Calculates and updates a new hash based on a given data stream. 67 * 68 * @param aStream an input stream to read from. 69 * 70 * @param aLen How much to read from the given |aStream|. Passing UINT32_MAX 71 * indicates that all data available will be used to update the hash. 72 * 73 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called. 74 * 75 * @throws NS_ERROR_NOT_AVAILABLE If the requested amount of data to be 76 * calculated into the hash is not available. 77 * 78 */ 79 [must_use] 80 void updateFromStream(in nsIInputStream aStream, in unsigned long aLen); 81 82 /** 83 * Completes this HMAC object and produces the actual HMAC digest data. 84 * 85 * @param aASCII If true then the returned value is a base64 encoded string. 86 * If false, then the returned value is binary data. 87 * 88 * @return a hash of the data that was read by this object. This can 89 * be either binary data or base 64 encoded. 90 * 91 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called. 92 * 93 * NOTE: This method may be called any time after |init| 94 * is called. This call resets the object to its 95 * pre-init state. 96 */ 97 [must_use] 98 ACString finish(in boolean aASCII); 99 100 /** 101 * Reinitialize HMAC context to be reused with the same settings (the key 102 * and hash algorithm) but on a different set of data. 103 */ 104 [must_use] 105 void reset(); 106}; 107