Struct ipworksauth::Kerberos

Properties   Methods   Events   Config Settings   Errors  

The Kerberos struct can be used to authenticate users using Kerberos 5.0.

Syntax

ipworksauth::Kerberos

Remarks

The Kerberos struct implements the Kerberos protocol defined in RFC 1510 and RFC 4120. The struct provides a simple interface to easily authenticate users.

Authentication

When authenticate is called the struct will attempt to authenticate the user with the Key Distribution Center (KDC). The struct will communicate with the kdc_host to obtain a service ticket and populate auth_token. The following properties are required when calling this method:

• spn (required)
• user (required)
• password (required)
• kdc_host (required)

A typical sequence of messages would be:

• KRB_AS_REQ -> KDC
• KRB_AS_REP <- KDC
• KRB_TGS_REQ -> KDC
• KRB_TGS_REP <- KDC
• auth_token is populated with the constructed KRB_AP_REP message.

Communication with the kdc_host can be seen through the on_pi_trail event.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksAuth. Due to this, the Kerberos struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of Kerberos 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.

auth_token property (Kerberos Struct)

The authentication token.

Syntax

fn auth_token(&self ) -> Result<Vec<u8>, IPWorksAuthError> 

Default Value

""

Remarks

This property holds the authentication token.

This property will be populated after calling authenticate. This may be used in by another entity to authenticate to the service. For instance this may be used in HTTP to authenticate to a web service.

The content of this property is a KRB_AP_REQ message. This is sometimes referred to as an "Authentication Header". It is comprised of the service ticket that was obtained from the TGS and an encrypted authenticator.

This property is read-only.

Data Type

Vec

kdc_host property (Kerberos Struct)

The domain name or IP address of the Key Distribution Center (KDC).

Syntax

fn kdc_host(&self ) -> Result<String, IPWorksAuthError> 
fn set_kdc_host(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_kdc_host_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property specifies the IP address (IP number in dotted internet format) or Domain Name of the Key Distribution Center (KDC).

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

Data Type

String

kdc_port property (Kerberos Struct)

The port for the Key Distribution Center (KDC).

Syntax

fn kdc_port(&self ) -> Result<i32, IPWorksAuthError> 
fn set_kdc_port(&self, value : i32) ->  Option<IPWorksAuthError> 

Default Value

88

Remarks

This property specifies the port for the Key Distribution Center (KDC). The default value is 88.

Data Type

i32

keytab_file property (Kerberos Struct)

The Kerberos Keytab file.

Syntax

fn keytab_file(&self ) -> Result<String, IPWorksAuthError> 
fn set_keytab_file(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_keytab_file_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property specifies the path to a Kerberos Keytab file. If specified, the credentials are read from this file.

Data Type

String

password property (Kerberos Struct)

The user's password.

Syntax

fn password(&self ) -> Result<String, IPWorksAuthError> 
fn set_password(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_password_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property specifies the user's password. This must be set before calling authenticate.

Data Type

String

spn property (Kerberos Struct)

The Service Principal Name (SPN).

Syntax

fn spn(&self ) -> Result<String, IPWorksAuthError> 
fn set_spn(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_spn_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property specifies the Service Principal Name (SPN). This must be set before calling authenticate.

Data Type

String

timeout property (Kerberos Struct)

The timeout for the struct.

Syntax

fn timeout(&self ) -> Result<i32, IPWorksAuthError> 
fn set_timeout(&self, value : i32) ->  Option<IPWorksAuthError> 

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 struct will wait for the operation to complete before returning control.

The struct will use do_events 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 struct fails with an error.

NOTE: By default, all timeouts are inactivity timeouts, that is, 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.

Data Type

i32

user property (Kerberos Struct)

The name and domain of the user to authenticate.

Syntax

fn user(&self ) -> Result<String, IPWorksAuthError> 
fn set_user(&self, value : &str) ->  Option<IPWorksAuthError> 
fn set_user_ref(&self, value : &String) ->  Option<IPWorksAuthError> 

Default Value

""

Remarks

This property specifies the name and realm/domain of the user. The value specified must be in one of the following formats:

• user@domain
• domain/user

Data Type

String

use_tcp property (Kerberos Struct)

Whether TCP is used when establishing the connection.

Syntax

fn use_tcp(&self ) -> Result<bool, IPWorksAuthError> 
fn set_use_tcp(&self, value : bool) ->  Option<IPWorksAuthError> 

Default Value

false

Remarks

This property specifies whether TCP is used as the transport protocol when establishing the connection. By default this property is False and UDP will be used.

Data Type

bool

authenticate method (Kerberos Struct)

Authenticates the user.

Syntax

fn authenticate(&self) -> Result<(), IPWorksAuthError>

Remarks

This method authenticates the user.

Authentication

When authenticate is called the struct will attempt to authenticate the user with the Key Distribution Center (KDC). The struct will communicate with the kdc_host to obtain a service ticket and populate auth_token. The following properties are required when calling this method:

• spn (required)
• user (required)
• password (required)
• kdc_host (required)

A typical sequence of messages would be:

• KRB_AS_REQ -> KDC
• KRB_AS_REP <- KDC
• KRB_TGS_REQ -> KDC
• KRB_TGS_REP <- KDC
• auth_token is populated with the constructed KRB_AP_REP message.

Communication with the kdc_host can be seen through the on_pi_trail event.

config method (Kerberos Struct)

Sets or retrieves a configuration setting.

Syntax

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

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.

do_events method (Kerberos Struct)

This method processes events from the internal message queue.

Syntax

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

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.

interrupt method (Kerberos Struct)

This method interrupts the current method.

Syntax

fn interrupt(&self) -> Result<(), IPWorksAuthError>

Remarks

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

reset method (Kerberos Struct)

Resets the struct properties to their default values.

Syntax

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

Remarks

This method resets the properties to their default values.

on_error event (Kerberos Struct)

Fired when information is available about errors during data delivery.

Syntax

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

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

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

Remarks

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

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

on_log event (Kerberos Struct)

Fires once for each log message.

Syntax

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

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

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

Remarks

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

LogLevel indicates the level of the Message. Possible values are:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

LogType identifies the type of log entry. Possible values are:

• Info
• Verbose
• Debug

on_pi_trail event (Kerberos Struct)

Traces the messages sent to the server, and the respective replies.

Syntax

// KerberosPITrailEventArgs carries the Kerberos PITrail event's parameters.
pub struct KerberosPITrailEventArgs {
  fn direction(&self) -> i32
  fn message(&self) -> &String
}

// KerberosPITrailEvent defines the signature of the Kerberos PITrail event's handler function.
pub trait KerberosPITrailEvent {
  fn on_pi_trail(&self, sender : Kerberos, e : &mut KerberosPITrailEventArgs);
}

impl <'a> Kerberos<'a> {
  pub fn on_pi_trail(&self) -> &'a dyn KerberosPITrailEvent;
  pub fn set_on_pi_trail(&mut self, value : &'a dyn KerberosPITrailEvent);
  ...
}

Remarks

The on_pi_trail event is useful for debugging purposes. It shows all the interaction between the client and the server. To include the raw packets set LogKerberosPackets to True.

The Message parameter contains the full text of the message. The Direction parameter shows the originator of the message:

Config Settings (Kerberos Struct)

The struct accepts one or more of the following configuration settings. Configuration 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.

KERBEROS Config Settings

UDP Config Settings

Socket Config Settings

Base Config Settings

Trappable Errors (Kerberos Struct)

kerberos Errors

UDP Errors

TCP/IP Errors