Skip to content

feat: Add ZUC stream cipher operation - #2666

Closed
NihaoKangkang wants to merge 2 commits into
gchq:masterfrom
NihaoKangkang:feature/zuc-cipher-3656552422777355745
Closed

NihaoKangkang wants to merge 2 commits into
gchq:masterfrom
NihaoKangkang:feature/zuc-cipher-3656552422777355745

Conversation

@NihaoKangkang

Copy link
Copy Markdown

Implements the ZUC stream cipher in pure JavaScript based on the 3GPP confidentiality algorithm 128-EEA3/EIA3 specifications. Registers the cipher as a new Operation within CyberChef and includes test vectors to ensure correctness.

Author: Kyi Wong
Copyright: Crown Copyright 2026
License: Apache-2.0

Description
This PR adds the ZUC stream cipher to CyberChef. ZUC is a stream cipher designed by the Chinese Academy of Sciences and forms the core of the 3GPP confidentiality algorithm 128-EEA3 and the 3GPP integrity algorithm 128-EIA3.

The implementation strictly follows the 3GPP TS 35.221 specification, handling the 128-bit Key and 128-bit Initialization Vector (IV) to generate the keystream.

Existing Issue
None

Screenshots
image

AI disclosure
AI tools (Google Labs Jules) were used to assist in translating the cryptographic algorithm mathematically safely into JavaScript and structuring the module according to the CONTRIBUTING.md guidelines. The code has been thoroughly reviewed and manually tested to guarantee cryptographic correctness and performance without external dependencies.

Test Coverage
Official Test Vectors (from the 3GPP standard specification) have been integrated into the Node API testing suite (tests/node/tests/operations.mjs) to guarantee strictly standardized keystream output. All tests pass locally (npm run test). And by the way, I developed ZUC in python before and I check these two results manually.

@NihaoKangkang

Copy link
Copy Markdown
Author

Reference paper / official specification: https://www.gsma.com/about-us/wp-content/uploads/2014/12/eea3eia3zucv16.pdf

@sylvesterkaczmarek sylvesterkaczmarek left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The advertised Base64 input paths are currently broken.

_parseInput() does new Uint8Array(fromBase64(input)), but CyberChef's fromBase64() returns a binary string by default. Passing that string to the Uint8Array constructor does not convert its character bytes; it is treated as a length-like argument and produces an empty typed array (new Uint8Array("...") has length 0).

Consequences:

  • a valid 16-byte Base64 key is parsed as 0 bytes and fails the key-length check;
  • a valid 16-byte Base64 IV is parsed as 0 bytes and fails the IV-length check;
  • Base64 message input becomes an empty message and returns an empty result.

The current tests only exercise Hex, so this is not covered. Could this request the byte-array return type directly, e.g. fromBase64(input, undefined, "byteArray"), and add at least one Base64 key/IV/input test that is equivalent to an existing Hex vector?

@NihaoKangkang

Copy link
Copy Markdown
Author

Ok, I'll update this brach ASAP. Thanks for your reply.

@NihaoKangkang

Copy link
Copy Markdown
Author

Thanks for the detailed review and for catching the Base64 parsing issue.

This has been fixed in commit b56b1be by requesting the byte-array return type directly:

fromBase64(input, undefined, "byteArray")

I also expanded the ZUC test coverage to include:

  • a Base64 key/IV/input regression test equivalent to the existing all-zero Hex vector;
  • 128 combinations covering Hex, UTF8, Latin1, and Base64 across the key, IV, and message input;
  • variable-length Hex and Base64 inputs, including different Base64 padding cases;
  • invalid 15-byte and 17-byte key/IV checks in every supported input format;
  • both supported output formats, Hex and Base64.

ZUC output has also been limited to Hex and Base64 because ciphertext is arbitrary binary data. UTF-8 or Latin1 interpretation can still be performed explicitly using CyberChef's existing From Hex/From Base64 and Decode text operations.

The branch has now been updated with the latest gchq:master. I re-ran the full validation on the updated branch:

  • Node API tests: 286/286 passing
  • Operation tests: 2316/2316 passing
  • ESLint and the production Webpack build both pass

Could you please take another look when you have time?

@sylvesterkaczmarek sylvesterkaczmarek left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Rechecked current a34864b. The Base64 parsing issue I raised is resolved: ZUC now requests the byte-array return type directly from fromBase64(), matching the existing CyberChef API used elsewhere. The regression covers Base64 key/IV/message equivalence to the known Hex vector, and the expanded matrix exercises all supported input formats, invalid key/IV lengths, variable message lengths, and both binary-safe output formats. No remaining blocker from my review.

@sylvesterkaczmarek sylvesterkaczmarek left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Rechecked current head c399f5a after the latest master merge. The ZUC implementation and tests I reviewed are unchanged; the Base64 byte-array fix and expanded format/length coverage remain intact. No remaining blocker from my review.

NihaoKangkang and others added 2 commits November 4, 2026 18:25
Implements the ZUC stream cipher in pure JavaScript based on the 3GPP confidentiality algorithm 128-EEA3/EIA3 specifications. Registers the cipher as a new Operation within CyberChef and includes test vectors to ensure correctness.

Author: Kyi Wong
Copyright: Crown Copyright 2026
License: Apache-2.0

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
@NihaoKangkang
NihaoKangkang force-pushed the feature/zuc-cipher-3656552422777355745 branch from c399f5a to a2ff23e Compare November 4, 2026 09:25
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution - unfortunately this repository only accepts pull requests from organisation members or approved outside collaborators. Due to that, this pull request has been closed automatically.

@github-actions github-actions Bot closed this Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants