HTTPClient Class

Properties   Methods   Events   Config Settings   Errors  

The HTTPClient class implements client-side functionality of HTTP and HTTPS protocols.

Syntax

secureblackbox.Httpclient

Remarks

HTTPClient provides means of exchanging HTTP messages with HTTP servers. Both plain (HTTP) and secure (HTTPS) connection types are supported.

Features supported

• All standard request types (GET, POST, PUT etc.), plus custom VERBs
• TLS 1.2 and 1.3 (and earlier versions for older servers)
• Strong client and server authentication on TLS and HTTP levels
• Flexible custom header adjustment
• A variety of proxy server types

Configuring the component

HTTPClient is very easy to configure. In some cases, like in the example given below, you do not need any special tuneups whatsoever: client.Get("http://www.mywebserver.com/"); if (client.StatusCode == 200) { string response = client.OutputString; } You may need to adjust the component settings if you plan to connect to endpoints secured with TLS. By default, HTTPClient relies on the system settings when validating server certificates. If you would prefer to ignore the system trust and implement customized chain validation procedures - such as certificate pinning - in your code instead, set TLSSettings.AutoValidateCertificates to false, and subscribe to CertificateValidate event. This event will fire whenever a server certificate validation needs to be performed.

Use ClientChain collection to provide your certificates for client authentication. Make sure the provided certificate contains a private key; otherwise it will be unable to authenticate.

To provide custom HTTP headers, subscribe to HeadersPrepared event. HTTPClient fires this event right before sending the request out to the server, giving you an opportunity to alter the headers or add your own. The list of headers can be accessed via the RequestHeaders collection. Note: the headers can only be modified from the HeadersPrepared event handler. Setting them earlier or later in your code won't provide the expected effect.

Having set up the component, use the appropriate variant of the request method (such as: Get, GetBytes, or GetFile) to obtain the response in the desired format (string, memory buffer, or file).

Property List

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

Method List

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

Event List

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

Config Settings

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

BlockedCertificates Property (HTTPClient Class)

The certificates that must be rejected as trust anchors.

Syntax

public CertificateList getBlockedCertificates();


public void setBlockedCertificates(CertificateList blockedCertificates);

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 (HTTPClient Class)

The TLS client certificate chain.

Syntax

public CertificateList getClientChain();


public void setClientChain(CertificateList clientChain);

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the class. 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.

ConnectionInfo Property (HTTPClient Class)

Returns the details of the underlying network connection.

Syntax

public ConnectionInfo getConnectionInfo();

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.

CustomRequest Property (HTTPClient Class)

Specifies a custom request verb.

Syntax

public String getCustomRequest();


public void setCustomRequest(String customRequest);

Default Value

""

Remarks

Use this property to specify a custom HTTP method verb to use instead of the original method. PATCH is one of the commonly used custom verbs.

This property is not available at design time.

DynamicData Property (HTTPClient Class)

Takes a piece of data to be sent to the server within a dynamic POST or PUT request.

Syntax

public byte[] getDynamicData();


public void setDynamicData(byte[] dynamicData);

Remarks

Assign the next chunk of data to this property from your DynamicDataNeeded event handler to pass it to the server. Leave it empty to tell the component that no more data is available.

This property is not available at design time.

ExternalCrypto Property (HTTPClient Class)

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

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 (HTTPClient Class)

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

KeepAlivePolicy Property (HTTPClient Class)

Defines the keep-alive handling policy.

Syntax

public int getKeepAlivePolicy();


public void setKeepAlivePolicy(int keepAlivePolicy);


Enumerated values:
  public final static int ckapStandardDefined = 0;
  public final static int ckapPreferKeepAlive = 1;
  public final static int ckapRelyOnServer = 2;
  public final static int ckapKeepAlivesDisabled = 3;

Default Value

0

Remarks

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

KnownCertificates Property (HTTPClient Class)

Additional certificates for chain validation.

Syntax

public CertificateList getKnownCertificates();


public void setKnownCertificates(CertificateList knownCertificates);

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 certificates to be added to this collection is roughly equivalent to that of 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 (HTTPClient Class)

