TOC 
WSN OpenAPIJ. Suhonen, Ed.
 Department of Computer Systems,
 Tampere University of Technology
 September 14, 2012


Authentication and Capability Format (ACF)

Abstract

This documents describes WSN OpenAPI interface for establishing and authenticating a WSN OpenAPI connection, and querying the supported services.



Table of Contents

1.  Document information
2.  Introduction
3.  Terminology
4.  Specification information
5.  Authentication
    5.1.  Authentication list
    5.2.  Authentication procedure
        5.2.1.  Password authentication
        5.2.2.  Challenge-response authentication
6.  Capability information
7.  Response codes
8.  Message formats
    8.1.  XML
    8.2.  CSV
9.  References
§  Author's Address




 TOC 

1.  Document information

Document version: 1.3

XML namespace: urn:wsn-openapi:acf



 TOC 

2.  Introduction

The Authentication and Capability Format (ACF) provides the means to authenticate WSN OpenAPI devices and query their capabilities.

ACF authenticates a communication session. As such, it is mostly useful for connection-oriented transport layers. Otherwise, authentication features of the ACF could be replaced, e.g. with HTTP basic access authentication. As ACF itself does not encrypt its contents, it is assumed that messages are exchanged over a secure channel, e.g. with TLS/SSL.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].



 TOC 

3.  Terminology

This document uses the following terminology to describe the WSN OpenAPI functionality.

A 'device' is any computing device (e.g. computer, sensor node, mobile phone, or satellite) that accesses a WSN OpenAPI 'service'. The service denotes the capability to provide sensor values, control sensor devices, etc. The user of said service is referred to as a 'client'. A device may both offer a WSN OpenAPI service, and act as a client to access services located on other devices.

A 'session' denotes the time during which a connection is active between a client device and another device providing the WSN OpenAPI service.



 TOC 

4.  Specification information

The specification version described in this document is 1.3. This version number must be included to the version fields in XML and CSV messages to allow correct decoding and interpretation of the message at the receiver.

All WSN OpenAPI messages contain an optional message identifier. A reply message shall contain the same message identifier as the corresponding request message (if any).

The namespace used in XML documents should be urn:wsn-openapi:acf.



 TOC 

5.  Authentication

ACF provides the means for a device to authenticate to a WSN OpenAPI service, this way allowing access control to the gateway services.

A gateway may require that a client authenticates before sending any message. If the authentication is required, messages sent by a client will be ignored and replied with response status 401 (Unauthorized) until the authentication is successfully completed.

A WSN OpenAPI service shall support one of the following authentication methods:

If formal authentication is not required (authentication method is 'none'), the exchange of authentication messages is not required. Otherwise, a client must authenticate itself either with 'password' or 'challenge' methods.

A gateway may combine different methods for different access rights. For example, a gateway may allow open access (no authentication) for some data, while requiring password authentication for configuring the network. Maintaining access control lists is implementation specific and outside the scope of this specification.



 TOC 

5.1.  Authentication list

A client may request the list of supported authentication methods with AuthenticationListRequest message (Figure 1 (AuthenticationListRequest)).



<AuthenticationListRequest version="1" xmlns="urn:wsn-openapi:acf"/>
 Figure 1: AuthenticationListRequest 

A gateway replies to the AuthenticationListRequest with AuthenticationListResponse message (Figure 2 (AuthenticationListResponse example)) that contains a list of the supported authentication methods.



<AuthenticationListResponse version="1" xmlns="urn:wsn-openapi:acf">
  <Method name="password">
  <Method name="challenge">
</AuthenticationListResponse>
 Figure 2: AuthenticationListResponse example 



 TOC 

5.2.  Authentication procedure

A client initiates authentication with a AuthenticationRequest message. The contents of this message depends on the authentication method. If the service does not require authentication, the authentication procedure is optional.

After the authentication, the client may send other openapi messages, including configuring the network with WMF and requesting archived measurements and alerts with SADF.



 TOC 

5.2.1.  Password authentication

