Skip to main content

External Signature Verification & Cert Manager

External Signature Verification application​

To manage the certificates in the Signature Verification Module, you can use the external application Certificate Manager.

This chapter describes the installation, configuration and use of this external application, which is a command line tool that you can start from your Client PC. The application uses the SOAP interface to connect to the KOBIL Security Server.

In order to successfully use the external application, a valid license for the module must be available on the server.

Important: In the properties files, no backslashes "\" should be used in the directory paths:

For example

     C:/Program Files/KOBIL/SSMS/modules/svm/utils/svm-apps-<version\>

on Windows and

     /opt/KOBIL/SSMS/modules/svm/utils/svm-apps-<version\>

on Linux and Solaris.

Note that to use the external application on a client, the Java Crypthography Extension (JCE) must be additionally installed.

You can copy this from the installation directory of the Security Server in the subdirectory

jre/lib/security/

or download it from the web site.

http://www.oracle.com/technetwork/java/javase/downloads/index.html.

You can then extract the two files local_policy.jar and US_export_policy.jar and copy them into the directory jre/lib/security/ on your Client PC. You must substitute the existing versions of the files with these versions. In addition, you must copy the files iaik_jce-3.16.jar (subdirectory jre/lib/ext/) and java.security (subdirectory jre/lib/ext/) of the SSMS installation into the corresponding directory of your local java installation.

Required configuration parameters of the external application

For the configuration of the external application, you must configure the keys and the certificates for the secure communication with the Security Server. More precisely, you must enter the path to these files in the config file of the application (in the subdirectory /config).
To authenticate and authorize the external application against the Security Server, you need a key and a certificate, which must be assigned to the role “Administrator” or “SuperAdmin” and must be a p12 file. Either use the certificate and key “SuperAdmin” generated during the Security Server installation and added to the directory <SSMS_HOME>/certs or generate another certificate via the graphical interface of the Security Server (find more information in the Kernel manual, chapter “Role Management View”, paragraphs “Create a role” and “Download certificate”). You also need the password of the key.

To verify the authenticity of the Security Server, you need the CA certificate belonging to the Security Server installation. This CA certificate must be available as a truststore in JCEKS format with the file extension “jks”. The trustore is used to verify the issuers of the SSL certificates of the server. The truststore is generated during the Security Server installation and added to the directory <SSMS_HOME>/certs and can be used directly. Default password for protecting the integrity of this truststore is 123456. This password can be changed later.

Note that the password currently valid must also be entered into the Tomcat (server.xml). If you change it, you must change it in all the relevant configuration files.

The following parameters must be entered into the properties file:

### key file of the operator (PKCS#12)

soap.SSL.KeyStoreFile = /path to the certificate/ssms-superadmin.p12 oder admin.p12

### trust store file containing the ssms servers root and ca certificate (java key store)

soap.SSL.TrustStoreFile = /path to the certificate/truststore.jks

### pass phrase to access the trust store

soap.SSL.TrustStorePassPhrase = 123456

Information for all Linux users

You may need to change the permissions to run the files of the external application (for example chmod 755 ./issuer-certificate-manager.sh). For security reasons, the rights of the lib directory must be adjusted after decompressing the application archive file. More precisely, all other users and the group must have read permissions (z. B. chmod 644 ./svm-apps-<version>/lib/).

Certificate Manager​

With the Certificate Manager, you can manage the certificates and the users of the Signature Verification Module. Follow these paths to reach the application in the installation directory:

  • Windows:

    C:\Program Files\KOBIL\SSMS\modules\svm\utils\svm-apps-<version><release>;

  • Linux/Solaris:

    /opt/KOBIL/SSMS/modules/svm/utils/svm-apps-<version><release>;

Scope of the application​

This application offers different certificate management functions to manage the certificates in the KOBIL Security Server database. To carry out these management functions, the user needs a private key and an SSL client certificate to authenticate himself on the KOBIL Security Server. This certificate must match the role or the permissions of the user, in order to run the certificate management functions (role management). The user additionally needs a truststore, containing the KOBIL SSMS SSL server certificate chain, to verify the server authentication.

Requirements​

  • Check the network connection to the KOBIL Security Server on which the certificates and the users should be managed
  • JRE Version 1.7.0_25 or higher
  • Be sure that the directory path to the binary library contains the right Java version

Installation​

  • Copy the zip file into the directory of your choice from which the certificates and the user should be managed
  • Unzip the archive file
  • Switch to the newly generated directory

Configuration of the application​

  1. The configuration file certificate-manager.properties is in the subdirectory config/ of the application.
  2. Define every parameter. No value must be left empty. Some parameters are preconfigured; you can either use these values or enter other values.
  3. To connect to the SOAP interface, you need certificates, keys and keystore. Examples of the parameters that you need are listed in Text 1 on the preceding page.
  4. For the SOAP URL, use the host name of the server and not the IP address.

Start the application​

Run the Certificate Manager script (for example on Windows certificate-manager.cmd or on Linux/Solaris certificate-manager.sh) with the right parameters.

./certificate-manager.sh <command> <command parameter1> [command parameter n]

(Example 1:

     ./certificate-manager.sh removeIssuerCertificate “CN=mIDentity“ 123456

)
(Example 2:

      ./certificate-manager.sh assignUserCertificate “CN=Issuer DN “ 456123 testuser01

)

Find additional functions available in the application in chapter available-management-functions

Log file of the application​

The external application certificate manager usually generates a log file in the directory of the application: certificate-manager.log. You can adjust the path to the log file in the log4j.properties.

log4j.appender.R.File=certificate-manager.log

In the above example, the log file is in the directory of the application.

In the configuration of the log file, be sure that you enter the correct path and that the application can write and read files in the given directory. If the log file cannot be generated, the application does not give any warning or information. The application continues its operations, without generating a log file.

Available management functions​

addIssuerCertificate “<path to the certificate file>”Adds an issuer certificate to the database.
removeIssuerCertificate “<issuerDN>” <serial number>Removes an issuer certificate from the database.
lockIssuerCertificate “<issuerDN>” <serial number>Locks an issuer certificate.
unlockIssuerCertificate “<issuerDN>” <serial number>Unlocks an issuer certificate.
getIssuerCertificates “<filter>”Returns all issuer certificates that match the selected filter
addUserCertificate “<path to the certificate file>”Adds a user certificate to the database.
removeUserCertificate “<issuerDN>” <serial number>Removes a user certificate from the database.
assignUserCertificate “<issuerDN>” <serial number> <userID>Assigns a user certificate to a user.
unassignUserCertificate “<issuerDN>” <serial number>Unassigns a user certificate from a user.
lockUserCertificate “<issuerDN>” <serial number> “<lock reason>”Locks a user certificate in the database.
unlockUserCertificate “<issuerDN>” <serial number>Unlocks a user certificate in the database.
getUserCertificatesInfo “<filter>”Returns all user certificates that match the selected filter
getUserCertificate „<issuerDN>“ <serial number>Returns the user certificate that matches the filter.
getUserByIssuerAndSerial “<issuerDN>” <serial number>Returns the user name that match the filter.
getUserByDEREncodedCertificate “<path to the certificate file>”Returns the user name that matches the filter.
addUser “<userID>“Adds a user to the database.
removeUser “<userID>“Removes an already added user from the database.