NAME

dwmauth — Generate or check key pairs for services using libDwmAuth

SYNOPSIS

dwmauth

keygen [-C comment] [-f private_keyfile]

dwmauth

keycheck [-f private_keyfile]

DESCRIPTION

dwmauth is a simple command-line utility for creating and checking public/private keypairs (RSA 2048-bit) to be used by services that utilize libDwmAuth for authentication. It operates in a somewhat similar manner to ssh-keygen(1) but does not use passphrases and only uses RSA 2048-bit keys (other key types are not supported).

dwmauth(1) operates in two possible modes: key generation and key checking.

Key generation

dwmauth keygen [-C comment] [-f private_keyfile]

Generates public and private key files. The following command line options are available:

-C comment: Specify the comment. If this option is not used, a default of username@hostname will be used, where username will be determined via getuid(2) and getpwuid(2) and hostname will be determined via gethostname(3).
-f private_keyfile: Specify the file in which the private key should be stored. The public key will be stored in a file with '.pub' appended to the private keyfile name. If this option is not used, the private key will be stored in ~/.dwmauth/id_rsa and the public key will be stored in ~/.dwmauth/id_rsa.pub.

A user will normally use their email address as the comment, and not use the -f private_keyfile argument. They may then copy the contents of their .dwmauth directory onto any host from which they need access to services using libDwmAuth, taking care to maintain 0600 permissions on their key files and 0700 permissions on their .dwmauth directory. For example:

% dwmauth keygen -c dwm@mcplex.net

A service will normally use a service name and hostname as the comment, and an appropriate location for the key files. For example:

# dwmauth keygen -c mcblockd@gw.mcplex.net -f /usr/local/etc/mcblockd/id_rsa

Key checking

dwmauth keycheck [-f private_keyfile]

Checks the validity of a public/private key pair. The following command line options are available:

-f private_keyfile: Specify the file in which the private key is stored. The public key is assumed to be stored in a file with '.pub' appended to the private keyfile name. If this option is not used, the private key is assumed to be stored in ~/.dwmauth/id_rsa and the public key is assumed to be stored in ~/.dwmauth/id_rsa.pub.

If the key pair is valid, nothing will be printed and the dwmauth(1) process will exit with status 0. If any error occurs (invalid keypair, missing file(s), etc.), dwmauth(1) will print an error and exit with status 1.

FILES

${HOME}/.dwmauth/id_rsa: The user's dwmauth private key file, created with dwmauth(1). This file should be owned by the user and have permissions 0600. It must contain the private part of a 2048-bit RSA key pair.
${HOME}/.dwmauth/id_rsa.pub: The user's dwmauth public key file, created with dwmauth(1). This file should be owned by the user and have permissions 0600. It must contain the public part of a 2048-bit RSA key pair.
${HOME}/.dwmauth/known_services: The user's dwmauth known services file. This file must contain the public keys of services the user will access. Each public key is used to authenticate a remote service during authentication.

HISTORY

libDwmAuth came about when I needed a simpler means of authenticating both sides of a TCP connection in machine to machine communications (no user at a keyboard) in C++ client/server applications. Anyone who has used OpenSSL or ssh tunneling knows that this can be a pain to administer, and when you add human users to the mix, it can grow cumbersome fairly quickly. And while I could have used Kerberos with my own tweaks and additions as I have in the past, I wanted to avoid the KDC single point of failure and wanted the flexibility of choosing my scheme. I've also used CORBA with ssliop and certificates on both ends, but I wanted to avoid CORBA since it's out of fashion (and outside of my own Naming Service implementation I wrote years ago, the Naming Service is a single point of failure for many CORBA applications). And certificate management is cumbersome. I have several daemon applications that act as both client and server, and I want all network communication to be authenticated and encrypted (on both ends). For example, mcblockd(8) is a server for mcblocklog(1) and mcblockc(1) but a client of dwmrdapd(8). Basically what I really wanted was a C++ library for ssh with an easy-to-use, stable API, but such a thing doesn't exist. So I wrote something I could use in my C++ applications and administer much like ssh without creating tunnels, user accounts, etc. I've no idea if anyone else will find the library useful.