Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: gRPC SSL certificate documentation improvements #7731

Conversation

s373nZ
Copy link
Contributor

@s373nZ s373nZ commented Oct 8, 2024

Checklist

Before submitting the PR, ensure the following tasks are completed. If an item is not applicable to your PR, please mark it as checked:

  • The changelog has been updated in the relevant commit(s) according to the guidelines.
  • Tests have been added or modified to reflect the changes.
  • Documentation has been reviewed and updated as needed.
  • Related issues have been listed and linked, including any that this PR closes.

Adds some additional documentation around generating custom gRPC SSL certificates.

  1. Fixes anchor links to point to the gprc page instead of redirecting to app-development.
  2. Adds a clarifying example depicting that "lightning" directory should actually be the network subdirectory, as certs are stored there.
  3. Adds an additional section of documentation for generating SSL certificates using Subject Alternative Names.

Context

After struggling with properly generating custom certificates for a long time while trying to run the API under both Tor and SSL, as well as allow another local service to communicate with the gRPC APIs, I'm submitting the process that worked for me as candidate for documentation improvements. From memory, the problematic issues were:

  1. Generating new certificates using the existing documentation didn't preserve the SAN from the original default certificate, including localhost, 127.0.0.1 and cln etc.
  2. Generating a new certificate using the existing documentation suggests to use CN for the "production" domain, but browsers and other common SSL client libraries complain that verification via SAN is required and throw an error (as of circa 2017?).

Caveat

Not exactly an SSL expert here, so a review on best practices would be appreciated. I used the following resources to assemble this solution:

Also, this page suggests it could be possible to do this with a one-liner due to this openssl commit. Just saying, there may be a better way to do this.

@s373nZ s373nZ force-pushed the grpc-ssl-certificate-doc-improvements branch from 3d6322e to 6e0ace9 Compare October 8, 2024 09:36
@s373nZ s373nZ force-pushed the grpc-ssl-certificate-doc-improvements branch from 6e0ace9 to 6525778 Compare October 13, 2024 08:23
@s373nZ
Copy link
Contributor Author

s373nZ commented Oct 13, 2024

Changed the CN of the example certificate configuration to cln grpc server.

@ShahanaFarooqui ShahanaFarooqui added this to the v24.11 milestone Oct 13, 2024
@ShahanaFarooqui ShahanaFarooqui force-pushed the grpc-ssl-certificate-doc-improvements branch from 6525778 to 85e5b95 Compare October 13, 2024 23:12
Changelog-Added: Example documentation on generating custom gRPC
certificates with SANs.
@ShahanaFarooqui ShahanaFarooqui force-pushed the grpc-ssl-certificate-doc-improvements branch from 85e5b95 to dad0676 Compare October 13, 2024 23:13
@ShahanaFarooqui
Copy link
Collaborator

Combined the last two commits into one as the second commit only added links to the content of the first.

ACK 85e5b95.

@ShahanaFarooqui ShahanaFarooqui merged commit 4f5ea34 into ElementsProject:master Oct 21, 2024
38 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants