tarsnap/keymgmt/tarsnap-keymgmt.1-mdoc

.\" Copyright 2008-2025 Tarsnap Backup Inc.
.\" All rights reserved.
.\"
.Dd @DATE@
.Dt TARSNAP-KEYMGMT 1
.Os
.Sh NAME
.Nm tarsnap-keymgmt
.Nd generate subsets of
.Xr tarsnap 1
key files
.Sh SYNOPSIS
.Nm
.Fl -outkeyfile Ar new-key-file
.Op Fl r
.Op Fl w
.Op Fl d
.Op Fl -nuke
.Op Fl -passphrased
.Op Fl -passphrase-mem Ar maxmem
.Op Fl -passphrase-time Ar maxtime
.Ar key-file ...
.Nm
.Fl -print-key-id Ar key-file
.Nm
.Fl -print-key-permissions Ar key-file
.Nm
.Fl -version
.Sh DESCRIPTION
.Nm
reads the provided key files and writes a new key file
(specified by
.Fl -outkeyfile Ar new-key-file )
containing only the keys required for the operations
specified via the
.Fl r
(list and extract archives),
.Fl w
(write archives),
.Fl d
(delete archives), and
.Fl -nuke
flags.
Note that
.Fl d
implies
.Fl r
since it is impossible to delete an individual archive without
being able to read it; while a key file generated with
.Fl -nuke
can be used to delete all the archives stored, but not individual
archives.
.Pp
The following list shows which permissions are required for various
.Xr tarsnap 1
.Em command modes .
.Bl -tag -width 4n -offset 4n
.It Em --recover
requires either (1)
.Fl d
(archive deleting), (2)
.Fl w
(archive creating), or (3)
.Fl -nuke
keys.
.It Em --fsck
requires either (1) both
.Fl w
(archive writing) and
.Fl r
(archive reading) keys, or (2)
.Fl d
(archive deleting) keys.
.It Em --fsck-prune
requires
.Fl d
(archive deleting) keys, since it needs to be able to delete
corrupted archives.
.El
.Pp
If the
.Fl -passphrased
option is specified, the user will be prompted to enter a passphrase (twice)
to be used to encrypt the key file.
.Pp
If the
.Fl -passphrase-mem Ar maxmem
option is specified, a maximum of
.Ar maxmem
bytes of RAM will be used in the scrypt key derivation function to
encrypt the key file; it may be necessary to set this option if a key
file is being created on a system with far more RAM than the system
on which the key file will be used.
.Pp
If the
.Fl -passphrase-time Ar maxtime
option is specified, a maximum of approximately
.Ar maxtime
seconds will be used in the scrypt key derivation function to encrypt
the key file.
.Pp
Note that if none of the
.Fl w ,
.Fl r ,
.Fl d ,
or
.Fl -nuke
options are specified, a key file will be produced which does not
contain any keys.
This is probably not very useful.
.Pp
The
.Fl -print-key-id Ar key-file
option displays the 64-bit integer corresponding to the key's machine number.
This may be useful for scripts or GUIs which manage a user's Tarsnap account,
but is not likely to be helpful for command-line use.
.Pp
The
.Fl -print-key-permissions Ar key-file
option displays the permissions which the key possesses.
.Pp
The
.Fl -version
option prints the version number of
.Nm ,
then exits.