AUTHENTICATION OF USENET GROUP CHANGES

   This document addresses a method for the authentication of the special
   types of Usenet articles that are used to maintain the namespace of
   Usenet groups. A basic familiarity with what the Usenet control
   message types "newgroup", "rmgroup" and "checkgroups" do is assumed;
   this is not a tutorial in namespace administration.

   Usenet articles are notoriously easy to forge, and control messages
   are no exception. Since administrators often want to have their news
   systems automatically honor requests from some particular people to
   add or remove newsgroups, it is risky to trust the From: and Sender:
   headers to identify the real sender of a message, as has historically
   been done. Thus a system using Philip Zimmerman's Pretty Good
   Privacy(tm) (PGP (tm)) was developed to provide a more secure means of
   authenticating the sender of a control message.

   Unlike traditional PGP authentication of messages, which just verifies
   that the contents of the body of a message are unchanged from when it
   was digitally "signed", this system also needed to sign a few headers
   of the control message to verify the action to be taken and to guard
   against certain other pitfalls. Another goal was to make the signature
   as unobtrusive as possible and require minimal changes to existing
   software in order to work.

How to Verify Control Messages

   Listed below are the steps you need to take to enable PGP
   authentication of control messages on your system.

   Here is the short and simple version for someone who feels confident
   hacking around the news system and doesn't like to read a lot:

    1. Get and configure the software:
          + ftp://ftp.isc.org/pub/pgpcontrol/pgpverify
          + ftp://ftp.isc.org/pub/pgpcontrol/server-patches/
    2. Add maintainers' PGP public keys to the news system key ring.
    3. Enable verification through the news system authorization system.

        INN:    Use the action verify-pgp_userid (possibly appended
                =logfile) in control.ctl.

        C News: Use the action "p" in the fourth field of controlperm
                followed by a suitable pgp_userid in the fifth field.

        D News: Use the action "doit,pgp" in control.conf.
        ANU News:
                Use the "HELP ADD FILE PGP_verification" ANU command.

        Other systems:
                Sorry, not implemented yet.

    4. Test pgpverify. If you have the news.announce.newgroups key in
       your key ring, run
       ftp://ftp.isc.org/pub/pgpcontrol/sample.control
       through pgpverify on stdin. It should spit out the string
       "news.announce.newgroups" on stdout.

   Here is a more verbose version of the instructions:

    1. Get the software.

       There are two pieces of code that will need to be added to a news
       server to make use of this authentication system: a stand-alone
       script that verifies an article is what it says it is, and a patch
       to hook it into the news server's processing of control messages.

       The stand-alone program, ftp://ftp.isc.org/pub//pgpcontrol/pgpverify,
       is a Perl script that should work with Perl version 4 and up. (I have
       not tested it with earlier versions.) It does not contain any code
       making it dependent on any particular news server software.

       ftp://ftp.isc.org/pub/pgpcontrol/server-patches/
       has patches for hooking the system into existing news server
       software. Choose the one for your system from the list below.

          + INN version 1.4sec
          + INN version 1.4unoff4
          + C News version CR.G
            (Courtesy of System Administrator <root@hp9000.laafb.af.mil>
             and Charles Lindsey <chl@clw.cs.man.ac.uk>)

       Newer versions of INN (since 1.5), D News and ANU News (since 6.2.0)
       do not need to be patched, as they ship with built-in handling for
       pgp verification.  You can therefore skip past the "Install it
       on your news system" section to "Enable verification for the
       hierarchies that interest you".  I recommend that you upgrade
       to INN 1.5.1sec if you are running any prior INN version,
       because it has a few important security problems fixed.

       I regret that I do not have the time to develop more patches,
       but I will gladly add patches for other systems to this page as
       they are made available to me.  The INN version 1.4sec patch
       will apply to all INN "unoff" versions, albeit with a little
       bit of fuzz.  I am not positive what versions of C News will
       work with the C News CR.G patch; if you try it with C News
       CR.E, please let me know how it goes.

    2. Install it in your news system.

       First you must ensure that the absolute paths to perl and to
       pgp are correct in the first few lines of the pgpverify
       program. No other configuration of options or pathnames should be
       needed.

       Next, the following steps assume, solely for the sake of making it
       easy for me to write a simple recipe, that you have copied
       pgpverify and the patch for your system to your news server as
       /tmp/pgpverify and /tmp/pgpcontrol.pch respectively. I have
       tried to format this so that you should be able to cut and paste
       any of the lines in italics directly to your shell.  (Sorry, the 
       italics won't show up in the plain text version of this document.
       Commands versus comments should still be pretty well obvious.)

          + If you are running INN:

                cd to the executable program directory that has ctlinnd.
                mv /tmp/pgpverify pgpverify

                cd to the root of your INN source tree.
                cd site
                patch </tmp/pgpcontrol.pch
                make install

            It has been reported to me that at least one AIX system
            has problems with patch not applying the last section of
            parsecontrol.pch.  If you run AIX, double check it and
            apply by manually editing, if necessary.

          + If you are running C News:

                cd to the root of the C News executable program directory;
                   it is the one with the program "spacefor" in it.
                mv /tmp/pgpverify pgpverify

                cd to the root of your C News source tree.
                cd ctl
                patch </tmp/pgpcontrol.pch
                make install

          + If you are running some other system:

            You're out of luck until someone writes a patch and
            instructions for your system and makes it available to me
            for redistribution.

    3. Enable verification for the hierarchies that interest you.

       To verify messages, you must have a PGP public key for each signer
       that you wish to trust. It should be entered in a key ring that is
       accessible to the user-id that runs the news system by running
       pgp -ka on a file containing the key to add. For example, at a
       site that runs the news server software as news, the following
       command run by the news user-id should add the key bounded by
       BEGIN and END "PGP PUBLIC KEY BLOCK" lines in the file /tmp/key
       to the default key ring that would be used for authentication:

                pgp -ka /tmp/key

       As a general policy rule, control message signers will not use their
       control message keys to introduce other keys, so when PGP asks you
       a question similar to, "Would you trust this user to act as an
       introducer and certify other people's public keys to you?" answer
       that you would not.

       After you have added the appropriate key to your key ring, you
       need to tell the news software to validate the control messages
       received. As implemented, the system will perform the requested
       action if the message can be authenticated and it will mail the
       message to the news system administrator if it cannot. Clearly
       there are other possible actions that could be implemented, but I
       wanted to keep the patches minimal. Future releases of the server
       software will probably have increased flexibility.

          + If you are running INN:

            Automatic processing of control messages is handled by
            control.ctl, which you edit in the same site
            subdirectory where you patched parsecontrol. control.ctl
            has several lines at the beginning of it that describe the
            format of the file, and there is an even longer
            control.ctl(5) manual page. To enable PGP verification in
            addition to the normal authorization done by control.ctl,
            use the action "verify-PGP_USERID" in the fourth field.

            For example, if you trust group-admin@isc.org (currently
            David Lawrence <tale@isc.org>, aka tale@uunet.uu.net, the
            author of this document) to manage groups in the "Big 8"
            hierarchies, you could have lines like these (but don't
            use the backslash continuation, which I have used here
            for readability; keep it all on one line):

