Understanding the Synergy HTTP document transport API

The Synergy HTTP document transport API enables you to send and receive documents via HTTP or HTTPS from within your Synergy program.

This topic includes the following:

What is HTTP?

What is HTTPS?

What is OpenSSL?

Using the HTTP document transport API

Transmitting data securely via HTTPS

Error messages

What is HTTP?

HTTP, which stands for HyperText Transfer Protocol, is a communication protocol for sending information via sockets. This information can be any type of data and is generically referred to as a “document.” The underlying protocol for the World Wide Web, HTTP defines how messages are formatted and transmitted and what actions servers and clients should take in response to commands.

What is HTTPS?

HTTPS, or secure HTTP, is an extension to HTTP that enables you to securely transmit sensitive data over a network to a server (most commonly a web server). It uses Netscape’s Secure Sockets Layer (SSL) as a sublayer under its regular HTTP application layering to encrypt and decrypt user requests as well as documents that are returned by the server. For example, if you do your banking online, the URL for the log‑in page and any other account information you view will start with https://. If you submit a form to transfer funds, your browser’s HTTPS sublayer will encrypt it, the server will acknowledge the request on the same connection with an equally encrypted reply, and then your browser’s HTTPS sublayer will decrypt the acknowledgement for you.

HTTPS and SSL support the use of X.509 digital certificates from the server so that, if necessary, a user can authenticate the sender. A digital certificate is like an electronic ID card that establishes your credentials when doing business or other transactions on the Web. If you want to send encrypted messages, you can request a digital certificate from a certificate authority (CA). The CA digitally creates and issues a certificate that contains your name, a serial number, the expiration dates, a copy of the certificate holder’s public key (used for encrypting messages and digital signatures), and the digital signature of the certificate authority so that a recipient can verify the certificate is real. The recipient of an encrypted message uses the CA’s public key to decrypt the digital certificate attached to the message, verifies it as being issued by the CA, and gets the sender’s public key and other information from the certificate, which enables the recipient to send an encrypted reply. X.509 is the most widely used standard for defining digital certificates.

Important

Some countries are legally restricted from using HTTPS support, and it is illegal to export strong encryption to those countries. Refer to the encryption section of www.bis.doc.gov for current U.S. regulations. You can disable Synergy HTTPS support on a site‑by‑site basis by removing the HTTPS runtime support DLL. The HTTPS runtime support DLL files installed with your Synergy/DE distribution are httpslib.dll (Windows), httpslib.so (UNIX), and httpslib.exe (OpenVMS).

Important

Note that SSL 2 and SSL 3 protocols are not secure, and TLS 1 has known vulnerabilities. We recommend using TLS 1.1 or TLS 1.2 for secure sites. For more information, see Section 3.1 in nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800‑52r1.pdf. TLS 1.1 and TLS 1.2 are available on OpenSSL 1.0.1.

What is OpenSSL?

The Synergy HTTP document transport API interfaces with a third‑party library, OpenSSL, to provide SSL support. You must install OpenSSL to use HTTPS.

Installing OpenSSL

Follow these steps to install OpenSSL. For details on which version of OpenSSL is required for your operating system, see OpenSSL requirements. For information on OpenSSL, see Synergex KnowledgeBase article 100001979.

1. Obtain the OpenSSL libraries.
2. Ensure the OpenSSL shared libraries are in the correct location and were added to the correct path.

Once OpenSSL is installed, you can use the openssl command line utility to create a certificate request and key file, append a key file to the created certificate, establish a local CA for testing purposes, and more. Instructions for some of these tasks are provided in Using the HTTP document transport API and Transmitting data securely via HTTPS.

Additional documentation for the openssl utility can be found in the openssl manpages and at www.openssl.org/docs/. We also highly recommend the book Network Security with OpenSSL by John Viega, Matt Messier, and Pravir Chandra. If you are new to HTTPS, a book that provides a good high‑level description of SSL, certificates, and encryption is SSL and TLS Essentials: Securing the Web by Stephen Thomas.

