diff --git a/custom-payload-header/README.md b/custom-payload-header/README.md index b8e2b81..ad82c8f 100644 --- a/custom-payload-header/README.md +++ b/custom-payload-header/README.md @@ -8,36 +8,40 @@ title: Custom Payload Signature Scheme for Authenticated JSON RPC Service Access > [!IMPORTANT] > This specification provides a structured approach to implementing a secure and authenticated method for interacting with JSON RPC service endpoints. It ensures that the requests are authenticated and traceable, enhancing the security and usability of the service. -**Title**: Custom Payload Signature Scheme for Authenticated JSON RPC Service Access +# Custom Payload Signature Scheme for Authenticated JSON RPC Service Access -**Abstract**: This document specifies a method for authenticating requests to a JSON RPC service endpoint using a custom payload signature scheme. The scheme involves signing the request payload with an Ethereum key and including this signature in the request headers. +## Abstract -**1. Introduction**: This specification defines a method for authenticating requests made to a JSON RPC service endpoint. The authentication is achieved by signing the request payload using an Ethereum key and including this signature in the request's HTTP headers. This method ensures that the requests are authenticated and can be tracked over time for user statistics. +This document specifies a method for authenticating requests to a JSON RPC service endpoint using a custom payload signature scheme. The scheme involves signing the request payload with an Ethereum key and including this signature in the request headers. -**2. Terminology**: +### Introduction -- **JSON RPC**: A remote procedure call protocol encoded in JSON. -- **Ethereum Key**: A cryptographic key used for signing transactions in the Ethereum blockchain. -- **Payload Signature**: A digital signature generated by signing the request payload. -- **X-Flashbots-Signature**: HTTP header used to include the payload signature for Flashbots requests. -- **X-Auction-Signature**: HTTP header used to include the payload signature for auction requests. + This specification defines a method for authenticating requests made to a JSON RPC service endpoint. The authentication is achieved by signing the request payload using an Ethereum key and including this signature in the request's HTTP headers. This method ensures that the requests are authenticated and can be tracked over time for user statistics. -**3. Specification**: +### Terminology: -- **Signature Generation**: +- JSON RPC: A remote procedure call protocol encoded in JSON. +- Ethereum Key: A cryptographic key used for signing transactions in the Ethereum blockchain. +- Payload Signature: A digital signature generated by signing the request payload. +- X-Flashbots-Signature: HTTP header used to include the payload signature for Flashbots requests. +- X-Auction-Signature: HTTP header used to include the payload signature for auction requests. + +### Specification: + +- Signature Generation: - The client MUST generate a digital signature by signing the hash of the JSON body of the request. The JSON body MUST be encoded as UTF-8 bytes before hashing. - Any valid Ethereum key CAN be used for signing the payload. - The Ethereum address associated with the key used for signing WILL be utilized by the service to track requests and provide user statistics. -- **Request Headers**: +- Request Headers: - The client MUST include the generated signature in the request headers. - For Flashbots requests, the signature MUST be included in the `X-Flashbots-Signature` header. - For auction requests, the signature MUST be included in the `X-Auction-Signature` header. - The headers `X-Flashbots-Signature` and `X-Auction-Signature` are CASE-INSENSITIVE. -- **Example Usage with cURL**: +- Example Usage with cURL: - For Flashbots requests: ``` curl -X POST -H "Content-Type: application/json" -H "X-Flashbots-Signature: 0x1234:0xabcd" --data '{"jsonrpc":"2.0","method":"eth_sendBundle","params":[...],"id":1}' @@ -47,22 +51,18 @@ title: Custom Payload Signature Scheme for Authenticated JSON RPC Service Access curl -X POST -H "Content-Type: application/json" -H "X-Auction-Signature: 0x1234:0xabcd" --data '{"jsonrpc":"2.0","method":"eth_sendBundle","params":[...],"id":1}' ``` -**4. Security Considerations**: +## Security Considerations: - The use of Ethereum keys for signing the payload adds a layer of security by ensuring that the sender holds the corresponding private key. - Clients MUST protect their Ethereum private keys to prevent unauthorized access and request forgery. -**5. Backwards Compatibility**: +## Backwards Compatibility: - This specification does not affect existing JSON RPC implementations that do not use payload signature authentication. - Implementations not supporting this scheme WILL treat requests as unauthenticated. -**6. References**: +## References: - [JSON RPC Specification] - [Ethereum Key Management] - [Digital Signature Standards] - -**7. Acknowledgments**: - -- Contributions to this specification by [List of Contributors].