Cancel-Lock secrets

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:

    cancels {
        canlockadmin: [ "Cl4yniTtmlsR3nwVaM2erBQClVprEtLjd/UiqTErXjk=" ]
        canlockuser:  [ "tf+fY0Z7KNzYzF9uPo/qPrLKOPXIJLqejwqsV1nwOTRwGQ==" ]
    }

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, 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, you can set canlockuser and make sure to parameter addcanlockuser to false 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, 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 parameter addcanlockuser to false 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 36 random octets with:

    % openssl rand -base64 36
    Vs4zdggAHKEUtqs6dH5/oNGWwIVFPf2ZIngog6aE6cDMoyJF
    

and use it as follows:

    canlockadmin: [ "Vs4zdggAHKEUtqs6dH5/oNGWwIVFPf2ZIngog6aE6cDMoyJF" ]
    

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="
                    "eAaeyrQfjqQryhqrfwJOKezwf9GpL+xs+A9YfK9MMxE=" ]
    

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. 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 false 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 he had when posting the original article).