Online Level Control Protocol (OLCP)

This section describes the Online Level Control Protocol (OLCP).

This page discusses:

Overview

The problem of managing the compatibility between collaborating DS components is essential (client and servers must always be on the same build levels (GAs, FPs)).

To guarantee compatibility and prevent damage (such as data corruption) resulting from usage of incompatible components, a simple robust functionality called Online Level Control Protocol (OLCP) has been delivered and supports two enhancements:

  • mistakes in the customer configuration deployment will be detected during user login
  • customers can add their own custom tokens in the certificates, and finely control compatibility between their own custom build levels.

The Online Level Control protocol (OLCP) is based on a simple client/server symmetrical handshake pattern that takes place at login. It is combined with a declarative system of certificates, in each tier involved in the handshake.

Certificates

The native app holds two certificates:

  • SupByClient: contains the tokens supported by the client
  • ReqByClient: contains the tokens required by the client.

The server holds two certificates:

  • ReqByServer: contains the tokens required by the server
  • SupByServer: contains the tokens supported by the server.

Tokens

The certificate is composed of tokens. Each token contains the following data:

  • Key: a unique string that identifies the token
  • Rule: the type of rule used to validate the token during the certificate exchange process
  • Comment: additional information about content of token.

There are two kinds of tokens:

  • Internal development: delivered by development team
  • Custom: created by the customer to control compatibility between customized components.

Negotiation

The communication is initiated by the client during Login protocol. The client and server perform the handshake by exchanging their certificates and cross-checking them. Once the handshake has successfully taken place, the rest of the login process is performed.

Simplified sequence of a OLCP handshake:

The client sends its SupByClient certificate and the server checks if it matches its ReqByServer certificate.

Then the server sends its SupByServer certificate and the client checks if it matches its ReqByClient certificate.

The client and server are valid if the two previous tests are successful. This is a symmetrical check:

  • SupByClient/ReqByServer
  • SupByServer/ReqByClient

How to Deliver a Custom Token

On the server side, the custom tokens of certificates are delivered in two certificate files:

  • OLCPCustomCertificateRequired.xml
  • OLCPCustomCertificateSupplied.xml

On the server, you have two possibilities to deploy the custom file:

  • External deployment: an environment variable or property contains the path where the OLCPCustomCertificateRequired.xml and OLCPCustomCertificateSupplied.xml files are deployed. The name of this variable (or property) is: OLCPCustomCertificatePath. This environment variable must be set before the application server is started.

    Example how to set the properties:

    • When using a JVM, properties can be specified to the jvm, e.g java -D OLCPCustomCertificatePath =/tmp/MyCertif …..
    • Example how to set the environment variable in a JVM shell or .bat starter:

      export OLCPCustomCertificatePath =/tmp/MyCertif

      or:

      set OLCPCustomCertificatePath =/tmp/MyCertif

  • Internal deployment: the OLCPCustomCertificateRequired.xml and OLCPCustomCertificateSupplied.xml files must be delivered in the path: $DeploymentRoot\enovia\WEB-INF\resources.

General rules:

  • custom tokens cannot overload inline tokens - an exception will be raised if this happens. This can be easily prevented by avoiding DS reserved namespace DS.internal to prefix custom token key.
  • If an external deployment is activated, then internal files are overridden by the external files.

In the server, both OLCPCustomCertificateRequired.xml and OLCPCustomCertificateSupplied.xml files are delivered in: .

$DeploymentRoot\enovia\WEB-INF\resources\logincertificates\sample

After WAR deployment to activate these certificates, you must copy them to:

$DeploymentRoot\enovia\WEB-INF\resources

In the native app, both PLM1.OLCPCertificateRequired.xml and PLM1.OLCPCertificateSupplied.xml files are delivered in:

$OS\resources\logincertificates\sample

To activate these certificates you must copy them to:

$OS\resources\logincertificates

The certificates are provider dependent. For the native app, there will be two files for each provider. 'PLM1' is the alias of the data provider, from the native app standpoint. Custom tokens cannot overload in-lined tokens: an exception will be raised if this happens.

