Struct ipworks::DTLSServer

Properties   Methods   Events   Config Settings   Errors  

The DTLSServer struct provides server-side functionality for secure UDP communication utilizing the Datagram Transport Layer Security (DTLS) protocol.

Syntax

ipworks::DTLSServer

Remarks

The DTLSServer struct functions as a server that facilitates incoming DTLS connections and offers a convenient means of transmitting and receiving datagrams over the established, secure connections.

Getting Started

First, a valid certificate must be selected before the server can start listening for incoming connections. The certificate can be specified via the ssl_cert. Note the certificate must contain a private key.

After doing so, calling start_listening will cause the struct to start listening for incoming connections. The struct will listen on the interface defined by local_host and local_port, if specified. Otherwise, these values will be set by the struct. If applicable, these values must be set before calling start_listening. For example:

//dtlsserver.LocalHost = "some_ip_address"; //dtlsserver.LocalPort = 1234; dtlsserver.SSLCert = new Certificate("/path/to/cert.pfx", CertStoreTypes.cstPFXFile, "cert_password", "cert_subject"); dtlsserver.StartListening(); Console.WriteLine("Listening on: " + dtlsserver.LocalHost + ":" + dtlsserver.LocalPort); while (dtlsserver.Listening) { dtlsserver.DoEvents(); }

Handling Incoming Connections

Once successfully listening, the struct can now accept (or reject) incoming connections. The first indicator of an incoming connection will be through the on_connection_request event. Here, the connection's originating address and port can be queried. By default, the struct will accept all incoming connections, but this behavior can be overridden within this event.

Assuming the connection is accepted, the DTLS handshake will proceed. Relevant handshake details will be reported by the on_ssl_status event. By default, the client is not required to present a certificate to the server. To force this, the ssl_authenticate_clients property can be enabled. When enabled, the client's presented certificate will be available within the on_ssl_client_authentication event, where the server can again choose to accept (or reject) incoming connections.

Once the connection is complete (or fails), the on_connected event will fire. Note that this event will fire if a connection succeeds or fails. If successful, the event will fire with a StatusCode of 0. If this value is non-zero, it indicates the connection was unsuccessful. The Description parameter will contain relevant details.

After a successful connection, relevant connection-specific details will be available within the Connection* properties. Each connection will be assigned a unique ConnectionId, which can be acquired for a given connection within the on_connected event. For example:

dtlsserver.OnConnected += (o, e) => { if (e.StatusCode == 0) { Console.WriteLine("Successful connection from " + e.SourceAddr + ":" + e.SourcePort); Console.WriteLine("ConnectionId: " + e.ConnectionId); } else { Console.WriteLine("Connection failed from " + e.SourceAddr + ":" + e.SourcePort); Console.WriteLine("Error code: " + e.StatusCode); Console.WriteLine("Error description: " + e.Description); } }; dtlsserver.OnSSLClientAuthentication += (o, e) => { if (e.Accept) return; Console.Write("Client provided the following certificate:\nIssuer: " + e.CertIssuer + "\nSubject: " + e.CertSubject + "\n"); Console.Write("The following problems have been determined for this certificate: " + e.Status + "\n"); Console.Write("Would you like to accept anyways? [y/n] "); if (Console.Read() == 'y') e.Accept = true; }; dtlsserver.SSLCert = new Certificate("/path/to/cert.pfx", CertStoreTypes.cstPFXFile, "cert_password", "cert_subject"); dtlsserver.SSLAuthenticateClients = true; dtlsserver.StartListening(); Console.WriteLine("Listening on: " + dtlsserver.LocalHost + ":" + dtlsserver.LocalPort); while (dtlsserver.Listening) { dtlsserver.DoEvents(); }

Sending and Receiving Data

The struct can send data to individual connections, specified by the ConnectionId parameter, via the send_bytes and send_text methods.

