SecureBlackbox 2020 Python Edition

Questions / Feedback?

HTTPClient Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

class 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 on_certificate_validate event. This event will fire whenever a server certificate validation needs to be performed.

Use client_chain 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 on_headers_prepared 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 request_headers collection. Note: the headers can only be modified from the on_headers_prepared 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, get_bytes, or get_file) 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.

blocked_cert_countThe number of records in the BlockedCert arrays.
blocked_cert_bytesReturns raw certificate data in DER format.
blocked_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
client_cert_countThe number of records in the ClientCert arrays.
client_cert_bytesReturns raw certificate data in DER format.
client_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
conn_info_aead_cipherIndicates whether the encryption algorithm used is an AEAD cipher.
conn_info_chain_validation_detailsThe details of a certificate chain validation outcome.
conn_info_chain_validation_resultThe outcome of a certificate chain validation routine.
conn_info_ciphersuiteThe cipher suite employed by this connection.
conn_info_client_authenticatedSpecifies whether client authentication was performed during this connection.
conn_info_client_auth_requestedSpecifies whether client authentication was requested during this connection.
conn_info_connection_establishedIndicates whether the connection has been established fully.
conn_info_connection_idThe unique identifier assigned to this connection.
conn_info_digest_algorithmThe digest algorithm used in a TLS-enabled connection.
conn_info_encryption_algorithmThe symmetric encryption algorithm used in a TLS-enabled connection.
conn_info_exportableIndicates whether a TLS connection uses a reduced-strength exportable cipher.
conn_info_key_exchange_algorithmThe key exchange algorithm used in a TLS-enabled connection.
conn_info_key_exchange_key_bitsThe length of the key exchange key of a TLS-enabled connection.
conn_info_named_ec_curveThe elliptic curve used in this connection.
conn_info_pfs_cipherIndicates whether the chosen ciphersuite provides perfect forward secrecy (PFS).
conn_info_pre_shared_identity_hintA hint professed by the server to help the client select the PSK identity to use.
conn_info_public_key_bitsThe length of the public key.
conn_info_resumed_sessionIndicates whether a TLS-enabled connection was spawned from another TLS connection.
conn_info_secure_connectionIndicates whether TLS or SSL is enabled for this connection.
conn_info_server_authenticatedIndicates whether server authentication was performed during a TLS-enabled connection.
conn_info_signature_algorithmThe signature algorithm used in a TLS handshake.
conn_info_symmetric_block_sizeThe block size of the symmetric algorithm used.
conn_info_symmetric_key_bitsThe key length of the symmetric algorithm used.
conn_info_total_bytes_receivedThe total number of bytes received over this connection.
conn_info_total_bytes_sentThe total number of bytes sent over this connection.
conn_info_validation_logContains the server certificate's chain validation log.
conn_info_versionIndicates the version of SSL/TLS protocol negotiated during this connection.
custom_requestSpecifies a custom request verb.
dynamic_dataTakes a piece of data to be sent to the server within a dynamic POST or PUT request.
external_crypto_custom_paramsCustom parameters to be passed to the signing service (uninterpreted).
external_crypto_dataAdditional data to be included in the async state and mirrored back by the requestor.
external_crypto_external_hash_calculationSpecifies whether the message hash is to be calculated at the external endpoint.
external_crypto_hash_algorithmSpecifies the request's signature hash algorithm.
external_crypto_key_idThe ID of the pre-shared key used for DC request authentication.
external_crypto_key_secretThe pre-shared key used for DC request authentication.
external_crypto_methodSpecifies the asynchronous signing method.
external_crypto_modeSpecifies the external cryptography mode.
external_crypto_public_key_algorithmProvide public key algorithm here if the certificate is not available on the pre-signing stage.
keep_alive_policyDefines the keep-alive handling policy.
known_cert_countThe number of records in the KnownCert arrays.
known_cert_bytesReturns raw certificate data in DER format.
known_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
known_crl_countThe number of records in the KnownCRL arrays.
known_crl_bytesReturns raw CRL data in DER format.
known_crl_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
known_ocsp_countThe number of records in the KnownOCSP arrays.
known_ocsp_bytesBuffer containing raw OCSP response data.
known_ocsp_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
output_bytesContains the response content.
output_stringContains the response content.
proxy_addressThe IP address of the proxy server.
proxy_authenticationThe authentication type used by the proxy server.
proxy_passwordThe password to authenticate to the proxy server.
proxy_portThe port on the proxy server to connect to.
proxy_proxy_typeThe type of the proxy server.
proxy_request_headersContains HTTP request headers for WebTunnel and HTTP proxy.
proxy_response_bodyContains the HTTP or HTTPS (WebTunnel) proxy response body.
proxy_response_headersContains response headers received from an HTTP or HTTPS (WebTunnel) proxy server.
proxy_use_i_pv6Specifies whether IPv6 should be used when connecting through the proxy.
proxy_use_proxyEnables or disables proxy-driven connection.
proxy_usernameSpecifies the username credential for proxy authentication.
reason_phraseContains the Reason Phrase element of the server's response.
req_header_countThe number of records in the ReqHeader arrays.
req_header_nameThe name element in a (name, value) pair.
req_header_valueThe value element in a (name, value) pair.
req_params_acceptSpecifies the Accept header property of the HTTP request.
req_params_accept_charsetSpecifies the Accept-Charset header property of the HTTP request.
req_params_accept_languageSpecifies the Accept-Language header property of the HTTP request.
req_params_accept_range_endThis property, in combination with AcceptRangeStart, defines the media-range of the HTTP request.
req_params_accept_range_startThis property, in combination with AcceptRangeEnd, defines the media-range of the HTTP request.
req_params_authorizationSpecifies the Authorization header of the HTTP request.
req_params_connectionSpecifies the value to pass to the Connection header property of HTTP request.
req_params_content_lengthSpecifies the size of the entity-body of the HTTP request.
req_params_content_range_endSpecifies the upper bound used in the Content-Range header of the HTTP request.
req_params_content_range_full_sizeSpecifies the total length of the full entity-body of the HTTP request.
req_params_content_range_startSpecifies the lower bound used in the Content-Range header of the HTTP request.
req_params_content_typeThe Content-Type header property of the HTTP request.
req_params_cookieThis header is expected to be assigned with cookies previously received from the server and stored by the client.
req_params_custom_headersAssign any custom HTTP headers to be passed to the server to this property.
req_params_dateThe date and time of the request.
req_params_fromContains the From header property of the HTTP request.
req_params_hostThis property contains the Host header property of the HTTP request.
req_params_http_versionSpecifies the version of HTTP protocol to use: 1.
req_params_if_matchContains the If-Match request header property.
req_params_if_modified_sinceContains the If-Modified-Since request header property.
req_params_if_none_matchContains the If-None-Match request header property.
req_params_if_unmodified_sinceContains the If-Unmodified-Since request header property.
req_params_passwordAssign this property with the user's password.
req_params_refererThe Referer property of the HTTP request header specifies the address of the resource from which the Request-URI was obtained (the referrer).
req_params_user_agentThe User-Agent property of the HTTP request provides information about the software that initiates the request.
req_params_usernameAssign this property with the user's login name.
resp_header_countThe number of records in the RespHeader arrays.
resp_header_nameThe name element in a (name, value) pair.
resp_header_valueThe value element in a (name, value) pair.
resp_params_content_lengthIndicates the length of the response content in bytes.
resp_params_dateThe date and time at which the response was generated, in server time, in UTC.
resp_params_reason_phraseContains the reason phrase (a human-readable comment) of the request processing status, which corresponds to, and complements, the staus code.
resp_params_status_codeThe server-generated status code of the request processing status.
server_cert_countThe number of records in the ServerCert arrays.
server_cert_bytesReturns raw certificate data in DER format.
server_cert_ca_key_idA unique identifier (fingerprint) of the CA certificate's private key.
server_cert_fingerprintContains the fingerprint (a hash imprint) of this certificate.
server_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
server_cert_issuerThe common name of the certificate issuer (CA), typically a company name.
server_cert_issuer_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer.
server_cert_key_algorithmSpecifies the public key algorithm of this certificate.
server_cert_key_bitsReturns the length of the public key.
server_cert_key_fingerprintReturns a fingerprint of the public key contained in the certificate.
server_cert_key_usageIndicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set.
server_cert_public_key_bytesContains the certificate's public key in DER format.
server_cert_self_signedIndicates whether the certificate is self-signed (root) or signed by an external CA.
server_cert_serial_numberReturns the certificate's serial number.
server_cert_sig_algorithmIndicates the algorithm that was used by the CA to sign this certificate.
server_cert_subjectThe common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name.
server_cert_subject_key_idContains a unique identifier (fingerprint) of the certificate's private key.
server_cert_subject_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject).
server_cert_valid_fromThe time point at which the certificate becomes valid, in UTC.
server_cert_valid_toThe time point at which the certificate expires, in UTC.
socket_dns_modeSelects the DNS resolver to use: the class's (secure) built-in one, or the one provided by the system.
socket_dns_portSpecifies the port number to be used for sending queries to the DNS server.
socket_dns_query_timeoutThe timeout (in milliseconds) for each DNS query.
socket_dns_serversThe addresses of DNS servers to use for address resolution, separated by commas or semicolons.
socket_dns_total_timeoutThe timeout (in milliseconds) for the whole resolution process.
socket_incoming_speed_limitThe maximum number of bytes to read from the socket, per second.
socket_local_addressThe local network interface to bind the socket to.
socket_local_portThe local port number to bind the socket to.
socket_outgoing_speed_limitThe maximum number of bytes to write to the socket, per second.
socket_timeoutThe maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.
socket_use_i_pv6Enables or disables IP protocol version 6.
status_codeContains the Status Code element of the server's response.
tls_auto_validate_certificatesSpecifies whether server-side TLS certificates should be validated automatically using internal validation rules.
tls_base_configurationSelects the base configuration for the TLS settings.
tls_ciphersuitesA list of ciphersuites separated with commas or semicolons.
tlsec_curvesDefines the elliptic curves to enable.
tls_force_resume_if_destination_changesWhether to force TLS session resumption when the destination address changes.
tls_pre_shared_identityDefines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated.
tls_pre_shared_keyContains the pre-shared for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16.
tls_pre_shared_key_ciphersuiteDefines the ciphersuite used for PSK (Pre-Shared Key) negotiation.
tls_renegotiation_attack_prevention_modeSelects renegotiation attack prevention mechanism.
tls_revocation_checkSpecifies the kind(s) of revocation check to perform.
tlsssl_optionsVarious 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.
tlstls_modeSpecifies the TLS mode to use.
tls_use_extended_master_secretEnables Extended Master Secret Extension, as defined in RFC 7627.
tls_use_session_resumptionEnables or disables TLS session resumption capability.
tls_versionsTh SSL/TLS versions to enable by default.
trusted_cert_countThe number of records in the TrustedCert arrays.
trusted_cert_bytesReturns raw certificate data in DER format.
trusted_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
use_digest_authEnables or disables the HTTP Digest authentication.
use_ntlm_authEnables 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.

