Main Index

GM-X ERP for Blockchain - the ROSETTANET subsystem

By Tony Marston

26th September 2019

Introduction
Directory structure
Apache configuration
Partner identification
Partner configuration files
X.509 certificates
The Client process
The Server process
The Batch process

Introduction

RosettaNet is a non-profit consortium aimed at establishing standard processes for the sharing of business information (B2B). It is comprised of major Computer and Consumer Electronics, Electronic Components, Semiconductor Manufacturing, Telecommunications and Logistics companies working to create and implement industry-wide, open e-business process standards. These standards form a common e-business language, aligning processes between supply chain partners on a global basis. Documentation on these standards can be accessed at HTTPSs://resources.gs1us.org/rosettanet (login required).

Messages are passed from one trading partner to another as HTTPS/HTTPSS requests which consist of a series of XML documents which have pre-determined structures and content. While RosettaNet also supports the exchange of messages using the SMTP protocol (email) this has been superseded by the use of HTTPS/HTTPSS (web services) as it is faster yet no less secure. This is a client/server protocol which utilises a request/response in a synchronous manner. The client process connects to the server process and sends a request. The server process will analyse that request and return a response before closing that connection. In some cases, especially those which involve a lot of processing which may take longer than the default timeout limit for an HTTPS request, the initial synchronous response will simply acknowledge the receipt of a valid message while the actual processing of the message will then be performed in a separate batch (background) task. This task will send an asynchronous message back to the initiating partner but only if the request failed to process.

The GM-X implementation follows the RosettaNet Implementation Framework version V02.00.01 (RNIF_Spec_V02_00_01). This has a separate PIP (Partner Interface Process) for each business message which can be generated by one trading partner and procesed by another.

Directory structure

The subsystem directory is RosettaNet which contains the following:

The root (RosettaNet) directory contains the following files:

The classes directory contains the following files:

The dtd and xsd directories will contains files for validating each XML document which may be processed by both the client and server programs. Some older documents will have DTD files while other later ones will have XSD files. The system will look for a DTD first, then an XSD. If neither can be found the XML validation will fail and the entire message will be rejected.

The partners directory will contain the configuration files for each participating partner as explained in Partner configuration files.

The www directory is used as the document root for the URL which points to the server program. This provides a URL which is totally separate from the URL which is used by the main GM-X application. Anybody accessing this URL can only access the server.php script and nothing else.

Apache configuration

The following directive can be inserted into the HTTPSd.conf file:

<VirtualHost *:80>
   ServerName <subdomain>.<domain>
   DocumentRoot "F:/Apache2/HTDOCS/GMX-Transix/rosettanet/www"
</VirtualHost>

This identifies the URL that is to be used to access the GM-X RosettaNet server. It allows access to nothing higher than the /rosettanet/www directory.

While <ServerName> can be anything you like, it is usual practice to define it as a subdomain. For example, if your main domain is something.com you could create a subdomain called rosettanet.something.com.

Partner identification

It is the standard within RosettaNet for each trading partner to be identified by their partner_id which is their DUNS Number. The GM-X application uses its own internal numbering system which is known as a party_id. In order to relate a particular party_id with a particular partner_id the GM-X database uses a table called PARTY_IDENTIFICATION which allows any number of different external identities to be assigned to a party. Each partner will therefore require an entry to be added to this table with the fllowing values:

FieldTypeDescription
party_id number The GM-X identification number for this party.
identity_type_id string The literal 'DUNS'.
id_value string The partner's DUNS number.

Partner configuration files

This should contain a configuration file for each trading partner, plus a subdirectory to contain the X.509 certificates used by that partner. There is a file called default.conf which should be copied and renamed to replace default with the partner's DUNS number. The contents of this file can then be amended to provide the relevant configuration data for that partner. The available details are as follows:

<?php

