Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document token format #369

Closed
nobe4 opened this issue Jun 17, 2024 · 5 comments · Fixed by #372
Closed

Document token format #369

nobe4 opened this issue Jun 17, 2024 · 5 comments · Fixed by #372
Labels

Comments

@nobe4
Copy link
Contributor

nobe4 commented Jun 17, 2024

Is your feature request related to a problem? Please describe.

I opened hashicorp/vault#27151 and due to legal shenanigans ended up not contributing to hashicorp/vault

I was wondering if this project would benefits from clarification towards the token format.

It seems that the code used for generating it is similar to vault's:

openbao/vault/token_store.go

Lines 997 to 1000 in 1800244

entry.Accessor, err = base62.Random(TokenLength)
if err != nil {
return err
}

Happy to discuss this further!

Describe the solution you'd like

Having the token format documented.

Here's the patch I submitted in hashicorp/vault, which might be applicable with little updates to this repo, granted the correct place is found.

+## Token formats
+
+Vault tokens are composed of a _prefix_ and a _body_.
+
+- The _prefix_ indicates the token's type:
+
+  Token Type | Vault 1.9.x or earlier | Vault 1.10 and later
+  -- | -- | --
+  Service tokens | s. | hvs.
+  Batch tokens | b. | hvb.
+  Recovery tokens | r. | hvr.
+
+- The _body_ is a randomly-generated 24 characters [Base62](https://en.wikipedia.org/wiki/Base62) string.
+
+Token are expected to match the following regexp: `(hv)?[sbr]\.[a-zA-Z0-9]{24}`
+
+Examples:
+
+```shell
+# Vault 1.9.x or earlier
+b.n6keuKu5Q6pXhaIcfnC9cFNd
+r.MEOkcS6xauDAZkS4bEvQTpbT
+
+# Vault 1.10 and later
+hvs.R0670sAqZnKX3yW40NddrPVk
+hvb.aYnhlZjetM09MRRc11FSLVk1
+```
+

Additional context

cc github/redacting-logger#48
cc hashicorp/vault#27151

@nobe4 nobe4 added the feature label Jun 17, 2024
@cipherboy
Copy link
Member

Hello @nobe4 -- happy to take such a PR. Do note that we've disabled the "new" Vault 1.9.x format tokens by default in #298 -- SSCTs still exist but one has to manually opt in as the functionality isn't used without Vault Enterprise clustering that OpenBao lacks. (So only s., b., and r. tokens are to be expected.)

That said, IMO, I'd prefer tokens be treated as mostly opaque. Token size changed, so I think the regex may not match both short and long token formats, I'd expect a range operator or two explicit sizes based on types. My 2c., but I saw a lot of pain caused by adding SSCTs in system design that was too closely coupled to token size when perhaps being more forgiving would be better. :-)

@nobe4
Copy link
Contributor Author

nobe4 commented Jun 18, 2024

Hi @cipherboy thanks for your swift answer!

So only s., b., and r. tokens are to be expected.

Gotcha, nice ⭐

I'd prefer tokens be treated as mostly opaque
being more forgiving would be better. :-)

I mostly agree with this. In the event that we want to "look for" OpenBao tokens on an automated basis, to prevent leaks, would a specific regexp work?

How about this more relaxed one? [sbr]\.[a-zA-Z0-9]{24,}

@cipherboy
Copy link
Member

cipherboy commented Jun 18, 2024

I think that should suffice. Note here: https://developer.hashicorp.com/vault/docs/faq/ssct#q-what-token-changes-does-the-server-side-consistent-tokens-feature-introduce

For the new token format (hv[sbr].) that could be above 95 characters. :-)

@nobe4
Copy link
Contributor Author

nobe4 commented Jun 18, 2024

Amazing, where do you think this should be documented? I am happy to open a PR :)

@cipherboy
Copy link
Member

I think your original location (https://openbao.org/docs/concepts/tokens/) is good :-) This repository has the same documentation structure as upstream so I think you'll find the patch should port somewhat cleanly :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants