IDC/CD Receiver/SDD16 March 2004

English only

CD Receiver Software Design Description

This document defines the CD Receiver software design description. The software designwill be used as the basis for implementation.

Summary

CD Receiver is a software system that can receive, and store, continuous seismoacoustic datafrom IMS stations (or from a data centre forwarding data from IMS stations). The software isable to receive connection requests. If the request is valid, the software establishes aconnection with the station. Multiple simultaneous connections can be established. For eachconnection, the software is able to authenticate and store the received data. A number ofsummary files can also be generated. The software allows previously received data to bechecked off-line for errors.

IDC/CD Receiver/SDDPage 2

16 March 2004

Document History

Version Date Author Description

0.5 06 September 2002 Stephen Lloyd Conversion of Siemens’ document to IDC format

0.6 20 September 2002 Gerald Klinkl Document update

0.7 7 October 2002 Gerald Klinkl Document update

0.8 30 October 2002 Gerald Klinkl Document update

0.9 16 December 2002 Gerald Klinkl Document update (AckNack behaviour and authentication)

0.10 8 January 2003 Gerald Klinkl Rename of some configuration parameters, largeauthentication update and more AckNack behaviour

description

0.11 31 January 2003 Gerald Klinkl Update offline section

0.12 10 February 2003 Gerald Klinkl Document Update (ARM keys, logging and more)

0.13 25 February 2003 Gerald Klinkl Document update (index file, more about offline mode)

0.14 12 March 2003 Gerald Klinkl Document update (wfdisc record, configurationparameters, authentication update)

0.15 23 April 2003 Gerald Klinkl Document update (authentication update)

0.16 25 May 2003 Gerald Klinkl Document update (offline mode and certification threadupdate)

0.17 7 June 2003 Gerald Klinkl Document update

0.2 31 July 2003 Stephen Lloyd Made consistent with SRS and SUG

0.21 19 August 2003 Stephen Lloyd Comments from Peder Johansson

0.22 01 September 2003 Stephen Lloyd Removed references to detailed design

0.23 11 September 2003 Gerald Klinkl Add thread synchronization chapter

0.24 25 September 2003 Gerald Klinkl Move ‘Error Checking Functionality’ Chapter to handlingThread, Update Offline Sender thread chapter

0.25 15 January 2004 Gerald Klinkl Update document and add Command Request Frames

0.26 24 February 2004 Stephen Lloyd Small comments and suggestions

0.3 16 March 2004 Gerald Klinkl Replace Visio drawings with Word drawings

IDC/CD Receiver/SDDPage 3

16 March 2004

Contents

1. Scope .................................................................................................................................. 51.1. Identification .............................................................................................................. 51.2. System Overview ....................................................................................................... 51.3. Document Overview .................................................................................................. 5

2. External Interfaces.............................................................................................................. 62.1. Libraries ..................................................................................................................... 6

2.1.1. Public Libraries .................................................................................................. 62.1.2. IDC Libraries...................................................................................................... 6

3. Threads ............................................................................................................................... 63.1. Main Thread ............................................................................................................... 7

3.1.1. CD Receiver Configuration................................................................................ 73.1.2. User Interaction .................................................................................................. 73.1.3. Process Flow ...................................................................................................... 83.1.4. State Diagram..................................................................................................... 93.1.5. Logging .............................................................................................................. 9

3.2. Monitor Thread ........................................................................................................ 103.2.1. Standard Information........................................................................................ 103.2.2. Station Information .......................................................................................... 103.2.3. State Diagram................................................................................................... 123.2.4. Logging ............................................................................................................ 12

3.3. Listener Thread ........................................................................................................ 133.3.1. Connection Requests ........................................................................................ 133.3.2. Command requests ........................................................................................... 143.3.3. Process Flow Diagram ..................................................................................... 173.3.4. State Diagram................................................................................................... 183.3.5. Logging ............................................................................................................ 18

3.4. Handling Thread....................................................................................................... 203.4.1. Thread Initialization ......................................................................................... 213.4.2. Main Loop ........................................................................................................ 213.4.3. Error Checking Functionality........................................................................... 273.4.4. Process Flow Diagram ..................................................................................... 293.4.5. State Diagram................................................................................................... 303.4.6. Logging ............................................................................................................ 30

3.5. Certificate Thread..................................................................................................... 313.5.1. State Diagram................................................................................................... 323.5.2. Logging ............................................................................................................ 32

3.6. Offline Sender Thread.............................................................................................. 323.6.1. State Diagram................................................................................................... 333.6.2. Logging ............................................................................................................ 33

3.7. Thread synchronization ............................................................................................ 334. Error Policies.................................................................................................................... 34

4.1. Non-strict Mode ....................................................................................................... 344.2. Strict Mode............................................................................................................... 35

Appendix I CD-1.1 Receiver Design Details ...................................................................... 36Appendix II Station Equipment Diagrams ........................................................................... 37Terminology............................................................................................................................. 39

Glossary................................................................................................................................ 39Abbreviations ....................................................................................................................... 39

IDC/CD Receiver/SDDPage 4

16 March 2004

References ................................................................................................................................ 40

IDC/CD Receiver/SDDPage 5

16 March 2004

1. SCOPE

1.1. Identification

This document applies to CD Receiver version 1.0.

1.2. System Overview

CD Receiver is a software system that can receive, and store, continuous seismoacoustic data.The data will be sent from IMS stations (or from a data centre forwarding data from IMSstations) according to the formats and protocols defined in IDC (2002), Formats and ProtocolsCD1.0 and IDC (2002), Formats and Protocols CD1.1.

The software is able to receive connection requests from data providers. If the request is valid,the software establishes a connection with the station. Multiple simultaneous connections canbe established.

For each connection, the software can authenticate and store the received data. The receiveddata is stored in binary format. A number of summary files can also be generated. Thesoftware also allows previously received data to be checked off-line for errors.

The primary user of the software will be the International Monitoring System (IMS) Divisionat the Comprehensive Nuclear-Test-Ban Treaty Organization (CTBTO). In addition, it isexpected that the software will be used at National Data Centres (NDCs). The software isavailable to State Signatories.

The software will continue to develop in the future. This is required in order to followexpected advances in the formats and protocols (for example, the addition of command andcontrol messages).

1.3. Document Overview

This document defines the CD Receiver software design. The software design will be used asthe basis for implementation. The design is based upon the software requirements described inIDC (2003), CD Receiver Software Requirements Specification.

This document is mainly intended for developers, maintainers and documentation writers. It isalso of interest to project management, requirements analysts, quality assurance staff and userrepresentatives.

Each mandatory, design decision is stated using the word shall or will. Each designrecommendation is stated using the word should. A permissible course of action is statedusing the word may. This convention is used in ISO/IEC (1995), ISO/IEC12207.

This document is compliant with IDC (2003) Software Design Description Template, IDC(2002), Software Documentation Framework and the CTBTO/PTS (2002), Editorial Manual.

IDC/CD Receiver/SDDPage 6

16 March 2004

2. EXTERNAL INTERFACES

All external interfaces visible to the user (command line interface, configuration options,input files and output files) are described in IDC (2003), CD Receiver Software User Guide.

2.1. Libraries

2.1.1. Public Libraries

Table 1. Public LibrariesType Description

Standard C Required for all C programs and used automatically when a C program is linked.

POSIX threads Required for the POSIX threads of CD Receiver (-lpthread).

