search

grpc / grpc.io

Repository for the gRPC website and documentation
https://grpc.io
Other
420 stars 444 forks source link

SSL/TSL documentation is lacking #722

Open githorse opened 3 years ago

githorse commented 3 years ago

For this programmer with reasonable familiarity with GRPC and web development but not with encryption, the Auth documentation is pretty elliptical:

  1. It shows only the client-side code.
  2. There's no discussion of what the certificate is or how to obtain one (e.g., via openssl), or any discussion of the merits of self-signed certificates vs., say, free ones from Cloudflare.
  3. There's no discussion of TLS vs SSL and whether that's a necessary distinction or impacts the certificates used. (I think it doesn't matter).
  4. The C++ example shown up-front at Using client-side SSL/TLS uses a "default credentials" object that mysteriously requires no certificate file. Most or all of the other (client-side) code examples use a certificate file. It's unclear how this could be language-dependent.
  5. The examples show installation of the certificate on the client side, which does not seem to be consistent with the most familiar implementation of TLS, in which the handshake downloads the certificate from the server. (I'm still confused about this one. It seems like it might be mutual authentication/the Client-authenticated TLS handshake, but then again that seems to require the client to have a private key.)

There's a simple client+server Python example here which fills in some of these gaps, but I still haven't managed to get a node client / Java server example working. Perhaps not all of the above points are in scope for discussion here, but more guidance from grpc.io (especially the server-side code excerpts) would definitely be helpful.

yashykt commented 3 years ago

Thanks for the feedback!

It shows only the client-side code. There's no discussion of what the certificate is or how to obtain one (e.g., via openssl), or any discussion of the merits of self-signed certificates vs., say, free ones from Cloudflare. There's no discussion of TLS vs SSL and whether that's a necessary distinction or impacts the certificates used. (I think it doesn't matter).

I'm not sure if this is in scope for this doc, but the doc can certainly link to guides on how to obtain certificates and such.

The C++ example shown up-front at Using client-side SSL/TLS uses a "default credentials" object that mysteriously requires no certificate file. Most or all of the other (client-side) code examples use a certificate file. It's unclear how this could be language-dependent.

Note that as the guide mentions the certificates which are configured via SslCredentialsOptions can be modified. https://github.com/grpc/grpc/blob/b55fba33821d3aa3cb4ab38414151518d85c07a6/include/grpcpp/security/credentials.h#L156 for more details

The examples show installation of the certificate on the client side, which does not seem to be consistent with the most familiar implementation of TLS, in which the handshake downloads the certificate from the server. (I'm still confused about this one. It seems like it might be mutual authentication/the Client-authenticated TLS handshake, but then again that seems to require the client to have a private key.)

It sounds like you are looking for information on TLS/mTLS, differences and how to set it all up.

@jiangtaoli2016 @ZhenLian to comment on good resources to follow for this.

ZhenLian commented 3 years ago

Yeah, overall I agree we should improve the security blogs and add more guidance to grpc.io, especially with the coming of many new security features besides authentication, such as authorization and certificate revocation. I think we probably can have one big section "gRPC security" in grpc.io, and have authentication, authorization, etc to be each of the sub-sections. The question is how much detail shall we cover. I will need to discuss with @jiangtaoli2016 about this.

That might take some time, though, so let me answer your questions first:

It shows only the client-side code.

Yeah I agree, this could be improved. You can find a server side example here.

There's no discussion of what the certificate is or how to obtain one (e.g., via openssl), or any discussion of the merits of self-signed certificates vs., say, free ones from Cloudflare.

If you are just trying to build a toy project(e.g. make a client and server up and running with TLS), you can find how to create OpenSSL certificates through here or here. In the production environment, the certs usually are obtained from a CA. I think this is too much to cover in grpc, but you can search for "certificate authority" or "public key infrastructure" to learn more.

There's no discussion of TLS vs SSL and whether that's a necessary distinction or impacts the certificates used. (I think it doesn't matter).

No, it doesn't matter. BTW, gRPC C++ uses the prefix Ssl in some of the class/struct names such as SslCredentialsOptions for historical reasons, but internally it is actually using TLS. You can think of SSL as an older version of TLS. I don't know any of the gRPC library which is still using SSL nowadays.

The examples show installation of the certificate on the client side, which does not seem to be consistent with the most familiar implementation of TLS, in which the handshake downloads the certificate from the server. (I'm still confused about this one. It seems like it might be mutual authentication/the Client-authenticated TLS handshake, but then again that seems to require the client to have a private key.)

In a typical one-way TLS scenario, the client needs to present root certificates and the server needs to present identity certificates as well as identity key. The identity key/certs are basically to show the identity of the server, and the client root certs basically tell you who the client trusts. In a mutual-TLS scenario, we need to do the reverse for the client and server as well, so we need root certs, identity certs, identity keys for both the client and the server. If you are not familiar with the concept, I highly suggest you to take a deeper look at how the TLS works.

Feel free to let me know anything else if you have any questions. Thanks!

jiangtaoli2016 commented 3 years ago

+Mark Roth @.***> The plan is to update grpc.io with concrete examples once new TLS credentials is stable.

Thanks, Jiangtao

On Sat, Mar 27, 2021 at 11:23 PM ZhenLian @.***> wrote:

Yeah, overall I agree we should improve the security blogs and add more guidance to grpc.io, especially with the coming of many new security features besides authentication, such as authorization and certificate revocation. I think we probably can have one big section "gRPC security" in grpc.io, and have authentication, authorization, etc to be each of the sub-sections. The question is how much detail shall we cover. I will need to discuss with @jiangtaoli2016 https://github.com/jiangtaoli2016 about this.

That might take some time, though, so let me answer your questions first:

It shows only the client-side code. Yeah I agree, this could be improved. You can find a server side example here https://github.com/grpc/grpc/issues/20167.

There's no discussion of what the certificate is or how to obtain one (e.g., via openssl), or any discussion of the merits of self-signed certificates vs., say, free ones from Cloudflare. If you are just trying to build a toy project(e.g. make a client and server up and running with TLS), you can find how to create OpenSSL certificates through here https://github.com/grpc/grpc/blob/master/src/core/tsi/test_creds/README or here https://github.com/grpc/grpc-go/blob/master/security/advancedtls/testdata/README.md. In the production environment, the certs usually are obtained from a CA https://en.wikipedia.org/wiki/Certificate_authority. I think this is too much to cover in grpc, but you can search for "certificate authority" or "public key infrastructure" to learn more.

There's no discussion of TLS vs SSL and whether that's a necessary distinction or impacts the certificates used. (I think it doesn't matter). No, it doesn't matter. BTW, gRPC C++ uses the prefix Ssl in some of the class/struct names such as SslCredentialsOptions for historical reasons, but internally it is actually using TLS. You can think of SSL as an older version of TLS. I don't know any of the gRPC library which is still using SSL nowadays.

The examples show installation of the certificate on the client side, which does not seem to be consistent with the most familiar implementation of TLS, in which the handshake downloads the certificate from the server. (I'm still confused about this one. It seems like it might be mutual authentication/the Client-authenticated TLS handshake, but then again that seems to require the client to have a private key.) In a typical one-way TLS scenario, the client needs to present root certificates and the server needs to present identity certificates as well as identity key. The identity key/certs are basically to show the identity of the server, and the client root certs basically tell you who the client trusts. In a mutual-TLS scenario, we need to do the reverse for the client and server as well, so we need root certs, identity certs, identity keys for both the client and the server. If you are not familiar with the concept, I highly suggest you to take a deeper look at how the TLS works.

Feel free to let me know anything else if you have any questions. Thanks!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/grpc/grpc.io/issues/722#issuecomment-808854365, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEX5XZCVK3UMWNWWA2JPXETTF3DOXANCNFSM4ZBEYMYQ .