Using the HTTP document transport API

Using the HTTP document transport API, a Synergy program, posing as an HTTP/HTTPS client, is able to send or receive data from an HTTP/HTTPS server. Conversely, a Synergy program can pose as an HTTP/HTTPS server to receive data from an HTTP/HTTPS client and then send data to that client to satisfy the client’s request.

This API uses the TCP/IP network protocol.

Important

You must include the synxml.def file, which defines some of the standard HTTP status codes and the text associated with these codes, to use the %HTTP_xxx routines.

URIs

Before you begin accessing or developing an HTTP or HTTPS server, you must know the URI (Uniform Resource Indicator) of the resource to be requested. The URI consists of

username:password@

Example: “bsmith:iq497j@”

Important

For security reasons, we do not recommend passing username:password as clear text in an HTTP packet.

If sending to a Synergy HTTP/HTTPS server, this can be a path or logical and filename. Examples:

“http://myServer:3507/DBLDIR:afile.txt”

“http://myName:myPassword@myServer:3507/c:/location/afile.txt”

If sending to a web server (such as IIS or Apache), location is a virtual directory set up on the web server, plus the page you want. Examples:

“http://myServer/location/file.jsp”

“http://myServer/location/file.asp”

For the client, you must build the URI with this information to send to the server. For the server, you must parse the specified URI to get the resource name and location.

A URI can have a maximum of 2000 bytes. URIs that are longer than 2000 bytes will be truncated.

The HTTP document transport API automatically escapes certain characters, such as spaces, in the URI when it sends a request to a server, and it also unescapes any escaped characters upon receiving a request from a client. (See the Escape Codes for Characters in a Memory Handle table for a list of characters that are escaped and their corresponding escape codes.) For example, “http://server/hello there.html” becomes “http://server/hello%20there.html”. To disable automatic escaping, set HTTP_NOESCAPE. (See HTTP_NOESCAPE.)

Note

The Synergy OPEN statement does not allow escape characters in a file specification. Therefore, if your program contains logic that uses part of the URI as the filename to save the handle data to, you may encounter problems on OPEN if the URI contains escape characters.

Memory handles

All memory that you allocate for the body of an HTTP/HTTPS transmission must be allocated with the DM_STATIC option of the %MEM_PROC routine. This memory must be global so it can be manipulated at different levels within the program. A memory allocation error occurs if a memory handle is not allocated with DM_STATIC.

All memory handle and length arguments (handle and length) are required arguments to the method calls. The memory handles are resized to the needed length by the %HTTP_xxx methods, and the correct length is returned.

In Synergy .NET, make sure that you explicitly close channels and free global memory handles. Implicit program or AppDomain shutdown does not ensure clean socket termination, and memory handles, channels, and sockets are not closed on AppDomain shutdown, only on application shutdown.

Proxy settings

The HTTP document transport API supports Synergy client HTTP and HTTPS requests through a proxy server. To specify the name and port of the proxy, use the PROXY_HOST and PROXY_PORT environment variables. (See PROXY_HOST and PROXY_PORT.) If PROXY_HOST is not defined, the HTTP document transport API will not go through a proxy server.

You can change other default proxy settings using the PROXY_LOCAL and PROXY_SUBNET environment variables. (See PROXY_LOCAL and PROXY_SUBNET.) If you’re having trouble connecting to local URIs, check the PROXY_SUBNET mask to ensure it matches your local subnet mask. To view your proxy settings in Internet Explorer, select Tools > Internet Options > Connections > LAN Settings.

Accessing an HTTP server

(If you are accessing an HTTPS server, see Accessing an HTTPS server.)

To request a document from an HTTP server, your program should do the following:

1. Call %HTTP_CLIENT_GET, specifying the URI of the resource to get. An HTTP connection is established with the server.
2. After a response is received from the server (i.e., when %HTTP_CLIENT_GET returns), check the response status by checking the return value. If the return value is zero, the response body will contain the requested data. The HTTP connection will be closed. If the return value is nonzero, process the error.

