RADIUS Component

Properties   Methods   Events   Config Settings   Errors  

The RADIUS component provides an easy way to authenticate users.

Syntax

nsoftware.IPWorksAuth.Radius

Remarks

The RADIUS component implements support for Remote Authentication Dial In User Service (RADIUS).

Authentication

The component can be used to authenticate users with a RADIUS server. To begin set the following properties:

• RemoteHost
• RemotePort (optional)
• User
• Password
• SharedSecret

The AuthMechanism property may be set to specify the authentication mechanism used.

Property List

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

Method List

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

Event List

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

Config Settings

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

Attributes Property (RADIUS Component)

The attributes of the request or response.

Syntax

• C#
• VB.NET

public RADIUSAttributeList Attributes { get; }

Public Property Attributes As RADIUSAttributeList

Remarks

This property holds a collection of attributes associated with the request or response. To include attributes in a request populate this collection before calling Authenticate. After Authenticate returns this collection will be populated with the attributes from the response.

This property is not available at design time.

AuthMechanism Property (RADIUS Component)

The authentication mechanism to be used when connecting to the RADIUS server.

Syntax

• C#
• VB.NET

public RadiusAuthMechanisms AuthMechanism { get; set; }

enum RadiusAuthMechanisms {
  ramMSCHAPv2,
  ramPAP,
  ramPEAPv0,
  ramEAPTLS
}

Public Property AuthMechanism As RadiusAuthMechanisms

Enum RadiusAuthMechanisms
  ramMSCHAPv2
  ramPAP
  ramPEAPv0
  ramEAPTLS
End Enum

Default Value

0

Remarks

This property defines the authentication mechanism used when connecting to the RADIUS server. Possible values are:

When set to ramEAPTLS the SSLCert property must be set to the client certificate used to authenticate to the server.

EAPAnonymousIdentity Property (RADIUS Component)

The identity to use when using PEAP or EAP-TLS.

Syntax

• C#
• VB.NET

public string EAPAnonymousIdentity { get; set; }

Public Property EAPAnonymousIdentity As String

Default Value

"anonymous"

Remarks

This property specifies the initital identity to use when establishing a secure connection using PEAP. When AuthMechanism is set to amPEAPv0 or emEAPTLS the connection begins in plaintext. This property specifies the user name (if any) that is sent in the initial plaintext request. This allows the true identity of the user to be hidden.

If set, the value will be sent in the plaintext connection request. If not set (empty string) the User will be sent. Authentication servers may make use of a value that includes the domain to which the user will authenticate, such as anonymous@example.com. In that case the user's identity is still hidden, however the authentication server will have knowledge of the domain for the user which it may make use of.

Once a secure connection is established the user's true identity is sent to the authentication server over the TLS encrypted connection. This property specifies only the identity sent in the initial plaintext request.

The default value is anonymous.

This setting is only applicable when AuthMechanism is set to amPEAPv0 or amEAPTLS.

LocalHost Property (RADIUS Component)

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

Syntax

• C#
• VB.NET

public string LocalHost { get; set; }

Public Property LocalHost As String

Default Value

""

Remarks

The LocalHost 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 multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the component initiate connections (or accept in the case of server components) only through that interface.

If the component is connected, the LocalHost 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 multi-homed hosts (machines with more than one IP interface).

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

LocalPort Property (RADIUS Component)

The UDP port in the local host where UDP binds.

Syntax

• C#
• VB.NET

public int LocalPort { get; set; }

Public Property LocalPort As Integer

Default Value

0

Remarks

The LocalPort property must be set before UDP is activated (Active is set to True). It instructs the component to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the TCP/IP stack to choose a port at random. The chosen port will be shown by the LocalPort property after the connection is established.

LocalPort cannot be changed once the component is Active. Any attempt to set the LocalPort property when the component is Active will generate an error.

The LocalPort property is useful when trying to connect to services that require a trusted port in the client side.

Password Property (RADIUS Component)

The user's password.

Syntax

• C#
• VB.NET

public string Password { get; set; }

Public Property Password As String

Default Value

""

Remarks

This property specifies the password for the User. This must be set before calling Authenticate.

RemoteHost Property (RADIUS Component)

