Skip to content
rachel/workerd
File

Blob: src/node/internal/crypto.d.ts

typescript508 lines
1// Copyright (c) 2017-2022 Cloudflare, Inc.
2// Licensed under the Apache 2.0 license found in the LICENSE file or at:
3//     https://opensource.org/licenses/Apache-2.0
4 
5import { Buffer } from 'node-internal:internal_buffer';
6 
7// random
8export function checkPrimeSync(
9  candidate: ArrayBufferView,
10  num_checks: number
11): boolean;
12export function randomPrime(
13  size: number,
14  safe: boolean,
15  add?: ArrayBufferView,
16  rem?: ArrayBufferView
17): ArrayBuffer;
18 
19export function statelessDH(
20  privateKey: CryptoKey,
21  publicKey: CryptoKey
22): ArrayBuffer;
23 
24// X509Certificate
25export interface CheckOptions {
26  subject?: string;
27  wildcards?: boolean;
28  partialWildcards?: boolean;
29  multiLabelWildcards?: boolean;
30  singleLabelSubdomains?: boolean;
31}
32 
33export class X509Certificate {
34  static parse(data: ArrayBuffer | ArrayBufferView): X509Certificate | null;
35  get subject(): string | undefined;
36  get subjectAltName(): string | undefined;
37  get infoAccess(): string | undefined;
38  get issuer(): string | undefined;
39  get issuerCert(): X509Certificate | undefined;
40  get validFrom(): string | undefined;
41  get validTo(): string | undefined;
42  get fingerprint(): string | undefined;
43  get fingerprint256(): string | undefined;
44  get fingerprint512(): string | undefined;
45  get keyUsage(): string[] | undefined;
46  get serialNumber(): string | undefined;
47  get pem(): string | undefined;
48  get raw(): ArrayBuffer | undefined;
49  get publicKey(): CryptoKey | undefined;
50  get isCA(): boolean;
51  checkHost(host: string, options?: CheckOptions): string | undefined;
52  checkEmail(email: string, options?: CheckOptions): string | undefined;
53  checkIp(ip: string, options?: CheckOptions): string | undefined;
54  checkIssued(cert: X509Certificate): boolean;
55  checkPrivateKey(key: CryptoKey): boolean;
56  verify(key: CryptoKey): boolean;
57  toLegacyObject(): object;
58}
59 
60// Hash and Hmac
61export class HashHandle {
62  constructor(algorithm: string, xofLen: number);
63  update(data: Buffer | ArrayBufferView): number;
64  digest(): ArrayBuffer;
65  copy(xofLen: number): HashHandle;
66}
67 
68export class SignHandle {
69  constructor(algorithm: string);
70  update(data: Buffer | ArrayBufferView): void;
71  sign(
72    key: CryptoKey,
73    rsaPadding?: number,
74    pssSaltLength?: number,
75    dsaSigEnc?: number
76  ): Uint8Array;
77}
78 
79export class VerifyHandle {
80  constructor(algorithm: string);
81  update(data: Buffer | ArrayBufferView): void;
82  verify(
83    key: CryptoKey,
84    signature: ArrayBufferView,
85    rsaPadding?: number,
86    pssSaltLength?: number,
87    dsaSigEnc?: number
88  ): boolean;
89}
90 
91export function signOneShot(
92  key: CryptoKey,
93  algorithm: string | undefined,
94  data: ArrayBufferView,
95  rsaPadding?: number,
96  pssSaltLength?: number,
97  dsaSigEnc?: number
98): ArrayBuffer;
99export function verifyOneShot(
100  key: CryptoKey,
101  algorithm: string | undefined,
102  data: ArrayBufferView,
103  signature: ArrayBufferView,
104  rsaPadding?: number,
105  pssSaltLength?: number,
106  dsaSigEnc?: number
107): boolean;
108 
109export class CipherHandle {
110  update(data: ArrayBuffer | ArrayBufferView): ArrayBuffer;
111  final(): ArrayBuffer;
112  setAAD(data: ArrayBuffer | ArrayBufferView, plaintextLength?: number): void;
113  setAutoPadding(autoPadding: boolean): void;
114  getAuthTag(): ArrayBuffer | undefined;
115  setAuthTag(tag: ArrayBuffer | ArrayBufferView): void;
116}
117 
118export class AeadHandle {
119  update(data: ArrayBuffer | ArrayBufferView): ArrayBuffer;
120  final(): ArrayBuffer;
121  setAAD(data: ArrayBuffer | ArrayBufferView, plaintextLength?: number): void;
122  setAutoPadding(autoPadding: boolean): void;
123  getAuthTag(): ArrayBuffer | undefined;
124  setAuthTag(tag: ArrayBuffer | ArrayBufferView): void;
125}
126 
127export type CipherMode = {
128  CIPHER: 0;
129  DECIPHER: 1;
130};
131 
132export function newHandle(
133  mode: (typeof CipherMode)[keyof typeof CipherMode],
134  algorithm: string,
135  key: CryptoKey,
136  iv: ArrayBuffer | ArrayBufferView,
137  authTagLength?: number
138): CipherHandle | AeadHandle;
139export interface PublicPrivateCipherOptions {
140  padding: number;
141  oaepHash: string;
142  oaepLabel: ArrayBuffer | ArrayBufferView | undefined;
143}
144 
145export function publicEncrypt(
146  key: CryptoKey,
147  buffer: ArrayBuffer | ArrayBufferView,
148  options: PublicPrivateCipherOptions
149): Buffer;
150export function publicDecrypt(
151  key: CryptoKey,
152  buffer: ArrayBuffer | ArrayBufferView,
153  options: PublicPrivateCipherOptions
154): Buffer;
155export function privateEncrypt(
156  key: CryptoKey,
157  buffer: ArrayBuffer | ArrayBufferView,
158  options: PublicPrivateCipherOptions
159): Buffer;
160export function privateDecrypt(
161  key: CryptoKey,
162  buffer: ArrayBuffer | ArrayBufferView,
163  options: PublicPrivateCipherOptions
164): Buffer;
165 
166interface CipherInfo {
167  name: string;
168  nid: number;
169  blockSize?: number;
170  ivLength?: number;
171  keyLength: number;
172  mode:
173    | 'cbc'
174    | 'ccm'
175    | 'cfb'
176    | 'ctr'
177    | 'ecb'
178    | 'gcm'
179    | 'ocb'
180    | 'ofb'
181    | 'stream'
182    | 'wrap'
183    | 'xts';
184}
185 
186interface GetCipherInfoOptions {
187  ivLength?: number;
188  keyLength?: number;
189}
190 
191export function getCipherInfo(
192  nameOrId: string | number,
193  options: GetCipherInfoOptions
194): CipherInfo | undefined;
195 
196export function getCiphers(): string[];
197 
198export type ArrayLike = ArrayBuffer | string | Buffer | ArrayBufferView;
199 
200export class HmacHandle {
201  constructor(algorithm: string, key: ArrayLike | CryptoKey);
202  update(data: Buffer | ArrayBufferView): number;
203  digest(): ArrayBuffer;
204}
205 
206// hkdf
207export function getHkdf(
208  hash: string,
209  key: ArrayLike,
210  salt: ArrayLike,
211  info: ArrayLike,
212  length: number
213): ArrayBuffer;
214 
215// pbkdf2
216export function getPbkdf(
217  password: ArrayLike,
218  salt: ArrayLike,
219  iterations: number,
220  keylen: number,
221  digest: string
222): ArrayBuffer;
223 
224// scrypt
225export function getScrypt(
226  password: ArrayLike,
227  salt: ArrayLike,
228  N: number,
229  r: number,
230  p: number,
231  maxmem: number,
232  keylen: number
233): ArrayBuffer;
234 
235// Keys
236export function exportKey(
237  key: CryptoKey,
238  options?: InnerExportOptions
239): KeyExportResult;
240export function equals(key: CryptoKey, otherKey: CryptoKey): boolean;
241export function getAsymmetricKeyDetail(key: CryptoKey): AsymmetricKeyDetails;
242export function getAsymmetricKeyType(key: CryptoKey): AsymmetricKeyType;
243export function createSecretKey(key: ArrayBuffer | ArrayBufferView): CryptoKey;
244export function createPrivateKey(
245  key: InnerCreateAsymmetricKeyOptions
246): CryptoKey;
247export function createPublicKey(
248  key: InnerCreateAsymmetricKeyOptions
249): CryptoKey;
250 
251export interface RsaKeyPairOptions {
252  type: string;
253  modulusLength: number;
254  publicExponent: number;
255  saltLength?: number;
256  hashAlgorithm?: string;
257  mgf1HashAlgorithm?: string;
258}
259 
260export interface DsaKeyPairOptions {
261  modulusLength: number;
262  divisorLength: number;
263}
264 
265export interface EcKeyPairOptions {
266  namedCurve: string;
267  paramEncoding: ParamEncoding;
268}
269 
270export interface EdKeyPairOptions {
271  type: string;
272}
273 
274export interface DhKeyPairOptions {
275  primeOrGroup: BufferSource | number | string;
276  generator?: number | undefined;
277}
278 
279export function generateRsaKeyPair(options: RsaKeyPairOptions): CryptoKeyPair;
280export function generateDsaKeyPair(options: DsaKeyPairOptions): CryptoKeyPair;
281export function generateEcKeyPair(options: EcKeyPairOptions): CryptoKeyPair;
282export function generateEdKeyPair(options: EdKeyPairOptions): CryptoKeyPair;
283export function generateDhKeyPair(options: DhKeyPairOptions): CryptoKeyPair;
284 
285// Spkac
286export function verifySpkac(input: ArrayBufferView | ArrayBuffer): boolean;
287export function exportPublicKey(
288  input: ArrayBufferView | ArrayBuffer
289): null | ArrayBuffer;
290export function exportChallenge(
291  input: ArrayBufferView | ArrayBuffer
292): null | ArrayBuffer;
293 
294export type KeyData = string | ArrayBuffer | ArrayBufferView;
295 
296export interface RsaKeyAlgorithm {
297  name: 'rsa' | 'rsa-pss';
298  modulusLength: number;
299  publicExponent: Uint8Array;
300  hash?: string;
301}
302 
303export interface EcKeyAlgorithm {
304  name: 'ec';
305  namedCurve: string;
306}
307 
308export interface DhKeyAlgorithm {
309  name: 'dh';
310  prime: Uint8Array;
311  generator: Uint8Array;
312}
313 
314export interface DsaKeyAlgorithm {
315  name: 'dsa';
316  prime: Uint8Array;
317  divisorLength: number;
318}
319 
320export interface HmacKeyAlgorithm {
321  name: 'hmac';
322  hash: string;
323}
324 
325export interface AesKeyAlgorithm {
326  name: 'aes';
327  length: number;
328}
329 
330export type KeyAlgorithm =
331  | RsaKeyAlgorithm
332  | EcKeyAlgorithm
333  | DhKeyAlgorithm
334  | DsaKeyAlgorithm
335  | HmacKeyAlgorithm
336  | AesKeyAlgorithm;
337 
338export interface RsaOtherPrimesInfo {
339  d?: string;
340  r?: string;
341  t?: string;
342}
343 
344export interface JsonWebKey {
345  alg?: string;
346  crv?: string;
347  d?: string;
348  dp?: string;
349  dq?: string;
350  e?: string;
351  ext?: boolean;
352  k?: string;
353  key_ops?: string[];
354  kty?: string;
355  n?: string;
356  oth?: Array<RsaOtherPrimesInfo>;
357  p?: string;
358  q?: string;
359  qi?: string;
360  use?: string;
361  x?: string;
362  y?: string;
363}
364 
365export interface CryptoKeyPair {
366  privateKey: CryptoKey;
367  publicKey: CryptoKey;
368}
369 
370export type KeyObjectType = 'secret' | 'public' | 'private';
371 
372export type KeyExportResult = string | Buffer | JsonWebKey;
373 
374export type SecretKeyFormat = 'buffer' | 'jwk';
375export type AsymmetricKeyFormat = 'pem' | 'der' | 'jwk';
376export type PublicKeyEncoding = 'pkcs1' | 'spki';
377export type PrivateKeyEncoding = 'pkcs1' | 'pkcs8' | 'sec1';
378export type AsymmetricKeyType = 'rsa' | 'ec' | 'x25519' | 'ed25519' | 'dh';
379export type SecretKeyType = 'hmac' | 'aes';
380export type ParamEncoding = 'named' | 'explicit';
381 
382export interface SecretKeyExportOptions {
383  format?: SecretKeyFormat;
384}
385 
386export interface PublicKeyExportOptions {
387  type?: PublicKeyEncoding;
388  format?: AsymmetricKeyFormat;
389}
390 
391export interface PrivateKeyExportOptions {
392  type?: PrivateKeyEncoding;
393  format?: AsymmetricKeyFormat;
394  cipher?: string;
395  passphrase?: string | Uint8Array;
396  encoding?: string;
397}
398 
399export interface InnerPrivateKeyExportOptions {
400  type?: PrivateKeyEncoding;
401  format?: AsymmetricKeyFormat;
402  cipher?: string;
403  passphrase?: Uint8Array;
404}
405 
406export type ExportOptions =
407  | SecretKeyExportOptions
408  | PublicKeyExportOptions
409  | PrivateKeyExportOptions;
410 
411export type InnerExportOptions =
412  | SecretKeyExportOptions
413  | PublicKeyExportOptions
414  | InnerPrivateKeyExportOptions;
415 
416export interface AsymmetricKeyDetails {
417  modulusLength?: number;
418  publicExponent?: bigint;
419  hashAlgorithm?: string;
420  mgf1HashAlgorithm?: string;
421  saltLength?: number;
422  divisorLength?: number;
423  namedCurve?: string;
424}
425 
426// The user-provided options passed to createPrivateKey or createPublicKey.
427// This will be processed into an InnerCreateAsymmetricKeyOptions.
428export interface CreateAsymmetricKeyOptions {
429  key: string | ArrayBuffer | ArrayBufferView | JsonWebKey | null | undefined;
430  format?: AsymmetricKeyFormat;
431  type?: PublicKeyEncoding | PrivateKeyEncoding;
432  passphrase?: string | Uint8Array | Buffer;
433  encoding?: string;
434}
435 
436// The processed key options. The key property will be one of either
437// an ArrayBuffer, an ArrayBufferView, a JWK, or a CryptoKey. The
438// format and type options will be validated to known good values,
439// and the passphrase will either be undefined or an ArrayBufferView.
440export interface InnerCreateAsymmetricKeyOptions {
441  // CryptoKey is only used when importing a public key derived from
442  // an existing private key.
443  key: ArrayBuffer | ArrayBufferView | JsonWebKey | CryptoKey;
444  format: AsymmetricKeyFormat;
445  type: PublicKeyEncoding | PrivateKeyEncoding | undefined;
446  passphrase: Buffer | ArrayBuffer | ArrayBufferView | undefined;
447}
448 
449export interface GenerateKeyOptions {
450  length: number;
451}
452 
453export interface GenerateKeyPairOptions {
454  modulusLength?: number;
455  publicExponent?: number | bigint;
456  hash?: string;
457  hashAlgorithm?: string;
458  mgf1Hash?: string;
459  mgf1HashAlgorithm?: string;
460  saltLength?: number;
461  divisorLength?: number;
462  namedCurve?: string;
463  prime?: Uint8Array;
464  primeLength?: number;
465  generator?: number;
466  group?: string;
467  groupName?: string;
468  paramEncoding?: ParamEncoding;
469  publicKeyEncoding?: PublicKeyExportOptions;
470  privateKeyEncoding?: PrivateKeyExportOptions;
471}
472 
473// DiffieHellman
474export class DiffieHellmanHandle {
475  constructor(
476    sizeOrKey: number | ArrayBuffer | ArrayBufferView,
477    generator: number | ArrayBuffer | ArrayBufferView
478  );
479  setPublicKey(data: ArrayBuffer | ArrayBufferView | Buffer): void;
480  setPrivateKey(data: ArrayBuffer | ArrayBufferView | Buffer): void;
481  getPublicKey(): ArrayBuffer;
482  getPrivateKey(): ArrayBuffer;
483  getGenerator(): ArrayBuffer;
484  getPrime(): ArrayBuffer;
485 
486  computeSecret(key: ArrayBuffer | ArrayBufferView): ArrayBuffer;
487  generateKeys(): ArrayBuffer;
488 
489  getVerifyError(): number;
490}
491 
492export type ECDHFormat = 'compressed' | 'uncompressed' | 'hybrid';
493export class ECDHHandle {
494  constructor(curveName: string);
495  computeSecret(otherPublicKey: ArrayBufferView): ArrayBuffer;
496  generateKeys(): ArrayBuffer;
497  getPrivateKey(): ArrayBuffer;
498  getPublicKey(format: ECDHFormat): ArrayBuffer;
499  setPrivateKey(key: ArrayBufferView): void;
500  static convertKey(
501    key: ArrayBufferView,
502    curveName: string,
503    format: ECDHFormat
504  ): ArrayBuffer;
505}
506 
507export function DiffieHellmanGroupHandle(name: string): DiffieHellmanHandle;