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