OCSPServer Component

Properties   Methods   Events   Config Settings   Errors  

The OCSPServer component provides the functionality of an HTTP-based OCSP server.

Syntax

TsbxOCSPServer

Remarks

Use this class to quickly set up a working HTTP-based OCSP server.

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.

Active Property (OCSPServer Component)

Indicates whether the server is active and is listening to new connections.

Syntax

property Active: Boolean read get_Active;

Default Value

false

Remarks

This read-only property returns True if the server is listening to incoming connections.

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

AuthBasic Property (OCSPServer Component)

Enables or disables basic authentication.

Syntax

property AuthBasic: Boolean read get_AuthBasic write set_AuthBasic;

Default Value

false

Remarks

Use this property to enable or disable basic user authentication in the HTTP server.

AuthDigest Property (OCSPServer Component)

Enables or disables digest authentication.

Syntax

property AuthDigest: Boolean read get_AuthDigest write set_AuthDigest;

Default Value

false

Remarks

Use this property to enable or disable digest-based user authentication in the HTTP server.

AuthDigestExpire Property (OCSPServer Component)

Specifies digest expiration time for digest authentication.

Syntax

property AuthDigestExpire: Integer read get_AuthDigestExpire write set_AuthDigestExpire;

Default Value

20

Remarks

Use this property to specify the digest expiration time for digest authentication, in seconds.

AuthRealm Property (OCSPServer Component)

Specifies authentication realm for digest and NTLM authentication.

Syntax

property AuthRealm: String read get_AuthRealm write set_AuthRealm;

Default Value

'SecureBlackbox'

Remarks

Specifies authentication realm for digest and NTLM authentication types.

BadEntries Property (OCSPServer Component)

Contains a list of revoked certificate entries.

Syntax

property BadEntries: TsbxCRLEntryInfoList read get_BadEntries write set_BadEntries;

Remarks

This collection contains a list of revoked certificate identifiers. Add them manually, or use ImportBadCertificates method to create them from a collection of certificates.

This property is not available at design time.

BoundPort Property (OCSPServer Component)

Indicates the bound listening port.

Syntax

property BoundPort: Integer read get_BoundPort;

Default Value

0

Remarks

Check this property to find out the port that has been allocated to the server by the system. The bound port always equals Port if it is provided, or is allocated dynamically if configured to fall in the range between PortRangeFrom and PortRangeTo constraints.

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

CACertificate Property (OCSPServer Component)

The CA certificate.

Syntax

property CACertificate: TsbxCertificate read get_CACertificate write set_CACertificate;

Remarks

Use this property to provide the CA certificate that this OCSP server is providing status responses for.

This property is not available at design time.

ClientAuth Property (OCSPServer Component)

Enables or disables certificate-based client authentication.

Syntax

property ClientAuth: TsbxClientAuthTypes read get_ClientAuth write set_ClientAuth;

TsbxClientAuthTypes = (
  ccatNoAuth,
  ccatRequestCert,
  ccatRequireCert
);

Default Value

ccatNoAuth

Remarks

Set this property to true to tune up the client authentication type: ccatNoAuth = 0; ccatRequestCert = 1; ccatRequireCert = 2;

Endpoint Property (OCSPServer Component)

The virtual path that the server recognizes as the OCSP serving endpoint.

Syntax

property Endpoint: String read get_Endpoint write set_Endpoint;

Default Value

'/'

Remarks

Specifies the virtual path that the server serves OCSP responses on.

ErrorOrigin Property (OCSPServer Component)

Indicates the endpoint where the error originates from.

Syntax

property ErrorOrigin: TsbxErrorOrigins read get_ErrorOrigin write set_ErrorOrigin;

TsbxErrorOrigins = (
  eoLocal,
  eoRemote
);

Default Value

eoLocal

Remarks

Use this property to establish whether the reported error originates from a local or remote endpoint.

This property is not available at design time.

