sha3.d.ts 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228
  1. declare type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";
  2. declare type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
  3. declare type FormatType = "TEXT" | FormatNoTextType;
  4. declare 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. declare type FixedLengthOptionsNoEncodingType = {
  19. hmacKey?: GenericInputType;
  20. } | {
  21. numRounds?: number;
  22. };
  23. declare 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. */
  92. update(srcString: string | ArrayBuffer | Uint8Array): void;
  93. /**
  94. * Returns the desired SHA hash of the input fed in via `update` calls.
  95. *
  96. * @param format The desired output formatting
  97. * @param options Hashmap of output formatting options. `outputLen` must be specified for variable length hashes.
  98. * `outputLen` replaces the now deprecated `shakeLen` key.
  99. * @returns The hash in the format specified.
  100. */
  101. getHash(format: "HEX", options?: {
  102. outputUpper?: boolean;
  103. outputLen?: number;
  104. shakeLen?: number;
  105. }): string;
  106. getHash(format: "B64", options?: {
  107. b64Pad?: string;
  108. outputLen?: number;
  109. shakeLen?: number;
  110. }): string;
  111. getHash(format: "BYTES", options?: {
  112. outputLen?: number;
  113. shakeLen?: number;
  114. }): string;
  115. getHash(format: "UINT8ARRAY", options?: {
  116. outputLen?: number;
  117. shakeLen?: number;
  118. }): Uint8Array;
  119. getHash(format: "ARRAYBUFFER", options?: {
  120. outputLen?: number;
  121. shakeLen?: number;
  122. }): ArrayBuffer;
  123. /**
  124. * Sets the HMAC key for an eventual `getHMAC` call. Must be called immediately after jsSHA object instantiation.
  125. *
  126. * @param key The key used to calculate the HMAC
  127. * @param inputFormat The format of key.
  128. * @param options Hashmap of extra input options.
  129. */
  130. setHMACKey(key: string, inputFormat: "TEXT", options?: {
  131. encoding?: EncodingType;
  132. }): void;
  133. setHMACKey(key: string, inputFormat: "B64" | "HEX" | "BYTES"): void;
  134. setHMACKey(key: ArrayBuffer, inputFormat: "ARRAYBUFFER"): void;
  135. setHMACKey(key: Uint8Array, inputFormat: "UINT8ARRAY"): void;
  136. /**
  137. * Internal function that sets the MAC key.
  138. *
  139. * @param key The packed MAC key to use
  140. */
  141. protected _setHMACKey(key: packedValue): void;
  142. /**
  143. * Returns the the HMAC in the specified format using the key given by a previous `setHMACKey` call.
  144. *
  145. * @param format The desired output formatting.
  146. * @param options Hashmap of extra outputs options.
  147. * @returns The HMAC in the format specified.
  148. */
  149. getHMAC(format: "HEX", options?: {
  150. outputUpper?: boolean;
  151. }): string;
  152. getHMAC(format: "B64", options?: {
  153. b64Pad?: string;
  154. }): string;
  155. getHMAC(format: "BYTES"): string;
  156. getHMAC(format: "UINT8ARRAY"): Uint8Array;
  157. getHMAC(format: "ARRAYBUFFER"): ArrayBuffer;
  158. /**
  159. * Internal function that returns the "raw" HMAC
  160. */
  161. protected _getHMAC(): number[];
  162. }
  163. /**
  164. * Int_64 is a object for 2 32-bit numbers emulating a 64-bit number.
  165. */
  166. declare class Int_64 {
  167. /**
  168. * @param msint_32 The most significant 32-bits of a 64-bit number.
  169. * @param lsint_32 The least significant 32-bits of a 64-bit number.
  170. */
  171. readonly highOrder: number;
  172. readonly lowOrder: number;
  173. constructor(msint_32: number, lsint_32: number);
  174. }
  175. declare type FixedLengthVariantType = "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512" | "SHAKE128" | "SHAKE256";
  176. declare type VariantType = FixedLengthVariantType | "SHAKE128" | "SHAKE256" | "CSHAKE128" | "CSHAKE256" | "KMAC128" | "KMAC256";
  177. declare class jsSHA extends jsSHABase<Int_64[][], VariantType> {
  178. intermediateState: Int_64[][];
  179. variantBlockSize: number;
  180. bigEndianMod: -1 | 1;
  181. outputBinLen: number;
  182. isVariableLen: boolean;
  183. HMACSupported: boolean;
  184. converterFunc: (input: any, existingBin: number[], existingBinLen: number) => packedValue;
  185. roundFunc: (block: number[], H: Int_64[][]) => Int_64[][];
  186. finalizeFunc: (remainder: number[], remainderBinLen: number, processedBinLen: number, H: Int_64[][], outputLen: number) => number[];
  187. stateCloneFunc: (state: Int_64[][]) => Int_64[][];
  188. newStateFunc: (variant: VariantType) => Int_64[][];
  189. getMAC: ((options: {
  190. outputLen: number;
  191. }) => number[]) | null;
  192. constructor(variant: FixedLengthVariantType, inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
  193. constructor(variant: FixedLengthVariantType, inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
  194. constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: "TEXT", options?: SHAKEOptionsEncodingType);
  195. constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: FormatNoTextType, options?: SHAKEOptionsNoEncodingType);
  196. constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: "TEXT", options?: CSHAKEOptionsEncodingType);
  197. constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: FormatNoTextType, options?: CSHAKEOptionsNoEncodingType);
  198. constructor(variant: "KMAC128" | "KMAC256", inputFormat: "TEXT", options: KMACOptionsEncodingType);
  199. constructor(variant: "KMAC128" | "KMAC256", inputFormat: FormatNoTextType, options: KMACOptionsNoEncodingType);
  200. /**
  201. * Initialize CSHAKE variants.
  202. *
  203. * @param options Options containing CSHAKE params.
  204. * @param funcNameOverride Overrides any "funcName" present in `options` (used with KMAC)
  205. * @returns The delimiter to be used
  206. */
  207. protected _initializeCSHAKE(options?: CSHAKEOptionsNoEncodingType, funcNameOverride?: packedValue): number;
  208. /**
  209. * Initialize KMAC variants.
  210. *
  211. * @param options Options containing KMAC params.
  212. */
  213. protected _initializeKMAC(options: KMACOptionsNoEncodingType): void;
  214. /**
  215. * Returns the the KMAC in the specified format.
  216. *
  217. * @param options Hashmap of extra outputs options. `outputLen` must be specified.
  218. * @returns The KMAC in the format specified.
  219. */
  220. protected _getKMAC(options: {
  221. outputLen: number;
  222. }): number[];
  223. }
  224. export default jsSHA;