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