Sessions¶
A session is an agreement between the client that initiated the connection and the server that accepted it to use the connection in a specific way. It assumes that the details of establishing and maintaining the connection have already been provided by a connection-oriented protocol.
Authentication is the process of determining the identity of a connected client by a server. The authentication procedure described in this section is optional, the server may already have determined the identity of the client as a consequence of establishing a secure connection, or the server may provide the service to all clients. Determining when authentication is necessary is a local matter.
Authorization is the process of validating the right to a service by an authenticated client. Authorization is a local matter.
Service Procedure¶
Clients request a service by sending a Service Request to the server using the appropriate Service Identifier. The service responds with an appropriate Service Request Result.
If the server responds with AUTHENTICATION_REQUIRED then the client will send an Access Request with its user name. The server will respond with Access Challenge to authenticate the user, and the client will respond with an Access Response to the challenge. If the challenge is successful, the server will respond with a Service Request Result with the result code SUCCESS.
Protocol Data Units¶
The session PDUs are used to request a specific type of session and establish authentication. Authorization is a function of the server. Authentication is not necessary if the mechanism used to establish the connection already provides authentication, or if the service allows for “guest” access.
Service Request¶
This PDU is sent by a client to a server to request that the connection by used for a specific service. The server may provide more than one service via a common connection endpoint.
| Field | Size | Description |
|---|---|---|
| BSLV Type | 1-octet | Streaming BACnet (value = X‘82’) |
| BSLV Function | 1-octet | BSLV Result (value = X‘00’) |
| BSLV Length | 2-octets | Length (value = X‘0006’) |
| Service Identifier | 2-octets | Service Identifier |
Service Identifier¶
Service identifiers are used to identify a service.
| Service Identifier Code | Value | Description |
|---|---|---|
| DEVICE_TO_DEVICE_SERVICE_ID | 1 | Device-to-Device Service |
| ROUTER_TO_ROUTER_SERVICE_ID | 2 | Router-to-Router Service |
| PROXY_SERVICE_ID | 3 | Proxy Service |
| LANE_SERVICE_ID | 4 | Local Area Network Emulation Service |
Service Request Result¶
This PDU is used by the server to acknowledge that the service requested by the client is accepted and established, or to signal an error condition.
| Field | Size | Description |
|---|---|---|
| BSLV Type | 1-octet | Streaming BACnet (value = X‘82’) |
| BSLV Function | 1-octet | BSLV Result (value = X‘00’) |
| BSLV Length | 2-octets | Length (value = X‘0006’) |
| Result Code | 2-octets | Success (value = X‘0000’) or error |
Result Codes¶
If the server cannot provide the service requested, or the client is not authorized to use the service, the server may respond with a BSLL Response with function code X‘00’ and one of the following error values. It will then terminate the connection.
| Result Code | Value | Description |
|---|---|---|
| SUCCESS | 0 | |
| NO_DEVICE_TO_DEVICE_SERVICE | 1 | |
| NO_ROUTER_TO_ROUTER_SERVICE | 2 | |
| NO_PROXY_SERVICE | 3 | |
| NO_LANE_SERVICE | 4 | |
| UNRECOGNIZED_SERVICE | 10 | |
| AUTHENTICATION_REQUIRED | 11 | Authentication required |
| AUTHENTICATION_FAILURE | 12 | Username and/or username/password failure |
| AUTHENTICATION_NO_SERVICE | 13 | |
| AUTHENTICATION_HASH | 14 | Specified hash function not supported |
Access Request¶
This PDU is sent by a client to the server to initiate the authentication process. It may be sent before a Service Request when the client knows a priory that authentication will be required, or when told by the server it is necessary.
This request includes a request to use a cryptographic hash function to provide a level of encryption of the subsequent Access Challenge and Access Response PDUs.
| Field | Size | Description |
|---|---|---|
| BSLV Type | 1-octet | Streaming BACnet (value = X‘82’) |
| BSLV Function | 1-octet | Access Request (value = X‘02’) |
| BSLV Length | 2-octets | Length (variable) |
| Hash Function Identifier | 1-octet | Hash Function Identifier |
| User name | variable | User name |
The user name is an octet string that identifies the client within the context understood by the server.
Note
I expect the user name to morph into the public key of a public/private key pair, rather than using usernames and passwords.
If the server does not support the hash function requested by the client, the server will respond with a Service Request Result with the error code AUTHENTICATION_HASH and close the connection.
If the server does not recognize the user name provided by the client it may continue with the authentication process by sending an Access Challenge which will ultimately fail, it may send a Service Request Result with the error code AUTHENTICATION_FAILURE and close the connection, or simply close the connection.
Hash Function Identifier¶
The hash function identifier specifies which function of a number of functions that both the client and server will use to create digest values contained in the Access Challenge and Access Response PDUs.
| Hash Function Identifier Code | Value | Description |
|---|---|---|
| MD5 | 0 | MD5 obsolete |
| SHA-1 | 1 | SHA-1 obsolete |
| SHA-2, 224 | 2 | SHA-2 |
| SHA-2, 256 | 3 | |
| SHA-2, 384 | 4 | |
| SHA-2, 512 | 5 |
Access Challenge¶
This PDU is sent by a server to a client after it receives an Access Request to request that the client confirm the user name it presented to the server.
| Field | Size | Description |
|---|---|---|
| BSLV Type | 1-octet | Streaming BACnet (value = X‘82’) |
| BSLV Function | 1-octet | Access Request (value = X‘02’) |
| BSLV Length | 2-octets | Length (variable) |
| Hash Function Identifier | 1-octet | Hash Function Identifier |
| Challenge Data | variable | Challenge data |
The hash function identifier matches the value requested by the client in the Access Request.
The challenge data is a suitably large block of random data.
Access Response¶
This PDU is sent by the client after receiving a Access Challenge from the server.
| Field | Size | Description |
|---|---|---|
| BSLV Type | 1-octet | Streaming BACnet (value = X‘82’) |
| BSLV Function | 1-octet | Access Response (value = X‘03’) |
| BSLV Length | 2-octets | Length (variable) |
| Hash Function Identifier | 1-octet | Hash Function Identifier |
| Response Digest | variable | Response digest |
The hash function identifier matches the value requested by the client in the Access Request and provided by the sever in the Access Challenge.
The response digest is the cryptographic digest of the secret password stored by the client concatenated with the challenge data provided by the server.
Note
I expect the password to morph into the private key of a public/private key pair, rather than using usernames and passwords.
When the server receives the access response, it performs the identical calculation as the client by computing the cryptographic digest of the secret password associated with the client concatenated with the challenge data it provided earlier. If the calculation results are identical, the client is considered authenticated.
If the server does not recognize the user name provided by the client it may continue with the authentication process by sending an Access Challenge which will ultimately fail, it may send a Service Request Result with the error code AUTHENTICATION_FAILURE and close the connection, or simply close the connection.
If the authenticated client had previously requested a specific service, the server will verify that the client is authorized to access the service. If the client is authorized, the server will respond with a Service Request Result with the error code SUCCESS. If the client is not authorized, the server will respond with a Service Request Result with the error code AUTHENTICATION_NO_SERVICE and closes the connection.