To post a document to an HTTP server, follow the steps above using %HTTP_CLIENT_POST, providing the URI of the resource to post to and the data to be posted as the body of the request.

Developing an HTTP server

(If you are developing an HTTPS server, see Developing an HTTPS server.)

To pose as an HTTP server, your program should do the following:

1. Call %HTTP_SERVER_CREATE to create a server and initialize Synergy HTTP by connecting to the local host and a known port.
2. Wait to accept HTTP GET or POST requests using %HTTP_SERVER_RECEIVE. Inspect each request to find out the resource requested. Process the request and retrieve data as needed.

Your Synergy program prepares the HTTP response by setting the status value and putting the response data in the body of the HTTP response. (It puts the response text in the handle and returns the handle and its length as argument values.)

3. Call %HTTP_SERVER_SEND to send the HTTP response to the client.
4. Wait to accept another HTTP request.
5. When you’re finished, call %HTTP_SERVER_DELETE to release the memory associated with the server object.

Sample programs

Several sample HTTP programs are available from CodeExchange in the Resource Center on the Synergex website: HTTPexample.zip, http8.zip, and url_encode.zip.

Transmitting data securely via HTTPS

If you are developing an HTTPS server, you will need a server certificate file. If you are accessing an HTTPS server, you will need a CA (Certificate Authority) file, and optionally a certificate file (for the client).

A server certificate (file) contains public keys to prove identify between servers and clients. It binds an entity’s public key with the entity that owns the public/private key pair. A certificate is signed with the issuer’s private key so that anyone with the issuer’s public key can verify its authenticity.

A CA file essentially lists the certificate authorities whose certificates you are willing to trust. Thus, in order to make a connection to a secure server, a CA file must be specified containing the CA that issued the server’s certificate.

The easiest way to get a CA file is to export one from a known and reliable source, and the most commonly used reliable source is Internet Explorer. In Internet Explorer, Microsoft maintains information about all of the globally recognized Certificate Authorities, such as VeriSign, Thawte, and many others. For details, see Exporting and importing certificates in Internet Explorer.

If the server you are trying to connect to uses a certificate that was not issued by a CA that is trusted by Internet Explorer (for example, if the server operator created their own certificate authority and used it to create and sign their own certificate), you will have to append information about that private CA to your CA file. The server operator will have to give you a copy of their CA’s public key, in PEM format, and you will have to manually add this certificate to your CA file by concatenating the two CA files (the one from Internet Explorer and the one from your server operator) together.

A client certificate (file) could also be involved when accessing an HTTPS server. A client certificate is a mechanism whereby the HTTPS server can verify who the client is. (This is rarely used, as normally only the client needs to verify who the server is.)

A client certificate is used to restrict which clients can connect to the server. If this is a requirement for the server, generally one of two things will happen. The most common is that the server operator will provide a certificate to the client and require that they pass this certificate on every request. (Note that this is not the same certificate as the “private” CA certificate discussed above. If the server operator is using a local certificate authority and requires client authentication, then two certificates will need to be provided: their CA certificate and a client certificate.) The other possibility is that the server operator will require the client operator to generate their own client certificate and to provide the public key of that certificate to them, so they can tell their server to trust it. This is very unlikely, however, as the server operator is likely to want to keep control of all certificates.

Accessing an HTTPS server

If accessing an HTTPS server that requires client certification, you will need to request a certificate from a trusted certificate authority. See Requesting a certificate.

To request a document from an HTTPS server, your program should do the following:

1. (Optional) Call %HTTP_METHOD to register a Synergy routine that will get called to prompt the user for a password.
2. Call %HTTP_CLIENT_GET, specifying the URI of the resource to get, a CA filename, and optionally the client’s supported SSL protocols, supported ciphers, and certificate filename.

