HTTPS and Encryption in Transit
Vendors require cryptographically signed messages to verify both the source of requests and that they have not been altered in transit.
Why a Request Needs More Than an Identity
An API request can contain an API key that identifies the caller as someone who possesses that key. For many uses, this is enough. But a vendor may also need assurance that the request was not changed while traveling to the server. A cryptographically signed request addresses both questions: did the request come from the holder of the shared secret, and has the request remained unchanged since it was signed?
What do you think happens?
Suppose a request contains a valid API key, but an attacker changes one of its parameters before forwarding it. What can the server conclude from the API key alone?
Reveal answer
Answer: The request came from someone who has the key, but modification cannot be ruled out
An API key tells the server that the sender has the key. By itself, it does not allow the server to verify that the request parameters stayed unchanged in transit.
How Signatures Protect a Request
A signature is created by combining the request message with a shared secret key and applying a mathematical algorithm. The signature therefore depends on the request's contents and on the secret. The client sends the request together with the resulting signature. The server uses the shared secret to recompute what the signature should be for the received request, then compares that result with the signature that arrived. If the message has changed, the recomputed signature no longer matches the original one.
The signature is not merely an extra copy of the API key. It is calculated from the request and the shared secret. Changing the request without knowing the secret prevents an attacker from producing a matching signature.
The Shared Secret Stays Hidden
The client and the server both know the shared secret, but the secret is used as an input to the signing and verification process rather than being included in the request as the signature itself. The request carries the message and its signature. The server uses its own copy of the secret to recompute the signature. The security of this arrangement depends entirely on keeping the shared secret confidential.
A Changed Transfer Request
Detecting a Modified Fund Transfer
A client sends a fund transfer request specifying a transfer of 100 dollars to account 5678. The client signs the request with its secret key. An attacker intercepts the request, changes the amount to 10,000 dollars, and forwards the modified request with the original signature.
Original signing: The client combines the original transfer request with its secret key and produces a signature for the 100-dollar request.
Interception: The attacker changes the amount in the message but does not know the secret key needed to create a new matching signature.
Vendor verification: The bank uses its copy of the secret key to recompute the signature for the modified 10,000-dollar message. That result differs from the original signature.
Decision: Because the signatures do not match, the bank rejects the request. The changed message is not accepted as the request that the client signed.
The signature gives the vendor evidence about both the request source and the request's integrity. Changing the amount causes verification to fail.
Encryption During Transit
Encryption in transit concerns information while it travels between a client and a vendor. The source material distinguishes protected handling from unencrypted channels: shared secrets must not be transmitted over unencrypted channels. Signed requests address a related but separate assurance. A signature lets the vendor detect whether the signed message changed in transit, while the secret used to create that signature must remain confidential.
Do not confuse the request signature with the secret itself. The signature travels with the request; the shared secret must remain confidential and must not be sent as request data.
OAuth and Internet Requests
OAuth is a widely used standard technology for signing requests over the Internet. In this topic, OAuth belongs in the same general mechanism: a request is prepared for signing, a signature is produced using the required secret information, and the receiving service verifies the request. The key learning point is not to treat OAuth as a replacement for the underlying assurance. Requests are signed so the vendor can check their source and whether they were altered in transit.
Choosing the Right Assurance
Not every API request needs a cryptographic signature. Simple API key authentication is sufficient for many situations where the primary concern is identifying who is making the request. A vendor requires signed messages when it needs stronger assurance: not only that the caller is authorized or possesses the key, but also that the request was not altered in transit.
| Authentication approach | What the vendor can establish | When it may be sufficient |
|---|---|---|
| API key only | The request came from someone who has the API key | When the main concern is identifying who is making the request |
| Cryptographically signed request | The request came from the holder of the shared secret and has not changed since it was signed | When the request modifies sensitive data, performs a financial transaction, or accesses protected resources |
Mistakes That Weaken Signed Requests
Assuming an API key proves that a request was not modified.
The server can identify someone who has the key, but the key alone does not verify message integrity.
Fix:
Use a cryptographically signed request when the vendor requires assurance that the message was not altered.Sending the shared secret as ordinary request data.
The shared secret must remain confidential; exposing it allows an attacker to forge signatures.
Fix:
Use the secret as an input to the signing and verification process, and send the resulting signature with the request.Hardcoding or logging the shared secret.
Anyone who learns the secret can create signatures that appear legitimate to the server.
Fix:
Keep the secret confidential and never hardcode it, log it, or share it over an unencrypted channel.Signing a request without considering what the signature protects.
Financial transactions are among the situations where vendors may require proof that the request was not altered.
Fix:
Use the assurance required by the operation; sensitive data changes and financial transactions may need cryptographically signed messages.
Check Your Understanding
A service accepts requests that contain an API key. You are designing an operation that changes protected data. Explain whether an API key alone gives the service enough assurance, and describe what a signed request would add.
Hints
- Start by stating what the API key tells the service.
- Then consider whether the request could be changed while in transit.
- Finally, explain the roles of the shared secret, signature, and server-side recomputation.
A signed request reaches the vendor, but verification fails. List two possible facts about the request or its secret that would explain why the vendor cannot accept it.
Hints
- Consider what happens if the message changes after signing.
- Consider what happens if the secret is not kept consistent and confidential.
Key Takeaways
- An API key identifies a caller as someone who possesses the key, but it does not by itself prove that a request was unchanged in transit.
- A cryptographic signature combines the request message and a shared secret through a mathematical algorithm.
- The vendor verifies a signed request by recomputing the signature and comparing it with the received signature.
- The shared secret must remain confidential and must never be hardcoded, logged, or transmitted over an unencrypted channel.
- OAuth is a widely used technology for signing requests over the Internet, and signed requests are especially valuable for sensitive data, financial transactions, and protected resources.
Key Takeaways
- Cryptographic signatures give vendors evidence about both request source and request integrity.
- A signature is computed from the request and a shared secret; the secret itself must remain confidential.
- A vendor verifies a request by recomputing its signature and comparing the result with the signature received.
- API keys may be sufficient when identification is the main concern, while signed requests are important when modification of the request must also be detected.
- OAuth is a widely used standard technology for signing requests over the Internet.