configSets or retrieves a configuration setting.
deleteSends a DELETE request to the server.
getSends a GET request to the server.
get_bytesSends a GET request to the server and returns the output.
get_fileSends a GET request to the server and saves the output to a file.
headSends a HEAD request to the server.
optionsSends an OPTIONS request to the server.
postSends a POST request to the server.
post_bytesSends a POST request to the server.
post_fileSends a file to the server using a POST request.
post_web_formPosts a web form data to the server.
putSends a PUT request to the server.
put_bytesSends a PUT request to the server.
put_fileSends a file to the server using a PUT request.
traceSends 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.

on_certificate_validateFires when the server's TLS certificate has to be validated.
on_cookieFired to report a received cookie.
on_document_beginMarks the start of the incoming HTML document or file.
on_document_endMarks the successful receipt of the incoming HTML document or file.
on_dynamic_data_neededRequests a portion of data to be uploaded from the application.
on_errorInformation about errors during data delivery.
on_external_signHandles remote or external signing initiated by the SignExternal method or other source.
on_headers_preparedFires when the request headers have been formed and are about to be sent to the server.
on_headers_receivedFires when the HTTP response headers have just been received from the server.
on_notificationThis event notifies the application about an underlying control flow event.
on_progressFires periodically during the data transfer.
on_redirectionFires 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.