The client will authenticate the server certificate, and an SSL connection will be established with the HTTPS server. If the supported protocols and ciphers are not specified, all protocols and ciphers will be accepted. The name of a client certificate file is only required when the client is requesting a resource on the server for which the server requires authentication.

3. After a response is received from the server (i.e., when %HTTP_CLIENT_GET returns), check the response status by checking the return value. If the return value is zero, the response body will contain the requested data. The SSL connection will be closed. If the return value is nonzero, process the error.

To post a document to an HTTPS server, follow the steps above using %HTTP_CLIENT_POST, providing the URI of the resource to post to and the data to be posted as the body of the request.

Developing an HTTPS server

If developing an HTTPS server, you will need to request a certificate from a trusted certificate authority. See Requesting a certificate.

Then, your program should do the following:

1. (Optional) Call %HTTP_METHOD to register a Synergy routine that will get called to prompt the user for a password.
2. Call %HTTP_SERVER_CREATE to create a server and initialize Synergy HTTPS by providing the name of a certificate file and optionally the server’s supported SSL protocols, supported ciphers, and CA filename.

The Synergy program running as an HTTPS server initializes by connecting to the local host and a known port. If no protocols or ciphers are specified, the default is TLS1.0/TLS1.1/TLS1.2 for OpenSSL 1.0.1 and above or TSL1.0 for OpenSSL before 1.0.1. If a CA filename is specified, client authentication will be performed on all requests.

3. Wait to accept HTTPS GET or POST requests using %HTTP_SERVER_RECEIVE. Inspect each request to find out the resource requested. Process the request and retrieve data as needed.

Your Synergy program prepares the HTTPS response by setting the status value and putting the response data in the body of the HTTPS response. (It puts the response text in the handle and returns the handle and its length as argument values.)

4. Call %HTTP_SERVER_SEND to send the HTTPS response to the client.
5. Wait to accept another HTTPS request.
6. When you’re finished, call %HTTP_SERVER_DELETE) to release the memory associated with the server object.

Requesting a certificate

If you are developing an HTTPS server or need an authenticated client, you must first get a certificate from a trusted certificate authority so your server or client can be authenticated.

1. Use the openssl utility to create a certificate request and key file. The syntax is
openssl req -newkey rsa:bits [-keyout key_file] -out cert_file -config config_file

where bits is the size in bits of the new RSA private key, key_file is the name of the file to write the private key to, cert_file is the name of the file to write the certificate request to, and config_file is the name of your configuration file. (See Configuration files for more information.) If the ‑keyout option is not specified, the private key filename specified in the configuration file is used as key_file.

The example below creates a new certificate request file, testreq.pem, and a new private RSA key file, testkey.pem, using configuration file openssl.cnf (which is a sample distributed with OpenSSL). The new private key will be 1024 bits. The certificate request file will contain the country, state, city, organization, department, and common name and e‑mail address of the requester.

openssl req -newkey rsa:1024 -keyout testkey.pem -out testreq.pem 
-config openssl.cnf
2. Send the certificate request file generated in step 1 to a public certificate authority, such as VeriSign or Thawte, along with any necessary fees.

The certificate authority will send back a certificate that can be used to authenticate a server or client.

Exporting and importing certificates in Internet Explorer

Internet Explorer acts as a client and keeps its own list of trusted Certificate Authorities. For convenience, you can use this list as a CA file in the openssl utility or Synergy HTTP document transport API routines.

Exporting certificates

To export certificates for use with OpenSSL or the Synergy HTTP document transport API,

1. From Internet Explorer, select Tools > Internet Options.
2. Select the Content tab and click the Certificates button.
3. Select the Trusted Root Certification Authorities tab.
4. Select all of the certificates in this dialog box and click Export button.
5. Follow the Certificate Manager Export Wizard to create a .p7b file.
6. Use the openssl utility to convert the file to PEM format:
openssl pkcs7 -inform DER -outform PEM -in file.p7b -out file.pem -print_certs

