OPENSSL_S390XCAP(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 OPENSSL_S390XCAP — the IBM z processor capabilities vector

okay bestie, welcome to the <openssl/s390xcap.h>-adjacent corner of the OpenSSL manuals, page OPENSSL_S390XCAP(3ossl). this one is genuinely niche and genuinely iconic: it's all about telling libcrypto which fancy mainframe instructions it's allowed to use on IBM z. stay with me, it's actually so clean once you see the pattern 🦋

✨ SYNOPSIS ✨

env OPENSSL_s390xcap=... <application>

that's it. one env var, one app, and vibes. 🎀

🌸 DESCRIPTION 🌸

so libcrypto supports z/Architecture instruction set extensions, and every single one of those extensions is denoted by an individual bit in the capabilities vector. when libcrypto is initialized, the bits returned by the STFLE instruction and by the QUERY functions get stored in that vector. no cap, that's just how it works. 💅

now, if you want to change the set of instructions available to an application, you set the OPENSSL_s390xcap environment variable before you start the application. after initialization, the capability vector is ANDed bitwise with a mask which is derived from that environment variable. think of the mask as a little filter sieve for features. 🫶

the environment variable is a semicolon-separated list of tokens which is processed from left to right (whitespace is ignored):

OPENSSL_s390xcap="<tok1>;<tok2>;..."

there are four types of tokens. four. i counted. 👑

🧚 <string>

the name of a processor generation. a bit in the environment variable's mask is set to one if and only if the specified processor generation implements the corresponding instruction set extension. the possible values are z900, z990, z9, z10, z196, zEC12, z13, z14, z15, and z16. that's the whole squad, oldest to newest. ⭐

🧚 <string>:<mask>:<mask>

the name of an instruction followed by two 64-bit masks. the part of the environment variable's mask corresponding to the specified instruction is set to the specified 128-bit mask. possible values are kimd, klmd, km, kmc, kmac, kmctr, kmo, kmf, prno, kma, pcc and kdsa. (yes, kmctr and prno are in the list even though their bit tables below are basically empty — that's not a typo, that's the original. 💀)

🧚 stfle:<mask>:<mask>:<mask>

store-facility-list-extended (stfle) followed by three 64-bit masks. the part of the environment variable's mask corresponding to the stfle instruction is set to the specified 192-bit mask. three masks = 192 bits, the math is mathing. 🔥

🧚 nocex

deactivate modular exponentiation and CRT operation offloading to Crypto Express Adapters. that's the whole description, she's short and she knows it.

the 64-bit masks are specified in hexadecimal notation. the 0x prefix is optional. prefix a mask with a tilde, "~", to denote a bitwise NOT operation. so ~0 is your "gimme everything" move. 🎀

the following is a list of significant bits for each instruction. colon rows separate the individual 64-bit masks. the bit numbers in the first column are consistent with [1], that is, 0 denotes the leftmost bit and the numbering is continuous across 64-bit mask boundaries. (iykyk — the colons are literally the mask boundaries, do not @ me.)

      Bit     Mask     Facility/Function

stfle:

      # 17    1<<46    message-security assist
      # 25    1<<38    store-clock-fast facility
      :
      # 76    1<<51    message-security assist extension 3
      # 77    1<<50    message-security assist extension 4
      # 86    1<<41    message-security-assist extension 12
      :
      #129    1<<62    vector facility
      #134    1<<57    vector packed decimal facility
      #135    1<<56    vector enhancements facility 1
      #146    1<<45    message-security assist extension 8
      #155    1<<36    message-security assist extension 9

kimd :

      #  1    1<<62    KIMD-SHA-1
      #  2    1<<61    KIMD-SHA-256
      #  3    1<<60    KIMD-SHA-512
      # 32    1<<31    KIMD-SHA3-224
      # 33    1<<30    KIMD-SHA3-256
      # 34    1<<29    KIMD-SHA3-384
      # 35    1<<28    KIMD-SHA3-512
      # 36    1<<27    KIMD-SHAKE-128
      # 37    1<<26    KIMD-SHAKE-256
      :
      # 65    1<<62    KIMD-GHASH

klmd :

      # 32    1<<31    KLMD-SHA3-224
      # 33    1<<30    KLMD-SHA3-256
      # 34    1<<29    KLMD-SHA3-384
      # 35    1<<28    KLMD-SHA3-512
      # 36    1<<27    KLMD-SHAKE-128
      # 37    1<<26    KLMD-SHAKE-256
      :

km :

      # 18    1<<45    KM-AES-128
      # 19    1<<44    KM-AES-192
      # 20    1<<43    KM-AES-256
      # 50    1<<13    KM-XTS-AES-128
      # 52    1<<11    KM-XTS-AES-256
      :
      # 82    1<<45    KM-XTS-AES-128-MSA10
      # 84    1<<43    KM-XTS-AES-256-MSA10

kmc :

      # 18    1<<45    KMC-AES-128
      # 19    1<<44    KMC-AES-192
      # 20    1<<43    KMC-AES-256
      :

kmac :

      # 18    1<<45    KMAC-AES-128
      # 19    1<<44    KMAC-AES-192
      # 20    1<<43    KMAC-AES-256
      :
      # 112   1<<15    KMAC-SHA-224
      # 113   1<<14    KMAC-SHA-256
      # 114   1<<13    KMAC-SHA-384
      # 115   1<<12    KMAC-SHA-512

kmctr:

      :

kmo :

      # 18    1<<45    KMO-AES-128
      # 19    1<<44    KMO-AES-192
      # 20    1<<43    KMO-AES-256
      :

kmf :

      # 18    1<<45    KMF-AES-128
      # 19    1<<44    KMF-AES-192
      # 20    1<<43    KMF-AES-256
      :

prno :

      :

kma :

      # 18    1<<45    KMA-GCM-AES-128
      # 19    1<<44    KMA-GCM-AES-192
      # 20    1<<43    KMA-GCM-AES-256
      :

pcc :

      :
      # 64    1<<63    PCC-Scalar-Multiply-P256
      # 65    1<<62    PCC-Scalar-Multiply-P384
      # 66    1<<61    PCC-Scalar-Multiply-P521
      # 72    1<<55    PCC-Scalar-Multiply-Ed25519
      # 73    1<<54    PCC-Scalar-Multiply-Ed448
      # 80    1<<47    PCC-Scalar-Multiply-X25519
      # 81    1<<46    PCC-Scalar-Multiply-X448

kdsa :

      #  1    1<<62    KDSA-ECDSA-Verify-P256
      #  2    1<<61    KDSA-ECDSA-Verify-P384
      #  3    1<<60    KDSA-ECDSA-Verify-P521
      #  9    1<<54    KDSA-ECDSA-Sign-P256
      # 10    1<<53    KDSA-ECDSA-Sign-P384
      # 11    1<<52    KDSA-ECDSA-Sign-P521
      # 32    1<<31    KDSA-EdDSA-Verify-Ed25519
      # 36    1<<27    KDSA-EdDSA-Verify-Ed448
      # 40    1<<23    KDSA-EdDSA-Sign-Ed25519
      # 44    1<<19    KDSA-EdDSA-Sign-Ed448
      :

💀 RETURN VALUES 💀

not available. that's it, that's the section. she said "no thoughts, head empty." 🙈

🌈 EXAMPLES 🌈

disables all instruction set extensions which the z196 processor does not implement:

OPENSSL_s390xcap="z196"

disables the vector facility:

OPENSSL_s390xcap="stfle:~0:~0:~0x4000000000000000"

disables the KM-XTS-AES and the KIMD-SHAKE function codes:

OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0"

look at those tildes go. bitwise NOT said "i'm the main character now." 🔥

🦋 SEE ALSO 🦋

  • [1] z/Architecture Principles of Operation, SA22-7832-12

Copyright 2018-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page, bestie 💖 this was OpenSSL 3.5.0, dated 2026-09-25, and the page itself is OPENSSL_S390XCAP(3ossl) — go forth and mask your capability vectors responsibly, periodt. ✨🎀🫶

📦 where this page comes from