inn-secrets.conf - Configuration data for InterNetNews secrets
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.
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).
Documentation written by Julien Elie for InterNetNews.
gencancel(1),
nnrpd(8),
readers.conf(5).