Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(node/crypto): separate chacha20-poly1305 from CipherCCMTypes #71834

Merged
merged 1 commit into from
Mar 3, 2025
Merged

feat(node/crypto): separate chacha20-poly1305 from CipherCCMTypes #71834

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 36 additions & 1 deletion types/node/crypto.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -682,9 +682,10 @@ declare module "crypto" {
*/
type: KeyObjectType;
}
type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm" | "chacha20-poly1305";
type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm";
type CipherGCMTypes = "aes-128-gcm" | "aes-192-gcm" | "aes-256-gcm";
type CipherOCBTypes = "aes-128-ocb" | "aes-192-ocb" | "aes-256-ocb";
type CipherChaCha20Poly1305Types = "chacha20-poly1305";
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: This type is probably semantically unnecessary – by definition, the only type that would ever fit the definition of a ChaCha20Poly1305 type is chacha20-poly1305. This can probably be removed, in favour of just using the string literal in the function parameter.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extracting it is better I think. Repeatedly working with string literal may result in typo in string content, but CipherChaCha20Poly1305Types as a ts type under tsc typecheck won't have such issue.

type BinaryLike = string | NodeJS.ArrayBufferView;
type CipherKey = BinaryLike | KeyObject;
interface CipherCCMOptions extends stream.TransformOptions {
Expand All @@ -696,6 +697,10 @@ declare module "crypto" {
interface CipherOCBOptions extends stream.TransformOptions {
authTagLength: number;
}
interface CipherChaCha20Poly1305Options extends stream.TransformOptions {
/** @default 16 */
authTagLength?: number | undefined;
}
/**
* Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
* initialization vector (`iv`).
Expand Down Expand Up @@ -744,6 +749,12 @@ declare module "crypto" {
iv: BinaryLike,
options?: CipherGCMOptions,
): CipherGCM;
function createCipheriv(
algorithm: CipherChaCha20Poly1305Types,
key: CipherKey,
iv: BinaryLike,
options?: CipherChaCha20Poly1305Options,
): CipherChaCha20Poly1305;
function createCipheriv(
algorithm: string,
key: CipherKey,
Expand Down Expand Up @@ -943,6 +954,15 @@ declare module "crypto" {
): this;
getAuthTag(): Buffer;
}
interface CipherChaCha20Poly1305 extends Cipher {
setAAD(
buffer: NodeJS.ArrayBufferView,
options: {
plaintextLength: number;
},
): this;
getAuthTag(): Buffer;
}
/**
* Creates and returns a `Decipher` object that uses the given `algorithm`, `key` and initialization vector (`iv`).
*
Expand Down Expand Up @@ -990,6 +1010,12 @@ declare module "crypto" {
iv: BinaryLike,
options?: CipherGCMOptions,
): DecipherGCM;
function createDecipheriv(
algorithm: CipherChaCha20Poly1305Types,
key: CipherKey,
iv: BinaryLike,
options?: CipherChaCha20Poly1305Options,
): DecipherChaCha20Poly1305;
function createDecipheriv(
algorithm: string,
key: CipherKey,
Expand Down Expand Up @@ -1175,6 +1201,15 @@ declare module "crypto" {
},
): this;
}
interface DecipherChaCha20Poly1305 extends Decipher {
setAuthTag(buffer: NodeJS.ArrayBufferView): this;
setAAD(
buffer: NodeJS.ArrayBufferView,
options: {
plaintextLength: number;
},
): this;
}
interface PrivateKeyInput {
key: string | Buffer;
format?: KeyFormat | undefined;
Expand Down
164 changes: 164 additions & 0 deletions types/node/test/crypto.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,170 @@ import { promisify } from "node:util";
decipher.final();
}

{
let key: crypto.CipherKey = "" as crypto.CipherKey;
let iv: crypto.BinaryLike = "" as crypto.BinaryLike;
{
let cipher = crypto.createCipheriv("aes-128-ccm", key, iv, { authTagLength: 16 });
cipher = crypto.createCipheriv("aes-128-ccm", key, iv, {
authTagLength: 16,
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
// $ExpectType Buffer<ArrayBufferLike>
cipher.getAuthTag();
}

{
let cipher = crypto.createCipheriv("aes-128-gcm", key, iv);
cipher = crypto.createCipheriv("aes-128-gcm", key, iv, {});
cipher = crypto.createCipheriv("aes-128-gcm", key, iv, { authTagLength: 16 });
cipher = crypto.createCipheriv("aes-128-gcm", key, iv, {
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
// $ExpectType Buffer<ArrayBufferLike>
cipher.getAuthTag();
}

{
let cipher = crypto.createCipheriv("aes-128-ocb", key, iv, { authTagLength: 16 });
cipher = crypto.createCipheriv("aes-128-ocb", key, iv, {
authTagLength: 16,
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
// $ExpectType Buffer<ArrayBufferLike>
cipher.getAuthTag();
}

{
let cipher = crypto.createCipheriv("chacha20-poly1305", key, iv);
cipher = crypto.createCipheriv("chacha20-poly1305", key, iv, {});
cipher = crypto.createCipheriv("chacha20-poly1305", key, iv, { authTagLength: 16 });
cipher = crypto.createCipheriv("chacha20-poly1305", key, iv, {
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
// $ExpectType Buffer<ArrayBufferLike>
cipher.getAuthTag();
}

let cipher = crypto.createCipheriv("aes-128-ecb", key, iv);
cipher = crypto.createCipheriv("aes-128-ecb", key, iv, {
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
// @ts-expect-error - .setAAD() does not exist
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
// @ts-expect-error - .getAuthTag() does not exist
cipher.getAuthTag();
}

{
let key: crypto.CipherKey = "" as crypto.CipherKey;
let iv: crypto.BinaryLike = "" as crypto.BinaryLike;
{
let cipher = crypto.createDecipheriv("aes-128-ccm", key, iv, { authTagLength: 16 });
cipher = crypto.createDecipheriv("aes-128-ccm", key, iv, {
authTagLength: 16,
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
cipher.setAuthTag(Buffer.from([]));
}

{
let cipher = crypto.createDecipheriv("aes-128-gcm", key, iv);
cipher = crypto.createDecipheriv("aes-128-gcm", key, iv, {});
cipher = crypto.createDecipheriv("aes-128-gcm", key, iv, { authTagLength: 16 });
cipher = crypto.createDecipheriv("aes-128-gcm", key, iv, {
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
cipher.setAuthTag(Buffer.from([]));
}

{
let cipher = crypto.createDecipheriv("aes-128-ocb", key, iv, { authTagLength: 16 });
cipher = crypto.createDecipheriv("aes-128-ocb", key, iv, {
authTagLength: 16,
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
cipher.setAuthTag(Buffer.from([]));
}

{
let cipher = crypto.createDecipheriv("chacha20-poly1305", key, iv);
cipher = crypto.createDecipheriv("chacha20-poly1305", key, iv, {});
cipher = crypto.createDecipheriv("chacha20-poly1305", key, iv, { authTagLength: 16 });
cipher = crypto.createDecipheriv("chacha20-poly1305", key, iv, {
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
cipher.setAuthTag(Buffer.from([]));
}

let cipher = crypto.createDecipheriv("aes-128-ecb", key, iv);
cipher = crypto.createDecipheriv("aes-128-ecb", key, iv, {
read(size) {
// $ExpectType Transform
this;
// $ExpectType number
size;
},
});
// @ts-expect-error - .setAAD() does not exist
cipher = cipher.setAAD(Buffer.from([]), { plaintextLength: 0 });
// @ts-expect-error - .setAuthTag() does not exist
cipher.setAuthTag(Buffer.from([]));
}

{
// crypto_timingsafeequal_buffer_test
const buffer1: Buffer = new Buffer([1, 2, 3, 4, 5]);
Expand Down
53 changes: 52 additions & 1 deletion types/node/v18/crypto.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -669,9 +669,10 @@ declare module "crypto" {
*/
type: KeyObjectType;
}
type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm" | "chacha20-poly1305";
type CipherCCMTypes = "aes-128-ccm" | "aes-192-ccm" | "aes-256-ccm";
type CipherGCMTypes = "aes-128-gcm" | "aes-192-gcm" | "aes-256-gcm";
type CipherOCBTypes = "aes-128-ocb" | "aes-192-ocb" | "aes-256-ocb";
type CipherChaCha20Poly1305Types = "chacha20-poly1305";
type BinaryLike = string | NodeJS.ArrayBufferView;
type CipherKey = BinaryLike | KeyObject;
interface CipherCCMOptions extends stream.TransformOptions {
Expand All @@ -683,6 +684,10 @@ declare module "crypto" {
interface CipherOCBOptions extends stream.TransformOptions {
authTagLength: number;
}
interface CipherChaCha20Poly1305Options extends stream.TransformOptions {
/** @default 16 */
authTagLength?: number | undefined;
}
/**
* Creates and returns a `Cipher` object that uses the given `algorithm` and `password`.
*
Expand Down Expand Up @@ -720,6 +725,14 @@ declare module "crypto" {
/** @deprecated since v10.0.0 use `createCipheriv()` */
function createCipher(algorithm: CipherGCMTypes, password: BinaryLike, options?: CipherGCMOptions): CipherGCM;
/** @deprecated since v10.0.0 use `createCipheriv()` */
function createCipher(algorithm: CipherOCBTypes, password: BinaryLike, options: CipherOCBOptions): CipherOCB;
/** @deprecated since v10.0.0 use `createCipheriv()` */
function createCipher(
algorithm: CipherChaCha20Poly1305Types,
password: BinaryLike,
options?: CipherChaCha20Poly1305Options,
): CipherChaCha20Poly1305;
/** @deprecated since v10.0.0 use `createCipheriv()` */
function createCipher(algorithm: string, password: BinaryLike, options?: stream.TransformOptions): Cipher;
/**
* Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
Expand Down Expand Up @@ -769,6 +782,12 @@ declare module "crypto" {
iv: BinaryLike,
options?: CipherGCMOptions,
): CipherGCM;
function createCipheriv(
algorithm: CipherChaCha20Poly1305Types,
key: CipherKey,
iv: BinaryLike,
options?: CipherChaCha20Poly1305Options,
): CipherChaCha20Poly1305;
function createCipheriv(
algorithm: string,
key: CipherKey,
Expand Down Expand Up @@ -968,6 +987,15 @@ declare module "crypto" {
): this;
getAuthTag(): Buffer;
}
interface CipherChaCha20Poly1305 extends Cipher {
setAAD(
buffer: NodeJS.ArrayBufferView,
options: {
plaintextLength: number;
},
): this;
getAuthTag(): Buffer;
}
/**
* Creates and returns a `Decipher` object that uses the given `algorithm` and `password` (key).
*
Expand All @@ -994,6 +1022,14 @@ declare module "crypto" {
/** @deprecated since v10.0.0 use `createDecipheriv()` */
function createDecipher(algorithm: CipherGCMTypes, password: BinaryLike, options?: CipherGCMOptions): DecipherGCM;
/** @deprecated since v10.0.0 use `createDecipheriv()` */
function createDecipher(algorithm: CipherOCBTypes, password: BinaryLike, options: CipherOCBOptions): DecipherOCB;
/** @deprecated since v10.0.0 use `createDecipheriv()` */
function createDecipher(
algorithm: CipherChaCha20Poly1305Types,
password: BinaryLike,
options?: CipherChaCha20Poly1305Options,
): DecipherChaCha20Poly1305;
/** @deprecated since v10.0.0 use `createDecipheriv()` */
function createDecipher(algorithm: string, password: BinaryLike, options?: stream.TransformOptions): Decipher;
/**
* Creates and returns a `Decipher` object that uses the given `algorithm`, `key` and initialization vector (`iv`).
Expand Down Expand Up @@ -1042,6 +1078,12 @@ declare module "crypto" {
iv: BinaryLike,
options?: CipherGCMOptions,
): DecipherGCM;
function createDecipheriv(
algorithm: CipherChaCha20Poly1305Types,
key: CipherKey,
iv: BinaryLike,
options?: CipherChaCha20Poly1305Options,
): DecipherChaCha20Poly1305;
function createDecipheriv(
algorithm: string,
key: CipherKey,
Expand Down Expand Up @@ -1226,6 +1268,15 @@ declare module "crypto" {
},
): this;
}
interface DecipherChaCha20Poly1305 extends Decipher {
setAuthTag(buffer: NodeJS.ArrayBufferView): this;
setAAD(
buffer: NodeJS.ArrayBufferView,
options: {
plaintextLength: number;
},
): this;
}
interface PrivateKeyInput {
key: string | Buffer;
format?: KeyFormat | undefined;
Expand Down
Loading