While a connection is active, incoming data from a connection will be available within the on_data_in event. Note that this event is non-reentrant, and it is recommended to offload time-consuming operations to ensure the best performance.

If required, the pause_data method can be called, disabling the reception of incoming data from a particular connection. Data reception can later be enabled via the process_data method. Note that if this reception is disabled for a connection, the connection may continue sending data, which will remain unprocessed by the struct. In this case, the underlying socket buffer may be filled. This can result in possible data loss originating from this connection. Please use these methods with caution.

The complete process may look like the following:

dtlsserver.OnDataIn += (o, e) => { Console.WriteLine("Packet received from: " + e.ConnectionId); Console.WriteLine("Packet: " + e.Datagram); }; dtlsserver.SSLCert = new Certificate("/path/to/cert.pfx", CertStoreTypes.cstPFXFile, "cert_password", "cert_subject"); dtlsserver.StartListening(); Console.WriteLine("Listening on: " + dtlsserver.LocalHost + ":" + dtlsserver.LocalPort); ... ... ... // Broadcast data foreach (DTLSConnection c in dtlsserver.Connections.Values) { dtlsserver.SendText(c.ConnectionId, "Hello world!"); }

Removing Connections

To remove a connection, disconnect must be called with the corresponding ConnectionId. In order to remove inactive connections, the default_idle_timeout property can be set accordingly. By default, this property is set to 0, and idle connections are not removed automatically. When this property is set to a positive value, this will automatically remove connections that are idle for a specified amount of time.

NOTE: For default_idle_timeout to work as intended, do_events must be called frequently in both console and form-based applications (e.g., using a loop or timer).

Finally, once a connection ends, on_disconnected will fire. In the case a connection ends and an error is encountered, the StatusCode and Description parameters will contain relevant details regarding the error. The connection will be removed from the Connection* properties. For example:

dtlsserver.OnDisconnected += (o, e) => { if (e.StatusCode == 0) { Console.WriteLine("Connection removed: " + e.ConnectionId); } else { Console.WriteLine("Connection removed: " + e.ConnectionId); Console.WriteLine("Error code: " + e.StatusCode); Console.WriteLine("Error description: " + e.Description); } }; dtlsserver.DefaultIdleTimeout = 60; // Remove connections inactive for 60 seconds dtlsserver.StartListening(); Console.WriteLine("Listening on: " + dtlsserver.LocalHost + ":" + dtlsserver.LocalPort); while (dtlsserver.Listening) { dtlsserver.DoEvents(); }

Additional Information

To support default_idle_timeout and keep_alive functionality, it is important to note that do_events must be called regularly in both console and form-based applications.

For default_idle_timeout, do_events must be called frequently to ensure that idle connections are handled and removed in a timely manner. For keep_alive, do_events must be called frequently to ensure the struct sends keep-alive (or Heartbeat) packets to existing connections in a timely manner.

In form-based applications, this does not apply if default_idle_timeout is set to 0 and keep_alive is False.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorks. Due to this, the DTLSServer struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of DTLSServer when you have finished using the instance.

Property List

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

connection_count property (DTLSServer Struct)

The number of records in the Connection arrays.

Syntax

fn connection_count(&self ) -> Result<i32, IPWorksError> 
fn set_connection_count(&self, value : i32) ->  Option<IPWorksError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• connection_id
• connection_local_host
• connection_local_port
• connection_remote_host
• connection_remote_port

The array indices start at 0 and end at connection_count - 1.

Data Type

i32

connection_id property (DTLSServer Struct)

This property contains an identifier generated by the struct to identify each connection.

Syntax

fn connection_id(&self , ConnectionId : i32) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

This property contains an identifier generated by the struct to identify each connection. This identifier is unique to this connection.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the ConnectionCount property.

This property is read-only.

Data Type

i32

connection_local_host property (DTLSServer Struct)

This property indicates the name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

fn connection_local_host(&self , ConnectionId : i32) -> Result<String, IPWorksError> 

Default Value

""

Remarks

