diff options
| -rw-r--r-- | client/wallet.pod | 11 | ||||
| -rwxr-xr-x | server/keytab-backend | 64 | ||||
| -rwxr-xr-x | server/wallet-admin | 17 | ||||
| -rwxr-xr-x | server/wallet-backend | 83 | ||||
| -rw-r--r-- | tests/TESTS | 4 | ||||
| -rwxr-xr-x | tests/client/pod-t | 22 | ||||
| -rwxr-xr-x | tests/docs/pod-spelling-t | 80 | ||||
| -rwxr-xr-x | tests/docs/pod-t | 21 | ||||
| -rwxr-xr-x | tests/server/pod-t | 22 |
9 files changed, 200 insertions, 124 deletions
diff --git a/client/wallet.pod b/client/wallet.pod index 9908bb1..09fb571 100644 --- a/client/wallet.pod +++ b/client/wallet.pod @@ -2,6 +2,11 @@ wallet - Client for retrieving secure data from a central server +=for stopwords +-hv srvtab arg keytabs metadata keytab ACL PTS kinit klist remctl PKINIT +acl timestamp autocreate backend-specific setacl enctypes enctype ktadd +KDC appdefaults remctld Allbery nul uuencode getacl backend + =head1 SYNOPSIS B<wallet> [B<-hv>] [B<-c> I<command>] [B<-f> I<file>] @@ -44,9 +49,7 @@ entries, each of which is a scheme and an identifier. A scheme specifies a way of checking whether a user is authorized. An identifier is some data specific to the scheme that specifies which users are authorized. For example, for the C<krb5> scheme, the identifier is a principal name -and only that principal is authorized by that ACL entry. For the C<pts> -scheme, the identifier is a PTS group name, and all members of that PTS -group are authorized by that ACL entry. +and only that principal is authorized by that ACL entry. To run the wallet command-line client, you must already have a Kerberos ticket. You can obtain a Kerberos ticket with B<kinit> and see your @@ -201,7 +204,7 @@ Display the history of the ACL <id>. Each change to the ACL (not including changes to the name of the ACL) will be represented by two lines. The first line will have a timestamp of the change followed by a description of the change, and the second line will give the user who made -the change and the host from which the change was mde. +the change and the host from which the change was made. =item acl remove <id> <scheme> <identifier> diff --git a/server/keytab-backend b/server/keytab-backend index b37fb3a..7b6adb4 100755 --- a/server/keytab-backend +++ b/server/keytab-backend @@ -17,7 +17,8 @@ # The keytab for the extracted principal will be printed to standard output. # # Written by Russ Allbery <rra@stanford.edu> -# Copyright 2006, 2007, 2008 Board of Trustees, Leland Stanford Jr. University +# Copyright 2006, 2007, 2008, 2010 +# Board of Trustees, Leland Stanford Jr. University # # See LICENSE for licensing terms. @@ -155,6 +156,10 @@ __END__ # Documentation ############################################################################## +=for stopwords +keytab-backend keytabs KDC keytab kadmin.local -norandkey ktadd remctld +auth Allbery rekeying + =head1 NAME keytab-backend - Extract keytabs from the KDC without changing the key @@ -165,27 +170,28 @@ B<keytab-backend> retrieve I<principal> =head1 DESCRIPTION -B<keytab-backend> retrieves a keytab for an existing principal from the KDC -database without changing the current key. It allows generation of a keytab -for a service without rekeying that service. It requires a B<kadmin.local> -patched to support the B<-norandkey> option to B<ktadd>. +B<keytab-backend> retrieves a keytab for an existing principal from the +KDC database without changing the current key. It allows generation of a +keytab for a service without rekeying that service. It requires a +B<kadmin.local> patched to support the B<-norandkey> option to B<ktadd>. -This script is intended to run under B<remctld>. On success, it prints the -keytab to standard output, logs a success message to syslog (facility auth, -priority info), and exits with status 0. On failure, it prints out an error -message, logs an error to syslog (facility auth, priority err), and exits -with a non-zero status. +This script is intended to run under B<remctld>. On success, it prints +the keytab to standard output, logs a success message to syslog (facility +auth, priority info), and exits with status 0. On failure, it prints out +an error message, logs an error to syslog (facility auth, priority err), +and exits with a non-zero status. The principal is checked for basic sanity (only accepting alphanumerics, -C<_>, and C<-> with an optional instance and then only alphanumerics, C<_>, -C<->, and C<.> in the realm) and then checked against a configuration file -that lists regexes of principals that can be retrieved. When deploying this -software, limit as tightly as possible which principals can be downloaded in -this fashion. Generally only shared service principals used on multiple -systems should be made available in this way. +C<_>, and C<-> with an optional instance and then only alphanumerics, +C<_>, C<->, and C<.> in the realm) and then checked against a +configuration file that lists regexes of principals that can be retrieved. +When deploying this software, limit as tightly as possible which +principals can be downloaded in this fashion. Generally only shared +service principals used on multiple systems should be made available in +this way. -B<keytab-backend> does not do any authorization checks. Those should be done -by B<remctld> before it is called. +B<keytab-backend> does not do any authorization checks. Those should be +done by B<remctld> before it is called. =head1 FILES @@ -193,19 +199,19 @@ by B<remctld> before it is called. =item F</etc/krb5kdc/allow-extract> -The configuration file that controls which principals can have their keytabs -retrieved. Blank lines and lines starting with C<#>, as well as anything -after C<#> on a line, are ignored. All other lines should be Perl regular -expressions, one per line, that match principals whose keytabs can be -retrieved by B<keytab-backend>. Any principal that does not match one of -those regular expressions cannot be retrieved. +The configuration file that controls which principals can have their +keytabs retrieved. Blank lines and lines starting with C<#>, as well as +anything after C<#> on a line, are ignored. All other lines should be +Perl regular expressions, one per line, that match principals whose +keytabs can be retrieved by B<keytab-backend>. Any principal that does +not match one of those regular expressions cannot be retrieved. =item F</var/lib/keytabs> The temporary directory used for creating keytabs. B<keytab-backend> will -create the keytab in this directory, make sure that was successful, and then -delete the temporary file after the results have been sent to standard -output. +create the keytab in this directory, make sure that was successful, and +then delete the temporary file after the results have been sent to +standard output. =back @@ -213,8 +219,8 @@ output. kadmin.local(8), remctld(8) -This program is part of the wallet system. The current version is available -from L<http://www.eyrie.org/~eagle/software/wallet/>. +This program is part of the wallet system. The current version is +available from L<http://www.eyrie.org/~eagle/software/wallet/>. =head1 AUTHOR diff --git a/server/wallet-admin b/server/wallet-admin index cd775b6..828cfc5 100755 --- a/server/wallet-admin +++ b/server/wallet-admin @@ -1,9 +1,9 @@ #!/usr/bin/perl -w # -# wallet-admin -- Wallet server administrative commands. +# wallet-backend -- Wallet server administrative commands. # # Written by Russ Allbery <rra@stanford.edu> -# Copyright 2008, 2009 Board of Trustees, Leland Stanford Jr. University +# Copyright 2008, 2009, 2010 Board of Trustees, Leland Stanford Jr. University # # See LICENSE for licensing terms. @@ -110,6 +110,9 @@ __END__ wallet-admin - Wallet server administrative commands +=for stopwords +metadata ACL hostname backend acl acls wildcard SQL Allbery + =head1 SYNOPSIS B<wallet-admin> I<command> [I<args> ...] @@ -171,8 +174,8 @@ be listed in the form: In both cases, there will be one line per ACL or object. -If no searchtype is given, all the ACLs or objects in the database will -be returned. If a searchtype (and possible search arguments) are given, +If no search type is given, all the ACLs or objects in the database will +be returned. If a search type (and possible search arguments) are given, then the ACLs or objects will be limited to those that match the search. The currently supported object search types are: @@ -206,7 +209,7 @@ The currently supported ACL search types are: =item list acls empty Returns all ACLs which have no entries, generally so that abandoned ACLs -can be housekept. +can be destroyed. =item list acls entry <schema> <identifier> @@ -256,8 +259,8 @@ with duplicates suppressed. Wallet::Admin(3), Wallet::Config(3), wallet-backend(8) -This program is part of the wallet system. The current version is available -from L<http://www.eyrie.org/~eagle/software/wallet/>. +This program is part of the wallet system. The current version is +available from L<http://www.eyrie.org/~eagle/software/wallet/>. =head1 AUTHOR diff --git a/server/wallet-backend b/server/wallet-backend index 0770f97..7780758 100755 --- a/server/wallet-backend +++ b/server/wallet-backend @@ -3,7 +3,7 @@ # wallet-backend -- Wallet server for storing and retrieving secure data. # # Written by Russ Allbery <rra@stanford.edu> -# Copyright 2007, 2008 Board of Trustees, Leland Stanford Jr. University +# Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University # # See LICENSE for licensing terms. @@ -311,6 +311,11 @@ __END__ # The commands section of this document is duplicated from the documentation # for wallet and should be kept in sync. +=for stopwords +wallet-backend backend backend-specific remctld ACL acl timestamp getacl +setacl metadata nul keytab keytabs enctypes enctype ktadd KDC Allbery +autocreate + =head1 NAME wallet-backend - Wallet server for storing and retrieving secure data @@ -321,20 +326,22 @@ B<wallet-backend> [B<-q>] I<command> [I<args> ...] =head1 DESCRIPTION -B<wallet-backend> implements the interface between B<remctld> and the wallet -system. It is written to run under B<remctld> and expects the authenticated -identity of the remote user in the REMOTE_USER environment variable. It -uses REMOTE_HOST or REMOTE_ADDR if REMOTE_HOST isn't set for additional -trace information. It accepts the command from B<remctld> on the command -line, creates a Wallet::Server object, and calls the appropriate methods. - -This program is a fairly thin wrapper around Wallet::Server that translates -command strings into method calls and returns the results. It does check -all arguments except for the <data> argument to the store command and -rejects any argument not matching C<^[\w_/.-]+\z>; in other words, only -alphanumerics, underscore (C<_>), slash (C</>), period (C<.>), and hyphen -(C<->) are permitted in arguments. This provides some additional security -over and above the checking already done by the rest of the wallet code. +B<wallet-backend> implements the interface between B<remctld> and the +wallet system. It is written to run under B<remctld> and expects the +authenticated identity of the remote user in the REMOTE_USER environment +variable. It uses REMOTE_HOST or REMOTE_ADDR if REMOTE_HOST isn't set for +additional trace information. It accepts the command from B<remctld> on +the command line, creates a Wallet::Server object, and calls the +appropriate methods. + +This program is a fairly thin wrapper around Wallet::Server that +translates command strings into method calls and returns the results. It +does check all arguments except for the <data> argument to the store +command and rejects any argument not matching C<^[\w_/.-]+\z>; in other +words, only alphanumerics, underscore (C<_>), slash (C</>), period (C<.>), +and hyphen (C<->) are permitted in arguments. This provides some +additional security over and above the checking already done by the rest +of the wallet code. =head1 OPTIONS @@ -400,7 +407,7 @@ Display the history of the ACL <id>. Each change to the ACL (not including changes to the name of the ACL) will be represented by two lines. The first line will have a timestamp of the change followed by a description of the change, and the second line will give the user who made -the change and the host from which the change was mde. +the change and the host from which the change was made. =item acl remove <id> <scheme> <identifier> @@ -447,8 +454,8 @@ The expiration will be displayed in seconds since epoch. If <date> is given, sets the expiration on the object identified by <type> and <name> to <date> and (if given) <time>. <date> must be in the format -C<YYYY-MM-DD> and <time> in the format C<HH:MM:SS>. If <date> is the empty -string, clears the expiration of the object. +C<YYYY-MM-DD> and <time> in the format C<HH:MM:SS>. If <date> is the +empty string, clears the expiration of the object. Currently, the expiration of an object is not used. @@ -460,16 +467,16 @@ Clears the flag <flag> on the object identified by <type> and <name>. Sets the flag <flag> on the object identified by <type> and <name>. Recognized flags are C<locked>, which prevents all further actions on that -object until the flag is cleared, and C<unchanging>, which tells the object -backend to not generate new data on get but instead return the same data as -previously returned. The C<unchanging> flag is not meaningful for objects -that do not generate new data on the fly. +object until the flag is cleared, and C<unchanging>, which tells the +object backend to not generate new data on get but instead return the same +data as previously returned. The C<unchanging> flag is not meaningful for +objects that do not generate new data on the fly. =item get <type> <name> -Prints to standard output the data associated with the object identified by -<type> and <name>. This may trigger generation of new data and invalidate -old data for that object depending on the object type. +Prints to standard output the data associated with the object identified +by <type> and <name>. This may trigger generation of new data and +invalidate old data for that object depending on the object type. =item getacl <type> <name> <acl> @@ -485,17 +492,17 @@ or setting it. Prints the object attribute <attr> for the object identified by <type> and <name>. Attributes are used to store backend-specific information for a particular object type, and <attr> must be an attribute type known to the -underlying object implementation. The attribute values, if any, are printed -one per line. If the attribute is not set on this object, nothing is -printed. +underlying object implementation. The attribute values, if any, are +printed one per line. If the attribute is not set on this object, nothing +is printed. =item history <type> <name> -Displays the history for the object identified by <type> and <name>. -This human-readable output will have two lines for each action that -changes the object, plus for any get action. The first line has the -timestamp of the action and the action, and the second line gives the user -who performed the action and the host from which they performed it. +Displays the history for the object identified by <type> and <name>. This +human-readable output will have two lines for each action that changes the +object, plus for any get action. The first line has the timestamp of the +action and the action, and the second line gives the user who performed +the action and the host from which they performed it. =item owner <type> <name> [<owner>] @@ -562,9 +569,9 @@ values of this attribute must be enctype strings recognized by Kerberos the salt should not be included; since the salt is irrelevant for keytab keys, it will always be set to C<normal> by the wallet. -If this attribute is set, the specified enctype list will be passed to ktadd -when get() is called for that keytab. If it is not set, the default set in -the KDC will be used. +If this attribute is set, the specified enctype list will be passed to +ktadd when get() is called for that keytab. If it is not set, the default +set in the KDC will be used. This attribute is ignored if the C<unchanging> flag is set on a keytab. Keytabs retrieved with C<unchanging> set will contain all keys present in @@ -577,8 +584,8 @@ enctypes than those requested by this attribute. Wallet::Server(3), remctld(8) -This program is part of the wallet system. The current version is available -from L<http://www.eyrie.org/~eagle/software/wallet/>. +This program is part of the wallet system. The current version is +available from L<http://www.eyrie.org/~eagle/software/wallet/>. =head1 AUTHOR diff --git a/tests/TESTS b/tests/TESTS index ac6fd82..161941c 100644 --- a/tests/TESTS +++ b/tests/TESTS @@ -1,7 +1,8 @@ client/basic client/full -client/pod client/prompt +docs/pod +docs/pod-spelling portable/asprintf portable/mkstemp portable/setenv @@ -11,7 +12,6 @@ portable/strlcpy server/admin server/backend server/keytab -server/pod util/concat util/messages util/messages-krb5 diff --git a/tests/client/pod-t b/tests/client/pod-t deleted file mode 100755 index 9963567..0000000 --- a/tests/client/pod-t +++ /dev/null @@ -1,22 +0,0 @@ -#!/usr/bin/perl -# -# Test POD formatting for client documentation. -# -# Written by Russ Allbery <rra@stanford.edu> -# Copyright 2008, 2010 Board of Trustees, Leland Stanford Jr. University -# -# See LICENSE for licensing terms. - -use Test::More; - -my @files = qw(wallet.pod); -my $total = scalar (@files); -plan tests => $total; - -eval 'use Test::Pod 1.00'; -SKIP: { - skip $total, 'Test::Pod 1.00 required for testing POD' if $@; - for my $file (@files) { - pod_file_ok ("$ENV{SOURCE}/../client/$file", "client/$file"); - } -} diff --git a/tests/docs/pod-spelling-t b/tests/docs/pod-spelling-t new file mode 100755 index 0000000..433d841 --- /dev/null +++ b/tests/docs/pod-spelling-t @@ -0,0 +1,80 @@ +#!/usr/bin/perl +# +# Check for spelling errors in POD documentation +# +# Checks all POD files in the tree for spelling problems using Pod::Spell and +# either aspell or ispell. aspell is preferred. This test is disabled unless +# RRA_MAINTAINER_TESTS is set, since spelling dictionaries vary too much +# between environments. +# +# Copyright 2008, 2009 Russ Allbery <rra@stanford.edu> +# +# See LICENSE for licensing terms. + +use strict; +use Test::More; + +# Skip all spelling tests unless the maintainer environment variable is set. +plan skip_all => 'spelling tests only run for maintainer' + unless $ENV{RRA_MAINTAINER_TESTS}; + +# Load required Perl modules. +eval 'use Test::Pod 1.00'; +plan skip_all => 'Test::Pod 1.00 required for testing POD' if $@; +eval 'use Pod::Spell'; +plan skip_all => 'Pod::Spell required to test POD spelling' if $@; + +# Locate a spell-checker. hunspell is not currently supported due to its lack +# of support for contractions (at least in the version in Debian). +my @spell; +my %options = (aspell => [ qw(-d en_US --home-dir=./ list) ], + ispell => [ qw(-d american -l -p /dev/null) ]); +SEARCH: for my $program (qw/aspell ispell/) { + for my $dir (split ':', $ENV{PATH}) { + if (-x "$dir/$program") { + @spell = ("$dir/$program", @{ $options{$program} }); + } + last SEARCH if @spell; + } +} +plan skip_all => 'aspell or ispell required to test POD spelling' + unless @spell; + +# Prerequisites are satisfied, so we're going to do some testing. Figure out +# what POD files we have and from that develop our plan. +$| = 1; +my @pod = map { + my $pod = "$ENV{SOURCE}/../" . $_; + $pod =~ s,[^/.][^/]*/../,,g; + $pod; +} qw(client/wallet.pod server/keytab-backend server/wallet-admin + server/wallet-backend); +plan tests => scalar @pod; + +# Finally, do the checks. +for my $pod (@pod) { + my $child = open (CHILD, '-|'); + if (not defined $child) { + BAIL_OUT ("cannot fork: $!"); + } elsif ($child == 0) { + my $pid = open (SPELL, '|-', @spell) + or BAIL_OUT ("cannot run @spell: $!"); + open (POD, '<', $pod) or BAIL_OUT ("cannot open $pod: $!"); + my $parser = Pod::Spell->new; + $parser->parse_from_filehandle (\*POD, \*SPELL); + close POD; + close SPELL; + exit ($? >> 8); + } else { + my @words = <CHILD>; + close CHILD; + SKIP: { + skip "@spell failed for $pod", 1 unless $? == 0; + for (@words) { + s/^\s+//; + s/\s+$//; + } + is ("@words", '', $pod); + } + } +} diff --git a/tests/docs/pod-t b/tests/docs/pod-t new file mode 100755 index 0000000..9b6c5d1 --- /dev/null +++ b/tests/docs/pod-t @@ -0,0 +1,21 @@ +#!/usr/bin/perl -w +# +# Test POD formatting for documentation. +# +# Written by Russ Allbery <rra@stanford.edu> +# Copyright 2008, 2010 Board of Trustees, Leland Stanford Jr. University +# +# See LICENSE for licensing terms. + +use strict; +use Test::More; +eval 'use Test::Pod 1.00'; +plan skip_all => 'Test::Pod 1.00 required for testing POD' if $@; + +my @files = qw(client/wallet.pod server/keytab-backend server/wallet-admin + server/wallet-backend); +my $total = scalar (@files); +plan tests => $total; +for my $file (@files) { + pod_file_ok ("$ENV{SOURCE}/../$file", $file); +} diff --git a/tests/server/pod-t b/tests/server/pod-t deleted file mode 100755 index 52d81eb..0000000 --- a/tests/server/pod-t +++ /dev/null @@ -1,22 +0,0 @@ -#!/usr/bin/perl -# -# Test POD formatting for client documentation. -# -# Written by Russ Allbery <rra@stanford.edu> -# Copyright 2008, 2010 Board of Trustees, Leland Stanford Jr. University -# -# See LICENSE for licensing terms. - -use Test::More; - -my @files = qw(keytab-backend wallet-admin wallet-backend); -my $total = scalar (@files); -plan tests => $total; - -eval 'use Test::Pod 1.00'; -SKIP: { - skip 'Test::Pod 1.00 required for testing POD', $total if $@; - for my $file (@files) { - pod_file_ok ("$ENV{SOURCE}/../server/$file", "server/$file"); - } -} |