The address of the remote host. Domain names are resolved to IP addresses.

Syntax

• C#
• VB.NET

public string RemoteHost { get; set; }

Public Property RemoteHost As String

Default Value

""

Remarks

The RemoteHost property specifies the IP address (IP number in dotted internet format) or Domain Name of the remote host.

If RemoteHost is set to 255.255.255.255, the component broadcasts data on the local subnet.

If the RemoteHost property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the RemoteHost property is set to the corresponding address. If the search is not successful, an error is returned.

If UseConnection is set to True, the RemoteHost must be set before the component is activated (Active is set to True).

RemotePort Property (RADIUS Component)

The port for the RADIUS server (default is 1812).

Syntax

• C#
• VB.NET

public int RemotePort { get; set; }

Public Property RemotePort As Integer

Default Value

1812

Remarks

The RemotePort is the UDP port to which requests will be made. The default value is 1812. Port 1645 is also commonly used.

SharedSecret Property (RADIUS Component)

The RADIUS shared secret.

Syntax

• C#
• VB.NET

public string SharedSecret { get; set; }
public byte[] SharedSecretB { get; set; }

Public Property SharedSecret As String
Public Property SharedSecretB As Byte()

Default Value

""

Remarks

This property holds the shared secret to use when communicating with the RADIUS server.

SSLCert Property (RADIUS Component)

The certificate to be used during SSL negotiation.

Syntax

• C#
• VB.NET

public Certificate SSLCert { get; set; }

Public Property SSLCert As Certificate

Remarks

The digital certificate that the component will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Timeout Property (RADIUS Component)

A timeout for the component.

Syntax

• C#
• VB.NET

public int Timeout { get; set; }

Public Property Timeout As Integer

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the component will wait for the operation to complete before returning control.

The component will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the component throws an exception.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

User Property (RADIUS Component)

The name of the user to authenticate.

Syntax

• C#
• VB.NET

public string User { get; set; }

Public Property User As String

Default Value

""

Remarks

This property holds the name of the user to authenticate.

Authenticate Method (RADIUS Component)

Authenticates the user.

Syntax

• C#
• VB.NET

public void Authenticate();

Async Version
public async Task Authenticate();
public async Task Authenticate(CancellationToken cancellationToken);

Public Sub Authenticate()

Async Version
Public Sub Authenticate() As Task
Public Sub Authenticate(cancellationToken As CancellationToken) As Task

Remarks

This method authenticates the user with the RADIUS server.

If authentication is successful this method returns without error. If authentication fails this method will throw an exception.

This following properties are applicable when calling this method:

• User (required)
• Password (required)
• SharedSecret (required)
• RemoteHost (required)
• RemotePort
• Timeout

Config Method (RADIUS Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.

DoEvents Method (RADIUS Component)

Processes events from the internal message queue.

Syntax

• C#
• VB.NET

public void DoEvents();

Async Version
public async Task DoEvents();
public async Task DoEvents(CancellationToken cancellationToken);

Public Sub DoEvents()

Async Version
Public Sub DoEvents() As Task
Public Sub DoEvents(cancellationToken As CancellationToken) As Task

Remarks

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

Interrupt Method (RADIUS Component)

Interrupt the current method.

Syntax

• C#
• VB.NET

public void Interrupt();

Async Version
public async Task Interrupt();
public async Task Interrupt(CancellationToken cancellationToken);

Public Sub Interrupt()

Async Version
Public Sub Interrupt() As Task
Public Sub Interrupt(cancellationToken As CancellationToken) As Task

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

Reset Method (RADIUS Component)

Resets the component properties to their default values.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method resets the properties to their default values.

Attribute Event (RADIUS Component)

Fires for each attribute that is received.

Syntax

• C#
• VB.NET

public event OnAttributeHandler OnAttribute;

public delegate void OnAttributeHandler(object sender, RadiusAttributeEventArgs e);

public class RadiusAttributeEventArgs : EventArgs {
  public int AttributeType { get; }
  public string Name { get; }
  public string Value { get; }
  public byte[] ValueB { get; }
}

Public Event OnAttribute As OnAttributeHandler

Public Delegate Sub OnAttributeHandler(sender As Object, e As RadiusAttributeEventArgs)

Public Class RadiusAttributeEventArgs Inherits EventArgs
  Public ReadOnly Property AttributeType As Integer
  Public ReadOnly Property Name As String
  Public ReadOnly Property Value As String
  Public ReadOnly Property ValueB As Byte()
End Class

Remarks

This event fires once for each attribute that is received. This will fire when calling Authenticate.

AttributeType is the attribute type. Common values are:

Name is the text description of the attribute.

Value is the value of the attribute.

Error Event (RADIUS Component)

Information about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, RadiusErrorEventArgs e);

