doc/man3/OPENSSL_s390xcap.pod

   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 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
  37 are B<z900>, B<z990>, B<z9>, B<z10>, B<z196>, B<zEC12>, B<z13>, B<z14>
  38 and B<z15>.
  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 =back
  55
  56 The 64-bit masks are specified in hexadecimal notation. The 0x prefix is
  57 optional. Prefix a mask with a tilde, C<~>, to denote a bitwise NOT operation.
  58
  59 The following is a list of significant bits for each instruction. Colon
  60 rows separate the individual 64-bit masks. The bit numbers in the first
  61 column are consistent with [1], that is, 0 denotes the leftmost bit and
  62 the 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
 170 Not available.
 171
 172 =head1 EXAMPLES
 173
 174 Disables all instruction set extensions which the z196 processor does not implement:
 175
 176  OPENSSL_s390xcap="z196"
 177
 178 Disables the vector facility:
 179
 180  OPENSSL_s390xcap="stfle:~0:~0:~0x4000000000000000"
 181
 182 Disables 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
 192 Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved.
 193
 194 Licensed under the Apache License 2.0 (the "License").  You may not use
 195 this file except in compliance with the License.  You can obtain a copy
 196 in the file LICENSE in the source distribution or at
 197 L<https://www.openssl.org/source/license.html>.
 198
 199 =cut