This property indicates the name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the ConnectionCount property.

This property is read-only.

Data Type

String

connection_local_port property (DTLSServer Struct)

This property indicates the UDP port on the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

fn connection_local_port(&self , ConnectionId : i32) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

This property indicates the UDP port on the local host or user-assigned IP interface through which connections are initiated or accepted.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the ConnectionCount property.

This property is read-only.

Data Type

i32

connection_remote_host property (DTLSServer Struct)

This property indicates the IP address of the remote host through which the connection is coming.

Syntax

fn connection_remote_host(&self , ConnectionId : i32) -> Result<String, IPWorksError> 

Default Value

""

Remarks

This property indicates the IP address of the remote host through which the connection is coming.

The connection must be valid or an error will be fired.

If the struct is configured to use a SOCKS firewall, the value assigned to this property may be preceded with an "*". If this is the case, the host name is passed to the firewall unresolved and the firewall performs the DNS resolution.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the ConnectionCount property.

This property is read-only.

Data Type

String

connection_remote_port property (DTLSServer Struct)

This property indicates the UDP port on the remote host through which the connection is coming.

Syntax

fn connection_remote_port(&self , ConnectionId : i32) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

This property indicates the UDP port on the remote host through which the connection is coming.

The connection must be valid or an error will be fired.

The ConnectionId parameter specifies the index of the item in the array. The size of the array is controlled by the ConnectionCount property.

This property is read-only.

Data Type

i32

default_idle_timeout property (DTLSServer Struct)

This property includes the default idle timeout for inactive clients.

Syntax

fn default_idle_timeout(&self ) -> Result<i32, IPWorksError> 
fn set_default_idle_timeout(&self, value : i32) ->  Option<IPWorksError> 

Default Value

0

Remarks

This property specifies the idle timeout (in seconds) for clients. When set to a positive value, the struct will disconnect idle clients after the specified timeout.

This applies only to clients that have not sent or received data within default_idle_timeout seconds.

If set to 0 (default), no idle timeout is applied.

NOTE: do_events must be called for the struct to check existing connections.

Data Type

i32

keep_alive property (DTLSServer Struct)

When True, keep-alive functionality is enabled via the DTLS Heartbeat Extension.

Syntax

fn keep_alive(&self ) -> Result<bool, IPWorksError> 
fn set_keep_alive(&self, value : bool) ->  Option<IPWorksError> 

Default Value

false

Remarks

This property enables keep-alive functionality for established connections via the DTLS Heartbeat Extension (RFC 6520). Enabling this option can prevent long connections from timing out in case of inactivity.

NOTE: For this functionality to work as intended, do_events must be called frequently in both console and form-based applications (e.g., using a loop or timer).

Additionally, DTLS server implementations are not required to support Heartbeats.

Data Type

bool

listening property (DTLSServer Struct)

This property indicates whether the struct is listening for incoming connections on LocalPort.

Syntax

fn listening(&self ) -> Result<bool, IPWorksError> 

Default Value

false

Remarks

This property indicates whether the struct is listening for connections on the port specified by the local_port property. Use the start_listening and stop_listening methods to control whether the struct is listening.

This property is read-only.

Data Type

bool

local_host property (DTLSServer Struct)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

fn local_host(&self ) -> Result<String, IPWorksError> 
fn set_local_host(&self, value : &str) ->  Option<IPWorksError> 
fn set_local_host_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