ErrorSeverity Property (OCSPServer Component)

The severity of the error that happened.

Syntax

property ErrorSeverity: TsbxErrorSeverities read get_ErrorSeverity write set_ErrorSeverity;

TsbxErrorSeverities = (
  esInfo,
  esWarning,
  esFatal
);

Default Value

esWarning

Remarks

Use this property to establish whether the error is fatal.

This property is not available at design time.

ExternalCrypto Property (OCSPServer Component)

Provides access to external signing and DC parameters.

Syntax

property ExternalCrypto: TsbxExternalCrypto read get_ExternalCrypto;

Remarks

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

This property is read-only.

FIPSMode Property (OCSPServer Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

GoodEntries Property (OCSPServer Component)

Contains a list of valid and active certificate entries.

Syntax

property GoodEntries: TsbxCRLEntryInfoList read get_GoodEntries write set_GoodEntries;

Remarks

Use this property to provide a list of entried a 'good' status for which is returned. Provide the entries manually, or import them from a certificate collection using ImportGoodCertificates method.

Use BadEntries to provide a list of revoked certificates.

The entries that are neither good nor bad are reported with Unknown status.

This property is not available at design time.

Host Property (OCSPServer Component)

The host to bind the listening port to.

Syntax

property Host: String read get_Host write set_Host;

Default Value

''

Remarks

Use this property to specify the IP address on which to listen to incoming connections.

PinnedCerts Property (OCSPServer Component)

A collection of certificates to be imported.

Syntax

property PinnedCerts: TsbxCertificateList read get_PinnedCerts write set_PinnedCerts;

Remarks

Use this property to provide a list of certificates to be imported into GoodEntries or BadEntries list using ImportGoodCertificates or ImportBadCertificates calls respectively.

This property is not available at design time.

PinnedClient Property (OCSPServer Component)

Populates the pinned client details.

Syntax

property PinnedClient: TsbxTLSClientEntry read get_PinnedClient;

Remarks

Use this property to access the details of the client connection previously pinned with PinClient method.

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

PinnedClientChain Property (OCSPServer Component)

Contains the certificate chain of the pinned client.

Syntax

property PinnedClientChain: TsbxCertificateList read get_PinnedClientChain;

Remarks

Use this property to access the certificate chain of the client connection pinned previously with a PinClient call.

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

Port Property (OCSPServer Component)

Specifies the port number to listen for connections on.

Syntax

property Port: Integer read get_Port write set_Port;

Default Value

80

Remarks

Use this property to specify the port number to listen to connections on. Standard port numbers are 80 for an HTTP server, and 443 for an HTTPS server.

Alternatively, you may specify the acceptable range of listening ports via PortRangeFrom and PortRangeTo properties. In this case the port will be allocated within the requested range by the operating system, and reported in BoundPort.

PortRangeFrom Property (OCSPServer Component)

Specifies the lower limit of the listening port range for incoming connections.

Syntax

property PortRangeFrom: Integer read get_PortRangeFrom write set_PortRangeFrom;

Default Value

0

Remarks

Use this property to specify the lower limit of the port range to listen to connections on. When a port range is used to specify the listening port (as opposed to a fixed value provided via Port), the port will be allocated within the requested range by the operating system, and reported in BoundPort.

Note that this property is ignored if the Port property is set to a non-zero value, in which case the server always aims to listen on that fixed port.

PortRangeTo Property (OCSPServer Component)

Specifies the upper limit of the listening port range for incoming connections.

Syntax

property PortRangeTo: Integer read get_PortRangeTo write set_PortRangeTo;

Default Value

0

Remarks

Use this property to specify the upper limit of the port range to listen to connections on. When a port range is used to specify the listening port (as opposed to a fixed value provided via Port), the port will be allocated within the requested range by the operating system, and reported in BoundPort.

Note that this property is ignored if the Port property is set to a non-zero value, in which case the server always aims to listen on that fixed port.

ServerCertificates Property (OCSPServer Component)

The server's TLS certificates.

Syntax

property ServerCertificates: TsbxCertificateList read get_ServerCertificates write set_ServerCertificates;

Remarks

Use this property to provide a list of TLS certificates for the server endpoint.

A TLS endpoint needs a certificate to be able to accept TLS connections. At least one of the certificates in the collection - the endpoint certificate - must have a private key associated with it.

The collection may include more than one endpoint certificate, and more than one chain. A typical usage scenario is to include two chains (ECDSA and RSA), to cater for clients with different cipher suite preferences.

This property is not available at design time.

SigningCertificate Property (OCSPServer Component)

The certificate to use for signing.

Syntax

property SigningCertificate: TsbxCertificate read get_SigningCertificate write set_SigningCertificate;

Remarks

Use this property to provide the certificate which is to be used for signing outgoing OCSP responses. This certificate must have a private key associated with it.

This property is not available at design time.

SocketSettings Property (OCSPServer Component)

Manages network connection settings.

Syntax

property SocketSettings: TsbxSocketSettings read get_SocketSettings;

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

TLSSettings Property (OCSPServer Component)

Manages TLS layer settings.

Syntax

property TLSSettings: TsbxTLSSettings read get_TLSSettings;

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

UpdatePeriod Property (OCSPServer Component)

The server's information update period.

Syntax

property UpdatePeriod: Integer read get_UpdatePeriod write set_UpdatePeriod;

Default Value

86400

Remarks

Provide the server information update period here. This value is used as a basis for the NextUpdate parameter of the responses.

Users Property (OCSPServer Component)

Provides a list of registered users.

Syntax

property Users: TsbxUserAccountList read get_Users write set_Users;

Remarks

Assign a list of 'known' users to this property to automate authentication handling by the component.

This property is not available at design time.

WebsiteName Property (OCSPServer Component)

Specifies the web site name to use in the certificate.

Syntax

property WebsiteName: String read get_WebsiteName write set_WebsiteName;

Default Value

'SecureBlackbox'

Remarks

If using an internally-generated certificate, use this property to specify the web site name to be included as a common name. A typical common name consists of the host name, such as '192.168.10.10' or 'domain.com'.

Config Method (OCSPServer Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): 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 (OCSPServer Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): 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 insencitive) 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;....

