Network

Posted on by admin

Network has several methods starting with ‘canUse’. They indicate whether the corresponding property (-ies) and/or method (-s) can be read, called or changed.

Returned values are:

0 = Properties and methods are not applicable. (No access)
1 = Properties’ values can be read; methods that do not make changes in SEC can be called. (Read-only access)
2 = Properties can be read and changed; all methods can be called. (Read/write access)

For example, if a property (like ‘address‘) cannot be changed when network is started, the method (‘canUseAddress‘) will return 1 if network is started (see ‘isStarted‘ method), meaning that ‘address‘ property can be read but not changed.
If network is not started, ‘canUseAddress‘ will return 2, meaning that ‘address‘ property can be both read and set.

Method: mode

Returns the mode of the current connection:

0 = TCP server
1 = TCP client
2 = UDP

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net mode

Returned value:

    uint32 0

 

Method: canStart

Indicates whether the specified connection can be started.

Returns true if connection can be started, false if not.

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net canStart

 

Method: isStarted

Indicates whether the specified connection is started.

Returns true if connection is started, false if not.

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net isStarted

 

Property: address

Address for sending UDP packets to.

Type:                      string (s)
Network mode:              UDP
Related 'canUse' function: canUseAddress
Value limits:              not empty
Default value:             '255.255.255.255'
Note: Cannot be changed when network is started.

Example:

To get property’s value:

    evesec get /SEC/__dev__ttyS0/net connection.net address

To set property’s value:

    evesec set /SEC/__dev__ttyS0/net connection.net address string:'192.168.0.1'

 

Property: port

Port for sending UDP packets to.

Type:                      uint16 (q)
Network mode:              UDP
Related 'canUse' function: canUsePort
Value limits:              <> 0
Default value:             5000
Note: Cannot be changed when network is started.

Example:

To get property’s value:

    evesec get /SEC/__dev__ttyS0/net connection.net port

To set property’s value:

    evesec set /SEC/__dev__ttyS0/net connection.net port uint16:5000

 

Property: listenAddress

Address on which SEC listens to UDP packets.

Type:                      string (s)
Network mode:              UDP
Related 'canUse' function: canUseListenAddress
Value limits:              not empty
Default value:             '0.0.0.0'
Note: Cannot be changed when network is started.

Property: listenPort

Port on which SEC listens to UDP packets or incoming TCP connection requests.

Type:                      uint16 (q)
Network mode:              TCP server, UDP
Related 'canUse' function: canUseListenPort
Value limits:              <> 0
Default value:             5000
Note: Cannot be changed when network is started.

Property: lateSerialPortOpen

If set to true, serial port will not be opened until at least one TCP connection is established.

If set to false, serial port will be opened when connection is started.

Type:                      boolean (b)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseLateSerialPortOpen
Default value:             true
Note: Cannot be changed when network is started.

Property: encryption

Allows encrypting TCP traffic.

Note that this property controls server side encryption.

To set encryption on client side, use parameter of addServer method (see below).

Type:                      boolean (b)
Network mode:              TCP server
Related 'canUse' function: canUseEncryption
Default value:             false
Note: Cannot be changed when network is started.

Method: setAuthorisation

Sets a connection password to enable a TCP server to authenticate remote clients.

The following parameter is used:

  • password – string parameter specifying the password used for connection authorization

Returns no value.

Related 'canUse' function: canUseAuthorisation
Note: Cannot be called when network is started.

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net setAuthorisation \
      string:'password'

 

Method: hasAuthorisation

Indicates whether authorization is used for incoming connection. Returns true if authorization is used, false if not.

Related 'canUse' function: canUseAuthorisation
Note: This is read-only method, i.e. can be called when ‘canUseAuthorisation’ returns either 1 or 2, but not 0.

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net hasAuthorisation

Returned value:

    boolean true

 

Method: clearAuthorisation

Removes authorization used in connection.

Related 'canUse' function: canUseAuthorisation
Note: Cannot be called when network is started.

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net clearAuthorisation
Note: There are no other ways to get back plain text password but via ‘saveScript’ method.

Property: sendPolicy

Together with receivePolicy, controls default traffic policies for a new TCP connection.

