=encoding utf8

=head1 NAME

shib-seckeygen - Rotate the keys of a Versioned DataSealer

=head1 SYNOPSIS

B<shib-seckeygen> [B<-o> I<output-dir>] [B<-f> I<filename>]
    [B<-h> I<history-length>] [B<-b> I<key-size>]
    [B<-u> I<user>] [B<-g> I<group>]

=head1 DESCRIPTION

The I<Versioned> <DataSealer> type is designed for production use and
obtains its key material from a simple flat file that allows a history
of several keys to be kept to decrypt older data and continuously
rotate the encryption key on a regular basis, usually daily.

The flat file format consists of lines of the form <name>:<key>, where
the name is typically a number for record keeping but can be any
label, and the key is base64-encoded. The key length dictates which
AES-GCM algorithm is used, among the supported key sizes
(128,192,256). The "default" key used for new operations is the last
line in the file.

This script provides a simple means of rotating the key, and the
Service Provider software will typically detect when the file changes
and reload it.

=head1 OPTIONS

=over 4

=item B<-b> I<key-size>

Number of random bits in the newly generated key.  See above for the
supported sizes.  The default is 128.

=item B<-g> I<group>

Change the group ownership of the key file to this group.  The default
is C<_shibd>.

=item B<-h> I<history-length>

The maximum number of keys to keep in the file.  The default is 14.

=item B<-f> I<filename>

The name of the file containing the keys in I<output-dir>.  The
default is C<sealer.keys>.

=item B<-o> I<output-dir>

The key file and a temporary key file are created in this directory.
The default is C</etc/shibboleth>.

=item B<-u> I<user>

Change the ownership of the key file to this user.  The default is
C<_shibd>.

=back

=head1 FILES

=over 4

=item F</etc/shibboleth/sealer.keys>

The default key file rotated by this script.

=back

=head1 AUTHOR

This manual page was written by Ferenc Wágner for Debian GNU/Linux
using the text on
https://wiki.shibboleth.net/confluence/display/SP3/VersionedDataSealer.

=head1 COPYRIGHT

Copyright 2018 Shibboleth Project.  License: Creative Commons
Attribution-ShareAlike 3.0.

=cut