$data = array(
    'id' => '<DUNS number>',
    'name' => '<name>',
    'target_url' => 'HTTPS://domain.com/rosettanet/api',
    'public_key'  => file_get_contents(dirname(__FILE__).'/<subdir>/publickey.cer'),
    // these two are only required for the SENDING partner, otherwise they should be blank
    'private_key' => file_get_contents(dirname(__FILE__).'/<subdir>/privatekey.pem'),
    OR
    'private_key' => file_get_contents(dirname(__FILE__).'/<subdir>/public_privatekey.pfx'),
    'private_key_pass_phrase' => '<password>',
    // end private_key
    'test_or_production' => 'test/production',
    'PartnerRoleClassificationCode' => 'Buyer/Seller',
    'PartnerClassificationCode' => 'Manufacturer/End User',
    'compression' => false,
    'sign' => true,
    'encrypt' => false,
);

return $data;

?>

The id value must be the partner's DUNS number.

The name value must identify the partner's name. This will only be used in the test_client program.

The target_url value must identify the web address which that partner uses to receive RosettaNet requests. All addresses should specify the HTTPSS protocol.

The public_key value must point to the publickey.cer file which is created as specified in X.509 certificates. The value for <subdir> should point to the sub-directory which contains the actual file. Note that each partner must create both a private_key and a public_key, but only the public key should be distributed to others.

The private_key value is ONLY required by the sending partner in order to digitally sign each message. The receiving partner will use his copy of the sending partner's public_key in order to verify the digital signature. This may point to either of the privatekey.pem or public_privatekey.pfx files which are created as specified in X.509 certificates.

The private_key_pass_phrase is ONLY required by the sending partner AND the private_key points to the public_privatekey.pfx file. If the privatekey.pem file is specified then the password cannot be validated.

The test_or_production value should be set to either 'test' or 'production' as appropriate.

The PartnerRoleClassificationCode value should be set to whatever is appropriate for that partner.

The PartnerClassificationCode value should be set to whatever is appropriate for that partner.

The compression value will always be treated as FALSE. Any other value will be ignored.

The sign value will always be treated as TRUE. Any other value will be ignored.

The encrypt value will always be treated as FALSE. Any other value will be ignored.

X.509 certificates

Each partner must create an X.509 certificate comprised of both a public key (the certificate itself) and a private key. It is ONLY the public key which needs to be shared with the other partners. The private key will be used to digitally sign each outgoing message, and the receiving partner will use the sending partner's public key to verify that signature.

This can be a self-signed certificate instead of having to be generated by a Certificate Authority (CA) for the simple reason that all communication via this protocol is between trading partners who are known to each other and therefore trusted. Messages sent by any partner can be guaranteed to be from that partner by comparing the certificate (public key) used to digitally sign each message with that partner's public key which is held on file by the receiving partner. Certificates generated by a CA are only required when dealing with an untrusted organisation.

The procedure used to create a self-signed X.509 certificate is documented at developer.zero.com which uses the OpenSSL library. If your system does not have the OpenSSL binaries pre-installed there are some download sites listed on the OpenSSL wiki page.

Figure 1 - CLI commands to create an X.509 certificate with a public/private key pair

set OPENSSL_CONF=E:\Program Files\OpenSSL-Win64\bin\openssl.cfg

openssl genrsa -out privatekey.pem 1024
openssl req -new -x509 -key privatekey.pem -out publickey.cer -days 1825
openssl pkcs12 -export -out public_privatekey.pfx -inkey privatekey.pem -in publickey.cer

All of these files (publickey.cer, privatekey.pem and public_privatekey.pfx) must be placed in the subdirectory specified as <subdir> in your Partner Configuration File.

Every outbound message will be signed using your private key. Note that it is only the file containing your public key which you should send to your trading partners so that they can verify the digital signature of every inbound message which they receive from you.

The Client process

