--- /dev/null
+
+**DRAFT**
+
+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.
git://git.openafs.org / openafs-wiki.git / blobdiff