OAuthClient Component

Properties   Methods   Events   Config Settings   Errors  

The OAuthClient component implements interaction between the client, the resource owner (end-user), and the authorization server via OAuth 2.0 protocol.

Syntax

nsoftware.SecureBlackbox.Oauthclient

Remarks

OAuthClient implements interaction between the client (an application that needs access to a protected resource), the resource owner (end-user), and the authorization server via OAuth 2.0 (RFC 6749) protocol.

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.

AccessToken Property (OAuthClient Component)

Contains the access token.

Syntax

• C#
• VB.NET

public string AccessToken { get; set; }

Public Property AccessToken As String

Default Value

""

Remarks

Use this property to check or set the authorization access token.

This property is not available at design time.

AuthURL Property (OAuthClient Component)

Specifies the URL of the authorization server.

Syntax

• C#
• VB.NET

public string AuthURL { get; set; }

Public Property AuthURL As String

Default Value

""

Remarks

Use this property to set the URL of the authorization server.

AutoRefresh Property (OAuthClient Component)

Specifies whether access token should be automatically refreshed.

Syntax

• C#
• VB.NET

public bool AutoRefresh { get; set; }

Public Property AutoRefresh As Boolean

Default Value

True

Remarks

Set this property to true to let the component automatically refresh AccessToken. If available, RefreshToken is used to renew access token. Otherwise the authorization process is initiated from the beginning, with user authentication and so on.

BlockedCertificates Property (OAuthClient Component)

The certificates that must be rejected as trust anchors.

Syntax

• C#
• VB.NET

public CertificateList BlockedCertificates { get; }

Public Property BlockedCertificates As CertificateList

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

ClientChain Property (OAuthClient Component)

The TLS client certificate chain.

Syntax

• C#
• VB.NET

public CertificateList ClientChain { get; }

Public Property ClientChain As CertificateList

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the component. Note that the client's end-entity certificate should have a private key associated with it.

Use CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

ClientID Property (OAuthClient Component)

Client ID of the application which needs access to the protected resource.

Syntax

• C#
• VB.NET

public string ClientID { get; set; }

Public Property ClientID As String

Default Value

""

Remarks

Use this property to specify the client ID of the application.

ClientSecret Property (OAuthClient Component)

Client secret of the application which needs access to the protected resource.

Syntax

• C#
• VB.NET

public string ClientSecret { get; set; }

Public Property ClientSecret As String

Default Value

""

Remarks

Use this property to specify client secret of the application.

ConnectionInfo Property (OAuthClient Component)

Returns the details of the underlying network connection.

Syntax

• C#
• VB.NET

public ConnectionInfo ConnectionInfo { get; }

Public ReadOnly Property ConnectionInfo As ConnectionInfo

Remarks

Use this property to learn about the connection setup, such as the protocol security details and amounts of data transferred each way.

This property is read-only and not available at design time.

CustomParameters Property (OAuthClient Component)

Contains custom parameters of the authorization request.

Syntax

• C#
• VB.NET

public StringNameValuePairList CustomParameters { get; }

Public ReadOnly Property CustomParameters As StringNameValuePairList

Remarks

This property contains key-value pairs of custom parameters of HTTP request.

This property is read-only and not available at design time.

ExpiresAt Property (OAuthClient Component)

The expiration time of access token.

Syntax

• C#
• VB.NET

public string ExpiresAt { get; set; }

Public Property ExpiresAt As String

Default Value

""

Remarks

Use this property to check the expiration time of AccessToken.

ExpiresIn Property (OAuthClient Component)

Returns access token lifetime in seconds.

Syntax

• C#
• VB.NET

public int ExpiresIn { get; }

Public ReadOnly Property ExpiresIn As Integer

Default Value

0

Remarks

Use this property to get the AccessToken lifetime in seconds. This value is returned by the authorization server together with the access token. To check the token's expiration moment, use ExpiresAt property.

This property is read-only and not available at design time.

ExternalCrypto Property (OAuthClient Component)

Provides access to external signing and DC parameters.

Syntax

• C#
• VB.NET

public ExternalCrypto ExternalCrypto { get; }

Public ReadOnly Property ExternalCrypto As ExternalCrypto

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

FailureResponse Property (OAuthClient Component)

The web page showed to the user by the component on authorization failure.

Syntax

• C#
• VB.NET