Additional CRLs for chain validation.

Syntax

public CRLList getKnownCRLs();


public void setKnownCRLs(CRLList knownCRLs);

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 (HTTPClient Class)

Additional OCSP responses for chain validation.

Syntax

public OCSPResponseList getKnownOCSPs();


public void setKnownOCSPs(OCSPResponseList knownOCSPs);

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.

OutputBytes Property (HTTPClient Class)

Contains the response content.

Syntax

public byte[] getOutputBytes();

Remarks

Use this property to access the content received from the server in response to a prior request.

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

OutputString Property (HTTPClient Class)

Contains the response content.

Syntax

public String getOutputString();

Default Value

""

Remarks

Use this property to access the content received from the server in response to a prior request, as a string.

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

Proxy Property (HTTPClient Class)

The proxy server settings.

Syntax

public ProxySettings getProxy();

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

ReasonPhrase Property (HTTPClient Class)

Contains the Reason Phrase element of the server's response.

Syntax

public String getReasonPhrase();

Default Value

""

Remarks

Use this property to access the reason phrase supplied by the server in its response (such as OK in HTTP 200 OK).

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

RequestHeaders Property (HTTPClient Class)

Contains HTTP request headers.

Syntax

public StringNameValuePairList getRequestHeaders();

Remarks

Use this property to check and/or adjust the HTTP request headers from your HeadersPrepared event handler.

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

RequestParameters Property (HTTPClient Class)

Provides access to common HTTP request properties.

Syntax

public HTTPRequestParameters getRequestParameters();


public void setRequestParameters(HTTPRequestParameters requestParameters);

Remarks

Use this property to configure the HTTP request properties.

This property is not available at design time.

ResponseHeaders Property (HTTPClient Class)

Contains the HTTP server's response headers.

Syntax

public StringNameValuePairList getResponseHeaders();

Remarks

Use this property to check the headers of the HTTP response received from the server. The headers become available as soon as HeadersReceived event is fired.

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

ResponseParameters Property (HTTPClient Class)

Contains the HTTP server's response parameters.

Syntax

public HTTPResponseParameters getResponseParameters();

Remarks

Use this property to access the properties of the received HTTP response.

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

ServerChain Property (HTTPClient Class)

The TLS server's certificate chain.

Syntax

public CertificateList getServerChain();

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 (HTTPClient Class)

Manages network connection settings.

Syntax

public SocketSettings getSocketSettings();

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

StatusCode Property (HTTPClient Class)

Contains the Status Code element of the server's response.

Syntax

public int getStatusCode();

Default Value

0

Remarks

Use this property to access the status code supplied by the server in its response (such as 200 in HTTP 200 OK).

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

TLSSettings Property (HTTPClient Class)

Manages TLS layer settings.

Syntax

public TLSSettings getTLSSettings();

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

TrustedCertificates Property (HTTPClient Class)

A list of trusted certificates for chain validation.

Syntax

public CertificateList getTrustedCertificates();


public void setTrustedCertificates(CertificateList trustedCertificates);

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 than that of 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.

UseDigestAuth Property (HTTPClient Class)

Enables or disables the HTTP Digest authentication.

Syntax

public boolean isUseDigestAuth();


public void setUseDigestAuth(boolean useDigestAuth);

Default Value

False

Remarks

Digest authentication is more advanced than the Basic scheme, as it does not send the username and password in plain text and is immune to replay attacks.

Digest authentication is standardized in RFC 2617.

UseKerberosAuth Property (HTTPClient Class)

Enables Kerberos authentication mechanism.

Syntax

public boolean isUseKerberosAuth();


public void setUseKerberosAuth(boolean useKerberosAuth);

Default Value

False

Remarks

Set this property to true to enable Kerberos (Negotiate) authentication mechanism.

UseNTLMAuth Property (HTTPClient Class)

Enables or disables NTLM authentication.

Syntax

public boolean isUseNTLMAuth();


public void setUseNTLMAuth(boolean useNTLMAuth);

Default Value

False

Remarks

