PKI 10.5 CMC Shared Token

Introduction

In PKI 10.4 CMC Update we touched upon the possible design for CMC Shared Token. In PKI 10.5 we are taking a closer look at the design and provide a minimum implementation to support:

IdentifyProofV2
popLinkWitnessV2
revokeRequest

Design

Framework

SharedSecret will be a special implementation of the IAuthentication interface. Unlike the real authentication plugin, the SharedSecret plugin implements a bogus authenticate() method, as it is not the intended use. Instead, the getSharedToken() method as intended for the ISharedToken interface is the actual method to be called by CMC operations for retrieving the shared secret or verification purpose.

Configuration

As one of the IAuthentication plugins and DirBasedAuthentication extensions, the SharedSecret class shares the same configuration as the other like authentication plugins.

Here is an example:

auths.impl.SharedToken.class=com.netscape.cms.authentication.SharedSecret
...
auths.instance.SharedToken.dnpattern=
auths.instance.SharedToken.ldap.basedn=ou=People,dc=example,dc=com
auths.instance.SharedToken.ldap.ldapauth.authtype=BasicAuth
auths.instance.SharedToken.ldap.ldapauth.bindDN=CN=Directory Manager
auths.instance.SharedToken.ldap.ldapauth.bindPWPrompt=internaldb
auths.instance.SharedToken.ldap.ldapauth.clientCertNickname=
auths.instance.SharedToken.ldap.ldapconn.host=example.com
auths.instance.SharedToken.ldap.ldapconn.port=389
auths.instance.SharedToken.ldap.ldapconn.secureConn=false
auths.instance.SharedToken.ldap.ldapconn.version=3
auths.instance.SharedToken.ldap.maxConns=
auths.instance.SharedToken.ldap.minConns=
auths.instance.SharedToken.ldapByteAttributes=
auths.instance.SharedToken.ldapStringAttributes=mail
auths.instance.SharedToken.pluginName=SharedToken
auths.instance.SharedToken.shrTokAttr=shrTok

Note that while the shared token attribute, auths.instance.SharedToken.shrTokAttr, for enrollment is configurable as exemplified above, the shared token MetaInfo attribute for revocation is not configuration and stays as revShrTok (see example below).

Protection

The implementation will be pretty much what’s described in Protection. It is the same mechanism adopted by various key/secret archival features provided by KRA.

By default, the subsystem certificate (specified under cert.subsystem.nickname in the CA’s CS.cfg), is used as the issuance protection certification. However, it is strongly advised that the administrator generate a different system certificate and dedicate that to this role. To configure such dedicated issuance protection certificate, the configuration parameter, cert.issuance_protection.nickname, must be specified. e.g.:

ca.cert.issuance_protection.nickname=CA Inssuance Protection cert-pki-tomcat CA

Client Tool

A new tool, CMCSharedToken is provided in this release to assist administrators in generating the encrypted Shared Token entries for users. This tool has the follow feature:

Usage: CMCSharedToken [OPTIONS]
       If the issuance protection cert was previously imported into the
       nss database, then -n <nickname> can be used instead of -b <PEM>

Options:
  -d <database>                Security database location (default: current directory)
  -h <token>                   Security token name (default: internal)
  -p <passphrase>              CMC enrollment passphrase (put in "" if containing spaces)
  -b <issuance protection cert>          PEM issuance protection certificate
  -n <issuance protection cert nickname>          issuance protection certificate nickname
To store the base-64 secret data, the following options are required:
  -o <output>                  Output file to store base-64 secret data

  -v, --verbose                Run in verbose mode.
      --help                   Show help message.

Workflow

This section outlines the intended workflow for this feature. There are two different workflow choices:

Shared secret (passphrase) created by the end entity user (preferred)
Shared secret (passphrase) generated by the CA administrator

Shared Secret created by the end entity user (preferred)

End entity user obtains Protection certificate from the CA administrator
End entity user runs CMCSharedToken tool (see man CMCSharedToken). Note the following:
- See the Protection section above to understand what Issuance Protection certificate to use for -b
- The -p option is for the passphrase that is to be shared between the CA and the individual user, not the password to the token
End entity user sends the resulting (encrypted) shared token to the administrator
Administrator puts the shared token into the shrTok attribute of the individual user’s LDAP record (see example below)
End entity user uses the passphrase to set the witness.sharedSecret parameter in the CMCRequest config file per instruction in PKI 10.4 CMC Update

Shared Secret generated by the CA administrator

