make-ssl-client-context

Arguments: &key method certificate key certificate-password method verify max-depth ca-file ca-directory ciphers crl-check crl-file prefer-server-cipher-order

This function was added by a patch (to versions 8.2 and 9.0) released in April, 2014. You must have updated (with sys:update-allegro or related technique) to use this function.

This function creates and returns an SSL context object (an instance of the class excl::ssl-context) suitable for use as the value of the context keyword argument to make-ssl-client-stream.

The context has values for all relevant arguments. For the arguments method, ciphers, verify, max-depth, and prefer-server-cipher-order, specifying a value in a call to make-ssl-client-stream which is also passed a context object as the value of the context argument causes the associated argument value to be local to that connection (i.e. the specified argument value overrides the value in the context object). The value for the arguments certificate, key, ca-file, ca-directory, certificate-password, crl-file, and crl-check cannot be overridden when a context is provided. It is an error to supply a context and values for any of those arguments.

The keyword arguments are:

• method: (default is :tlsv1+) this argument allows control over the SSL protocol handshake process. Supported SSL protocols are SSLv2, SSLv3, TLSv1, TLSv1.1, and TLSv1.2 from oldest to newest. The method keyword argument can be:
  • A list of values specifying each SSL method to explicitly support. Valid members of the list are :sslv2, :sslv3, :tlsv1, :tlsv1.1, and :tlsv1.2. This provide the ability to specify precisely which ssl methods one wants to allow, helping to mitigate downgrade attacks to weaker methods (anything before tlsv1).
  • :tlsv1+: support TLSv1, TLSv1.1, and TLSv1.2. This is the default.
  • :sslv3+: support SSLv3, TLSv1, TLSv1.1, and TLSv1.2.
  • :sslv23: the server will handle SSLv2, SSLv3, and TLSv1. The highest protocol version that is common between the client and server will be selected. This method allows for best compatibility. This option is out of date but supported for backward compatibility.
  • :sslv2: the server will only handle SSLv2. This option is not recommended as SSLv2 has known security issues (such as susceptibility to man In the middle attacks).
  • :sslv3: the server will only handle SSLv3. This option is not recommended as SSLv3 has known security issues (such as susceptibility to man In the middle attacks).
  • :tlsv1: the server will only handle TLSv1.
• certificate: (default is nil) this argument names a file which contains one or more PEM-encoded certificates. The first (or only) certificate in the file will be used to identify the client (in the case of make-ssl-client-stream). Optionally, subsequent entries in the file may be used to supply intermediate CA certificates (also known as a certificate chain).
• key: (default is nil) this argument is a string or pathname naming a file containing the private RSA key corresponding the the public key in the certificate. The file must be in PEM format. The key can be stored in an encrypted form which requires a pass phrase to read, but in that case the certificate-password must also be specified. If the key is stored in the certificate file, then you needn't specify the key argument.
• certificate-password: (default is nil) this argument, if specified, should be a string. If the private key stored with the certificate inside the file named by the certificate argument is encrypted, then this value is used as the key to decrypt it.
• verify: (default is :optional) this argument can be nil, :optional, or :required. Due to the way OpenSSL is implemented, the behavior of peer verification differs for servers and clients; here is the behavior for clients:
  • :verify nil means that no automatic verification will occur on the server-supplied certificate. Manual verification can be done using get-ssl-peer-certificate and get-ssl-verify-result.
  • :verify :optional means that the server's certificate (if supplied) will be automatically verified during SSL handshake. If verification fails, an error will be generated during SSL handshake. This is the default for client streams.
  • :verify :required means that the server's certificate will be automatically verified during SSL handshake. If the server does not supply a certificate or if verification of the supplied certificate fails, an error will be generated during SSL handshake.
• maxdepth: (default is 10) the value must be an integer which indicates the maximum allowable depth of the certificate verification chain. If the chain exceeds this depth, an error will be generated during SSL handshake.
• ca-file: (default is "sys:;examples;ssl;ca-bundle.crt") this argument specifies the name of a file containing a series of trusted PEM-encoded Intermediate CA or Root CA certificates that will be used during peer certificate verification. Keep in mind that, when using on an SSL server, the subject name information for each of these certificates is supplied to the peer during SSL handshake, so you may want to keep the number of certificates listed in the file to a minimum. A file containing certificates of well-known root CAs can be found in [acl directory]/examples/ssl/ca-bundle.crt, (to give the actual pathname, a logical pathname is used to specify the default value).
• ca-directory: (default is nil) this argument specifies the name of a directory containing a series of trusted Intermediate CA or Root CA certificate files that will be used during peer certificate verification. Each file in the directory should contain one certificate. The files should be named based on the hash value of the certificate subject name. If more than one certificate with the same hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. Use the c_rehash (available via standard OpenSSL distributions) utility to create the necessary links.
• ciphers: (default is the string given at the end of this paragraph) if the ciphers keyword argument is supplied, it must be a string which specifies an OpenSSL cipher list. This list determines which ciphers the SSL server will support. The strongest common entry from this list and the list supplied by the client during handshake will be used. If there is no entry in common, SSL handshake will fail and an error will be generated. For details on the cipher list format, see the CIPHER LIST FORMAT section of http://www.openssl.org/docs/apps/ciphers.html. The default value is the string "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS".
• crl-check: (default is nil) this argument controls certificate revocation list (CRL) checking. Its value may be nil (the default) for no CRL checking, t for CRL checking of the peer's certificate (if provided by the peer), or :all for CRL checking of all components of the peer's supplied certificate chain. If this argument is non-nil, the verify argument must also be non-nil. If you enable CRL checking, you must supply a proper PEM-encoded CRL, even if it contains zero revocations. If you do not supply a CRL, peer verification will never succeed.
• crl-file: (default is value of the ca-file argument) this argument specifies the location of a PEM-encoded CRL file. If nil or not supplied, defaults to the value of the ca-file argument. It is acceptable for CRL to be included amongst other PEM-encoded certificates.
• prefer-server-cipher-order: this argument is ignored. (It is used by make-ssl-server-context and that function and this one have the same argument lists.)

See socket.htm for information on sockets. For information on Secure Sockets, see the section Secure Socket Layer (SSL) in that document.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 8.2 release.
Created 2016.6.21.