Skip to content

Commit b327b81

Browse files
tomaswolftomaswolf
committed
Post-release documentation updates
1 parent d85220e commit b327b81

3 files changed

Lines changed: 81 additions & 56 deletions

File tree

‎CHANGES.md‎

Lines changed: 10 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -8,75 +8,33 @@
88
generated by [japicmp](https://siom79.github.io/japicmp) are published at
99
[https://apache.github.io/mina-sshd](https://apache.github.io/mina-sshd).
1010

11-
Version 3 includes all the features and bug fixes of [version 2.16.0](./docs/changes/2.16.0.md) and up to
12-
[commit f9887391](https://github.com/apache/mina-sshd/blob/f9887391/CHANGES.md#planned-for-next-version).
11+
Version 3 includes all the features and bug fixes of version 2, including the
12+
[latest ones](https://github.com/apache/mina-sshd/blob/master/CHANGES.md#planned-for-next-version).
13+
14+
* For building Apache MINA SSHD 3.0, **Java >= 24** and Apache **Maven >= 3.9.11** are required. Generated artifacts
15+
still use Java 8 as minimum runtime requirement.
1316

1417
## Milestone 1: Pre-Release 3.0.0-M1
1518

1619
Complete refactoring of the SSH transport protocol. New feature: support for client-side proxies.
1720

1821
* [Change notes for 3.0.0-M1](./docs/changes/3.0.0-M1.md)
1922

20-
# Milestone 2: Pre-Release 3.0.0-M2
23+
## Milestone 2: Pre-Release 3.0.0-M2
2124

2225
Refactoring of cryptography. New feature: multi-release JARs for `sshd-common` and `sshd-osgi` and using on
2326
newer Java versions the already built-in cryptographic algorithms for ChaCha20, ed25519, and ML-KEM.
2427

25-
* For building Apache MINA SSHD 3.0, Java >= 24 and Apache Maven >= 3.9.11 are required. Generated artifacts
26-
still use Java 8 as minimum runtime requirement.
28+
* [Change notes for 3.0.0-M2](./docs/changes/3.0.0-M2.md)
29+
30+
# Planned for the Next Milestone Release
31+
2732

2833
## Bug Fixes
2934

30-
* [GH-502](https://github.com/apache/mina-sshd/issues/502) Don't load security provider classes reflectively
31-
for Bouncy Castle and `net.i2p.crypto:eddsa:0.3.0`.
3235

3336
## Major Code Re-factoring
3437

35-
* The classes dealing with serializing or de-serializing public and private keys have been de-generified,
36-
which simplifies them a lot. Previous code from version 2 tried to tie particular public key types and
37-
private key types together via generics, such that it could be statically checked that only matching key
38-
types were used. But that never worked well and in a few crucial places unchecked conversions or raw
39-
types were used anyway, which makes the point moot. Code now just uses `PublicKey` and `PrivateKey` instead
40-
of generic types, and checks at run-time that keys are of the expected kind.
41-
* The way ed25519 keys are handled has been refactored. Duplicate code has been removed, and the handling
42-
has been simplified to make it easier to include support for other eddsa implementations. This brings
43-
additional API breaks, but in code areas that are unlikely to be used in customer code.
4438

4539
## New Features
4640

47-
* [GH-585](https://github.com/apache/mina-sshd/issues/585) Support the JDK built-in ed25519 on Java15+
48-
49-
With this change `sshd-common` and `sshd-osgi` become MRJARs (multi-release JARs). When run on Java >= 15,
50-
Apache MINA SSHD will use the built-in ed25519 from the SunEC security provider. On Java < 15, ed25519 is
51-
supported if Bouncy Castle or `net.i2p.crypto:eddsa:0.3.0` is present.
52-
53-
On Java >= 15, Apache MINA SSHD will use the JDK ed25519 even if Bouncy Castle or `net.i2p.crypto:eddsa:0.3.0`
54-
are present. (Including `net.i2p.crypto:eddsa:0.3.0` makes no sense on Java >= 15.) There is a new
55-
[registrar](./docs/security-providers.md) `SunECSecurityProviderRegistrar` with the name "SunECWrapper". It
56-
is by default registered ahead of the Bouncy Castle or net.i2p registrars, and has by default ed25519,
57-
X25519, and X448 enabled if SunEC is registered and has these algorithms. This new registrar can be
58-
configured like any other registrar via system properties; in particular it can also be disabled via system
59-
property `org.apache.sshd.security.provider.SunECWrapper.enabled=false`.
60-
61-
The sole purpose of this new registrar is to prefer the SunEC implementations of ed25519, X25519, or X448 over
62-
the Bouncy Castle or net.i2p implementations if Bouncy Castle or net.i2p are also available.
63-
64-
* Use the JDK's built-in ChaCha20 cipher on Java11+
65-
66-
With `sshd-common` being a MRJAR, it is finally possible to use the JDK's built-in ChaCha20 cipher for the
67-
chacha20-poly1305@<!-- -->openssh.com cipher on Java >= 11. This brings a substantial speed-up for this
68-
encryption. On Java < 11, Apache MINA SSHD still uses its own implementation written in Java.
69-
70-
(Note that one cannot use the JDK's "ChaCha20-Poly1305" cipher for SSH; Java implements
71-
[RFC 8439](https://datatracker.ietf.org/doc/html/rfc8439), which has a different AEAD tag construction than
72-
the version used in SSH. Since the Poly1305 MAC in Java is not accessible separately (see
73-
[JDK-8253394](https://bugs.openjdk.org/browse/JDK-8253394)), Apache MINA SSHD still has to use its own
74-
implementation for that part.)
75-
76-
* [GH-803](https://github.com/apache/mina-sshd/issues/803) Support the JDK built-in ML-KEMs on Java24+
77-
78-
Use the ML-KEM implementations from SunJCE if run on Java >= 24. For Java < 24, the Bouncy Castle implementations
79-
are used. The SunJCE ML-KEMs are advertised in the `SunJCESecurityProviderRegistrar`.
80-
81-
* OSGi: the upper bound of the version range for package imports from `org.bouncycastle.*` has been raised from 2.0.0
82-
to 3.0.0. This enables using BC-FIPS in an OSGi environment. BC-FIPS provides OSGi manifests as of version 2.1.0.

‎docs/changes/3.0.0-M2.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Milestone Pre-Release 3.0.0-M2
2+
3+
Includes all the features and bug fixes of [version 2.16.0](./2.16.0.md) and up to
4+
[commit f9887391](https://github.com/apache/mina-sshd/blob/f9887391/CHANGES.md#planned-for-next-version).
5+
6+
* [Change notes for 3.0.0-M1](./3.0.0-M1.md)
7+
8+
* For building Apache MINA SSHD 3.0, **Java >= 24** and Apache **Maven >= 3.9.11** are required. Generated artifacts
9+
still use Java 8 as minimum runtime requirement.
10+
11+
## Bug Fixes
12+
13+
* [GH-502](https://github.com/apache/mina-sshd/issues/502) Don't load security provider classes reflectively
14+
for Bouncy Castle and `net.i2p.crypto:eddsa:0.3.0`.
15+
16+
## Major Code Re-factoring
17+
18+
* The classes dealing with serializing or de-serializing public and private keys have been de-generified,
19+
which simplifies them a lot. Previous code from version 2 tried to tie particular public key types and
20+
private key types together via generics, such that it could be statically checked that only matching key
21+
types were used. But that never worked well and in a few crucial places unchecked conversions or raw
22+
types were used anyway, which makes the point moot. Code now just uses `PublicKey` and `PrivateKey` instead
23+
of generic types, and checks at run-time that keys are of the expected kind.
24+
* The way ed25519 keys are handled has been refactored. Duplicate code has been removed, and the handling
25+
has been simplified to make it easier to include support for other eddsa implementations. This brings
26+
additional API breaks, but in code areas that are unlikely to be used in customer code.
27+
28+
## New Features
29+
30+
* [GH-585](https://github.com/apache/mina-sshd/issues/585) Support the JDK built-in ed25519 on Java15+
31+
32+
With this change `sshd-common` and `sshd-osgi` become MRJARs (multi-release JARs). When run on Java >= 15,
33+
Apache MINA SSHD will use the built-in ed25519 from the SunEC security provider. On Java < 15, ed25519 is
34+
supported if Bouncy Castle or `net.i2p.crypto:eddsa:0.3.0` is present.
35+
36+
On Java >= 15, Apache MINA SSHD will use the JDK ed25519 even if Bouncy Castle or `net.i2p.crypto:eddsa:0.3.0`
37+
are present. (Including `net.i2p.crypto:eddsa:0.3.0` makes no sense on Java >= 15.) There is a new
38+
[registrar](./../security-providers.md) `SunECSecurityProviderRegistrar` with the name "SunECWrapper". It
39+
is by default registered ahead of the Bouncy Castle or net.i2p registrars, and has by default ed25519,
40+
X25519, and X448 enabled if SunEC is registered and has these algorithms. This new registrar can be
41+
configured like any other registrar via system properties; in particular it can also be disabled via system
42+
property `org.apache.sshd.security.provider.SunECWrapper.enabled=false`.
43+
44+
The sole purpose of this new registrar is to prefer the SunEC implementations of ed25519, X25519, or X448 over
45+
the Bouncy Castle or net.i2p implementations if Bouncy Castle or net.i2p are also available.
46+
47+
* Use the JDK's built-in ChaCha20 cipher on Java11+
48+
49+
With `sshd-common` being a MRJAR, it is finally possible to use the JDK's built-in ChaCha20 cipher for the
50+
chacha20-poly1305@<!-- -->openssh.com cipher on Java >= 11. This brings a substantial speed-up for this
51+
encryption. On Java < 11, Apache MINA SSHD still uses its own implementation written in Java.
52+
53+
(Note that one cannot use the JDK's "ChaCha20-Poly1305" cipher for SSH; Java implements
54+
[RFC 8439](https://datatracker.ietf.org/doc/html/rfc8439), which has a different AEAD tag construction than
55+
the version used in SSH. Since the Poly1305 MAC in Java is not accessible separately (see
56+
[JDK-8253394](https://bugs.openjdk.org/browse/JDK-8253394)), Apache MINA SSHD still has to use its own
57+
implementation for that part.)
58+
59+
* [GH-803](https://github.com/apache/mina-sshd/issues/803) Support the JDK built-in ML-KEMs on Java24+
60+
61+
Use the ML-KEM implementations from SunJCE if run on Java >= 24. For Java < 24, the Bouncy Castle implementations
62+
are used. The SunJCE ML-KEMs are advertised in the `SunJCESecurityProviderRegistrar`.
63+
64+
* OSGi: the upper bound of the version range for package imports from `org.bouncycastle.*` has been raised from 2.0.0
65+
to 3.0.0. This enables using BC-FIPS in an OSGi environment. BC-FIPS provides OSGi manifests as of version 2.1.0.

‎sshd-site/src/site/markdown/index.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,14 +42,16 @@ volunteers in their free time and resources are limited.
4242

4343
But we can give you a rough outline of what we want to do:
4444

45-
* **3.0.0-M1**: Rework of the SSH transport protocol as a filter chain. The main user-visible new feature is support for client-side proxies.
45+
* **3.0.0-M1**: Rework of the SSH transport protocol as a filter chain. The main user-visible
46+
new feature is support for client-side proxies.
47+
* **3.0.0-M2**: Refactoring of cryptography. New feature: multi-release JARs for `sshd-common`
48+
and `sshd-osgi` and using on newer Java versions the already built-in cryptographic algorithms
49+
for ChaCha20, ed25519, and ML-KEM.
4650

4751
Further possible milestones (the order might change, though):
4852

49-
* Some rework of handling of private/public keys. No new feature planned, it's necessary clean-up that will require some public API changes.
50-
* Resolve the split packages between `sshd-common` and `sshd-core`.
51-
* Support Java native ed25519 on Java >= 15. This may result in a multi-release JAR artifact.
5253
* Some refactoring of SFTP code; current code has shortcomings regarding SFTP file systems.
54+
* Resolve the split packages between `sshd-common` and `sshd-core`.
5355
* Anything else we stumble upon and that we cannot fix reasonably without breaking API.
5456

5557
We reserve the right to make arbitrary API changes between M-releases.

0 commit comments

Comments
 (0)