Package com.pdftools

Class HttpClientHandler

java.lang.Object

com.pdftools.internal.NativeBase

com.pdftools.internal.NativeObject

com.pdftools.HttpClientHandler

public class HttpClientHandler
extends NativeObject

The handler and options for communication to remote server

This class can be used to configure HTTP and HTTPS communication.

Also see Sdk.getProxy() for the product wide proxy configuration.

For HTTPS (SSL/TLS) communication, the server certificate's trustworthiness is verified using the system's default trust store (CA certificate store). If the server certificate's trustworthiness cannot be determined, the connection to the server is aborted.

The default trust store is:

• Windows:

  The Windows certificate store for "Trusted Root Certification Authorities" is used. You can manually install the root certificate of a private CA on a computer by using the CertMgr tool. The certificate store is only available if the user profile has been loaded.

• Linux:

  The certificates available in CAfile and CApath are trusted:

  • CAfile:

    The file can contain a concatenated sequence of CA certificates in PEM format.

    The SDK searches for the file at the following locations:

    • The file of your local OpenSSL installation (if libssl.so is found), or
    • the environment variable SSL_CERT_FILE, or
    • the default location /etc/ssl/cert.pem.

  • CApath:

    A directory containing CA certificates in PEM format. The files are looked up by the CA subject name hash value, e.g. 9d66eef0.0.

    The SDK searches for the directory at the following locations:

    • The directory of your local OpenSSL installation (if libssl.so is found), or
    • the environment variable SSL_CERT_DIR, or
    • the default location /etc/ssl/certs/.

• macOS:

  The trusted certificates from the macOS keychain are used. You can manually install the root certificate of a private CA by dragging the certificate file onto the Keychain Access app.

You can add more certificates to the trust store using addTrustedCertificate(com.pdftools.sys.Stream).

Instances of this class can be used in multiple threads concurrently, as long as they are not modified concurrently.

Constructor Summary

Constructors

Constructor	Description
HttpClientHandler()	The default values of newly created objects are not copied from the default handler Sdk.getHttpClientHandler(), but are as described in this documentation.

Method Summary

Modifier and Type	Method	Description
void	addTrustedCertificate(Stream cert)	Add a certificate to the trust store
boolean	getSslVerifyServerCertificate()	Verify the server certificate for SSL/TLS (Getter)
void	setClientCertificate(Stream archive, java.lang.String password)	Set the SSL/TLS client certificate as PFX (PKCS#12) archive
void	setClientCertificateAndKey(Stream cert, Stream key, java.lang.String password)	Set the SSL/TLS client certificate and private key
void	setSslVerifyServerCertificate(boolean value)	Verify the server certificate for SSL/TLS (Setter)

Methods inherited from class com.pdftools.internal.NativeObject

equals, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HttpClientHandler

public HttpClientHandler()

The default values of newly created objects are not copied from the default handler Sdk.getHttpClientHandler(), but are as described in this documentation.

Method Detail

setClientCertificate

public void setClientCertificate(Stream archive,
                                 java.lang.String password)
                          throws CorruptException,
                                 PasswordException

Set the SSL/TLS client certificate as PFX (PKCS#12) archive

The file must contain the certificate itself, all certificates of the trust chain, and the private key.

Parameters:

archive - The SSL client certificate in PKCS#12 format (.p12, .pfx)

password - The password required to decrypt the private key of the archive

Throws:

CorruptException - The PFX (PKCS#12) archive is corrupt and cannot be read.

PasswordException - The password is invalid.

java.lang.IllegalArgumentException - The PFX (PKCS#12) archive is incomplete.

java.lang.IllegalArgumentException - if archive is null

setClientCertificateAndKey

public void setClientCertificateAndKey(Stream cert,
                                       Stream key,
                                       java.lang.String password)
                                throws CorruptException,
                                       PasswordException

Set the SSL/TLS client certificate and private key

The file must contain the certificate and its private key. It is also recommended to include all certificates of the trust chain.

Parameters:

cert - The certificate may be in either PEM (.pem, ASCII text) or DER (.cer, binary) form.

key - The encrypted private key of the certificate must be in PEM (ASCII text) form (.pem).

password - The password required to decrypt the private key.

Throws:

PasswordException - The password is invalid.

CorruptException - The certificate or key cannot be read.

java.lang.IllegalArgumentException - if cert is null

java.lang.IllegalArgumentException - if key is null

addTrustedCertificate

public void addTrustedCertificate(Stream cert)
                           throws CorruptException

Add a certificate to the trust store

Add a certificate to the trust store of this HttpClientHandler instance. The certificates in the trust store are used to verify the certificate of the SSL/TLS server (see HttpClientHandler). You should add trusted certification authorities (Root CA) certificates to the trust store. However, you can also add server certificates (e.g. self-signed certificates) and intermediate CA certificates.

Parameters:

cert - The certificate may be in either PEM (.pem, ASCII text) or DER (.cer, binary) form.

Throws:

CorruptException - The certificate cannot be read.

java.lang.IllegalArgumentException - if cert is null

getSslVerifyServerCertificate

public boolean getSslVerifyServerCertificate()

Verify the server certificate for SSL/TLS (Getter)

If true the server certificate's trustworthiness is verified. If the verification process fails, the handshake is immediately terminated and the connection is aborted. The verification requires a trust store; otherwise, verification always fails.

Default: true

setSslVerifyServerCertificate

public void setSslVerifyServerCertificate(boolean value)

Verify the server certificate for SSL/TLS (Setter)

If true the server certificate's trustworthiness is verified. If the verification process fails, the handshake is immediately terminated and the connection is aborted. The verification requires a trust store; otherwise, verification always fails.

Default: true