Support ZMQ Curve for transport encryption by krassowski · Pull Request #1515 · ipython/ipykernel

krassowski · 2026-05-06T10:39:30Z

This PR adds support for ZMQ Curve cryptography to encrypt kernel communications over TCP, addressing the current limitation of all code and outputs being transmitted in plaintext.

What's changed

Curve key support in IPKernelApp: Loads curve_publickey / curve_secretkey from connection files and applies them to all ZMQ sockets (iopub, shell, control, stdin, heartbeat) via new _apply_curve_server_options() / _apply_curve_client_options() helpers.
Kernelspec metadata: Advertises "supported_encryption": "curve" so frontends can discover and negotiate encryption capability.
Emits a warning when TCP transport is used without encryption, guiding users toward IPC or CurveZMQ.
Heartbeat thread: Extended to accept and apply curve keys to its ROUTER socket.

References

Depends on Add ZMQ Curve for transport encryption jupyter/jupyter_client#1110
Enables Support encryption for the kernel protocol over ZMQ jupyter/jupyter_client#808
PoC for pre-proposal: CurveZMQ jupyter/enhancement-proposals#75
Toggle on server-level: Add a toggle to enable curve encryption for all kernels that support it jupyter-server/jupyter_server#1638

Code changes

tests
additions

for more information, see https://pre-commit.ci

krassowski · 2026-05-07T10:16:42Z

+            self.log.warning(
+                "Kernel is running over TCP without encryption."
+                " All communication (including code and outputs) is sent in plain text"
+                " and is susceptible to eavesdropping."
+                " Use IPC transport or set IPKernelApp.enable_curve=True to enable"
+                " CurveZMQ encryption."
+            )


nbclient downstream tests are failing due to addition of this warning, see:

E AssertionError: assert '[IPKernelApp] WARNING | Kernel is running over TCP without encryption. All communication (including code and outputs) is sent in plain text and is susceptible to eavesdropping. Use IPC transport or set IPKernelApp.enable_curve=True to enable CurveZMQ encryption.\n[IPKernelApp] WARNING | Kernel is running over TCP without encryption. All communication (including code and outputs) is sent in plain text and is susceptible to eavesdropping. Use IPC transport or set IPKernelApp.enable_curve=True to enable CurveZMQ encryption.' == ''

I believe we should keep it and update nbclient tests, any objections?

+1 to fix nbclient.

yeah, nbclient tests shouldn't fail if warnings are logged from another package, that's a problem in the test suite

I opened jupyter/nbclient#341

Carreau · 2026-05-07T10:23:22Z

    ).tag(config=True)