NT LAN Manager (NTLM) authentication relies on Windows credentials to authenticate the user, and requires multiple exchanges between the client and server. Generally it is considered more secure and SSO-friendly than the Digest authentication.

Config Method (Httpclient Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

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

Delete Method (Httpclient Class)

Sends a DELETE request to the server.

Syntax

public void delete(String url);

Remarks

Use this method to send a DELETE request to server. In response to this request, the server may (without any guarantees) delete the resource specified in Url. Most of the servers disable DELETE requests.

If this request fails, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

DoAction Method (Httpclient Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. 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;....

Get Method (Httpclient Class)

Sends a GET request to the server.

Syntax

public void get(String url);

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the received content will be available in OutputBytes and OutputString properties. Otherwise an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

GetBytes Method (Httpclient Class)

Sends a GET request to the server and returns the output.

Syntax

public byte[] getBytes(String url);

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the method returns the received content. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

GetFile Method (Httpclient Class)

Sends a GET request to the server and saves the output to a file.

Syntax

public void getFile(String url, String filename);

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the received content will be saved to Filename. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

GetStream Method (Httpclient Class)

Sends a GET request to the server and saves the output in a stream.

Syntax

public void getStream(String url, java.io.OutputStream outputStream);

Remarks

GET is one of the most widely used HTTP requests. The server responds with the content of the resource specified in Url.

If the request is successful, the method saves the received content to OutputStream. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Head Method (Httpclient Class)

Sends a HEAD request to the server.

Syntax

public void head(String url);

Remarks

HEAD is very similar to GET, with the only difference being that only the headers (but not the content) is returned.

HEAD is often use to retrieve the parameters of the resource, such as its size and modification date. If the request is successful, those details will be available via ResponseParameters and ResponseHeaders properties. Otherwise, an exception will be thrown, and the error details published in StatusCode and ReasonPhrase properties.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Options Method (Httpclient Class)

Sends an OPTIONS request to the server.

Syntax

public void options(String url);

Remarks

This request gets various information about the server such as supported HTTP methods. No content is included in the response.

Post Method (Httpclient Class)

Sends a POST request to the server.

Syntax

public void post(String url, String content);

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the data you need to send via the Content parameter. If Content is omitted, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event.

To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostBytes Method (Httpclient Class)

Sends a POST request to the server.

Syntax

public void postBytes(String url, byte[] contentBytes);

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the data you need to send via the ContentBytes parameter. If content is omitted, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event.

To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostFile Method (Httpclient Class)

Sends a file to the server using a POST request.

Syntax

public void postFile(String url, String filename);

Remarks

POST is used to send data to the remote HTTP endpoint/script. The content to send will be taken from Filename.

To post a web form's data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostStream Method (Httpclient Class)

Sends a POST request to the server.

Syntax

public void postStream(String url, java.io.InputStream inputStream);

Remarks

POST is used to send data to the remote HTTP endpoint/script.

Provide the data you need to send via the InputStream parameter.

To post a web form data (including file attachments to the form) use PostWebForm method.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PostWebForm Method (Httpclient Class)

Posts a web form data to the server.

Syntax

public void postWebForm(String url, String fields, String fileField, String fileName, String contentType);

Remarks

This variant of the POST method provides means to submit a form (as in a web browser) with an optional file attachment. Fields are expected to contain a list of field names and values in "Name=Value" format separated with EOLs. This list can be empty.

If including a file with your request, use the FileField and FileName properties to specify the file field name and the local filename for the uploaded file. Use ContentType to override the default content type chosen by the client, e.g., "application/x-www-form-urlencoded".

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Put Method (Httpclient Class)

Sends a PUT request to the server.

Syntax

public void put(String url, String content);

Remarks

PUT method is used to write data to the server. This method is optional to support and is disabled on most of HTTP servers.

If Content is not present, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event. Note that some servers do not support streaming.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutBytes Method (Httpclient Class)

Sends a PUT request to the server.

Syntax

public void putBytes(String url, byte[] contentBytes);

Remarks

PUT method is used to write data to the server. This method is optional to support and is disabled on most of HTTP servers.

If ContentBytes is not present, and only Url is set, the data will be streamed dynamically using the DynamicDataNeeded event. Note that some servers do not support streaming.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutFile Method (Httpclient Class)

Sends a file to the server using a PUT request.

Syntax

public void putFile(String url, String filename);

Remarks

PUT is an alternative to POST and is used to send data to the remote HTTP endpoint/script. Many servers have this method switched off. The content to send will be taken from Filename.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

PutStream Method (Httpclient Class)

Sends a PUT request to the server.

Syntax

public void putStream(String url, java.io.InputStream inputStream);

Remarks

PUT is an alternative to POST, and is used to send data to the remote HTTP endpoint/script. Many servers have this method switched off.

Provide the data you need to send via the InputStream parameter.

Note that any parameters you intend to pass to this method should be properly encoded before this method is called.

Trace Method (Httpclient Class)

Sends a TRACE request to the server.

Syntax

public void trace(String url);

Remarks

TRACE is a debug command and is typically switched off and/or not supported by web servers.

Cookie Event (Httpclient Class)

Fired to report a received cookie.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void cookie(HttpclientCookieEvent e) {}
  ...
}

public class HttpclientCookieEvent {
  public String cookieText;
}

Remarks

The CookieText parameter contains the text of the cookie.

DocumentBegin Event (Httpclient Class)

Marks the start of the incoming HTML document or file.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void documentBegin(HttpclientDocumentBeginEvent e) {}
  ...
}

