sha3.d.ts 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229
  1. type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";
  2. type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
  3. type FormatType = "TEXT" | FormatNoTextType;
  4. type GenericInputType = {
  5. value: string;
  6. format: "TEXT";
  7. encoding?: EncodingType;
  8. } | {
  9. value: string;
  10. format: "B64" | "HEX" | "BYTES";
  11. } | {
  12. value: ArrayBuffer;
  13. format: "ARRAYBUFFER";
  14. } | {
  15. value: Uint8Array;
  16. format: "UINT8ARRAY";
  17. };
  18. type FixedLengthOptionsNoEncodingType = {
  19. hmacKey?: GenericInputType;
  20. } | {
  21. numRounds?: number;
  22. };
  23. type FixedLengthOptionsEncodingType = {
  24. hmacKey?: GenericInputType;
  25. encoding?: EncodingType;
  26. } | {
  27. numRounds?: number;
  28. encoding?: EncodingType;
  29. };
  30. interface packedValue {
  31. value: number[];
  32. binLen: number;
  33. }
  34. interface SHAKEOptionsNoEncodingType {
  35. numRounds?: number;
  36. }
  37. interface SHAKEOptionsEncodingType extends SHAKEOptionsNoEncodingType {
  38. encoding?: EncodingType;
  39. }
  40. interface CSHAKEOptionsNoEncodingType {
  41. customization?: GenericInputType;
  42. funcName?: GenericInputType;
  43. }
  44. interface CSHAKEOptionsEncodingType extends CSHAKEOptionsNoEncodingType {
  45. encoding?: EncodingType;
  46. }
  47. interface KMACOptionsNoEncodingType {
  48. kmacKey: GenericInputType;
  49. customization?: GenericInputType;
  50. }
  51. interface KMACOptionsEncodingType extends KMACOptionsNoEncodingType {
  52. encoding?: EncodingType;
  53. }
  54. declare abstract class jsSHABase<StateT, VariantT> {
  55. /**
  56. * @param variant The desired SHA variant.
  57. * @param inputFormat The input format to be used in future `update` calls.
  58. * @param options Hashmap of extra input options.
  59. */
  60. protected readonly shaVariant: VariantT;
  61. protected readonly inputFormat: FormatType;
  62. protected readonly utfType: EncodingType;
  63. protected readonly numRounds: number;
  64. protected abstract intermediateState: StateT;
  65. protected keyWithIPad: number[];
  66. protected keyWithOPad: number[];
  67. protected remainder: number[];
  68. protected remainderLen: number;
  69. protected updateCalled: boolean;
  70. protected processedLen: number;
  71. protected macKeySet: boolean;
  72. protected abstract readonly variantBlockSize: number;
  73. protected abstract readonly bigEndianMod: -1 | 1;
  74. protected abstract readonly outputBinLen: number;
  75. protected abstract readonly isVariableLen: boolean;
  76. protected abstract readonly HMACSupported: boolean;
  77. protected abstract readonly converterFunc: (input: any, existingBin: number[], existingBinLen: number) => packedValue;
  78. protected abstract readonly roundFunc: (block: number[], H: StateT) => StateT;
  79. protected abstract readonly finalizeFunc: (remainder: number[], remainderBinLen: number, processedBinLen: number, H: StateT, outputLen: number) => number[];
  80. protected abstract readonly stateCloneFunc: (state: StateT) => StateT;
  81. protected abstract readonly newStateFunc: (variant: VariantT) => StateT;
  82. protected abstract readonly getMAC: ((options: {
  83. outputLen: number;
  84. }) => number[]) | null;
  85. protected constructor(variant: VariantT, inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
  86. protected constructor(variant: VariantT, inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
  87. /**
  88. * Hashes as many blocks as possible. Stores the rest for either a future update or getHash call.
  89. *
  90. * @param srcString The input to be hashed.
  91. * @returns A reference to the object.
  92. */
  93. update(srcString: string | ArrayBuffer | Uint8Array): this;
  94. /**
  95. * Returns the desired SHA hash of the input fed in via `update` calls.
  96. *
  97. * @param format The desired output formatting
  98. * @param options Hashmap of output formatting options. `outputLen` must be specified for variable length hashes.
  99. * `outputLen` replaces the now deprecated `shakeLen` key.
  100. * @returns The hash in the format specified.
  101. */
  102. getHash(format: "HEX", options?: {
  103. outputUpper?: boolean;
  104. outputLen?: number;
  105. shakeLen?: number;
  106. }): string;
  107. getHash(format: "B64", options?: {
  108. b64Pad?: string;
  109. outputLen?: number;
  110. shakeLen?: number;
  111. }): string;
  112. getHash(format: "BYTES", options?: {
  113. outputLen?: number;
  114. shakeLen?: number;
  115. }): string;
  116. getHash(format: "UINT8ARRAY", options?: {
  117. outputLen?: number;
  118. shakeLen?: number;
  119. }): Uint8Array;
  120. getHash(format: "ARRAYBUFFER", options?: {
  121. outputLen?: number;
  122. shakeLen?: number;
  123. }): ArrayBuffer;
  124. /**
  125. * Sets the HMAC key for an eventual `getHMAC` call. Must be called immediately after jsSHA object instantiation.
  126. *
  127. * @param key The key used to calculate the HMAC
  128. * @param inputFormat The format of key.
  129. * @param options Hashmap of extra input options.
  130. */
  131. setHMACKey(key: string, inputFormat: "TEXT", options?: {
  132. encoding?: EncodingType;
  133. }): void;
  134. setHMACKey(key: string, inputFormat: "B64" | "HEX" | "BYTES"): void;
  135. setHMACKey(key: ArrayBuffer, inputFormat: "ARRAYBUFFER"): void;
  136. setHMACKey(key: Uint8Array, inputFormat: "UINT8ARRAY"): void;
  137. /**
  138. * Internal function that sets the MAC key.
  139. *
  140. * @param key The packed MAC key to use
  141. */
  142. protected _setHMACKey(key: packedValue): void;
  143. /**
  144. * Returns the the HMAC in the specified format using the key given by a previous `setHMACKey` call.
  145. *
  146. * @param format The desired output formatting.
  147. * @param options Hashmap of extra outputs options.
  148. * @returns The HMAC in the format specified.
  149. */
  150. getHMAC(format: "HEX", options?: {
  151. outputUpper?: boolean;
  152. }): string;
  153. getHMAC(format: "B64", options?: {
  154. b64Pad?: string;
  155. }): string;
  156. getHMAC(format: "BYTES"): string;
  157. getHMAC(format: "UINT8ARRAY"): Uint8Array;
  158. getHMAC(format: "ARRAYBUFFER"): ArrayBuffer;
  159. /**
  160. * Internal function that returns the "raw" HMAC
  161. */
  162. protected _getHMAC(): number[];
  163. }
  164. /**
  165. * Int_64 is a object for 2 32-bit numbers emulating a 64-bit number.
  166. */
  167. declare class Int_64 {
  168. /**
  169. * @param msint_32 The most significant 32-bits of a 64-bit number.
  170. * @param lsint_32 The least significant 32-bits of a 64-bit number.
  171. */
  172. readonly highOrder: number;
  173. readonly lowOrder: number;
  174. constructor(msint_32: number, lsint_32: number);
  175. }
  176. type FixedLengthVariantType = "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512" | "SHAKE128" | "SHAKE256";
  177. type VariantType = FixedLengthVariantType | "SHAKE128" | "SHAKE256" | "CSHAKE128" | "CSHAKE256" | "KMAC128" | "KMAC256";
  178. declare class jsSHA extends jsSHABase<Int_64[][], VariantType> {
  179. intermediateState: Int_64[][];
  180. variantBlockSize: number;
  181. bigEndianMod: -1 | 1;
  182. outputBinLen: number;
  183. isVariableLen: boolean;
  184. HMACSupported: boolean;
  185. converterFunc: (input: any, existingBin: number[], existingBinLen: number) => packedValue;
  186. roundFunc: (block: number[], H: Int_64[][]) => Int_64[][];
  187. finalizeFunc: (remainder: number[], remainderBinLen: number, processedBinLen: number, H: Int_64[][], outputLen: number) => number[];
  188. stateCloneFunc: (state: Int_64[][]) => Int_64[][];
  189. newStateFunc: (variant: VariantType) => Int_64[][];
  190. getMAC: ((options: {
  191. outputLen: number;
  192. }) => number[]) | null;
  193. constructor(variant: FixedLengthVariantType, inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
  194. constructor(variant: FixedLengthVariantType, inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
  195. constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: "TEXT", options?: SHAKEOptionsEncodingType);
  196. constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: FormatNoTextType, options?: SHAKEOptionsNoEncodingType);
  197. constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: "TEXT", options?: CSHAKEOptionsEncodingType);
  198. constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: FormatNoTextType, options?: CSHAKEOptionsNoEncodingType);
  199. constructor(variant: "KMAC128" | "KMAC256", inputFormat: "TEXT", options: KMACOptionsEncodingType);
  200. constructor(variant: "KMAC128" | "KMAC256", inputFormat: FormatNoTextType, options: KMACOptionsNoEncodingType);
  201. /**
  202. * Initialize CSHAKE variants.
  203. *
  204. * @param options Options containing CSHAKE params.
  205. * @param funcNameOverride Overrides any "funcName" present in `options` (used with KMAC)
  206. * @returns The delimiter to be used
  207. */
  208. protected _initializeCSHAKE(options?: CSHAKEOptionsNoEncodingType, funcNameOverride?: packedValue): number;
  209. /**
  210. * Initialize KMAC variants.
  211. *
  212. * @param options Options containing KMAC params.
  213. */
  214. protected _initializeKMAC(options: KMACOptionsNoEncodingType): void;
  215. /**
  216. * Returns the the KMAC in the specified format.
  217. *
  218. * @param options Hashmap of extra outputs options. `outputLen` must be specified.
  219. * @returns The KMAC in the format specified.
  220. */
  221. protected _getKMAC(options: {
  222. outputLen: number;
  223. }): number[];
  224. }
  225. export { jsSHA as default };