NAME

       inn-secrets.conf - Configuration data for InterNetNews secrets

DESCRIPTION

       inn-secrets.conf in pathetc is a configuration file containing general secrets used by
       INN.  It was added in INN 2.7.0 for the implementation of Cancel-Lock.  The intent is that
       new secrets used by INN are added to that file, and that all secrets currently stored in
       several other configuration files eventually move to that file.

       The inn-secrets.conf file is not required.  It currently only serves the purpose of
       Cancel-Lock.  If not present or empty, the Cancel-Lock authentication system will just be
       deactivated for local posts.

       This file is intended to be fairly static.  Any changes made to it will generally not
       affect any running programs until they restart.

       Changes in Cancel-Lock secrets will be taken into account when new nnrpd processes are
       spawned (which happens each time a reader opens a new connection).

       Blank lines and lines starting with a number sign ("#") are ignored.  All other lines
       specify parameters, and are organized in groups.  The general form is:

           <group> {
               <parameter>: <value>
           }

       (Any amount of whitespace can be put after the colon and is optional.)  If the value
       contains embedded whitespace or any of the characters "[]<>{}"\:;", it must be enclosed in
       double quotes ("").  A backslash ("\") can be used to escape quotes and backslashes inside
       double quotes.  <group> and <parameter> are case-sensitive; "cancels" is not the same as
       "Cancels" or "CANCELS".  (inn-secrets.conf groups and parameters are generally all in
       lowercase.)

       The two parameters currently defined in this file have as their value a list of strings,
       that is to say space-separated elements enclosed in square brackets.  Examples follow in
       the documentation.

PARAMETERS

   Cancel-Lock secrets
       These secrets are used for the Cancel-Lock authentication system described in RFC 8315.
       This mechanism permits verifying that the withdrawal of an article is valid, that is to
       say the poster, posting agent, moderator, or injecting agent that processed the original
       article has requested to withdraw it via the use of a cancel control article or a
       Supersedes header field.

       You'll need to build INN with version 3.3.0 or later of libcanlock to embed Cancel-Lock
       support.  This library is available at <https://micha.freeshell.org/libcanlock/>.  The
       "configure" script will automatically enable Cancel-Lock support if it finds libcanlock;
       you may have to specify the --with-canlock option to help "configure" find it.

       The "cancels" group is defined as follows (you should naturally use other passwords than
       the following ones):

           cancels {
               canlockadmin: [ "9kc3ZtAACpNZRGtmYiPlbfkDacqNwPbcEfzFodc5X48g" ]
               canlockuser:  [ "TSrg41qEbp6AyZuQoIIHo6sUzFkBLOocJYN3KsUVdgft" ]
           }

       If one of the canlockadmin or canlockuser parameters is not an empty list, nnrpd will add
       information to every posted article that will permit other news servers to later ensure
       that an attempt to cancel or supersede the article is not forged, and really originates
       from the authenticated original sender or the administrator of the local server.

       If your users are not individually authenticated or identifiable with a unique static IP,
       you must not set canlockuser as otherwise anyone would be able to cancel the articles of
       any other person with the same assigned identity.  If all or only some of your users are
       individually authenticated or identifiable, you can set canlockuser and make sure to
       parameterize addcanlockuser to "none" in all the access groups in readers.conf that are
       shared between several different persons with the same identity.

       More concretely, for each secret in canlockadmin, nnrpd adds two Base64-encoded hashes to
       a Cancel-Lock header field.  These hashes are based on the secret and the Message-ID of
       the article.  If this field already exists, it will just append the Base64-encoded hashes
       to its end.  One hash uses the SHA-1 algorithm (for interoperability reasons as not all
       news software implement SHA-256), and the other hash uses the mandatory SHA-256 algorithm
       per RFC 8315.  Besides, nnrpd will similarly add two Base64-encoded hashes for each secret
       in canlockuser; these hashes are based on the secret, the identity assigned in
       readers.conf to the connection or its static IP (depending on the setting of
       addcanlockuser), and the Message-ID of the article.

       When a cancel or supersede article is posted by an authenticated user, nnrpd will add to a
       Cancel-Key header field two pre-images for each secret in canlockuser.  (This is why it is
       important, if you have set canlockuser, to parameterize addcanlockuser to "none" in all
       the access groups in readers.conf not corresponding to individual persons.)  Other news
       servers can then hash one of these pre-images with SHA-1 or SHA-256 algorithms (one is
       enough) and verify that the resulted Base64-encoded hash is the same as the one present in
       the Cancel-Lock header field of the original article.  (Necessarily, the same
       authenticated user on the same local server sent the original article.)  When receiving
       articles with a Cancel-Key header field (locally or from other peers), innd applies that
       check to verify the authenticity of the withdrawal before deciding to honour it.

       Naturally, no pre-images for each secret in canlockadmin are added by nnrpd.  As these
       pre-images are not based on a user name, only the news administrator can generate them
       (with the gencancel tool shipped with INN) and then inject the cancel or supersede request
       with for instance inews.  The news administrator is therefore capable to send
       authenticated withdrawal requests for articles posted by all the users of his news server,
       be they authenticated or not.

       After this (little) introduction to explain what Cancel-Lock is for, here are the two
       relevant parameters:

       canlockadmin
           This parameter expects a list of strings.  It is unset by default (no admin hashes
           will be generated).

           If this parameter is not an empty list, each provided secret will be used to generate
           admin hashes.

           To maximize security, secrets should have a length of at least the output size of the
           hash function used (32 octets for SHA-256).  You can for instance generate a strong
           secret based on 33 random octets (so that the last character is not systematically
           "=", as it happens when Base64-encoding 32 random octets) with:

               % openssl rand -base64 33
               nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8

           and use it as follows:

               canlockadmin: [ "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ]

           The purpose of providing several secrets is when you want to rotate secrets.  For
           instance, if your policy is to change secrets each year, you can use two secrets
           during a transition period:

               canlockadmin: [ "rH5L8geEzkNVvpAZQMJJcd4AYkpSkkx5S/4qewPDA/U="
                               "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ]

           Withdrawals of previously posted articles will still work with the old secret (still
           added to the Cancel-Key header field).

           As all posted articles will have a Cancel-Lock header field with the admin secret, you
           should also set canlockuser (and individually authenticate the posters) because
           otherwise posters may not be able to withdraw their own articles (unless their posting
           agents generate Cancel-Lock header fields themselves with their own secrets).

       canlockuser
           This parameter expects a list of strings.  It is unset by default (no user-specific
           hashes will be generated).

           The same recommendation of more than 32 random octets applies, and the secrets must
           not be the same as canlockadmin.

           If this parameter is not an empty list, each provided secret will be used to generate
           hashes based on the identity assigned to users by readers.conf or their static IP
           (depending on the setting of addcanlockuser).  Beware that if your users are not
           individually authenticated, you must not set canlockuser as otherwise anyone would be
           able to cancel the articles of any other person with the same assigned identity.  If
           needed, you can deactivate the generation of user-specific hashes in access groups
           shared between several different persons with the same identity in readers.conf by
           setting addcanlockuser to "none" in these access groups (it may for instance be the
           case for localhost connections, if some articles are injected with inews from an
           external source).

           When using canlockuser, you should also set canlockadmin because you may otherwise not
           always be able to generate the needed hash to cancel an article posted by the users of
           your news server (notably if you do not manage to find out the identity a user had
           when posting the original article).

HISTORY

       Documentation written by Julien Elie for InterNetNews.

SEE ALSO

       gencancel(1), nnrpd(8), readers.conf(5).