nsICryptoHash

Method overview

Constants

Hash algorithms

These constants are used by the init() method to indicate which hashing function to use. The values map directly onto the values defined in mozilla/security/nss/lib/cryptohi/hasht.h.

Methods

finish()

Completes the hash object and produces the actual hash data.

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

This method returns a hash of the data that was read by this object. This can be either binary data or a base-64 encoded string.

Exceptions thrown

NS_ERROR_NOT_INITIALIZED

Indicates that init() or initWithString() has not been called.

init()

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

void init(
  in unsigned long aAlgorithm
);

Parameters

aAlgorithm

The hash algorithm to use. Must be one of the Hash Algorithms.

Exceptions thrown

NS_ERROR_INVALID_ARG

Indicates that an unsupported algorithm type was passed

initWithString()

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

void initWithString(
  in ACString aAlgorithm
);

Parameters

aAlgorithm

The hash algorithm type to be used as a string, such as "SHA256".

Exceptions thrown

NS_ERROR_INVALID_ARG

Indicates that an unsupported algorithm type was passed

update()

Adds an array of data to be hashed to the object. See Computing the Hash of a String for an example of using this method.

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

Indicates that init() or initWithString() has not been called.

updateFromStream()

Calculates and updates a new hash based on a given data stream (nsIInputStream). See Computing the Hash of a File for an example of using this method.

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_AVAILABLE

Indicates that the requested amount of data to be calculated into the hash is not available.

NS_ERROR_NOT_INITIALIZED

Indicates that init() or initWithString() has not been called.

Example

Computing the Hash of a File

You can easily compute the hash of a file using nsICryptoHash. You will need to create an instance of nsICryptoHash, open an input stream from a file, and then update the hash with the file. The following example shows how to compute the SHA256 hash of a file:

// hardcoded here for convenience
var path = "c:\\windows\\notepad.exe";
var f = Components.classes["@mozilla.org/file/local;1"]
                  .createInstance(Components.interfaces.nsILocalFile);
f.initWithPath(path);
var istream = Components.classes["@mozilla.org/network/file-input-stream;1"]           
                        .createInstance(Components.interfaces.nsIFileInputStream);
// open for reading
istream.init(f, 0x01, 0444, 0);
var ch = Components.classes["@mozilla.org/security/hash;1"]
                   .createInstance(Components.interfaces.nsICryptoHash);
// we want to use the SHA256 algorithm
ch.init(ch.SHA256);
// this tells updateFromStream to read the entire file
const PR_UINT32_MAX = 0xffffffff;
ch.updateFromStream(istream, PR_UINT32_MAX);
// pass false here to get binary data back
var hash = ch.finish(false);

// return the two-digit hexadecimal code for a byte
function toHexString(charCode)
{
  return ("0" + charCode.toString(16)).slice(-2);
}

// convert the binary hash data to a hex string.
var s = Array.from(hash, (c, i) => toHexString(hash.charCodeAt(i))).join("");
// s now contains your hash in hex

This gives 5eb63bbbe01eeed093cb22bb8f5acdc3 for the hash value. This example, while simple, shows most of the functionality of the interface.

The first thing to note is that when you call the init() method you must specify the hash algorithm to use. All of the available algorithms are specified as constants on the interface.

Also note that when you call the updateFromStream() method, the second parameter is the number of bytes to read. Passing PR_UINT32_MAX here indicates that you want the entire file read.

Finally, note that calling the finish() method produces the hash value. The single parameter to this method is false in this example to return binary data. Passing true returns the hash as a base 64 encoded string. In this example we take the binary data and produce a hexadecimal string of the result, as is commonly output by hashing programs.

Computing the Hash of a String

Another common operation is computing the hash value of a string. Since hash functions are computed over bytes, you will first need to convert the string to a series of bytes using nsIScriptableUnicodeConverter and a Unicode encoding that you specify.

The example below shows how to convert a string to bytes in the UTF-8 encoding, and then compute the SHA256 hash of it. The result is computed as a hex string as in the previous example.

In this example, we use the update() method to pass an array of bytes to be hashed. As in the previous example, we convert the binary result to a hex string.

var str = "hello world";
var converter =
  Components.classes["@mozilla.org/intl/scriptableunicodeconverter"].
    createInstance(Components.interfaces.nsIScriptableUnicodeConverter);

// we use UTF-8 here, you can choose other encodings.
converter.charset = "UTF-8";
// result is an out parameter,
// result.value will contain the array length
var result = {};
// data is an array of bytes
var data = converter.convertToByteArray(str, result);
var ch = Components.classes["@mozilla.org/security/hash;1"]
                   .createInstance(Components.interfaces.nsICryptoHash);
ch.init(ch.SHA256);
ch.update(data, data.length);
var hash = ch.finish(false);

// return the two-digit hexadecimal code for a byte
function toHexString(charCode)
{
  return ("0" + charCode.toString(16)).slice(-2);
}

// convert the binary hash data to a hex string.
var s = Array.from(hash, (c, i) => toHexString(hash.charCodeAt(i))).join("");
// s now contains your hash in hex: should be
// 5eb63bbbe01eeed093cb22bb8f5acdc3

See also

• Firefox 1.5