Appendix A: Abridged Flap Specification

This appendix includes an extract from version 2.2 of the FLAP specification. This documents the FLAP messages and includes the FLAP XML schema.

BEEP Protocol Binding

FLAP uses the Block Extensible Exchange Protocol (BEEP) (see Reference 1) for the session-layer protocol. BEEP provides a secure, asynchronous communication layer that allows for two-way communication between client and server. It also manages message framing and message-response correlation.

The FLAP profile is identified by the URN:

• http://sitacs.uow.edu.au/ns/location/flap/beep

Following the guidelines of Reference 1, Table A.1 summarizes the FLAP profile.

Table A.1: BEEP Profile Summary

Registration Item	Value
Profile Identification	http://sitacs.uow.edu.au/ns/location/flap/beep
Messages exchanged during channel creation	ns-prefix
Messages starting one-to-one exchanges	ns-prefix, ntfy, aq
Messages in positive replies	syncr, aqr
Messages in negative replies	error
Messages in one-to-many exchanges	sync
Message syntax	This appendix
Message semantics	Chapter 3 of this book
Contact information	The authors of this book

BEEP Transport

The TCP [binding for BEEP] is required (see References 1 and 2). In addition, it is recommended that the TLS profile for BEEP be used for FLAP TLS provides a reliable connection with authentication and protection from replay, intercept, and eavesdropping. However, where performance requirements demand it, unsecured TCP may be used, providing that link security is ensured through other means (dedicated media, VPN, and so on).

No specific TLS ciphersuite is required for this protocol, although due to the nature of the relationship between the LIS and ALE, those defined in Reference 3 are recommended. Pre-shared keys provide a degree of security over unsecured TCP without significantly affecting ALE performance or increasing the management overhead of maintaining the ALE. The pure Pre-Shared Key (PSK) ciphersuites described in Section 2 of Reference 3 do not protect against dictionary attacks, other ciphersuites may be selected if this is considered insufficient.

No TCP port is reserved for FLAP communications.

Connection Management

Connection establishment is the responsibility of the LIS. This ensures that the LIS is able to regulate the rate at which it establishes connections. The LIS is also responsible for starting the FLAP channel.

The ALE MAY support the establishment of multiple connections from a LIS for link redundancy. Where multiple connections exist, response messages and error indications must be transmitted on the same connection as the original request or detected error condition. If multiple connections to an ALE have been established, the ALE must send notification messages on all connections; the ALE should not assume that the connections have been established by the same LIS.

A single BEEP connection may have any number of FLAP channels, although it is recommended that only one channel be established. Where multiple channels are employed, the ALE must not send duplicate notification messages; one channel should be selected for notifications.

Note that in certain situations, particularly where NAT is employed, inactive connections may go "stale," preventing further use of the connection. The LIS should either close unused connections or use the resynchronization message as a "keep-alive" request. The TCP "keep-alive" method is not recommended because the minimum interval is too short to be practical.

BEEP and XML

FLAP uses XML messages to convey data. The character encoding for XML documents should be UTF-8 or UTF-16.

Implementations also should validate each message against the schema. The Post Schema Validation Infoset (PSVI) can contain more information that is explicitly expressed in the message, because default and fixed values are included in schema. Errors in well formedness and schema validation must be reported.

Note that each message is an XML fragment only. Fragments can be validated by insertion. The fragment is inserted into the last ns-prefix message received, which then forms a complete XML document.

FLAP Versions

The FLAP namespace is identified by the http://sitacs.uow.edu.au/ns/location/flap/beep URN. New versions of this protocol will be identified by a different URN.

Error Handling

If a LIS or ALE notices an error in the received stream, they should generate an error message to notify the sender of the error. Errors include badly formed XML, unsupported protocol versions, and errors relating to the state of either LIS or ALE.

Error messages typically arise from the receipt of a message that displays an error (or errors) in processing a request. In these cases, the error indication is included in a standard BEEP ERR response. If an error is detected in any response message (RPY, ANS, NUL), the MSG frame is used to send the error indication. An error that is raised in this manner must be acknowledged with an empty RPY frame. Error messages, however, must not be generated in response to errors in an error (ERR) message.

If a particular error renders the connection unusable for any reason, the connection must be closed. Likewise, the channel should be stopped if an unrecoverable error occurs in the channel.

A LIS or ALE should respond to requests within a short amount of time. BEEP uses an acknowledged transport; the sender can be sure that the message was received. From this, it can be assumed that an unanswered request indicates an application error. If the other end does not respond within a certain amount of time, two possibilities are recommended:

• Further to the recommendations in the earlier section titled "Connection Management," if no messages are received on the FLAP channel over a similar period, the channel should be terminated and restarted. Similarly, if there is no activity on the connection, the connection can be terminated and restarted.

• If it is only a single message that has not been answered within a certain period and other messages have been received, the message may be re-sent. An upper limit should be set on the number of times retransmission is attempted. Alternatively, the request can be considered as having failed with the error code 500 (see the later section titled "Result Codes").