public class RadiusErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As RadiusErrorEventArgs)

Public Class RadiusErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

ErrorCode 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.

Log Event (RADIUS Component)

Fires with log information during processing.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, RadiusLogEventArgs e);

public class RadiusLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As RadiusLogEventArgs)

Public Class RadiusLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event fires during processing with log information. The level of detail that is logged is controlled via the LogLevel.

LogLevel indicates the level of message. Possible values are:

LogMessage is the log entry.

LogType indicates the type of log. Possible values are:

• "REQUEST"
• "RESPONSE"

SSLServerAuthentication Event (RADIUS Component)

Fired after the server presents its certificate to the client.

Syntax

• C#
• VB.NET

public event OnSSLServerAuthenticationHandler OnSSLServerAuthentication;

public delegate void OnSSLServerAuthenticationHandler(object sender, RadiusSSLServerAuthenticationEventArgs e);

public class RadiusSSLServerAuthenticationEventArgs : EventArgs {
  public string CertEncoded { get; }
  public byte[] CertEncodedB { get; }
  public string CertSubject { get; }
  public string CertIssuer { get; }
  public string Status { get; }
  public bool Accept { get; set; }
}

Public Event OnSSLServerAuthentication As OnSSLServerAuthenticationHandler

Public Delegate Sub OnSSLServerAuthenticationHandler(sender As Object, e As RadiusSSLServerAuthenticationEventArgs)

Public Class RadiusSSLServerAuthenticationEventArgs Inherits EventArgs
  Public ReadOnly Property CertEncoded As String
  Public ReadOnly Property CertEncodedB As Byte()
  Public ReadOnly Property CertSubject As String
  Public ReadOnly Property CertIssuer As String
  Public ReadOnly Property Status As String
  Public Property Accept As Boolean
End Class

Remarks

This event is where the client can decide whether to continue with the connection process or not. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether to continue or not.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string "OK"). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (RADIUS Component)

Shows the progress of the secure connection.

Syntax

• C#
• VB.NET

public event OnSSLStatusHandler OnSSLStatus;

public delegate void OnSSLStatusHandler(object sender, RadiusSSLStatusEventArgs e);

public class RadiusSSLStatusEventArgs : EventArgs {
  public string Message { get; }
}

Public Event OnSSLStatus As OnSSLStatusHandler

Public Delegate Sub OnSSLStatusHandler(sender As Object, e As RadiusSSLStatusEventArgs)

Public Class RadiusSSLStatusEventArgs Inherits EventArgs
  Public ReadOnly Property Message As String
End Class

Remarks

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

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

Opens CertificateFile and reads out the contents as an X509 public key.

• C#
• VB.NET

public Certificate(byte[] certificateData);

Public Certificate(ByVal CertificateData As Byte())

Parses CertificateData as an X509 public key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

RADIUSAttribute Type

This type holds details of the RADIUS attribute.

Remarks

This type holds details of the RADIUS attribute such as type and value.

Fields

Constructors

• C#
• VB.NET

public RADIUSAttribute();

Public RADIUSAttribute()

• C#
• VB.NET

public RADIUSAttribute(int attributeType);

Public RADIUSAttribute(ByVal AttributeType As Integer)

• C#
• VB.NET

public RADIUSAttribute(int attributeType, byte[] value);

Public RADIUSAttribute(ByVal AttributeType As Integer, ByVal Value As Byte())

Config Settings (RADIUS Component)

RADIUS Config Settings

UDP Config Settings

Socket Config Settings

Base Config Settings

Trappable Errors (RADIUS Component)

RADIUS Errors

UDP Errors

TCP/IP Errors