Prerequisites

Make sure you first read and understand the What is the S-63 protection scheme guide. This tutorial assumes you are familiar with all the terminology introduced in that guide.

Goal

S-63 (IHO Data Protection Scheme) provides a mechanism to encrypt and protect ENC data from unauthorized use. This encrypted data can be decoded using a specific S-63 model decoder on which you configure the necessary decryption keys.

The goal of this tutorial is to illustrate how you can decode S-63 data using the LuciadLightspeed API and the Cell Permits you obtained from the data provider.

Once the S-63 encrypted data is decoded into an ILcdModel, using and visualizing the model uses the exact same API as for S-57 data. This means that all S-57 documentation about visualizing or accessing the model data can also be applied on S-63 data.

Initial setup on application startup

This step is only required when you are an S-63 manufacturer and you use your own HW_ID. If not, you can skip this step.

When you are a manufacturer and create your own HW_ID instance for your system, you need to specify it to our API so that our model decoders can decrypt the Cell Permits.

This is done by calling a static method on the TLcdS63UnifiedModelDecoder class or using a system property. The following example uses the static method: 

//Configure the HW_ID of the system
//An alternative is using a system property
//See the javadoc of com.luciad.format.s63.TLcdS63UnifiedModelDecoder.setEncryptedHardwareID
//for more information
TLcdS63UnifiedModelDecoder.setUnencryptedHardwareID("A79AB");

//If your license contains a s63CustomerSystemId property, you also need to configure that one
//It should match the value from the license
//This can also be set using a system property
//Consult the javadoc of that method for more information
TLcdS63UnifiedModelDecoder.setS63CustomerSystemID("my_system_id");

This setup step should only be done once.

Configuring the decoder with the Cell Permits

As explained in the What is the S-63 protection scheme guide, decoding of an encrypted ECDIS cell requires:

  • Knowledge of the HW_ID

  • Access to the Cell Permit which is provided by the S-63 data supplier

The model decoder already knows the HW_ID, so the only remaining thing is to provide it access to the Cell Permit: 

TLcdS63UnifiedModelDecoder modelDecoder = new TLcdS63UnifiedModelDecoder();

// Configure the cell permit(s) on the model decoder
// The method you need to call depends on the type of cell permit you received
modelDecoder.setBasicPermitSources(Collections.singletonList("ENC.PMT"));

// In case your cell permit is a PERMIT.txt file, you need to use
// modelDecoder.setMetaPermitSources(Collections.singletonList("PERMIT.txt"));

//The source name passed to the model decoder is the encrypted cell (or a catalogue file)
ILcdModel model = modelDecoder.decode("NO5F1615.000");

The model returned by the model decoder is an ILcd2DBoundsIndexedModel containing S-57 domain objects. S-63 models have exactly the same model structure and use the same domain model as S-57 models. The only difference is the model descriptor, which is a TLcdS63ModelDescriptor in the case of S-63, instead of a TLcdS57ModelDescriptor.

The visualization of the data is identical to the visualization of S-57 data.

An alternative to configuring the permit on the model decoder is storing those permit files in the same folder as the source data. The model decoder will then automatically pick up and use those permit files.

In this case you do not need to call any extra methods on the model decoder before you can use it.

Configuring the public keys on the model decoder

By default, the S-63 model decoder is configured to use several public keys for the verification of the authenticity of the data:

  • The IHO public key that expires in August 2013

  • The IHO public key that expires in the year 2033

  • The PRIMAR public key

Some data providers use another public key. If this is the case for your provider, you can configure one or several public keys, using either the setSACertificateSource/setSACertificateSources or setSAPublicKeySource/setSAPublicKeySources, depending on the format in which the key is distributed.