You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

108 lines
6.1 KiB

  1. # ADR 063: Privval gRPC
  2. ## Changelog
  3. - 23/11/2020: Initial Version (@marbar3778)
  4. ## Context
  5. Validators use remote signers to help secure their keys. This system is Tendermint's recommended way to secure validators, but the path to integration with Tendermint's private validator client is plagued with custom protocols.
  6. Tendermint uses its own custom secure connection protocol (`SecretConnection`) and a raw tcp/unix socket connection protocol. The secure connection protocol until recently was exposed to man in the middle attacks and can take longer to integrate if not using Golang. The raw tcp connection protocol is less custom, but has been causing minute issues with users.
  7. Migrating Tendermint's private validator client to a widely adopted protocol, gRPC, will ease the current maintenance and integration burden experienced with the current protocol.
  8. ## Decision
  9. After discussing with multiple stake holders, [gRPC](https://grpc.io/) was decided on to replace the current private validator protocol. gRPC is a widely adopted protocol in the micro-service and cloud infrastructure world. gRPC uses [protocol-buffers](https://developers.google.com/protocol-buffers) to describe its services, providing a language agnostic implementation. Tendermint uses protobuf for on disk and over the wire encoding already making the integration with gRPC simpler.
  10. ## Alternative Approaches
  11. - JSON-RPC: We did not consider JSON-RPC because Tendermint uses protobuf extensively making gRPC a natural choice.
  12. ## Detailed Design
  13. With the recent integration of [Protobuf](https://developers.google.com/protocol-buffers) into Tendermint the needed changes to migrate from the current private validator protocol to gRPC is not large.
  14. The [service definition](https://grpc.io/docs/what-is-grpc/core-concepts/#service-definition) for gRPC will be defined as:
  15. ```proto
  16. service PrivValidatorAPI {
  17. rpc GetPubKey(tendermint.proto.privval.PubKeyRequest) returns (tendermint.proto.privval.PubKeyResponse);
  18. rpc SignVote(tendermint.proto.privval.SignVoteRequest) returns (tendermint.proto.privval.SignedVoteResponse);
  19. rpc SignProposal(tendermint.proto.privval.SignProposalRequest) returns (tendermint.proto.privval.SignedProposalResponse);
  20. message PubKeyRequest {
  21. string chain_id = 1;
  22. }
  23. // PubKeyResponse is a response message containing the public key.
  24. message PubKeyResponse {
  25. tendermint.crypto.PublicKey pub_key = 1 [(gogoproto.nullable) = false];
  26. }
  27. // SignVoteRequest is a request to sign a vote
  28. message SignVoteRequest {
  29. tendermint.types.Vote vote = 1;
  30. string chain_id = 2;
  31. }
  32. // SignedVoteResponse is a response containing a signed vote or an error
  33. message SignedVoteResponse {
  34. tendermint.types.Vote vote = 1 [(gogoproto.nullable) = false];
  35. }
  36. // SignProposalRequest is a request to sign a proposal
  37. message SignProposalRequest {
  38. tendermint.types.Proposal proposal = 1;
  39. string chain_id = 2;
  40. }
  41. // SignedProposalResponse is response containing a signed proposal or an error
  42. message SignedProposalResponse {
  43. tendermint.types.Proposal proposal = 1 [(gogoproto.nullable) = false];
  44. }
  45. }
  46. ```
  47. > Note: Remote Singer errors are removed in favor of [grpc status error codes](https://grpc.io/docs/guides/error/).
  48. In previous versions of the remote signer, Tendermint acted as the server and the remote signer as the client. In this process the client established a long lived connection providing a way for the server to make requests to the client. In the new version it has been simplified. Tendermint is the client and the remote signer is the server. This follows client and server architecture and simplifies the previous protocol.
  49. #### Keep Alive
  50. If you have worked on the private validator system you will see that we are removing the `PingRequest` and `PingResponse` messages. These messages were used to create functionality which kept the connection alive. With gRPC there is a [keep alive feature](https://github.com/grpc/grpc/blob/master/doc/keepalive.md) that will be added along side the integration to provide the same functionality.
  51. #### Metrics
  52. Remote signers are crucial to operating secure and consistently up Validators. In the past there were no metrics to tell the operator if something is wrong other than the node not signing. Integrating metrics into the client and provided server will be done with [prometheus](https://github.com/grpc-ecosystem/go-grpc-prometheus). This will be integrated into node's prometheus export for node operators.
  53. #### Security
  54. [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) is widely adopted with the use of gRPC. There are various forms of TLS (one-way & two-way). One way is the client identifying who the server is, while two way is both parties identifying the other. For Tendermint's use case having both parties identifying each other provides adds an extra layer of security. This requires users to generate both client and server certificates for a TLS connection.
  55. An insecure option will be provided for users who do not wish to secure the connection.
  56. #### Upgrade Path
  57. This is a largely breaking change for validator operators. The optimal upgrade path would be to release gRPC in a minor release, allow key management systems to migrate to the new protocol. In the next major release the current system (raw tcp/unix) is removed. This allows users to migrate to the new system and not have to coordinate upgrading the key management system alongside a network upgrade.
  58. The upgrade of [tmkms](https://github.com/iqlusioninc/tmkms) will be coordinated with Iqlusion. They will be able to make the necessary upgrades to allow users to migrate to gRPC from the current protocol.
  59. ## Status
  60. Proposed
  61. ### Positive
  62. - Use an adopted standard for secure communication. (TLS)
  63. - Use an adopted communication protocol. (gRPC)
  64. - Requests are multiplexed onto the tcp connection. (http/2)
  65. - Language agnostic service definition.
  66. ### Negative
  67. - Users will need to generate certificates to use TLS. (Added step)
  68. - Users will need to find a supported gRPC supported key management system
  69. ### Neutral