The file.pem file can now be specified in the openssl utility or as the CA_file argument in the Synergy HTTP document transport API.

Note

If you are on Internet Explorer 9, you will need to repeat steps 4 through 6 for the Intermediate Certification Authorities tab and concatenate the two .pem files.

Importing certificates

If you want to add trusted certificates to Internet Explorer’s list, you can import certificates as follows:

1. From Internet Explorer, select Tools > Internet Options.
2. Select the Content tab and click the Certificates button.
3. Select the Trusted Root Certification Authorities tab.
4. Select all the certificates in this dialog box and click the Import button.
5. Follow the Certificate Manager Import Wizard and select the PEM file you want to include as a trusted CA.

Testing your HTTPS setup locally

If you want to test your HTTPS setup locally, without going through a public certificate authority, you can establish a local certificate authority. (In the actual production world, of course, you would use a public CA, such as VeriSign or Thawte.)

Note

These examples assume that the CA directory structure is already set up and the relevant files already exist. For the example configuration file (caopenssl.cnf), you would need subdirectories named certs, newcerts, and private; an empty index.txt file; and a file named serial containing “01”. This sample configuration file is included in Configuration files.

1. Use the openssl utility to create a local CA.

Before we can begin issuing certificates with our local CA, it needs a certificate of its own, so we’ll create a self‑signed root certificate. The req command below is used to create the certificate request file rootreq.pem and private key file rootkey.pem. The key will be 1024 bits and the configuration file used will be caopenssl.cnf.

openssl req -newkey rsa:1024 -keyout rootkey.pem -out rootreq.pem -config caopenssl.cnf

(When prompted to “Enter Pem Pass Phrase,” enter the pass phrase, or password, that will later be required to access the certificate, and then enter it a second time to confirm when prompted. (You’ll also be prompted for other information that will be incorporated into the certificate request.) You can later remove this pass phrase if you don’t want to be prompted for it each time you access the certificate. See step 4.)

Next, the x509 command with the ‑req option is used to create a root certificate in the rootcert.pem file by reading the rootreq.pem file created above. The ‑signkey option causes rootreq.pem to be self‑signed using the private key rootkey.pem. The configuration file, caopenssl.cnf, contains certificate extensions to use. If ‑extfile is not specified, no extensions are added to the certificate.

openssl x509 -req –in rootreq.pem -signkey rootkey.pem -out rootcert.pem  –extfile caopenssl.cnf

The following cat command is optional, but it simplifies things for testing purposes. It concatenates the certificate file (rootcert.pem) and the key file (rootkey.pem) to yield a concatenated file called root.pem. This file will be used when signing certificates in step 3. (On Windows, use the type command.)

cat rootcert.pem rootkey.pem > root.pem
2. Create a certificate request and key file for your test program using the same openssl req syntax as the previous step. (For the purposes of these steps, name them testcert.pem and testkey.pem respectively.)
3. Create the certificate requested in step 2 and sign it using your local CA. You can use either the openssl ca command or the openssl x509 command. For example,
openssl ca -in testreq.pem -out testcert.pem -config caopenssl.cnf

The ca command is a minimal CA application. In the above example, testreq.pem is the file containing the certificate request to be signed by the local CA, testcert.pem is the file to return signed certificates to, and caopenssl.cnf is the configuration file.

Alternatively, you could use the following:

openssl x509 -req -in testreq.pem -extfile caopenssl.cnf -CA root.pem 
-CAkey root.pem -CAcreateserial -out testcert.pem

The x509 command is a multi‑purpose certificate utility. When the ‑CA option is present, the x509 command behaves like a minimal CA application. In the example above, testreq.pem is the file containing the certificate request to be signed by the local CA, ‑extfile adds certificate extensions from the configuration file caopenssl.cnf, root.pem is the CA certificate to be used for signing, CAkey is the private key to sign the certificate with, and testcert.pem is the file to return signed certificates to. (If the ‑CAkey option is not specified, it is assumed that the CA private key is present in the CA certificate file.) The ‑CAcreateserial option creates the CA serial number file if it does not exist. Future signing requests for this local CA should use ‑CAserial root.srl so the serial number can be incremented.