If set to 1 then only the first established TCP connection will be allowed to send data to its peer.
All TCP connections established after that will have their transmissions blocked.

If the “first” TCP connection is dropped (disconnected), the next TCP connection, established after that, will be treated as the first one, i.e. will have the right to send data.

To control already established TCP connections’ traffic use dataSendRight and dataReceiveRight properties of each TCP connection.

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseSendPolicy
Value limits:              [0 .. 2]
Values:

0 = Send data to nobody
1 = Send data to the first peer only
2 = Send data to all peers

Default value:             2

See also: receivePolicy, dataSendRight

Property: receivePolicy

Controls data receiving from TCP peers. Works similar to sendPolicy method (see above).

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseReceivePolicy
Value limits:              [0 .. 2]
Values:

0 = Receive data from nobody
1 = Receive data from the first peer only
2 = Receive data from all peers

Default value:             2

See also: sendPolicy, dataReceiveRight

Property: waitPolicy

Controls the way the data from serial port is sent to the network.

Type:                      uint32 (u)
Network mode:              TCP server, TCP client, UDP
Related 'canUse' function: canUseWaitPolicy
Value limits:              [0 .. 4]
Values:

0 = none – No wait policy is used, data is sent immediately.
1 = size – All buffered data is sent when data block reaches the size of the specified value.
2 = char – All buffered data is sent when the specified char is received.
3 = accumulate – A timeout in milliseconds is taken before transmission after which all buffered data is sent.
4 = pause – A pause in milliseconds is made after the packet transmission.

Default value:             0
Note: Cannot be changed when network is started.

See also: waitPolicyValue

Property: waitPolicyValue

Controls specific parameters of the current wait policy.

Type:                      uint32 (u)
Network mode:              TCP server, TCP client, UDP
Condition:                 waitPolicy <> 0
Related 'canUse' function: canUseWaitPolicyValue
Default value:             1024 bytes if waitPolicy = 1 (size)
Default value:             10 ('\n')  if waitPolicy = 2 (char)
Default value:             1000 ms    if waitPolicy = 3 (accumulate)
Default value:             1000 ms    if waitPolicy = 4 (pause)
Note: Cannot be changed when network is started.

Property: maximumClients

Controls maximum number of simultaneous connections (peers) to TCP server.
For Telnet server this value is always equals to 1.

Maximum number of peers can be set even if connection is already started, but established connections will not be dropped to satisfy a new value of maximumClients property.

Type:                      uint32 (u)
Network mode:              TCP server
Condition:                 Not when [Telnet][Network-telnet] is on, as this value always equals to 1.
Related 'canUse' function: canUseMaximumClients
Value limits:              = 1 if Telnet, > 0 otherwise
Default value:             4

See also: telnet

Property: reconnectTimeout

Controls period of time after which TCP client will try to restore connection if connection was dropped or unsuccessful connection attempt occurred.

Type:                      uint32 (u)
Network mode:              TCP client
Related 'canUse' function: canUseReconnectTimeout
Value limits:              > 0
Default value:             5000 ms
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: handshakeTimeout

Controls period of time after which TCP connection will be dropped if handshake is not finished yet.

Handshake is used for encryption and authorization.

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseHandshakeTimeout
Value limits:              > 0
Default value:             30000 ms
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: offlineBufferMaxSize

Controls maximum size of buffer where data arriving from the serial port is collected, when TCP connection is not established.

Buffer will be sent to the first connected peer regardless of sendPolicy and receivePolicy properties.

Also, note that when you decrease this value and the offline buffer already contains more data than you have specified, new value will be applied to the offline buffer only on the next data arrival from the serial port.

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseOfflineBufferMaxSize
Default value:             4096 B
Note: For TCP client mode this property can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: telnet

Controls Telnet mode. This mode works only with 1-to-1 connections and supports RFC 2217.

Type:                      boolean (b)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseTelnet
Default value:             false

See also: maximumClients, telnetReadAttrRight, telnetWriteAttrRight, telnetPing

Property: telnetReadAttrRight

Controls whether serial port attributes can be read by RFC 2217 methods.

Type:                      boolean (b)
Network mode:              TCP server, TCP client
Condition:                 [telnet][Network-telnet] is true
Related 'canUse' function: canUseTelnetParameters
Default value:             true
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: telnetWriteAttrRight

