README.icsf_stdll

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/<tokenname>.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 <binddn> -u <uri> -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 <binddn> -u <uri> -m simple

        pkcsicsf -l -b <binddn> -u <uri> -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.