HTTPClient Class
Properties Methods Events Configuration Settings Errors
The HTTPClient class implements client-side functionality of HTTP and HTTPS protocols.
Class Name
SecureBlackbox_HTTPClient
Procedural Interface
secureblackbox_httpclient_open(); secureblackbox_httpclient_close($res); secureblackbox_httpclient_register_callback($res, $id, $function); secureblackbox_httpclient_get_last_error($res); secureblackbox_httpclient_get_last_error_code($res); secureblackbox_httpclient_set($res, $id, $index, $value); secureblackbox_httpclient_get($res, $id, $index); secureblackbox_httpclient_do_config($res, $configurationstring); secureblackbox_httpclient_do_delete($res, $url); secureblackbox_httpclient_do_get($res, $url); secureblackbox_httpclient_do_getbytes($res, $url); secureblackbox_httpclient_do_getfile($res, $url, $filename); secureblackbox_httpclient_do_head($res, $url); secureblackbox_httpclient_do_options($res, $url); secureblackbox_httpclient_do_post($res, $url, $content); secureblackbox_httpclient_do_postbytes($res, $url, $contentbytes); secureblackbox_httpclient_do_postfile($res, $url, $filename); secureblackbox_httpclient_do_postwebform($res, $url, $fields, $filefield, $filename, $contenttype); secureblackbox_httpclient_do_put($res, $url, $content); secureblackbox_httpclient_do_putbytes($res, $url, $contentbytes); secureblackbox_httpclient_do_putfile($res, $url, $filename); secureblackbox_httpclient_do_trace($res, $url);
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;}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.
| BlockedCertCount | The number of records in the BlockedCert arrays. |
| BlockedCertBytes | Returns raw certificate data in DER format. |
| BlockedCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| ClientCertCount | The number of records in the ClientCert arrays. |
| ClientCertBytes | Returns raw certificate data in DER format. |
| ClientCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| ConnInfoAEADCipher | Indicates whether the encryption algorithm used is an AEAD cipher. |
| ConnInfoChainValidationDetails | The details of a certificate chain validation outcome. |
| ConnInfoChainValidationResult | The outcome of a certificate chain validation routine. |
| ConnInfoCiphersuite | The cipher suite employed by this connection. |
| ConnInfoClientAuthenticated | Specifies whether client authentication was performed during this connection. |
| ConnInfoClientAuthRequested | Specifies whether client authentication was requested during this connection. |
| ConnInfoConnectionEstablished | Indicates whether the connection has been established fully. |
| ConnInfoConnectionID | The unique identifier assigned to this connection. |
| ConnInfoDigestAlgorithm | The digest algorithm used in a TLS-enabled connection. |
| ConnInfoEncryptionAlgorithm | The symmetric encryption algorithm used in a TLS-enabled connection. |
| ConnInfoExportable | Indicates whether a TLS connection uses a reduced-strength exportable cipher. |
| ConnInfoKeyExchangeAlgorithm | The key exchange algorithm used in a TLS-enabled connection. |
| ConnInfoKeyExchangeKeyBits | The length of the key exchange key of a TLS-enabled connection. |
| ConnInfoNamedECCurve | The elliptic curve used in this connection. |
| ConnInfoPFSCipher | Indicates whether the chosen ciphersuite provides perfect forward secrecy (PFS). |
| ConnInfoPreSharedIdentityHint | A hint professed by the server to help the client select the PSK identity to use. |
| ConnInfoPublicKeyBits | The length of the public key. |
| ConnInfoResumedSession | Indicates whether a TLS-enabled connection was spawned from another TLS connection. |
| ConnInfoSecureConnection | Indicates whether TLS or SSL is enabled for this connection. |
| ConnInfoServerAuthenticated | Indicates whether server authentication was performed during a TLS-enabled connection. |
| ConnInfoSignatureAlgorithm | The signature algorithm used in a TLS handshake. |
| ConnInfoSymmetricBlockSize | The block size of the symmetric algorithm used. |
| ConnInfoSymmetricKeyBits | The key length of the symmetric algorithm used. |
| ConnInfoTotalBytesReceived | The total number of bytes received over this connection. |
| ConnInfoTotalBytesSent | The total number of bytes sent over this connection. |
| ConnInfoValidationLog | Contains the server certificate's chain validation log. |
| ConnInfoVersion | Indicates the version of SSL/TLS protocol negotiated during this connection. |
| CustomRequest | Specifies a custom request verb. |
| DynamicData | Takes a piece of data to be sent to the server within a dynamic POST or PUT request. |
| ExternalCryptoCustomParams | Custom parameters to be passed to the signing service (uninterpreted). |
| ExternalCryptoData | Additional data to be included in the async state and mirrored back by the requestor. |
| ExternalCryptoExternalHashCalculation | Specifies whether the message hash is to be calculated at the external endpoint. |
| ExternalCryptoHashAlgorithm | Specifies the request's signature hash algorithm. |
| ExternalCryptoKeyID | The ID of the pre-shared key used for DC request authentication. |
| ExternalCryptoKeySecret | The pre-shared key used for DC request authentication. |
| ExternalCryptoMethod | Specifies the asynchronous signing method. |
| ExternalCryptoMode | Specifies the external cryptography mode. |
| ExternalCryptoPublicKeyAlgorithm | Provide public key algorithm here if the certificate is not available on the pre-signing stage. |
| KeepAlivePolicy | Defines the keep-alive handling policy. |
| KnownCertCount | The number of records in the KnownCert arrays. |
| KnownCertBytes | Returns raw certificate data in DER format. |
| KnownCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| KnownCRLCount | The number of records in the KnownCRL arrays. |
| KnownCRLBytes | Returns raw CRL data in DER format. |
| KnownCRLHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| KnownOCSPCount | The number of records in the KnownOCSP arrays. |
| KnownOCSPBytes | Buffer containing raw OCSP response data. |
| KnownOCSPHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| OutputBytes | Contains the response content. |
| OutputString | Contains the response content. |
| ProxyAddress | The IP address of the proxy server. |
| ProxyAuthentication | The authentication type used by the proxy server. |
| ProxyPassword | The password to authenticate to the proxy server. |
| ProxyPort | The port on the proxy server to connect to. |
| ProxyProxyType | The type of the proxy server. |
| ProxyRequestHeaders | Contains HTTP request headers for WebTunnel and HTTP proxy. |
| ProxyResponseBody | Contains the HTTP or HTTPS (WebTunnel) proxy response body. |
| ProxyResponseHeaders | Contains response headers received from an HTTP or HTTPS (WebTunnel) proxy server. |
| ProxyUseIPv6 | Specifies whether IPv6 should be used when connecting through the proxy. |
| ProxyUseProxy | Enables or disables proxy-driven connection. |
| ProxyUsername | Specifies the username credential for proxy authentication. |
| ReasonPhrase | Contains the Reason Phrase element of the server's response. |
| ReqHeaderCount | The number of records in the ReqHeader arrays. |
| ReqHeaderName | The name element in a (name, value) pair. |
| ReqHeaderValue | The value element in a (name, value) pair. |
| ReqParamsAccept | Specifies the Accept header property of the HTTP request. |
| ReqParamsAcceptCharset | Specifies the Accept-Charset header property of the HTTP request. |
| ReqParamsAcceptLanguage | Specifies the Accept-Language header property of the HTTP request. |
| ReqParamsAcceptRangeEnd | This property, in combination with AcceptRangeStart, defines the media-range of the HTTP request. |
| ReqParamsAcceptRangeStart | This property, in combination with AcceptRangeEnd, defines the media-range of the HTTP request. |
| ReqParamsAuthorization | Specifies the Authorization header of the HTTP request. |
| ReqParamsConnection | Specifies the value to pass to the Connection header property of HTTP request. |
| ReqParamsContentLength | Specifies the size of the entity-body of the HTTP request. |
| ReqParamsContentRangeEnd | Specifies the upper bound used in the Content-Range header of the HTTP request. |
| ReqParamsContentRangeFullSize | Specifies the total length of the full entity-body of the HTTP request. |
| ReqParamsContentRangeStart | Specifies the lower bound used in the Content-Range header of the HTTP request. |
| ReqParamsContentType | The Content-Type header property of the HTTP request. |
| ReqParamsCookie | This header is expected to be assigned with cookies previously received from the server and stored by the client. |
| ReqParamsCustomHeaders | Assign any custom HTTP headers to be passed to the server to this property. |
| ReqParamsDate | The date and time of the request. |
| ReqParamsFrom | Contains the From header property of the HTTP request. |
| ReqParamsHost | This property contains the Host header property of the HTTP request. |
| ReqParamsHTTPVersion | Specifies the version of HTTP protocol to use: 1. |
| ReqParamsIfMatch | Contains the If-Match request header property. |
| ReqParamsIfModifiedSince | Contains the If-Modified-Since request header property. |
| ReqParamsIfNoneMatch | Contains the If-None-Match request header property. |
| ReqParamsIfUnmodifiedSince | Contains the If-Unmodified-Since request header property. |
| ReqParamsPassword | Assign this property with the user's password. |
| ReqParamsReferer | The Referer property of the HTTP request header specifies the address of the resource from which the Request-URI was obtained (the referrer). |
| ReqParamsUserAgent | The User-Agent property of the HTTP request provides information about the software that initiates the request. |
| ReqParamsUsername | Assign this property with the user's login name. |
| RespHeaderCount | The number of records in the RespHeader arrays. |
| RespHeaderName | The name element in a (name, value) pair. |
| RespHeaderValue | The value element in a (name, value) pair. |
| RespParamsContentLength | Indicates the length of the response content in bytes. |
| RespParamsDate | The date and time at which the response was generated, in server time, in UTC. |
| RespParamsReasonPhrase | Contains the reason phrase (a human-readable comment) of the request processing status, which corresponds to, and complements, the staus code. |
| RespParamsStatusCode | The server-generated status code of the request processing status. |
| ServerCertCount | The number of records in the ServerCert arrays. |
| ServerCertBytes | Returns raw certificate data in DER format. |
| ServerCertCAKeyID | A unique identifier (fingerprint) of the CA certificate's private key. |
| ServerCertFingerprint | Contains the fingerprint (a hash imprint) of this certificate. |
| ServerCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| ServerCertIssuer | The common name of the certificate issuer (CA), typically a company name. |
| ServerCertIssuerRDN | A collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer. |
| ServerCertKeyAlgorithm | Specifies the public key algorithm of this certificate. |
| ServerCertKeyBits | Returns the length of the public key. |
| ServerCertKeyFingerprint | Returns a fingerprint of the public key contained in the certificate. |
| ServerCertKeyUsage | Indicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set. |
| ServerCertPublicKeyBytes | Contains the certificate's public key in DER format. |
| ServerCertSelfSigned | Indicates whether the certificate is self-signed (root) or signed by an external CA. |
| ServerCertSerialNumber | Returns the certificate's serial number. |
| ServerCertSigAlgorithm | Indicates the algorithm that was used by the CA to sign this certificate. |
| ServerCertSubject | The common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name. |
| ServerCertSubjectKeyID | Contains a unique identifier (fingerprint) of the certificate's private key. |
| ServerCertSubjectRDN | A collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject). |
| ServerCertValidFrom | The time point at which the certificate becomes valid, in UTC. |
| ServerCertValidTo | The time point at which the certificate expires, in UTC. |
| SocketDNSMode | Selects the DNS resolver to use: the class's (secure) built-in one, or the one provided by the system. |
| SocketDNSPort | Specifies the port number to be used for sending queries to the DNS server. |
| SocketDNSQueryTimeout | The timeout (in milliseconds) for each DNS query. |
| SocketDNSServers | The addresses of DNS servers to use for address resolution, separated by commas or semicolons. |
| SocketDNSTotalTimeout | The timeout (in milliseconds) for the whole resolution process. |
| SocketIncomingSpeedLimit | The maximum number of bytes to read from the socket, per second. |
| SocketLocalAddress | The local network interface to bind the socket to. |
| SocketLocalPort | The local port number to bind the socket to. |
| SocketOutgoingSpeedLimit | The maximum number of bytes to write to the socket, per second. |
| SocketTimeout | The maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful. |
| SocketUseIPv6 | Enables or disables IP protocol version 6. |
| StatusCode | Contains the Status Code element of the server's response. |
| TLSAutoValidateCertificates | Specifies whether server-side TLS certificates should be validated automatically using internal validation rules. |
| TLSBaseConfiguration | Selects the base configuration for the TLS settings. |
| TLSCiphersuites | A list of ciphersuites separated with commas or semicolons. |
| TLSECCurves | Defines the elliptic curves to enable. |
| TLSForceResumeIfDestinationChanges | Whether to force TLS session resumption when the destination address changes. |
| TLSPreSharedIdentity | Defines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated. |
| TLSPreSharedKey | Contains the pre-shared for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16. |
| TLSPreSharedKeyCiphersuite | Defines the ciphersuite used for PSK (Pre-Shared Key) negotiation. |
| TLSRenegotiationAttackPreventionMode | Selects renegotiation attack prevention mechanism. |
| TLSRevocationCheck | Specifies the kind(s) of revocation check to perform. |
| TLSSSLOptions | Various SSL (TLS) protocol options, set of cssloExpectShutdownMessage 0x001 Wait for the close-notify message when shutting down the connection cssloOpenSSLDTLSWorkaround 0x002 (DEPRECATED) Use a DTLS version workaround when talking to very old OpenSSL versions cssloDisableKexLengthAlignment 0x004 Do not align the client-side PMS by the RSA modulus size. |
| TLSTLSMode | Specifies the TLS mode to use. |
| TLSUseExtendedMasterSecret | Enables Extended Master Secret Extension, as defined in RFC 7627. |
| TLSUseSessionResumption | Enables or disables TLS session resumption capability. |
| TLSVersions | Th SSL/TLS versions to enable by default. |
| TrustedCertCount | The number of records in the TrustedCert arrays. |
| TrustedCertBytes | Returns raw certificate data in DER format. |
| TrustedCertHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| UseDigestAuth | Enables or disables the HTTP Digest authentication. |
| UseNTLMAuth | Enables or disables NTLM authentication. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
| Config | Sets or retrieves a configuration setting. |
| Delete | Sends a DELETE request to the server. |
| Get | Sends a GET request to the server. |
| GetBytes | Sends a GET request to the server and returns the output. |
| GetFile | Sends a GET request to the server and saves the output to a file. |
| Head | Sends a HEAD request to the server. |
| Options | Sends an OPTIONS request to the server. |
| Post | Sends a POST request to the server. |
| PostBytes | Sends a POST request to the server. |
| PostFile | Sends a file to the server using a POST request. |
| PostWebForm | Posts a web form data to the server. |
| Put | Sends a PUT request to the server. |
| PutBytes | Sends a PUT request to the server. |
| PutFile | Sends a file to the server using a PUT request. |
| Trace | Sends a TRACE request to the server. |
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.
| CertificateValidate | Fires when the server's TLS certificate has to be validated. |
| Cookie | Fired to report a received cookie. |
| DocumentBegin | Marks the start of the incoming HTML document or file. |
| DocumentEnd | Marks the successful receipt of the incoming HTML document or file. |
| DynamicDataNeeded | Requests a portion of data to be uploaded from the application. |
| Error | Information about errors during data delivery. |
| ExternalSign | Handles remote or external signing initiated by the SignExternal method or other source. |
| HeadersPrepared | Fires when the request headers have been formed and are about to be sent to the server. |
| HeadersReceived | Fires when the HTTP response headers have just been received from the server. |
| Notification | This event notifies the application about an underlying control flow event. |
| Progress | Fires periodically during the data transfer. |
| Redirection | Fires when the server suggests a redirect. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
| CacheStreamOutput | Tells the class whether to cache stream- and file-bound responses in the class. |
| ForceNTLMAuth | Activates and enforces NTLM authentication. |
| IgnoreSystemTrust | Whether trusted Windows Certificate Stores should be treated as trusted. |
| IgnoreUnknownTransferEncodings | All incoming responses with unknown transfer encodings are ignored if this property is true. |
| MaxRedirections | The maximum number of HTTP redirects. |
| PersistentAuthHeader | Whether to resend NTLM negotiation on every request. |
| RequestCompressionGZip | Ask server to use GZip compression. |
| RequestCompressionLevel | Ask server to use the specified compression level. |
| SendBufferSize | Size of send buffer in bytes. |
| SuppressRedirectionContent | Whether to suppress the redirection content. |
| TempPath | Path for storing temporary files. |
| TolerateMinorChainIssues | Whether to tolerate minor chain issues. |
| Use100Continue | Whether to use 100-continue for POST and PUT commands. |
| UseCompression | Whether to use GZip compression. |
| UseMicrosoftCTL | Enables or disables automatic use of Microsoft online certificate trust list. |
| UseSystemCertificates | Enables or disables the use of the system certificates. |
| CheckKeyIntegrityBeforeUse | Enables or disable private key integrity check before use. |
| CookieCaching | Specifies whether a cookie cache should be used for HTTP(S) transports. |
| Cookies | Gets or sets local cookies for the class (supported for HTTPClient, RESTClient and SOAPClient only). |
| DefDeriveKeyIterations | Specifies the default key derivation algorithm iteration count. |
| EnableClientSideSSLFFDHE | Enables or disables finite field DHE key exchange support in TLS clients. |
| GlobalCookies | Gets or sets global cookies for all the HTTP transports. |
| HttpUserAgent | Specifies the user agent name to be used by all HTTP clients. |
| LogDestination | Specifies the debug log destination. |
| LogDetails | Specifies the debug log details to dump. |
| LogFile | Specifies the debug log filename. |
| LogFilters | Specifies the debug log filters. |
| LogFlushMode | Specifies the log flush mode. |
| LogLevel | Specifies the debug log level. |
| LogMaxEventCount | Specifies the maximum number of events to cache before further action is taken. |
| LogRotationMode | Specifies the log rotation mode. |
| MaxASN1BufferLength | Specifies the maximal allowed length for ASN.1 primitive tag data. |
| MaxASN1TreeDepth | Specifies the maximal depth for processed ASN.1 trees. |
| OCSPHashAlgorithm | Specifies the hash algorithm to be used to identify certificates in OCSP requests. |
| UseOwnDNSResolver | Specifies whether the client classes should use own DNS resolver. |
| UseSharedSystemStorages | Specifies whether the validation engine should use a global per-process copy of the system certificate stores. |
| UseSystemOAEPAndPSS | Enforces or disables the use of system-driven RSA OAEP and PSS computations. |
| UseSystemRandom | Enables or disables the use of the OS PRNG. |