|
Packit |
8681c6 |
EP11 Token
|
|
Packit |
8681c6 |
==========
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The EP11 token is a token that uses the IBM Crypto Express adapters (starting
|
|
Packit |
8681c6 |
with Crypto Express 4S adapters) configured with Enterprise PKCS#11 (EP11)
|
|
Packit |
8681c6 |
firmware. By convention, Crypto Express n adapters with that firmware load are
|
|
Packit |
8681c6 |
also called CEXnP adapters for n >= 4.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The EP11 token is only supported on the System z architecture and requires a
|
|
Packit |
8681c6 |
Crypto Express adapter with EP11 firmware load, a zcrypt/ap device driver loaded
|
|
Packit |
8681c6 |
into the kernel and the availability of EP11 library libep11.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The token directory of the EP11 token is opencryptoki/ep11tok typically located
|
|
Packit |
8681c6 |
in /var/lib.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
There is a new possibility to configure multiple EP11 tokens.
|
|
Packit |
8681c6 |
Thus dedicated adapter/domains can be assigned to different tokens respectively
|
|
Packit |
8681c6 |
applications. That ensures data isolation between multiple applications.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Configuration
|
|
Packit |
8681c6 |
-------------
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
To use the EP11 token a slot entry must be defined in the general openCryptoki
|
|
Packit |
8681c6 |
configuration file that sets the stdll attribute to libpkcs11_ep11.so.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
A EP11 token specific configuration file must be set up to define the target
|
|
Packit |
8681c6 |
adapters and target adapter domains. The name of the configuration file must be
|
|
Packit |
8681c6 |
defined in the global openCryptoki configuration opencryptoki.conf file as part
|
|
Packit |
8681c6 |
of the token specification using the confname attribute. In case of using
|
|
Packit |
8681c6 |
multiple ep11 tokens a token directory name must be specified for each token
|
|
Packit |
8681c6 |
using the tokname attribute.
|
|
Packit |
8681c6 |
E.g.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
slot 4
|
|
Packit |
8681c6 |
{
|
|
Packit |
8681c6 |
stdll = libpkcs11_ep11.so
|
|
Packit |
8681c6 |
confname = ep11tok01.conf
|
|
Packit |
8681c6 |
tokname = ep11token01
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
slot 5
|
|
Packit |
8681c6 |
{
|
|
Packit |
8681c6 |
stdll = libpkcs11_ep11.so
|
|
Packit |
8681c6 |
confname = ep11tok02.conf
|
|
Packit |
8681c6 |
tokname = ep11token02
|
|
Packit |
8681c6 |
}
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The sample entry define the name of the configuration files of the EP11 token
|
|
Packit |
8681c6 |
to be e.g. ep11tok01.conf. Per default this file is searched in the directory
|
|
Packit |
8681c6 |
where openCryptoki searches its global configuration file. This default path
|
|
Packit |
8681c6 |
can be overriden using the OCK_EP11_TOKEN_DIR environment variable.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The tokname attribute specifies the name of the individual token directory.
|
|
Packit |
8681c6 |
Typically it's located in /var/lib/opencryptoki/. Each token directory contain
|
|
Packit |
8681c6 |
it's own token individual objects that are separated from other ep11 tokens.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
EP11 token configuration files defines a list of adapter/domain pairs to which
|
|
Packit |
8681c6 |
the EP11 token sends its cryptographic requests. This list can be specified as a
|
|
Packit |
8681c6 |
white list starting with a line containing the key word APQN_WHITELIST followed
|
|
Packit |
8681c6 |
by one or more lines containing each two integers (in the range of 0 - 255)
|
|
Packit |
8681c6 |
separated by a white space. The white list is ended with a line containing the
|
|
Packit |
8681c6 |
key word END. In each of lines of the white list the first integer denotes the
|
|
Packit |
8681c6 |
adapter number and the second integer denotes the domain id. Alternatively the
|
|
Packit |
8681c6 |
keyword APQN_ANY can be used to define that all adapter/domain pairs with EP11
|
|
Packit |
8681c6 |
firmware load that are available to the system shall be used as target adapters.
|
|
Packit |
8681c6 |
An adapter number corresponds to the numerical part xx of an adapter id of the
|
|
Packit |
8681c6 |
form cardxx as displayed by the lszcrypt tool or in the sys file system (e.g. in
|
|
Packit |
8681c6 |
/sys/bus/ap/devices). Currently Linux on z only supports a single domain. That
|
|
Packit |
8681c6 |
domain number can be displayed with lszcrypt -b (see the value of ap_domain) or
|
|
Packit |
8681c6 |
alternatively as contents of /sys/bus/ap/ap_domain.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Crypto Express Adapter EP11 Master Key Management
|
|
Packit |
8681c6 |
-------------------------------------------------
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
If master keys are changed on an EP11 adapter all key objects in the token
|
|
Packit |
8681c6 |
object repository (in the TOK_OBJ directory within the EP11 token directory)
|
|
Packit |
8681c6 |
become invalid.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The key migration tool pkcsep11_migrate can be used to perform the migration of
|
|
Packit |
8681c6 |
the current EP11 master keys to new master keys. Therefore the following steps
|
|
Packit |
8681c6 |
must be performed:
|
|
Packit |
8681c6 |
1) On the Trusted Key Entry console (TKE): Submit and commit new master keys on
|
|
Packit |
8681c6 |
the EP11 adapter(s).
|
|
Packit |
8681c6 |
2) On Linux: Stop all processes using openCryptoki with the EP11 token.
|
|
Packit |
8681c6 |
3) On Linux: Back up the token object repository of the EP11 token.
|
|
Packit |
8681c6 |
4) On Linux: Migrate keys of object repository of EP11 token with migration
|
|
Packit |
8681c6 |
tool. If a failure occurs restore the backed up token repository and retry step
|
|
Packit |
8681c6 |
4.
|
|
Packit |
8681c6 |
5) On the TKE: Activate new master keys on the EP11 adapter(s).
|
|
Packit |
8681c6 |
6) On Linux: Restart applications using openCryptoki with the EP11 token.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Token specifics
|
|
Packit |
8681c6 |
---------------
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The EP11 token only supports secure keys (i.e. key wrapped by a master key of
|
|
Packit |
8681c6 |
the Crypto Express adapter). Therefore all keys must have the attribute
|
|
Packit |
8681c6 |
CKA_SENSITIVE set to CK_TRUE. Since the PKCS#11 standard does not define a
|
|
Packit |
8681c6 |
(token specific) default for secret keys the attribute must be explicitly
|
|
Packit |
8681c6 |
provided whenever a secret key is generated, unwrapped or build with
|
|
Packit |
8681c6 |
C_CreateObject. In addition all keys used with the EP11 token are extractable.
|
|
Packit |
8681c6 |
i.e. they must have the attribute CKA_EXTRACTABLE set to CK_TRUE.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
When creating keys the default values of the attributes CKA_ENCRYPT,
|
|
Packit |
8681c6 |
CKA_DECRYPT, CKA_VERYFY, CKA_SIGN, CKA_WRAP and CKA_UNWRAP are CK_TRUE. Note, no
|
|
Packit |
8681c6 |
EP11 mechanism supports the Sign/Recover or Verify/Recover functions.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
All RSA key must have a public exponent (CKA_PUBLIC_EXPONENT) greater than or
|
|
Packit |
8681c6 |
equal to 17.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The CryptoExpress EP11 coprocessor restricts RSA keys (primes and moduli)
|
|
Packit |
8681c6 |
according to ANSI X9.31. Therefore in the EP11 token the lengths of the RSA
|
|
Packit |
8681c6 |
primes (p or q) must be a multiple of 128 bits and the length of the modulus
|
|
Packit |
8681c6 |
(CKA_MODULUS_BITS) must be a multiple of 256.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
The mechanisms CKM_DES3_CBC and CKM_AES_CBC can only wrap keys which have a
|
|
Packit |
8681c6 |
length that is a multiple of the block size of DES3 or AES respectively.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
See the mechanism list and mechanism info (pkcsconf -m) for supported mechanisms
|
|
Packit |
8681c6 |
together with supported functions and key sizes. Note the supported mechanism
|
|
Packit |
8681c6 |
list is currently fix and matches the most stringent setting of the Crypto
|
|
Packit |
8681c6 |
Express adapter.
|
|
Packit |
8681c6 |
|
|
Packit |
8681c6 |
Note, the EP11 coprocessor adapter can be configured to restrict the
|
|
Packit |
8681c6 |
cryptographic capabilities in order for the adapter to comply with specific
|
|
Packit |
8681c6 |
security requirements and regulations. Such restrictions on the adapter impact
|
|
Packit |
8681c6 |
the capabilitiy of the EP11 token.
|