+    enable_curve = Bool(
+        bool(int(os.environ.get("JUPYTER_ENABLE_CURVE", "0"))),


I don't like the name it's non obvious, i think it's ok to have "curve" in inner variable names, maybe not in env-var and options. ; should we also trim(), the value of environ.get, or be stricter on it's format ?

I agree, I think we could hide "curve" here as an implementation detail; an argument for keeping it as-is would be alignment with ipyparallel (ipython/ipyparallel#553).

I think an obvious choice would be enable_transport_encryption?

Same change would need to follow in jupyter-server/jupyter_server#1638.

CC @minrk in case if you have an opinion here

enable_transport_encryption / JUPYTER_ENABLE_TRANSPORT_ENCRYPTION seems fine to me, if a bit verbose. I can update ipyparallel to match, no big deal.

Co-authored-by: M Bussonnier <bussonniermatthias@gmail.com>

Co-authored-by: Min RK <benjaminrk@gmail.com>

Carreau · 2026-06-05T08:17:23Z

I kicked test; everything passing. Do you want to update the PR description extensively before merge ?

krassowski

The PR description is fine, but we should release jupyter-client and update pyproject.toml before we merge

This commit adds CurveZMQ transport encryption to jupyter_client, providing the foundational layer for encrypted kernel communication. It is the upstream dependency for ipykernel#1515 and jupyter-server#1638. What's changed - local_provisioner.py: Generates a CurveZMQ keypair and writes curve_publickey / curve_secretkey into the connection file. The client owns key generation. - connect.py: Reads curve keys from connection files and applies them when setting up ZMQ sockets. - manager.py: Introduces a transport_encryption traitlet with three modes: - 'disabled' (default) — no encryption, existing behavior unchanged - 'auto' — enables encryption only for kernelspecs that advertise metadata.supported_encryption: 'curve' - 'required' — encryption is mandatory; kernel startup fails if the kernelspec doesn't declare support - channels.py / client.py: Heartbeat channel configured as a CurveZMQ client using the server's public key. - Validation: Checks for libsodium support in pyzmq at startup and raises a clear error if missing. Design notes - Named `transport_encryption` (not a boolean) to leave room for future encryption backends beyond CurveZMQ. - Fully backward-compatible: 'disabled' is the default, so nothing changes for existing kernels. - Kernel capability discovery is via kernelspec metadata (supported_encryption: 'curve'), handled on the kernel side in ipykernel#1515. - Guards against pyzmq builds without libsodium, with graceful degradation or a clear error depending on the configured mode. ### References - Closes #808 - PoC for jupyter/enhancement-proposals#75 - Sibling PR ipython/ipykernel#1515 - Toggle on server-level: jupyter-server/jupyter_server#1638

…an branch

krassowski · 2026-06-09T13:27:41Z

All tests pass 🎉

I do not have merge rights here, can we get this merged and released?

Add test for curve encryption

0de32e5

krassowski added the feature label May 6, 2026

pre-commit-ci Bot and others added 4 commits May 6, 2026 10:39

[pre-commit.ci] auto fixes from pre-commit.com hooks

66b706c

for more information, see https://pre-commit.ci

Fix lint in tests

a53cd8f

Draft implementation

38a596f

Use a fork with curve support for testing/PoC

6007e9b

krassowski commented May 6, 2026

View reviewed changes

Comment thread ipykernel/kernelapp.py Outdated

Handoff serialization to jupyter-client

2f29d52

krassowski mentioned this pull request May 6, 2026

Add ZMQ Curve for transport encryption jupyter/jupyter_client#1110

Merged

3 tasks

krassowski commented May 6, 2026

View reviewed changes

Comment thread ipykernel/kernelapp.py Outdated

krassowski added 4 commits May 6, 2026 13:36

Add a warning when curve is disabled and using tcp transport

af73137

Allow references

955e1d4

Fix lint

c246875

Merge branch 'main' into curve-encryption

0defb2b

krassowski mentioned this pull request May 7, 2026

Add a toggle to enable curve encryption for all kernels that support it jupyter-server/jupyter_server#1638

Open

krassowski commented May 7, 2026

View reviewed changes

Carreau self-requested a review May 7, 2026 10:20

Carreau reviewed May 7, 2026

View reviewed changes

Comment thread ipykernel/heartbeat.py Outdated

Carreau reviewed May 7, 2026

View reviewed changes

Comment thread ipykernel/heartbeat.py Outdated

Carreau reviewed May 7, 2026

View reviewed changes

Comment thread tests/test_curve.py Outdated

krassowski and others added 5 commits May 7, 2026 11:45

Require curve keys to be passed as kwargs

8a2a911

Co-authored-by: M Bussonnier <bussonniermatthias@gmail.com>

Make curve keys private and typed

0eec39d

Simplify test fixtures

0c71c21

Make the client own key generation

8d56ecc

Use traitlets for keys

a058d1f

krassowski mentioned this pull request May 9, 2026

Ignore new warning from ipykernel about encryption jupyter/nbclient#341

Merged

krassowski marked this pull request as ready for review May 9, 2026 08:20

krassowski commented May 9, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

krassowski commented May 9, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

krassowski mentioned this pull request May 18, 2026

Support encryption for the kernel protocol over ZMQ jupyter/jupyter_client#808

Closed

minrk approved these changes May 26, 2026

View reviewed changes

Comment thread ipykernel/kernelapp.py Outdated

krassowski and others added 7 commits May 26, 2026 17:07

Change log level to info

bb59da2

Co-authored-by: Min RK <benjaminrk@gmail.com>

Advertise encryption support in kernelspec

04ec2fe

Fix tests

5481d4b

Fix debugger when curve encryption is enabled

b8c7473

Fix somewhat flaky test by waiting for the connection file to show up

7eb90e0

Fix tests

7ecb521

Update tests to reflact rename to "auto"

2157ae7

krassowski commented Jun 5, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

Comment thread pyproject.toml Outdated

krassowski added 2 commits June 5, 2026 20:38

Update pyproject.toml to depend on jupyter_client 8.9.0 rather th…

b0678ba

…an branch

Fix typing due to new jupyter_client version

cd6f460

krassowski requested a review from Carreau June 6, 2026 13:49

krassowski mentioned this pull request Jun 9, 2026

Fix broken IPython Reference URL in help_links #1526

Merged

krassowski added this to the 7.3 milestone Jun 9, 2026

Carreau approved these changes Jun 9, 2026

View reviewed changes

Merge branch 'main' into curve-encryption

b64f597

minrk merged commit 4e4f82c into ipython:main Jun 9, 2026
42 checks passed

krassowski deleted the curve-encryption branch June 9, 2026 16:20

Uh oh!

Conversation

krassowski commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

References

Code changes

Uh oh!

Uh oh!

Uh oh!

krassowski May 7, 2026

Choose a reason for hiding this comment

Uh oh!

Carreau May 7, 2026

Choose a reason for hiding this comment

Uh oh!

minrk May 9, 2026

Choose a reason for hiding this comment

Uh oh!

krassowski May 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Carreau May 7, 2026

Choose a reason for hiding this comment

Uh oh!

krassowski May 7, 2026

Choose a reason for hiding this comment

Uh oh!

minrk Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Carreau commented Jun 5, 2026

Uh oh!

krassowski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

krassowski commented Jun 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

krassowski commented May 6, 2026 •

edited

Loading