DropClient Method (OCSPServer Component)

Terminates a client connection.

Syntax

procedure DropClient(ConnectionId: Int64; Forced: Boolean);

Remarks

Call this method to shut down a connected client. Forced indicates whether the connection should be closed in a graceful manner.

GetRequestBytes Method (OCSPServer Component)

Returns the contents of the client's HTTP request.

Syntax

function GetRequestBytes(ConnectionId: Int64): TBytes;

Remarks

Use this method to get the body of the client's HTTP request. Note that the body of GET and HEAD requests is empty.

GetRequestHeader Method (OCSPServer Component)

Returns a request header value.

Syntax

function GetRequestHeader(ConnectionId: Int64; HeaderName: String): String;

Remarks

Use this method to get the value of a request header. A good place to call this method is a request-marking event, such as GetRequest or PostRequest.

GetRequestString Method (OCSPServer Component)

Returns the contents of the client's HTTP request.

Syntax

function GetRequestString(ConnectionId: Int64): String;

Remarks

Use this method to get the body of the client's HTTP request to a string. Note that the body of GET and HEAD requests is empty.

GetRequestUsername Method (OCSPServer Component)

Returns the username for a connection.

Syntax

function GetRequestUsername(ConnectionId: Int64): String;

Remarks

Use this method to obtain a username for an active connection. The method will return an empty string if no authentication has been performed on the connection.

ImportBadCertificates Method (OCSPServer Component)

Imports revoked certificates.

Syntax

procedure ImportBadCertificates();

Remarks

This method imports a collection of bad (revoked) certificates into BadEntries list. Provide the certificates via PinnedCerts property.

