.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "INN-SECRETS.CONF 5" .TH INN-SECRETS.CONF 5 "2023-03-07" "INN 2.7.2" "InterNetNews Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" inn\-secrets.conf \- Configuration data for InterNetNews secrets .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIinn\-secrets.conf\fR in \fIpathetc\fR is a configuration file containing general secrets used by \s-1INN.\s0 It was added in \s-1INN\s0\ 2.7.0 for the implementation of Cancel-Lock. The intent is that new secrets used by \s-1INN\s0 are added to that file, and that all secrets currently stored in several other configuration files eventually move to that file. .PP The \fIinn\-secrets.conf\fR 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. .PP This file is intended to be fairly static. Any changes made to it will generally not affect any running programs until they restart. .PP Changes in Cancel-Lock secrets will be taken into account when new \fBnnrpd\fR processes are spawned (which happens each time a reader opens a new connection). .PP Blank lines and lines starting with a number sign (\f(CW\*(C`#\*(C'\fR) are ignored. All other lines specify parameters, and are organized in groups. The general form is: .PP .Vb 3 \& { \& : \& } .Ve .PP (Any amount of whitespace can be put after the colon and is optional.) If the value contains embedded whitespace or any of the characters \f(CW\*(C`[]<>{}"\e:;\*(C'\fR, it must be enclosed in double quotes (""). A backslash (\f(CW\*(C`\e\*(C'\fR) can be used to escape quotes and backslashes inside double quotes. and are case-sensitive; \f(CW\*(C`cancels\*(C'\fR is not the same as \f(CW\*(C`Cancels\*(C'\fR or \f(CW\*(C`CANCELS\*(C'\fR. (\fIinn\-secrets.conf\fR groups and parameters are generally all in lowercase.) .PP 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. .SH "PARAMETERS" .IX Header "PARAMETERS" .SS "Cancel-Lock secrets" .IX Subsection "Cancel-Lock secrets" These secrets are used for the Cancel-Lock authentication system described in \s-1RFC\s0\ 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. .PP You'll need to build \s-1INN\s0 with version 3.3.0 or later of libcanlock to embed Cancel-Lock support. This library is available at . The \f(CW\*(C`configure\*(C'\fR script will automatically enable Cancel-Lock support if it finds libcanlock; you may have to specify the \fB\-\-with\-canlock\fR option to help \f(CW\*(C`configure\*(C'\fR find it. .PP The \f(CW\*(C`cancels\*(C'\fR group is defined as follows (you should naturally use other passwords than the following ones): .PP .Vb 4 \& cancels { \& canlockadmin: [ "9kc3ZtAACpNZRGtmYiPlbfkDacqNwPbcEfzFodc5X48g" ] \& canlockuser: [ "TSrg41qEbp6AyZuQoIIHo6sUzFkBLOocJYN3KsUVdgft" ] \& } .Ve .PP If one of the \fIcanlockadmin\fR or \fIcanlockuser\fR parameters is not an empty list, \fBnnrpd\fR 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. .PP If your users are not individually authenticated or identifiable with a unique static \s-1IP,\s0 you must not set \fIcanlockuser\fR 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 \fIcanlockuser\fR and make sure to parameterize \&\fIaddcanlockuser\fR to \f(CW\*(C`none\*(C'\fR in all the access groups in \fIreaders.conf\fR that are shared between several different persons with the same identity. .PP More concretely, for each secret in \fIcanlockadmin\fR, \fBnnrpd\fR 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 \s-1SHA\-1\s0 algorithm (for interoperability reasons as not all news software implement \s-1SHA\-256\s0), and the other hash uses the mandatory \&\s-1SHA\-256\s0 algorithm per \s-1RFC\s0\ 8315. Besides, \fBnnrpd\fR will similarly add two Base64\-encoded hashes for each secret in \fIcanlockuser\fR; these hashes are based on the secret, the identity assigned in \fIreaders.conf\fR to the connection or its static \s-1IP\s0 (depending on the setting of \fIaddcanlockuser\fR), and the Message-ID of the article. .PP When a cancel or supersede article is posted by an authenticated user, \&\fBnnrpd\fR will add to a Cancel-Key header field two pre-images for each secret in \fIcanlockuser\fR. (This is why it is important, if you have set \fIcanlockuser\fR, to parameterize \fIaddcanlockuser\fR to \f(CW\*(C`none\*(C'\fR in all the access groups in \fIreaders.conf\fR not corresponding to individual persons.) Other news servers can then hash one of these pre-images with \s-1SHA\-1\s0 or \s-1SHA\-256\s0 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), \fBinnd\fR applies that check to verify the authenticity of the withdrawal before deciding to honour it. .PP Naturally, no pre-images for each secret in \fIcanlockadmin\fR are added by \&\fBnnrpd\fR. As these pre-images are not based on a user name, only the news administrator can generate them (with the \fBgencancel\fR tool shipped with \s-1INN\s0) and then inject the cancel or supersede request with for instance \fBinews\fR. 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. .PP After this (little) introduction to explain what Cancel-Lock is for, here are the two relevant parameters: .IP "\fIcanlockadmin\fR" 4 .IX Item "canlockadmin" This parameter expects a list of strings. It is unset by default (no admin hashes will be generated). .Sp If this parameter is not an empty list, each provided secret will be used to generate admin hashes. .Sp To maximize security, secrets should have a length of at least the output size of the hash function used (32 octets for \s-1SHA\-256\s0). You can for instance generate a strong secret based on 33 random octets (so that the last character is not systematically \f(CW\*(C`=\*(C'\fR, as it happens when Base64\-encoding 32 random octets) with: .Sp .Vb 2 \& % openssl rand \-base64 33 \& nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8 .Ve .Sp and use it as follows: .Sp .Vb 1 \& canlockadmin: [ "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ] .Ve .Sp 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: .Sp .Vb 2 \& canlockadmin: [ "rH5L8geEzkNVvpAZQMJJcd4AYkpSkkx5S/4qewPDA/U=" \& "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ] .Ve .Sp Withdrawals of previously posted articles will still work with the old secret (still added to the Cancel-Key header field). .Sp As all posted articles will have a Cancel-Lock header field with the admin secret, you should also set \fIcanlockuser\fR (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). .IP "\fIcanlockuser\fR" 4 .IX Item "canlockuser" This parameter expects a list of strings. It is unset by default (no user-specific hashes will be generated). .Sp The same recommendation of more than 32 random octets applies, and the secrets must not be the same as \fIcanlockadmin\fR. .Sp 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 \fIreaders.conf\fR or their static \s-1IP\s0 (depending on the setting of \fIaddcanlockuser\fR). Beware that if your users are not individually authenticated, you must not set \fIcanlockuser\fR 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 \fIreaders.conf\fR by setting \fIaddcanlockuser\fR to \f(CW\*(C`none\*(C'\fR in these access groups (it may for instance be the case for localhost connections, if some articles are injected with \fBinews\fR from an external source). .Sp When using \fIcanlockuser\fR, you should also set \fIcanlockadmin\fR 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). .SH "HISTORY" .IX Header "HISTORY" Documentation written by Julien Elie for InterNetNews. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgencancel\fR\|(1), \fBnnrpd\fR\|(8), \fBreaders.conf\fR\|(5).