HOW-TO Handle X.509 Certificates in SeaSWIM

Version Date Sign Description

0.9 2017-12-04 MO Added description how to use link service to vesselUpdated and added description to issue Host Certificates

1.0 2019-03-28 MO Editorial updates

This HOW-TO explains the procedure to issue certificates to be usedin Service-to-Service interaction in SeaSWIM and according to MCP.

Certificates

Host certificates are used to identify machines (virtual or real) by hostname for secure services.

Client certificate is a type of digital certificate that is used by client systems to make authenticated requests to a remote server.

Mutual Authentication1. A server certificate is a required part of any SSL communication. The server certificate is a digital certificate that contains basic information and a digital signature that properly identifies the server that it is associated with. It is the means by which a client is assured of the identity and authenticity of the server with which it is communicating.

2. Server address validation is an optional part of SSL server authentication that adds an extra layer of security and server address checking. Server address validation simply means that the client validates that the URL that is contained in the server certificate and the URL of the server with which the client is attempting to communicate are in fact identical.

These two components, server certificate and server address validation, work together to establish trust between the client and the server so that the client is assured that it is indeed communicating with the proper server and not with some other potentially malicious server.

Now that we’ve established what we mean by server authentication, let’s move on to client authentication. Essentially, client authentication is the same as server authentication, only this time it is a means of authenticating and identifying the client to the server. One thing to note is that whether client authentication is required or not for a particular server is something that is specified by that server. A server can be configured to allow connections from any client, or it can be configured to require any clients that attempt to connect to it to be authenticated. So, for a client to authenticate, it involves a client certificate and optionally client address validation.

Just like a server certificate, a client certificate contains basic information about the client’s identity, and the digital signature on this certificate verifies that this information is authentic. Client address validation, like its server counterpart, validates the URL from which the client is communicating and validates that it matches the URL contained in the client certificate. These aspects of client authentication protect a server by ensuring that it is accepting a communication from a known client instead of from an unknown and potentially malicious entity.3

The use of client authentication is appropriate for a scenario where the server should only accept connections from a specific limited group of authorized/allowed clients. An example of such a scenario would be where a company wants to limit connections to its server to only be coming from the company’s legitimate business partners. Client authentication lends itself quite well to this type of scenario.

We’ve briefly talked about server authentication and client authentication, but at the beginning of this blog entry I said that we would be discussing two-way authentication. So when am I finally going to get around to talking about that? Well, actually, we already have. Two-way authentication, also commonly referred to as mutual authentication, is a term used to refer to the combination of server and client authentication. The authentication that is occurring is mutual, or two-way, because the server is authenticating itself to the client, and the client is authenticating itself to the server.

One thing to note in all of this is that in an SSL communication, client authentication never occurs alone. As I said above, at the bare minimum an SSL communication requires server certificate authentication. So an SSL communication can either have server authentication only, or it can have two-way authentication.

Host certificate detailsHost certificates are used to identify machines (virtual or real) by hostname for secure services.

The common name (CN) represents the name protected by the SSL certificate. The certificate is valid only if the request hostname matches the certificate common name.

The Common Name (also CN) identifies the host name associated with the certificate, for

example www.example.com or example.com.

It consists of a single host name in case of a single-name certificate (e.g. example.com, www.example.com), or a

wildcard name in case of a wildcard certificate (e.g. *.example.com). In all cases, it is not an URL and therefore it

doesn’t include any protocol (e.g. http:// or https://), port number, or pathname.

https://support.dnsimple.com/

Use of host certificate in STM• The Host Certificate is required and shall contain a matched

Common Name (CN) with the URL where the server is located.

• The Host Certificate shall be valid

• The Host Certificate shall be issued by a trusted party

ISSUE: Shall the client check the organisation (O) in the host certificate, or it is enough to check match between CN from host certificate with the domain name in the called URL?

Client Certificate details

Client certificate is a type of digital certificate that is used by client systems to make authenticated requests to a remote server.

Use of client certificate in STM• The Client Certificate shall authenticate a unique actor

(ship, shore centre, service provider etc) and the organisation (O).

– ISSUE; How identify the unique actor, such as a unique ship? Today using service certificates, we have the service identity (MRN id) in the UID field in the client certificate. Hence ,it is the service that are identified, not the actor per sé.

• The Client Certificate shall be valid

• The Client Certificate shall be issued by MCP (hence MCP Root Certificate shall be part of the chain of certificates)

Sequence

ClientSR Host

findService

URL

service call

C

H

C Client Certificate

H Host Certificate

Check Client Certificate

Check Host Certificate

CRLIR

Establish SSL

CRLIR

Check Host Certificate• Validity (incl CRL check)• Trust• Domain match (CN)

Check Client Certificate• Validity (incl CRL check)• Trust

Extract information for authorization check• Org (O)• ServiceID (UID)• IMO and MMSI can be included

for ships

CRL=Certificate Revocation List

Client Certificate in STM Live Testbed

Service Certificate

The preferred client certificate within a service-to-service interaction is the Service Certificate. This certificate contains the service identity (UID) and the organisation (O), both in MRN format that can be used for lookup in Identity and Service Registry for more details.

VesselIf the service is provided by a ship, a vessel identity can be linked to the Service, and the vessel identifications (IMO and MMSI) will then be included as separate fields in the service certificate.

Client Certificates in STM Live Testbed

Create Host Certificates in STM (1)

Host certificate associated with one or several service can be created by registering an ID Service directly in the Identity Registry. This way there will NOT be created any service instances in the Service Registry. The Certificate issued this way will look exactly like the certificates created for the Service Instances

Create Host Certificates in STM (2)

In the case where a host certificate is used only for a single service, the same certificate issued via Service Instance can be used both as client certificate and host certificate.

Create Host Certificate in STM (3)

A certificate can also be bought from a well-known trusted Certificate Authority (CA), currently from GeoTrust, Let’s Encrypt or DigiCert (only valid in the STM version of JAVA KeyStore).

The Organisation (O) shall match a organisation registered in the Identity Registry (e.g. Transas, Furuno).

The Common Name (CN) shall match the domain where the server is located (e.g. transas.com, furuno.fi)

MCP Certificates

• Service Certificate

• Device Certificate

• User Certificate

• Organisation Certificate

• Vessel Certificate

MCP Certificates

HOW-TO Check Host certificate

openssl s_client -connect <URL/domain name>:<port>

Example:

openssl s_client -connect dmsvdbvispublic-stage2.azurewebsites.net:443

openssl s_client -connect smavistest.stmvalidation.eu:443

Using Service Certificate

Using Vessel Certificate

Using Device Certificate

Revoke certificate

Alt 1) Logon to MCP Portal and find the identity, and revoke the certificate.

This can only be done with identities within your own organisation.

Presumable also by MCP ”Super user”

Check if certificate has been revoked

• Link in certificate to CRL (Certificate Revocation List)

Login to MC Portal –MC STAGING=STM TEST

https://staging-management.maritimecloud.net

MC Portal - Service Registry

MC Portal - Service Registry

Issue Certificate

• Select the Service Instance or ID Service for which to create a certificate

• Press ”Issue new Certificate”

• Press ”Download Certificate”

Do this immediately after issuing! It’s the only timeyou can download the private key