conf

The modules conf.py and vars.py provide support for the above configuration. They will be used by the client sign.py too if available.

As of 20220525, conf.py provides .include, .-include and simple conditionals - again following the syntax of bmake(1).

For example, the config for the Signer instance I use for my packages contains:

ListenPort= 12345
OpenPGPKeyid= BA54C8AF755A2A99
syslogFacility= local0.debug
syslogIdent= Crufty.NET
children= 2
.include "openpgp.inc"

As with bmake(1) the "openpgp.inc" will be looked for first in the directory where the above was found. It contains:

Signer= OpenSSLSigner
Hash= fakesha256
SetKnobs= OpenPGPKeyid=${OpenPGPKeyid}
SigningKey= ${config_dir:H}/keys/${OpenPGPKeyid}.sec.pem
TrustAnchor= ${config_dir:H}/keys/${OpenPGPKeyid}.pub.asc
Certs= ${TrustAnchor}

The client for the above is openpgp-sign.py and since it leverages sign.py it will automatically look for openpgp-sign.cf in the same directory. In that file I have:

armor=1
.include "conf/crufty.cf"

which means I can simply run:

openpgp-sign.py sigs.tar.gz

to get sigs.tar.gz.asc.

PoolServer

This is a base class for a generic server. It needs to be extended to be useful.

After initial setup (whatever the sub-class wants - such as loading the private key) and listening on the configured port, it gets rid of any controlling tty and forks N children (one per cpu works well). These children accept(2) connections from clients and service them.

Since each transaction takes only a few ms, avoiding the overhead of continually forking, or starting threads keeps the overhead to a minium, at the same time as constraining the resource consumption.

This class covers the startup and shutdown of the server pool.

SignServerPool

A sub-class of PoolServer, provides the basic signing protocol. It loads an appropriate Signer class based on the key and signature it has been configured to produce.

It can enforce network based access controls.

Signer

A mostly abstract base class for doing a signing operation. It should be extended to do something useful.

OpenSSLSigner

This is the most commonly used Signer. It interfaces to a C module which provides two generic methods load_key and sign_digest which in turn simply use OpenSSL (0.9.9 or later) APIs.

We add a directory to sys.path corresponding to a host-target derrived from os.uname() eg. netbsd5-i386 or freebsd10-amd64 which just happens to be were the compiled C module is placed on such platforms. The Python api does not provide access to uname -p so src/Makefile takes this into account.

Note: the latest version of config file allows for doing:

uname_p != uname -p

ie. run uname -p and assign its output to uname_p, but it isn't necessary.

This Signer can handle any key type that OpenSSL supports.

FakeHash

Takes advantage of Python's duck typing. It loads itself with the data provided, and provides digest() and hexdigest() methods that simply return that same data.

This allows the signing server to implement signature methods that do not normally lend themselves to an efficient client server model.

That is; the signature methods typically want a hash object passed to them rather than a hash value. For efficiency, we want the client to send us a hash. So what the signer usually ends up getting is in fact a hash of a hash. This is not always desirable - FakeHash is the fix.

ExternalSigner

This is an interface to external signing tools. It is not intended for high volume use.

For each message received it saves the input in a temp file, and creates a temp file for the signature, then runs the configured command line which can refer to {infile} and {outfile}. The content of the outfile is returned to caller.

sign

Per the protocol above, for each file, it produces a hexdigest to send to the server (with trailing newline).

It receives back a PEM encoded signature, and (normally) a clue as to which file extension to use.

It can also ask the server for the certificate chain needed to verify the signatures being produced.

The client is designed to know as little as possible about the signing operation. It really only needs to be told the url to use and whether to send a SHA1 or SHA256 digest.

The hash sent and the processing done by the server, need to produce a signature acceptible to whatever is expected to verify it.

The client will look at the name it was invoked with and see if a configuration file exists with that name. That is sign.py will look for sign.cf and openpgp-sign.py will look for openpgp-sign.cf.

Additional configuration files can be passed via the -c option. This makes it easy to configure hash choice, and server url.

Note: the client will attempt to import the conf modules to get loadConfig but if that fails a simplified implementation which does not support variable references will be used. The fallback reader will ignore any of the fancy features it cannot support:

Warning: ignoring: arch != uname -p
Warning: ignoring: .include "openpgp.inc"

It is thus possible to construct the configuration file for a Signer such that at least some portion of it can be used by the client.

openpgp-sign

Extends the SignClient class in sign.py to generate OpenPGP compatable signatures.

The corresponding server instance must be configured to report the keyid (and use FakeHash):

Signer= OpenSSLSigner
SetKnobs= OpenPGPKeyid=CAFEBABEDEADBEEF
Hash= fakesha256

The keyid ends up in the signature and allows a verifier to find the correct public key.

Note: OpenSSLSigner knows nothing about OpenPGP, it is just generating an RSA signature. All the work of putting the signature into OpenPGP packets is done by the client.

Use convert-gpg-seckey-to-pem to convert a private key generated by gpg or another OpenPGP client to PEM format so it can be loaded by OpenSSLSigner.

ima-sign

Extends the SignClient class in sign.py to generate Linux IMA signatures.

signctl

As the name might suggest, this client is for controlling the signing server. It is used by the rc_sigs script for stopping, and checking status of servers.

It prefixes its requests with signctl:, to ensure they are not mistaken for signing requests. The only one the server actually cares about is shutdown.

When a server instance receives the shutdown request, it sets a flag and exits with with a status that ensures the main process knows.

The main server process will signal any other children, but for simplicity, signctl will repeat the shutdown request until it gets a connection failure. This will shutdown all the server instances as rapidly as possible.

SignProxy

Run as an SSH sub-agent, this class opens a connection to the signing server when it has work for it, and sends the responses back to its client.

After a period of idleness it disconnects from the server. After an extended period of idleness, it shuts down. The next request from the client (SignAgent) will cause it to be restarted.

SignAgent

Run on client host by the user, and with access to SSH_AUTH_SOCK. It creates a private unix domain socket, which it listens to for singing requests. It indicates the socket it is listening on, which should then be used as the url given to sign.

When it gets a request it (if needed) opens a connection to the specified url - which leads to SignProxy. Sends and gets the response which it passes back to the caller.

There is only one thread, so if multiple sign clients attempt requests they will be serviced sequentially.