From 5d7f614e88bac459a693f1dcc91aad36ed3d00dd Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Tue, 9 Feb 2010 23:57:10 -0800 Subject: Reorganize main POD tests and add a spelling check Add a POD spelling test to the non-Perl-module part of the code and move the documentation tests into a separate directory. Merge the POD syntax tests between client and server into one test. Reformat all of the POD documentation to use 74 columns. Fix a few revealed spelling errors or weird wordings. --- client/wallet.pod | 11 ++++--- server/keytab-backend | 64 +++++++++++++++++++----------------- server/wallet-admin | 17 ++++++---- server/wallet-backend | 83 +++++++++++++++++++++++++---------------------- tests/TESTS | 4 +-- tests/client/pod-t | 22 ------------- tests/docs/pod-spelling-t | 80 +++++++++++++++++++++++++++++++++++++++++++++ tests/docs/pod-t | 21 ++++++++++++ tests/server/pod-t | 22 ------------- 9 files changed, 200 insertions(+), 124 deletions(-) delete mode 100755 tests/client/pod-t create mode 100755 tests/docs/pod-spelling-t create mode 100755 tests/docs/pod-t delete mode 100755 tests/server/pod-t 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 [B<-hv>] [B<-c> I] [B<-f> I] @@ -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 scheme, the identifier is a principal name -and only that principal is authorized by that ACL entry. For the C -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 and see your @@ -201,7 +204,7 @@ Display the history of the ACL . 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 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 -# 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 retrieve I =head1 DESCRIPTION -B 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 -patched to support the B<-norandkey> option to B. +B 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 patched to support the B<-norandkey> option to B. -This script is intended to run under B. 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. 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 does not do any authorization checks. Those should be done -by B before it is called. +B does not do any authorization checks. Those should be +done by B before it is called. =head1 FILES @@ -193,19 +199,19 @@ by B before it is called. =item F -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. 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. Any principal that does +not match one of those regular expressions cannot be retrieved. =item F The temporary directory used for creating keytabs. B 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. +This program is part of the wallet system. The current version is +available from L. =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 -# 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 I [I ...] @@ -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 @@ -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. +This program is part of the wallet system. The current version is +available from L. =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 -# 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 [B<-q>] I [I ...] =head1 DESCRIPTION -B implements the interface between B and the wallet -system. It is written to run under B 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 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 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 implements the interface between B and the +wallet system. It is written to run under B 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 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 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 . 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 @@ -447,8 +454,8 @@ The expiration will be displayed in seconds since epoch. If is given, sets the expiration on the object identified by and to and (if given)