public class HttpclientDocumentBeginEvent {
}

Remarks

This event is followed by one or more Progress calls. When the document has been received in full, the DocumentEnd event is fired.

DocumentEnd Event (Httpclient Class)

Marks the successful receipt of the incoming HTML document or file.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void documentEnd(HttpclientDocumentEndEvent e) {}
  ...
}

public class HttpclientDocumentEndEvent {
}

Remarks

This event fires when the document has been received in full.

DynamicDataNeeded Event (Httpclient Class)

Requests a portion of data to be uploaded from the application.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void dynamicDataNeeded(HttpclientDynamicDataNeededEvent e) {}
  ...
}

public class HttpclientDynamicDataNeededEvent {
  public int bytesNeeded;
}

Remarks

If dynamic ('streaming') variants of PUT or POST methods are used, this event is fired periodically to request portions of data to be sent to the server.

When handling this event, assign the next portion of data of BytesNeeded length (or less) to DynamicData. If no more data is available to upload (the whole document has been sent), leave DynamicData empty.

Error Event (Httpclient Class)

Information about errors during data delivery.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void error(HttpclientErrorEvent e) {}
  ...
}

public class HttpclientErrorEvent {
  public int errorCode;
  public String description;
}

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 (Httpclient Class)

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

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void externalSign(HttpclientExternalSignEvent e) {}
  ...
}

public class HttpclientExternalSignEvent {
  public String operationId;
  public String hashAlgorithm;
  public String pars;
  public String data;
  public String signedData;
}

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(); };

HeadersPrepared Event (Httpclient Class)

Fires when the request headers have been formed and are about to be sent to the server.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void headersPrepared(HttpclientHeadersPreparedEvent e) {}
  ...
}

public class HttpclientHeadersPreparedEvent {
}

Remarks

The prepared headers are available in RequestHeaders property. This event provides you the last chance to review/alter them.

HeadersReceived Event (Httpclient Class)

Fires when the HTTP response headers have just been received from the server.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void headersReceived(HttpclientHeadersReceivedEvent e) {}
  ...
}

public class HttpclientHeadersReceivedEvent {
}

Remarks

The received headers are available via the ResponseHeaders property.

Notification Event (Httpclient Class)

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

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void notification(HttpclientNotificationEvent e) {}
  ...
}

public class HttpclientNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class 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.

Progress Event (Httpclient Class)

Fires periodically during the data transfer.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void progress(HttpclientProgressEvent e) {}
  ...
}

public class HttpclientProgressEvent {
  public long total;
  public long current;
  public boolean cancel;
}

Remarks