Socket Used for the network communication of CD Receiver (-lsocket and -lnsl; included in thestandard C library on Linux).

Mathematic Used for simple arithmetic by CD Receiver (-lm; most of the functions are included in thestandard C library on Linux).

Crypto Used for authentication verification. CD Receiver uses a library coming with the opensslpackage (-lcrypto).

LDAP Used to retrieve certificates from an LDAP directory server. CD Receiver uses a librarycoming with the openldap package (-lopenldap).

2.1.2. IDC Libraries

Table 2. IDC LibrariesType Description

cancomp Used for Canadian compression/uncompression and is part of the CD-Tools distribution.

paridc Used for reading and processing parameter files and is part of the CD-Tools distribution.

cd Used for decoding of CD frames and is part of the CD-Tools distribution

3. THREADS

The software will contain the following threads:

(a) Main thread: Configures system, pre-loads authentication keys, spawns Monitor andCertification thread (if configured), spawns Listening thread in online mode or OfflineSender thread in offline mode and handles user requests.

(b) Listening thread: handles incoming connection requests and spawns a handling threadfor each valid connection request. Also handles incoming command requests.

IDC/CD Receiver/SDDPage 7

16 March 2004

(c) Offline Sender thread: reads binary data to check, and emulates a sender in offlinemode.

(d) Monitor thread: prints usage summaries.(e) Certificate thread: checks if new keys are available or if cached keys have been

revoked.(f) Handling threads: spawned by the listening thread. Services a particular sender. There

is one handling thread per connection for the duration of the connection.

The relationship between the different threads is shown in Appendix I, Figure 13, page 36.

3.1. Main Thread

The main thread is primarily concerned with system configuration and starting monitor,certificate and listener threads in online mode or offline sender thread in error checking mode.When all required threads are started, the main thread waits for user shutdown requests.

3.1.1. CD Receiver Configuration

CD Receiver is configured on start-up via a configuration file. A subset of the configurationparameters can be changed during runtime using the CD Receiver command interface (seeIDC, 2004, CD Controller Software User Guide) .

If the configuration parameter verboseEnable is set, the current configuration is dumped toSyslog (see IDC, 2003, Using Syslog).

3.1.2. User Interaction

Currently user run-time interaction with CD Receiver is limited to CD Receiver termination.This is achieved with pressing control C (ctrl-c) on the controlling terminal or sending aSIGINT signal to the CD Receiver process. Upon receipt of this termination request the mainthread will begin an orderly shutdown of CD Receiver. In this shutdown mode all of thehandling threads may finish handling the frame that they are currently processing beforeterminating. However, if, under certain circumstances, the user does not wish to wait for sucha graceful shutdown, by issuing a further control C or sending a SIGUSR1 signal a rapidshutdown of CD Receiver can be requested. This causes the immediate, but safe, shutdown ofCD Receiver. The handling threads still send the appropriate terminating Alert Frames, closethe log files and terminate in an orderly fashion, but they abandon processing the currentframe.

IDC/CD Receiver/SDDPage 8

16 March 2004

3.1.3. Process Flow

Figure 1. Main thread process diagram

start

Spawn MonitorThread

Configure Receiver

mode

Shutdown

online

Initialize Authentication

initialize Logging

Spawn CertificateThread

Spawn ListeningThread

Wait for usertermination

Wait for usertermination or alldata processed

Spawn Offline SenderThread

offline

Cause orderly shutdownor receiving request

IDC/CD Receiver/SDDPage 9

3.1.4. State Diagram

Figure 2. Main thread state diagra

3.1.5. Logging

The following events are logged to Syslog:

(a) CD Receiver started. The start time, CD Receiver versievent is logged with LOG_NOTICE priority. For exampl

Cdreceiver 0.4.9 started: 3/23/2002 12:00

(b) CD Receiver stopped. The stop date, time and reason arewith LOG_NOTICE priority. For example:

Receiver stopped by signal 2: 3/23/2002 13

(c) No key found for station. A key, which is specified infound. This event is logged with LOG_WARNING priorit

Can't find LDAP key for station PPTM speciin keyPreloadFile <keyPreloadFile>

(d) Load a key or certificate. This event is only logged if veris logged with LOG_INFO priority. For example:

Loaded key [o=CTBTO;ou=IDC Test;l=PPTM]

Initialize

Wait for usertermination

request

Wait for usertermination

requeststt

Userterminationrequest or

all datasent

Usertermination

request

Startapplication

All threadsshutdown orsecond user

Wait forstation

threads toshutdown

m

on and date are:

by User 500

logged. This e

:00

the keyPreloay. For example

fied

boseEnable is

Wait foration threado shutdown

terminationrequest

t

threadshutdownor second

userermination

onlinemode

offlinemode

16 March 2004

e logged. This

vent is logged

dFile, can't be:

set. This event

IDC/CD Receiver/SDDPage 10

16 March 2004

for station PPTM from LDAP

3.2. Monitor Thread

The monitor thread of CD Receiver is spawned by the main thread and is primarily concernedwith gathering and reporting utilization information. Information is printed when CDReceiver exits and on defined time intervals (see summaryRefreshTime)..

3.2.1. Standard Information

The monitor thread will output the following standard information:

(a) CD Receiver start time.(b) Utilization information for each station (if verboseEnable is set).(c) Listener information. Listener information includes address information for the well-

known port and information about data that could not be related to a particular station.Frames that are too short or illegal station names could cause this. The informationconsists of details of failed connection requests, number of frames and bytes received.

(d) Summary for CD-1 stations. The summary for CD-1 stations contains the addedvalues of all CD-1 stations. The summary information is the same as the informationfor a single station, with the exception of last connection start time, end time, type andport.

(e) Summary for CD-1.1 stations.(f) Summary for all stations.(g) Thread information including:

(i) Number of threads started,(ii) Number of threads in use,(iii) Number of threads that have been shut down.

3.2.2. Station Information

For each station, the monitor thread will output the following timing information:

(a) Last connection start time.(b) Last connection stop time (printed only if station is currently not connected).

For each station, the monitor thread will output connection information including:

(a) State (unconnected, connecting, waiting, connected);(b) Station type (CD-1 or CD-1.1);(c) Used Port;(d) Whether frame signature authentication is active;(e) Number of valid connections requests;(f) Number of connection request warnings;(g) Number of connections since start up of CD Receiver;(h) Number of connection warnings.

IDC/CD Receiver/SDDPage 11

16 March 2004

For each station, the monitor thread will output details of failed connection requestsincluding:

(a) Station already connected;(b) Invalid station name;(c) Invalid IP address;(d) Authentication failure (only CD-1.1) during connection attempt;(e) Handling thread failed to initialize;(f) Incorrect frame format;(g) Connection requests which have timed out;(h) Connection terminated;(i) Insufficient resources to handle connection.

For each station, the monitor thread will output details of failed connections including:

(a) Authentication failure;(b) Incorrect Format;(c) Connections which have timed out;(d) Connection terminated;(e) Insufficient resources to handle connection.

For each station, the monitor thread will output details of frames and bytes received including:

(a) Number of Connection Request Frames received;(b) Number of Data Format Frames received (always zero for CD-1.1);(c) Number of Data Frames received;(d) Number of Alert Frames received;(e) Number of AckNak Frames received (always zero for CD-1);(f) Number of Option Request Frames received (always zero for CD-1);(g) Number of Option Response Frames received (always zero for CD-1);(h) Number of Command Request Frames received (always zero for CD-1);(i) Number of Command Response Frames received (always zero for CD-1);(j) Number of invalid frames received;(k) Number of signed and unsigned frames received;(l) Current receive buffer size.

