Consider Improvements to the keyless documentation

[amouat]

We have this documentation on keyless or OIDC signing. It's fine in as far as it goes, but it left me with a lot of questions that I couldn't find answers to. In particular:

• It doesn’t describe what keyless really mean (that ephemeral keys are created and they don’t need to be stored because y).
• It doesn’t explain what level of trust this gives me i.e. that someone with access to the chosen identity in this exact period signed this image
• It should probably mention something about revocation or why it’s not needed
• I’d really like a timeline/breakdown of what happens e.g. ephemeral keys are created, OIDC token is retrieved (possibly requiring sign-in), certificate is requested, certificate is bound to public key, container is signed, signature is pushed, details are written to transparency log. And also why all these steps are required.

I'm not sure if these questions are answered somewhere else, if so it would help to add a link.

[amouat]

I note some of this is answered here: https://docs.sigstore.dev/security/#putting-it-all-together

[dneville-cvs]

I can open a new issue for this if needed, but this seemed like a good catch-all issue for improvements

I noticed that the OIDC signing docs are referencing a png that doesn't seem to exist in this repo.

Also, the documentation refers to "the link that Cosign provides to the Issuer login page" but doesn't show the command to use to get the link. Unless the command is in the missing image, in which case it would still be nice to have it copy/pastable.

[haydentherapper]

@jonvnadelberg can you take a look at these comments, particularly #167 (comment)?

[smythp]

Looks like John fixed the PNG issue in #182. The other issue mentioned by @dneville-cvs is the somewhat confusing mention of a link:

Follow the link that Cosign provides to the Issuer login page.

This link is generated by Cosign during the flow and cannot be linked directly as suggested, but I think it does make sense to provide more context on the link, something like:

1. Follow the link that Cosign provides to the Issuer login page. If you are using Cosign interactively, a browser window should automatically open after agreeing to Cosign's terms. When using Cosign non-interactively, the link will be printed to stdout.

One other issue which I haven't seen flagged here is the brief mention of a "standard flow" and a "device flow." I couldn't find any other mentions of these terms grepping the docs. From context, I assume the standard flow is the interactive flow and the device flow is the non-interactive flow. If these terms aren't used elsewhere, it might be better to just say the interactive flow and the non-interactive flow.

I'll add a commit to John's PR related to the link language. @ltagliaferri, let me know if it makes sense and I can also make a change to use interactive flow and non-interactive flow, removing the two mentions of device flow on this page.

[smythp]

Not used to not being maintainer, looks like I can't push commits to the end of a PR. @ltagliaferri, feel like starting a new PR on top of John's might confuse things, I'll wait until merge and then do a PR. The branch with the commit:

https://github.com/smythp/sigstore-docs/tree/update-openid_signing.md