| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | OPENSSL_s390xcap - the IBM z processor capabilities vector
|
|---|
| 6 |
|
|---|
| 7 | =head1 SYNOPSIS
|
|---|
| 8 |
|
|---|
| 9 | env OPENSSL_s390xcap=... <application>
|
|---|
| 10 |
|
|---|
| 11 | =head1 DESCRIPTION
|
|---|
| 12 |
|
|---|
| 13 | libcrypto supports z/Architecture instruction set extensions. These
|
|---|
| 14 | extensions are denoted by individual bits in the capabilities vector.
|
|---|
| 15 | When libcrypto is initialized, the bits returned by the STFLE instruction
|
|---|
| 16 | and by the QUERY functions are stored in the vector.
|
|---|
| 17 |
|
|---|
| 18 | To change the set of instructions available to an application, you can
|
|---|
| 19 | set the B<OPENSSL_s390xcap> environment variable before you start the
|
|---|
| 20 | application. After initialization, the capability vector is ANDed bitwise
|
|---|
| 21 | with a mask which is derived from the environment variable.
|
|---|
| 22 |
|
|---|
| 23 | The environment variable is a semicolon-separated list of tokens which is
|
|---|
| 24 | processed from left to right (whitespace is ignored):
|
|---|
| 25 |
|
|---|
| 26 | OPENSSL_s390xcap="<tok1>;<tok2>;..."
|
|---|
| 27 |
|
|---|
| 28 | There are four types of tokens:
|
|---|
| 29 |
|
|---|
| 30 | =over 4
|
|---|
| 31 |
|
|---|
| 32 | =item <string>
|
|---|
| 33 |
|
|---|
| 34 | The name of a processor generation. A bit in the environment variable's
|
|---|
| 35 | mask is set to one if and only if the specified processor generation
|
|---|
| 36 | implements the corresponding instruction set extension. Possible values
|
|---|
| 37 | are B<z900>, B<z990>, B<z9>, B<z10>, B<z196>, B<zEC12>, B<z13>, B<z14>,
|
|---|
| 38 | B<z15>, and B<z16>.
|
|---|
| 39 |
|
|---|
| 40 | =item <string>:<mask>:<mask>
|
|---|
| 41 |
|
|---|
| 42 | The name of an instruction followed by two 64-bit masks. The part of the
|
|---|
| 43 | environment variable's mask corresponding to the specified instruction is
|
|---|
| 44 | set to the specified 128-bit mask. Possible values are B<kimd>, B<klmd>,
|
|---|
| 45 | B<km>, B<kmc>, B<kmac>, B<kmctr>, B<kmo>, B<kmf>, B<prno>, B<kma>, B<pcc>
|
|---|
| 46 | and B<kdsa>.
|
|---|
| 47 |
|
|---|
| 48 | =item stfle:<mask>:<mask>:<mask>
|
|---|
| 49 |
|
|---|
| 50 | Store-facility-list-extended (stfle) followed by three 64-bit masks. The
|
|---|
| 51 | part of the environment variable's mask corresponding to the stfle
|
|---|
| 52 | instruction is set to the specified 192-bit mask.
|
|---|
| 53 |
|
|---|
| 54 | =item nocex
|
|---|
| 55 |
|
|---|
| 56 | Deactivate modular exponentiation and CRT operation offloading to
|
|---|
| 57 | Crypto Express Adapters.
|
|---|
| 58 |
|
|---|
| 59 | =back
|
|---|
| 60 |
|
|---|
| 61 | The 64-bit masks are specified in hexadecimal notation. The 0x prefix is
|
|---|
| 62 | optional. Prefix a mask with a tilde, C<~>, to denote a bitwise NOT operation.
|
|---|
| 63 |
|
|---|
| 64 | The following is a list of significant bits for each instruction. Colon
|
|---|
| 65 | rows separate the individual 64-bit masks. The bit numbers in the first
|
|---|
| 66 | column are consistent with [1], that is, 0 denotes the leftmost bit and
|
|---|
| 67 | the numbering is continuous across 64-bit mask boundaries.
|
|---|
| 68 |
|
|---|
| 69 | Bit Mask Facility/Function
|
|---|
| 70 |
|
|---|
| 71 | stfle:
|
|---|
| 72 | # 17 1<<46 message-security assist
|
|---|
| 73 | # 25 1<<38 store-clock-fast facility
|
|---|
| 74 | :
|
|---|
| 75 | # 76 1<<51 message-security assist extension 3
|
|---|
| 76 | # 77 1<<50 message-security assist extension 4
|
|---|
| 77 | :
|
|---|
| 78 | #129 1<<62 vector facility
|
|---|
| 79 | #134 1<<57 vector packed decimal facility
|
|---|
| 80 | #135 1<<56 vector enhancements facility 1
|
|---|
| 81 | #146 1<<45 message-security assist extension 8
|
|---|
| 82 | #155 1<<36 message-security assist extension 9
|
|---|
| 83 |
|
|---|
| 84 | kimd :
|
|---|
| 85 | # 1 1<<62 KIMD-SHA-1
|
|---|
| 86 | # 2 1<<61 KIMD-SHA-256
|
|---|
| 87 | # 3 1<<60 KIMD-SHA-512
|
|---|
| 88 | # 32 1<<31 KIMD-SHA3-224
|
|---|
| 89 | # 33 1<<30 KIMD-SHA3-256
|
|---|
| 90 | # 34 1<<29 KIMD-SHA3-384
|
|---|
| 91 | # 35 1<<28 KIMD-SHA3-512
|
|---|
| 92 | # 36 1<<27 KIMD-SHAKE-128
|
|---|
| 93 | # 37 1<<26 KIMD-SHAKE-256
|
|---|
| 94 | :
|
|---|
| 95 | # 65 1<<62 KIMD-GHASH
|
|---|
| 96 |
|
|---|
| 97 | klmd :
|
|---|
| 98 | # 32 1<<31 KLMD-SHA3-224
|
|---|
| 99 | # 33 1<<30 KLMD-SHA3-256
|
|---|
| 100 | # 34 1<<29 KLMD-SHA3-384
|
|---|
| 101 | # 35 1<<28 KLMD-SHA3-512
|
|---|
| 102 | # 36 1<<27 KLMD-SHAKE-128
|
|---|
| 103 | # 37 1<<26 KLMD-SHAKE-256
|
|---|
| 104 | :
|
|---|
| 105 |
|
|---|
| 106 | km :
|
|---|
| 107 | # 18 1<<45 KM-AES-128
|
|---|
| 108 | # 19 1<<44 KM-AES-192
|
|---|
| 109 | # 20 1<<43 KM-AES-256
|
|---|
| 110 | # 50 1<<13 KM-XTS-AES-128
|
|---|
| 111 | # 52 1<<11 KM-XTS-AES-256
|
|---|
| 112 | :
|
|---|
| 113 |
|
|---|
| 114 | kmc :
|
|---|
| 115 | # 18 1<<45 KMC-AES-128
|
|---|
| 116 | # 19 1<<44 KMC-AES-192
|
|---|
| 117 | # 20 1<<43 KMC-AES-256
|
|---|
| 118 | :
|
|---|
| 119 |
|
|---|
| 120 | kmac :
|
|---|
| 121 | # 18 1<<45 KMAC-AES-128
|
|---|
| 122 | # 19 1<<44 KMAC-AES-192
|
|---|
| 123 | # 20 1<<43 KMAC-AES-256
|
|---|
| 124 | :
|
|---|
| 125 |
|
|---|
| 126 | kmctr:
|
|---|
| 127 | :
|
|---|
| 128 |
|
|---|
| 129 | kmo :
|
|---|
| 130 | # 18 1<<45 KMO-AES-128
|
|---|
| 131 | # 19 1<<44 KMO-AES-192
|
|---|
| 132 | # 20 1<<43 KMO-AES-256
|
|---|
| 133 | :
|
|---|
| 134 |
|
|---|
| 135 | kmf :
|
|---|
| 136 | # 18 1<<45 KMF-AES-128
|
|---|
| 137 | # 19 1<<44 KMF-AES-192
|
|---|
| 138 | # 20 1<<43 KMF-AES-256
|
|---|
| 139 | :
|
|---|
| 140 |
|
|---|
| 141 | prno :
|
|---|
| 142 | :
|
|---|
| 143 |
|
|---|
| 144 | kma :
|
|---|
| 145 | # 18 1<<45 KMA-GCM-AES-128
|
|---|
| 146 | # 19 1<<44 KMA-GCM-AES-192
|
|---|
| 147 | # 20 1<<43 KMA-GCM-AES-256
|
|---|
| 148 | :
|
|---|
| 149 |
|
|---|
| 150 | pcc :
|
|---|
| 151 | :
|
|---|
| 152 | # 64 1<<63 PCC-Scalar-Multiply-P256
|
|---|
| 153 | # 65 1<<62 PCC-Scalar-Multiply-P384
|
|---|
| 154 | # 66 1<<61 PCC-Scalar-Multiply-P521
|
|---|
| 155 | # 72 1<<55 PCC-Scalar-Multiply-Ed25519
|
|---|
| 156 | # 73 1<<54 PCC-Scalar-Multiply-Ed448
|
|---|
| 157 | # 80 1<<47 PCC-Scalar-Multiply-X25519
|
|---|
| 158 | # 81 1<<46 PCC-Scalar-Multiply-X448
|
|---|
| 159 |
|
|---|
| 160 | kdsa :
|
|---|
| 161 | # 1 1<<62 KDSA-ECDSA-Verify-P256
|
|---|
| 162 | # 2 1<<61 KDSA-ECDSA-Verify-P384
|
|---|
| 163 | # 3 1<<60 KDSA-ECDSA-Verify-P521
|
|---|
| 164 | # 9 1<<54 KDSA-ECDSA-Sign-P256
|
|---|
| 165 | # 10 1<<53 KDSA-ECDSA-Sign-P384
|
|---|
| 166 | # 11 1<<52 KDSA-ECDSA-Sign-P521
|
|---|
| 167 | # 32 1<<31 KDSA-EdDSA-Verify-Ed25519
|
|---|
| 168 | # 36 1<<27 KDSA-EdDSA-Verify-Ed448
|
|---|
| 169 | # 40 1<<23 KDSA-EdDSA-Sign-Ed25519
|
|---|
| 170 | # 44 1<<19 KDSA-EdDSA-Sign-Ed448
|
|---|
| 171 | :
|
|---|
| 172 |
|
|---|
| 173 | =head1 RETURN VALUES
|
|---|
| 174 |
|
|---|
| 175 | Not available.
|
|---|
| 176 |
|
|---|
| 177 | =head1 EXAMPLES
|
|---|
| 178 |
|
|---|
| 179 | Disables all instruction set extensions which the z196 processor does not implement:
|
|---|
| 180 |
|
|---|
| 181 | OPENSSL_s390xcap="z196"
|
|---|
| 182 |
|
|---|
| 183 | Disables the vector facility:
|
|---|
| 184 |
|
|---|
| 185 | OPENSSL_s390xcap="stfle:~0:~0:~0x4000000000000000"
|
|---|
| 186 |
|
|---|
| 187 | Disables the KM-XTS-AES and the KIMD-SHAKE function codes:
|
|---|
| 188 |
|
|---|
| 189 | OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0"
|
|---|
| 190 |
|
|---|
| 191 | =head1 SEE ALSO
|
|---|
| 192 |
|
|---|
| 193 | [1] z/Architecture Principles of Operation, SA22-7832-12
|
|---|
| 194 |
|
|---|
| 195 | =head1 COPYRIGHT
|
|---|
| 196 |
|
|---|
| 197 | Copyright 2018-2023 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 198 |
|
|---|
| 199 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 200 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 201 | in the file LICENSE in the source distribution or at
|
|---|
| 202 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 203 |
|
|---|
| 204 | =cut
|
|---|