CacheStreamOutputTells the class whether to cache stream- and file-bound responses in the class.
ForceNTLMAuthActivates and enforces NTLM authentication.
IgnoreSystemTrustWhether trusted Windows Certificate Stores should be treated as trusted.
IgnoreUnknownTransferEncodingsAll incoming responses with unknown transfer encodings are ignored if this property is true.
MaxRedirectionsThe maximum number of HTTP redirects.
PersistentAuthHeaderWhether to resend NTLM negotiation on every request.
RequestCompressionGZipAsk server to use GZip compression.
RequestCompressionLevelAsk server to use the specified compression level.
SendBufferSizeSize of send buffer in bytes.
SuppressRedirectionContentWhether to suppress the redirection content.
TempPathPath for storing temporary files.
TolerateMinorChainIssuesWhether to tolerate minor chain issues.
Use100ContinueWhether to use 100-continue for POST and PUT commands.
UseCompressionWhether to use GZip compression.
UseMicrosoftCTLEnables or disables automatic use of Microsoft online certificate trust list.
UseSystemCertificatesEnables or disables the use of the system certificates.
CheckKeyIntegrityBeforeUseEnables or disable private key integrity check before use.
CookieCachingSpecifies whether a cookie cache should be used for HTTP(S) transports.
CookiesGets or sets local cookies for the class (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterationsSpecifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHEEnables or disables finite field DHE key exchange support in TLS clients.
GlobalCookiesGets or sets global cookies for all the HTTP transports.
HttpUserAgentSpecifies the user agent name to be used by all HTTP clients.
LogDestinationSpecifies the debug log destination.
LogDetailsSpecifies the debug log details to dump.
LogFileSpecifies the debug log filename.
LogFiltersSpecifies the debug log filters.
LogFlushModeSpecifies the log flush mode.
LogLevelSpecifies the debug log level.
LogMaxEventCountSpecifies the maximum number of events to cache before further action is taken.
LogRotationModeSpecifies the log rotation mode.
MaxASN1BufferLengthSpecifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepthSpecifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithmSpecifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolverSpecifies whether the client classes should use own DNS resolver.
UseSharedSystemStoragesSpecifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSSEnforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandomEnables or disables the use of the OS PRNG.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 Python Edition - Version 20.0 [Build 8165]