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