Controls whether serial port attributes can be set by RFC 2217 methods.

Type:                      boolean (b)
Network mode:              TCP server, TCP client
Condition:                 [telnet][Network-telnet] is true
Related 'canUse' function: canUseTelnetParameters
Default value:             true
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: telnetPing

Keeps Telnet ping default interval in milliseconds. If interval value is zero ping is disabled. Telnet ping is implemented via Telnet’s AYT (‘Are You There’) command.

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Condition:                 [telnet][Network-telnet] is true
Related 'canUse' function: canUseTelnetParameters
Default value:             0 ms
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: nagle

Controls Nagle’s algorithm of TCP streams.
Nagle’s algorithm prevents sending multiple small packets by merging them into larger ones instead.

Visit http://en.wikipedia.org/wiki/Nagle’s_algorithm for details.

Type:                      boolean (b)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseNagle
Default value:             true
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: keepAlive

Controls ‘keep alive’ feature of TCP streams.
‘Keep alive’ allows discovering TCP stream disconnection between peers.

We use non-default timeouts (i.e. keepAliveIdle and keepAliveInterval) to detect disconnections faster.

Visit http://en.wikipedia.org/wiki/Keepalive#TCP_Keepalive for details.

Type:                      boolean (b)
Network mode:              TCP server, TCP client
Related 'canUse' function: canUseKeepAlive
Default value:             true
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

See also: TCP keepAlive, keepAliveIdle, keepAliveInterval, keepAliveCount

Property: keepAliveIdle

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Condition:                 [keepAlive][Network-keepAlive] is true
Related 'canUse' function: canUseKeepAlive
Value limits:              <= 604800 s
Default value:             7 s
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: keepAliveInterval

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Condition:                 [keepAlive][Network-keepAlive] is true
Related 'canUse' function: canUseKeepAlive
Value limits:              <= 86400 s
Default value:             1 s
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: keepAliveCount

Type:                      uint32 (u)
Network mode:              TCP server, TCP client
Condition:                 [keepAlive][Network-keepAlive] is true
Related 'canUse' function: canUseKeepAlive
Value limits:              <= 1000
Default value:             9
Note: Can be changed anytime but the value will be applied only to a new TCP connection. Already established TCP connection has its own property.

Property: proxy

Controls proxy usage.

Applicable to all network modes.

In TCP server mode, proxy is used to resolve domain names.

Type:                      uint32 (u)
Network mode:              TCP server, TCP client, UDP
Related 'canUse' function: canUseProxy
Default value:             false
Note: Cannot be changed when network is started.

See also: proxyHostname, proxyPort, proxyUser, proxyPassword

Property: proxyHostname

Controls proxy server host name.

Type:                      string (s)
Network mode:              TCP server, TCP client, UDP
Condition:                 proxy is true
Related 'canUse' function: canUseProxy
Value limits:              not empty
Note: Cannot be changed when network is started.

Property: proxyPort

Controls proxy server port.

Type:                      uint16 (q)
Network mode:              TCP server, TCP client, UDP
Condition:                 proxy is true
Related 'canUse' function: canUseProxy
Value limits:              <> 0
Note: Cannot be changed when network is started.

Property: proxyUser

Controls user name if proxy server requires authentication.

Type:                      string (s)
Network mode:              TCP server, TCP client, UDP
Condition:                 proxy is true
Related 'canUse' function: canUseProxy
Note: Cannot be changed when network is started.

Property: proxyPassword

Controls password if proxy server requires authorization.

Type:                      string (s)
Network mode:              TCP server, TCP client, UDP
Condition:                 proxy is true
Related 'canUse' function: canUseProxy
Note: Cannot be changed when network is started.

Method: peerCount

Returns the number of established TCP connections.

Valid only when network is started. canUsePeerCount returns 0 if network is not started.

Network mode:              TCP server, TCP client
Related 'canUse' function: canUsePeerCount

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net peerCount

Returned value:

    uint32 1

 

Method: getPeersList

Returns the list of D-Bus node names of established TCP connections.

Valid only when network is started. canUsePeerCount returns 0 if network is not started.

Network mode:              TCP server, TCP client
Related 'canUse' function: canUsePeerCount

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net getPeersList

