.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ASETKEY 8"
.TH ASETKEY 8 "2016-07-18" "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
.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 delete <\fIkvno\fR>
.PP
\&\fBasetkey\fR list
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBasetkey\fR command is used to add a key to an \s-1AFS\s0 KeyFile from a
Kerberos keytab.  It is similar to \fBbos addkey\fR except that it must be
run locally on the system where the KeyFile is located and it takes the
new key from the command line or 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 (similar
to \fBbos listkeys\fR).
.PP
\&\fBasetkey\fR is used when authentication for an \s-1AFS\s0 cell is provided by a
Kerberos 5 \s-1KDC\s0 rather than \fBkaserver\fR.  The key for the \f(CW\*(C`afs\*(C'\fR or
\&\f(CW\*(C`afs/\f(CIcell name\f(CW\*(C'\fR principal in the Kerberos 5 \s-1KDC\s0 must match the key
stored in the \s-1AFS\s0 KeyFile on all \s-1AFS\s0 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 \s-1AFS\s0 database server and file server, adding
that key to the KeyFile with \fBasetkey add\fR.  The \fIkvno\fR chosen should
match the kvno in the Kerberos \s-1KDC \s0(checked with \fBkvno\fR or the
\&\f(CW\*(C`getprinc\*(C'\fR function of \fBkadmin\fR).  \fIprincipal\fR should be the name of
the \s-1AFS\s0 principal in the keytab, which must be either \f(CW\*(C`afs\*(C'\fR or
\&\f(CW\*(C`afs/\f(CIcell name\f(CW\*(C'\fR. \fBasetkey\fR can also be used to install a key
from a hex string.
.PP
In cells that use the Update Server to distribute the contents of the
\&\fI/etc/openafs/server\fR directory, it is conventional to run \fBasetkey add\fR only
on the control machine and then let the Update Server propagate the new
KeyFile to all other systems.
.SH "CAUTIONS"
.IX Header "CAUTIONS"
\&\s-1AFS\s0 currently only supports des\-cbc\-crc:v4 Kerberos keys.  Make sure, when
creating the keytab with \f(CW\*(C`ktadd\*(C'\fR, you pass \f(CW\*(C`\-e des\-cbc\-crc:v4\*(C'\fR to force
the encryption type.  Otherwise, \s-1AFS\s0 authentication may not work.
.PP
As soon as a new keytab is created with \f(CW\*(C`ktadd\*(C'\fR, new \s-1AFS\s0 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 KeyFile on the \s-1AFS\s0 file
server.  There is therefore an outage window between when the new keytab
is created and when the key had been added to the KeyFile of all \s-1AFS\s0
servers with \fBasetkey\fR, during which newly obtained \s-1AFS\s0 tokens will not
work properly.
.PP
All of the KeyFile entries must match the key in the Kerberos \s-1KDC,\s0 but
each time \f(CW\*(C`ktadd\*(C'\fR is run, it creates a new key.  Either the Update Server
must be used to distribute the KeyFile to all servers or the same keytab
must be used with \fBasetkey\fR on each server.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
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/\f(CIcell name\f(CW\*(C'\fR instead of \f(CW\*(C`afs\*(C'\fR, particularly if
you may have multiple \s-1AFS\s0 cells for a single Kerberos realm.
.PP
In the event you have been distributed a key by a Kerberos administrator
in the form of a hex string, you may use asetkey to install that.
.PP
.Vb 1
\&    % asetkey add 3 80b6a7cd7a9dadb6
.Ve
.PP
\&\fIkey\fR should be an 8 byte hex representation.
.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 KeyFile, normally
\&\fI/etc/openafs/server/KeyFile\fR.  In practice, this means that the issuer must be
the local superuser \f(CW\*(C`root\*(C'\fR on the \s-1AFS\s0 file server or database server.
For \fBasetkey add\fR, the issuer must also be able to read the specified
keytab file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIKeyFile\fR\|(5),
\&\fIbos_addkey\fR\|(8),
\&\fIbos_listkeys\fR\|(8),
\&\fIbos_removekey\fR\|(8),
\&\fIkadmin\fR\|(8),
\&\fIkvno\fR\|(1)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006 Russ Allbery <rra@stanford.edu>
.PP
This documentation is covered by the \s-1IBM\s0 Public License Version 1.0.  This
man page was written by Russ Allbery for OpenAFS.