THE ICSF TOKEN Overview -------- The ICSF token is a clear-key, remote crypto token. The actual crypto operations are performed remotely on a 390x server and all the PKCS#11 key objects are stored remotely on the server. openCryptoki's ICSF token sends ICSF service calls to the remote server via LDAP. Extensions to LDAP and the addition of a remote crypto plugin allow the remote LDAP server to receive the request and interface with ICSF to service the request. ICSF interfaces with the crypto hardware and the z/OS keystore to service the request. Upon completion, the result is passed back through the same channels. The PKCS#11 key objects are created or generated remotely. The remote z/OS keystore stores all the created or generated key objects, allowing for centralized storage and key management. The remote server's configuration is outside the scope of this README. Please see XXXXX for more information on the z/OS LDAP server requirements and remote crypto configuration. For more information on ICSF PKCS#11, see "Writing PKCS#11 Applications" manual at http://www-01.ibm.com/support/docview.wss?uid=isg24664157d6cdc890485257a7c0054dc3d&aid=1. Pre-requisites: 1. ICSF token communicates to the remote via LDAP. On Linux install openldap, openldap-clients, and openldap-devel. 2. You will also need lex and yacc packages installed. ----------------------------------------------------------------------- CONFIGURING THE ICSF TOKEN Some setup of the ICSF token must be done for openCryptoki before initializing it with the pkcsconf utility. You will need, - LDAP bind information - The name of an ICSF token created on the remote server. LDAP Bind Information --------------------- openCryptoki must bind and authenticate to the remote LDAP server. openCryptoki supports the Simple and SASL authentication methods when authenticating with the remote LDAP server to send an ICSF service request. You have the option of using, 1. existing LDAP config files for the information required to bind and authenticate to the LDAP server. OR 2. you can give the information to openCryptoki to store and use when binding and authenticating to LDAP server. This is done through the pkcsiscf utility. The first option involves using an existing LDAP config file to bind and authenticate to the remote server. When openCryptoki calls the openldap function to bind and authenticate, the openldap function call will look for the ldaprc config file to acquire the information it needs to bind and authenticate to the server. When using this option, - with Simple authentication, you need to specify the authentication mechanism as simple when adding the ICSF token into openCryptoki with the pkcsicsf utility. You will also be prompted for the RACF password, which will be securely stored on disk by openCryptoki for subsequent use. - with SASL authentication, you need to specify the authentication mechanism as sasl when adding the ICSF token into opecryptoki with the pkcsicsf utility. SASL does not require an RACF password, so you will not be prompted for this information. **Note, when using the first option, users should have the same information in their .ldaprc files. The second option, chooses to give openCryptoki the necessary ldap credentials to store in an openCryptoki config file for subsequent use. With this option the credentials are stored in one place for all who access openCryptoki's ICSF token. When openCryptoki calls the openldap function to bind and authenticate, it will pass along the information stored in the ICFS config file to the function call. For example, when simple authentication, it will pass the BINDDN and URI found in this config file to the function. When using this option, - with Simple authentication, you need to specify the authentication mechanism as simple, along with the BINDDN, and the URI when adding the ICSF token into openCryptoki with the pkcsicsf utility. You will also be prompted for the RACF password, which will be securely stored on disk for subsequent use by openCryptoki. - with SASL authentication, you need to specify the authentication mechanism as sasl, along with the CERT, CACERT, and KEY when adding the ICSF token into openCryptoki with the pkcsiscf utility. SASL does not require an RACF password, so you will not be prompted for it. When required, the RACF password is stored securely on disk for subsequent use in /prefix/var/lib/opencryptoki/icsf/RACF. **Note: Setup of LDAP and SASL are outside the scope of this README. openCryptoki's ICSF token setup ------------------------------- The installed opencryptoki.conf does not contain an entry for the ICSF token. An entry is created upon setting up the ICSF token with the pkcsicsf utility. openCryptoki's ICSF token must first be set up with the pkcsiscf utility before the token can be initialized with the pkcsconf utility. Setup ----- ICSF token(s) originate on the remote server. It is likely that they are created and destroyed by the remote's system administrator. openCryptoki queries the remote server for a list of the available ICSF tokens via the pkcsicsf utility. The list returned may contain more than one remote token. Note, which token(s) returned depend on the caller's SAF authority on the remote server. openCryptoki can only handle one remote ICSF token. If a list of tokens are returned from the query, a single token must be chosen and installed into openCryptoki with the pkcsicsf utility. Upon adding the token into openCryptoki with the pkcsicsf utility, an ICSF token entry will be created in the openCryptoki.conf file. For example, slot 5 { stdll = libpkcs11_icsf.so confname = /usr/local/etc/opencryptoki/JML.conf } Also, a separate ICSF token config file will be created, /prefix/etc/opencryptoki/.conf, containing information required to bind to the LDAP server if any was specified. It will also contain information from the remote server about the particular ICSF token that was added. In this example, /usr/local/etc/opencryptoki/JML.conf was created. And since I am using .ldaprc file, it only specifies the authentication method. slot 5 { TOKEN_NAME = "JML" TOKEN_MANUFACTURE = "IBM" TOKEN_MODEL = "ICSFModel" TOKEN_SERIAL = "012345" MECH = "SIMPLE" } And lastly, when using simple authentication, a secured RACF password file will have been created. EXAMPLE OF HOW TO CONFIGURE THE ICSF TOKEN ------------------------------------------ First, get a list of the available tokens from the remote server. From the list choose one token and add it into openCryptoki. After successfully adding the ICSF token and any relatedinformation into openCryptoki, initialize the ICSF token. Examples to get a list of available tokens ------------------------------------------- 1. Using simple authentication and .ldaprc which has BINDDN and URI set in it, get a list of the available tokens from the remote. pkcsicsf -l -m simple you will be prompted for the racf passwd and the SO PIN. you should get a list of the available tokens from the remote 2. Using simple authentication and giving openCryptoki the credentials to use to get a list of available tokens from the remote. pkcsicsf -l -b -u -m simple you will be prompted for the racf passwd and the SO PIN. you should get a list of the available tokens from the remote 3. Using sasl authentication and ldap configuration files, get list of available tokens from the remote. pkcsicsf -l -m sasl 4. Using sasl authentication and giving openCryptoki the credentials to use to get a list of available tokens from the remote. (TO DO) Examples to add a token into openCryptoki ----------------------------------------- 1. Using simple authentication and .ldaprc which has BINDDN and URI set in it, add the token named, Foo. pkcsicsf -a Foo -m simple you will be prompted for the racf passwd and the SO PIN. An entry for the token should have been added in the /usr/local/etc/opencryptoki/opencryptoki.conf file AND /usr/local/etc/opencryptoki/Foo.conf should have been created. The racf passwd should have been secured in /usr/local/var/lib/opencryptoki/icsf/RACF. 2. Using simple authentication and giving openCryptoki the credentials to use, add the ICSF token named, Foo. In this case, the credentials (the BINDDN and URI) will be stored in the Foo.conf file that will be created. pkcsicsf -a Foo -b -u -m simple pkcsicsf -l -b -u -m simple you will be prompted for the racf passwd and the SO PIN. An entry for the token should have been added in the /usr/local/etc/opencryptoki/opencryptoki.conf file AND /usr/local/etc/opencryptoki/Foo.conf should have been created. The racf passwd should have been secured in /usr/local/var/lib/opencryptoki/icsf/RACF. 3. Using sasl authentication and ldap configuration files to authenticate, add an ICSF token named, Foo into openCryptoki. pkcsicsf -a Foo -m sasl 4. Using sasl authentication and giving openCryptoki the credentials to use to get a list of available tokens from the remote. (TO DO) Configure openCryptoki ---------------------- Now initialize the ICSF token and set the USER and SO PINs using the pkcsconf utility. 1. Start the pkcsslotd daemon pkcsslotd 2. List the available tokens in openCryptoki pkcsconf -t 3. Initialize the ICSF token. NOTE: For this example, my ICSF token is listed in slot 5. pkcsconf -I -c 5 You will be prompted for the SO PIN. The default SO PIN is 87654321 You will also be prompted to enter a unique token label. You can press enter since this will be ignored. The label or name has already been created on the remote server. 4. Set the user pin pkcsconf -u -c 5 you will be prompted to enter the SO PIN. Enter the default SO PIN, 87654321. You will be prompted twice to enter the new user PIN. Enter 8 digits for the new user pin. Remember it so you can use it later. 6. Set a new SO PIN pkcsconf -P -c 5 you will be prompted to enter the SO PIN. Enter the default SO PIN, 87654321. You will then be prompted to enter the new SO PIN. Enter 8 digits for the new SO PIN. Remember it for later use. 7. List the token and ensure it is ready. pkcsconf -t -c 5 Sample output: pkcsconf -t -c 5 Token #5 Info: Label: JML Manufacturer: IBM Model: ICSF Model Serial Number: 012345 Flags: 0x44D (RNG|LOGIN_REQUIRED|USER_PIN_INITIALIZED|CLOCK_ON_TOKEN|TOKEN_INITIALIZED) Sessions: 0/-2 R/W Sessions: -1/-2 PIN Length: 4-8 Public Memory: 0xFFFFFFFF/0xFFFFFFFF Private Memory: 0xFFFFFFFF/0xFFFFFFFF Hardware Version: 1.0 Firmware Version: 1.0 Time: 22:09:20 You are now done configuring the ICSF token into openCryptoki and its ready to be used.