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 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