-
-
Notifications
You must be signed in to change notification settings - Fork 300
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
Algorithm Selection Guide #114
Comments
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
See also Algorithm Key Requirements.
How to select a JOSE / JWT cryptographic algorithm for your application
The need to secure tokens comes from a number concerns, any of which may apply to your particular use case:
Understanding which security objectives we're after is the first step in selecting an appropriate JOSE algorithm.
This guide is in large inspired by c2id nimbus-jose-jwt which its authors have graciously allowed me to gather copies and content from.
Available JOSE algorithm classes
HMAC algorithms: An efficient hash (HMAC) for ensuring the integrity and authenticity of data. In order to compute an HMAC you need a secret key.
Digital signatures: Offers the properties of HMAC, plus cryptographic non-repudiation (enabling others than the signer to check the signature's validity). Digital signatures are based on public / private key cryptography. Requires a public / private key pair (of type RSA, elliptic curve (EC), or Edwards-curve Octet Key Pair (OKP)).
Public-key encryption: Encrypt data using the recipient's public key. Note that the receiver cannot verify the origin of encrypted messages - unless combined with a digital signature. Requires a public / private key pair (of type RSA, elliptic curve (EC), or Edwards-curve Octet Key Pair (OKP))
Authenticated encryption: Encrypt data, while also ensuring its integrity and authenticity (like HMAC). Authenticated encryption requires that a shared secret must be exchanged via a secure channel beforehand. JOSE offers encryption with secret (shared) keys and with passwords.
Nested signing and encryption: Combine a digital signature with public-key encryption to achive all security objectives (integrity, authenticity, non-repudiation and confidentiality). Note, that non-repudiation may not always be a design goal (because this proves the origin of a message to third parties).
HMAC
Key type: Symmetric Secret keys (oct)
Algorithms: HS256, HS384, HS512
Use when you're both the issuer and recipient of the token. E.g. when you want to sign your cookie values.
Notes:
Digital Signatures
Key type: Public / Private key pairs (RSA, EC, OKP)
Algorithms:
Use when producing tokens, statements, assertions and documents which integrity and authenticity must be verifiable by third parties. E.g. access tokens, identity tokens, proofs of key possession.
Notes:
Public-Key Encryption
Key type: Public / Private key pairs (RSA, EC, OKP)
Algorithms:
Encrypt using the recipient's public key when you want the token payloads to remain confidential. Recipients will decrypt using their private key. Note that the receiver cannot verify the origin of encrypted messages - unless combined with a digital signature.
Notes:
Authenticated Encryption
Key type: Symmetric Secret keys (oct) or Passwords
Algorithms:
Encrypt using a symmetric secret in case you encrypt data for yourself or in case a shared secret has been exchanged beforehand via a secure channel. Use a password based scheme when encrypting data with a rememberable passphrase.
Notes:
Nested signing and encryption
A signed JWT / JWS object can be additionally encrypted, thus providing integrity, authenticity, non-repudiation and confidentiality to data.
This is achieved by nesting (see #112).
To produce: The JWT is signed with a private RSA, EC or OKP key. The signed JWT then becomes the payload (plaintext) of a JWE object, which is encrypted with either the public key (RSA, EC, OKP) of the recipient, or with a secret key that has been shared between the two parties.
To consume: The JWE object is decrypted with the appropriate key (private key for RSA, EC or OKP, or established secret key). The extracted payload (plaintext) is then parsed as a signed JWT, and verified with the issuer's public key (RSA, EC or OKP).
The text was updated successfully, but these errors were encountered: