#!/usr/bin/perl
#
# Generate an exported Kerberos credential.
#
# This script is not run automatically by the build process or by the test
# suite, since the point of this section of the test suite is to verify that
# the newly-built code can parse Kerberos credentials generated by previous
# versions.  It's here as documentation for how the Kerberos tokens were
# generated.
#
# This script will read the given Kerberos ticket cache and generate an
# exported credential from that cache, so variations in Kerberos ticket data
# should be handled by getting a variety of different tickets.  Consider
# generating at least the following:
#
# 1. Regular, non-renewable, non-forwardable tickets.
# 2. Forwardable tickets.
# 3. Renewable tickets with some renewable lifetime.
# 4. Tickets with addresses.
# 5. A few different Kerberos encryption types.
# 6. Both a TGT and a service ticket for some other principal.

use 5.010;
use autodie;
use strict;
use warnings;

use Getopt::Long qw(GetOptions);
use WebAuth 3.06;

# Parse command-line options.  By default, use the system default ticket
# cache, which is probably the KRB5CCNAME environment setting, but one can be
# passed on the command line.  Takes the principal to export which, if not
# set, defaults to the TGT for the local realm.
my ($cache, $output, $principal);
GetOptions(
    'c|cache=s'     => \$cache,
    'o|output=s'    => \$output,
    'p|principal=s' => \$principal,
) or exit 1;

# Create the WebAuth Kerberos context and initialize from the cache.
my $wa   = WebAuth->new();
my $krb5 = $wa->krb5_new();
if (defined $cache) {
    $krb5->init_via_cache($cache);
} else {
    $krb5->init_via_cache();
}

# Export the credentials.
my $cred;
if (defined $principal) {
    $cred = $krb5->export_cred($principal);
} else {
    $cred = $krb5->export_cred();
}

# Print out the encoded credential.
if (defined($output)) {
    open(my $out_fh, '>', $output);
    print {$out_fh} $cred or die "Cannot write to $output: $!\n";
    close($out_fh);
} else {
    print {*STDOUT} $cred or die "Cannot write to STDOUT: $!\n";
}

__END__

=for stopwords
Allbery KRB5CCNAME KDC MERCHANTABILITY NONINFRINGEMENT TGT WebAuth
WebAuth-encoded kinit make-krb5-cred nul sublicense

=head1 NAME

make-krb5-cred - Generate a WebAuth-encoded Kerberos credential

=head1 SYNOPSIS

B<make-krb5-cred> [B<-c> I<cache>] [B<-o> I<output>] [B<-p> I<principal>]

=head1 REQUIREMENTS

Perl 5.10 or later and the WebAuth Perl modules from WebAuth 4.4.0 or
later.

=head1 DESCRIPTION

B<make-krb5-cred> exports a Kerberos credential from a Kerberos ticket
cache in the encoding format used in WebAuth tokens.  It is primarily
intended as a testing tool.

By default, it uses the system default Kerberos ticket cache (normally
whatever the KRB5CCNAME environment variable points to, with some
system-specific fallback), exports the Kerberos TGT from that ticket
cache, and prints it to standard output.  Be aware that the encoding
format is binary and includes nul characters, so when generating encoded
credentials to standard output, you will probably want to redirect that
output to a file.

The Kerberos ticket cache must already exist before running this program.
To create a variety of different Kerberos credentials, use options to
B<kinit> or a similar program to request different types of tickets.

=head1 OPTIONS

=over 4

=item B<-c> I<cache>, B<--cache>=I<cache>

The Kerberos ticket cache to use as a source of Kerberos credentials.

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

The path to a file to which to write the encoded credential.  If this
option is given, the specified file will be overwritten with the encoded
credential rather than printing the credential to standard output.

=item B<-p> I<principal>, B<--principal>=I<principal>

The principal for which to export credentials.  If the Kerberos ticket
cache does not already contain credentials for that principal, they will
be retrieved from the KDC if possible.

=back

=head1 SEE ALSO

kinit(1)

This script is is part of the WebAuth distribution, the current version of
which can be found at L<http://webauth.stanford.edu/>.

=head1 AUTHOR

Russ Allbery <rra@stanford.edu>

=head1 COPYRIGHT AND LICENSE

Copyright 2012, 2013 The Board of Trustees of the Leland Stanford Junior
University

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

=cut