This is the process used by one partner to send a request to another partner. The steps in this process are as follows:

  1. The partner's application constructs the XML file which is relevant for the PIP message. The client process will then construct the full Business Process Message which is comprised of the following parts:
    1. Preamble - fixed format
    2. Delivery-Header - fixed format
    3. Service-Header - fixed format
    4. Service-Content - a separate format for each PIP.
  2. The client process will also give the message a globally unique Message-ID which conforms to RFC 2111. This should be in a format such as CCYYMMDD-HHMMSS-SSSSS.<random-number>@<domain-name> so that it can be used to easily locate that message in the log directory.
  3. Each of these four parts is an XML file which will be validated against either its DTD or XSD. Any validation failures will cause the transmission of the message to be aborted.
  4. The sender's X.509 certificate will then be checked. If any problem is found the client will abort with a suitable error message. If the certificate is due to expire within the next 7 days a warning email will be sent to the local system administrator.
  5. The full message will then be digitally signed using the sending partner's certificate and private key.
  6. The full message will the written out to the logs/outbound directory
  7. The client process will then connect to the receiving partner's URL in order to send the message. This connection will be held open until a response is returned. This reponse may be one of the following:
    1. An HTTPS response code other than 200 (OK) which sigifies an error which was encountered before the request could be validated.
    2. An Exception message in XML format which identifies some sort of error during the validation of the Preamble, Delivery-Header and Service-Header.
    3. An Acknowledgement Of Receipt which signifies that the message was valid and that the actual processing of the Service-Content has been handed over to a separate batch process.

The actual processing of the Service-Content part of the message is handled in a separate process after the connection with the sending partner has been closed. This is because the time taken to process that request may be longer than the time limit which is usually set for HTTPS requests. This processing may or may not result in a NotificationOfFailure (see Note 2) message being sent to the sending partner as a separate message using a separate connection

The Server process

This is the process used by each partner to receive requests sent by any of the other partners. The steps in this process are as follows:

  1. The message will be assigned a temporary Message-ID where <domain-name> is set to the sender's IP address. This temporary name will be replaced by the actual Message-ID encountered in the message.
  2. The entire message will be written out to the logs/inbound directory using the Message-ID as the file name.
  3. Validate that the message has the right structure with the correct number of component parts. Any errors at this point will result in an HTTPS response code such as 204 (No Content) or 400 (Bad Request). If the message is not digitally signed it will return a response code of either 402 (Unauthorised) or 403 (Forbidden).
  4. The digital signature will be verified and compared with the sender's public key which is known to the receiving partner. Any failures will return a response code of 403 (Forbidden).
  5. If the certificate is due to expire within the next 7 days a warning email will be sent to the local system administrator.
  6. Each of the four component parts, which exist as XML documents, will have their structure validated against the relevant DTD or XSD file. Any failures will result in a HTTPS response code of 400 (Bad Request).
  7. The contents of the Preamble, Delivery-Header and Service-Header will be validated. Any errors will result is a response containing an Exception (see Note 1) message.
  8. Extract the PIP name from the Service-Content and the PIP version from the Service-Header. Look for a class file with this name in the custom-processing/<project> directory. If it does not exist then return an Exception (see Note 1) message.
  9. If there are no errors the server will return a response containing an Acknowledgement Of Receipt message, then will spawn a separate batch process to deal with the Service-Content.

NOTE 1: If an Exception message is generated the text will also be written to the log file.

The Batch process

The actual processing of each PIP document will be handled in a separate batch (background) process as it may take more time than the limit expected for HTTPS requests. The steps in this process are as follows:

  1. This will create a file in the logs/jobs directory to keep a record of its progress.
  2. This will read the message from the copy in the logs/inbound directory using the Message-ID which was pased down from the server process.
  3. Extract the PIP name from the Service-Content and the PIP version from the Service-Header. Look for a class file with this name in the custom-processing/<project> directory. At this point it is known that the file exists. All further processing will be handled by this file.
  4. The contents of the PIP message will be examined to verify that such things as the sending and receiving partners are correct, any order numbers are correct, and any part numbers are correct. Any error at this point will result in a NotificationOffailure (see Note 2) message being sent to the relevant partner and all further processing being terminated.
  5. The process will update the GM-X database using the data supplied in the PIP message. Although unlikely it is possible that this update could encounter an error which will result in a NotificationOffailure (see Note 2) message being sent to the relevant partner.
  6. If there are no processing errors the relevant message file will be moved from the logs/inbound directory to the logs/processed directory.

NOTE 2: If a NotificationOffailure message is generated a copy of this message will be emailed to the local system administrator.

Date created: 26th September 2019

Copyright © 1999-2020 by Geoprise Technologies Licensing, All Rights Reserved.