paa-http-client-curl.h File Reference

#include "apr.h"
#include "apr_pools.h"
#include "paa-config.h"
#include "paa-http-client.h"

Go to the source code of this file.

Functions
apr_status_t	paa_http_client_curl_create (apr_pool_t *pool, const paa_config *config, const char *cert_path, char **err_msg, const paa_http_client **impl)
apr_status_t	paa_curl_create_cert_file (apr_pool_t *pool, const paa_config *config, const char *cert_dir, const char **output)

Detailed Description

Header for the paa_http_client curl implementation

Function Documentation

apr_status_t paa_curl_create_cert_file	(	apr_pool_t *	pool,
		const paa_config *	config,
		const char *	cert_dir,
		const char **	output
	)

Extracts the truststore property from the configuration and places it in a unique file in the specified certificate directory.

Note: this function may have side-effects on the local filesystem when the certificate is extracted from the configuration and placed in cert_dir. Multiple processes or threads calling this function concurrently should synchronize before calling this function to ensure only one process/thread is executing this function at a time. This synchronization will ensure nondeterministic behavior does not occur due to coordination on access to the local filesystem.

Parameters

pool	the pool in which the output path will be allocated
config	the configuration in which the truststore property resides
cert_dir	the directory in which the certificate should be extracted from the configuration (no trailing slash) and only using forward slashes as the path element separator.
output	the path to the certificate, prefixed with the specified cert directory. Populated on success. The value will be NULL if the specified configuration does not contain a truststore property.

Returns

APR_SUCCESS on success

APR_STATUS_IS_EEXIST when the certificate already exists

error otherwise

apr_status_t paa_http_client_curl_create	(	apr_pool_t *	pool,
		const paa_config *	config,
		const char *	cert_path,
		char **	err_msg,
		const paa_http_client **	impl
	)

Creates an instance of an HTTP client that uses curl.

This implementation expects the following keys from the configuration:

• agent.engine.configuration.scheme (required)
  • The scheme to use for connecting to PingAccess. Must be http or https.
• agent.engine.configuration.host (required)
  • The hostname to use for connecting to PingAccess.
• agent.engine.configuration.port (required)
  • The port to use for connecting to PingAccess.
• agent.engine.configuration.bootstrap.truststore (optional)
  • The root certificate to trust when using https to connect to PingAccess. The value should be a base64 version of the certificate.
  • If unspecified, the system truststore will be used.
• agent.engine.configuration.ciphers (optional)
  • The ciphers to use when connecting to PingAccess using https. The format of the ciphers depends on the underlying SSL implementation used by curl.
  • If unspecified, the defaults of the underlying SSL implementation are used.
• agent.engine.configuration.maxConnections (required)
  • The number of connections to keep open to a single PingAccess engine
• agent.engine.configuration.connectTimeout (required)
  • The timeout in milliseconds for connecting to PingAccess.
• agent.engine.configuration.timeout (required)
  • The timeout in milliseconds for receiving an HTTP response from PingAccess.
• agent.engine.configuration.dnsIPv4Only (optional)
  • When non-zero, only use IPv4 DNS records when resolving hostnames.
  • The default is 0
• agent.engine.configuration.checkCertRevocation (optional)
  • When non-zero, enable certificate revocation checking if supported by the underlying TLS/SSL library used by curl.
  • The default is 1
• agent.engine.configuration.noCACerts (optional)
  • When non-zero and agent.engine.configuration.bootstrap.truststore is not set, configure curl to not use the system-provided CA certificates file.
  • This option will only have an effect when the underlying TLS/SSL library used by curl uses a file to provide the system-provided CA certificates.
  • The default is 0
• agent.engine.configuration.failover.hosts (optional)
  • An ordered, comma-separated list of host:port combinations defining the backup PingAccess policy servers.
  • Defaults to unset. Failover functionality is only enabled when this property is present
• agent.engine.configuration.failover.failedRetryTimeout (optional)
  • The timeout in milliseconds to wait before retrying an unavailable policy server.
  • A positive integer
  • Defaults to 60000
• agent.engine.configuration.failover.maxRetries
  • The max number of times an agent request will be attempted before failing over to a backup policy server and marking the current policy server as unavailable
  • A non-negative integer
  • Defaults to 5

Parameters

pool	the pool in which to allocate the structure
config	the configuration used to configure the implementation
cert_path	the full path to the certificate containing the trust store, only using forward slashes as the path element separator. Can be NULL if the system trust store should be utilized or if HTTPS is not used.
err_msg	an error message, populated on failure
impl	the output, populated on success; NULL on failure

Returns

APR_SUCCESS on success

error otherwise; err_msg contains a description of the specific error