public string FailureResponse { get; set; }

Public Property FailureResponse As String

Default Value

""

Remarks

This property contains the html of the web page to be shown on authorization failure.

FIPSMode Property (OAuthClient Component)

Reserved.

Syntax

• C#
• VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

Default Value

False

Remarks

This property is reserved for future use.

GrantType Property (OAuthClient Component)

Specifies which protocol flow should be used to authorize the user.

Syntax

• C#
• VB.NET

public OauthclientGrantTypes GrantType { get; set; }

enum OauthclientGrantTypes {
  ogtAuthorizationCode,
  ogtImplicit,
  ogtPasswordCredentials,
  ogtClientCredentials,
  ogtHybridIdToken,
  ogtHybridToken,
  ogtHybridAll
}

Public Property GrantType As OauthclientGrantTypes

Enum OauthclientGrantTypes
  ogtAuthorizationCode
  ogtImplicit
  ogtPasswordCredentials
  ogtClientCredentials
  ogtHybridIdToken
  ogtHybridToken
  ogtHybridAll
End Enum

Default Value

0

Remarks

Use this property to specify the authorization protocol to use.

IDToken Property (OAuthClient Component)

Contains the ID Token parameter for JWT.

Syntax

• C#
• VB.NET

public string IDToken { get; }

Public ReadOnly Property IDToken As String

Default Value

""

Remarks

Use this property to get the id_token parameter (if any) than can be used for JWT operations.

This property is read-only and not available at design time.

KeepAlivePolicy Property (OAuthClient Component)

Defines the keep-alive handling policy.

Syntax

• C#
• VB.NET

public OauthclientKeepAlivePolicies KeepAlivePolicy { get; set; }

enum OauthclientKeepAlivePolicies {
  ckapStandardDefined,
  ckapPreferKeepAlive,
  ckapRelyOnServer,
  ckapKeepAlivesDisabled
}

Public Property KeepAlivePolicy As OauthclientKeepAlivePolicies

Enum OauthclientKeepAlivePolicies
  ckapStandardDefined
  ckapPreferKeepAlive
  ckapRelyOnServer
  ckapKeepAlivesDisabled
End Enum

Default Value

0

Remarks

Use this property to tune-up the keep-alive mechanism as per the needs of your application.

KnownCertificates Property (OAuthClient Component)

Additional certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList KnownCertificates { get; }

Public Property KnownCertificates As CertificateList

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

KnownCRLs Property (OAuthClient Component)

Additional CRLs for chain validation.

Syntax

• C#
• VB.NET

public CRLList KnownCRLs { get; }

Public Property KnownCRLs As CRLList

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

KnownOCSPs Property (OAuthClient Component)

Additional OCSP responses for chain validation.

Syntax

• C#
• VB.NET

public OCSPResponseList KnownOCSPs { get; }

Public Property KnownOCSPs As OCSPResponseList

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Password Property (OAuthClient Component)

The connecting user's authentication password.

Syntax

• C#
• VB.NET

public string Password { get; set; }

Public Property Password As String

Default Value

""

Remarks

Assign the user's authentication password to this property. Use Username for username/login. The Username and Password properties are used only when GrantType is oauthPasswordCredentials.

Proxy Property (OAuthClient Component)

The proxy server settings.

Syntax

• C#
• VB.NET

public ProxySettings Proxy { get; }

Public ReadOnly Property Proxy As ProxySettings

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

RedirectURL Property (OAuthClient Component)

The URL where the user is redirected after authorization.

Syntax

• C#
• VB.NET

public string RedirectURL { get; set; }

Public Property RedirectURL As String

Default Value

""

Remarks

Use this property to specify the URL on which the local HTTP server should open the listening port and wait for response from the authorization server. When the port number is explicitly specified, e.g., "http://localhost:5050/", the application has to be allowed to open a listening socket on that port.

HTTPS redirects support

Services increasingly require that redirects are made to HTTPS-enabled endpoints (e.g. "https://localhost:5050/"). OAuthClient does support them, but you are expected to do a little tuneup to be able to handle them.

What you need to do is set up the TLS server certificate that the OAuth receiver will be presenting to the user's web browser. The certificate is an integral part of the TLS handshake process. You can provide the certificate to the component using the AddLocalServerCertificate or AddLocalServerCertificateFromFile actions. See DoAction for the details.