ImportGoodCertificates Method (OCSPServer Component)

Imports good certificates.

Syntax

procedure ImportGoodCertificates();

Remarks

This method imports a collection of good (active) certificates into GoodEntries list. Provide the certificates via PinnedCerts property.

ListClients Method (OCSPServer Component)

Enumerates the connected clients.

Syntax

function ListClients(): String;

Remarks

This method enumerates the connected clients. It returns a list of strings, with each string being of 'ConnectionID|Address|Port' format, and representing a single connection.

PinClient Method (OCSPServer Component)

Takes a snapshot of the connection's properties.

Syntax

procedure PinClient(ConnectionId: Int64);

Remarks

Use this method to take a snapshot of a connected client. The captured properties are populated in PinnedClient and PinnedClientChain properties.

ProcessGenericRequest Method (OCSPServer Component)

Processes a generic OCSP status request.

Syntax

function ProcessGenericRequest(RequestBytes: TBytes; BasicOnly: Boolean): TBytes;

Remarks

This method processes a generic status request and produces a response. Use it to generate OCSP statuses for requests obtained externally, out of the default HTTP channel.

This method respects all current settings of the server object, and invokes StatusRequest to consult about the request and response details with the application.

If BasicOnly is set, the return value will only contain the BasicOCSPResponse piece of the response. If it is switched off, the whole OCSPResponse structure will be returned.

Start Method (OCSPServer Component)

Starts the server.

Syntax

procedure Start();

Remarks

Use this method to activate the server and start listening to incoming connections.

Stop Method (OCSPServer Component)

Stops the server.

Syntax

procedure Stop();

Remarks

Call this method to stop listening to incoming connections and deactivate the server.

Accept Event (OCSPServer Component)

Reports an incoming connection.

Syntax

type TAcceptEvent = procedure (
  Sender: TObject;
  const RemoteAddress: String;
  RemotePort: Integer;
  var Accept: Boolean
) of Object;

property OnAccept: TAcceptEvent read FOnAccept write FOnAccept;

Remarks

This event is fired when a new connection from RemoteAddress:RemotePort is ready to be accepted. Use the Accept parameter to accept or decline it.

Subscribe to Connect event to be notified of every connection that has been set up.

AuthAttempt Event (OCSPServer Component)

Fires when a connected client makes an authentication attempt.

Syntax

type TAuthAttemptEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  const HTTPMethod: String;
  const URI: String;
  const AuthMethod: String;
  const Username: String;
  const Password: String;
  var Allow: Boolean
) of Object;

property OnAuthAttempt: TAuthAttemptEvent read FOnAuthAttempt write FOnAuthAttempt;

Remarks

The component fires this event whenever a client attempts to authenticate itself. Use the Allow parameter to let the client through.

ConnectionID contains the unique session identifier for that client, HTTPMethod specifies the HTTP method (GET, POST, etc.) used to access the URI resource, AuthMethod specifies the authentication method, and Username and Password contain the professed credentials.

Connect Event (OCSPServer Component)

Reports an accepted connection.

Syntax

type TConnectEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  const RemoteAddress: String;
  RemotePort: Integer
) of Object;

property OnConnect: TConnectEvent read FOnConnect write FOnConnect;

Remarks

The component fires this event to report that a new connection has been established. ConnectionId indicates the unique ID assigned to this connection. The same ID will be supplied to any other events related to this connection, such as GetRequest or AuthAttempt.

Disconnect Event (OCSPServer Component)

Fires to report a disconnected client.

Syntax

type TDisconnectEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64
) of Object;

property OnDisconnect: TDisconnectEvent read FOnDisconnect write FOnDisconnect;

Remarks

The component fires this event when a connected client disconnects.

Error Event (OCSPServer Component)

Information about errors during data delivery.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ConnectionId: Int64;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The event is fired in case of exceptional conditions during message processing.

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 HTTPS section.