Returned value:

    array [
        string "1"
    ]

Connection in TCP client mode (but not in Telnet mode) can be established with several servers simultaneously with different encryption and authorisation settings provided that serial ports settings are the same.

The servers list is controlled via addServer and removeServer methods, which can be used only when canUseServerList returns 2, i.e. when network is not started.

Information about the servers list can be always received using hasServer, getServers, serverUsesAuthorisation and serverUsesEncryption methods, since canUseServerList always returns either 1 or 2.

Method: addServer

Allows adding server to the list. The following parameters are used:

  • host – string parameter specifying remote server name to connect to
  • port – uint parameter specifying remote TCP port to connect to
  • password – string parameter specifying the server’s password, if required

  • encryption – boolean parameter specifying whether data encryption is enabled (true) or disabled (false) for this connection

    Network mode: TCP client Related ‘canUse’ function: canUseServerList

     

    Note: Cannot be changed when network is started.

Returns true if server is added, false if not (e.g. if a server with the same host and port parameters is already in the list).

Example (autorisation without traffic encryption is used):

    evesec call /SEC/__tmp__virt1/net connection.net addServer \
      string:'localhost' \
      uint16:5000 \
      string:'password' \
      boolean:false

Returned value:

    boolean true

 

Method: removeServer

Removes server from the list. The following parameters are used:

  • host – string parameter specifying remote server name

  • port – uint parameter specifying remote TCP port number

    Network mode: TCP client Related ‘canUse’ function: canUseServerList

    Note: Cannot be changed when network is started.

Returns true if connection was removed, false if not.

Example:

    evesec call /SEC/__tmp__virt1/net connection.net removeServer \
      string:'google.com' \
      uint16:80

Returned value:

    boolean false

 

Method: hasServer

Indicates whether TCP server is in the list. The following parameters are used:

  • host – string parameter specifying remote server name

  • port – uint parameter specifying remote TCP port number

    Network mode: TCP client Related ‘canUse’ function: canUseServerList

    Note: Can be called even when network is started.

Returns true if server is available, false if not.

Note: ‘localhost’ and ‘127.0.0.1’ are treated as different servers.

Example:

    evesec call /SEC/__tmp__virt1/net connection.net hasServer \
      string:'localhost' \
      uint16:5000

Returned value:

    boolean true

 

Method: getServers

Returns the list of servers to connect to and settings related to them.

Network mode:              TCP client
Related 'canUse' function: canUseServerList
Note: Can be called even when network is started.

Example:

    evesec call /SEC/__tmp__virt1/net connection.net getServers

Returned value:

    array [
        struct {
            string "localhost"
            uint16 5000
            boolean true
            boolean false
        }
    ]

where the first boolean shows whether authorisation is used (true in this example). The second boolean shows whether encryption is used (false in this example).

Method: serverUsesAuthorisation

Indicates whether the remote server uses authorisation. The following parameters are used:

  • host – string parameter specifying remote server name

  • port – uint parameter specifying remote TCP port number

    Network mode: TCP client Related ‘canUse’ function: canUseServerList

    Note: Can be called even when network is started.

Returns true if authorisation is used for this connection, false if not.

Example:

    evesec call /SEC/__tmp__virt1/net connection.net serverUsesAuthorisation \
      string:'localhost' \
      uint16:5000

Returned value:

    boolean true

 

Method: serverUsesEncryption

Indicates whether the remote server uses encryption. The following parameters are used:

  • host – string parameter specifying remote server name

  • port – uint parameter specifying remote TCP port number

    Network mode: TCP client Related ‘canUse’ function: canUseServerList

    Note: Can be called even when network is started.

Returns true if encryption is used for this connection, false if not.

Example:

    evesec call /SEC/__tmp__virt1/net connection.net serverUsesEncryption \
      string:'localhost' \
      uint16:5000

Returned value:

    boolean false

 

Method: bytesRead

Returns the amount of bytes received from network.

Network mode:              UDP

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net bytesRead

Returned value:

    uint64 42

 

Method: bytesWritten

Returns the amount of bytes sent to network.

Network mode:              UDP

Example:

    evesec call /SEC/__dev__ttyS0/net connection.net bytesWritten

Returned value:

    uint64 404