.\" -*- 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 "AKEYCONVERT 8"
.TH AKEYCONVERT 8 2024-02-03 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
akeyconvert \- Import keys from rxkad.keytab to an AFS KeyFileExt
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBakeyconvert\fR \fI\-all\fR
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBakeyconvert\fR command is used when upgrading an AFS cell from
the 1.6.x release series to the 1.8.x release series.
When using the rxkad\-k5 security extension, the 1.6.x release series
stored the AFS long-term Kerberos keys in a krb5 keytab file named
\&\fIrxkad.keytab\fR.  The 1.8.x series releases avoid widespread linking
against libkrb5, and instead store the AFS long-term Kerberos keys
in an OpenAFS-specific file format, the \fBKeyFileExt\fR\|(5).
.PP
\&\fBakeyconvert\fR provides an easy way to convert the AFS long-term
Kerberos keys from the krb5 keytab format to the KeyFileExt format.
The same functionality is possible via repeated use of \fBasetkey\fR\|(8),
but \fBakeyconvert\fR is provided to simplify the process.
.PP
By default, \fBakeyconvert\fR will only migrate the newest key (highest kvno)
for each Kerberos principal with a key in the rxkad.keytab.  The ability
to convert all keys, regardless of kvno, is provided as \fBakeyconvert \-all\fR.
.SH CAUTIONS
.IX Header "CAUTIONS"
The \fIKeyFileExt\fR format is slightly less flexible than the krb5
keytab format \-\- the \fIKeyFileExt\fR identifies keys only by the
type (rxkad\-k5), kvno, and enctype ("subtype"), whereas the krb5 keytab
also stores the principal name associated with each key.  This means
that a krb5 keytab which contained keys of identical kvno and enctype,
but for different principals, would not be representable as a
\&\fIKeyFileExt\fR.  \fBakeyconvert\fR detects such a situation and does
not perform any key conversions until the conflict is removed.
.PP
Many of the concerns given in \fBasetkey\fR\|(8) regarding extracting
new Kerberos keys with \f(CW\*(C`ktadd\*(C'\fR are also applicable to changes
involving the \fIrxkad.keytab\fR.
.SH EXAMPLES
.IX Header "EXAMPLES"
In a cell which is using the rxkad\-k5 extension, the following command
will read the newest keys from the \fIrxkad.keytab\fR and write them to the
\&\fIKeyFileExt\fR in the appropriate format.
.PP
.Vb 1
\&    % akeyconvert
.Ve
.PP
In a cell which has a key of kvno 2 and enctype aes128\-cts\-hmac\-sha1\-96
for both afs/example.com@EXAMPLE.COM and a different key with
the same kvno and enctype but for the principal afs@EXAMPLE.COM,
\&\fBakeyconvert\fR will detect the kvno/enctype collision and refuse to
continue.  The appropriate Kerberos keytab-manipulation tools should
be used to generate a new key (of higher kvno) for one of the colliding
principals and remove the old (colliding) key for that principal before
\&\fBakeyconvert\fR is used.
.PP
.Vb 3
\&    % akeyconvert \-all
\&    Duplicate kvno/enctype 2/17
\&    FATAL: duplicate key identifiers found.
.Ve
.SH "PRIVILEGE REQUIRED"
.IX Header "PRIVILEGE REQUIRED"
The issuer must be able to read the \fIrxkad.keytab\fR and write the
\&\fIKeyFile\fR and \fIKeyFileExt\fR, normally \fI/etc/openafs/server/KeyFile\fR and
\&\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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBKeyFile\fR\|(5),
\&\fBKeyFileExt\fR\|(5),
\&\fBasetkey\fR\|(8),
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2015 Massachusetts Institute of Technology.
.PP
This documentation is covered by the IBM Public License Version 1.0.  This
man page was written by Benjamin Kaduk for OpenAFS.