For each station, the monitor thread will output details of frames and bytes sent including:

(a) Number of Connection Response (CD-1.1) or Port Assignment (CD-1) Frames sent;(b) Number of Alert Frames sent;(c) Number of AckNak Frames sent (always zero for CD-1);(d) Number of Option Request Frames sent (always zero for CD-1);(e) Number of Option Response Frames sent (always zero for CD-1);(f) Number of Command Request Frames sent (always zero for CD-1);(g) Number of Command Response Frames sent (always zero for CD-1);(h) Number of Invalid Frames sent;(i) Number of signed and unsigned frames sent.

IDC/CD Receiver/SDDPage 12

16 March 2004

3.2.3. State Diagram

Figure 3. Monitor thread state diagram

3.2.4. Logging

This information is written to Syslog with the LOG_INFO priority. For example:Summary: Receiver started: 07/04/02 15:58Summary: ---- Listener values----Summary: Listen on: 0.0.0.0:7777Summary: Connection warnings: 0Summary: Connection requests failed: 0 [0/0/0/0/0/0/0/0/0] Summary: Received 0 frames [0/0/0/0/0/0/0/0/0/0], 0 bytesSummary: ---- CD1 values ----Summary: Connection requests valid: 874 Summary: Connection requests failed: 0 [0/0/0/0/0/0/0/0/0] Summary: Connection errors: 874 [0/874/0/0] Summary: Received 874 frames [874/0/0/0/0/0/0/0/0/0], 6992 bytes Summary: Input buffer size 10240 bytes Summary: Transmitted 874 frames [874/0/0/0/0/0/0/0], 27968 bytes Summary: ---- CD11 values ---- Summary: Connection requests valid: 1748 Summary: Connection requests failed: 1748 [0/0/0/0/0/874/0/874/0] Summary: Connection errors: 1748 [874/874/0/0] Summary: Received 4370 frames [3496/0/0/0/0/0/0/0/0/874], 229862 bytes Summary: Input buffer size 20480 bytes Summary: Transmitted 2622 frames [1748/874/0/0/0/0/0/0], 195776 bytes Summary: -------------- Summary: Thread info: 2624/2/2622 PPTM: Connection started: 3/23/2002 12:00:00 PPTM: Connection stopped: 6/23/2002 13:00:00 PPTM: Connection info: connecting, CD1.0, 0 PPTM: Connections requests valid: 1 PPTM: Connections requests failed: 0 [0/0/0/0/0/0] PPTM: Connections since startup: 1

Wait for nextinterval

Gather andprint data

Startapplication

Data processed Interval timehas expired

Gather andprint data

Usertermination

request

IDC/CD Receiver/SDDPage 13

16 March 2004

PPTM: Connections timed out: 0 PPTM: Received: 1789 frames, 234234 bytes PPTM: Transmitted: 23 frames, 634 bytes PPTM: Frame authentication is active PPTM: Frames signed: 1788, unsigned: 1 PPTM: Bad frames received: 0 [0/0] PPTM: Input buffer size: 32768 bytes

3.3. Listener Thread

The listener thread is spawned by the main thread and handles incoming connection requestsas well as incoming command requests. It listens on the well-known port on all local IPaddresses1. Only CD-1 or CD-1.1 Connection Request Frames or CD1-1 Command RequestFrames are accepted by the listener thread. All other frames types are treated as invalid.During frame processing, the listener checks for validity of the incoming request. The listenerthread will also load the authentication keys for the requesting station, under the followingconditions:

(a) Authentication is switched on;(b) No key cache exists;(c) Authentication is not switched off with a station global directive in the Key Preload

file or a previously received command request.

The request will be dropped if one of the following errors occurs:

(a) The connection or command request is initiated from an unauthorized IP address (seeparameter stationFile). No frame data is logged for unauthorized IP addresses toprevent the frame store being flooded with invalid data in case of DoS attacks. Thelistener thread also waits a defined time [SJL1]before it drops the connection at IP levelto avoid too high system loads in case of DoS attacks.

(b) Frame is not a valid CD-1 or CD-1.1 Connection Request or CD1-1 CommandRequest Frame. CD-1 and CD-1.1 Connection Request and Command RequestFrames are distinguished using the first 4 bytes which must be an IEEE integer valueof one or eight for a CD-1.1 frame.

(c) Request is initiated from an unauthorized station (see parameter stationFile).(d) No data is received within the connection request timeout period (see parameter

connectionRequestTimeout).(e) The (IP) connection has been closed unexpectedly.

3.3.1. Connection Requests

If the incoming request has passed initial checks and has been identified as a ConnectionRequest Frame additional checks are performed. A connection request will be dropped if oneof the following errors occurs:

(a) A station with the same station ID is already connected or a connection request isbeing processed for a station with the same ID.

1 If the system has more than one network card built-in, or one card has been configured to have more than oneIP address, then the listener will listen on all these addresses.

IDC/CD Receiver/SDDPage 14

16 March 2004

(b) System has insufficient resources to handle connection. This includes: (i) Number of allowed concurrent connections exceeded (see parameters startPort

and finishPort);(ii) No socket within the configured port numbers available (see parameters

startPort and finishPort);(iii) Insufficient system resources [SJL2]to handle connection (memory, file

descriptors, disk space, etc.);(iv) Number of threads exceeded.

(c) Handling thread doesn't signal readiness within Handling thread start-up timeout. TheHandling thread start-up timeout is an internal value.

The connection request will be dropped if one of the following errors2 occurs and if theconfiguration parameter strictModeEnable has been set, otherwise a warning is generated:

(a) Invalid frame length.(b) Bad CRC (only CD-1.1).(c) Authentication failure3.

(i) Invalid signature,(ii) No key available.

(d) Frame not signed and verSigEnable is set to FRAME or ALL.

If no error occurs, the listener allocates a new port, spawns a station handling thread and waitsuntil the handling thread is ready or a Handling thread start-up timeout occurs. If the handlingthread is ready the listener sends a Port Assignment Frame (CD-1.0) or Connection ResponseFrame (CD-1.1) to the connecting station, drops the connection and waits for a new request.The configuration parameter port specifies the port on which the listener thread listens.

3.3.1.1. Network Address Translations

As default, the receiver uses the IP address of the incoming interface when building PortAssignment or Connection Response Frames. This works fine for simple in-routes, butdoesn’t work when NAT is used somewhere in the in-route. To solve this problem, the IPaddress sent back in Port Assignment or Connection Response Frames can be specified in thestationFile for each station.

3.3.2. Command requests

Commanding the receiver is done by Command Request Frames which have to be signed withthe private key of the receiver. The user is responsible for running the receiver with framesignature check switched on to avoid unauthorized control of the receiver! (Currentimplementation allows control without frame signatures for testing!!) If the incoming requesthas passed initial checks and has been identified as a Command Request Frame additionalchecks are performed. For command requests, the CD Receiver will always behave as in strictmode. A command request will be dropped if one of the following errors occurs:

(a) Invalid frame length.

2 Invalid frames are not acknowledged with AckNack frames on CD-1.1 connections to prevent the sender fromsending invalid frames again. 3 Authentication validation is only done for CD-1.1 if the frame signature check is enabled.

IDC/CD Receiver/SDDPage 15

16 March 2004

(b) Bad CRC.(c) Authentication failure4.

