.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "ASETKEY 8" .TH ASETKEY 8 2024-03-20 OpenAFS "AFS Command Reference" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME asetkey \- Add a key from a keytab to an AFS KeyFile or KeyFileExt .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBasetkey\fR add <\fIkvno\fR> <\fIkeyfile\fR> <\fIprincipal\fR> .PP \&\fBasetkey\fR add <\fIkvno\fR> <\fIkey\fR> .PP \&\fBasetkey\fR add <\fItype\fR> <\fIkvno\fR> <\fIsubtype\fR> <\fIkey\fR> .PP \&\fBasetkey\fR add <\fItype\fR> <\fIkvno\fR> <\fIsubtype\fR> <\fIkeyfile\fR> <\fIprinc\fR> .PP \&\fBasetkey\fR delete <\fIkvno\fR> .PP \&\fBasetkey\fR delete <\fItype\fR> <\fIkvno\fR> .PP \&\fBasetkey\fR delete <\fItype\fR> <\fIkvno\fR> <\fIsubtype\fR> .PP \&\fBasetkey\fR list .SH DESCRIPTION .IX Header "DESCRIPTION" The \fBasetkey\fR command is used to add a key to an AFS KeyFile or KeyFileExt from a Kerberos keytab. It is similar to \fBbos addkey\fR except that it must be run locally on the system where the KeyFile or KeyFileExt is located and it takes the new key from a Kerberos 5 keytab rather than prompting for the password. .PP \&\fBasetkey delete\fR can be used to delete a key (similar to \fBbos removekeys\fR), and \fBasetkey list\fR will list the keys in a KeyFile and the keys in a KeyFileExt (similar to \fBbos listkeys\fR, but more fully featured, since \fBbos listkeys\fR cannot list the contents of a KeyFileExt). .PP \&\fBasetkey\fR is used when authentication for an AFS cell is provided by a Kerberos 5 KDC rather than the deprecated \fBkaserver\fR. The key for the \f(CW\*(C`afs\*(C'\fR or \&\f(CW\*(C`afs/\fR\f(CIcell name\fR\f(CW\*(C'\fR principal in the Kerberos 5 KDC must match the key stored in the AFS KeyFileExt on all AFS database servers and file servers. This is done by creating a keytab containing that key using the standard Kerberos commands (generally the \f(CW\*(C`ktadd\*(C'\fR function of the \fBkadmin\fR command) and then, on each AFS database server and file server, adding that key to the KeyFileExt with \fBasetkey add\fR. The \fIkvno\fR chosen should match the kvno in the Kerberos KDC (checked with \fBkvno\fR or the \&\f(CW\*(C`getprinc\*(C'\fR function of \fBkadmin\fR). \fIprincipal\fR should be the name of the AFS principal in the keytab, which must be either \f(CW\*(C`afs\*(C'\fR or \&\f(CW\*(C`afs/\fR\f(CIcell name\fR\f(CW\*(C'\fR. .SH CAUTIONS .IX Header "CAUTIONS" Historically, AFS only supported des\-cbc\-crc:v4 Kerberos keys. In environments which have not been upgraded to use the rxkad\-k5 extension, when creating the keytab with \f(CW\*(C`ktadd\*(C'\fR, you must pass \f(CW\*(C`\-e des\-cbc\-crc:v4\*(C'\fR to force the encryption type. Otherwise, AFS authentication may not work. .PP As soon as a new keytab is created with \f(CW\*(C`ktadd\*(C'\fR, new AFS service tickets will use the new key. However, tokens formed from those service tickets will only work if the new key is present in the KeyFileExt on the AFS file server. There is therefore an outage window between when the new keytab is created and when the key had been added to the KeyFileExt of all AFS servers with \fBasetkey\fR, during which newly obtained AFS tokens will not work properly. .PP All of the KeyFileExt entries must match the key in the Kerberos KDC, but each time \f(CW\*(C`ktadd\*(C'\fR is run, it creates a new key. Some secure mechanism must be used to distribute the KeyFileExt to all servers, or the same keytab must be used with \fBasetkey\fR on each server. .SH EXAMPLES .IX Header "EXAMPLES" In a cell which is using the rxkad\-k5 extension, the following commands create a new keytab for the principal \f(CW\*(C`afs/\fR\f(CIcell name\fR\f(CW\*(C'\fR and then import its keys into the KeyFileExt. Note the kvno in the output from \f(CW\*(C`ktadd\*(C'\fR. The values 18, 17, and 16 are the assigned numbers corresponding to the kerberos enctypes in the keytab. These numbers can be determined from your system's krb5 headers. .PP .Vb 10 \& % kadmin \& Authenticating as principal kaduk/admin@ZONE.MIT.EDU with password. \& Password for kaduk/admin@ZONE.MIT.EDU: \& kadmin: ktadd \-k /tmp/afs.keytab afs/disarray.mit.edu \& Entry for principal afs/disarray.mit.edu with kvno 4, encryption type \& aes256\-cts\-hmac\-sha1\-96 added to keytab WRFILE:/tmp/afs.keytab. \& Entry for principal afs/disarray.mit.edu with kvno 4, encryption type \& aes128\-cts\-hmac\-sha1\-96 added to keytab WRFILE:/tmp/afs.keytab. \& Entry for principal afs/disarray.mit.edu with kvno 4, encryption type \& des3\-cbc\-sha1 added to keytab WRFILE:/tmp/afs.keytab. \& kadmin: exit \& % asetkey add rxkad_krb5 4 18 /tmp/afs.keytab afs/disarray.mit.edu \& % asetkey add rxkad_krb5 4 17 /tmp/afs.keytab afs/disarray.mit.edu \& % asetkey add rxkad_krb5 4 16 /tmp/afs.keytab afs/disarray.mit.edu .Ve .SH "PRIVILEGE REQUIRED" .IX Header "PRIVILEGE REQUIRED" The issuer must be able to read (for \fBasetkey list\fR) and write (for \&\fBasetkey add\fR and \fBasetkey delete\fR) the KeyFileExt, normally \&\fI/etc/openafs/server/KeyFileExt\fR. In practice, this means that the issuer must be the local superuser \f(CW\*(C`root\*(C'\fR on the AFS file server or database server. For \fBasetkey add\fR, the issuer must also be able to read the specified keytab file. .SH "HISTORICAL COMPATIBILITY" .IX Header "HISTORICAL COMPATIBILITY" A modern AFS cell should be using the rxkad\-k5 extension, or risks terribly insecure operation (complete cell compromise for \f(CW$100\fR in 1 day). The keys used for rxkad\-k5 operation are stored in the KeyFileExt. Cells not using the rxkad\-k5 extension (i.e., stock rxkad) use keys of the des-cbc-crc encryption type, which are stored in the KeyFile. .PP \&\fBasetkey\fR retains the functionality needed to support stock rxkad operation, but its use is disrecommended. A bare 8\-byte hex key can be added with .PP .Vb 1 \& % asetkey add I I .Ve .PP \&\fIkey\fR should be an 8 byte hex representation. An example using a kvno of 3: .PP .Vb 1 \& % asetkey add 3 80b6a7cd7a9dadb6 .Ve .PP The following commands create a new keytab for the principal \f(CW\*(C`afs\*(C'\fR and then import the key into the KeyFile. Note the kvno in the output from \f(CW\*(C`ktadd\*(C'\fR. .PP .Vb 8 \& % kadmin \& Authenticating as principal rra/admin@stanford.edu with password. \& Password for rra/admin@stanford.edu: \& kadmin: ktadd \-k /tmp/afs.keytab \-e des\-cbc\-crc:v4 afs \& Entry for principal afs with kvno 3, encryption type DES cbc mode \& with CRC\-32 added to keytab WRFILE:/tmp/afs.keytab. \& kadmin: exit \& % asetkey add 3 /tmp/afs.keytab afs .Ve .PP You may want to use \f(CW\*(C`afs/\fR\f(CIcell name\fR\f(CW\*(C'\fR instead of \f(CW\*(C`afs\*(C'\fR, particularly if you may have multiple AFS cells for a single Kerberos realm. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBKeyFile\fR\|(5), \&\fBKeyFileExt\fR\|(5), \&\fBbos_addkey\fR\|(8), \&\fBbos_listkeys\fR\|(8), \&\fBbos_removekey\fR\|(8), \&\fBkadmin\fR\|(8), \&\fBkvno\fR\|(1) .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2006 Russ Allbery Copyright 2013,2015 Massachusetts Institute of Technology .PP This documentation is covered by the IBM Public License Version 1.0. This man page was written by Russ Allbery for OpenAFS and updated for the rxkad\-k5 extension by Benjamin Kaduk.