This article provides technical information on how to integrate the LuciadLightspeed S-63 component in end user applications. It explains at a technical level how to implement each of the requirements described in paragraph I in the document 'S-63 Data Protection Scheme Appendix’[1].

In the code snippets below, it is assumed that s63decoder is an instance of TLcdS63UnifiedModelDecoder or TLcdS63ModelDecoder, used for the decoding of S-63 data.

Guidelines

Authenticate the digital certificate prior to loading the protected ENC information. If the SA Digital Certificate is invalid, prominently display an appropriate message to inform the user about this fact.

  • The digital certificate is used to verify the authenticity of the S-63 data that is distributed. It is required that the authenticity of the digital certificate is verified before any data is decoded.

  • By default, the IHO’s digital certificate is configured on Luciad’s TLcdS63ModelDecoder and TLcdS63UnifiedModelDecoder. It is possible to configure other digital certificates on the decoder. For example, Primar Stavanger signs its S-63 data with its own digital certificate. The application should either use the default IHO certificate, in which case no extra action is required, or ensure that other appropriate digital certificates are set on the decoder:

    Program: S-63 SA certificate configuration
    s63decoder.setSACertificateSource(valid certificate)
  or
s63decoder.setSAPublicKeySource(valid certificate)

    The S-63 decoders allow you to set multiple SA certificates one a single decoder. This is useful if you are using S-63 data from multiple data providers. Each of those data providers may sign its data with a distinct SA digital certificate.

  • TLcdS63ModelDecoder offers the possibility to disable authentication of data for debugging purposes. However, the application should ensure that authentication is always enabled in deployment environments:

    Program: S-63 authentication configuration
    s63decoder.setDoAuthentication(true) (= default setting)

  • If authentication is enabled, TLcdS63ModelDecoder throws an exception during decoding if the digital certificate is unavailable or invalid. This exception will be a TLcdS63Exception with error code SSE_05 (unavailable) or SSE_08 (incorrect format). The application should display an appropriate message to the end user if the decoder throws a TLcdS63Exception with error code SSE_05 or SSE_08 during decoding.

    See Program: S-63 decoding snippet for an illustration.

Allow the user to view the digital certificate / public key, as defined in IHO S-63, and to enter a new official digital certificate/public key issued by Luciad.

  • The application should provide a way to display the digital certificate, used for the authentication of S-63 data, via a UI menu button for example. The certificate’s public key can be retrieved as follows:

    Program: S-63 certificate viewing
    CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
InputStream input = s63Decoder.getInputStreamFactory().createInputStream(fS63Decoder.getSACertificateSource());
Certificate certificate = certFactory.generateCertificate(input);
String publicKey = certificate.getPublicKey();
// Show public key on user request.

Authenticate the Data Server Certificate contained in the Digital Signature file using the digital certificate/public key information. Authentication must be completed for all ENC information prior to loading and processing of encrypted ENCs. The ENC Processing System (EPS) must prominently display an appropriate message to inform the user if the Data Server Certificate is not correctly authenticated.

  • If authentication is enabled, TLcdS63ModelDecoder will throw an exception during decoding if the Data Server digital certificate is invalid. This exception will be a TLcdS63Exception with error code SSE_06 or SSE_024 (Invalid signature). If the certificate has expired or is not valid yet, a warning with error code SSE_022 will be attached to the model. The application should display an appropriate message to the end user if the decoder throws a TLcdS63Exception with error code SSE_06 or SSE_024 during decoding, or if the decoded model has an attached warning with error code SSE_022.

    See Program: S-63 decoding snippet for an illustration.

Following authentication of the Data Server Certificate, extract the Data Server public key from the certificate and use it to verify the signatures of the ENC data files. Verification must be completed prior to loading and processing the encrypted ENCs. The EPS must prominently display an appropriate message to inform the user if an ENC data file signature is found to be invalid.

  • If authentication is enabled, TLcdS63ModelDecoder will throw an exception during decoding if the ENC cell signature is invalid. This exception will be a TLcdS63Exception with error code SSE_09 (No valid signature found). The application should display an appropriate message to the end user in case the decoder throws a TLcdS63Exception with error code SSE_09 during decoding.

    See Program: S-63 decoding snippet for an illustration.