4. If any encryption options are set, a pass phrase will be prompted for whenever the key file is accessed. If you want to remove the pass phrase from an RSA private key, use the openssl rsa command. For example,
openssl rsa -in testkey.pem -out testkeyout.pem

where testkey.pem is the file containing the private key and testkeyout.pem is the file to write the updated key to. If you are using a concatenated certificate and key file, after removing the pass phrase, you must reconcatenate the two files.

Important

Note that step 4 is a security risk on a public certificate, but it is convenient for local testing. Step 4 is a requirement when creating an xfServer/xfServerPlus certificate on Windows.

Configuration files

You’ll want to customize your own configuration file (for example, with your own company name and e‑mail address, number of days to certify for, etc.) and use that file to to create the certificate or certificate request. To specify a configuration file in the openssl utility, use the ‑config option.

The following caopenssl.cnf file is used in the examples in Testing your HTTPS setup locally.

####################################################################
[ ca ]
default_ca      = CA_default    # The default ca section

####################################################################
[ CA_default ]
dir             = . # Where everything is kept
certs           = $dir/certs    # Where the issued certs are kept
crl_dir         = $dir/crl      # Where the issued crl are kept
database        = $dir/index.txt # Database index file
new_certs_dir = $dir/newcerts # Default place for new certs
certificate     = $dir/rootcert.pem # The CA certificate
serial          = $dir/serial # The current serial number
crl             = $dir/crl.pem # The current CRL
private_key     = $dir/root.pem # The private key
RANDFILE = $dir/private/.rand # Private random number file

x509_extensions = certificate_extensions # Extensions to add to the cert

# Extensions to add to a CRL. Note: Netscape Communicator chokes on 
# V2 CRLs so this is commented out by default to leave a V1 CRL.
# crl_extensions = crl_ext

default_days     = 365 # How long to certify for
default_crl_days= 180 # How long before next CRL
default_md      = md5 # which md to use
preserve        = no # keep passed DN ordering

# A few different ways of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that
policy          = policy_match
			
# For the CA policy
[ policy_match ]
commonName      = supplied
stateOrProvinceName = supplied
countryName     = supplied
emailAddress    = supplied
organizationName = supplied
organizationalUnitName = optional

# For the 'anything' policy
# At this point, you must list all acceptable 'object' types
[ policy_anything ]
countryName             = optional
stateOrProvinceName     = optional
localityName            = optional
organizationName        = optional
organizationalUnitName = optional
commonName              = supplied
emailAddress            = optional

[ certificate_extensions ]
basicConstraints = CA:false

[ req ]
default_bits    = 1024
default_keyfile = rootkey.pem
default_md      = md5

prompt = yes 
distinguished_name = root_ca_distinguished_name
x509_extensions = root_ca_extensions

[ root_ca_distinguished_name ]
commonName = MyCompany CA
stateOrProvinceName = California
countryName = US
emailAddress = jane.smith@MyCompany.com
organizationName = MyCompany

[ root_ca_extensions ]
basicConstraints = CA:true

Ciphers

Several of the HTTP document transport API routines pass an optional ciphers argument, which specifies the encryption methods that are in effect in the form of a “cipher list.” A cipher list consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators, but colons are normally used. The actual cipher string can take several different forms:

Each cipher string can be optionally preceded by the following characters:

Character

Meaning

!

The specified ciphers are permanently deleted from the list. The deleted ciphers can never reappear in the list even if they are explicitly stated.

The specified ciphers are deleted from the list, but some or all of the ciphers can be added again by later options.

+

The specified ciphers are moved to the end of the list. This option doesn’t add any new ciphers; it just moves matching existing ones.

None

The string is simply interpreted as a list of ciphers to be appended to the current preference list. If the list includes any ciphers already present, those ciphers will be ignored (i.e., they will not be moved to the end of the list).