(i) Invalid signature,(ii) No key available.

(d) Frame not signed and verSigEnable is set to FRAME or ALL.

If no error occurs, the listener processes the command request, sends back a CommandResponse Frame, drops the connection and waits for a new request. Currently the followingcommands are supported[SJL3]:

(a) Get thread information (GST). This command returns number of threads started,number of threads in use and number of threads that have been shut down.

(b) Get list of known stations (GST=1). This command returns the following informationfor each known station object:

(i) connection name,(ii) connection state,(iii) connection type,(iv) used or last used port,(v) authentication state,(vi) number of warning and errors in unconnected state and(vii) number of warnings and errors in connected state.

A station object is created when an incoming request passes all checks and no stationobject exists for the connection station. Please keep in mind that a station object iscreated also for the controlling station. This station object is named using the stationname field of the command request payload.

(c) Get station information (GST=3,station). This command returns detailed informationfor the given connection name. It returns the number of successful connectionrequests, number of connection requests with warning, number of connection requestswith errors, the number of

(i) Connection requests when the station was already connected;(ii) Requests from an unauthorized station (only the unconnected station object);(iii) Requests from an unauthorized IP address (only the unconnected station

object);(iv) Authentication failures in connected and unconnected state:(v) Unsuccessful connection requests caused by a too slow handling thread

initialization; (vi) Invalid frames in connected and unconnected state;(vii) Timeouts in connected and unconnected state;(viii) Unexpected closed connections in connected and unconnected state;(ix) System failures in connected and unconnected state;

(d) Set global debug level (SDL=level). This command sets the debug level for allstations and returns the old global debug level.

(e) Set station debug level (SDL= level,station). This command sets the debug level for agiven station and returns the old debug level of this station.

(f) Set configuration parameters for all stations (SCP=added bit values,station). The bitvalue is the sum of the chosen systemConf values defined in cd_common.h. Thiscommand returns the old global systemConf value;

4 Authentication validation is only done for CD-1.1 if the frame signature check is enabled.

IDC/CD Receiver/SDDPage 16

16 March 2004

(g) Set configuration parameters for a designated station (SCP=added bitvalues,station,station) This command returns the old station specific systemConfvalue;

(h) Disconnect station (DIS= station). Initiate an user shutdown for a designated station.

IDC/CD Receiver/SDDPage 17

3.3.3. Process Flow Diagram

Figure 4. Listen

start

Configure Thread

Shut-down

Wait for connectionrequest

Accept connection,Read Frame

Validate request (incl.Authentication for CD-1.1)

Log request

Store Frame (.bin, .clf)

L

Spaw

W

Ccon

Log c

Close connection

Timeout

User terminationrequest

Valid Frame

er thread process flo

Allocate Port

oad certificates

n Handling thread

ait for Handlingthread

reate, sign, sendnection response

onnection response

Invalid or CRFnot authorized

w

Handling threadtimeout

16 March 2004

diagram

IDC/CD Receiver/SDDPage 18

16 March 2004

3.3.4. State Diagram

Figure 5. Listener thr

3.3.5. Logging

When the listener thread is started, the start time This event is logged with LOG_NOTICE priority.

Listener started, listen at 0.0.0.

When a Connection or Command Request Frameor MORE, the following information is logged wi

(a) Station Name;(b) Source IP address and port;(c) Destination IP address and port;(d) Format of frame;(e) Connection state of the station;(f) Event [GK4](Connection or Command Req

For example:CRQ_I: PPTM 192.168.2.1:1123 to 19received

Wait forconnection

request

Wait forconnection

requestframe

Wait forstationthreadStart

application

Stopapplication

Line ldle Timeoutclose connection

CRFreceived,

Start stationthread

Station threadstarted

CRF invalid/not allowed*

close connection

*) Station not permitted orbelow reconnect time limit orauthentication failure (CD-1.1)

Wait tosendData

Output buffer readySend PAF/Connection

Response frame

Line ldle TimeoutClose connection

Connectionrequest

Station thread timeoutClose connection

ead state diagram

and date and the port to listen to are logged. For example:0:8080

is received and verboseEnable is set to YESth LOG_INFO priority:

uest Frame received)

2.168.23.3:8753 CD 1.0 0 CRF

IDC/CD Receiver/SDDPage 19

16 March 2004

CRF summary, station PPTM, 3/1, 983453234566.003456,983453234466.003456, 8823, 0/1/0/0/1/0/1/3

When the Port Assignment Frame or Connection Response Frame is sent successfully andverboseEnable is set to YES or MORE, the following information is logged withLOG_NOTICE priority:

(a) Station Name;(b) Source IP address and port;(c) Destination IP address and port;(d) Format [GK5]of Connection Request Frame;(e) Time of port assignment or connection response frame sent;(added by Syslog)(f) Data consumer IP address and port number.(logged in handling thread)

Note that a detailed description of the frame can be found in the textSummaryFile. Forexample:

station PPTM connected, source 192.168.2.1:1123, destination192.168.23.3:8753, format CD 1.0, processing time: 0.321,responding at: 983453234566.003456,

redirect to 192.168.23.3:8832

When a key or certificate is loaded and verboseEnable is set, information will be logged withLOG_INFO priority. For example:

PEM key loaded [PPTM] [1234] for station PPTM

When an error occurs, the following information is logged with LOG_ ERR priority:

(a) Station name;(b) Source IP address and port;(c) Destination IP address and port;(d) Format of Connection Request Frame;(e) Time of last successful connection/command request (for grouping log messages);(f) Reason for error.

Possible reasons for errors are:

(a) Unauthorized IP address;(b) Invalid frame;(c) Invalid frame size;(d) Bad CRC;(e) Unauthorized station name;(f) Authentication failure (CD-1.1 only):

(i) No key found for station,(ii) Invalid key.

(g) Unsigned frame;(h) Station already connected;(i) Connection limit exceeded;(j) No port available;(k) Insufficient system resources;

IDC/CD Receiver/SDDPage 20

16 March 2004

(l) Number of threads exceeded;(m) Thread failed to initialize;(n) Connection request timeout;(o) IP connection closed unexpectedly;(p) Error sending response.

For example:connection request failed, station PPTM, source 192.168.2.1:1123,destination 1192.168.23.3:8753,

format CD 1.0, last connection: 983453234566.003456, reason: invalid IPaddress

When a warning occurs, the following information is logged with LOG_ WARN priority:

(a) Station name;(b) Source IP address and port;(c) Destination IP address and port;(d) Format of Connection Request Frame;(e) Time of last successful connection request;(f) Reason for error.

Possible reasons are:

(a) Invalid frame size;(b) Bad CRC;(c) Unsigned frame (CD-1.1 only);(d) Authentication failure (CD-1.1 only):

(i) No key found for station,(ii) Invalid key.

For example:connection request warning, station PPTM, source 192.168.2.1:1123,destination 1192.168.23.3:8753,

format CD 1.0, last connection: 983453234566.003456, reason: no key found

When the listener thread is stopped, the stop time and date are logged. This event is loggedwith LOG_NOTICE priority. For example:

Listener [GK6]stopped

3.4. Handling Thread

Handling threads are spawned by the listener thread and are primarily concerned withprocessing incoming frames and storing the data in several files depending on theconfiguration. A handling thread services a particular sender for the duration of theconnection. There is one handling thread per connection.

IDC/CD Receiver/SDDPage 21

16 March 2004

3.4.1. Thread Initialization

