SERVAL communications protocol
ASN.1 specification
We have designed a protocol to communicate the client with the server and we chose ASN.1 (Abstract system notation 1) as the way to code and interchange the Serval messages.
The ASN.1 standard is an abstract notation to specify data types and it defines the way to convert these data types to a stream of bytes to send through a computer network. The ASN.1 is both CPU architecture and programming language independent. So, on specifying the SERVAL protocol in ASN.1, a client in any programming language might be implemented.
In both the SERVAL server and client is used the ASN.1 Erlang compiler to code and decode the communication messages.
Protocol description
The messages which make up the SERVAL communication protocol are the following:
connectionRequest
The
connectionRequest message is used to ask SERVAL to accept the connection from a client. The fields of the message are:
| connectionRequest | ConnectionRequestType |
ConnectionRequestType can have two values:
- startTLS
It requests to start an encrypted connection.
- notStartTLS It request to start a clear connection.
responseDataConnectionResponse
The
responseDataConnectionResponse message is the answer of the SERVAL server to a
connectionRequest message.
(A)
| responseDataConnectionResponse | UserName | MacAddress | ServerList |
(B)
| responseDataConnectionResponse | MacAddress | ServerList | AuthenticationOptions |
- UserName It is the login of the user the client has been authenticated with.
- MacAddress It the MAC address by the server to the virtual network interface of the client.
- ServerList It is the list of nodes the SERVAL server has. The information provided for each node is the machine DNS name and the port numbers for the udp, tcp and ssl connections.
- AuthenticationOptions Here the authentication options are showed.
errorConnectionRequestCode
This message is sent by the SERVAL server if a
connectionRequest message is received and an error happens.
| errorConnectionRequestCode | ErrorCode |
ErrorCode can have be:
unknownError,
noFreeMac and
systemNotAvailable
authenticatePlainRequest
It is used to open an authentication process using the
plain method. The format of the message is:
| authenticatePlainRequest | Login | Password |
- Login User identifier.
- Password Watchword to authenticate.
authenticatePlainResponse
This is the answer sent by the SERVAL server of a previous
authenticateRequest message. The format of the message is:
(A)
| authenticatePlainResponse | Login |
(B)
| authenticationPlainResponse | Login | ErrorCode |
- Login User identifier who requested the authentication process.
- ErrorCode If the authentication is not successful then an ErrorCode is sent back.
sendUnicastSourceToServer
This message is used to send data from a client to another. The format of the message:
| sendUnicastSourceToServer | DestinationAddress | MessageData |
- DestinationAddress It is the MAC address of the destination client.
- MessageData It is the data to deliver to the destination.
sendBroadcastSourceToServer
With this message the data is delivered by the SERVAL server to all the clients belonging to the VLANs the client sending the message belongs.
| sendBroadcastSourceToServer | MessageData |
- MessageData It is the data to deliver to the destination.
sendMessageServerToDestination
This message is sent by the server to deliver data to clients. It can be caused by the arrival to SERVAL of a
sendUnicastSourceToServer or a
sendBroadcastSourceToServer.
| sendMessageServerToDestination | MessageData |
- MessageData It is the data to deliver to the destination.
joinVlanRequest
It is used to join the client to an existing VLAN.
- VlanId It is the identifier of the VLAN the client is going to join to.
joinVlanResponse
It is the response emitted by the SERVAL server on receiving a
joinVlanRequest.
(A)
(B)
| joinVlanResponse | VlanId | ErroCode |
- VlanId The name of the VLAN this answer corresponds with.
- ErrorCode At the moment, notInAccessGroup, notExistingVlan and alreadyJoinedVlan are the three types or erros can be handled.
createVlanRequest
This message is to create VLANS in SERVAL.
(A)
| createVlanRequest | VlanId | Description |
(B)
| createVlanRequest | VlanId | Description | ListGroups |
- VlanId Name of the VLAN to create.
- Description Some words explaining the porpuse of the VLAN.
- ListGroups User groups with access permission to join the VLAN.
vlanListRequest
With this message the user can ask the list of VLANs created in the server.
vlansListResponse
With
vlansListResponse the SERVAL server communicates the list of VLANS created in the server.
| vlansListResponse | ListofVlans |
leaveVlanRequest
This message is to request to abandon a VLAN.
| leaveVlanRequest | VlanName |
- VlanName It is the identifier of the VLAN to create.
leaveVlanResponse
It is the answer the server gives to a
leaveVlanRequest message.
(A)
| leaveVlanRequest | VlanName |
(B)
| leaveVlanRequest | VlanName | ErrorCode |
- VlanName It is the VLAN identifier.
- ErrorCode It is the error code when something bad has happened. The errors which are considered until now are notInVlan and notExistingVlan.
listVlansJoinedRequest
This is message to request the list of VLANs the client is connected to.
listVlansJoinedResponse
This is the response message of the previous one,
listVlansJoinedRequest.
(A)
| listVlansJoinedResponse | ListOfVlansJoined |
(B)
| listVlansJoinedResponse | ErrorCode |
- ListOfVlansJoined It is the list of VLANS joined by the client that issued the message.
- ErrorCode The error which is handled at the moment is notInAnyVlan.
clientsInVlanListRequest
With this message the user can ask for the clients which are connected to a VLAN.
| clientsInVlanListRequest | VlanName |
- VlanName It is the name of the VLAN the client wants to obtain the list of users connected.
clientsInVlanResponse
It is the message the server answers to the client after receiving a
clientsInVlanListRequest
(A)
| clientsInVlanResponse | VlanName | ListOfClients |
(B)
| clientsInVlanResponse | VlanName | ErrorCode |
- VlanName Vlan identifier
- ListOfClients The list of clients belonging to the VLAN.
- ErrorCode The errors handled are notClientsInVlan and notExistingVlan.
deleteVlanRequest
This message is used to delete a VLAN from the SERVAL server. To delete a VLAN it has to be empty.
- VlanId The VlanId is the name of the VLAN it wants to be deleted.
deleteVlanResponse
This is the confirmation message of a
deleteVlanRequest.
(A)
| deleteVlanResponse | VlanId |
(B)
| deleteVlanResponse | VlanId | ErrorCode |
- VlanId The name of the VLAN requested for deletion.
- ErrorCode The errors handled are vlanEmpty and notExistingVlan.
setOnPromiscouModeRequest
This is used to request turn on the promiscous mode in the client.
setOnPromiscousModeResponse
This is the acknowledgment message to a
setOnPromiscousModeRequest.
| setOnPromiscousModeResponse | ResultCode |
- RequestCode can be success or alreadyPromiscousMode.
setOffPromiscouModeRequest
This is used to request turn off the promiscous mode in the client.
setOffPromiscousModeResponse
This is the acknowledgment message to a
setOffPromiscousModeRequest.
| setOnPromiscousModeResponse | ResultCode |
- RequestCode can be success or alreadyInNormalMode.
div class="twikiTopicInfo twikiRevInfo twikiGrayText twikiMoved"<&/div>-->
