1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsICryptoHMAC.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,108 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +interface nsIInputStream;
1.10 +interface nsIKeyObject;
1.11 +
1.12 +/**
1.13 + * nsICryptoHMAC
1.14 + * This interface provides HMAC signature algorithms.
1.15 + */
1.16 +
1.17 +[scriptable, uuid(8FEB4C7C-1641-4a7b-BC6D-1964E2099497)]
1.18 +interface nsICryptoHMAC : nsISupports
1.19 +{
1.20 + /**
1.21 + * Hashing Algorithms. These values are to be used by the
1.22 + * |init| method to indicate which hashing function to
1.23 + * use. These values map onto the values defined in
1.24 + * mozilla/security/nss/lib/softoken/pkcs11t.h and are
1.25 + * switched to CKM_*_HMAC constant.
1.26 + */
1.27 + const short MD2 = 1;
1.28 + const short MD5 = 2;
1.29 + const short SHA1 = 3;
1.30 + const short SHA256 = 4;
1.31 + const short SHA384 = 5;
1.32 + const short SHA512 = 6;
1.33 +
1.34 + /**
1.35 + * Initialize the hashing object. This method may be
1.36 + * called multiple times with different algorithm types.
1.37 + *
1.38 + * @param aAlgorithm the algorithm type to be used.
1.39 + * This value must be one of the above valid
1.40 + * algorithm types.
1.41 + *
1.42 + * @param aKeyObject
1.43 + * Object holding a key. To create the key object use for instance:
1.44 + * var keyObject = Components.classes["@mozilla.org/security/keyobjectfactory;1"]
1.45 + * .getService(Components.interfaces.nsIKeyObjectFactory)
1.46 + * .keyFromString(Components.interfaces.nsIKeyObject.HMAC, rawKeyData);
1.47 + *
1.48 + * WARNING: This approach is not FIPS compliant.
1.49 + *
1.50 + * @throws NS_ERROR_INVALID_ARG if an unsupported algorithm
1.51 + * type is passed.
1.52 + *
1.53 + * NOTE: This method must be called before any other method
1.54 + * on this interface is called.
1.55 + */
1.56 + void init(in unsigned long aAlgorithm, in nsIKeyObject aKeyObject);
1.57 +
1.58 + /**
1.59 + * @param aData a buffer to calculate the hash over
1.60 + *
1.61 + * @param aLen the length of the buffer |aData|
1.62 + *
1.63 + * @throws NS_ERROR_NOT_INITIALIZED if |init| has not been
1.64 + * called.
1.65 + */
1.66 + void update([const, array, size_is(aLen)] in octet aData, in unsigned long aLen);
1.67 +
1.68 + /**
1.69 + * Calculates and updates a new hash based on a given data stream.
1.70 + *
1.71 + * @param aStream an input stream to read from.
1.72 + *
1.73 + * @param aLen how much to read from the given |aStream|. Passing
1.74 + * UINT32_MAX indicates that all data available will be used
1.75 + * to update the hash.
1.76 + *
1.77 + * @throws NS_ERROR_NOT_INITIALIZED if |init| has not been
1.78 + * called.
1.79 + *
1.80 + * @throws NS_ERROR_NOT_AVAILABLE if the requested amount of
1.81 + * data to be calculated into the hash is not available.
1.82 + *
1.83 + */
1.84 + void updateFromStream(in nsIInputStream aStream, in unsigned long aLen);
1.85 +
1.86 + /**
1.87 + * Completes this HMAC object and produces the actual HMAC diegest data.
1.88 + *
1.89 + * @param aASCII if true then the returned value is a base-64
1.90 + * encoded string. if false, then the returned value is
1.91 + * binary data.
1.92 + *
1.93 + * @return a hash of the data that was read by this object. This can
1.94 + * be either binary data or base 64 encoded.
1.95 + *
1.96 + * @throws NS_ERROR_NOT_INITIALIZED if |init| has not been
1.97 + * called.
1.98 + *
1.99 + * NOTE: This method may be called any time after |init|
1.100 + * is called. This call resets the object to its
1.101 + * pre-init state.
1.102 + */
1.103 + ACString finish(in boolean aASCII);
1.104 +
1.105 + /**
1.106 + * Reinitialize HMAC context to be reused with the same
1.107 + * settings (the key and hash algorithm) but on different
1.108 + * set of data.
1.109 + */
1.110 + void reset();
1.111 +};
