No documentation for policy called "HMAC" in apigee edge

bbhatia
Participant III

I need to generate hmac and trying to use policy HMAC in apigee edge but there is no documentation for it.

Can someone point me to right link for HMAC documenation. See below image.

10092-annotation-2020-07-02-162632.png

Solved Solved
2 12 1,944
1 ACCEPTED SOLUTION

The HMAC policy is available in some Apigee organizations, I believe it may be limited to evaluation organizations now. [Update 2020-09-27: it is now available in virtually all organizations] But that is changing. The Apigee update that includes the HMAC policy is "coming soon" to all organizations. Perhaps not yet available in some commercial organizations.

Rolling out new releases, with new features, in stages like this is typical for Apigee. The one problem we had with the HMAC policy is that in some cases we deployed the UI updates before the we deployed the runtime updates. So you could see the HMAC policy in the UI, but .... if you tried to deploy a proxy containing an HMAC policy, the deployment would fail. And there was a separate, related problem regarding the documentation not being available. I'm sorry about that. We're working to insure that doesn't happen again.

For evaluation organizations, right now, and in the near future in other organizations, you will be able to use configuration like this to compute an HMAC:

<HMAC name="HMAC-1">
    <Algorithm>SHA-256</Algorithm>
    <Message ref="request.content"/>
    <SecretKey ref="private.secretkey"/>
    <Output encoding="base16">hmac_value</Output>
    <VerificationValue ref='variable_name'/> <!-- optional -->
</HMAC>

In lieu of official documentation, here is some quick information.

The Algorithm can be SHA-1, SHA-256, SHA-384, SHA-512.

The Output is the name of a context variable that gets the computed hmac value. Because the hmac is a byte array, it may need to be converted to a string form, in order to be transmitted and easily compared. You can do that with the encoding attribute. The value of that attribute can be base16, base64, and base64url. They all do what you think they should do. The string "hex" is an alias for "base16". If you omit the encoding attribute, you get utf-8 encoding. In that case if you use "Secret" for your key, you would get hex bytes 53 65 63 72 65 74 for your key.

The VerificationValue element tells the policy to not only *compute* the HMAC, but also compare it to an expected value.

Computing an HMAC requires a secret key. One good source of key material is the Consumer Secret. This would allow you to set up an authentication system like this:

  • the client forms its payload. It can be any content-type.
  • the client computes the HMAC(SHA-256) of that payload using the consumer secret that is embedded in the client app.
  • The client sends a request containing the payload, as well as two additional headers: APIKey and HMAC.
  • The Apigee API Proxy receives the request, and does these things:

    1. invoke VerifyAPIKey on the request.header.apikey
    2. invoke HMAC on the request.content, using verifyapikey.POLICYNAME.client_secret as the key material, and specifying VerificationValue with a ref pointing to request.header.hmac. If this HMAC policy fails it means the provided HMAC value did not correspond to the combination of {payload, secret key}, which means either the sender does not have the expected secret key, or the message was modified in transit and should not be trusted.

HMAC is the function behind the HS256 algorithm in JWT. Think of the HMAC policy as a lower-level building block that you can use, if you don't wish to depend on JWT and all of its structure. Many cloud services rely on HMAC to secure requests. Among them: Many AWS services, Google Cloud Storage signed URLs, and Azure Shared Access Signatures. I'm sure there are others. The HttpSignature standard also relies on HMAC.

View solution in original post

12 REPLIES 12

Here's a tip, when you're in Edge UI and you select a policy from the left navigation bar, use the "Help for Selected" link top center of the UI to go directly to the docs for the policy.

See the top right area in the screenshot.

10099-screen-shot-2020-07-06-at-110650-am.png

Normally, this would take you to the docs, but for HMAC, I see it takes you to the release notes.

In the interem: https://docs.apigee.com/release/notes/20032700-apigee-edge-public-cloud-release-notes-ui#hmac

I'll open an internal issue for the documentation.

The HMAC policy is available in some Apigee organizations, I believe it may be limited to evaluation organizations now. [Update 2020-09-27: it is now available in virtually all organizations] But that is changing. The Apigee update that includes the HMAC policy is "coming soon" to all organizations. Perhaps not yet available in some commercial organizations.