If a handling thread is started, it first configures a socket and creates the necessary outputfiles. All files are created in an operating directory specified by the configuration parameterfilePath. Existing files will be opened in append mode. If a finite file size is specified with theconfiguration parameter fileSize and the file size is exceeded, new files are created. Forperformance reasons, CD Receiver cannot guarantee that the file size of binary files will notbe exceeded. In the worst case, the file size may be exceeded by the amount of data that canbe received in one minute. Received frames are stored as an exact copy in binary files.

If the initialization is done the handling thread signals readiness to the listener thread andwaits for a sender to connect. If a sender connects before the configured timeout expires, themain loop of the handling is entered.

3.4.2. Main Loop

In the main loop, the handling thread waits for data until the connection will be terminated oran error occurs. If data are received the frame is logged in the binary file, the timeout is reset,the frame type is determined and the frame is checked for errors and processed.

3.4.2.1. CD-1 Connection

If an Alert Frame is received, the software will take the following actions:

(a) 0 – do nothing, (b) 1 – shutdown thread, (c) 2 – prepare for Data Format Frame.

If a Data Format Frame is received, the software will extract, check (see ErrorChecks) andstore the channel info. If the check fails and strictModeEnable is set, an error message isgenerated, an Alert Frame is sent and the connection is terminated. If strictModeEnable is notset, a warning is generated and frame processing is continued if possible. No wfdisc recordsare written and only the headers of Data Frames are checked until a valid Data Format Frameis received.

If a Data Frame is received, the software will extract status bits, time stamp and samplesinformation and check the frame. The software will optionally perform signature verificationand write wfdisc records (see parameters verSigEnable and enableWfdiscFile). CD1 dataframes don’t include a key ID and there is no strict relation between the keys subject attributeand the site/channel information in the frame. To find the right keys CD Receiver uses thefollowing algorithm:

(a) Search for a key with exactly the same site/channel name. If one is found then use thiskey.

(b) If no key is found then search for a key with exactly the same site name and nochannel name. If one is found then use this key.

(c) If no key is found then search for a key where the site name is equal to the stationname. If one is found then use this key.

(d) If no key is found then check if only one key is cached. If only one key is cached thenuse this key.

IDC/CD Receiver/SDDPage 22

16 March 2004

If no key is found which matches the site/channel name a warning is generated in non strictmode or an error is generated and the connection is terminated in strict mode. If the signatureverification fails and one or more alternate keys are available for the used certificate, theverification is repeated with all the alternate keys for this certificate. An alternate key is a keywith the same transformed common name. The rules to transform a common name into atransformed common name are:

(a) If the common name starts with station_name and a blank or hyphen, contains than aseries of alphanumeric characters and a second blank or hyphen and another series ofalphanumeric characters then copy the string between the first and the second blank orhyphen (NOT IMPLEMENTED YET).

(b) Copy all characters before the first blank or hyphen.

For example:

PPT01 test key is transformed to PPT01 if station name is PPTM.WBA-CF-01 is transformed to CF if station name is WBA (not implemented yet).

Alternate keys are chained together during caching of the certificates.

3.4.2.2. CD-1.1 Connection

If an Alert Frame is received, the software will shutdown the thread.

If a Data Frame is received, the software will extract channel information, status bits, time-stamp and samples information and check the frame. The software will optionally performframe and channel signature verification and write wfdisc records (see parametersverSigEnable and enableWfdiscFile). If the check fails and strictModeEnable is set, an errormessage is generated, an Alert Frame is sent and the connection is terminated. IfstrictModeEnable is not set, a warning is generated and frame processing is continued ifpossible.

If an AckNack Frame is received, the software will only log the frame.

If a CD1 Encapsulation Frame is received, the software will generate an error but continueprocessing the next frame.

If a Command Request Frame is received, the software will generate a warning.

If a Command Response Frame is received, the software will generate a warning.

If an Option Request Frame is received, the software will send an Option Response Frame.

If an Option Response Frame is received, the software will generate a warning.

If a Connection Request Frame is received, the software will generate an error but continueprocessing the next frame.

If a Connection Response Frame is received, the software will generate an error but continueprocessing the next frame.

AckNack Frames are sent in appropriate intervals to signal the sender that CD Receiver isalive. CD Receiver will start to send AckNack frames if no frames are sent within theconfigured heartbeat time (see configuration parameter heartBeat), regardless if a frame hasbeen received or not. Every sent frame resets the heartbeat timeout. If a frame is being

IDC/CD Receiver/SDDPage 23

received at the time that a heartbeat should be sent, the heartbeat is sent after the full framehas been received. AckNack behavior is shown in Figure 6.

Ackset. morrece

Option request/response frame

Data frame

Connectionestablished

Line Idle timeoutLine Idle timeout

Line Idle timeout Line Idle timeout

H

ti

Nack FraAccordine than onived dat

AckNack frame

Alert frameHeartbeattimeout

Heartbeattimeout

Heartbeattimeout

Heartbeattimeout

Heartbeattimeout

Heartbeattimeout

eart-beatmeout

Line Idle timeout

Line Idle timeout

Line Idle timeout Line Idle timeout

Line Idle timeout

Line Idle timeout

Figure 6. CD

mes are also used to informg to in IDC (2002), Formatse frame set. Every handlinga frame set (the gap list).

Heartbeattimeout

Heartbeattimeout

16 March 2004

-1.1 AckNack behaviour

the sender of missing frames in a particular frame and Protocols CD1.1, CD Receiver is able to handle

thread will maintain a list of missing frames for eachCD Receiver does not handle gap lists or sending

Heartbeat delay. No heartbeat issent when receiving a frame

Heartbeattimeout

IDC/CD Receiver/SDDPage 24

16 March 2004

AckNack frames for control frames. To prevent CD Receiver from sending AckNack Frameswith too large gap lists repeatedly, the number of entries in a gap list is limited. If there is nomore space for a new gap in the gap list then the gap with the lowest sequence number isremoved from the gap list. Under normal conditions, CD Receiver’s built in gap list limitshould not be reached. To keep the gap list small, the sender should follow these rules:

(a) If possible, avoid having sequence gaps in the senders frame store or create thesequence number immediately before sending the frame.

(b) After a line outage the sender should try to avoid creating unnecessary gaps. Existinggaps should be filled ascending in sequence from the lower boundary or descending insequence from the upper boundary. Sending a frame with a sequence number not on agap boundary should be avoided. The proper behaviour for backfill mode is shown inFigure 7.

Sent sequence # Highest sequence # Lowest sequence # gap list

10 10 10 empty

11-105 11-105 10 empty

outage

110 110 10 106-109

111 111 10 106-109

109 111 10 106-108

112 112 10 106-108

108 112 10 106-107

107 112 10 107-107

106 112 10 empty

113 113 10 empty

Figure 7. Backfill mode – good behaviour

IDC/CD Receiver/SDDPage 25

16 March 2004

The sender could also start to fill the gap with sequence number 106 and increase thenumber by 1 for each frame with fits in the gap (106, 107, 108, 109). The worstbehavior to fill a gap is splitting a gap in two or more gaps (see Figure 8).

Sent sequence#

Highest sequence#

Lowest sequence#

gap list

10 10 10 empty

11-105 11-105 10 empty

outage

110 110 10 106-109

111 111 10 106-109

107 111 10 106-106,

108-109

112 112 10 106-106,

108-109

108 112 10 106-106,

109-109

106 112 10 109-109

