Purpose of client key / cert unclear in setup guide. PKI docs confusing in general.

[benjumanji]

I'd very much like to setup a taskserver instance, and consider myself to reasonably adept with pki (have managed certificates / for smbs). I have to confess being completely confused by the server guide. I think it would be really useful to have a concise statement on how pki is used and what role each option in the config plays in that.

I think taskserver has a really standard setup of mutual tls, and server authentication of client certificates consists of checking if the client certificate is signed by our ca. A cursory reading of the TLSTransaction code seems to confirm this. Using self-signed client certificates is both sensible and secure. The docs don't make this clear at all and spend far more time lecturing on not switching off verification rather giving them the information they need to generate a proper pki setup. There is also no explanation of what the purpose of the client.{cert,key} options are. I had a quick scan of some of the server code and they don't seem to be read on startup, they aren't mentioned in the man pages. Mystery.

I am going to have a go at setting this up in the next few days and if I can get to a decent place, I'll be happy to try and write some words.

[pbeckingham]

Thank you, the web sites and product documentation are all open source. Paul

…

On Sep 2, 2018, at 6:50 PM, Benjamin Edwards ***@***.***> wrote: I'd very much like to setup a taskserver instance, and consider myself to reasonably adept with pki (have managed certificates / for smbs). I have to confess being completely confused by the server guide. I think it would be really useful to have a concise statement on how pki is used and what role each option in the config plays in that. I think taskserver has a really standard setup of mutual tls, and server authentication of client certificates consists of checking if the client certificate is signed by our ca. A cursory reading of the TLSTransaction code seems to confirm this. Using self-signed client certificates is both sensible and secure. The docs don't make this clear at all and spend far more time lecturing on not switching off verification rather giving them the information they need to generate a proper pki setup. There is also no explanation of what the purpose of the client.{cert,key} options are. I had a quick scan of some of the server code and they don't seem to be read on startup, they aren't mentioned in the man pages. Mystery. I am going to have a go at setting this up in the next few days and if I can get to a decent place, I'll be happy to try and write some words. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#3>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAfG8JFUt8neo458YWZLGTjKE8eQE81ks5uXGDTgaJpZM4WWy46>.

[riking]

Such as the part where server.cert/server.key should be issued from a publicly trusted CA, but server.crl is the revocation list for the client certificate-issuing, self-managed CA.

[benjumanji]

Yeah. The client option (on the server) seemed to have been renamed to api, and is only used by some debug tool. I haven't gotten around to doing an install yet. If there is anything else you spot, post it here, and maybe we can get a nice docs PR going.

[stappersg]

Using self-signed client certificates is both sensible and secure. The docs don't make this clear at all and spend far more time lecturing on not switching off verification rather giving them the information they need to generate a proper pki setup.

At https://github.com/GothenburgBitFactory/taskserver-setup/blob/master/index.html#L561 is meanwhile

The command below will generate all the certs and keys for the server, but this uses self-signed certificates, and this is not recommended for production use. This is for personal use, and this may be acceptable for you, but if not, you will need to purchase a proper certificate and key, backed by a certificate authority.

@benjumanji please close this issue.

[riking]

This issue is saying the documentation is strange and unclear, and I don't see any improvements made to the documentation? Why would it be closed?

[aeneby]

I think the main issue with the documentation is the format. The decision to use slides was an "interesting" one. I'd be happy to suggest improvements, but not if it has to be done as a powerpoint presentation :)

Formatting aside, as others have pointed out there are some parts which are quite confusing/misleading. The mechanism being implemented here is essentially mTLS, and although self-signed certificates on the server side should be avoided, they're really unavoidable on the client side. I think this could be made clearer. If nothing else, anyone looking to support a large number of users needs to understand they will have to become their own CA.

I think the most confusing part, however, is the client configuration section. The instructions imply that you need the self-generated CA cert on the client to verify the client keys, but this isn't true. The CA cert on the client is used to verify the server-side certificate. If you used Let's Encrypt to generate your server-side keys, then you need the Let's Encrypt CA cert on the client, even though the client keys are self-signed. The opposite is true on the server; ca.cert should point to the self-generated CA cert, not the Let's Encrypt one.

There is also some misleading documentation in the README file in the pki directory of taskserver, where the scripts live to genereate the self-signed keys. For example, it states:

Ideally you would purchase a server cert signed by a known CA, such as one of
the following:

Symantec
Comodo
GoDaddy
GlobalSign

That cert would need the 'encryption_key' and 'signing_key' attributes.
Using that server cert, you would then issue a server CRL and client keys.

I don't get how it is possible to generate your own client keys from a server key signed by a known CA. There seems to be some misunderstanding here, either by the author of this file or by myself. I realise that this file does not relate to this repository, just pointing out another source of confusion when trying to configure taskserver.

[lauft]

@aeneby The documentation could be moved to https://gothenburgbitfactory.org/taskd/ (i.e. to https://github.com/GothenburgBitFactory/gbf.org/tree/master/content/taskd) which then would be in Markdown.

[aeneby]

@lauft I think this would make sense.