Subjectstool command-line tool in Certificate Manager

This article is valid for Certificate Manager 8.4 and later.

If it is suspected that the relation between the Certificates and Subjects table is corrupted in the Smart ID Certificate Manager database, you can use subjectstool, to check the contents of the Subjects table against values that are created by this tool from the actual certificates in the CMDB.

Location

The program is located in the <install_root>/tools directory relative to where CM is installed.

Commands

check

The command check is used to check the contents of the Subjects table against values that are created by this tool from the actual certificates in the CMDB. The output file will contain all Subject entries that differ, or are missing. If no differences are found, the output file is empty.

csv

The command csv is used to output the data that the tool creates for the Subjects table for each certificate entry in the Certificates table to a CSV file. Review the CSV file to verify the data. The optional argument -delim can be used to decide the delimiter to use in the CSV file. Default is ";".

db

The command db is used to write the Subjects data created by this tool from the certificates in the CMDB into the Subjects table. This requires that all entries in the Subjects table has been deleted prior to running the command. This tool will not delete any data from the Subjects table. It only does insertions.

The suggested order to run the commands in is check, csv and lastly if needed db.

Limitations

These are the limitations for subjectstool:

It only handles Subjects for X.509 certificates.
It does not handle entries in the ExtendedCertSearch table. If that table is used, do not use this tool.
Subjects which have been marked for removal for GDPR reasons may be recreated.
It does not handle officers connected to subject. If such officers are used, change their profiles to use dynamic token before using this tool. After the db command has been executed, ALL officers should be resigned, even those not connected to a subject entry number.

Use subjectstool

Example 1 - check Subjects table

CODE

$ java -jar cm-tools.jar subjectstool -command check
2021-02-01 09:09:30.378 trace fine Successfully connected to DB
jdbc:oracle:thin:@//172.17.0.2:1521/XE.
2021-02-01 09:09:30.386 trace fine Oracle connection, Encryption
algorithm is: , dataintegrity algorithm is:
2021-02-01 09:09:32.768 trace fine Output written to
/opt/cm/server/tools/subjectstool-out-1612166972763.check
2021-02-01 09:09:38.063 trace fine All done OK

Example 2 - generate CSV file

CODE

$ java -jar cm-tools.jar subjectstool -command csv
2021-02-01 09:12:56.642 trace fine Oracle connection, Encryption
algorithm is: , dataintegrity algorithm is:
2021-02-01 09:12:56.628 trace fine Successfully connected to DB
jdbc:oracle:thin:@//172.17.0.2:1521/XE.
2021-02-01 09:12:58.649 trace fine Output written to
/opt/cm/server/tools/subjectstool-out-1612167178609.csv
2021-02-01 09:13:02.588 trace fine All done OK
$ cat subjectstool-out-1612167178609.csv
subjectId;subjGivenName;subjSurName;subjCommonName;subjOrgUnit;subjOrgName;
subjCountry;subjDMDName;subjAltName;certSerNr
;;;Protocol Gateway RA;;System;SE;;;10004
;;;localhost;;Example CM;SE;;*.ad.nexusgroup.com;10005
;;;Protocol Gateway VRO;;System;SE;;;10006
;;;WinEP connector;;Example CM;SE;;;10007

Example 3 - update CMDB

CODE

$ java -jar cm-tools.jar subjectstool -command db
2021-02-01 09:23:58.417 trace fine Successfully connected to DB
jdbc:oracle:thin:@//172.17.0.2:1521/XE.
2021-02-01 09:23:58.417 trace fine Oracle connection, Encryption
algorithm is: , dataintegrity algorithm is:
2021-02-01 09:24:06.023 trace fine Processed 299 out of 1056 entries
2021-02-01 09:24:11.023 trace fine Processed 686 out of 1056 entries
2021-02-01 09:24:15.284 trace fine Processed 1056 out of 1056 entries
2021-02-01 09:24:15.285 trace fine All done OK

Configure subjectstool

Use the following environment variable to configure subjectstool:

Environment variable

Description

CM_HOME

(optional) Specifies a directory where the CM configuration is installed, usually referred to as <configuration_root>. Specifying this environment variable allows the program to use database connection details from cm.conf if placed in a nonstandard location.

If this environment variable is not specified, and the program is placed in the default directory of <install_root>/tools, the program will automatically find the CM configuration and the database connection details.