newgroup:group-admin@isc.org:\
comp.*|humanities.*|misc.*|news.*|rec.*|sci.*|soc.*|talk.*:\
verify-news.announce.newgroups
rmgroup:group-admin@isc.org:\
comp.*|humanities.*|misc.*|news.*|rec.*|sci.*|soc.*|talk.*:\
verify-news.announce.newgroups
checkgroups:group-admin@isc.org:\
comp.*|humanities.*|misc.*|news.*|rec.*|sci.*|soc.*|talk.*:\
verify-news.announce.newgroups

            Additionally, if you like the logging feature available with
            the action doit=logfile, you can get the same logging by
            using verify-pgp_userid=logfile.

          + If you are running C News:

            Automatic processing of control messages is handled by
            controlperm, which you edit in the subdirectory where you
            patched the control message handling scripts.  There is a
            controlperm(5) manual page that describes its format.  To
            enable PGP verification in addition to the normal
            authorization done by controlperm, use the action "p" in
            the fourth field instead of "y" and add a fifth field for
            the pgp_userid.

            For example, if you trust group-admin@isc.org (currently
            David Lawrence <tale@isc.org>, aka tale@uunet.uu.net, the
            author of this document) to manage groups in the "Big 8"
            hierarchies, you could have lines like these (but don't
            use the backslash continuation, which I have used here for
            readability; keep it all on one line):

comp,sci,misc,news,rec,soc,talk group-admin@isc.org       nrc       pv \
news.announce.newgroups

            You could then remove the line that follows the comment,
            "but his name can be forged, so don't let him rmgroup..."

          + If you are running D News:

            Automatic processing of control messages is handled by
            control.conf.  To enable PGP verification in addition to
            the normal authorization done by control.conf, use the
            action "pgp" in the fourth field, in addition to whatever
            action you want to happen.  For example, if you trust
            group-admin@isc.org (currently David Lawrence
            <tale@isc.org>, aka tale@uunet.uu.net, the author of this
            document) to manage groups in the "Big 8" hierarchies, you
            could have lines like these (but don't use the backslash
            continuation, which I have used here for readability; keep
            it all on one line):

