diff options
| -rw-r--r-- | doc/man3/OPENSSL_s390xcap.pod | 173 | ||||
| -rw-r--r-- | util/private.num | 1 |
2 files changed, 174 insertions, 0 deletions
diff --git a/doc/man3/OPENSSL_s390xcap.pod b/doc/man3/OPENSSL_s390xcap.pod new file mode 100644 index 0000000000..550136a82b --- /dev/null +++ b/doc/man3/OPENSSL_s390xcap.pod @@ -0,0 +1,173 @@ +=pod + +=head1 NAME + +OPENSSL_s390xcap - the IBM z processor capabilities vector + +=head1 SYNOPSIS + + env OPENSSL_s390xcap=... <application> + +=head1 DESCRIPTION + +libcrypto supports z/Architecture instruction set extensions. These +extensions are denoted by individual bits in the capabilities vector. +When libcrypto is initialized, the bits returned by the STFLE instruction +and by the QUERY functions are stored in the vector. + +To change the set of instructions available to an application, you can +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 the environment variable. + +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 three types of tokens: + +=over 4 + +=item <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. Possible values +are z900, z990, z9, z10, z196, zEC12, z13 and z14. + +=item <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 and kma. + +=item 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. + +=back + +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. + +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. + + 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 + : + #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 + + 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 + : + + 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 + : + + 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 + : + +=head1 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 and the KIMD-SHAKE function codes: + + OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0" + +=head1 RETURN VALUES + +Not available. + +=head1 SEE ALSO + +[1] z/Architecture Principles of Operation, SA22-7832-11 + +=head1 COPYRIGHT + +Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/util/private.num b/util/private.num index c456578c33..2bfe987b43 100644 --- a/util/private.num +++ b/util/private.num @@ -3,6 +3,7 @@ # assembly language, etc. # OPENSSL_ia32cap environment +OPENSSL_s390xcap environment OPENSSL_MALLOC_FD environment OPENSSL_MALLOC_FAILURES environment OPENSSL_instrument_bus assembler |