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/. */
5 #include
"nsISupports.idl"
6 interface nsIInputStream
;
9 #include
"mozilla/AlreadyAddRefed.h"
14 * This interface provides crytographic hashing algorithms.
17 [builtinclass
, scriptable
, uuid(1e5b7c43
-4688-45ce
-92e1
-77ed931e3bbe
)]
18 interface nsICryptoHash
: nsISupports
21 * Hashing Algorithms. These values are to be used by the
22 * |init| method to indicate which hashing function to
23 * use. These values must be identical to the values defined
24 * in security/nss/lib/util/hasht.h in type HASH_HashType.
25 * This allows us to use NSS mapping functions like
26 * HASH_GetHashOidTagByHashType with these values.
28 const short MD5
= 2; /* String value: "md5" */
29 const short SHA1
= 3; /* String value: "sha1" */
30 const short SHA256
= 4; /* String value: "sha256" */
31 const short SHA384
= 5; /* String value: "sha384" */
32 const short SHA512
= 6; /* String value: "sha512" */
35 * Initialize the hashing object. This method may be
36 * called multiple times with different algorithm types.
38 * @param aAlgorithm the algorithm type to be used.
39 * This value must be one of the above valid
42 * @throws NS_ERROR_INVALID_ARG if an unsupported algorithm
45 * NOTE: This method or initWithString must be called
46 * before any other method on this interface is called.
48 void init
(in unsigned long aAlgorithm
);
51 * Initialize the hashing object. This method may be
52 * called multiple times with different algorithm types.
54 * @param aAlgorithm the algorithm type to be used.
56 * @throws NS_ERROR_INVALID_ARG if an unsupported algorithm
59 * NOTE: This method or init must be called before any
60 * other method on this interface is called.
63 void initWithString
(in ACString aAlgorithm
);
66 * @param aData a buffer to calculate the hash over
68 * @param aLen the length of the buffer |aData|
70 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called.
72 void update
([const, array
, size_is(aLen
)] in octet aData
, in unsigned long aLen
);
75 * Calculates and updates a new hash based on a given data stream.
77 * @param aStream an input stream to read from.
79 * @param aLen How much to read from the given |aStream|. Passing UINT32_MAX
80 * indicates that all data available will be used to update the hash.
82 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called.
84 * @throws NS_ERROR_NOT_AVAILABLE If the requested amount of
85 * data to be calculated into the hash is not available.
89 void updateFromStream
(in nsIInputStream aStream
, in unsigned long aLen
);
92 * Completes this hash object and produces the actual hash data.
94 * @param aASCII If true then the returned value is a base64 encoded string.
95 * If false, then the returned value is binary data.
97 * @return a hash of the data that was read by this object. This can
98 * be either binary data or base 64 encoded.
100 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called.
102 * NOTE: This method may be called any time after |init|
103 * is called. This call resets the object to its
106 ACString finish
(in boolean aASCII
);
110 already_AddRefed
<nsICryptoHash
> NS_NewCryptoHash
();
111 nsresult NS_NewCryptoHash
(uint32_t aHashType
, nsICryptoHash
** aOutHasher
);
112 nsresult NS_NewCryptoHash
(const nsACString
& aHashType
, nsICryptoHash
** aOutHasher
);