Decrypt the ENC using the appropriate cell key. Validate the ENC checksum after decryption and before conversion into SENC format. The EPS must prominently display an appropriate message to inform the user if the ENC checksum is not correct.

  • Decryption of the ENC is automatically taken care of by the TLcdS63ModelDecoder.

  • In LuciadLightspeed, the ENC checksum validation is done by the TLcdS57CatalogueModelDecoder, because the the S-57 catalogue file contains the ENC checksums. The TLcdS57CatalogueModelDecoder throws a TLcdS57InvalidCheckSumException when an invalid checksum is encountered. The decoder has a flag indicating whether to perform the checksum validation. The flag is disabled by default. Applications must enable the verifyCheckSum flag on the TLcdS57CatalogueModelDecoder and register an S-57 cell exception handler that shows an appropriate message to the end user whenever an invalid ENC checksum is encountered.

    Program: S-63 invalid checksum handling
    TLcdS57CatalogueModelDecoder s57CatalogueModelDecoder = new   TLcdS57CatalogueModelDecoder( s63decoder );

s57CatalogueModelDecoder.setVerifyChecksum( true );
s57CatalogueModelDecoder.setInvalidCellExceptionHandler( new   MyCellExceptionHandler() );

class MyCellExceptionHandler implements ILcdS57InvalidCellExceptionHandler {
  public void handleInvalidCellException(  String aCellSourceName,
              IOException aException ) {
    if ( aException instanceof TLcdS57InvalidChecksumException ) {
      // Show message in UI that the ENC checksum is incorrect.
    }
    else {
      // Another IOException (file not found, unexpected end of file, ...)
    }
  }
}

    Note that enabling the checksum validation may have an impact on the decoding performance.

Only hold decrypted ENC information temporarily before conversion to SENC. ENC Information must only be stored in its encrypted state, or as a SENC. It must not be stored in a decrypted state.

  • LuciadLightspeed does not use a SENC, nor does it store any decrypted S-63 data on the EPS, whether the decoding was successful or not. As such, this is not applicable to LuciadLightspeed. The application should never store decoded S-63 models (ILcdModel) into any other unencrypted format.

Delete the decrypted ENC information immediately upon successful conversion to SENC. If the SENC conversion fails, the system must delete the decrypted ENC information immediately and further processing must be on the encrypted ENC. The EPS must prominently display an appropriate message to inform the user about the problem.

  • LuciadLightspeed does not use a SENC, nor does it store any decrypted S-63 data on the EPS, whether the decoding was successful or not. As such, this is not applicable to LuciadLightspeed. The application should never store decoded S-63 models (ILcdModel) into any other unencrypted format.

Do not provide within the EPS a facility to copy the temporary unprotected ENC files that exist after decryption and before conversion to SENC.

  • TLcdS63ModelDecoder does not use an intermediate format to store the decrypted ENC data. As such, there is no risk of copying the decrypted data. The application should not provide any facility to store the decoded S-63 model ILcdModel into another file format, for example by providing an export mechanism using a GML, SHP or other model encoder.

Store Cell Permits as defined in the Proprietary Information in the same format they were received.

  • The application should store cell permits (enc.pmt or permit.txt) as received from the data provider. There is no need for conversion. These files can be directly passed onto the TLcdS63ModelDecoder (using setBasicPermitSource or setMetaPermitSource).

Conduct the system date and subscription status checks detailed in the S-63 Documentation, and provide prominent warnings, also detailed in the S-63 Documentation, when appropriate.

  • TLcdS63ModelDecoder attaches a warning to the decoded model if the subscription has expired. This warning will be a TLcdS63Exception with error code SSE_015 (Subscription license has expired). If the decoding of the cell fails and the subscription has expired, the decoder will throw a TLcdS63Exception with error code SSE_015. The application should display an appropriate message to the end user if the decoder throws a TLcdS63Exception with error code SSE_015 during decoding, or if the decoded model has a warning with error code SSE_015 attached to it.

    See Program: S-63 decoding snippet for an illustration.

