Certificate manager service

The CertificateManager service is a utility which other modules can use to check the validity of particular signer certificates against those saved in a storage of trusted certificates. For example, the CertificateManager service is used when checking if a deployment package in terms of the OSGi Service Compendium Specification is signed by a trusted signer.

The interface of the CertificateManager service is com.prosyst.mbs.framework.certmanager.CertificateManager.

The service offers methods for:

• getting the distinguished names (DNs) of the owners whose certificates are saved in the database;
• getting only the trusted certificate chains in a collection of certificate chains (e.g. the certificate chains used to sign a bundle JAR file);
• checking if a certificate is trusted and if a certificate is available in the trusted storage;
• matching the subject DN of a bundle's certificate against a certain DN pattern.

The service also supports checking the validity of a certificate chain over the Online Certificate Status Protocol (OCSP) through its methods ocspCheck and ocspCheckCancel. Applications calling these methods in order to execute an OCSP-related operation must have an OCSPPermission with name equal to "start" when calling ocspCheck and equal to "cancel" when calling ocspCheckCancel.

CertificateManager has option for disabling the check for expired certificates. It is available if the mbs.certificates.skipValidationCheck system property is set to true.

To provide a custom implementation of KeyManager and TrustManager services when using a secure connection and having a secure context bundle, consider either disabling the CertificateManager in the framework or register your own KeyManager and TrustManager with service.ranking higher than 0, which is the default rank. The recommended way to disable the CertificateManager is to use the 'nocert' option when starting the framework with 'server nocert' console command.

The CertificateManager service is available only if the value of the mbs.certificates system property is true (default). To easily disable this feature, start the OSGi Runtime by running the bin/vms/<vm_name>/server script with the nocert command line option or clean the value of the FWCERT environment variable before calling the server script. Refer to system Properties section in the Setup guide.

You can conveniently use the JAR utility for getting a bundle JAR with the trusted certificates signed (according to the content of the certificate storage).

Registering bundle

This service is registered by System bundle.

Certificate loading

The CertificateManager service gets the trusted certificates of a specific bundle, represented as an input stream. The other certificate operations are based on a certificate storage, built on top of a specific certificate store type.

Ready certificate storages

You can use one of the following certificate storages for trusted certificates, implemented in the framework:

• Keystore storage - Default storage. It loads certificates from the standard JVM keystore. The storage loads trusted certificates from four sources:
  1. The default JVM keystore with certificates of certification authorities located in the lib/security/cacerts file of the JVM home directory, indicated with the java.home system property.
  2. The default user's keystore saved in the .keystore file within the user's home directory, indicated with the user.home system property.
  3. The policy files with location specified under the policy.url.X properties in the security properties file – default file is lib/security/java.security from the JVM home directory. In each specified policy file, the keystore storage checks if the policy has a keystore entry, and if such exists, the storage loads the certificates from the specified keystore location.
  4. The truststores with location specified as value of the org.osgi.framework.trust.repositories system property.

  At the moment CertificateManager does not accept truststore with a password for keystores, specified in system property org.osgi.framework.trust.repositories. These keystores are not considered editable. Though it supports password for the other 3 supported keystores.

  The system property mbs.editable.keystore.password (either in default.prs or common.prs) specifies the password. The following details apply here:

  1. cacerts is considered password protected, only if mbs.editable.keystore specifies cacerts
  2. ${user.dir}/.keystore is considered password protected, only if mbs.editable.keystore specifies ${user.dir}
  3. ${current.dir}/.keystore is considered password protected by default. This can be disabled, only if mbs.editable.keystore specifies value, which is different from ${current.dir} for example 1) or 2).
  4. For the policy files java.policy and index.keystore the path must be first defined in mbs.editable.keystore so it is editable. After that mbs.editable.keystore.password property can be applied.

  Please note that:
  • current.dir = the directory for the java process (example: <gateway_install_dir>/runtime/osgi/bin/vms/jdk)
  • user.dir = C:/Users/<your username>

  For information about key and certificate management in Java, refer to Java security architecture document.

• Extended keystore storage – It extends the keystore storage providing applications with write access to the keystore. To activate the extended keystore storage in the Certificate Manager, set the mbs.keystore.class system property to com.prosyst.mbs.impl.framework.module.certmanager.certstorage.ExtKeystoreCertificateStorageImpl.
• X509 storage – This storage loads X509 certificates from a particular directory - in this way, you can avoid the dependence on JVM's keystore implementation. To make the Certificate Manager use the X509 storage, set the mbs.keystore.class system property to com.prosyst.mbs.impl.framework.module.certmanager.certstorage.FolderCertificateStorageImpl.
• Extended X509 storage – It extends the X509 storage providing applications with write access to the directory holding the X509 certificates. To activate extended X509 storage in the Certificate Manager, set the mbs.keystore.class system property to com.prosyst.mbs.impl.framework.module.certmanager.certstorage.ExtFolderCertificateStorageImpl.

Adding certificates to the certificate storage

You can add a certificate or a certificate chain to the Certificate Manager, import it in the used storage – keystore storage or X509 storage, or add them at runtime by using the Certificate Manager service.

Keystore storage

Simply import the certificate or certificate chain in the appropriate keystore by using the tools (e.g. keytool in JDK) supplied with the JVM installation. Then, start the framework, or if the framework has been running during the certificate import, restart it to apply the changes to the Certificate Manager.

X509 storage

Place your certificates in a dedicated directory and specify the path to it by using mbs.certificate.root system property. By default, if the mbs.certificate.root property is missing, the X509 storage will look into a folder, called certs, within the current directory (i.e. <user home>/certs>). Then, start the framework, or if the framework has been running during the certificate import, restart it to apply the changes to the Certificate Manager.

Extended keystore storage and extended X509 storage

To be able to import, update or remove a certificate at framework runtime, you can use the extended modifications of the keystore storage and of the X509 storage. Having configured the Certificate Manager to use some of these certificate storages, use the getCertificateStorage method of the Certificate Manager. The returned CertificateStorage instance provides the write access to the underlying keystore or certificate directory.

Signature validation features

When a signed bundle is deployed, beside signer's trust, its signature is checked against contained digests. By default, once digests of signed bundle JAR files are verified, they are not re-checked when the framework is restarted. To enable digest checks on framework restarts, set the mbs.certificates.boot.enableDigests system property to true (default is false).

Another option for configuration of signature digest checks is to have the entry digests verified only when the corresponding entry is requested by some bundle in the framework. Otherwise, the digest verification will be performed when the bundle is loaded at installation or at framework startup if already installed. To enable on-demand digest checking, set the mbs.certificates.delayedCheckJarEntriesDigests system property to true (false by default).

Strict certificate checks

Strict Certificate Checks are provided via the mbs.certificates.strict system property. If set to true the framework will run only signed bundles and will not allow update of signed to unsigned ones.