Rolling out new releases, with new features, in stages like this is typical for Apigee. The one problem we had with the HMAC policy is that in some cases we deployed the UI updates before the we deployed the runtime updates. So you could see the HMAC policy in the UI, but .... if you tried to deploy a proxy containing an HMAC policy, the deployment would fail. And there was a separate, related problem regarding the documentation not being available. I'm sorry about that. We're working to insure that doesn't happen again.

For evaluation organizations, right now, and in the near future in other organizations, you will be able to use configuration like this to compute an HMAC:

<HMAC name="HMAC-1">
    <Algorithm>SHA-256</Algorithm>
    <Message ref="request.content"/>
    <SecretKey ref="private.secretkey"/>
    <Output encoding="base16">hmac_value</Output>
    <VerificationValue ref='variable_name'/> <!-- optional -->
</HMAC>

In lieu of official documentation, here is some quick information.

The Algorithm can be SHA-1, SHA-256, SHA-384, SHA-512.

The Output is the name of a context variable that gets the computed hmac value. Because the hmac is a byte array, it may need to be converted to a string form, in order to be transmitted and easily compared. You can do that with the encoding attribute. The value of that attribute can be base16, base64, and base64url. They all do what you think they should do. The string "hex" is an alias for "base16". If you omit the encoding attribute, you get utf-8 encoding. In that case if you use "Secret" for your key, you would get hex bytes 53 65 63 72 65 74 for your key.

The VerificationValue element tells the policy to not only *compute* the HMAC, but also compare it to an expected value.

Computing an HMAC requires a secret key. One good source of key material is the Consumer Secret. This would allow you to set up an authentication system like this:

  • the client forms its payload. It can be any content-type.
  • the client computes the HMAC(SHA-256) of that payload using the consumer secret that is embedded in the client app.
  • The client sends a request containing the payload, as well as two additional headers: APIKey and HMAC.
  • The Apigee API Proxy receives the request, and does these things:

    1. invoke VerifyAPIKey on the request.header.apikey
    2. invoke HMAC on the request.content, using verifyapikey.POLICYNAME.client_secret as the key material, and specifying VerificationValue with a ref pointing to request.header.hmac. If this HMAC policy fails it means the provided HMAC value did not correspond to the combination of {payload, secret key}, which means either the sender does not have the expected secret key, or the message was modified in transit and should not be trusted.

HMAC is the function behind the HS256 algorithm in JWT. Think of the HMAC policy as a lower-level building block that you can use, if you don't wish to depend on JWT and all of its structure. Many cloud services rely on HMAC to secure requests. Among them: Many AWS services, Google Cloud Storage signed URLs, and Azure Shared Access Signatures. I'm sure there are others. The HttpSignature standard also relies on HMAC.

when it is planned for onprem?

I believe it is in OPDK 4.50.00, though the release notes do not state that.

EDIT: Just tested.

Yes, you can USE the policy in OPDK 4.50.00, but... it doesn't show up in the UI. Ref: b/161351690

I didn't realized the 4.50.x version is something for onprem.. We were used to see 4.15x/4.16x/4.17x/4.18x/4.19x and with old habits i thoughts it may be some document bug..Thankyou.

we will have to wait it to see since we are on 4.19x..

Yes, the PM/Eng team decided to change the numbering scheme. OPDK 4.50.00 is the current release, I guess.

Thanks Dino for explaining. This explains why i was getting error when trying to use it.

"The revision is deployed, but traffic cannot flow. Unexpected Repository Error unexpected element (uri:"", local:"HMAC"). Expected elements are <{}APIProxy>,<{}APIProxyRevisions>,<{}AccessControl>,<{}AccessEntity>,<{}Admin>,<{}Alert>,<{}AliasInfo>,<{}Allow>,<{}AllowConnections>,<{}AppUserId>,<{}AssignMessa"

Sorry about that.
That means your organization does not yet have the HMAC policy enabled.
This rollout is happening now.

Hey @Dino-at-Google are there public docs available and how would one know if their Apigee instance has access to this policy? Would it show up in the UI or are you expected to need to use <HMAC> manually by editing the XML directly?


Many thanks in advance!

The documentation is coming , and also, adding the HMAC policy to the policy chooser is also coming. That's my understanding.

To use it in the UI, you can just add a policy of any type, then paste over the provided XML with the HMAC policy XML, and save the proxy.

Update to an old comment, the documentation is available here:

https://cloud.google.com/apigee/docs/api-platform/reference/policies/hmac-policy