Debian Codegraph @

doc/README.ep11_stdll

raw
1 EP11 Token
2 ==========
3
4 The EP11 token is a token that uses the IBM Crypto Express adapters (starting
5 with Crypto Express 4S adapters) configured with Enterprise PKCS#11 (EP11)
6 firmware. By convention, Crypto Express n adapters with that firmware load are
7 also called CEXnP adapters for n >= 4.
8
9 The EP11 token is only supported on the System z architecture and requires a
10 Crypto Express adapter with EP11 firmware load, a zcrypt/ap device driver loaded
11 into the kernel and the availability of EP11 library libep11.
12
13 The token directory of the EP11 token is opencryptoki/ep11tok typically located
14 in /var/lib.
15
16 There is a possibility to configure multiple EP11 tokens.
17 Thus dedicated adapter/domains can be assigned to different tokens respectively
18 applications. That ensures data isolation between multiple applications.
19
20 For more details about the EP11 token, please also see
21 https://www.ibm.com/docs/en/linux-on-systems?topic=specifications-ep11-token
22
23 Configuration
24 -------------
25
26 To use the EP11 token a slot entry must be defined in the general openCryptoki
27 configuration file that sets the stdll attribute to libpkcs11_ep11.so.
28
29 A EP11 token specific configuration file must be set up to define the target
30 adapters and target adapter domains. The name of the configuration file must be
31 defined in the global openCryptoki configuration opencryptoki.conf file as part
32 of the token specification using the confname attribute. In case of using
33 multiple ep11 tokens a token directory name must be specified for each token
34 using the tokname attribute.
35 E.g.
36
37 slot 4
38 {
39 stdll = libpkcs11_ep11.so
40 confname = ep11tok01.conf
41 tokname = ep11token01
42 }
43
44 slot 5
45 {
46 stdll = libpkcs11_ep11.so
47 confname = ep11tok02.conf
48 tokname = ep11token02
49 }
50
51 The sample entry define the name of the configuration files of the EP11 token
52 to be e.g. ep11tok01.conf. Per default this file is searched in the directory
53 where openCryptoki searches its global configuration file. This default path
54 can be overriden using the OCK_EP11_TOKEN_DIR environment variable.
55
56 The tokname attribute specifies the name of the individual token directory.
57 Typically it's located in /var/lib/opencryptoki/. Each token directory contain
58 it's own token individual objects that are separated from other ep11 tokens.
59
60 EP11 token configuration files defines a list of adapter/domain pairs to which
61 the EP11 token sends its cryptographic requests. This list can be specified as a
62 allow list starting with a line containing the key word APQN_ALLOWLIST followed
63 by one or more lines containing each two integers (in the range of 0 - 255)
64 separated by a white space. The allow list is ended with a line containing the
65 key word END. In each of lines of the allow list the first integer denotes the
66 adapter number and the second integer denotes the domain id. Alternatively the
67 keyword APQN_ANY can be used to define that all adapter/domain pairs with EP11
68 firmware load that are available to the system shall be used as target adapters.
69 An adapter number corresponds to the numerical part xx of an adapter id of the
70 form cardxx as displayed by the lszcrypt tool or in the sys file system (e.g. in
71 /sys/bus/ap/devices).
72
73 Crypto Express Adapter EP11 Master Key Management
74 -------------------------------------------------
75
76 If master keys are changed on an EP11 adapter all key objects in the token
77 object repository (in the TOK_OBJ directory within the EP11 token directory)
78 become invalid.
79
80 The key migration tool pkcsep11_migrate can be used to perform the migration of
81 the current EP11 master keys to new master keys. Therefore the following steps
82 must be performed:
83 1) On the Trusted Key Entry console (TKE): Submit and commit new master keys on
84 the EP11 adapter(s).
85 2) On Linux: Stop all processes using openCryptoki with the EP11 token.
86 3) On Linux: Back up the token object repository of the EP11 token.
87 4) On Linux: Migrate keys of object repository of EP11 token with migration
88 tool. If a failure occurs restore the backed up token repository and retry step
89 4.
90 5) On the TKE: Activate new master keys on the EP11 adapter(s).
91 6) On Linux: Restart applications using openCryptoki with the EP11 token.
92
93 Token specifics
94 ---------------
95
96 The EP11 token only supports secure keys (i.e. key wrapped by a master key of
97 the Crypto Express adapter). Therefore all keys should have the attribute
98 CKA_SENSITIVE set to CK_TRUE. Since the PKCS#11 standard does not define a
99 (token specific) default for secret keys the attribute must be explicitly
100 provided whenever a secret key is generated, unwrapped or build with
101 C_CreateObject. You can change the default for CKA_SENSITIVE to TRUE by
102 specifying keyword FORCE_SENSITIVE in the EP11 token config file.
103
104 When creating keys the default values of the attributes CKA_ENCRYPT,
105 CKA_DECRYPT, CKA_VERYFY, CKA_SIGN, CKA_WRAP and CKA_UNWRAP are CK_TRUE. Note, no
106 EP11 mechanism supports the Sign/Recover or Verify/Recover functions.
107
108 All RSA key must have a public exponent (CKA_PUBLIC_EXPONENT) greater than or
109 equal to 17.
110
111 The CryptoExpress EP11 coprocessor restricts RSA keys (primes and moduli)
112 according to ANSI X9.31. Therefore in the EP11 token the lengths of the RSA
113 primes (p or q) must be a multiple of 128 bits and the length of the modulus
114 (CKA_MODULUS_BITS) must be a multiple of 256.
115
116 The mechanisms CKM_DES3_CBC and CKM_AES_CBC can only wrap keys which have a
117 length that is a multiple of the block size of DES3 or AES respectively.
118
119 See the mechanism list and mechanism info (pkcsconf -m) for supported mechanisms
120 together with supported functions and key sizes. Note the supported mechanism
121 list is currently fix and matches the most stringent setting of the Crypto
122 Express adapter.
123
124 Note, the EP11 coprocessor adapter can be configured to restrict the
125 cryptographic capabilities in order for the adapter to comply with specific
126 security requirements and regulations. Such restrictions on the adapter impact
127 the capabilitiy of the EP11 token.