nsICryptoHMAC

This interface provides HMAC signature algorithms.
1.0
66
Introduced
Gecko 1.9
Inherits from: nsISupports Last changed in Gecko 1.9 (Firefox 3)

Method overview

ACString finish(in PRBool aASCII);
void init(in unsigned long aAlgorithm, in nsIKeyObject aKeyObject);
void reset();
void update([const, array, size_is(aLen)] in octet aData, in unsigned long aLen);
void updateFromStream(in nsIInputStream aStream, in unsigned long aLen);

Constants

Hashing Algorithms. These values are to be used by the init() method to indicate which hashing function to use. These values map onto the values defined in mozilla/security/nss/lib/softoken/pkcs11t.h and are switched to CKM_*_HMAC constant.

Constant Value Description
MD2 1 Message Digest Algorithm 2
MD5 2 Message-Digest algorithm 5
SHA1 3 Secure Hash Algorithm 1
SHA256 4 Secure Hash Algorithm 256
SHA384 5 Secure Hash Algorithm 384
SHA512 6 Secure Hash Algorithm 512

Methods

finish()

Completes this HMAC object and produces the actual HMAC diegest data.

Note: This method may be called any time after init() is called. This call resets the object to its pre-init state.

ACString finish(
  in PRBool aASCII
);
Parameters
aASCII
If true then the returned value is a base-64 encoded string. if false, then the returned value is binary data.
Return value

A hash of the data that was read by this object. This can be either binary data or base 64 encoded.

Exceptions thrown
NS_ERROR_NOT_INITIALIZED
If init() has not been called.

init()

Initialize the hashing object. This method may be called multiple times with different algorithm types.

Warning: This approach is not FIPS compliant.

Note: This method must be called before any other method on this interface is called.

void init(
  in unsigned long aAlgorithm,
  in nsIKeyObject aKeyObject
);
Parameters
aAlgorithm
The algorithm type to be used. This value must be one of the above valid algorithm types.
aKeyObject
Object holding a key. To create the key object use for instance: 
var keyObject = Components.classes["@mozilla.org/security/keyobjectfactory;1"]
                .getService(Components.interfaces.nsIKeyObjectFactory)
                .keyFromString(Components.interfaces.nsIKeyObject.HMAC, rawKeyData);
Exceptions thrown
NS_ERROR_INVALID_ARG
If an unsupported algorithm type is passed.

reset()

Reinitialize HMAC context to be reused with the same settings (the key and hash algorithm) but on different set of data.

void reset();
Parameters

None.

update()

void update(
  [const, array, size_is(aLen)] in octet aData,
  in unsigned long aLen
);
Parameters
aData
A buffer to calculate the hash over.
aLen
The length of the buffer aData.
Exceptions thrown
NS_ERROR_NOT_INITIALIZED
If init() has not been called.

updateFromStream()

Calculates and updates a new hash based on a given data stream.

void updateFromStream(
  in nsIInputStream aStream,
  in unsigned long aLen
);
Parameters
aStream
An input stream to read from.
aLen
How much to read from the given aStream. Passing PR_UINT32_MAX indicates that all data available will be used to update the hash.
Exceptions thrown
NS_ERROR_NOT_INITIALIZED
If init() has not been called.
NS_ERROR_NOT_AVAILABLE
If the requested amount of data to be calculated into the hash is not available.