Installation and testing instructions for OpenAFS 1.9.x

The 1.9.0 development release is the first OpenAFS release to include support for the rxgk security class, the long-awaited mechanism to allow Rx RPC traffic to benefit from modern cryptographic algorithms. Since the 1.9.x series of releases are development snapshots, this functionality is not considered "complete", but enough functionality is present that it is appropriate to seek broader community testing and feedback.

The 1.9.0 release includes support for using rxgk for the server-to-server communications internal to the operations of the prdb and vldb ubik distributed database, as well as support for client utilities using the cell's secret key material (via -localauth) to perform queries and operations against those databases. In order to utilize these features, several steps must be taken in order to ensure that the appropriate keying material is available everywhere before enabling the use of rxgk.

1) Install updated software

In order to use rxgk for database server traffic, all database servers must be running software with rxgk support (i.e., 1.9.0 or newer). As of 1.9.0, no changes have been made to any database formats or structures, so the usual procedures for upgrading in place (shutdown server processes, install new software, restart server processes) will suffice. That said, since 1.9.x are development releases, performing a fresh install as a testing environment is recommended. As always, when stopping and starting database servers it is advised to only have one machine out of service at a given time and to wait for ubik to stabilize with a unanimous sync-site election before proceeding to perform maintenance on the next server.

2) Generate and install cryptographic keys on all dbservers

One of the many benefits rxgk brings is the ability to use a robust cryptographic key schedule, with most keys having a single dedicated purpose, per cryptographic best practice. Since the 1.8.0 release, OpenAFS key material has been stored in the extensible KeyFileExt in the server configuration directory, and this continues to be the case in 1.9.9. Multiple logical key types and key versions coexist, with the (potentially preexisting) rxkad_krb5 keys used for client tokens present alongside new rxgk keys used (for now) for the server-to-server communication. It's advised to generate a new random key for this purpose; on an arbitrary database server run:

# asetkey add-random rxgk 1

(The "1" is a key version number, or kvno, which could be set to a different value.) Then the resulting KeyFileExt can be copied to the other database servers. The new rxgk key will not be used for outgoing traffic at this time (although it is available for use decrypting incoming traffic once the KeyFileExt file is in place and the CellServDB has been touched to signal a configuration reload).

3) Update dbserver configuration to use rxgk for outbound traffic

At this point all database servers have the requisite software and key material to accept incoming rxgk connections, but no such connections are being produced automatically. (It would be possible to use the client utilities, e.g., pts -localauth -rxgk at this time, manually.) In order to actually use rxgk for server-to-server communications, each server's configuration needs to be updated to activate the use of rxgk for outbound connections. This transition can be made incrementally, with a mix of servers using rxgk and servers using legacy rxkad for outgoing connections, since all servers will accept both types of connection. To effectuate the change, each server in turn will have its configuration modified to pass the -s2scrypt rxgk-crypt arguments to the vlserver and ptserver processes, e.g., via bos delete and bos create. As this does require stopping and restarting the ptserver/vlserver process to change its configuration, the usual database server upgrade considerations apply (mentioned briefly in step (1)).

4) Use rxgk from client utilities

In order to provide additional testing of the rxgk functionality we also advise the use of rxgk from the client utilities, particularly in cases where automated scripts are already using the -localauth flag. For both the pts and vos utilities, the -localauth -rxgk <level> arguments can be used to instantiate rxgk connections to the ptserver and vlserver, respectively, using the indicated security level. The possible security levels are "clear" (perform rxgk authentication at the start of the connection but apply no per-message protection), "auth" (in addition to initial authentication, each message is protected by a cryptographic message integrity check), and "crypt" (all traffic is encrypted and authenticated). Note that the vos utility can be used to perform operations against both the vlserver and the volume server, and rxgk connection attempts against the latter will fail. Performance comparisons of the various security levels are welcome from a variety of deployment conditions.

5) Stay tuned for future updates

Subsequent releases from the 1.9.x series will add support for rxgk in more communications paths, such as inter-volume-server communication and, eventually, client-to-fileserver communication. Support for acquiring and using tokens for authenticated client acess is also under way.