Maritime Connectivity Platform (MCP) Public Key Infrastructure (PKI)

This is a library / cmdline tool used to manage and check certificates in the MCP Public Key Infrastructure (PKI).

Building using maven should be as simple as running mvn install under the assumption you have Java 17 installed already.

Maritime Connectivity Platform is formerly known as the Maritime Cloud and therefore there might still be references to that in this project.

MCP-PKI implements the certificate attributes described in the developer's page of identity registry and used in Maritime Identity Registry.

Using the lib

The primary function of this software is to make it easy/easier to use the MCP PKI for (Java) developers.

There is javadocs available here: https://maritimeconnectivity.github.io/MCP-PKI/apidocs/

Use PKIConfiguration for setting up configuration about Keystore and/or Truststore, use KeystoreHandler to load them and the you most like want to use CertificateHandler to, well, handle certificates...

A short example of use can be seen below:

    // Setup MCP PKI
    PKIConfiguration pkiConf = new PKIConfiguration("urn:mrn:mcp:ca:idp1:maritimeconnectivity");
    pkiConf.setTruststorePath("/path/to/mcp-truststore.jks");
    pkiConf.setTruststorePassword("changeit");
    KeystoreHandler kh = new KeystoreHandler(pkiConf);
    // Get the certificate that should be validated
    X509Certificate cert = getUserCertificate();
    // Validate certificate
    CertificateHandler.verifyCertificateChain(cert, kh.getTrustStore());
    // Extract Identity information from the certificate
    PKIIdentity user = CertificateHandler.getIdentityFromCert(cert);

Here the parameter "urn:mrn:mcp:ca:idp1:maritimeconnectivity" states the root-ca-alias which will be defined differently to each identity provider.

Commandline interface

The secondary function of this software is to provide a (relatively) easy to use interface for the PKI manager. How to use is will be described below.

If you have build using maven you should now have a mcp-pki-cli-1.2.0-SNAPSHOT.jar and a mcp-pki-cli-1.2.0-SNAPSHOT-jar-with-dependencies.jar (or similar) in the target folders. It is the latter we will be using since it can easily be run from the commandline.

Initializing the PKI

To use the PKI we must first initialize it, which means create a root Certificate Authority (CA). This can be done with this command:

java -jar mcp-pki-cli-1.2.0-SNAPSHOT-jar-with-dependencies.jar \
    --init \
    --truststore-path mcp-truststore.jks \
    --truststore-password changeit \
    --root-keystore-path root-ca-keystore.jks \
    --root-keystore-password changeit \
    --root-key-password changeit \
    --root-ca-alias "urn:mrn:mcp:ca:idp1:maritimeconnectivity" \
    --x500-name "C=DK, ST=Denmark, L=Copenhagen, O=MCP Test, OU=MCP Test, CN=MCP Test Root Certificate, E=info@maritimeconnectivity.net" \
    --crl-endpoint "http://localhost/x509/api/certificates/crl/urn:mrn:mcp:ca:idp1:maritimeconnectivity" \
    --validity-period 120

Note that the truststore and root-keystore will be overwritten! Also note that crl-endpoint should end with urn:mrn:mcp:ca:idp1:maritimeconnectivity which is the value of root-ca-alias. The unit of validity period field is months. The root CA in this example will be valid for 10 years from the issued date.

Change the passwords as you see fit.

Create root Certificate Revocation List

We must also create a root Certificate Revocation List to be able to tell if any sub CA has been revoked. This can be done with this command:

java -jar mcp-pki-cli-1.2.0-SNAPSHOT-jar-with-dependencies.jar \
    --generate-root-crl \
    --root-keystore-path root-ca-keystore.jks \
    --root-keystore-password changeit \
    --root-key-password changeit \
    --revoked-subca-file revoked-subca.csv \
    --root-ca-alias "urn:mrn:mcp:ca:idp1:maritimeconnectivity" \
    --root-crl-path root-ca.crl

The revoked-subca-file CSV file must either be empty or have a format like this:

345678954765889809876543;cacompromise;2017-04-31

That is <serial-number>;<revocation-reason>;<revocation-date>

The revocation reason can be one of the following: unspecified, keycompromise, cacompromise, affiliationchanged, superseded, cessationofoperation, certificatehold, removefromcrl, privilegewithdrawn or aacompromise.

The revocation date must be of the format: YYYY-MM-DD.

Remember to keep the list of revoked sub ca. Each time a new sub CA is revoked you must add it to the CSV file and generate a new CRL. Note that a CRL is valid for exactly on year.

Create sub CA

Create a sub CA like this:

java -jar mcp-pki-cli-1.2.0-SNAPSHOT-jar-with-dependencies.jar \
    --create-subca \
    --root-keystore-path root-ca-keystore.jks \
    --root-keystore-password changeit \
    --root-key-password changeit \
    --truststore-path mcp-truststore.jks \
    --truststore-password changeit \
    --subca-keystore subca-keystore.jks \
    --subca-keystore-password changeit \
    --subca-key-password changeit \
    --root-ca-alias "urn:mrn:mcp:ca:idp1:maritimeconnectivity" \
    --x500-name "UID=urn:mrn:mcp:ca:idp1:mcp-idreg, C=DK, ST=Denmark, L=Copenhagen, O=MCP Test, OU=MCP Test, CN=MCP Test Identity Registry, E=info@maritimeconnectivity.net" \
    --crl-endpoint "http://localhost/x509/api/certificates/crl/urn:mrn:mcp:ca:idp1:mcp-idreg" \
    --validity-period 60

The UID will be used as alias when stored in the truststore and subca-keystore. The root-keystore and truststore is expected to exist, while the subca-keystore will be created if it does not exist.

Checking client certificate

You can check the attributes of an MCP client certificate like this:

java -jar mcp-pki-cli-1.2.0-SNAPSHOT-jar-with-dependencies.jar --print-certificate <certificate-name>.pem

Alternatively the Identity Extractor Service which is an implementation of a web service visualizing the MCP certificate is available.

License

This software is distributed under the Apache License, Version 2.0.

This project includes code from the Apache Xcf project (Apache License, Version 2.0), and the POReID project (MIT License).

Building

Building the project requires that JDK (>=11) and Maven (>=v3.6.3) are installed on the system. The project can then be built like this:

mvn clean install

Sign (requires a gpg key):

mvn -Dskip.signing=false install

Deploy (requires a gpg key registered at sonatype):

mvn -Dskip.signing=false clean deploy -Psonatype

Build the javadocs used for the documentation available at https://maritimeconnectivity.github.io/MCP-PKI/

./javadocs.sh docs

Build the javadocs used for the documentation available at https://maritimeconnectivity.github.io/MCP-PKI/ and push to github:

./javadocs.sh site