NAME

App::Phoebe::RegisteredEditorsOnly - only known users may edit Phoebe wiki pages

DESCRIPTION

This extension limits editing to registered editors only. In order to register an editor, you need to know the client certificate's fingerprint, and add it to the Phoebe wiki config file. Do this by setting @known_fingerprints. Here’s an example:

    package App::Phoebe;
    our @known_fingerprints = qw(
      sha256$fce75346ccbcf0da647e887271c3d3666ef8c7b181f2a3b22e976ddc8fa38401
      sha256$54c0b95dd56aebac1432a3665107d3aec0d4e28fef905020ed6762db49e84ee1);
    use App::Phoebe::RegisteredEditorsOnly;
    our $server->{wiki_token} = []; # no tokens
    1;

If you have your editor’s client certificate (not their key!), run the following to get the fingerprint:

    openssl x509 -in client-cert.pem -noout -sha256 -fingerprint \
    | sed -e 's/://g' -e 's/SHA256 Fingerprint=/sha256$/' \
    | tr [:upper:] [:lower:]

This should give you the fingerprint in the correct format to add to the list above. Add it, and restart Phoebe.

If a visitor uses a fingerprint that Phoebe doesn’t know, the fingerprint is printed in the log (if your log level is set to “info” or more), so you can get it from there in case the user can’t send you their client certificate, or tell you what the fingerprint is.

You should also have a login link somewhere such that people can login immediately. If they don’t, and they try to save, their client is going to ask them for a certificate and their edits may or may not be lost. It depends. 😅

    => /login Login

This code works by intercepting all titan: links, and all web edit requests. If you allow editing via the web using App::Phoebe::WebEdit, then those also require a valid client certificate – and setting these up in a web browser are not easy. Be prepared to explain how to do this to your users!

This code does not prevent simple comments using App::Phoebe::Comments or App::Phoebe::WebComments. People can still leave comments, if you use these modules. This can be a problem: if only registered users can edit the site, you probably don’t want a token; if anonymous users can comment, you probably want a token. There is currently no solution for this. Choose one or the other. If you choose both, registered users might have to provide a token, which might annoy them.

Here’s an example config that allows reading and editing via the web, but only for users with known fingerprints, with no comments and no tokens:

    # tested by t/example-registered-editors-only.t
    package App::Phoebe;
    use App::Phoebe::Web;
    use App::Phoebe::WebEdit;
    use App::Phoebe::RegisteredEditorsOnly;
    our @known_fingerprints = qw(
      sha256$0ba6ba61da1385890f611439590f2f0758760708d1375859b2184dcd8f855a00);
    our $server->{wiki_token} = []; # no tokens
    1;

At the time of this writing, here’s a way to do provide a client certificate for Firefox users. First, we need a file in the PKCS12 format. On the command line, create this file from the cert.pem and key.pem files you have. Provide no password when you run the command.

    openssl pkcs12 -export -inkey key.pem -in cert.pem -out cert.p12

In Firefox, go to Preferences → Privacy & Security → Certificates, click on the View Certificates button, switch the Your Certificates tab, click on Import… and pick the cert.p12 file you just created.

Once you have done this and you visit the site, it’ll ask you what client certificate to use. Sadly, at this point Firefox will ask you for a certificate whenever you visit a Phoebe wiki, even if you don’t intend to identify yourself because Phoebe always tries to read the client’s client certificate. You can always cancel, but there’s that uncomfortable moment when you visit a new Phoebe wiki…