The provided TLS certificate must contain a matching private key. You can generate the certificate using the CertificateManager component, or third-party software such as OpenSSL. Note that some browsers no longer accept self-signed TLS certificates, which typically means that you need to generate and set up a pair of certificates (the self-signed root certificate and the subordinate web server certificate) to make your receiver work with such browsers.

RefreshToken Property (OAuthClient Component)

The refresh token, to be used to automatically obtain new access token.

Syntax

• C#
• VB.NET

public string RefreshToken { get; set; }

Public Property RefreshToken As String

Default Value

""

Remarks

The refresh token is used to obtain new AccessToken without user authentication.

Scope Property (OAuthClient Component)

The scope of the request to be authorized.

Syntax

• C#
• VB.NET

public string Scope { get; set; }

Public Property Scope As String

Default Value

""

Remarks

Use this property to specify the scope of the request to the protected resource.

ServerChain Property (OAuthClient Component)

The TLS server's certificate chain.

Syntax

• C#
• VB.NET

public CertificateList ServerChain { get; }

Public ReadOnly Property ServerChain As CertificateList

Remarks

Use this property to access the certificate chain sent by the TLS server. This property is ready to read when OnCertificateValidate event is fired by the client component.

This property is read-only and not available at design time.

SocketSettings Property (OAuthClient Component)

Manages network connection settings.

Syntax

• C#
• VB.NET

public SocketSettings SocketSettings { get; }

Public ReadOnly Property SocketSettings As SocketSettings

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

State Property (OAuthClient Component)

Specifies the state parameter of the authorization request or response.

Syntax

• C#
• VB.NET

public string State { get; set; }

Public Property State As String

Default Value

""

Remarks

This parameter contains an opaque value used by the client to maintain state between the request and callback. If this parameter was present in the authorization request, the server should include the same value in its response.

SuccessResponse Property (OAuthClient Component)

The web page showed to the user by the component on authorization success.

Syntax

• C#
• VB.NET

public string SuccessResponse { get; set; }

Public Property SuccessResponse As String

Default Value

""

Remarks

This property contains the html of the web page to be shown on authorization success.

Timeout Property (OAuthClient Component)

Specifies waiting timeout (in milliseconds).

Syntax

• C#
• VB.NET

public int Timeout { get; set; }

Public Property Timeout As Integer

Default Value

120000

Remarks

This property specifies the timeout (in milliseconds) to wait for server's response.

TLSSettings Property (OAuthClient Component)

Manages TLS layer settings.

Syntax

• C#
• VB.NET

public TLSSettings TLSSettings { get; }

Public ReadOnly Property TLSSettings As TLSSettings

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

TokenType Property (OAuthClient Component)

Returns the access token type.

Syntax

• C#
• VB.NET

public string TokenType { get; }

Public ReadOnly Property TokenType As String

Default Value

""

Remarks

The access token type provides a client with the information on how to use the AccessToken. The understanding of token type is the client's responsibility. Some token types are described, for instance, in RFC 6750 and OAuth-HTTP-MAC specifications.

This property is read-only and not available at design time.

TokenURL Property (OAuthClient Component)

Specifies the URL of the token endpoint.

Syntax

• C#
• VB.NET

public string TokenURL { get; set; }

Public Property TokenURL As String

Default Value

""

Remarks

The token endpoint is used by the client, which needs access to protected resource, to obtain access token from the authorization server.

TrustedCertificates Property (OAuthClient Component)

A list of trusted certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList TrustedCertificates { get; }

Public Property TrustedCertificates As CertificateList

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Username Property (OAuthClient Component)

The connecting user's username (login name).

Syntax

• C#
• VB.NET

public string Username { get; set; }

Public Property Username As String

Default Value

""

Remarks

Assign the user's login name to this property. Use Password to provide the password. The Username and Password properties are used only when GrantType is oauthPasswordCredentials.

Authorize Method (OAuthClient Component)

Performs user authorization and gets an access token.

Syntax

• C#
• VB.NET

public bool Authorize();

Public Function Authorize() As Boolean

Remarks

Call this method to perform user authorization and get an access token. When the user completes authorization and its data is sent to the server, OAuthClient will fire the Wait event periodically, to show how much waiting time is left. Upon successful authorization, the AccessToken and ExpiresAt properties are filled.

Returns true if the authorization was granted, and false otherwise.

