[docs] Explain concepts and cryptography for API key construction

[fungs]

Type of documentation issue

Missing Information

Describe the problem and the proposed solution

Unkey is great software that fills a need!

I've read the current docs, and they are pretty comprehensive when it comes to usage. But for the security architecture I only see the statement, that API keys are checked using their hashes. Without digging into the source code, I can't answer fundamental questions like:

• how is the API key itself generated, and what is the encoding format?
• is there any data "wrapped" (encoded) in the string itself, or is it just random?
• are API keys cryptographically signed?
• are API keys intrinsically linked to and API?

Related questions are:

• where is "wrapped" data stored?
• is "wrapped" data considered to be private (to whom)?

I noted that keys can be unwrapped by anyone without authentication using the public unkey API (which also seems to count against the API call limits, so a malicious customer could easily consume the API calls in an endless while-curl-loop, but that's a different topic). Due to this fact, I assume that wrapped data is considered public. That's however important, as the data can be used for authorization and should then not contain data which should not be visible to end users.

Just my two cents: I think a little cryptography, like real root keys and signing in the cryptographic sense, could make the whole architecture more robust and secure. But for judging, I'd need to understand the very basics asked here.

[linear[bot]]

ENG-610 [docs] Explain concepts and cryptography for API key construction

[chronark]

Good point, we should expand the docs!

Before we do, what do you mean by "wrapped" data?

---

and regarding this:

so a malicious customer could easily consume the API calls in an endless while-curl-loop

yes they could and we are working to migrate towards preventing this, but a malicious customer could also take that same key and just spam requests against your API endpoint, which would result in the same outcome.

other than requiring a 2nd factor (apiId or ideally root key), we're also building out a system to detect abuse to alert you and you can disable the key manually or potentially automatically

[fungs]

Before we do, what do you mean by "wrapped" data?

I was referring to the phrase "unwrap the data" somewhere in the documentation, which might be misleading, because it suggests that the associated metadata including owner and role are somehow encoded in the data?

but a malicious customer could also take that same key and just spam requests against your API endpoint, which would result in the same outcome

My API is under my control and I could easily take precautions against such actions, like first level rate limitation, exponential time penalties, firewall blocking etc.