newgroup:group-admin@isc.org:\
comp.*,misc.*,news.*,rec.*,sci.*,soc.*,talk.*:doit,pgp
rmgroup:group-admin@isc.org:\
omp.*,misc.*,news.*,rec.*,sci.*,soc.*,talk.*:doit,pgp
checkgroups:group-admin@isc.org:\
comp.*,misc.*,news.*,rec.*,sci.*,soc.*,talk.*:doit,pgp

            Note that there is no provision, with the current D News
            implementation, for checking that the signature matches a
            particular string, just that it it has a valid signature.
            This is probably adequate security as long as you keep the
            news user's PGP key ring limited only to people you trust
            to maintain newsgroup hierarchies.

            Finally, if you have not installed pgp on your system in a
            directory where D News normally looks for auxiliary
            programs, you will need to add a pointer to it in
            dnews.conf, like this:

                    pgp /path/to/pgp

            See http://www.netwinsite.com/pgp.htm for documentation by
            the D News authors that might supersede this document.

          + If you are running ANU News (V6.2.0 or later):

            Instructions will (hopefully) soon appear here.  In the
            meantime, consult the "HELP ADD FILE PGP_verification"
            server command.

          + If you are running some other system:

            You're out of luck until someone writes a patch and
            instructions for your system and makes it available to me for
            redistribution.

    4. Test the system.

       Get ftp://ftp.isc.org/pub/pgpcontrol/sample.control
       and save it to a file on your system; /tmp/sample.control will
       be used for this example. You'll use it to make sure things will
       work as expected.

       To verify the control message, you will need the key for
       news.announce.newgroups and authorization in your news system for
       group-admin@isc.org to automatically perform "newgroup". Go ahead
       and enable it for the test even if you don't want to really allow
       this, because it is easy enough to rescind after the test by
       editing the control message authorization file and removing the
       key with pgp -kr news.announce.newgroups.

       You can check that the pgpverify part of the system will work
       properly simply by feeding it the sample control message on stdin:

                pgpverify < /tmp/sample.control

       If if could run pgp and find the correct key in the default key ring,
       the string news.announce.newgroups should be printed. The exit
       status of the script, found in most shells with the command echo
       $? as the next command after pgpverify, should be 0 (zero).

       If it doesn't work, then

                pgpverify -test < /tmp/sample.control

       might give you some enlightment.  It will print out the input that is
       used for pgp (which is a reconstructed version of the input that
       supposedly created the control message) as well as the output of PGP's
       analysis of the message.  Look especially closely at the latter, since
       it can give you important information such as which keyring is being
       used.

       If it still doesn't work and you've tried and tried to figure out why,
       email me at tale@isc.org a complete description of the problem you are
       having and how you have tried to remedy it. At a bare minimum, your
       mail should include a copy of the message you are trying to verify, a
       typescript of the attempted execution of pgpverify -test, and the
       output of pgp -kc and pgp -kvc news.announce.newgroups.

       When pgpverify passes its test, use the appropriate procedure
       below for you news server to verify the authorization system.

          + If you are running INN:

            First, cd to the directory where parsecontrol is installed.
            Then execute the following four lines, in order, as the user
            who owns the news system:

                /bin/sh
                PROG=newgroup
                set -- group-admin@isc.org "" /tmp/sample.control
                (. ./parsecontrol "$@"; echo $ACTION)

            If the message verified correctly, the echo command should
            output doit; otherwise, verification failed and the output
            should be mail.

            Edit /tmp/sample.control and change all occurences of
            "newusers" to "newgroups". Then repeat the parsecontrol
            and echo lines.  This time verification should fail.

          + If you are running C News:

            Because of the way C News is implemented, I have not taken
            the trouble to find out how it can be tested without
            running through the whole newgroup script.  If you are
            testing with sample.control, I think this should let you
            know whether things will work:

                newsflag news.announce.newusers y
                newgroup news.announce.newusers moderated </tmp/sample.control

            (newsflag is the C News program maint subdirectory; newgroup is
            in the ctl subdirectory.)

            You should get a mail message telling you that
            news.announce.newusers was changed to moderated.  If it
            didn't appear to work, doublecheck the active file.  If it
            really didn't work, fix the status of the group with the
            following command then let me know about it.

                newsflag news.announce.newusers m

            If the message did verify correctly, edit /tmp/sample.control
            and change all occurences of "newusers" to "newgroups".
            Then repeat the newgroup line with an "unmoderated" argument
            instead of "moderated"; the argument is unused in the PGP
            verification code and doing it this way saves you the effort of
            newsflagging things again.

            With the changes to sample.control you should now get a
            mail message saying, "authentication failed".

            When you are all done, make sure news.announce.newusers is
            really marked moderated in your active file.

          + If you are running D News:

            It appears to me that currently you'll have to wait for a
            control message to come in and see whether it does what
            you want.  If it doesn't, and you can't readily tell why,
            contact D News's customer support staff.

          + If you are running ANU News (V6.2.0 or later):

            Instructions will (hopefully) soon appear here.  In the
            meantime, consult the "HELP ADD FILE PGP_verification"
            server command.

          + If you are running some other system:

            You're out of luck until someone writes a patch and
            instructions for your system and makes it available to me for
            redistribution.

