PKI Renewal Software Configuration

The attended mode is compatible only with the manual renewal process. The attended mode is for use with an HSM-based configuration (operator client certificates stored in the HSM).

When running the manual renewal process in attended mode, the operator is prompted for the following information in the Enter Secure Credentials window:

• Database user password

• HSM Personal Identification Number (PIN)

In the unattended mode, the credentials stored in the XML configuration file are obfuscated.

Configure the security mode implemented by editing the securityMode= line as shown in the following example:

<?xml version=”1.0” encoding=”UTF-8”?>
<common securityMode=”unattended”>

Modify the security mode by editing the common.xml file as follows:

1. Locate and open the common.xml file (typically in the conf folder).

2. Locate the XML root element common.

3. Modify the securityMode= attribute to match the desired security mode:

   • “unattended” for the unattended mode

   • “attended” for the attended mode

   If the unattended mode is selected, you need to perform the secret key configuration as follows:

   • Locate the secret key configuration section:

     Copy

     …
     <secret filename="./conf/secrets.jks" encryptedPassword="password" attended="false"/>
     …

   • Replace “password” with a password of your own choosing by entering this password in clear text.

     Refer to Password Encryption for more information on the password encryption.

     Important: Before executing the check.bat file, you should perform all the configuration steps detailed in PKI Renewal Software Configuration.

4. Save and close the common.xml file to save your configuration changes.

To configure the Oracle database, edit the common.xml file.

1. From the installation directory, locate the common.xml file in the conf folder.

   Copy

       <cmsDatabase>
           <dataSource>oracle.jdbc.pool.OracleDataSource</dataSource>
           <url>jdbc:oracle:thin:@cms411w2k3sp2:1521:CMS</url>
           <userName>AIMSEE</userName>
           <password isSecret="true" isEncrypted="false">password</password>
       </cmsDatabase>

2. Locate the XML element cmsDatabase.

3. Modify the URL element to match your specific environment. Copy the URL from the “url” property in the database.properties file located in the ActivID CMS Shared Files folder, available at %PROGRAMDATA%\HID Global\Credential Management System\Shared Files.

   Warning!
   Do not change the user name (XML element = userName).
   

4. Set the AIMSEE password in the configuration files. You can enter this password in clear text because it is encrypted the first time that the renewal tool is started.

5. Save and close the file to save your configuration changes.

To configure the SQL server database, edit the common.xml file.

1. From the installation directory, locate the common.xml file in the conf folder.

   Copy

     <cmsDatabase>
       <dataSource>com.microsoft.sqlserver.jdbc.SQLServerDataSource</dataSource>
   <url>jdbc:sqlserver://cmsserver.domain.com/AIMSEE;serverName=cmsserver.domain.com;
       databaseName=AIMSEE;socketTimeout=600</url>
   <userName>AIMSEE</userName>
       <password isSecret="true" isEncrypted="false">password</password>
     </cmsDatabase>

2. Locate the XML element cmsDatabase.

