#!/usr/bin/perl
##############################################################################
#
# Tools for interacting with the New Zealand 'igovt Logon Service'
# (see: https://i.govt.nz/ ).
#
# These tools ARE NOT produced by, nor endorsed by the Department of Internal
# Affairs who operate the igovt logon service.  They are merely an implemention
# of the published protocols.
#
# For more information, see:
#
#   nzigovt --help
#

use strict;
use warnings;

use Pod::Usage;
use Getopt::Long qw(GetOptions);

use Authen::NZigovt;

my(%opt);

if(!GetOptions(\%opt,
    'help|?',
    'version',
    'conf_dir|conf-dir|c=s',
    'allow_create|allow-create',
    'env=s',
    'org=s',
    'org_unit|org-unit=s',
    'subject=s',
    'domain=s',
)) {
    pod2usage(-exitval => 1,  -verbose => 0);
}


if($opt{help} or (@ARGV && $ARGV[0] eq 'help')) {
    pod2usage(-exitstatus => 0, -verbose => 2);
}

$ARGV[0] ||= 'version' if $opt{version};

eval { Authen::NZigovt->run_command(\%opt, @ARGV); };
if($@) {
    pod2usage(-exitstatus => 1, -verbose => 0, -message => "$@");
}

exit 0;

__END__

=head1 NAME

nzigovt - Tools for interacting with the New Zealand 'igovt Logon Service'

=head1 SYNOPSIS

  nzigovt [options] <command> [args ...]

  Commands:

   make-meta   generate XML metadata for your Service Provider (SP)
   make-certs  generate certificate/key-pair files
   make-bundle generate a zip archive of metadata and certificate files
   make-req    generate a SAML AuthnRequest, encoded as a URL
   dump-req    dissect the provided URL and dump the XML
   resolve     resolve an artifact to an FLT
   version     print module version number and exit
   help        detailed help message

  Options:

   --conf-dir <path>  pathname of directory containing metadata & cert files
   --allow-create     can be used with 'make-req' to allow account creation
   --env <name>       target environment (must be: 'mts', 'ite' or 'prod')
   --org <name>       organisation/agency name, e.g.: "Department of Innovation"
   --org-unit <name>  organisational unit, e.g.: "Innovation Labs"
   --subject <detail> additional detail for certificate subject
   --domain <name>    agency site domain e.g.: innovation.govt.nz

=head1 DESCRIPTION

The C<nzigovt> script and related modules from the L<Authen::NZigovt>
distribution provide tools for interacting with the New Zealand 'igovt logon
service' operated by the Department of Internal Affairs.  These tools ARE NOT
produced by nor endorsed by the Department of Internal Affairs.  They are
merely an implemention of the published protocols.

=head1 COMMANDS

The following commands are available:

=over 4

=item make-certs

Generate two certificate/key pairs - one for signing and one for mutual SSL
encryption.  This step is not required for integrating with the development
environment ('MTS') since certficates will be provided to you.  For integration
with the test environment ('ITE') two self-signed certificates will be
generated.  For integration with the production environment ('PROD') two CSRs
(Certificate Signing Requests) will be generated which you will then use to get
signed certificates issued from an approved CA (Certification Authority).

=item make-meta

Generate (or edit) a Service Provider metadata file and save it with a digital
signature.

=item make-bundle

Create a ZIP file containing the metadata and certificate files needed by
the Identity Provider.

=item make-req

Generate a URL containing a SAML AuthnRequest - for initiating a logon.

Note: By default, the AuthnRequest will have the AllowCreate flag set to false
(i.e.: the user must already have an igovt logon associated with this SP).  Use
C<--allow-create> if you want the request to allow a new account and FLT to be
created.

=item dump-req <request URL>

Takes a URL containing a SAML AuthnRequest; decodes it; and dumps the XML.  For
example:

  nzigovt -c /etc/igovt-conf make-req | nzigovt -c /etc/igovt-conf dump-req

This utility can be used to dump AuthnRequests produced by any SAML
implementation.

=item resolve <artifact> <request ID>

This command takes two arguments - an artifact (either the whole URL or just
the SAMLart part from the query string) and the request ID which was output
from the original 'make-req' command.

The command will decode the SAML artifact; generate a SAML ArtifactResolve
request; send the request to the IdP using SOAP over the SSL back-channel;
validate the resulting assertion; and extract the FLT (Federated Logon Tag)
from the response.

Note: in practice a SML artifact must be resolved very soon after it is
generated or it will expire.

=item version

Print version number of L<Authen::NZigovt> module and exit.

=item help

Display this documentation.

=back


=head1 OPTIONS

=over 4

=item B<< --conf-dir <directory> >> (alias -c)

Specify the path to the directory containing the metadata files and
certificate/key-pair files for signing requests and encrypting SSL traffic.
See C<< perldoc Authen::NZigovt >> for more information about config files.

=item B<< --env <name> >>

This option can be used with the C<make-certs> command and specifies the
target environment for the certificates.  Acceptable values are 'mts', 'ite'
and 'prod'.

If you do not provide any certificate parameters, you will be prompted.

=item B<< --org "<name>" >>

The service provider agency/organisation name which should be used in the
certificates.

=item B<< --org-unit "<name>" >>

The optional organisational unit name for use in the certificates.

=item B<< --subject "<detail>" >>

Optional additional details to go on the end of the certificate subject field.
The CN will be calculated for you based on --domain.  The O and OU will be
added based on --org and --org-unit.  Prefix each fieldname with a forward
slash (e.g.: --subject /L=Wellington/ST=Wellington/C=NZ).

=back


=head1 LICENSE AND COPYRIGHT

Copyright (c) 2010-2011 the New Zealand Electoral Enrolment Centre

Written by Grant McLean E<lt>grant@catalyst.net.nzE<gt>

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.


=cut