Administrator thinks of a passphrase that is to be shared with an individual user.
Administrator runs the CMCSharedToken tool as instructed to prepare for user’s LDAP record.. Note the following:
- See the Protection section above to understand what Issuance Protection certificate to use for -b
- The -p option is for the passphrase that is to be shared between the CA and the individual user, not the password to the token
Administrator puts the result of the CMCSharedToken into the shrTok attribute of the individual user’s LDAP record (see example below)
Administrator shares the passphrase with the individual user
The user takes the passphrase received from the administrator and set the witness.sharedSecret parameter in the CMCRequest config file per instruction in PKI 10.4 CMC Update

Directory Configuration

In the case that a corporate LDAP server exists for user entries, you need to setup a couple things:

ACI

Proper ACI should be added to shield the shrTok attribute from the general public.

LDAP password

For an external LDAP server such as a corporate LDAP server used for CMC shared token feature, the LDAP server password needs to be added to allow CS to start or restart without human interaction.

There are two ways the LDAP password can be added:

without nuxwdog: add the bindPWPrompt value and its password to the password.conf configuration file under:
- e.g.if /var/lib/pki/pki-tomcat/ca/conf/CS.cfg: auths.instance.SharedToken.ldap.ldapauth.bindPWPrompt=CorporateDirectory, then
  - add CorporateDirectory=yourCorporateDirectoryPassword into /var/lib/pki/pki-tomcat/password.conf
with nuxwdog: See
- Watchdog Daemon (nuxwdog)

Adding SharedToken Authentication Plugin

By default, the SharedToken authentication plugin is not enabled, as it requires information regarding deployment site’s user LDAP server.

One can add and configure the SharedToken plugin in two ways

Using Java Console
Manually editing CS.cfg

Using Java Console to add SharedToken Plugin

Login to the system (e.g. host.example.com) using pkiconsole:

$ pkiconsole https:host.example.com//:8443/ca
Configuration tab -> Authentication -> Click Add -> Select SharedToken -> next
Authentication InstanceID=SharedToken
shrTokAttr=shrTok
ldap.ldapconn.host=host.example.com
ldap.ldapconn.port=636
ldap.ldapconn.secureConn=true
ldap.ldapauth.bindDN=cn=Directory Manager
password=SECret.123
ldap.ldapauth.authtype=BasicAuth
ldap.basedn=ou=People,dc=example,dc=org

Click OK. Plugin should be added successfully.

Editing CS.cfg Manually to add the Shared Token Plugin

Editing CS.cfg directly is suitable during installation process, when CA is not yet up and running.

Edit <CA instance>/conf/CS.cfg and add the following:

auths.impl.SharedToken.class=com.netscape.cms.authentication.SharedSecret
...
auths.instance.SharedToken.dnpattern=
auths.instance.SharedToken.ldap.basedn=ou=People,dc=example,dc=org
auths.instance.SharedToken.ldap.ldapauth.authtype=BasicAuth
auths.instance.SharedToken.ldap.ldapauth.bindDN=cn=Directory Manager
auths.instance.SharedToken.ldap.ldapauth.bindPWPrompt=Rule SharedToken
auths.instance.SharedToken.ldap.ldapauth.clientCertNickname=
auths.instance.SharedToken.ldap.ldapconn.host=host.example.com
auths.instance.SharedToken.ldap.ldapconn.port=636
auths.instance.SharedToken.ldap.ldapconn.secureConn=true
auths.instance.SharedToken.ldap.ldapconn.version=3
auths.instance.SharedToken.ldap.maxConns=
auths.instance.SharedToken.ldap.minConns=
auths.instance.SharedToken.ldapByteAttributes=
auths.instance.SharedToken.ldapStringAttributes=
auths.instance.SharedToken.pluginName=SharedToken
auths.instance.SharedToken.shrTokAttr=shrTok

CA will need to be restarted.

Examples

The examples below assumes that there exist a user named user1a in the LDAP database.

Example Enrollment Procedure

In this first implementation of a real SharedToken, some manual steps are required. Here is an example:

Generate user shrTok entry

$ CMCSharedToken -d . -p wonderfulday  -o cmcSharedTok.b64 -n "subsystemCert cert-pki-tomcat"