Use this event to check the progress of an upload or download operation. Total indicates the total number of bytes to be transferred; Current specifies how much data has been transferred so far, and Cancel gives you a chance to cancel the operation.

Redirection Event (Httpclient Class)

Fires when the server suggests a redirect.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void redirection(HttpclientRedirectionEvent e) {}
  ...
}

public class HttpclientRedirectionEvent {
  public String oldURL;
  public String newURL;
  public boolean allowRedirection;
}

Remarks

This event is fired when the server suggests a redirection request (typically via a 301 or 302 response). OldURL indicates the 'from' page, and NewURL indicates the 'to' one. The destination page can be altered by the application if needed. Use AllowRedirection to block undesirable redirects.

Generally, this is a notification event: the component handles redirections automatically. Use the MaxRedirections config property to limit the number of redirection hops.

TLSCertNeeded Event (Httpclient Class)

Fires when a remote TLS party requests a client certificate.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void TLSCertNeeded(HttpclientTLSCertNeededEvent e) {}
  ...
}

public class HttpclientTLSCertNeededEvent {
  public String host;
  public String CANames;
}

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 (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 (Httpclient Class)

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

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void TLSCertValidate(HttpclientTLSCertValidateEvent e) {}
  ...
}

public class HttpclientTLSCertValidateEvent {
  public String serverHost;
  public String serverIP;
  public boolean accept;
}

Remarks

This event is fired during a TLS handshake. Use TLSServerChain property to access the certificate chain. In general case, 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 (Httpclient Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void TLSEstablished(HttpclientTLSEstablishedEvent e) {}
  ...
}

public class HttpclientTLSEstablishedEvent {
  public String host;
  public String version;
  public String ciphersuite;
  public byte[] connectionId;
  public boolean abort;
}

Remarks

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

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

TLSHandshake Event (Httpclient Class)

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

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void TLSHandshake(HttpclientTLSHandshakeEvent e) {}
  ...
}

public class HttpclientTLSHandshakeEvent {
  public String host;
  public boolean abort;
}

Remarks

The class 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 with TLSEstablished event. If the server chooses to request a client certificate, TLSCertNeeded event will also be fired.

TLSPSK Event (Httpclient Class)

Notifies the application about the PSK key exchange.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void TLSPSK(HttpclientTLSPSKEvent e) {}
  ...
}

public class HttpclientTLSPSKEvent {
  public String host;
  public String hint;
}

Remarks

The class 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 (Httpclient Class)

Reports the graceful closure of a TLS connection.

Syntax

public class DefaultHttpclientEventListener implements HttpclientEventListener {
  ...
  public void TLSShutdown(HttpclientTLSShutdownEvent e) {}
  ...
}

public class HttpclientTLSShutdownEvent {
  public String host;
}

Remarks

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

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

public Certificate( bytes,  startIndex,  count,  password);

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.

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

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.

public Certificate( bytes,  startIndex,  count);

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.

public Certificate( path,  password);

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.

public Certificate( certPath,  keyPath,  password);

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.

public Certificate( path);

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

public Certificate( stream);

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

public Certificate( stream,  password);

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

public Certificate( certStream,  keyStream,  password);

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.

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

public ConnectionInfo();

public CRL( bytes,  startIndex,  count);

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.

public CRL( location);

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

public CRL( stream);

Creates a CRL object from data contained in a stream.

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

public ExternalCrypto();

public HTTPRequestParameters();

public HTTPResponseParameters();

public OCSPResponse( bytes,  startIndex,  count);

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.

public OCSPResponse( location);

Downloads an OCSP response from a remote location.

public OCSPResponse( stream);

Initializes the response with the data from a stream.

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

public ProxySettings();

public SocketSettings();

public StringNameValuePair( name,  value);

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

public StringNameValuePair();

Creates an empty name-value object.

TLSSettings Type

A container for TLS connection settings.

Remarks

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

Fields

public TLSSettings();

Config Settings (Httpclient Class)

HTTPClient Config Settings

Base Config Settings

Trappable Errors (Httpclient Class)

HTTPClient Errors