ExternalSign Event (OCSPServer Component)

Handles remote or external signing initiated by the server protocol.

Syntax

type TExternalSignEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  const OperationId: String;
  const HashAlgorithm: String;
  const Pars: String;
  const Data: String;
  var SignedData: String
) of Object;

property OnExternalSign: TExternalSignEvent read FOnExternalSign write FOnExternalSign;

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 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 contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for 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 a .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(); };

Notification Event (OCSPServer Component)

This event notifies the application about an underlying control flow event.

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

StatusRequest Event (OCSPServer Component)

Requests a certificate status from the application.

Syntax

type TStatusRequestEvent = procedure (
  Sender: TObject;
  ConnectionId: Int64;
  const HashAlgorithm: String;
  IssuerNameHash: TBytes;
  IssuerKeyHash: TBytes;
  CertificateSerial: TBytes;
  var CertStatus: Integer;
  var Reason: Integer;
  var RevocationTime: String;
  var ThisUpdate: String;
  var NextUpdate: String
) of Object;

property OnStatusRequest: TStatusRequestEvent read FOnStatusRequest write FOnStatusRequest;

Remarks

Subscribe to this event to provide, alter, or inspect certificate statuses produced by the OCSP server.

ConnectionId returns the unique identifier of the client making the request. IssuerNameHash and IssuerKeyHash specify the message digests of the certificate issuer's name and public key obtained with the use of HashAlgorithm. CertificateSerial specifies the serial number of the checked certificate.

Use the by-ref parameters CertStatus, Reason, RevocationTime, ThisUpdate, and NextUpdate to check or alter the status details of the requested certificate.

TLSCertValidate Event (OCSPServer Component)

Fires when a client certificate needs to be validated.

Syntax

type TTLSCertValidateEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  var Accept: Boolean
) of Object;

property OnTLSCertValidate: TTLSCertValidateEvent read FOnTLSCertValidate write FOnTLSCertValidate;

Remarks

The component fires this event to notify the application of an authenticating client. Use the event handler to validate the certificate and pass your decision back to the server component via the Accept parameter.

TLSEstablished Event (OCSPServer Component)

Reports the setup of a TLS session.

Syntax

type TTLSEstablishedEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64
) of Object;

property OnTLSEstablished: TTLSEstablishedEvent read FOnTLSEstablished write FOnTLSEstablished;

Remarks

Subscribe to this event to be notified about the setup of a TLS connection by a connected client.

TLSPSK Event (OCSPServer Component)

Requests a pre-shared key for TLS-PSK.

Syntax

type TTLSPSKEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64;
  const Identity: String;
  var PSK: String;
  var Ciphersuite: String
) of Object;

property OnTLSPSK: TTLSPSKEvent read FOnTLSPSK write FOnTLSPSK;

Remarks

The component fires this event to report that a client has requested a TLS-PSK negotiation. ConnectionId indicates the unique connection ID that requested the PSK handshake.

Use Identity to look up for the corresponding pre-shared key in the server's database, then assign the key to the PSK parameter. If TLS 1.3 PSK is used, you will also need to assign the Ciphersuite parameter with the cipher suite associated with that identity and their key.

TLSShutdown Event (OCSPServer Component)

Reports closure of a TLS session.

Syntax

type TTLSShutdownEvent = procedure (
  Sender: TObject;
  ConnectionID: Int64
) of Object;

property OnTLSShutdown: TTLSShutdownEvent read FOnTLSShutdown write FOnTLSShutdown;

Remarks

The component fires this event when a connected client closes their TLS session gracefully. This event is typically followed by a Disconnect, which marks the closure of the underlying TCP session.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

constructor Create();

constructor Create();

constructor Create();

constructor Create();

constructor Create();

constructor Create();

Config Settings (OCSPServer Component)

OCSPServer Config Settings

Base Config Settings

Trappable Errors (OCSPServer Component)

OCSPServer Errors