Format of Signed Control Messages

   The format of the input to PGP for signing and verifying
   messages is described in a separate document,
   ftp://ftp.isc.org/pub/pgpcontrol/FORMAT.  It is intended for
   people who want to implement their own signing and/or verifying
   programs instead of using pgpverify or signcontrol.

Frequently Asked Questions

  HOW COME THIS PRESUMABLY VALID MESSAGES DOESN'T CHECK OUT WITH PGPVERIFY?
               o You don't have the latest version of pgpverify, which
                 fixed whatever bug is causing authentication of the
                 message to fail.
               o You don't have your PGP configuration files and keyrings
                 in the default path used by pgp and PGPPATH is not correctly
                 set in your environment.  Either move your PGP directory
                 to the default location or set the $ENV{'PGPPATH'} line in
                 pgpverify.  (Warning: some INN versions set $HOME to 
		 _PATH_NEWSLIB, so this might be the source of your trouble.)
               o You don't have the correct key for the user that signed
                 it in your key ring.
               o You are using a non-English version of pgp, set up with
                 a "Language = " line in your PGP config.txt file.  This
                 means pgpverify can't find the string it is looking for in
                 the pgp output.  pgpverify tries to overcome a non-English
                 language specification by setting LANGUAGE in the 
                 environment before calling pgp, but pgp overrides the
                 runtime environment with the config.txt variables.
               o You cut-and-pasted the message in your window system,
                 which converted the tab characters in the original
                 message into spaces in the message you are trying to
                 decode. Having this handled completely correctly by the
                 signing/verifying code is harder than you might first
                 think.
               o You are running pgpverify on a saved copy of the article
                 that includes an extraneous trailing newline, such
                 as might be inserted by saving the message from a mail
                 handler or news reader, that was not present in the
                 original message. 
               o You cut-and-pasted the sample INN control.ctl lines above
                 and left the continuation lines in, instead of joining
                 each group of three physical lines comprising one logical
                 line to just one physical line.

         _____________________________________________________________

Signing Control Messages

       If you are responsible for sending control messages about
       authorized changes to a newsgroup hierarchy, then
       ftp://ftp.isc.org/pub/pgpcontrol/signcontrol
       will sign your control messages so that pgpverify can
       authenticate them. It is a Perl script that requires Perl
       version 5 or higher to work. It has several configuration
       parameters that should be reviewed before use.

       When establishing a PGP key and control message sender, please use
       tokens that are not tied to a particular individual. This makes it
       easier to transfer the administrative responsibility when it
       finally comes time. (The all-too-common "tale@uunet.uu.net" sender
       is still used for control messages because of its legacy in the
       installed server base; I would prefer to use
       newgroups-request@uunet.uu.net.) Please also do not sign other
       keys with the key that is used for control messages.

       Note that the key you use should not include whitespace or angle
       brackets, because some of the various pieces of software that deal
       with the user id mishandle it.  For the best results netwide, I
       strongly recommend that you use only alphanumeric characters, the at
       sign, dot, dash, plus and underscore.

       If you will be signing control messages, please let me know the
       hierarchy that you are responsible for maintaining and the
       information that you would like to appear in the List of PGP
       Public Keys for Newsgroup Administration.

         _____________________________________________________________

How to Get PGP

       Information about obtaining PGP can be found in the Where to get the
       latest PGP FAQ article, posted regularly in the alt.security.pgp
       newsgroup.

How to Get Perl

       Information about obtaining Perl can be found in the comp.lang.perl.*
       FAQ 1/5 - Availability article, posted regularly in the
       comp.lang.perl.misc newsgroup.
         _____________________________________________________________

Last modified: 13 Apr 2001
David C Lawrence
tale@isc.org