Feat: docs: usage: improved certificates documentation (#39)

    onionmine select-candidate example.org 0

## HTTPS certificates

## Certificates

Onionmine can generate self-signed X.509 certificates for TLS/HTTP, ready to be

used in web services and other applications, as well as a Certificate Request

to be sent to a Certificate Authority in order to get a CA-validated

certificate. All that in a single command:

Onionmine can generate self-signed [X.509 certificates][] for protocols such as

[TLS][] (like [HTTPS][]), ready to be used in web services and other

applications, as well as a [Certificate Signing Request][CSR] (CSR) to be sent

to a [Certificate Authority][CA] in order to get a [CA][]-validated

certificate.

[HTTPS]: https://en.wikipedia.org/wiki/HTTPS

[TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security

[X.509 certificates]: https://en.wikipedia.org/wiki/X.509

### Generating keys, CSRs and self-signed certificates

Keys, [CSR][] and self-signed certificate generation happens in a single

command:

    onionmine generate-selected-cert <pool>

Onionmine can also generate a second Certificate Request with a proof of

ownership for the .onion address, which is [needed by the CA-based

The resulting private key and self-signed certificate can then be copy and

configured into an application.

A [CA][]-issued certificate can also be obtained by submitting the resulting

[CSR][] to the [CA][].

!!! info Wildcard SAN in the CSR by default

    The command above adds a [wildcard][] as a [Subject Alternative

    Name][subjectAltName] (SAN) by default in the resulting [CSR][], which

    should be harmless if a certificate being purchased/requested won't have

    a [wildcard][], as it's the [CA][]'s job to parse and remove

    [SANs][subjectAltName] that does not belong to an order).

    The rationale behind that is discussed at [tpo/onion-services/onionmine#39][].

    If you find problems with a [CA][] not accepting your [CSR][] because of

    that -- like if you're purchasing a regular, non-wildcard certificate, but

    your [CSR][] has a [wildcard][] in the `subjectAltName`, please open an

    [issue report][].

[wildcard]: https://en.wikipedia.org/wiki/Public_key_certificate#Wildcard_certificate

[subjectAltName]: https://en.wikipedia.org/wiki/Public_key_certificate#Subject_Alternative_Name_certificate

[CSR]: https://en.wikipedia.org/wiki/Certificate_signing_request

[CA]: https://en.wikipedia.org/wiki/Certificate_authority

[tpo/onion-services/onionmine#39]: https://gitlab.torproject.org/tpo/onion-services/onionmine/-/issues/39

[issue report]: contact.md

### Providing Proof of Possession

Onionmine can also generate a second [CSR][] with a Proof of

Possession (PoP) for the .onion address, which is [needed by the CA-based

certification process][existing-ca-validation]:

It can be invoked by running

This command above uses the [onion-csr][] application under the hood.

Once a CA-issued certificate is available, save it under

Once a [CA][]-issued certificate is available, save it under

`pools/<pool>/certs/selected/ca-signed.crt`, so it can be exported to external

applications directly from Onionmine.