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; 7 8/** 9 * nsICryptoHash 10 * This interface provides crytographic hashing algorithms. 11 */ 12 13[builtinclass, scriptable, uuid(1e5b7c43-4688-45ce-92e1-77ed931e3bbe)] 14interface nsICryptoHash : nsISupports 15{ 16 /** 17 * Hashing Algorithms. These values are to be used by the 18 * |init| method to indicate which hashing function to 19 * use. These values must be identical to the values defined 20 * in security/nss/lib/util/hasht.h in type HASH_HashType. 21 * This allows us to use NSS mapping functions like 22 * HASH_GetHashOidTagByHashType with these values. 23 */ 24 const short MD5 = 2; /* String value: "md5" */ 25 const short SHA1 = 3; /* String value: "sha1" */ 26 const short SHA256 = 4; /* String value: "sha256" */ 27 const short SHA384 = 5; /* String value: "sha384" */ 28 const short SHA512 = 6; /* String value: "sha512" */ 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 * @throws NS_ERROR_INVALID_ARG if an unsupported algorithm 39 * type is passed. 40 * 41 * NOTE: This method or initWithString must be called 42 * before any other method on this interface is called. 43 */ 44 void init(in unsigned long aAlgorithm); 45 46 /** 47 * Initialize the hashing object. This method may be 48 * called multiple times with different algorithm types. 49 * 50 * @param aAlgorithm the algorithm type to be used. 51 * 52 * @throws NS_ERROR_INVALID_ARG if an unsupported algorithm 53 * type is passed. 54 * 55 * NOTE: This method or init must be called before any 56 * other method on this interface is called. 57 */ 58 [must_use] 59 void initWithString(in ACString aAlgorithm); 60 61 /** 62 * @param aData a buffer to calculate the hash over 63 * 64 * @param aLen the length of the buffer |aData| 65 * 66 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called. 67 */ 68 void update([const, array, size_is(aLen)] in octet aData, in unsigned long aLen); 69 70 /** 71 * Calculates and updates a new hash based on a given data stream. 72 * 73 * @param aStream an input stream to read from. 74 * 75 * @param aLen How much to read from the given |aStream|. Passing UINT32_MAX 76 * indicates that all data available will be used to update the hash. 77 * 78 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called. 79 * 80 * @throws NS_ERROR_NOT_AVAILABLE If the requested amount of 81 * data to be calculated into the hash is not available. 82 * 83 */ 84 [must_use] 85 void updateFromStream(in nsIInputStream aStream, in unsigned long aLen); 86 87 /** 88 * Completes this hash object and produces the actual hash data. 89 * 90 * @param aASCII If true then the returned value is a base64 encoded string. 91 * If false, then the returned value is binary data. 92 * 93 * @return a hash of the data that was read by this object. This can 94 * be either binary data or base 64 encoded. 95 * 96 * @throws NS_ERROR_NOT_INITIALIZED If |init| has not been called. 97 * 98 * NOTE: This method may be called any time after |init| 99 * is called. This call resets the object to its 100 * pre-init state. 101 */ 102 ACString finish(in boolean aASCII); 103}; 104