The Device Drivers, Features, and Commands publication for Kernel 6.2 is live on IBM Docs and includes descriptions for:
You can access the publications here.
RoCE interfaces may lose their IP settings due to an unexpected change of the network interface name.
The RoCE Express adapters can lose their IP settings due to an unexpected change of the network interface name if both of the following conditions are met:
To workaround this problem:
Create the file /etc/systemd/network/98-rhel87-s390x.link with the following content:
[Match]
Architecture=s390x
KernelCommandLine=!net.naming-scheme=rhel-8.7
[Link]
NamePolicy=kernel database slot path
AlternativeNamesPolicy=database slot path
MACAddressPolicy=persistent
After rebooting the system for the changes to take effect, you can safely upgrade to RHEL 8.7 or later.
Note:
RoCE interfaces that are enumerated by function ID (FID, indicated by featuring the prefix ens in their interface names) are not unique and not affected by this issue. Set the kernel parameter net.naming-scheme=rhel-8.7. to switch to predictable interface names with the eno prefix. See the Networking with RoCE Express book for further details.
One of the outstanding features of IBM z16 and LinuxONE 4 systems is that they shall prepare their users for a quantum-safe era, meaning the investments of the owners of these systems shall be protected even if future strong quantum computers should be able to break classic asymmetric cryptographic methods like RSA, Diffie-Hellman or elliptic curve-based methods. Therefore, the infrastructure (e.g., secure firmware loads, internal secure communication channels) of an IBM z16 and a LinuxONE 4 are designed to be quantum-safe.
It is certainly nice if your applications run on secure, quantum-safe infrastructure, but what if you want to enhance your workload to be quantum-safe? The Crypto Express 8S adapters available with IBM z16 and LinuxONE 4 support two quantum-safe algorithms in both the CCA and the EP11 modes: CRYSTALS-Dilithium (a signing algorithm) and CRYSTALS-Kyber (a key exchange algorithm) both of which were among the winners of the Post Quantum Computing Competition sponsored by NIST. While an earlier version of CRYSTALS-Dilithium was already supported by the Crypto Express 7S adapters, support for CRYSTALS-Kyber is a new feature.
Whereas the usage of the Dilithium algorithm to sign messages is straight forward, the usage of Kyber keys is less intuitive. Therefore, this article wants to show you how your Linux on zSystems and LinuxONE applications can use the Kyber algorithm to exchange a symmetric key between two parties, using a PKCS #11 API and a Crypto Express 8S adapter in EP11 mode.
First, we need to understand how a key exchange with Kyber works. The cryptographic operation used with Kyber is called a key encapsulation method (KEM). A KEM uses a pair of a public key kpub and a private key kpriv, and consists of two methods:
such that the derived keys returned by encapsulation and decapsulation are equal if the encrypted secret input into the decapsulation is equal to the encrypted secret output by the encapsulation (and the respective optional shared secret inputs are equal).
So, for two parties (typically called) Alice and Bob to derive the same key k using Kyber, proceed as follows:
Alice generates a Kyber key pair (kpub,kpriv).
Alice sends the public Kyber key kpub to Bob.
Bob calls encapsulation with input kpub which returns the derived key k and the encrypted secret c.
Bob sends c to Alice.
Alice calls decapsulation with input kpriv and c which returns the derived key k.
Now, both Alice and Bob have a copy of the key k and can protect their communication using k.
Given
that quantum-safe methods are still young, IBM (in accordance with
NIST) recommends hybrid cryptographic schemes consisting of a
classical and a quantum-safe method such that both methods must be
broken to break the combined (i.e., hybrid) method.
In
a hybrid scheme, Kyber can be combined with
Elliptic-Curve-Diffie-Hellman ECDH.
For the hybrid scheme, both parties first use ECDH to each compute a shared secret which is then used as the optional shared secret input in the encapsulation and decapsulation methods:
Alice generates an Elliptic Curve (EC) key pair (akpub,akpriv) and sends her public EC key akpub to Bob
Bob generates an EC key pair (bkpub,bkpriv) and sends his public EC key bkpub to Alice
Alice derives the shared secret ss using ECDH with inputs bkpub and akpriv
Bob derives the same shared secret ss using ECDH with inputs akpub and bkpriv
Allice generates a Kyber key pair (kpub,kpriv).
Alice sends the public Kyber key kpub to Bob.
Bob calls encapsulation with inputs kpub and ss, and gets the derived key k and the encrypted secret c.
Bob sends c to Alice.
Alice calls decapsulation with input kpriv, c and ss, and gets the derived key k.
Again, both Alice and Bob have a copy of the key k and can protect their communication using k.
openCryptoki version 3.20 released in February 2023 supports the quantum-safe algorithms implemented by the Crypto Express 8S adapter in EP11 mode. Only recently, the first Linux distribution to ship this openCryptoki version was released: Ubuntu 23.04. The openCryptoki versions of RHEL 8.8 and RHEL 9.2 have picked up the new quantum safe functions. To use the new quantum-safe functions you must download the EP11 support program version 4.0, which is available for free from the following site: https://www.ibm.com/docs/en/cryptocards?topic=4770-linux-z-software.
The shared secret used in the hybrid key derivation can be computed as usual using the PKCS #11 C_DeriveKey function with the CKM_ECDH1 mechanism with the following special settings:
the mechanism parameter’s kdf component must be set to CKD_IBM_HYBRID_NULL
the derived key object must have the attribute CKA_IBM_USE_AS_DATA set to CK_TRUE.
The mechanism to generate Kyber keys and to perform encapsulation and decapsulation operations is called CKM_IBM_KYBER. A call to the PKCS #11 function C_GenerateKeyPair with CKM_IBM_KYBER in the mechanism argument generates a pair of a public and a private Kyber key. The keys to be generated must have the attribute CKA_DERIVE set to CK_TRUE and the attribute CKA_IBM_KYBER_KEYFORM set to CK_IBM_KYBER_KEYFORM_ROUND2_768 or CK_IBM_KYBER_KEYFORM_ROUND2_1024 for a more secure variant. The following attributes from the public key object must be extracted (by Alice) using C_GetAttributeValue and to be sent to Bob such that Bob can reconstruct the public key on his system using the PKCS #11 function C_CreateObject:
CKA_CLASS
CKA_TYPE
CKA_VALUE
CKA_DERIVE
CKA_IBM_KYBER_PK
CKA_IBM_KYBER_KEYFORM (not necessary if CKA_IBM_KYBER_MODE is provided)
CKA_IBM_KYBER_MODE (not necessary if CKA_IBM_KYBER_KEYFORM is provided)
Both the Kyber encapsulate and decapsulate functions are called via the PKCS #11 function C_DeriveKey. The derived key to be be shared by Alice and Bob is returned in the output parameter of C_DeriveKey. All other parameters needed (including the indication whether the function shall encapsulate or decapsulate) are provided as components of the mechanism parameter (of type CK_IBM_KYBER_PARAMS) of the mechanism passed to C_DeriveKey.
The encapsulate function (called by Bob) can be invoked using the PKCS #11 C_DeriveKey function and the derived key will be returned in the output parameter of C_DeriveKey. The type and attributes of the derived key must be specified in an attribute templated passed to C_DeriveKey as usual. The CKM_IBM_KYBER mechanism passed to C_DeriveKey must have a mechanism parameter with the following components:
ulVersion: CK_IBM_KYBER_KEM_VERSION
mode: CK_IBM_KYBER_KEM_ENCAPSULATE
kdf: CKD_IBM_HYBRID_SHA256_KDF or another CKD_IBM_HYBRID_*_KDF value
bPrepend: CK_TRUE
pCipher: a buffer to contain the returned encrypted secret
ulCipherLen: the length of that buffer (2kB should be sufficient, the exact size of the encrypted secret is returned provided the buffer is large enough)
hSecret: the handle to the key object derived with ECDH to be used as shared secret
The decapsulate function (called by Alice) can be invoked using the PKCS #11 C_DeriveKey function and the derived key will be returned in the output parameter of C_DeriveKey. The type and attributes of the derived key must be specified in an attribute templated passed to C_DeriveKey as usual. The CKM_IBM_KYBER mechanism passed to C_DeriveKey must have a mechanism parameter with the following components:
ulVersion: CK_IBM_KYBER_KEM_VERSION
mode: CK_IBM_KYBER_KEM_DECAPSULATE
kdf: CKD_IBM_HYBRID_SHA256_KDF or another CKD_IBM_HYBRID_*_KDF value
bPrepend: CK_TRUE
pCipher: a buffer that contains the encrypted secret computed by the encapsulate function (from Bob)
ulCipherLen: the length of that secret
hSecret: the handle to the key object derived with ECDH to be used as shared secret
Now, the keys returned in the output parameter of Alice’s and Bob’s respective C_DeriveKey calls are cryptographically equivalent (yet protected by different HSM wrapping keys) and can be used to encrypt, decrypt, or MAC data to be exchanged between Alice and Bob.
For more details on the new quantum-safe functions provided by EP11 see the wire format chapter in the ep11-structure.pdf document included in the zip file of the EP11 support program.
openCryptoki v3.21 is out.
Lots of changes around EP11, including support for concurrent HSM master key changes.
For a detailed list of all changes, see the changelog.