109 112 10 empty

113 113 10 empty

Figure 8. Backfill mode – bad behaviour

Lowest and highest sequence numbers of a frame set are derived from the first Data Framereceived for this frame set. Gap lists are not cleared if the connection is closed. If theconnection is re-established the previous gap list is still active. All information about gap listsis lost when CD Receiver shuts down.

3.4.2.3. All Connections

If an invalid frame is received, the software will try to locate the beginning of the next validframe (if strictModeEnable is not set) or send an Alert Frame and terminate the connection (ifstrictModeEnable is set).

The line idle timeout (see cd10Timeout or cd11Timeout) is reset if a frame is received. Alldata received are saved in the binary file. A text description of the received frame is generatedif enableTextFile is set and a concise list of frames file is created if enableClfFile is set. If theframe is processed a check for user termination request is done. If a user termination requestis pending then an appropriate Alert Frame is sent and the thread terminates. If terminationwas not requested the date and the file size of the bin file (controlled via the fileSizeparameter) are checked and a new binary file is started if the date has changed or the file sizehas been exceeded. When a new binary file is started, new related files (.clf, .txt or .wfdisc) arealso started if creation of these files have been enabled in the configuration file.

IDC/CD Receiver/SDDPage 26

16 March 2004

A new file is started when the binary file exceeds the user specified desired file size and atleast the minute part of the file name has changed. Frame fragmentation does not occur. Filesare ended only on frame boundaries. When the date changes a new file is started. When a newfile is started, the current Data Format Frame is replicated for reference purposes at the startof the .txt, .clf and .bin files (CD-1 connections only).

When a new file is about to be started and if the file already exists, it is opened in appendmode and the file size is checked. If the file size exceeds the configured limit, a warning isgenerated. Under normal operation the file, which was opened, should not exist, because thegenerated file name can change every minute. The only time there may be a problem is whena station tries to re-connect in less than 60 seconds.

Once all checks are complete, the handling thread waits for the next frame.

CD Receiver terminates if no disk space is available. The connection is always dropped if oneof following events occurs:

(a) System has insufficient resources to handle the frame. This includes: (i) Insufficient memory to handle the received frame;(ii) No file descriptor available.

(b) No frame is received within the line idle timeout period if set (see parameter timeout).(c) Re-acquiring failed. No valid frame found within the current maximal frame size

(<=10 Mb).(d) User termination requested.

A connection is dropped if the following events occur and the configuration parameterstrictModeEnable has been set. If the parameter is not set, the connection is not dropped andonly a warning is generated:

(a) Frame is not a valid frame type. CD Receiver keeps the connection open and attemptsto find the start of the next frame.

(b) Authentication failure – invalid frame signature (only CD-1.1).(c) Authentication failure - invalid signature of sensor data.(d) Frame check failed.(e) Bad CRC (only CD-1.1)5.(f) LDAP server could not be reached.(g) Frame not signed and verSigEnable is set (only CD-1.1).

Only a warning is generated if one of the following events occurs:

(a) Some bad values are found in the frame header (e.g., maximum deviation exceeded).(b) The sequence number of the received frame will cause a new gap.(c) No more space left in the gap list. The gap with the lowest sequence number is

removed.

If the connection has been closed without receiving an appropriate Alert Frame then an errormessage is generated. If possible, an Alert Frame will be sent if an error has occurred beforethe connection is dropped.

5 The reason why the connection is dropped, instead of forcing the sender to re-send the frame with anappropriate AckNack frame, is to prevent the sender from sending an invalid frame again.

IDC/CD Receiver/SDDPage 27

16 March 2004

3.4.3. Error Checking Functionality

Checks are undertaken for a variety of different error conditions.

3.4.3.1. Protocol Errors

The software checks for the following protocol errors:

(a) First frame must be a Data Format Frame (for CD 1.0 frames);(b) All subsequent Data Format Frames must have been immediately preceded by

appropriate Alert Frame (for CD 1.0 frames). (c) First frame must be an Option Request Frame (for CD-1.1frames)

3.4.3.2. CD1-0 Frame Errors

For errors pertaining to the Data Format Frame, the software will check the validity of:

(a) Frame length (x == 2020 || x == 2820);(b) Maximum Frame Size (0 <= x <= 10,000,000 && x%4 == 0);(c) Number of channels (0 < x <= 100);(d) Authentication switches (x == 0 || x == 1);(e) Compression switches (x == 0 || x == 1);(f) Ensure trailing bytes in channel and site names are zeroed.

For errors pertaining to the Data Frame, the software will check the validity of:

(a) Frame Length (40<= x <= maximum frame size && x%4==0).(b) Description Length (0 <= x <= 1024 && x%4).(c) Packet Length (0 <= x < Frame Length && x%4==0).(d) Number of channels in Data Frame (must correspond with Data Format Frame for

CD1.0 frames).(e) Cumulative packet length (must correspond with Frame Length for CD 1.0 frames):

lengthndescriptiolengthpacketlengthframechannelsofnumber

