• Note during each of these scenarios, there may be a need to format a token. For this to work in the exernal reg environment, the tokenCUID field of the registration record must match that of the token for even Format to succeed.

• setup

  • create a user record, "user1b" (this is the same user as "user1a" above, but a different uid for new enrollment)

  • modify the following CS.cfg:

    • externalReg.delegation.enable=false

  • restart the server

• setup

  • create a user record, "executive1"

  • enroll for executive1 (e.g. using userKey profile)

  • create a user record, "delegate1"

  • modify the following CS.cfg:

    • externalReg.delegation.enable=true

    • op.enroll.delegateISEtoken.keyGen.signing.ca.profileId=

      • from caTokenUserSigningKeyEnrollment to caTokenUserDelegateSigningKeyEnrollment

    • op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId=

      • from caTokenUserAuthenticationKeyEnrollment to caTokenUserDelegateAuthenticationKeyEnrollment

  • restart the server

The premise of enabling the External Registration feature is that an external ldap db is setup for authentication and retrieval of needed information to make decisions on a few things that used to be determined solely by TPS and CA. Such information include:

• tokenType (the TPS "profile" used for enrollment activities)

• certificates to be "recovered" onto the token

In addition, the following two additions allow finer control of the subject DN and Subject Alternative name by allowing patterns to be specified in the TPS profile where each $&lt;pattern-token&gt;$ can be replaced by <pattern-token> attributes defined in the ldap record:

• dnpattern

  • e.g. op.enroll.delegateIEtoken.keyGen.authentication.dnpattern=cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org

• SANpattern

  • e.g. op.enroll.delegateIEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com with the following interested TPS profile params:

• auth.instance.2.attributes=mail,cn,uid,tokenCUID,tokenType,lastname,firstname,edipi,pcc,exec-edipi,exec-pcc,exec-mail,certsToAdd

  • this is so that during authentication, the interested attributes will be retrieved to fulfil the pattern mappings

  • note that this specification is per authentication instance

• op.enroll.delegateIEtoken.keyGen.authentication.ca.profileId=caTokenUserDelegateAuthKeyEnrollment

  • this is so that the right ca enrollment profile will be used to cooperate and form the right DN and SAN during issuance

  • note that this specification is per profile

To take advantage of the new features, one needs to determine and setup the following for each of the authentication ldap user record:

• ldap attribute name for the tokenType (TPS profile):

  • This attribute now determines which TPS profile to use

  • e.g. auth.instance.2.externalReg.tokenTypeAttributeName=tokenType

• ldap attribute name for the CUID:

  • this attribute, if specified in the ldap user record, will be used to compare and restrict the token used for the action

  • e.g. auth.instance.2.externalReg.cuidAttributeName=tokenCUID

• ldap attribute name for the field where certs to recover are specified:

  • this attribute, if specified correctly, lists out all the certs to be either retained or recovered onto the token, aside from the certs generated per specified by the tokenType.

  • e.g. auth.instance.2.externalReg.certs.recoverAttributeName=certsToAdd

Here is an example of what an ldap record looks like with the above attribute names:

Note that the "certstoadd" attribute is multi-valued so one can add multiple certs. Also note that there are two types of specification for this attribute:

• The ones with keyid and drm id (e.g. 200,ca1,88,drm1) specifies which ca to retrieve which serial number (in decimal), and which drm to retrieve which key id (in decimal)

• The ones with only serial number and ca id (e.g. 375,ca1) specifies which cert that’s currently on the token to retain. NOTE: as per design, all certs/keys currently on token, but are not specified in the "certstoadd" attribute are deleted from the token.

Now that the ldap server used for external registration authentication is setup, we need to make sure that TPS configuration is configured correctly.

First of all, as discussed above, the authentication instance points to the External Registration ldap, and the required attribute names need to be set to match the ones you set up in the ldap server. e.g.:

the following are the relevant global parameters in the TPS CS.cfg:

• externalReg.enable

  • used to turn on the external registration feature. By default, it is set to false.

• externalReg.authId

  • Authentication id used to store registration records. By default, it is set to ldap3. Make sure you point it to the auth instance specifically for external registration db

• externalReg.delegation.enable

  • used to turn on delegation option. By default it is set to false.