Encrypted Secret Data:
MIIBFgSCAQA0+JztVi1rUAat2S9XkBalV0X65kOPp/71qHdRdHf19iWjKOwaxtVC
/zF5TLvEVIDYrDnWLnixtTuxwA+tNZ1ON2CYDG7Y586xs5yC9rwJNhMedDjaRlzQ
jgQMsZHA1dGmUDpeMlqniCAsetQAvmZ6e5JfRAoZqf0h1/yHx1Xy+Qa7c274EW+L
Z+S04mtWiCzMqbwNjQdxNHsToNHjMf+kdmyh/HYjH5BxcNp+AAagY1cFhs8w4Tz5
a1gxjXEEXrrnG2uJQkOzVxv+5pJfp20+DKQS4sa8QxOAp8iqliWrv/56atGLSkaQ
TeqNZYaI/FA1E6dk8WkVHhpXsZPNdxc8BBD0ekod/vF8U0lzFINV8mvF


Storing Base64 secret data into cmcSharedTok.b64

Use ldapmodify to add the above CMCSharedToken result into the user entry shrTok attribute (single line). Example ldif file:

# mod1a-serial.ldif
dn: uid=user1a,ou=People,dc=example,dc=com
changetype: modify
replace: shrTok
shrTok: MIIBFgSCAQA0+JztVi1rUAat2S9XkBalV0X65kOPp/71qHdRdHf19iWjKOwaxtVC/zF5TLvEVIDYrDnWLnixtTuxwA+tNZ1ON2CYDG7Y586xs5yC9rwJNhMedDjaRlzQjgQMsZHA1dGmUDpeMlqniCAsetQAvmZ6e5JfRAoZqf0h1/yHx1Xy+Qa7c274EW+LZ+S04mtWiCzMqbwNjQdxNHsToNHjMf+kdmyh/HYjH5BxcNp+AAagY1cFhs8w4Tz5a1gxjXEEXrrnG2uJQkOzVxv+5pJfp20+DKQS4sa8QxOAp8iqliWrv/56atGLSkaQTeqNZYaI/FA1E6dk8WkVHhpXsZPNdxc8BBD0ekod/vF8U0lzFINV8mvF

$ ldapmodify -H ldap://host.example.com -x -D "cn=Directory Manager" -w yourPassword -f mod1a-serial.ldif

Example result:

dn: uid=user1a,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
objectClass: top
objectClass: extensibleobject
objectClass: pinPerson
cn: user1a
sn: user1a
uid: user1a
givenName: user1a
mail: [email protected]
firstname: user1a

shrTok: MIIBFgSCAQA0+JztVi1rUAat2S9XkBalV0X65kOPp/71qHdRdHf19iWjKOwaxtVC/zF5TL
 vEVIDYrDnWLnixtTuxwA+tNZ1ON2CYDG7Y586xs5yC9rwJNhMedDjaRlzQjgQMsZHA1dGmUDpeMlq
 niCAsetQAvmZ6e5JfRAoZqf0h1/yHx1Xy+Qa7c274EW+LZ+S04mtWiCzMqbwNjQdxNHsToNHjMf+k
 dmyh/HYjH5BxcNp+AAagY1cFhs8w4Tz5a1gxjXEEXrrnG2uJQkOzVxv+5pJfp20+DKQS4sa8QxOAp
 8iqliWrv/56atGLSkaQTeqNZYaI/FA1E6dk8WkVHhpXsZPNdxc8BBD0ekod/vF8U0lzFINV8mvF

Optionally, provide proper LDAP aci.

Test with CMC IdentityProofV2

Example Revocation Procedure

The following is an example for doing CMC revcation using the same Shared Token generated in the above enrollment example.

Use ldapmodify to add the above CMCSharedToken result into the user entry shrTok MetaInfo attribute in the cert record of the certificate to be revoked

Example ldif file:

dn: cn=327,ou=certificateRepository,ou=ca,o=pki-tomcat-CA
changetype: modify
add: metaInfo
metaInfo: revShrTok: revShrTok:MIIBFgSCAQA0+JztVi1rUAat2S9XkBalV0X65kOPp/71qHdRdHf19iWjKOwaxtVC/zF5TLvEVIDYrDnWLnixtTuxwA+tNZ1ON2CYDG7Y586xs5yC9rwJNhMedDjaRlzQjgQMsZHA1dGmUDpeMlqniCAsetQAvmZ6e5JfRAoZqf0h1/yHx1Xy+Qa7c274EW+LZ+S04mtWiCzMqbwNjQdxNHsToNHjMf+kdmyh/HYjH5BxcNp+AAagY1cFhs8w4Tz5a1gxjXEEXrrnG2uJQkOzVxv+5pJfp20+DKQS4sa8QxOAp8iqliWrv/56atGLSkaQTeqNZYaI/FA1E6dk8WkVHhpXsZPNdxc8BBD0ekod/vF8U0lzFINV8mvF