Config Method (OAuthClient Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As 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.

DoAction Method (OAuthClient Component)

Performs an additional action.

Syntax

• C#
• VB.NET

public string DoAction(string actionID, string actionParams);

Public Function DoAction(ByVal ActionID As String, ByVal ActionParams As String) As String

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

Error Event (OAuthClient Component)

Provides information about errors during authorization operations.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

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

Remarks

This event is fired in case of exceptional conditions occured during authorization operations.

ErrorCode contains an error code and Description contains a textual description of the error.

ExternalSign Event (OAuthClient Component)

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

• C#
• VB.NET

public event OnExternalSignHandler OnExternalSign;

public delegate void OnExternalSignHandler(object sender, OauthclientExternalSignEventArgs e);

public class OauthclientExternalSignEventArgs : EventArgs {
  public string OperationId { get; }
  public string HashAlgorithm { get; }
  public string Pars { get; }
  public string Data { get; }
  public string SignedData { get; set; }
}

Public Event OnExternalSign As OnExternalSignHandler

Public Delegate Sub OnExternalSignHandler(sender As Object, e As OauthclientExternalSignEventArgs)

Public Class OauthclientExternalSignEventArgs Inherits EventArgs
  Public ReadOnly Property OperationId As String
  Public ReadOnly Property HashAlgorithm As String
  Public ReadOnly Property Pars As String
  Public ReadOnly Property Data As String
  Public Property SignedData As String
End Class

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the component via the SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contains algorithm-dependent parameters.

The component uses base16 (hex) encoding for the Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses the .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

LaunchBrowser Event (OAuthClient Component)

Fires to show the login page to the end-user.

Syntax

• C#
• VB.NET

public event OnLaunchBrowserHandler OnLaunchBrowser;

public delegate void OnLaunchBrowserHandler(object sender, OauthclientLaunchBrowserEventArgs e);

public class OauthclientLaunchBrowserEventArgs : EventArgs {
  public string URL { get; }
  public bool Handled { get; set; }
}

Public Event OnLaunchBrowser As OnLaunchBrowserHandler

Public Delegate Sub OnLaunchBrowserHandler(sender As Object, e As OauthclientLaunchBrowserEventArgs)

Public Class OauthclientLaunchBrowserEventArgs Inherits EventArgs
  Public ReadOnly Property URL As String
  Public Property Handled As Boolean
End Class

Remarks

Subscribe to this event to respond to requests from the component to open the URL in the browser. Set Handled to true to report that the URL has been opened in the browser.

TLSCertNeeded Event (OAuthClient Component)

Fires when a remote TLS party requests a client certificate.

Syntax

• C#
• VB.NET

public event OnTLSCertNeededHandler OnTLSCertNeeded;

public delegate void OnTLSCertNeededHandler(object sender, OauthclientTLSCertNeededEventArgs e);

public class OauthclientTLSCertNeededEventArgs : EventArgs {
  public string Host { get; }
  public string CANames { get; }
}

Public Event OnTLSCertNeeded As OnTLSCertNeededHandler

Public Delegate Sub OnTLSCertNeededHandler(sender As Object, e As OauthclientTLSCertNeededEventArgs)

Public Class OauthclientTLSCertNeededEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property CANames As String
End Class

Remarks

This event fires to notify the implementation that a remote TLS server has requested a client certificate. The Host parameter identifies the host that makes a request, and the CANames parameter (optional, according to the TLS spec) advises on the accepted issuing CAs.

Use the TLSClientChain property in response to this event to provide the requested certificate. Please make sure the client certificate includes the associated private key. Note that you may set the certificates before the connection without waiting for this event to fire.

This event is preceded by the TLSHandshake event for the given host and, if the certificate was accepted, succeeded by the TLSEstablished event.

TLSCertValidate Event (OAuthClient Component)

This event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Syntax

• C#
• VB.NET

public event OnTLSCertValidateHandler OnTLSCertValidate;

public delegate void OnTLSCertValidateHandler(object sender, OauthclientTLSCertValidateEventArgs e);

public class OauthclientTLSCertValidateEventArgs : EventArgs {
  public string ServerHost { get; }
  public string ServerIP { get; }
  public bool Accept { get; set; }
}

Public Event OnTLSCertValidate As OnTLSCertValidateHandler

Public Delegate Sub OnTLSCertValidateHandler(sender As Object, e As OauthclientTLSCertValidateEventArgs)

Public Class OauthclientTLSCertValidateEventArgs Inherits EventArgs
  Public ReadOnly Property ServerHost As String
  Public ReadOnly Property ServerIP As String
  Public Property Accept As Boolean
End Class

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, components may contact a number of TLS endpoints during their work, depending on their configuration.

Accept is assigned in accordance with the outcome of the internal validation check performed by the component, and can be adjusted if needed.

TLSEstablished Event (OAuthClient Component)

Fires when a TLS handshake with Host successfully completes.

Syntax

• C#
• VB.NET

public event OnTLSEstablishedHandler OnTLSEstablished;

public delegate void OnTLSEstablishedHandler(object sender, OauthclientTLSEstablishedEventArgs e);

public class OauthclientTLSEstablishedEventArgs : EventArgs {
  public string Host { get; }
  public string Version { get; }
  public string Ciphersuite { get; }
  public byte[] ConnectionId { get; }
  public bool Abort { get; set; }
}

Public Event OnTLSEstablished As OnTLSEstablishedHandler

Public Delegate Sub OnTLSEstablishedHandler(sender As Object, e As OauthclientTLSEstablishedEventArgs)

Public Class OauthclientTLSEstablishedEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property Version As String
  Public ReadOnly Property Ciphersuite As String
  Public ReadOnly Property ConnectionId As Byte()
  Public Property Abort As Boolean
End Class

Remarks

The component uses this event to notify the application about a successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate the security parameters of the new connection. Use the Abort parameter if you need to terminate the connection at this stage.

TLSHandshake Event (OAuthClient Component)

Fires when a new TLS handshake is initiated, before the handshake commences.

Syntax

• C#
• VB.NET

public event OnTLSHandshakeHandler OnTLSHandshake;

public delegate void OnTLSHandshakeHandler(object sender, OauthclientTLSHandshakeEventArgs e);

public class OauthclientTLSHandshakeEventArgs : EventArgs {
  public string Host { get; }
  public bool Abort { get; set; }
}

Public Event OnTLSHandshake As OnTLSHandshakeHandler

Public Delegate Sub OnTLSHandshakeHandler(sender As Object, e As OauthclientTLSHandshakeEventArgs)

Public Class OauthclientTLSHandshakeEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public Property Abort As Boolean
End Class

Remarks

The component uses this event to notify the application about the start of a new TLS handshake to Host. If the handshake is successful, this event will be followed by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSPSK Event (OAuthClient Component)

Notifies the application about the PSK key exchange.

Syntax

• C#
• VB.NET

public event OnTLSPSKHandler OnTLSPSK;

public delegate void OnTLSPSKHandler(object sender, OauthclientTLSPSKEventArgs e);

public class OauthclientTLSPSKEventArgs : EventArgs {
  public string Host { get; }
  public string Hint { get; }
}

Public Event OnTLSPSK As OnTLSPSKHandler

Public Delegate Sub OnTLSPSKHandler(sender As Object, e As OauthclientTLSPSKEventArgs)

Public Class OauthclientTLSPSKEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property Hint As String
End Class

Remarks

The component fires this event to notify the application about the beginning of TLS-PSK key exchange with Host. The Hint parameter may be used by the server to identify the key or service to use. Use the PreSharedKey field of TLSSettings to provide the pre-shared key to the component.

TLSShutdown Event (OAuthClient Component)

Reports the graceful closure of a TLS connection.

Syntax

• C#
• VB.NET

public event OnTLSShutdownHandler OnTLSShutdown;

public delegate void OnTLSShutdownHandler(object sender, OauthclientTLSShutdownEventArgs e);

public class OauthclientTLSShutdownEventArgs : EventArgs {
  public string Host { get; }
}

Public Event OnTLSShutdown As OnTLSShutdownHandler

Public Delegate Sub OnTLSShutdownHandler(sender As Object, e As OauthclientTLSShutdownEventArgs)

Public Class OauthclientTLSShutdownEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
End Class

Remarks

This event notifies the application about the closure of an earlier established TLS connection. Note that only graceful connection closures are reported.

Wait Event (OAuthClient Component)

Fired periodically to show how much waiting time is left.

Syntax

• C#
• VB.NET

public event OnWaitHandler OnWait;

public delegate void OnWaitHandler(object sender, OauthclientWaitEventArgs e);

public class OauthclientWaitEventArgs : EventArgs {
  public int TimeLeft { get; }
  public bool Stop { get; set; }
}

Public Event OnWait As OnWaitHandler

Public Delegate Sub OnWaitHandler(sender As Object, e As OauthclientWaitEventArgs)

Public Class OauthclientWaitEventArgs Inherits EventArgs
  Public ReadOnly Property TimeLeft As Integer
  Public Property Stop As Boolean
End Class

Remarks

This event is fired after authorization is started, to show how much time is left to wait for server's response. Waiting can be cancelled by setting the Stop parameter to true, which will result in authorization failure.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count, string password);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, string password);

Public Certificate(ByVal CertBytes As Byte(), ByVal CertStartIndex As Integer, ByVal CertCount As Integer, ByVal KeyBytes As Byte(), ByVal KeyStartIndex As Integer, ByVal KeyCount As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

• C#
• VB.NET

public Certificate(string path, string password);

Public Certificate(ByVal Path As String, ByVal Password As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string certPath, string keyPath, string password);

Public Certificate(ByVal CertPath As String, ByVal KeyPath As String, ByVal Password As String)

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream);

Public Certificate(ByVal Stream As System.IO.Stream)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream, string password);