This property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the struct initiate connections (or accept in the case of server structs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the struct is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: local_host is not persistent. You must always set it in code, and never in the property window.

Data Type

String

local_port property (DTLSServer Struct)

This property includes the User Datagram Protocol (UDP) port in the local host where the struct listens.

Syntax

fn local_port(&self ) -> Result<i32, IPWorksError> 
fn set_local_port(&self, value : i32) ->  Option<IPWorksError> 

Default Value

0

Remarks

This property must be set before the struct can start listening. If its value is 0, then the TCP/IP subsystem picks a port number at random. The port number can be found by checking the value of this property after the struct is listening (i.e., after successfully calling the start_listening method).

The service port is not shared among servers so two structs cannot be listening on the same port at the same time.

Data Type

i32

ssl_authenticate_clients property (DTLSServer Struct)

If set to True, the server asks the client(s) for a certificate.

Syntax

fn ssl_authenticate_clients(&self ) -> Result<bool, IPWorksError> 
fn set_ssl_authenticate_clients(&self, value : bool) ->  Option<IPWorksError> 

Default Value

false

Remarks

This property is used in conjunction with the on_ssl_client_authentication event. Please refer to the documentation of the on_ssl_client_authentication event for details.

Data Type

bool

ssl_cert_effective_date property (DTLSServer Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_cert_effective_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_expiration_date property (DTLSServer Struct)

The date on which the certificate expires.

Syntax

fn ssl_cert_expiration_date(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_extended_key_usage property (DTLSServer Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_cert_extended_key_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_cert_fingerprint property (DTLSServer Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha1 property (DTLSServer Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha256 property (DTLSServer Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_cert_issuer property (DTLSServer Struct)

The issuer of the certificate.

Syntax

fn ssl_cert_issuer(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_cert_private_key property (DTLSServer Struct)

The private key of the certificate (if available).

Syntax

fn ssl_cert_private_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_cert_private_key_available property (DTLSServer Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_cert_private_key_available(&self ) -> Result<bool, IPWorksError> 

Default Value

false

Remarks

Whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_cert_private_key_container property (DTLSServer Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_cert_private_key_container(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_cert_public_key property (DTLSServer Struct)

The public key of the certificate.

Syntax

fn ssl_cert_public_key(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_cert_public_key_algorithm property (DTLSServer Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_cert_public_key_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_public_key_length property (DTLSServer Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_cert_public_key_length(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_cert_serial_number property (DTLSServer Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_cert_serial_number(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_cert_signature_algorithm property (DTLSServer Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_cert_signature_algorithm(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_store property (DTLSServer Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_cert_store(&self ) -> Result<Vec<u8>, IPWorksError> 
fn set_ssl_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksError> 
fn set_ssl_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_cert_store_password property (DTLSServer Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_cert_store_password(&self ) -> Result<String, IPWorksError> 
fn set_ssl_cert_store_password(&self, value : &str) ->  Option<IPWorksError> 
fn set_ssl_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_cert_store_type property (DTLSServer Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_cert_store_type(&self ) -> Result<i32, IPWorksError> 
fn set_ssl_cert_store_type(&self, value : i32) ->  Option<IPWorksError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_cert_subject_alt_names property (DTLSServer Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_cert_subject_alt_names(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_md5 property (DTLSServer Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_md5(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha1 property (DTLSServer Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha256 property (DTLSServer Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_usage property (DTLSServer Struct)

The text description of UsageFlags .

Syntax

fn ssl_cert_usage(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_cert_usage_flags property (DTLSServer Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_cert_usage_flags(&self ) -> Result<i32, IPWorksError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_cert_version property (DTLSServer Struct)

The certificate's version number.

Syntax

fn ssl_cert_version(&self ) -> Result<String, IPWorksError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_cert_subject property (DTLSServer Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_cert_subject(&self ) -> Result<String, IPWorksError> 
fn set_ssl_cert_subject(&self, value : &str) ->  Option<IPWorksError> 
fn set_ssl_cert_subject_ref(&self, value : &String) ->  Option<IPWorksError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_cert_encoded property (DTLSServer Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksError> 
fn set_ssl_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksError> 
fn set_ssl_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

Data Type

Vec

config method (DTLSServer Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

disconnect method (DTLSServer Struct)

This method disconnects the specified client.

Syntax

fn disconnect(&self, connection_id : i32) -> Result<(), IPWorksError>

Remarks

Calling this method will disconnect the client specified by the connection_id parameter.

do_events method (DTLSServer Struct)

This method processes events from the internal message queue.

Syntax

fn do_events(&self) -> Result<(), IPWorksError>

Remarks

When do_events is called, the struct processes any available events. If no events are available, it waits for a preset period of time, and then returns.

pause_data method (DTLSServer Struct)

This method pauses data reception.

Syntax

fn pause_data(&self, connection_id : i32) -> Result<(), IPWorksError>

Remarks

This method pauses data reception for the connection identified by connection_id when called. While data reception is paused, the on_data_in event will not fire for the specified connection. Call process_data to reenable data reception.

process_data method (DTLSServer Struct)

This method reenables data reception after a call to PauseData .

Syntax

fn process_data(&self, connection_id : i32) -> Result<(), IPWorksError>

Remarks

This method reenables data reception for the connection identified by connection_id after a previous call to pause_data. When pause_data is called, the on_data_in event will not fire for the specified connection. To reenable data reception and allow on_data_in to fire, call this method.

NOTE: This method is used only after previously calling pause_data. It does not need to be called to process incoming data by default.

reset method (DTLSServer Struct)

This method will reset the struct.

Syntax

fn reset(&self) -> Result<(), IPWorksError>

Remarks

This method will reset the struct's properties to their default values.

send_bytes method (DTLSServer Struct)

This method sends binary data to the specified client.

Syntax

fn send_bytes(&self, connection_id : i32, data : &[u8]) -> Result<(), IPWorksError>

Remarks

This method sends binary data to the client identified by connection_id. For example:

byte[] dataToSend = new byte[] { 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33 }; foreach (DTLSConnection c in dtlsserver.Connections.Values) { dtlsserver.SendBytes(c.ConnectionId, dataToSend); }

To send text, use the send_text method instead.

send_text method (DTLSServer Struct)

This method sends text to the specified client.

Syntax

fn send_text(&self, connection_id : i32, text : &str) -> Result<(), IPWorksError>

Remarks

This method sends text to the client identified by connection_id. For example:

string dataToSend = "Hello world!"; foreach (DTLSConnection c in dtlsserver.Connections.Values) { dtlsserver.SendText(c.ConnectionId, dataToSend); }

To send binary data, use the send_bytes method instead.

shutdown method (DTLSServer Struct)

This method shuts down the server.

Syntax

fn shutdown(&self) -> Result<(), IPWorksError>

Remarks

This method shuts down the server. Calling this method is equivalent to calling stop_listening and then breaking every client connection by calling disconnect.

start_listening method (DTLSServer Struct)

This method starts listening for incoming connections.

Syntax

fn start_listening(&self) -> Result<(), IPWorksError>

Remarks

This method begins listening for incoming connections on the port specified by local_port. Once listening, events will fire as new clients connect and data are transferred.

To stop listening for new connections, call stop_listening. To stop listening for new connections and to disconnect all existing clients, call shutdown.

stop_listening method (DTLSServer Struct)

This method stops listening for new connections.

Syntax

fn stop_listening(&self) -> Result<(), IPWorksError>

Remarks

This method stops listening for new connections. After being called, any new connection attempts will be rejected. Calling this method does not disconnect existing connections.

To stop listening and to disconnect all existing clients, call shutdown instead.

on_connected event (DTLSServer Struct)

This event is fired immediately after a connection completes (or fails).

Syntax

// DTLSServerConnectedEventArgs carries the DTLSServer Connected event's parameters.
pub struct DTLSServerConnectedEventArgs {
  fn connection_id(&self) -> i32
  fn source_addr(&self) -> &String
  fn source_port(&self) -> i32
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// DTLSServerConnectedEvent defines the signature of the DTLSServer Connected event's handler function.
pub trait DTLSServerConnectedEvent {
  fn on_connected(&self, sender : DTLSServer, e : &mut DTLSServerConnectedEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_connected(&self) -> &'a dyn DTLSServerConnectedEvent;
  pub fn set_on_connected(&mut self, value : &'a dyn DTLSServerConnectedEvent);
  ...
}

Remarks

This event is fired immediately after a connection completes (or fails). The connection_id parameter indicates the unique ID assigned to this connection.

source_addr contains the IP number (Internet address) of the remote party, and source_port contains the port from which the packet originated.

If the connection is made normally, status_code is 0 and description is "OK".

If the connection fails, status_code has the error code returned by the system. description contains a description of this code. The value of status_code is equal to the value of the system error.

Please refer to the Error Codes section for more information.

on_connection_request event (DTLSServer Struct)

This event is fired when a request for connection comes from a remote host.

Syntax

// DTLSServerConnectionRequestEventArgs carries the DTLSServer ConnectionRequest event's parameters.
pub struct DTLSServerConnectionRequestEventArgs {
  fn address(&self) -> &String
  fn port(&self) -> i32
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// DTLSServerConnectionRequestEvent defines the signature of the DTLSServer ConnectionRequest event's handler function.
pub trait DTLSServerConnectionRequestEvent {
  fn on_connection_request(&self, sender : DTLSServer, e : &mut DTLSServerConnectionRequestEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_connection_request(&self) -> &'a dyn DTLSServerConnectionRequestEvent;
  pub fn set_on_connection_request(&mut self, value : &'a dyn DTLSServerConnectionRequestEvent);
  ...
}

Remarks

This event indicates an incoming connection. The connection is accepted by default. address and port will contain information about the remote host requesting the inbound connection. If you want to refuse it, you can set the accept parameter to False.

on_data_in event (DTLSServer Struct)

This event is fired when data is received.

Syntax

// DTLSServerDataInEventArgs carries the DTLSServer DataIn event's parameters.
pub struct DTLSServerDataInEventArgs {
  fn connection_id(&self) -> i32
  fn datagram(&self) -> &[u8]
}

// DTLSServerDataInEvent defines the signature of the DTLSServer DataIn event's handler function.
pub trait DTLSServerDataInEvent {
  fn on_data_in(&self, sender : DTLSServer, e : &mut DTLSServerDataInEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_data_in(&self) -> &'a dyn DTLSServerDataInEvent;
  pub fn set_on_data_in(&mut self, value : &'a dyn DTLSServerDataInEvent);
  ...
}

Remarks

The on_data_in event is fired every time a new datagram is received.

connection_id indicates the unique Id of the DTLSConnection from which the packet originated.

datagram contains the packet as sent by the remote host.

NOTE: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

on_disconnected event (DTLSServer Struct)

This event is fired when a connection is closed.

Syntax

// DTLSServerDisconnectedEventArgs carries the DTLSServer Disconnected event's parameters.
pub struct DTLSServerDisconnectedEventArgs {
  fn connection_id(&self) -> i32
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// DTLSServerDisconnectedEvent defines the signature of the DTLSServer Disconnected event's handler function.
pub trait DTLSServerDisconnectedEvent {
  fn on_disconnected(&self, sender : DTLSServer, e : &mut DTLSServerDisconnectedEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_disconnected(&self) -> &'a dyn DTLSServerDisconnectedEvent;
  pub fn set_on_disconnected(&mut self, value : &'a dyn DTLSServerDisconnectedEvent);
  ...
}

Remarks

If the connection is broken normally, status_code is 0, and description is "OK".

If the connection is broken for any other reason, status_code has the error code returned by the system. description contains a description of this code. The value of status_code is equal to the value of the system error.

Please refer to the Error Codes section for more information.

on_error event (DTLSServer Struct)

This event fires information about errors during data delivery.

Syntax

// DTLSServerErrorEventArgs carries the DTLSServer Error event's parameters.
pub struct DTLSServerErrorEventArgs {
  fn connection_id(&self) -> i32
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// DTLSServerErrorEvent defines the signature of the DTLSServer Error event's handler function.
pub trait DTLSServerErrorEvent {
  fn on_error(&self, sender : DTLSServer, e : &mut DTLSServerErrorEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_error(&self) -> &'a dyn DTLSServerErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn DTLSServerErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally, the struct fails with an error.

error_code contains an error code and description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

connection_id indicates the connection for which the error is applicable.

on_log event (DTLSServer Struct)

This event fires once for each log message.

Syntax

// DTLSServerLogEventArgs carries the DTLSServer Log event's parameters.
pub struct DTLSServerLogEventArgs {
  fn connection_id(&self) -> i32
  fn log_level(&self) -> i32
  fn message(&self) -> &String
  fn log_type(&self) -> &String
}

// DTLSServerLogEvent defines the signature of the DTLSServer Log event's handler function.
pub trait DTLSServerLogEvent {
  fn on_log(&self, sender : DTLSServer, e : &mut DTLSServerLogEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_log(&self) -> &'a dyn DTLSServerLogEvent;
  pub fn set_on_log(&mut self, value : &'a dyn DTLSServerLogEvent);
  ...
}

Remarks

This event fires once for each log message generated by the struct. The verbosity is controlled by the LogLevel setting.

connection_id identifies the connection to which the log message applies.

log_level indicates the detail level of the message. Possible values are as follows:

message is the log entry.

log_type identifies the type of log entry. Possible values are as follows:

• "Info"
• "Error"
• "Verbose"
• "Debug"

on_ssl_client_authentication event (DTLSServer Struct)

This event is fired when the client presents its credentials to the server.

Syntax

// DTLSServerSSLClientAuthenticationEventArgs carries the DTLSServer SSLClientAuthentication event's parameters.
pub struct DTLSServerSSLClientAuthenticationEventArgs {
  fn connection_id(&self) -> i32
  fn cert_encoded(&self) -> &[u8]
  fn cert_subject(&self) -> &String
  fn cert_issuer(&self) -> &String
  fn status(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// DTLSServerSSLClientAuthenticationEvent defines the signature of the DTLSServer SSLClientAuthentication event's handler function.
pub trait DTLSServerSSLClientAuthenticationEvent {
  fn on_ssl_client_authentication(&self, sender : DTLSServer, e : &mut DTLSServerSSLClientAuthenticationEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_ssl_client_authentication(&self) -> &'a dyn DTLSServerSSLClientAuthenticationEvent;
  pub fn set_on_ssl_client_authentication(&mut self, value : &'a dyn DTLSServerSSLClientAuthenticationEvent);
  ...
}

Remarks

This event enables the server to decide whether or not to continue. The accept parameter is a recommendation on whether to continue or to close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When accept is False, status shows why the verification failed (otherwise, status contains the string "OK").

on_ssl_status event (DTLSServer Struct)

This event is fired to show the progress of the secure connection.

Syntax

// DTLSServerSSLStatusEventArgs carries the DTLSServer SSLStatus event's parameters.
pub struct DTLSServerSSLStatusEventArgs {
  fn connection_id(&self) -> i32
  fn message(&self) -> &String
}

// DTLSServerSSLStatusEvent defines the signature of the DTLSServer SSLStatus event's handler function.
pub trait DTLSServerSSLStatusEvent {
  fn on_ssl_status(&self, sender : DTLSServer, e : &mut DTLSServerSSLStatusEventArgs);
}

impl <'a> DTLSServer<'a> {
  pub fn on_ssl_status(&self) -> &'a dyn DTLSServerSSLStatusEvent;
  pub fn set_on_ssl_status(&mut self, value : &'a dyn DTLSServerSSLStatusEvent);
  ...
}

Remarks

The event is fired for informational and logging purposes only. It is used to track the progress of the connection.

Config Settings (DTLSServer Struct)

DTLSServer Config Settings

UDP Config Settings

Socket Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Base Config Settings

Trappable Errors (DTLSServer Struct)

DTLSServer Errors