sha.d.ts 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. type EncodingType = "UTF8" | "UTF16BE" | "UTF16LE";
  2. type FormatNoTextType = "HEX" | "B64" | "BYTES" | "ARRAYBUFFER" | "UINT8ARRAY";
  3. type GenericInputType = {
  4. value: string;
  5. format: "TEXT";
  6. encoding?: EncodingType;
  7. } | {
  8. value: string;
  9. format: "B64" | "HEX" | "BYTES";
  10. } | {
  11. value: ArrayBuffer;
  12. format: "ARRAYBUFFER";
  13. } | {
  14. value: Uint8Array;
  15. format: "UINT8ARRAY";
  16. };
  17. type FixedLengthOptionsNoEncodingType = {
  18. hmacKey?: GenericInputType;
  19. } | {
  20. numRounds?: number;
  21. };
  22. type FixedLengthOptionsEncodingType = {
  23. hmacKey?: GenericInputType;
  24. encoding?: EncodingType;
  25. } | {
  26. numRounds?: number;
  27. encoding?: EncodingType;
  28. };
  29. interface SHAKEOptionsNoEncodingType {
  30. numRounds?: number;
  31. }
  32. interface SHAKEOptionsEncodingType extends SHAKEOptionsNoEncodingType {
  33. encoding?: EncodingType;
  34. }
  35. interface CSHAKEOptionsNoEncodingType {
  36. customization?: GenericInputType;
  37. funcName?: GenericInputType;
  38. }
  39. interface CSHAKEOptionsEncodingType extends CSHAKEOptionsNoEncodingType {
  40. encoding?: EncodingType;
  41. }
  42. interface KMACOptionsNoEncodingType {
  43. kmacKey: GenericInputType;
  44. customization?: GenericInputType;
  45. }
  46. interface KMACOptionsEncodingType extends KMACOptionsNoEncodingType {
  47. encoding?: EncodingType;
  48. }
  49. type FixedLengthVariantType = "SHA-1" | "SHA-224" | "SHA-256" | "SHA-384" | "SHA-512" | "SHA3-224" | "SHA3-256" | "SHA3-384" | "SHA3-512";
  50. declare class jsSHA {
  51. private readonly shaObj;
  52. /**
  53. * @param variant The desired SHA variant (SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-256,
  54. * SHA3-384, SHA3-512, SHAKE128, SHAKE256, CSHAKE128, CSHAKE256, KMAC128, or KMAC256) as a string.
  55. * @param inputFormat The input format to be used in future `update` calls (TEXT, HEX, B64, BYTES, ARRAYBUFFER,
  56. * or UINT8ARRAY) as a string.
  57. * @param options Options in the form of { encoding?: "UTF8" | "UTF16BE" | "UTF16LE"; numRounds?: number }.
  58. * `encoding` is for only TEXT input (defaults to UTF8) and `numRounds` defaults to 1.
  59. * `numRounds` is not valid for any of the MAC or CSHAKE variants.
  60. * * If the variant supports HMAC, `options` may have an additional `hmacKey` key which must be in the form of
  61. * {value: <INPUT>, format: <FORMAT>, encoding?: "UTF8" | "UTF16BE" | "UTF16LE"} where <FORMAT> takes the same
  62. * values as `inputFormat` and <INPUT> can be a `string | ArrayBuffer | Uint8Array` depending on <FORMAT>.
  63. * Supplying this key switches to HMAC calculation and replaces the now deprecated call to `setHMACKey`.
  64. * * If the variant is CSHAKE128 or CSHAKE256, `options` may have two additional keys, `customization` and `funcName`,
  65. * which are the NIST customization and function-name strings. Both must be in the same form as `hmacKey`.
  66. * * If the variant is KMAC128 or KMAC256, `options` can include the `customization` key from CSHAKE variants and
  67. * *must* have a `kmacKey` key that takes the same form as the `customization` key.
  68. */
  69. constructor(variant: FixedLengthVariantType, inputFormat: "TEXT", options?: FixedLengthOptionsEncodingType);
  70. constructor(variant: FixedLengthVariantType, inputFormat: FormatNoTextType, options?: FixedLengthOptionsNoEncodingType);
  71. constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: "TEXT", options?: SHAKEOptionsEncodingType);
  72. constructor(variant: "SHAKE128" | "SHAKE256", inputFormat: FormatNoTextType, options?: SHAKEOptionsNoEncodingType);
  73. constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: "TEXT", options?: CSHAKEOptionsEncodingType);
  74. constructor(variant: "CSHAKE128" | "CSHAKE256", inputFormat: FormatNoTextType, options?: CSHAKEOptionsNoEncodingType);
  75. constructor(variant: "KMAC128" | "KMAC256", inputFormat: "TEXT", options: KMACOptionsEncodingType);
  76. constructor(variant: "KMAC128" | "KMAC256", inputFormat: FormatNoTextType, options: KMACOptionsNoEncodingType);
  77. /**
  78. * Takes `input` and hashes as many blocks as possible. Stores the rest for either a future `update` or `getHash` call.
  79. *
  80. * @param input The input to be hashed.
  81. * @returns A reference to the object.
  82. */
  83. update(input: string | ArrayBuffer | Uint8Array): this;
  84. /**
  85. * Returns the desired SHA or MAC (if a HMAC/KMAC key was specified) hash of the input fed in via `update` calls.
  86. *
  87. * @param format The desired output formatting (B64, HEX, BYTES, ARRAYBUFFER, or UINT8ARRAY) as a string.
  88. * @param options Options in the form of { outputUpper?: boolean; b64Pad?: string; outputLen?: number; }.
  89. * `outputLen` is required for variable length output variants (this option was previously called `shakeLen` which
  90. * is now deprecated).
  91. * `outputUpper` is only for HEX output (defaults to false) and b64pad is only for B64 output (defaults to "=").
  92. * @returns The hash in the format specified.
  93. */
  94. getHash(format: "HEX", options?: {
  95. outputUpper?: boolean;
  96. outputLen?: number;
  97. shakeLen?: number;
  98. }): string;
  99. getHash(format: "B64", options?: {
  100. b64Pad?: string;
  101. outputLen?: number;
  102. shakeLen?: number;
  103. }): string;
  104. getHash(format: "BYTES", options?: {
  105. outputLen?: number;
  106. shakeLen?: number;
  107. }): string;
  108. getHash(format: "UINT8ARRAY", options?: {
  109. outputLen?: number;
  110. shakeLen?: number;
  111. }): Uint8Array;
  112. getHash(format: "ARRAYBUFFER", options?: {
  113. outputLen?: number;
  114. shakeLen?: number;
  115. }): ArrayBuffer;
  116. /**
  117. * Sets the HMAC key for an eventual `getHMAC` call. Must be called immediately after jsSHA object instantiation.
  118. * Now deprecated in favor of setting the `hmacKey` at object instantiation.
  119. *
  120. * @param key The key used to calculate the HMAC
  121. * @param inputFormat The format of key (HEX, TEXT, B64, BYTES, ARRAYBUFFER, or UINT8ARRAY) as a string.
  122. * @param options Options in the form of { encoding?: "UTF8" | "UTF16BE" | "UTF16LE }. `encoding` is only for TEXT
  123. * and defaults to UTF8.
  124. */
  125. setHMACKey(key: string, inputFormat: "TEXT", options?: {
  126. encoding?: EncodingType;
  127. }): void;
  128. setHMACKey(key: string, inputFormat: "B64" | "HEX" | "BYTES"): void;
  129. setHMACKey(key: ArrayBuffer, inputFormat: "ARRAYBUFFER"): void;
  130. setHMACKey(key: Uint8Array, inputFormat: "UINT8ARRAY"): void;
  131. /**
  132. * Returns the the HMAC in the specified format using the key given by a previous `setHMACKey` call. Now deprecated
  133. * in favor of just calling `getHash`.
  134. *
  135. * @param format The desired output formatting (B64, HEX, BYTES, ARRAYBUFFER, or UINT8ARRAY) as a string.
  136. * @param options Options in the form of { outputUpper?: boolean; b64Pad?: string }. `outputUpper` is only for HEX
  137. * output (defaults to false) and `b64pad` is only for B64 output (defaults to "=").
  138. * @returns The HMAC in the format specified.
  139. */
  140. getHMAC(format: "HEX", options?: {
  141. outputUpper?: boolean;
  142. }): string;
  143. getHMAC(format: "B64", options?: {
  144. b64Pad?: string;
  145. }): string;
  146. getHMAC(format: "BYTES"): string;
  147. getHMAC(format: "UINT8ARRAY"): Uint8Array;
  148. getHMAC(format: "ARRAYBUFFER"): ArrayBuffer;
  149. }
  150. export { jsSHA as default };