Saab TransponderTech
NMR Client Application Programmers Interface
COPYRIGHT
i
Page i
COPYRIGHT The content of this document and its attachments shall remain our property. They may not without our written consent, either in their original state or with any changes, be copied or reproduced, disclosed to or delivered to anyone unauthorised nor used for other purposes than what has been confirmed by Saab TransponderTech in writing. 2002 Saab TransponderTech AB, SWEDEN
Saab TransponderTech AB Office in Solna Mail Address P O Box 4113 SE-171 04 Solna Sweden
Office address Vretenvägen 12
Document id: 7000 101-185 C
www.transpondertech.com Phone +46 13 18 80 00 Telefax +46 8 627 49 49
Office in Linköping Mail Address SE-581-88 Linköping Sweden
Office address Bröderna Ugglas gata
Phone +46 13 18 80 00 Telefax +46 13 18 23 77
Registered office Solna Org.no 556535-9790 V.A.T No. SE556535979001
CONTENTS
Page ii
CONTENTS i
COPYRIGHT ......................................................................................................................... i
1
Introduction ........................................................................................................................... 1
2
Communication Protocol....................................................................................................... 2
2.1
Logon to the NMR-800/NMR-1800...................................................................................... 2
2.2 2.2.1
Message Protocol................................................................................................................... 2 Acknowledgments of Addressed Messages .......................................................................... 3
2.3 2.3.1 2.3.2
Maintain the Connection ....................................................................................................... 3 Socket Keep-Alive................................................................................................................. 3 Application Keep-Alive......................................................................................................... 3
2.4
Logoff from the NMR-800/NMR-1800 ................................................................................ 4
3
Error Handling....................................................................................................................... 5
3.1 3.1.1
Violation of Application Firewall Rule................................................................................. 5 Error Messages ...................................................................................................................... 5
3.2
User/Host Lockout................................................................................................................. 8
4
Code Examples...................................................................................................................... 9
4.1
C/C++ .................................................................................................................................... 9
4.2
Visual Basic........................................................................................................................... 9
Document id: 7000 101-185 C
Introduction
1
Page 1
INTRODUCTION This document describes the NMR Client Application Programmers Interface (API). Programmers writing applications intended to use the services provided by the NMR-800 and NMR-1800 servers shall use this document. The NMR-800 product is an application firewall used as a gateway between a NMR Network and clients in a Local Area Network (LAN). The NMR-1800 product is an Internet firewall, web server and an application firewall. The NMR-1800 is used to serve requests from clients connecting via Internet and also to protect the NMR Network from malicious attacks. A client can either connect to a home page on the web server or to a port serving real-time data. How to connect and read data from the web server is not described in this document. The application firewall part of the both products authenticates the client and parse every message received to verify no message break any of a predefined set of rules. If the authentication of the client fails the connection will be closed. If a rule is broken the connection may be closed. The NMR-800 and the NMR-1800 are part of the AIS Network Solution from Saab TransponderTech AB.
Document id: 7000 101-185 C
Communication Protocol
2
Page 2
COMMUNICATION PROTOCOL The NMR-800 and NMR-1800 offers TCP/IP socket connections to clients connected to a LAN respectively Internet. Only authenticated clients are granted such a connection, and sequentially, network distributed data to the extent matching the specific clients profile. The NMR-800/NMR-1800 listens on TCP port 8040 for clients to connect. Due to the nature of TCP/IP the client must be aware that it can take up to 1 minute before the NMR-800/NMR-1800 starts to send data to the client after a the Logon message has been sent. Another matter the client application must handle is when the connection is broken abnormally, for example when the cable is removed from the server. The NMR-800/NMR1800 will discover this, when the next message is sent to the client, and logout the client from the NMR Network. A client that don't send any messages to the NMR Network will not discover this break down of the connection. The client will thus believe that the connection is intact and continue wait for new messages. Section 2.3 describe how to handle this situation and how to maintain the connection.
2.1
Logon to the NMR-800/NMR-1800 The client shall establish a TCP/IP socket connection to the NMR server. When the connection has been established the client shall send a complete logon message before the logon attempt is timed out by the NMR server. The default value for the logon timeout is 5 seconds. The administrator of the NMR Network can change the timeout value. The timeout counter starts directly after the connection has been established. The logon message has the following format: 1 01
1 - 31 User Id
Size in bytes 1 1 - 63 00 Password
1 00
Figure 2-1 Logon Message
The user id and password shall be sent in plain text. The complete logon message must be sent before the logon timeout expires. If the logon was not successful the connection will be closed by the NMR-800/NMR-1800. The reason to an un-successful logon can be one of the following: •
Logon took to long time (logon timeout expired) or
•
Incorrect format of the logon message or
•
Unknown user id or incorrect password or
•
User account has been removed or is not active
•
The user id or host has been locked out, see Section 3.2.
If the logon was successful the client will start to receive data in accordance with the clients profile. 2.2
Message Protocol The message protocol used is in accordance with document Presentation System Port Interface Description SWT-001-DD-01 version 1.6 with the following exceptions and amendments.
Document id: 7000 101-185 C
Communication Protocol
Page 3
•
Only $PAIS 04, 05, 06, 07, 08, 09, 0E, 0F, 12 and 16 are allowed to be send to the NMR-800/NMR-1800. A client can however have been configured to only allow a subset of the listed messages.
•
Any other PAIS message will cause the connection to be closed by the NMR800/NMR-1800.
•
A number of PSTT messages as defined in this document have been added.
The NMR-800/NMR-1800 parses received message from the client and if a rule defining correct message is broken the connection will be closed. The administrator of the NMR Network can change the behaviour of the NMR-800/NMR1800 to not close the connection when below listed rules is broken, see section 3.1. 2.2.1
Acknowledgments of Addressed Messages The application does not need to send any acknowledgments for received addressed messages. The NMR server automatically generates the acknowledgments.
2.3
Maintain the Connection To maintain the connection and to discover when the connection is broken abnormally the client can use two methods.
2.3.1
Socket Keep-Alive This method is the preferred method as the TCP/IP stack in the server running the client application handles this automatically when enabled. Another advantage is that no extra TCP/IP traffic is generated when the connection works and data is received. The socket Keep-Alive function is started when no traffic is detected after a pre-configured timeout and stopped when data is received again. The socket Keep-Alive function is enabled when the socket option SO_KEEPALIVE is set to 1 with the setsockopt() call. int iKeepAlive = 1; setsockopt(m_socket, SOL_SOCKET, SO_KEEPALIVE, (const char *)&iKeepAlive, sizeof(int)) Figure 2-2 Socket Keep-Alive C Code Example
To change the timeout of the socket Keep-Alive function a modification of the registry is required. This applies to Windows 2000 only. For other operating systems consult the user documentations for respective operating system. The following parameter in the registry controls the timeout: HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\KeepAliveTime
Set this parameter to value required by the client application. The value is measured in milliseconds. Don't set the parameter to less than 10000 milliseconds. Don't make any modifications in the registry unless you know what you do. 2.3.2
Application Keep-Alive The second method is done on the application level. The client application sends an application Keep-Alive message to the NMR-800/NMR-1800 at a regular interval or when needed to verify the connection. The application Keep-Alive message will be bounced
Document id: 7000 101-185 C
Communication Protocol
Page 4
back to the client by the NMR-800/NMR-1800. If now message is returned within 5 seconds the client application should close the connection. If the connection has been closed abnormally the client application will be notified immediately by the TCP/IP stack when an application Keep-Alive message is sent. The application Keep-Alive message has the following format: $PSTT,01 Figure 2-3 Application Keep-Alive Message
2.4
Logoff from the NMR-800/NMR-1800 The client is logged off from the NMR-800/NMR-1800 on request by the client or if the connection is broken abnormally. The client can request to be logged off by sending the logoff message to the NMR800/NMR-1800. The client will then be logged off from the AIS network and the connection will be closed by the NMR-800/NMR-1800. The client shall when the command has been sent close the connection. The logoff message has the following format: $PSTT,FF Figure 2-4 Logoff Message
Document id: 7000 101-185 C
Error Handling
Page 5
3
ERROR HANDLING
3.1
Violation of Application Firewall Rule If the client breaches any of the rules defining the correct handling of the connection or messages the connection to the client will be closed by the NMR-800/NMR-1800. The administrator of the NMR Network can configure a client to have the NMR800/NMR-1800 to be more forgiving and override this behaviour for some of the rules, see below. Due to security the following breach of the defined rules and errors will always cause the connection to be closed: •
Logon failure (timeout, incorrect user id, faulty password, user id/host locked out) and
•
Unknown message.
The following breach of the defined rules can be changed to not close the established connection: •
Incomplete message,
•
A message not allowed to be sent from the client,
•
The source MMSI is not correct,
•
The client is not allowed to use a application id,
•
The client has sent too many messages over a configured time and
•
Message syntax error (too long message, too many fields, too long field, missing field, illegal MMSI, invalid channel, value out of range, invalid application id)
A message breaking any of the rules is however always dropped by the NMR-800/NMR1800 regardless if the client profile has been configured to close the connection or not when a rule has been broken. 3.1.1
Error Messages The following breaches of the defined rules will result in an error message sent to the client. Depending of the configuration of the client the connection may be closed after the error message has been sent. The message breaking the rule will always be dropped.
3.1.1.1
Unknown Message When the client has sent an unknown message the following error message will be sent to the client. $PSTT,F0,01 Figure 3-1 Error Message "Unknown Message"
The connection will be closed by the NMR-800/NMR-1800 after the error message has been sent.
Document id: 7000 101-185 C
Error Handling
3.1.1.2
Page 6
Incomplete Message When the client has not completed a message within a configured time the following error message will be sent to the client. One reason for this error is missing to end the message with . $PSTT,F0,80 Figure 3-2 Error Message " Incomplete Message "
Depending of the configuration of the client the connection may be closed after the error message has been sent. 3.1.1.3
Message not Allowed When the client has sent a message not in the clients set of allowed $PAIS messages the following error message will be sent to the client. $PSTT,F0,81, Figure 3-3 Error Message "Message not Allowed"
will be replaced with the original message sent from the client. Depending of the configuration of the client the connection may be closed after the error message has been sent. 3.1.1.4
Incorrect Source MMSI When the client has sent a message with an incorrect source MMSI the following error message will be sent to the client. $PSTT,F0,82, Figure 3-4 Error Message "Incorrect Source MMSI"
will be replaced with the original message sent from the client. Depending of the configuration of the client the connection may be closed after the error message has been sent. 3.1.1.5
Incorrect Application Id When the client has sent a message with an incorrect Application Id the following error message will be sent to the client. $PSTT,F0,83, Figure 3-5 Error Message "Incorrect Application Id"
will be replaced with the original message sent from the client. Depending of the configuration of the client the connection may be closed after the error message has been sent. 3.1.1.6
Too many Messages When the client has sent too many a messages over a configured time the following error message will be sent to the client. $PSTT,F0,84,
Document id: 7000 101-185 C
Error Handling
Page 7
Figure 3-6 Error Message "Too many Message"
will be replaced with the original message sent from the client. Depending of the configuration of the client the connection may be closed after the error message has been sent. 3.1.1.7
Message Syntax Error When the client has sent a message with a syntax error the following error message will be sent to the client. $PSTT,F0,FF,, Figure 3-7 Error Message "Message Syntax Error"
will be replaced with one of the below defined error codes. will be replaced with the original message sent from the client. The error message "Message Syntax Error" will be sent when one of the following syntax errors is found in the original message: •
Too long message (error code hex 01),
•
Too many fields (hex 02),
•
Invalid field length (hex 03),
•
Missing field (hex 04),
•
Invalid MMSI (hex 05),
•
Invalid channel (hex 06),
•
Value out of range (hex 07),
•
Invalid Application Id (hex 08),
•
Invalid character (hex 09),
•
missing (hex 0A) and
•
Invalid checksum (hex 0B)
Depending of the configuration of the client the connection may be closed after the error message has been sent.
Document id: 7000 101-185 C
Error Handling
3.2
Page 8
User/Host Lockout A user id or a host can be locked out if the limit of un-successful logons is reached. The default value for the lockout threshold on user level is 3 failures within 5 minutes. On host level the default limit is 10 failures within 5 minutes. As a logon failure on user level the following situations are regarded as a failure: •
The user id does not exists in the configuration database,
•
The user id is not active, that is the user id exists in the database but is not allowed to logon,
•
The supplied password does not match stored password
On the host level the following situations increments the counter of un-successful logons: •
A logon attempt with a user id that does not exists in the configuration database,
•
A logon attempt with a in-active user id,
•
Invalid password
In other words, on host level every failed logon attempt is counted regardless of user id. Default lockout duration on both levels are 5 minutes. A client trying to logon while the client or host is locked out will be disconnected immediately without any notification. During the lockout duration the client will be disconnected regardless if the user id and password supplied in the logon message are correct or not. The reason for the lockout is because of security. The lockout function will make it harder for an intruder to scan for valid user id and password.
Document id: 7000 101-185 C
Code Examples
4
Page 9
CODE EXAMPLES The following code examples shows possible implementations in Microsoft C/C++ and Visual Basic. No error handling is performed in the examples.
4.1
C/C++ The example code shows how to connect to a remote service running on host behind port . SOCKET mySocket = socket(AF_INET, SOCK_STREAM, 0); // set address and connect struct sockaddr_in addr; memset(&addr, 0, sizeof(addr)); addr.sin_family = AF_INET; addr.sin_port = htons(); addr.sin_addr = ; connect(mySocket, (sockaddr*)&addr, sizeof(addr)); int iKeepAlive = 1; setsockopt(mySocket, SOL_SOCKET, SO_KEEPALIVE, (const char *)&iKeepAlive, sizeof(int)); Figure 4-1 Connect C Code Example
The example code shows how to send the logon message. char szLogin[256]; sprintf(szLogin, "%c%s%c%s", 1, , 0, ); size_t bytesToSend = sizeof() + sizeof() + 3; send(mySocket, szLogin, bytesToSend, 0)); Figure 4-2 Send C Code Example
4.2
Visual Basic In the below VB examples the variable Winsock1 is an instance of Microsoft Winsock ActiveX control. The example code shows how to connect to a remote service running on host behind port . Winsock1.RemoteHost = Winsock1.RemotePort = Winsock1.Connect Figure 4-3 Connect VB Code Example
The example code shows how to send the logon message. Winsock1.SendData (Chr(1) + + Chr(0) + + Chr(0)) Figure 4-4 Send VB Code Example
Document id: 7000 101-185 C