Additionally the cipher string @STRENGTH can be used at any point to sort the current cipher list in order of encryption algorithm key length. When @STRENGTH is specified, HTTPS attempts to select the strongest cipher from the list.

For a current list of permitted cipher strings and their meanings, as well as lists of cipher suite names and their OpenSSL equivalents, see www.openssl.org/docs/manpages.html. Go to the “Commands” section for any version and select ciphers.htm from the list of files.

Error messages

The following errors can occur when using the HTTP document transport API:

HTTP Document Transport API Errors

Message

Cause

Address in use

A socket error occurred when the server attempted to start on a port that was already being used.

Address not available

A socket error occurred. The requested address is not valid in this context.

CA file required

An HTTPS URI was passed to %HTTP_CLIENT_GET or %HTTP_CLIENT_POST, but the CA filename was not passed. A CA filename is required for an HTTPS request.

Cannot get certificate from file

The certificate file does not include the certificate section.

Cannot get private key from file

The certificate file does not include the private key section.

Cannot load random state

There is not enough random data to seed cryptographic algorithms. Define the HTTP_RAND environment variable to a file that the Synergy HTTP document transport API can use to gather random data. (See HTTP_RAND for more information.)

Certificate verify failed

The certificate could not be validated using trusted CAs.

Connection refused

A socket error occurred when the client tried to connect to an invalid host and port.

Connection reset

A socket error occurred. If you are using HTTPS functionality, this could mean that only the client or only the server supports SSLv2 or that you tried to send an HTTP request to an HTTPS server. If you are using HTTP, the connection was closed by the remote host.

Error setting keepalive

A socket error occurred when the keepalive value was being set.

Error setting linger

A socket error occurred when the linger value was being set.

Host not found

A socket error occurred when an invalid host name was specified while the client was trying to connect to the server.

http request

The server expected an HTTPS request but received an HTTP request from the client.

HTTPS not available

HTTPS support is not available on the current platform. Either the httpslib DLL or the OpenSSL library is missing, or the OpenSSL library is not the shared version.

Invalid http request

The server did not receive a well‑formed HTTP request. The client may have tried to send an HTTPS request instead.

Invalid user information in URI

An invalid character was specified in the user information portion of the URI in a call to %HTTP_CLIENT_GET or %HTTP_CLIENT_POST. Valid characters are any alphanumeric character, escape codes %00 to %FF, semicolon (;), colon (:), ampersand (&), equal sign (=), plus sign (+), dollar sign ($), comma (,), hyphen (‑), underscore (_), period (.), exclamation point (!), tilde (~), asterisk (*), single quotation mark ('), left parenthesis ( ( ), or right parenthesis ( ) ).

No certificate returned

The peer did not have a certificate.

No ciphers available

Either the ciphers on the client and server do not match or the cipher specified on the client is invalid.

No shared ciphers

The client and server do not support the same ciphers.

No such file or directory

The specified CA file or certificate filename does not exist.

Socket error number

The socket error number occurred. Socket error numbers are usually defined in Microsoft Developer Network (MSDN) help for Microsoft platforms and in the manpages or help pages of the particular socket function that failed for other platforms.

Socket is not connected

A socket error occurred. An attempt to send or receive data failed because the socket was not connected.

SSL handshake failure

This message usually appears on the client when there is a cipher mismatch or a certificate authorization issue. The most common reasons are as follows:

  • The server does not support the client’s SSL protocol version. Ensure the client is using a protocol version supported by the server.
  • The server and client do not share common cryptographic algorithms. Ensure the client is using a cipher supported by the server.
  • Server authentication failed. The server must have a valid certificate that can be traced to a CA that the client trusts.
  • Client authentication failed. The client must have a valid certificate that can be traced to a CA that the server trusts.

Timed out

A socket error occurred when the program timed out while waiting to accept or receive a request.

Unsupported protocol

The client and server protocols do not match.