This can be easily prevented by avoiding DS reserved namespace DS.internal to prefix custom token key.

Each certificate is composed of a token. Each token is composed of the following fields:

  • Key: identification name
  • Rule: the rule apply for token: Exit
  • Comment: additional information about content of token

The content of xml files are case sensitive the available characters are: [a-z], [A-Z], [0-9],[.]

Example of OLCPCertificateRequired.xml file:

<? xml version="1.0" encoding="UTF-8" ?>
<!-- OLCPCertificate Required certificate: Declaration of tokens required -->
< certificate >
<!--Token 'exist' rule-->
<!--Checks if the token is declared -->
< token key ="NewCustomDev1" rule ="exist">
<comment>New CAA development 1</comment>
</ token >
</ certificate >

Example of OLCPCertificateSupplied.xml file

 <? xml version="1.0" encoding="UTF-8" ?>
<!-- OLCPCertificate Supplied certificate: Declaration of tokens supplied -->
< certificate >
<!--Token 'exist' rule-->
<!-The rule attribute is optional here-->
< token key ="NewCustomDev1" >
<comment>New CAA development 1</comment>
</ token >
</certificate>

Case 1 : Client requires a compatibility check.



Case 2 : Server requires a compatibility check.



Sample with default supplied token

On the server side, the custom tokens of certificates are delivered in two certificate files:

  • OLCPCustomCertificateRequired.xml
  • OLCPCustomCertificateSupplied.xml

On the server, you have two possibilities to deploy the custom file:

  • External deployment: an environment variable or property contains the path where the OLCPCustomCertificateRequired.xml and OLCPCustomCertificateSupplied.xml files are deployed. The name of this variable (or property) is: OLCPCustomCertificatePath. This environment variable must be set before the application server is started.

    Example how to set the properties:

    • When using a jvm, properties can be specified to the jvm, e.g java -D OLCPCustomCertificatePath =/tmp/MyCertif …..
    • Example how to set the environment variable in a JVM shell or .bat starter:

      export OLCPCustomCertificatePath =/tmp/MyCertif

      or:

      set OLCPCustomCertificatePath =/tmp/MyCertif

  • Internal deployment: the OLCPCustomCertificateRequired.xml and OLCPCustomCertificateSupplied.xml files must be delivered in the path: $DeploymentRoot\enovia\WEB-INF\resources.

After WAR deployment to activate these certificates, you must copy them to:

$DeploymentRoot\enovia\WEB-INF\resources

In the native app, both PLM1.OLCPCertificateRequired.xml and PLM1.OLCPCertificateSupplied.xml files are delivered in:

$OS\resources\logincertificates\sample

To activate these certificates you must copy them to:

$OS\resources\logincertificates

Default OLCPCertificateRequired.xml file:

<? xml version="1.0" encoding="UTF-8" ?>
<!-- OLCPCertificate Required certificate: Declaration of tokens required -->
< certificate >
<!--Token 'exist' rule-->
<!--Checks if the token is declared-->
< token key ="DS.internal.SDV1" rule ="exist">
<comment>New stream Descriptor ReqByServer 1</comment>
</ token >
 </ certificate >

Default OLCPCertificateSupplied.xml file:

<? xml version="1.0" encoding="UTF-8" ?>
<!-- OLCPCertificate Supplied certificate: Declaration of tokens supplied -->
< certificate >
<!--Token 'exist' rule-->
<!-The rule attribute is optional here-->
< token key ="DS.internal.SDV1" >
<comment>New stream Descriptor SupByServer 1</comment>
</ token >
</certificate>

Compatibility:

GA: Release code GA

CSupplied: supplied certificate

CRequired: required certificate

CATIA CATIA + CSupplied CATIA + CRequired CATIA + CRequired + CSupplied
ServerConnection OKConnection OKConnection KOConnection KO
Server + CRequired Connection KOConnection OKConnection KOConnection KO
Server + CRequired + CSupplied Connection KOConnection OKConnection KOConnection OK
Server + CSuppliedConnection OKConnection OKConnection OKConnection OK