schannel

# schannel
CFFI bindings to Windows SChannel API - provides TLS for Common Lisp on Windows.

## 1. Introduction
The canonical SSL/TLS for Common Lisp is the `CL+SSL` package, this works by calling into OpenSSL APIs.
This works well on Linux and other systems where the openssl libraries are installed as part of the OS and
kept up to date with package managers. On Windows however, this is not the case: Lisp users must install
specific openssl binaries and keep them up to date themselves. Over time users will find that their `CL+SSL`
install no longer works e.g. because their openssl binaries no longer support the version of TLS that
they intend to use.

However, Microsoft ships a full TLS implementation on all version of Windows. It is exposed using SSPI APIs and
is called `SChannel`. This library provides a set of CFFI bindings to these APIs and some utility functions
to simplify things.

## 2. Usage
The library exposes functions which wrap the underlying SChannel APIs at at a low level. These can be used
in a way that follows quite closely any examples from MSDN written in C. 

E.g. for a client you might write something like this:

```
(with-client-context (cxt "www.google.com")
  (let ((token (initialize-client-context cxt)))
    ;; ... send token to server ...
    )
  (let ((token (recv-token-from-server)))
    (let ((rtok (initialize-client-context cxt token)))
      ;; ... send token to server ...
      ))
  ;; continue until rtok=nil

  ;; context now complete, ready to exchange data messages
  (let ((count (encrypt-message cxt buf :end buf-end)))
   ;; ... send count bytes to server
   )  
  (let* ((count (recv-bytes-from-server))
         (pcount (decrypt-message cxt buf :end count)))
    ;; do something with pcount bytes of plaintext
    ))    
```

## 2.1 Streams
For more practical purposes a gray streams interface is provided `make-client-stream` and `make-server-stream`.
These take as inputs an underlying stream (i.e. a networking stream). The initializer functions handle
initial context negotiation. Subsequent reads and writes are passed through SChannel encryption/decryption routines. 

## 2.2 HTTP client 
See my fork of `drakma`. On Windows it replaces uses of CL+SSL with SChannel.

## 2.3 HTTP server
See my fork of `hunchentoot`. On Windows it replaces uses of CL+SSL with SChannel.

## 2.4 Client certificates
When a client connects to a server, the server may request the client provide a certificate (e.g. for authentication purposes).
Pass the `CLIENT-CERTIFICATE` parameter to `MAKE-CLIENT-STREAM` to do this.

To make a server which instructs clients to provide certificates, pass `:REQUIRE-CLIENT-CERTIFICATE t` parameter to `MAKE-SERVER-STREAM`.

## 2.5 Certificates
SChannel does not handle certificates directly as files, as is done by e.g. CL+SSL (OpenSSL). Instead, certificates
are installed in a system wide repository and are referenced by name.
Certificates are managed using Windows system tools (e.g. certmgr or powershell).

## 3. TODO 

## 4. Notes
## 4.1 How to create and install a self signed certificate.

To use schannel as a server you need both root and server certificates. The server machine needs the server certificate installed,
any clients which want to validate the certificate (e.g. web browsers) will need the root certificate installed.

To generate these run the following powershell script 
```
 $cert = New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname my.example.host
 $pwd = ConvertTo-SecureString -String password1234 -Force -AsPlainText
 $path = "cert:\localMachine\my\" + $cert.thumbprint
 Export-PfxCertificate -cert $path -FilePath c:\temp\powershellcert.pfx -Password $pwd
```
Find this file in explorer and double click it to install. This installs the server certificate.

Then open the certificates mmc console, find the certificate and copy/paste it into third party trusted root certificates.
 
TODO: should be able to do this exclusively using schannel.

## License

Released under the terms of the MIT license.

Frank James
2019 








schannel

Upstream URL

Author

License

schannel

License:

Authors:

Dependencies:

Dependencies (2)

Dependents (0)