nn _20)4_(_

__

1

���� ��

(f) Number of samples (must agree with the corresponding packet length):(i) Uncompressed and unauthenticated data:

packet_length = number_of_samples * 4 + 16 orpacket_length = number_of_samples * 3 + 16 orpacket_length = number_of_samples * 2 + 16

(ii) Uncompressed and authenticated data: packet_length = number_of_samples * 4 + 56 orpacket_length = number_of_samples * 3 + 56packet_length = number_of_samples * 2 + 56

(iii) Compressed and unauthenticated data:

1610

6___1610

1__�

����

� samplesofnumberlengthpacketsamplesofnumber

(iv) Compressed and authenticated data:

IDC/CD Receiver/SDDPage 28

16 March 2004

5610

6___5610

1__�

����

� samplesofnumberlengthpacketsamplesofnumber

(g) Signature in each channel sub-frame.

For errors pertaining to the Alert Frame, the software will check the validity of:

(a) Frame Length (x == 12);(b) Alert type (x == 0 || x == 1 || x == 2 || x == 1000 || x == 1001).

3.4.3.3. CD1-1 Frame Errors

For errors pertaining to all Frames, the software will check the validity of:

(a) Frame Length (52 <= x <= maximum frame size && x%4==0);(b) Trailer Offset (40 <= x <= maximum frame size);(c) Authentication size (x == 0 || x == 40);(d) CRC.

For errors pertaining to the Data Frame, the software will check the validity of:

(a) Number of channels (0 < x <= 100),(b) Channel String Size (x == nbr_of_channels * 10),(c) Nominal Time (x <= current_time + maxPosDeviation),(d) Channel Length (x < frame length && x%4 == 0),(e) Authentication switches (x == 0 || x == 1),(f) Compression switches (x >= 1 && x <= 4),(g) Option switches (x == 0 || x == 1),(h) Number of samples (must agree with the corresponding data size). For an

uncompressed, 4 byte data type:

data size = number_of_samples * 4

The following checks are not performed in offline mode:

(a) Nominal time (x <= (current time + deviation time));(b) Time stamp (x <= ((current time + deviation time) && x - nominal time <= 1 second).

IDC/CD Receiver/SDDPage 29

16 March 2004

3.4.4. Process Flow Diagram

Alert

CD-1.1 Designhandling Theread

startInitialize(Socket,log files)

SendAckNack

Waitfor

data

Checkevent

Read/ Parse/checkheader

Validframe

Determineframe type

Time tosend Ack-

Nack

Valid framefound

Check usertermination

request

Signalingreadiness to

Listenerthread

SendAckNack

Shut-down

yes

No

No

data

yes No

AckNacktimeout

Data Option/command AckNack Invalid

* Frame Authenticationis done only for CD-1.1

Locatestart of

next valid frame

Read remainder offrame/parse trailer

Lineidle

timeout

Updateappropriate

gap list

Authenticatesignature*

Authenticatesignature*

Authenticatesignature*

Authenticatesignature*

Parse /checkframe

Parse /checkframe

Parse /checkframe

Parse /checkframe

Store frame(binary)

Store frame(binary)

Store frame(binary)

Createwaveformreferences

Log frame (text,clf)

Log frame (text,clf)

Sendterminating AF

IDC/CD Receiver/SDDPage 30

16 March 2004

Figure 9. Handling thread process flow diagram

3.4.5. State Diagram

Figure 10. Handling thr

3.4.6. Logging

If a handling thread is started, the start time and event is logged with LOG_INFO priority. For exam

Handling thread PPTM starts, listen

If a warning has occurred, the following informatio

(a) Station Name;(b) Source IP address and port;(c) Destination IP address and port;(d) Format of frame;(e) Time of last successful connection request;(f) Reason for warning including:

(i) invalid frame,

Initialize rStartthread

Wait fordata

ProcessProcessing error andstrictModeEnable set.

Data processed

dataeceived

Line idle Timeout/ user termination requestsend AF and close connection

ead state di

date and theple: at 192.1

n is logged

data Send AF and closeconnection

Try toreacquire

data

W

Processing error andstrictModeEnable notset

S

Datareceived

Re-acquire failed

Reacquiringsuccessful

agram

port to liste

68.2.1:74

with a LOG_

ait fordata

Lint

give upend AF and

closeconnection

n are logged. This

34

WARN priority:

e idle Timeout/ userermination request.Send AF and close

connection

IDC/CD Receiver/SDDPage 31

16 March 2004

(ii) authentication failure,(iii) bad data format frame (only CD-1),(iv) bad header value.

For example:connection warning, station PPTM, source 192.168.2.1:1123,destination 1192.168.23.3:8753,

format CD 1.0, last connection: 983453234566.003456, reason:invalid frame received

If an error has occurred, the following information is logged with a LOG_ERR priority:

(a) Station name, (b) Source IP address and port, (c) Destination IP address and port, (d) Format of frame, (e) Time of last successful connection request,(f) Reason for error.

Possible error reasons are:

(a) Connection has been closed without an appropriate Alert Frame being received;(b) Line idle timeout;(c) Invalid frame;(d) Authentication failure;(e) Insufficient resources;(f) Bad data format frame (only CD-1).

For example:connection error, station PPTM, source 192.168.2.1:1123,destination 1192.168.23.3:8753,

format CD 1.0, last connection: 983453234566.003456, reason: lineidle timeout

3.5. Certificate Thread

The certificate thread of CD Receiver is primarily concerned with keeping the stationscertificate caches up to date. This is done by adding newly available certificates to a stationscertificate cache, or updating validity attributes of a cached certificate. As described inkeyLoadingSchema, certificates can be retrieved from an LDAP server or loaded from thelocal file system by the main or listener thread.

The Certificate thread checks the Certificate Revocation List (CRL) in a user configurabletime interval (see crlCheckTime). Certificates that are found on the CRL will be marked asrevoked, the validity will be updated in the key cache and a warning will be written to Syslog.

IDC/CD Receiver/SDDPage 32

16 March 2004

Revoked certificates are still used for data which has been signed with this certificate beforethe certificate has been revoked. The certificate thread will also check if a new certificate isavailable on the LDAP server or, if a PEM key pre-load directive is used, if a new certificateis available in the configured certificate directory. If a new certificate is found then it is addedto the station’s certificate cache. If a Handling thread could not find a valid certificate andstrictModeEnable is set then CD Receiver will close the connection. Otherwise a warning isgenerated and authentication is suppressed for this station or for the affected sub channel.

3.5.1. State Diagram

Figure 11. Monitor thread state diagram

3.5.2. Logging

If a certificate thread is started, the start time and date are logged with LOG_ NOTICEpriority. For example:

Certificate thread starts

If a revoked certificate is found, the distinguished name is logged with LOG_INFO priority.For example:

Revoked certificate found: o=CTBTO,ou=IDC Test Bed,l=IS57; Serialnumber=12345

3.6. Offline Sender Thread

The offline sender thread of CD Receiver is primarily concerned with emulating a sender in aconnected state. It loads the certificates, spawns a handling thread and connects to thehandling thread like a real station after the port assignment dialog. Then it reads the data thatshould be checked and sends the data to the handling thread. If all sent data is received by the

Wait for nextinterval

Updatestation

certificatecaches

Usertermination

requestStart

application

Certificatesprocessed

Interval timehas expired

IDC/CD Receiver/SDDPage 33

16 March 2004

handling thread then it emulates a user shutdown request and exits. All checks are done by theserving handling thread. For this reason, only data created in connected mode could bechecked. The handling thread performs the same checks as in online mode except

� verifications based on the sender's IP address and station name,

� checks based on current receiving time,

� and the first frame received for a CD1-1 connection does not need to be an Optionrequest frame.

In future, off-line error checking mode should also be able to read the current receiving timefrom a corresponding clf file. Please note that the CD receiver is not able to distinguishbetween sent and received frames in the file. If the file that should be checked contains datasent by the CD Receiver, CD Receiver will treat these data in offline-mode in the same wayas received data.

3.6.1. State Diagram

Figure 12. Offline sender thread state diagram

3.6.2. Logging

All logging information is written to Syslog and stdout in offline-mode. See Chapter 3.4.6 fora list of logged messages. Additionally a message is printed to stdout for each file processed:

Processing [/var/log/05/PPTM.20030305.1532.11bin] …

3.7. Thread synchronization

Threads are synchronized using POSIX mutex locks. The CD Receiver is designed to avoidmutex locks between more than two threads if possible. This is done by (theoretical) divisionof mutex locks in read and write locks. A read lock (set by a reader) doesn’t block anotherreader, it blocks only a writer (sets a write lock). A write lock blocks readers and otherwriters. Unfortunately POSIX doesn’t support different types of locks. It supports only writelocks. In lack of read locks the CD receiver uses a different approach. The synchronizationbetween readers and a single writer is done without using (read) locks. Critical values arechanged by writers using one ‘atomic operation’ like assigning a new value to a pointer. If the

No more inputfiles available oruser shutdown

request

Startapplication

Processinput file

more inputfiles available

IDC/CD Receiver/SDDPage 34

16 March 2004

critical value is not an atomic type (e. g. a string), the critical value is transformed to anatomic type (e. g. a pointer alternating pointing to two strings). An example where thistransformation could be used is a file path. The file path is a string used by all handlingthreads. It could not be changed by a writer directly, because one or more readers could usethe string while it is changed by the writer. This would lead to unexpected results. But if allreaders use a pointer to the string and the new value is copied into another string and then thepointer value is changed, it’s save as long as switching between the two strings isn’t done toofrequently and the strings are not released.

Another method to avoid mutex locks in the CD Receiver is to design the code to have onlyone writer (thread) for a particular state of an object. An example for this method is the perstation certificate cache. It is initialized by the main thread (during pre-load, no other threadsstarted) or the listener thread (during first connection request) and modified by the certificatethread (only if the cache has the proper state).

Currently the CD Receiver uses the following mutex locks:� readyMutex: used to signaling readiness of last started handling thread to the listener

thread � stopMutex: used to stop monitor thread� idxMutex: used to avoid concurrent writes to the index file (each file switch if an

index file is used). This is a lock situation in the CD receiver where more than twothreads could be involved

� shutdownMutex: used to synchronize shutdown of handling threads when a shutdownis pending. This is a lock situation in the CD receiver where more than two threadscould be involved

4. ERROR POLICIES

CD Receiver will stop during initialization if one of the configured files could not be found, ifone of the configured directories does not exist or if neither of the configured LDAPconnections could be established. CD Receiver will also stop if the listener could not listen onthe well-known port or if a system error occurs in the main, listener, monitor or certificationthreads. The listener is stopped if an output file could not be created.

4.1. Non-strict Mode

Received frames are always written to the appropriate files, regardless if they contain valid orinvalid data. This makes sense, because the data are checked by external applications before itis used. Errors and warnings concerning frames are reported, but most of them have no impacton storing frames. Only the following events stop processing and terminate the connection innon-strict mode:

(a) Line idle timeout,(b) Reacquiring failed, (c) Insufficient resources.

IDC/CD Receiver/SDDPage 35

16 March 2004

4.2. Strict Mode

Strict mode is more restrictive than non-strict mode. Received frames are also always writtento the appropriate files, regardless if they contain valid or invalid data. Errors and warningconcerning frames are reported, but most of them have no impact on storing frames. However,the following additional events will stop processing and terminate the connection:

(a) Frame is not a valid frame type or frame deviates from the protocol;(b) Authentication failure - invalid frame signature (only CD 1.1);(c) Authentication failure - invalid signature of sensor data.

IDC/CD Receiver/SDDPage 36

16 March 2004

APPENDIX I CD-1.1 RECEIVER DESIGN DETAILS

The relationship between the different threads (see 3.1, page 7) is shown in Figure 13 below.

Figure 13. CD-1.1 Receiver design details

main

Listener

config-params system-params

Portmap??

Key validation

Monitor

CD1Handling

CD1.1Handling

Thread exist forthe life time of the

receiver

Data structure existfor the lifetime of the

receiver

Comms0

Thread exist forthe life time of a

connection

Data structureexist for thelifetime of a

Data flow

Start up

Shutdown

Rec. Life

connection

history??

Comms1

keys??

monitor-params

Own?

IDC/CD Receiver/SDDPage 37

16 March 2004

APPENDIX II STATION EQUIPMENT DIAGRAMS

Typically configurations for CD1.0 stations and CD1.1 stations are shown in Figure 14 andFigure 15 below.

Figure 14. CD-1 station

Digitizer

S

S

SDigitizerS

S

S

DigitizerS OR

Sensor site

Sensor site

Digitizer

S

S

SDigitizerS

S

S

Sensor site

Sensor site

Sensor site

Sensor site

OR

Digitizer

S

S

S

CD-1 centraldata signing

facility

CD-1 datasigning facility

To IDC

IDC/CD Receiver/SDDPage 38

16 March 2004

Figure 15. CD-1.1 station

S

S

DigitizerS

DigitizerS

S

S

DigitizerS OR

Sensor site

Sensor site

Digitizer

S

S

SDigitizerS

S

S

Sensor site

Sensor site

Sensor site

Sensor site

OR

Digitizer

S

S

S

CD-1.1 datasigning facility,uses differentkey for same

DN

CD-1.1 datasigning facility

To IDC

CD-1 framesigning facility

IDC/CD Receiver/SDDPage 39

16 March 2004

TERMINOLOGY

Glossary

Data consumer Receiver of CD1.0 or CD1.1 Data Frames. This is always a data center.

Data provider Sender of CD1.0 or CD1.1 Data Frames. This may be a station or a data centrethat forwards data.

Frame set Data store defined for each source and destination pair for CD-1.1. data. Eachframe set has an associated frame log.

Line idle timeoutperiod

The maximum length of time that the software shall wait for data to bereceived before taking some action. The default action is to generate an errorand close the connection.

Network AddressTranslation(NAT)

The translation of an Internet Protocol address (IP address) used within onenetwork to a different IP address known within another network. One networkis designated the inside network and the other is the outside. Typically, acompany maps its local inside network addresses to one or more global outsideIP addresses and maps the global IP addresses on incoming packets back intolocal IP addresses. This helps ensure security since each outgoing or incomingrequest must go through a translation process that also offers the opportunity toqualify or authenticate the request or match it to a previous request. NAT alsoconserves on the number of global IP addresses that a company needs and itlets the company use a single IP address in its communication with the world.(www.whatis.com)

Open connection An open connection allows data frames to be sent from the data provider to thedata consumer. A CD1.0 connection is defined as open when the dataconsumer receives a CD1.0 Connection Request Frame on the well-knownport, returns a Port Assignment Frame in accordance with IDC (2002), Formatsand Protocols for Continuous Data CD-1.0 and opens a connection (at the TCPlevel) on a new port. A CD1.1 connection is defined as open when the dataconsumer receives a CD1.1 Connection Request Frame on the well-knownport, returns a Connection Response Frame in accordance with IDC (2002)Formats and Protocols for Continuous Data CD-1.1 and opens aconnection (at the TCP level) on a new port.

Terminate When the software terminates, it will attempt to close down in an orderlymanner. The software will try and complete the processing of the currentframes, close all connections according to the communication protocol andclose all open files. The software will also try to log the date, time to thenearest millisecond, and the reason the software was terminated.

Well-known port A port number is a 16-bit integer, associated with a specific process, to which anetwork message is to be forwarded when it arrives at a server. For thissoftware, the well-known port is a publicised number that a data provider canuse to open a connection.

Abbreviations

IDC/CD Receiver/SDDPage 40

16 March 2004

ARM Advanced Registration Module

ASCII American Standard Code for Information Interchange

CD Continuous Data

CLI Concise List of Frames

CLI Command Line Interface

CRC Cyclic Redundancy Checking

CRL Certificate Revocation List

CTBTO Comprehensive Nuclear-Test-Ban Treaty Organisation

DER Distinguished Encoding Rules

DoS Denial of Service

DSA Digital Signature Algorithm

ID Identification

IDC International Data Centre

IEC International Electrotechnical Commission

IMS International Monitoring System

IP Internet Protocol

ISO International Organization for Standardization

LDAP Lightweight Directory Access Protocol

NAT Network Address Translation

NDC National Data Centre

OS Operating System

PEM Privacy Enhanced Mail

POSIX Portable Operating System Interface

PTS Provisional Technical Secretariat

SNMP Simple Network Management Protocol

SRS Software Requirements Specification

UTC Co-ordinated Universal Time

TBS To be sent

TCP Transmission Control Protocol

REFERENCES

CTBTO/PTS (2002). Editorial Manual.

IDC (2002). Formats and Protocols for Continuous Data CD-1.0, IDC3.4.2Rev0.1.

IDC (2002). Formats and Protocols for Continuous Data CD-1.1, IDC3.4.3Rev0.3.

IDC (2002). Software Documentation Framework.

IDC/CD Receiver/SDDPage 41

16 March 2004

IDC (2003). Software Design Description Template

IDC (2003). Using Syslog at CTBTO.

IDC (2004). CD Controller Software User Guide.

ISO/IEC (1995). Information technology – Software life cycle processes, ISO/IEC 12207.