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