The EPS must provide support for all error messages or equivalent detailed in the S-63 Documentation.

  • TLcdS63ModelDecoder provides support for the following TLcdS63Exception exception codes:

    Table 1. Supported exceptions

    SSE_05

    SA digital certificate unavailable

    SSE_06

    Data Server digital certificate invalid

    SSE_08

    SA digital certificate incorrect

    SSE_09

    ENC Cell signature invalid

    SSE_011

    Cell permit unavailable

    SSE_012

    Cell permit format incorrect

    SSE_013

    Cell permit checksum incorrect

    SSE_015

    Subscription license has expired

    SSE_020

    Subscription license will expire in less than 30 days

    SSE_021

    Decryption failed

    SSE_022

    SA certificate has expired

    SSE_024

    ENC Cell signature format incorrect

    SSE_026

    ENC is not authenticated by the IHO acting as SA

    All these exceptions are thrown during the decoding of an ENC cell (during TLcdS63ModelDecoder.decode()). This corresponds to the exceptions described in the decoding process flow chart in the S-63 Specification Edition 1.0, paragraph 14.6.

    The application should display appropriate messages to the end user for all of the supported exceptions listed above.

    See Program: S-63 decoding snippet for an illustration.

    Note that SSE_014 (incorrect system date) and SSE_016 (invalid CRC checksum) are not supported by TLcdS63ModelDecoder: SSE_014 cannot be enforced in a general way. The application may implement one or more application-specific tests to verify whether the system date is correct. SSE_016 is handled by the TLcdS57CatalogueModelDecoder. For more information, see above.

Decoding code snippet

The following code snippet summarizes the correct procedure for decoding S-63 data after the decoder has been set up and configured correctly. See Guidelines for more information.

Program: S-63 decoding snippet
 try {
      ILcdModel model = s63decoder.decode( aSource );
      TLcdS63ModelDescriptor descriptor = (TLcdS63ModelDescriptor) model.getModelDescriptor();
      for (Exception exception : descriptor.getWarnings()) {
        if (exception instanceof TLcdS63Exception) {
          TLcdS63Exception s63Exception = (TLcdS63Exception ) exception;
          if (s63Exception.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_015) {
            // Show message in UI that the Subscription License has expired.
          }
          else if (s63Exception.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_020) {
            // Show message in UI that the Subscription License will expire in less than 30 days.
          }
          else if (s63Exception.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_022) {
            // Show message in UI that the SA digital certificate has expired.
          }
          else if (s63Exception.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_026) {
            // Show message in UI that the cell is not authenticated by the IHO as SA.
          }
        }
      }
    }
    catch ( TLcdS63Exception e ) {
      if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_05) {
        // Show message in UI that digital certificate is unavailable.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_06) {
        // Show message in UI that Data Server digital certificate is invalid.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_08) {
        // Show message in UI that SA digital certificate is invalid.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_09) {
        // Show message in UI that the ENC cell signature is invalid.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_011) {
        // Show message in UI that the Cell Permit could not be found.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_012) {
        // Show message in UI that the Cell Permit format is incorrect.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_013) {
        // Show message in UI that the Cell Permit checksum is incorrect.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_015) {
        // Show message in UI that the Subscription License has expired.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_021) {
        // Show message in UI that the decryption has failed - no valid cell permit was found.
      }
      else if (e.getErrorCode() == TLcdS63Exception.ErrorCode.SSE_024) {
        // Show message in UI that the ENC signature format is incorrect.
      }
      else {
        // Show message in UI that an unexpected error has occurred.
        // This can only happen after upgrading to a more recent LuciadLightspeed version
        // which would use more of the S-63 error codes.
      }
    }
    catch (IOException e) {
      // Another IOException (file not found, unexpected end of file, ...)
      // Show appropriate message in UI (this is not required by S-63).
    }
1. The document 'S-63 Data Protection Scheme Appendix' is a legal document included as an appendix to the LuciadLightspeed license agreement. The appendix is included with all LuciadLightspeed purchases that come with the S-63 component.