3. Modify the URL element to match your specific environment. Copy the URL from the “sqlserver.AIMSEE.url” property in the database.properties file located in the ActivID CMS Shared Files folder (available at %PROGRAMDATA%\HID Global\Credential Management System\Shared Files.

4. Set the AIMSEE password in the configuration files. You can enter this password in clear text because it is encrypted the first time that the renewal tool is started.

5. If the database connection uses 'Windows Authentication", then use the following configuration. Accept the userName and password (not defined) as illustrated next.

   Copy

   <cmsDatabase>
   <dataSource>com.microsoft.sqlserver.jdbc.SQLServerDataSource</dataSource>
   <url>jdbc:sqlserver://SQL2008/AIMSEE;serverName=SQL2008;databaseName=AIMSEE;socketTimeout=600;domain=XXXX;integratedSecurity=true</url>
   <userName></userName>
   <password isSecret="true" isEncrypted="false"></password>
   </cmsDatabase>

   6. Save and close the file to save your configuration changes.

      Warning!
      You must not change the user name (XML element = userName).
      

This section describes how to configure the common.xml file to re-encrypt the database password.

1. In the <common> XML element, change 'action' to 'update' as illustrated below.

2. In the <password> XML element, change 'isEncrypted' to 'false' as illustrated below.

   Copy

   ?xml version="1.0" encoding="UTF-8"?>
   <common securityMode="unattended" action="update"/>
     <secret filename="./conf/secrets.jks" encryptedPassword="c0FJFQdMGVt3DD2/1vRCZw==" attended="false" />
     <cmsDatabase>
       <dataSource>com.microsoft.sqlserver.jdbc.SQLServerDataSource</dataSource>
       <url>jdbc:sqlserver://localhost/AIMSEE;serverName=localhost;failoverPartner=(local);databaseName=AIMSEE;socketTimeout=600</url>
       <userName>AIMSEE</userName>
       <password isSecret="true" isEncrypted="false">Password</password>
     </cmsDatabase>
     <cmsPortal>
       <url>https:///win-b1h8s2evoie.cms423.sayuri.com:32456</url>
       <clientCertificate storage="file">
         <filename>./conf/certificates/renewalOperator.pfx</filename>

To configure the email server, complete the following tasks.

1. From the installation directory, locate the common.xml file in the conf folder.

2. Locate the XML element email.

   Copy

   <email>
       <type>SMTP</type>
       <hostname>smtp.wanadoo.fr</hostname>
       <from>pkirenewal_dma_TEST@hidglobal.com</from>
       <emailUser sendEmail="true">
       <subject>Your device needs to be updated</subject>
       <messageTemplate>
   Dear user,
   You are receiving this email because one of the certificates stored in your device is about to expire.
   To renew this certificate, please login to the User Portal web server and follow the process to update your device.
   https://mtpsmdasrv2.mtpsmda2.hidglobal.com:32456/aims/enterprise/user.
       </messageTemplate>
       </emailUser>
       <emailAdministrator sendEmail="true">
       <to> john.doe@hidglobal.com</to>
       <renewalSubject>PKI Renewal Report(s)</renewalSubject>
       <administrationSubject>PKI AdministrationReports</administrationSubject>
   <updateSubject>PKI Update Reports</updateSubject>
       </emailAdministrator>
   </email>

3. Modify the XML element hostname so that it matches the hostname of your SMTP server.

4. Save and close the file to save your configuration changes.

To configure the sending of an email to users when an applications update request is posted, complete the following tasks.

1. Locate the XML element emailUser.

   Copy

   <emailUser sendEmail="true">
       <subject>Your device needs to be updated</subject>
       <messageTemplate>
   Dear user,
   You are receiving this email because one of the certificates stored into your device is about to expire.
   To renew this certificate please login to the User Portal web server and follow the process to update your device.
   https://mtpsmdasrv2.mtpsmda2.activcard.com:32456/aims/enterprise/user.
       </messageTemplate>
   </emailUser>

2. To configure the sending of emails to users, set the sendEmail attribute to true. Otherwise, set the sendEmail attribute to false (emails not sent to users).

3. Save and close the file to save your configuration changes.

To configure the sending of an email to administrators when a batch has been posted, complete the following tasks.

1. Locate the XML element emailAdministrator.

   Copy

   <emailAdministrator sendEmail="true">
       <to>john.doe@hidglobal.com</to>
       <renewalSubject>PKI Renewal Report(s)</renewalSubject>
       <administrationSubject>PKI Administration Reports</administrationSubject>
   <updateSubject>PKI Update Reports</updateSubject>
   </emailAdministrator>

2. To configure the sending of emails to administrators, set the sendEmail attribute to true. Otherwise, set the sendEmail attribute to false (emails not sent to administrators).

3. Configure the to XML element with the email address of the administrators. You can add multiple email addresses, separated by a comma.

4. Configure the XML elements renewalSubject for a renewal batch or administrationSubject for an administration batch, or updateSubject for an update batch to suit your specific needs.

5. Save and close the file to save your configuration changes.

Start the Renewal process, either an Applications Update or a Re-Issuance. The date used as the filter for the report is based on the expiration date of the certificates.

1. Locate the XML element renewal.

   Copy

   <renewal>
   <foldername>./reports/renewal</foldername>
   <messageTemplate>Dear Administrator,
   Please find attached the reports containing the renewal batch process (%PROCESS_ID%) which took place on %DATE% and lasted approximately %PROCESS_DURATION% minutes.
   This batch was configured to scan device certificates which expired between %PERIOD_BEGIN_DATE% and %PERIOD_END_DATE%. 
   This batch processed %NB_DEVICES% devices. From this number:
   - %NB_DEVICES_PKIRENEWAL% were processed and received a PKI application update request. This request will be executed the next time they log in to the User Portal.
   - %NB_DEVICES_PENDING% were not processed because a request was already posted. 
   - %NB_DEVICES_ERROR% were not processed because an error occurred during the batch. Please open the file containing these devices and take the appropriate action.
   Best Regards</messageTemplate>
       </renewal>

   Note: Since version 5.0.1 of ActivID CMS, the keywords %NB_DEVICES, %NB_DEVICES_PKIRENEWAL%, %NB_DEVICES_PENDING%, %NB_DEVICES_ERROR% replace the following deprecated keywords: %NB_SMARTCARDS%, %NB_SMARTCARDS_PKIRENEWAL%, %NB_SMARTCARDS_PENDING%, %NB_SMARTCARDS_ERROR%.
   The support of these deprecated keywords will be removed in an upcoming version.

2. The XML element foldername shows the name of the folder which contains all the files related to the renewal reports including:

   • REP_RNW_SUMMARY_YYYYMMDDHHMMSS.txt—provides a summary of the batch renewal process.

   • REP_RNW_REQ_PENDING_YYYYMMDDHHMMSS.csv—lists devices with a certificate about to expire, but with a pending request.

   • REP_RNW_PKI_UPDATE_ YYYYMMDDHHMMSS.csv—lists devices with a certificate about to expire, with no pending request, and a PKI update request successfully posted.

   • REP_RNW_ERROR_ YYYYMMDDHHMMSS.csv—lists devices with a certificate about to expire, and for which an error occurred during the posting of the applications update.

3. The XML element messageTemplate lets you configure the report summary and also the email body sent to the administrator. This message template can also contain dynamic data. This data is defined by keywords that can be inserted anywhere in the message template including:

   • %PROCESS_ID%—the ID of the process as defined in the renewalProcesses.xml file.

   • %DATE%—the date the batch was processed.

   • %PROCESS_DURATION%—the time it takes (in minutes) to process the batch.

   • %PERIOD_BEGIN_DATE%—the starting date for which the renewal batch starts to scan for expiring certificates.

   • %PERIOD_END_DATE%—the end date for which the renewal batch finishes to scan for expiring certificates.

   • %NB_DEVICES%—the number of devices the renewal batch has processed.

   • %NB_DEVICES_PKIRENEWAL%—the number of devices for which a PKI application update was successfully posted.

   • %NB_DEVICES_PENDING%—the number of devices that could not be processed because a request was pending.

   • %NB_DEVICES_ERROR%—the number of devices that could not be processed because an error occurred during the batch.

This will list the Administration report of certificates.

1. Locate the XML element administration.

   Copy

   <administration>
      <foldername>./reports/administration</foldername>
         <messageTemplate>Dear Administrator,
   Please find attached the reports containing the administration batch process (%PROCESS_ID%) which took place on %DATE% and last approximately %PROCESS_DURATION% minutes.
   This batch was configured to scan device certificate which expired between %PERIOD_BEGIN_DATE% and %PERIOD_END_DATE%.
   This batch processed %NB_DEVICES% devices. These devices contain at least one certificate which will expire during the specified period.
   Best Regards</messageTemplate>
       </administration>

2. The XML element foldername shows the name of the folder which contains all of the files related to the renewal reports including:

   • REP_ADM_SUMMARY_YYYYMMDDHHMMSS.txt—summarizes the batch administration process.

   • REP_ADM_PKI_UPDATE_YYYYMMDDHHMMSS.csv—a comma-separated value (CSV) file containing all of the devices for which a certificate is about to expire in a given period.

3. The XML element messageTemplate lets you configure the report summary and also the email body sent to the administrator. The message template can also contain dynamic data. This data can be defined by keywords that can be inserted anywhere in the message template including:

   • %PROCESS_ID%—the ID of the process as defined in the renewalProcesses.xml file.

   • %DATE%—the date that the batch was processed.

   • %PROCESS_DURATION%—the duration time (in minutes) for the batch to process.

   • %PERIOD_BEGIN_DATE%—the starting date for which the administration batch starts scanning for expiring certificates.

   • %PERIOD_END_DATE%—the end date for which the administration batch finishes scanning for expiring certificates.

   • %NB_DEVICES%—the number of devices that the administration batch processed.

Start the Update process by returning all the devices where the certificates have been updated on the certificate repository (PKI_CREDENTIAL_DETAILS_PCD) during an ActivID CMS upgrade or some “missed” certificates. The date used as the filter for the report is based on the issuance date of the certificates.

1. Locate the XML element update.

   Copy

     <update>
         <foldername>./reports/update</foldername>
         <messageTemplate>Dear Administrator,
   Please find attached the reports containing the update batch process (%PROCESS_ID%) which took place on %DATE% and lasted approximately %PROCESS_DURATION% minutes.
   This batch was configured to scan devices issued between %PERIOD_BEGIN_DATE% and %PERIOD_END_DATE% and missing in the certificate repository.
   This batch processed %NB_CREDENTIALS% certificates. From this number:
   - %NB_CREDENTIALS_ALREADY_PRESENT% were already present in the certificate repository
   - %NB_CREDENTIALS_INSERTED% were inserted into the certificate repository. 
   - %NB_CREDENTIALS_ERROR% were not processed because an error occurred during the batch. Please open the file containing these certificates and take the appropriate action.
   Best Regards</messageTemplate>
       </update>

2. The XML element foldername shows the name of the folder which contains all the files related to the update reports including:

   • REP_UPD_SUMMARY_YYYYMMDDHHMMSS.txt—summarizes the batch update process.

   • REP_UPD_PKI_UPDATE_YYYYMMDDHHMMSS.csv—a CSV file containing all certificates that have been added to the repository.

   • REP_UPD_PKI_ERROR_YYYYMMDDHHMMSS.csv—a CSV file containing all certificates that should have been added to the repository, but were not because an error occurred during processing.

   • REP_UPD_PKI_ALREADY_INSERTED_YYYYMMDDHHMMSS.csv—a CSV file containing all certificates that are already present in the repository.

3. The XML element messageTemplate is made to configure the report summary and also the email body sent to the administrator. The message template can also contain dynamic data. This data is defined by keywords that can be inserted anywhere in the message template including:

   • %PROCESS_ID%—the ID of the process as defined in the updateProcesses.xml file.

   • %DATE%—the date that the batch was processed.

   • %PROCESS_DURATION%— the duration time (in minutes) for the batch to process.

   • %PERIOD_BEGIN_DATE%—the starting date for which the update batch starts scanning for certificates issued after this starting date.

   • %PERIOD_END_DATE%—the end date for which the update batch finishes scanning for certificates issued before this end date.

   • %NB_CREDENTIALS%—the number of certificates the update batch processed.

   • %NB_CREDENTIALS_ALREADY_PRESENT%—the number of certificates already present in the repository.

   • %NB_CREDENTIALS_INSERTED%—the number of certificates inserted during the update process.

   • %NB_CREDENTIALS_ERROR%—the number of certificates which produced an error during insertion into the certificate repository.