Public Certificate(ByVal Stream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(System.IO.Stream certStream, System.IO.Stream keyStream, string password);

Public Certificate(ByVal CertStream As System.IO.Stream, ByVal KeyStream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a new object with default field values.

ConnectionInfo Type

Contains information about a network connection.

Remarks

Use this property to check various details of the network connection. These include the total amounts of data transferred, the availability of TLS, and its parameters.

Fields

Constructors

• C#
• VB.NET

public ConnectionInfo();

Public ConnectionInfo()

Creates a new ConnectionInfo object.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

• C#
• VB.NET

public CRL(byte[] bytes, int startIndex, int count);

Public CRL(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Creates a CRL object from a memory buffer. Bytes is a buffer containing raw (DER) CRL data, StartIndex and Count specify the starting position and the length of the CRL data in the buffer, respectively.

• C#
• VB.NET

public CRL(string location);

Public CRL(ByVal Location As String)

Creates a CRL object by downloading it from a remote location.

• C#
• VB.NET

public CRL(System.IO.Stream stream);

Public CRL(ByVal Stream As System.IO.Stream)

Creates a CRL object from data contained in a stream.

• C#
• VB.NET

public CRL();

Public CRL()

Creates an empty CRL object.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

• C#
• VB.NET

public ExternalCrypto();

Public ExternalCrypto()

Creates a new ExternalCrypto object with default field values.

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRLs).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

• C#
• VB.NET

public OCSPResponse(byte[] bytes, int startIndex, int count);

Public OCSPResponse(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Initializes the response from a memory buffer. Bytes is a buffer containing raw OCSP response data, StartIndex and Count specify the starting position and the number of bytes to be read from this buffer.

• C#
• VB.NET

public OCSPResponse(string location);

Public OCSPResponse(ByVal Location As String)

Downloads an OCSP response from a remote location.

• C#
• VB.NET

public OCSPResponse(System.IO.Stream stream);

Public OCSPResponse(ByVal Stream As System.IO.Stream)

Initializes the response with the data from a stream.

• C#
• VB.NET

public OCSPResponse();

Public OCSPResponse()

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

• C#
• VB.NET

public ProxySettings();

Public ProxySettings()

Creates a new ProxySettings object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

• C#
• VB.NET

public SocketSettings();

Public SocketSettings()

Creates a new SocketSettings object.

StringNameValuePair Type

A simple name-value pair object.

Remarks

The component represents a name-value string pair used in a variety of network components.

Fields

Constructors

• C#
• VB.NET

public StringNameValuePair(string name, string value);

Public StringNameValuePair(ByVal Name As String, ByVal Value As String)

Creates a name-value pair from a name and a value.

• C#
• VB.NET

public StringNameValuePair();

Public StringNameValuePair()

Creates an empty name-value object.

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

• C#
• VB.NET

public TLSSettings();

Public TLSSettings()

Creates a new TLSSettings object.

Config Settings (OAuthClient Component)

OAuthClient Config Settings

Base Config Settings

Trappable Errors (OAuthClient Component)