Password authentication allows identifying the client to the gateway. The password is transmitted in plain text, thus necessitating the use of secure channel for communications.

AuthenticationRequest message comprises username and password fields (Figure 3 (Example of password authentication)).



<AuthenticationRequest version="1" xmlns="urn:wsn-openapi:acf" method="password">
  <Parameter name="username" value="user"/>
  <Parameter name="password" value="pass"/>
</AuthenticationRequest>
 Figure 3: Example of password authentication 

Gateway replies to the authentication with AuthenticationResponse message (Figure 4 (AuthenticationResponse indicating a successful authentication)). The response contains a return code with value 200 OK if the authorization was successful, or 405 Forbidden if the username or password was invalid.



<AuthenticationResponse version="1" xmlns="urn:wsn-openapi:acf" code="200"/>
 Figure 4: AuthenticationResponse indicating a successful authentication 



 TOC 

5.2.2.  Challenge-response authentication

The challenge-response authentication method allows a two-way authentication to ensure that both devices can be trusted. The cryptographic protocol used to calculate the challenges is outside the scope of this specification.

The authentication procedure begins when a client transmits an AuthenticationRequest (Figure 5 (Client's authentication challenge)). Note that the key used in the example is not safe and is presented for demonstration purposes.



<AuthenticationRequest version="1" xmlns="urn:wsn-openapi:acf" method="challenge">
  <Parameter name="username=" value="user"/>
  <Parameter name="challenge" value="5A2D05A94E7254197E9D71438B5FB565B6FD"/>
</AuthenticationRequest>
 Figure 5: Client's authentication challenge 

As a response to the challenge, the service replies with another AuthenticationRequest (Figure 6 (Services's authentication response and challenge)).



<AuthenticationResponse version="1" xmlns="urn:wsn-openapi:acf" code="200">
  <Parameter name="response" value="00F86123869E401F7334B9B0D0018A60F1DE911"/>
</AuthenticationResponse>
<AuthenticationRequest version="1" xmlns="urn:wsn-openapi:acf" method="challenge">
	<Parameter name="challenge" value="A29CDD4C062F05BF509CA3B561375CBC41792"/>
</AuthenticationRequest>
 Figure 6: Services's authentication response and challenge 

Client compares result and replies with AuthenticationResponse message (Figure 7 (Client's authentication response)).



<AuthenticationResponse version="1" xmlns="urn:wsn-openapi:acf" code="200">
  <Parameter name="response" value="FDAE4C590C524CF758917E62C2A2A1221E376CB"/>
</AuthenticationResponse>
 Figure 7: Client's authentication response 



 TOC 

6.  Capability information

A client may request supported interfaces with a CapabilityRequest message.



<CapabilityRequest version="1" xmlns="urn:wsn-openapi:acf"/>
 Figure 8: Capability request 

The request is replied with CapabilityResponse that lists the supported services (Figure 9 (Example of capability response)). Only the services that are supported and to which the user has access rights are listed.



<CapabilityResponse version="1" xmlns="urn:wsn-openapi:acf">
  <Interface name="NMF">
    <Parameter name="Measurements"/>
    <Parameter name="Alerts"/>
  </Interface>
  <Interface name="SIDF"/>
  <Interface name="SADF"/>
  <Interface name="NASC"/>
  <Interface name="MEDF"/>
</CapabilityResponse>
 Figure 9: Example of capability response 

An interface may define parameters that further describe its capabilities. An empty parameter list means that the interface is fully supported. When at least one parameter is listed, the interface supports only the features that are listed (missing parameters are unsupported).



 TOC 

7.  Response codes

Table 1 (ACF return codes) presents the response codes that an ACF service may return.



CodeNameDescription
200 OK Authentication was successful
400 Bad request Authentication request was invalid
403 Method not allowed Authentication method was invalid or unsupported
405 Forbidden Authentication denied

 Table 1: ACF return codes 



 TOC 

8.  Message formats

The handshaking with ACF is presented in Figure 10. AuthenticationListRequest and CapabilityRequest messages are optional but recommended. The authentication itself is done with message AuthenticationRequest.



 Client                                    Gateway
    |                                         |
    |  ACF:AuthenticationListRequest          |
    |---------------------------------------->|
    |  ACF:AuthenticationListResponse         |
    |<----------------------------------------|
    |                                         |
    |  ACF:AuthenticationRequest              |
    |---------------------------------------->|
    |  ACF:AuthenticationResponse             |
    |<----------------------------------------|
    |                                         |
    |  ACF:CapabilityRequest                  |
    |---------------------------------------->|
    |  ACF:CapabilityResponse                 |
    |<----------------------------------------|
    |                                         |
 Figure 10 



 TOC 

8.1.  XML



Schema of authentication list request messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:simpleType name="ResponseFormatType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="XML"/>
			<xs:enumeration value="CSV"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="AuthenticationListRequestType">
		<xs:attribute name="version" type="xs:double" use="required" />
        <xs:attribute name="responseFormat" type="ResponseFormatType" use="optional"
                      default="XML" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
	</xs:complexType>

    <xs:element name="AuthenticationListRequest"
                type="AuthenticationListRequestType" />
</xs:schema>

 Figure 11 



Schema of authentication list response messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:simpleType name="ResponseCodeType">
		<xs:restriction base="xs:integer">
			<xs:enumeration value="200"/>
			<xs:enumeration value="400"/>
			<xs:enumeration value="403"/>
			<xs:enumeration value="405"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="MethodEnumType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="none" />
			<xs:enumeration value="password" />
			<xs:enumeration value="challenge" />
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="MethodType">
		<xs:attribute name="name" type="MethodEnumType" />
	</xs:complexType>

	<xs:complexType name="AuthenticationListType">
		<xs:sequence>
            <xs:element name="Method" type="MethodType" minOccurs="0"
                        maxOccurs="unbounded" />
		</xs:sequence>
		<xs:attribute name="version" type="xs:double" use="required" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
		<xs:attribute name="responseCode" type="ResponseCodeType" use="required" />
	</xs:complexType>

    <xs:element name="AuthenticationListResponse"
                type="AuthenticationListType" />
</xs:schema>

 Figure 12 



Schema of authentication request messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:simpleType name="ResponseFormatType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="XML"/>
			<xs:enumeration value="CSV"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="MethodEnumType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="none" />
			<xs:enumeration value="password" />
			<xs:enumeration value="challenge" />
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="ParameterType">
		<xs:attribute name="name" type="xs:string" />
		<xs:attribute name="value" type="xs:string" />
	</xs:complexType>

	<xs:complexType name="AuthenticationRequestType">
		<xs:sequence>
			<xs:element name="Parameter" type="ParameterType" minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
		<xs:attribute name="method" type="MethodEnumType" />
		<xs:attribute name="version" type="xs:double" use="required" />
        <xs:attribute name="responseFormat" type="ResponseFormatType"
                      use="optional" default="XML" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
	</xs:complexType>

    <xs:element name="AuthenticationRequest"
                type="AuthenticationRequestType" />
</xs:schema>

 Figure 13 



Schema of authentication response messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:simpleType name="ResponseCodeType">
		<xs:restriction base="xs:integer">
			<xs:enumeration value="200"/>
			<xs:enumeration value="400"/>
			<xs:enumeration value="403"/>
			<xs:enumeration value="405"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="MethodEnumType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="none" />
			<xs:enumeration value="password" />
			<xs:enumeration value="challenge" />
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="ParameterType">
		<xs:attribute name="name" type="xs:string" />
		<xs:attribute name="value" type="xs:string" />
	</xs:complexType>

	<xs:complexType name="AuthenticationResponseType">
		<xs:sequence>
			<xs:element name="Parameter" type="ParameterType" minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
		<xs:attribute name="responseCode" type="ResponseCodeType" use="required" />
		<xs:attribute name="version" type="xs:double" use="required" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
		<xs:attribute name="method" type="MethodEnumType" />
	</xs:complexType>

    <xs:element name="AuthenticationResponse"
                type="AuthenticationResponseType" />
</xs:schema>

 Figure 14 



Schema of capabilities list request messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:simpleType name="ResponseFormatType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="XML"/>
			<xs:enumeration value="CSV"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="NetworkType">
		<xs:attribute name="id" type="xs:string" />
	</xs:complexType>

	<xs:complexType name="CapabilityRequestType">
		<xs:sequence>
			<xs:element name="Network" type="NetworkType" minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
		<xs:attribute name="version" type="xs:double" use="required" />
        <xs:attribute name="responseFormat" type="ResponseFormatType"
                      use="optional" default="XML" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
	</xs:complexType>

	<xs:element name="CapabilityRequest" type="CapabilityRequestType" />

</xs:schema>

 Figure 15 



Schema of capabilities list response messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >


	<xs:simpleType name="ResponseCodeType">
		<xs:restriction base="xs:integer">
			<xs:enumeration value="200"/>
			<xs:enumeration value="400"/>
			<xs:enumeration value="403"/>
			<xs:enumeration value="405"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="DataType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="both" />
			<xs:enumeration value="linked" />
			<xs:enumeration value="inline" />
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="NetworkType">
		<xs:attribute name="id" type="xs:string" />
	</xs:complexType>

	<xs:complexType name="ParameterType">
		<xs:attribute name="name" type="xs:string" />
	</xs:complexType>

	<xs:complexType name="InterfaceType">
		<xs:sequence>
			<xs:element name="Network" type="NetworkType" minOccurs="0" maxOccurs="unbounded" />
			<xs:element name="Parameter" type="ParameterType" minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" />
	</xs:complexType>

	<xs:complexType name="CapabilityResponseType">
		<xs:sequence>
			<xs:element name="Interface" type="InterfaceType" minOccurs="0" maxOccurs="unbounded" />
		</xs:sequence>
		<xs:attribute name="version" type="xs:double" use="required" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
		<xs:attribute name="responseCode" type="ResponseCodeType" use="required" />
		<xs:attribute name="preferData" type="DataType" use="optional" default="inline" />
		<xs:attribute name="watchdog" type="xs:integer" use="optional" >
			<xs:annotation><xs:documentation>Watchdog time (if used at the server) for how long the connection may be open in inactive state.</xs:documentation> </xs:annotation>
		</xs:attribute>
	</xs:complexType>

	<xs:element name="CapabilityResponse" type="CapabilityResponseType" />

</xs:schema>

 Figure 16 



Schema of ping messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:simpleType name="ResponseFormatType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="XML"/>
			<xs:enumeration value="CSV"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="PingType">
		<xs:attribute name="version" type="xs:double" use="required" />
		<xs:attribute name="responseFormat" type="ResponseFormatType" use="optional" default="XML" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
	</xs:complexType>

	<xs:element name="Ping" type="PingType" />

</xs:schema>

 Figure 17 



Schema of pong messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:simpleType name="ResponseCodeType">
		<xs:restriction base="xs:integer">
			<xs:enumeration value="200"/>
			<xs:enumeration value="400"/>
			<xs:enumeration value="403"/>
			<xs:enumeration value="405"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="PongType">
		<xs:attribute name="version" type="xs:double" use="required" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
		<xs:attribute name="responseCode" type="ResponseCodeType" use="required" />
	</xs:complexType>

	<xs:element name="Pong" type="PongType" />

</xs:schema>

 Figure 18 



Schema of close connection messages:

<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"

  targetNamespace="urn:ietf:params:xml:ns:acf"
  xmlns="urn:ietf:params:xml:ns:acf"
  >

	<xs:complexType name="CloseConnectionType">
		<xs:attribute name="version" type="xs:double" use="required" />
		<xs:attribute name="messageId" type="xs:string" use="optional" />
	</xs:complexType>

	<xs:element name="CloseConnection" type="CloseConnectionType" />

</xs:schema>

 Figure 19 



 TOC 

8.2.  CSV



The Augmented Backus-Naur Form (ABNF) RFC 5234 (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] definition:

ACF-MESSAGE = AUTHENTICATION-LIST / AUTHENTICATION / CAPABILITIES-LIST / PING / PONG / CLOSE-CONNECTION

AUTHENTICATION-LIST = AUTHENTICATION-LIST-REQUEST / AUTHENTICATION-LIST-RESPONSE
AUTHENTICATION = AUTHENTICATION-REQUEST / AUTHENTICATION-RESPONSE
CAPABILITIES-LIST = CAPABILITIES-LIST-REQUEST / CAPABILITIES-LIST-RESPONSE

AUTHENTICATION-LIST-REQUEST = "ACF:AUTHENTICATION-LIST-REQUEST" ";" VERSION ";" RESPONSE-FORMAT ";" MESSAGE-ID END-OF-LINE LF
AUTHENTICATION-LIST-RESPONSE = "ACF:AUTHENTICATION-LIST-RESPONSE" ";" VERSION ";" RESPONSE-CODE ";" MESSAGE-ID ";" LINES *(LF METHOD-LINE) LF
METHOD-LINE = AUTHENTICATION-METHOD END-OF-LINE

AUTHENTICATION-REQUEST = "ACF:AUTHENTICATION-REQUEST" ";" VERSION ";" RESPONSE-FORMAT ";" MESSAGE-ID ";" AUTHENTICATION-METHOD ";" LINES *(LF PARAMETER-LINE) LF
AUTHENTICATION-RESPONSE = "ACF:AUTHENTICATION-RESPONSE" ";" VERSION ";" RESPONSE-CODE ";" MESSAGE-ID ";" AUTHENTICATION-METHOD ";" LINES *(LF PARAMETER-LINE) LF
PARAMETER-LINE = NAME ";" VALUE END-OF-LINE


CAPABILITIES-LIST-REQUEST = "ACF:CAPABILITY-REQUEST" ";" VERSION ";" RESPONSE-FORMAT ";" MESSAGE-ID END-OF-LINE LF
CAPABILITIES-LIST-RESPONSE = "ACF:CAPABILITY-RESPONSE" ";" VERSION ";" RESPONSE-CODE ";" MESSAGE-ID ";" DATA-TYPE ";" WATCHDOG ";" LINES *(LF INTERFACE-LINE) LF
INTERFACE-LINE = NAME ";" [NETWORK] *("," NETWORK) ";" [INTERFACE-PARAMETER] *("," INTERFACE-PARAMETER) END-OF-LINE
INTERFACE-PARAMETER = VALUE
NETWORK = VALUE

PING = "ACF:PING" ";" VERSION ";" RESPONSE-FORMAT ";" MESSAGE-ID

PONG = "ACF:PONG" ";" VERSION ";" RESPONSE-CODE ";" MESSAGE-ID

CLOSE-CONNECTION = "ACF:CLOSE-CONNECTION" ";" VERSION ";"

AUTHENTICATION-METHOD = "none" / "password" / "challenge"
END-OF-LINE = *(";")
VERSION = Double
RESPONSE-FORMAT = "XML" / "CSV"
LINES = Integer
MESSAGE-ID = String
RESPONSE-CODE = "200" / "400" / "403" / "405"
NAME = String
VALUE = String
DATA-TYPE = "both" / "linked" / "inline"
WATCHDOG = Integer

Double = 1*DIGIT ["." 1*DIGIT]
String = DQUOTE *VCHAR DQUOTE
 Figure 20 



 TOC 

9. References

[RFC5234] Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” STD 68, RFC 5234, January 2008 (TXT).
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997.


 TOC 

Author's Address

  Jukka Suhonen (editor)
  Department of Computer Systems, Tampere University of Technology
  Korkeakoulunkatu 1
  Tampere, 33101
  FI
Email:  tutwsn@cs.tut.fi