1INN-SECRETS.CONF(5) InterNetNews Documentation INN-SECRETS.CONF(5)
2
6 inn-secrets.conf - Configuration data for InterNetNews secrets
7
9 inn-secrets.conf in pathetc is a configuration file containing general
10 secrets used by INN. It was added in INN 2.7.0 for the implementation
11 of Cancel-Lock. The intent is that new secrets used by INN are added
12 to that file, and that all secrets currently stored in several other
13 configuration files eventually move to that file.
14 The inn-secrets.conf file is not required. It currently only serves
16 the purpose of Cancel-Lock. If not present or empty, the Cancel-Lock
17 authentication system will just be deactivated for local posts.
18 This file is intended to be fairly static. Any changes made to it will
20 generally not affect any running programs until they restart.
21 Changes in Cancel-Lock secrets will be taken into account when new
23 nnrpd processes are spawned (which happens each time a reader opens a
24 new connection).
25 Blank lines and lines starting with a number sign ("#") are ignored.
27 All other lines specify parameters, and are organized in groups. The
28 general form is:
29 <group> {
31 <parameter>: <value>
32 }
33 (Any amount of whitespace can be put after the colon and is optional.)
35 If the value contains embedded whitespace or any of the characters
36 "[]<>{}"\:;", it must be enclosed in double quotes (""). A backslash
37 ("\") can be used to escape quotes and backslashes inside double
38 quotes. <group> and <parameter> are case-sensitive; "cancels" is not
39 the same as "Cancels" or "CANCELS". (inn-secrets.conf groups and
40 parameters are generally all in lowercase.)
41 The two parameters currently defined in this file have as their value a
43 list of strings, that is to say space-separated elements enclosed in
44 square brackets. Examples follow in the documentation.
45
47 Cancel-Lock secrets
48 These secrets are used for the Cancel-Lock authentication system
49 described in RFC 8315. This mechanism permits verifying that the
50 withdrawal of an article is valid, that is to say the poster, posting
51 agent, moderator, or injecting agent that processed the original
52 article has requested to withdraw it via the use of a cancel control
53 article or a Supersedes header field.
54 You'll need to build INN with version 3.3.0 or later of libcanlock to
56 embed Cancel-Lock support. This library is available at
57 <https://micha.freeshell.org/libcanlock/>. The "configure" script will
58 automatically enable Cancel-Lock support if it finds libcanlock; you
59 may have to specify the --with-canlock option to help "configure" find
60 it.
61 The "cancels" group is defined as follows (you should naturally use
63 other passwords than the following ones):
64 cancels {
66 canlockadmin: [ "9kc3ZtAACpNZRGtmYiPlbfkDacqNwPbcEfzFodc5X48g" ]
67 canlockuser: [ "TSrg41qEbp6AyZuQoIIHo6sUzFkBLOocJYN3KsUVdgft" ]
68 }
69 If one of the canlockadmin or canlockuser parameters is not an empty
71 list, nnrpd will add information to every posted article that will
72 permit other news servers to later ensure that an attempt to cancel or
73 supersede the article is not forged, and really originates from the
74 authenticated original sender or the administrator of the local server.
75 If your users are not individually authenticated or identifiable with a
77 unique static IP, you must not set canlockuser as otherwise anyone
78 would be able to cancel the articles of any other person with the same
79 assigned identity. If all or only some of your users are individually
80 authenticated or identifiable, you can set canlockuser and make sure to
81 parameterize addcanlockuser to "none" in all the access groups in
82 readers.conf that are shared between several different persons with the
83 same identity.
84 More concretely, for each secret in canlockadmin, nnrpd adds two
86 Base64-encoded hashes to a Cancel-Lock header field. These hashes are
87 based on the secret and the Message-ID of the article. If this field
88 already exists, it will just append the Base64-encoded hashes to its
89 end. One hash uses the SHA-1 algorithm (for interoperability reasons
90 as not all news software implement SHA-256), and the other hash uses
91 the mandatory SHA-256 algorithm per RFC 8315. Besides, nnrpd will
92 similarly add two Base64-encoded hashes for each secret in canlockuser;
93 these hashes are based on the secret, the identity assigned in
94 readers.conf to the connection or its static IP (depending on the
95 setting of addcanlockuser), and the Message-ID of the article.
96 When a cancel or supersede article is posted by an authenticated user,
98 nnrpd will add to a Cancel-Key header field two pre-images for each
99 secret in canlockuser. (This is why it is important, if you have set
100 canlockuser, to parameterize addcanlockuser to "none" in all the access
101 groups in readers.conf not corresponding to individual persons.) Other
102 news servers can then hash one of these pre-images with SHA-1 or
103 SHA-256 algorithms (one is enough) and verify that the resulted
104 Base64-encoded hash is the same as the one present in the Cancel-Lock
105 header field of the original article. (Necessarily, the same
106 authenticated user on the same local server sent the original article.)
107 When receiving articles with a Cancel-Key header field (locally or from
108 other peers), innd applies that check to verify the authenticity of the
109 withdrawal before deciding to honour it.
110 Naturally, no pre-images for each secret in canlockadmin are added by
112 nnrpd. As these pre-images are not based on a user name, only the news
113 administrator can generate them (with the gencancel tool shipped with
114 INN) and then inject the cancel or supersede request with for instance
115 inews. The news administrator is therefore capable to send
116 authenticated withdrawal requests for articles posted by all the users
117 of his news server, be they authenticated or not.
118 After this (little) introduction to explain what Cancel-Lock is for,
120 here are the two relevant parameters:
121 canlockadmin
123 This parameter expects a list of strings. It is unset by default
124 (no admin hashes will be generated).
125 If this parameter is not an empty list, each provided secret will
127 be used to generate admin hashes.
128 To maximize security, secrets should have a length of at least the
130 output size of the hash function used (32 octets for SHA-256). You
131 can for instance generate a strong secret based on 33 random octets
132 (so that the last character is not systematically "=", as it
133 happens when Base64-encoding 32 random octets) with:
134 % openssl rand -base64 33
136 nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8
137 and use it as follows:
139 canlockadmin: [ "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ]
141 The purpose of providing several secrets is when you want to rotate
143 secrets. For instance, if your policy is to change secrets each
144 year, you can use two secrets during a transition period:
145 canlockadmin: [ "rH5L8geEzkNVvpAZQMJJcd4AYkpSkkx5S/4qewPDA/U="
147 "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ]
148 Withdrawals of previously posted articles will still work with the
150 old secret (still added to the Cancel-Key header field).
151 As all posted articles will have a Cancel-Lock header field with
153 the admin secret, you should also set canlockuser (and individually
154 authenticate the posters) because otherwise posters may not be able
155 to withdraw their own articles (unless their posting agents
156 generate Cancel-Lock header fields themselves with their own
157 secrets).
158 canlockuser
160 This parameter expects a list of strings. It is unset by default
161 (no user-specific hashes will be generated).
162 The same recommendation of more than 32 random octets applies, and
164 the secrets must not be the same as canlockadmin.
165 If this parameter is not an empty list, each provided secret will
167 be used to generate hashes based on the identity assigned to users
168 by readers.conf or their static IP (depending on the setting of
169 addcanlockuser). Beware that if your users are not individually
170 authenticated, you must not set canlockuser as otherwise anyone
171 would be able to cancel the articles of any other person with the
172 same assigned identity. If needed, you can deactivate the
173 generation of user-specific hashes in access groups shared between
174 several different persons with the same identity in readers.conf by
175 setting addcanlockuser to "none" in these access groups (it may for
176 instance be the case for localhost connections, if some articles
177 are injected with inews from an external source).
178 When using canlockuser, you should also set canlockadmin because
180 you may otherwise not always be able to generate the needed hash to
181 cancel an article posted by the users of your news server (notably
182 if you do not manage to find out the identity a user had when
183 posting the original article).
184
186 Documentation written by Julien Elie for InterNetNews.
187
189 gencancel(1), nnrpd(8), readers.conf(5).
190INN 2.7.1 2023-03-07 INN-SECRETS.CONF(5)