Upload
vuanh
View
257
Download
7
Embed Size (px)
Citation preview
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.