• externalReg.format.loginRequest.enable

  • used to turn on login request for the format operation. By default, it is set to false.

The following are the relevant parameters in each of the default TPS profile (tokenType):

• delegateIEtoken

  • This example demonstrates a token with ID (Authentication) and Encryption certs where

    • the "ID" (authentication) cert is newly requested with the dnpattern and SANpattern mapped as specified

    • the "encryption" cert is expected to be "recovered", if specified in the ldap registration user record (not specified in the TPS profile)

      op.enroll.delegateIEtoken._000=#########################################
      op.enroll.delegateIEtoken._001=# Enrollment for externalReg
      op.enroll.delegateIEtoken._002=#     ID, Encryption
      op.enroll.delegateIEtoken._003=#    where Encryption cert/keys are "recovered"
      op.enroll.delegateIEtoken._004=#    is controlled by registration user record
      op.enroll.delegateIEtoken._005=#########################################
      ...
      op.enroll.delegateIEtoken.keyGen.authentication.dnpattern=
         cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org
      op.enroll.delegateIEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com
      op.enroll.delegateIEtoken.keyGen.authentication.ca.profileId=caTokenUserDelegateAuthKeyEnrollment
      ...
      op.pinReset.delegateIEtoken.*
      op.format.delegateIEtoken.*

• delegateISEtoken -

  • This example demonstrates a token with (Authentication), Signing, and Encryption certs where

    • the "ID" (authentication) cert is newly requested with the dnpattern and SANpattern mapped as specified

    • the "signing" cert is newly requested with the dnpattern and SANpattern mapped as specified

    • the "encryption" cert is expected to be "recovered", if specified in the ldap registration user record (not specified in the TPS profile)

  • note the following errors:

    • op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId=caTokenUserAuthenticationKeyEnrollment, where caTokenUserAuthenticationKeyEnrollment does not exist. caTokenUserEncryptionKeyEnrollment would be more suitable. However, "encrytion" is not turned on in this profile by default)

    • <op.pinReset.delegateISEtoken.*  — this one seems to be missing in default; manually add when needed>

      op.enroll.delegateISEtoken._000=#########################################
      op.enroll.delegateISEtoken._001=# Enrollment for externalReg
      op.enroll.delegateISEtoken._002=#     ID, Signing, Encryption
      op.enroll.delegateISEtoken._003=#    where Encryption cert/keys is "recovered"
      op.enroll.delegateISEtoken._004=#    is controlled by registration user record
      op.enroll.delegateISEtoken._005=#########################################
      ...
      op.enroll.delegateISEtoken.keyGen.signing.dnpattern=cn=
          $auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org
      op.enroll.delegateISEtoken.keyGen.signing.SANpattern=$auth.exec-mail$
      op.enroll.delegateISEtoken.keyGen.signing.ca.profileId=caTokenUserDelegateSigningKeyEnrollment
      ...
      op.enroll.delegateISEtoken.keyGen.authentication.dnpattern=
          cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org
      op.enroll.delegateISEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@redhat.com
      op.enroll.delegateISEtoken.keyGen.authentication.ca.profileId=caTokenUserDelegateAuthKeyEnrollment
      ...
      op.format.delegateISEtoken.*

• externalRegAddToToken

  • This example demonstrates a token with no new certs and the profile’s purpose is just to "recover" certs/keys onto the token.

  • notice how the authentication must be enabled so that the certstoadd attributes can be retrieved and processed

    op.enroll.externalRegAddToToken._000=#########################################
    op.enroll.externalRegAddToToken._001=# for externalReg recovering certs/keys only
    op.enroll.externalRegAddToToken._002=#########################################
    op.enroll.externalRegAddToToken.auth.enable=true
    op.enroll.externalRegAddToToken.auth.id=ldap3
    ...

By default, TPS has a an HTTP receive buffer size of 8192. In case of certain errors such as recovering an revoked cert, the response by CA is truncated whereby the actual cert is not in the receive buffer. To fix the issue, one will have to increase the buffer size to something larger (perhaps double it). The default is maintained as is to minimize memory use. The parameter to tune the size is the following:

Also, by default the printing of Buffer is truncated in the tps-debug log. To print full Buffer’s, one can enable it:

Note that enabling it will increase the debug log a great deal; use with caution.