Algorithms
This page describes polyjose 0.1.0 as designed. The library is in development and not published yet.
polyjose recognises the JOSE algorithm identifiers on this page, spelled exactly as in the IANA JOSE registry. The same identifiers, with the same behaviour, apply in Rust, Node, the Web, Kotlin and Swift.
Recognising an identifier is not the same as accepting it. Every verify and decrypt call takes an explicit allow-list of the algorithms you expect, and a token whose header names anything else fails with AlgorithmNotAllowed before any cryptography runs (RFC 8725 §3.1).
Conformance
Section titled “Conformance”Conforms to RFC 7518: implements every algorithm marked Required. It deliberately omits
RSA-OAEP(SHA-1), RSA signing and decryption (pending RUSTSEC-2023-0071, see the security page) andRSA1_5.
Where a recipient expects RSA-OAEP, use RSA-OAEP-256 instead, or ECDH-ES for new recipients.
RFC 7518 marks three algorithms Required: HS256 for JWS (RFC 7518 §3.1), and A128CBC-HS256 and A256CBC-HS512 for JWE content encryption (RFC 7518 §5.1). polyjose 0.1.0 is designed to implement all three. RSA-OAEP is Recommended+ (RFC 7518 §4.1), not Required.
Reading the tables
Section titled “Reading the tables”- Each table has one column per operation: Sign and Verify for JWS, Encrypt and Decrypt for JWE. Yes means the operation is part of the 0.1.0 design.
- RSA keys are used only for public-key operations. You can verify
RS*andPS*signatures and encrypt to anRSA-OAEP-256recipient, but you can’t sign with RSA or decrypt with an RSA private key. A call that would need one fails withUnsupportedAlgorithm. - No in both columns means polyjose recognises the identifier only to report a precise error.
- Specification gives the section that defines the identifier, then its requirement level: the “JOSE Implementation Requirements” value in the IANA registry. RFC 7518 §3.1, §4.1 and §5.1 set it for the algorithms that RFC defines. A
+means the requirement is likely to become stronger in a future version of the specification, and a-that it is likely to become weaker.
Signatures and MACs (JWS alg)
Section titled “Signatures and MACs (JWS alg)”| Identifier | Sign | Verify | Key | Specification | Details |
|---|---|---|---|---|---|
HS256 | Yes | Yes | oct, at least 32 bytes | RFC 7518 §3.2 Required | HMAC using SHA-256. A key shorter than the hash output is rejected with InvalidKey, when signing and when verifying. |
HS384 | Yes | Yes | oct, at least 48 bytes | RFC 7518 §3.2 Optional | HMAC using SHA-384. |
HS512 | Yes | Yes | oct, at least 64 bytes | RFC 7518 §3.2 Optional | HMAC using SHA-512. |
RS256 | No | Yes | RSA public key, 2048 to 8192 bits | RFC 7518 §3.3 Recommended | RSASSA-PKCS1-v1_5 using SHA-256. Verify only, so that tokens from identity providers can be checked. Signing fails with UnsupportedAlgorithm. Why it is limited |
RS384 | No | Yes | RSA public key, 2048 to 8192 bits | RFC 7518 §3.3 Optional | RSASSA-PKCS1-v1_5 using SHA-384. Why it is limited |
RS512 | No | Yes | RSA public key, 2048 to 8192 bits | RFC 7518 §3.3 Optional | RSASSA-PKCS1-v1_5 using SHA-512. Why it is limited |
PS256 | No | Yes | RSA public key, 2048 to 8192 bits | RFC 7518 §3.5 Optional | RSASSA-PSS using SHA-256 and MGF1 with SHA-256. Why it is limited |
PS384 | No | Yes | RSA public key, 2048 to 8192 bits | RFC 7518 §3.5 Optional | RSASSA-PSS using SHA-384 and MGF1 with SHA-384. Why it is limited |
PS512 | No | Yes | RSA public key, 2048 to 8192 bits | RFC 7518 §3.5 Optional | RSASSA-PSS using SHA-512 and MGF1 with SHA-512. Why it is limited |
ES256 | Yes | Yes | EC P-256 | RFC 7518 §3.4 Recommended+ | ECDSA using P-256 and SHA-256. Verifying accepts both forms of the s value; signing always produces the low form. Don't use a token's exact bytes as a replay key: use the jti claim. |
ES384 | Yes | Yes | EC P-384 | RFC 7518 §3.4 Optional | ECDSA using P-384 and SHA-384. |
ES512 | Yes | Yes | EC P-521 | RFC 7518 §3.4 Optional | ECDSA using P-521 and SHA-512. |
ES256K | Yes | Yes | EC secp256k1 | RFC 8812 §3.2 Optional | ECDSA using secp256k1 curve and SHA-256. |
Ed25519 | Yes | Yes | OKP Ed25519 | RFC 9864 §2.2 Optional | EdDSA using the Ed25519 parameter set (RFC 8032 §5.1). Recommended for new tokens. Verification is strict: small-order public keys are rejected. |
EdDSA | Yes | Yes | OKP Ed25519 | RFC 8037 §3.1 Deprecated (RFC 9864 §4.1.2) | EdDSA signature algorithms. Deprecated. Kept for existing tokens and peers. polyjose uses it with Ed25519 keys only. EdDSA and Ed25519 are separate entries in an allow-list and in a JWK's alg. |
none | No | No | none | RFC 7518 §3.6 Optional | No digital signature or MAC performed. Recognised so the error is precise, and never accepted: a token with alg: none, or an allow-list that names it, fails with AlgorithmNotAllowed. |
For new tokens, prefer Ed25519. RFC 9864 registers it as the fully-specified name for EdDSA with Ed25519, and deprecates the older EdDSA identifier, which polyjose keeps for tokens and peers that already use it.
Key management (JWE alg)
Section titled “Key management (JWE alg)”| Identifier | Encrypt | Decrypt | Key | Specification | Details |
|---|---|---|---|---|---|
RSA-OAEP-256 | Yes | No | RSA public key, 2048 to 8192 bits | RFC 7518 §4.3 Optional | RSAES OAEP using SHA-256 and MGF1 with SHA-256. You can encrypt to an RSA recipient. Decrypting needs the RSA private key, which polyjose does not use. Why it is limited |
A128KW | Yes | Yes | oct, 16 bytes | RFC 7518 §4.4 Recommended | AES Key Wrap using 128-bit key. |
A192KW | Yes | Yes | oct, 24 bytes | RFC 7518 §4.4 Optional | AES Key Wrap using 192-bit key. |
A256KW | Yes | Yes | oct, 32 bytes | RFC 7518 §4.4 Recommended | AES Key Wrap using 256-bit key. |
A128GCMKW | Yes | Yes | oct, 16 bytes | RFC 7518 §4.7 Optional | Key wrapping with AES GCM using 128-bit key. |
A192GCMKW | Yes | Yes | oct, 24 bytes | RFC 7518 §4.7 Optional | Key wrapping with AES GCM using 192-bit key. |
A256GCMKW | Yes | Yes | oct, 32 bytes | RFC 7518 §4.7 Optional | Key wrapping with AES GCM using 256-bit key. |
dir | Yes | Yes | oct, the size the enc algorithm needs | RFC 7518 §4.5 Recommended | Direct use of a shared symmetric key. |
ECDH-ES | Yes | Yes | EC P-256, P-384, P-521 or OKP X25519 | RFC 7518 §4.6 Recommended+ | ECDH-ES using Concat KDF. X25519 follows RFC 8037 §3.2. The sender's ephemeral public key is validated before use. |
ECDH-ES+A128KW | Yes | Yes | EC P-256, P-384, P-521 or OKP X25519 | RFC 7518 §4.6 Recommended | ECDH-ES using Concat KDF and "A128KW" wrapping. |
ECDH-ES+A192KW | Yes | Yes | EC P-256, P-384, P-521 or OKP X25519 | RFC 7518 §4.6 Optional | ECDH-ES using Concat KDF and "A192KW" wrapping. |
ECDH-ES+A256KW | Yes | Yes | EC P-256, P-384, P-521 or OKP X25519 | RFC 7518 §4.6 Recommended | ECDH-ES using Concat KDF and "A256KW" wrapping. |
PBES2-HS256+A128KW | Yes | Yes | oct (the password) | RFC 7518 §4.8 Optional | PBES2 with HMAC SHA-256 and "A128KW" wrapping. Bounded: decryption accepts at most 10,000 iterations (p2c) unless you raise the limit explicitly, up to 1,000,000. Encryption uses 10,000 by default. A larger p2c fails with DecryptionFailed. |
PBES2-HS384+A192KW | Yes | Yes | oct (the password) | RFC 7518 §4.8 Optional | PBES2 with HMAC SHA-384 and "A192KW" wrapping. Bounded at 10,000 iterations by default, as above. |
PBES2-HS512+A256KW | Yes | Yes | oct (the password) | RFC 7518 §4.8 Optional | PBES2 with HMAC SHA-512 and "A256KW" wrapping. Bounded at 10,000 iterations by default, as above. |
RSA-OAEP | No | No | RSA | RFC 7518 §4.3 Recommended+ | RSAES OAEP using default parameters. Uses SHA-1. A header or JWK with alg: RSA-OAEP fails with UnsupportedAlgorithm. Use RSA-OAEP-256, or ECDH-ES. Why it is not supported |
RSA1_5 | No | No | RSA | RFC 7518 §4.2 Recommended- | RSAES-PKCS1-v1_5. Not implemented in either direction; it fails with UnsupportedAlgorithm. Why it is not supported |
Content encryption (JWE enc)
Section titled “Content encryption (JWE enc)”| Identifier | Encrypt | Decrypt | Key | Specification | Details |
|---|---|---|---|---|---|
A128CBC-HS256 | Yes | Yes | 32-byte content encryption key | RFC 7518 §5.2.3 Required | AES_128_CBC_HMAC_SHA_256 authenticated encryption algorithm. |
A192CBC-HS384 | Yes | Yes | 48-byte content encryption key | RFC 7518 §5.2.4 Optional | AES_192_CBC_HMAC_SHA_384 authenticated encryption algorithm. |
A256CBC-HS512 | Yes | Yes | 64-byte content encryption key | RFC 7518 §5.2.5 Required | AES_256_CBC_HMAC_SHA_512 authenticated encryption algorithm. |
A128GCM | Yes | Yes | 16-byte content encryption key | RFC 7518 §5.3 Recommended | AES GCM using 128-bit key. |
A192GCM | Yes | Yes | 24-byte content encryption key | RFC 7518 §5.3 Optional | AES GCM using 192-bit key. |
A256GCM | Yes | Yes | 32-byte content encryption key | RFC 7518 §5.3 Recommended | AES GCM using 256-bit key. |
Compression (JWE zip)
Section titled “Compression (JWE zip)”| Identifier | Compress | Decompress | Key | Specification | Details |
|---|---|---|---|---|---|
DEF | Yes, in Rust with the deflate feature | Yes, in Rust with the deflate feature | none | RFC 7516 §4.1.3 | DEFLATE. Rust only, with the deflate feature, which is off by default. Decompression is capped at 250,000 bytes by default, and runs only after the authentication tag checks. Without the feature, and in the Node, Web, Kotlin and Swift packages, zip fails with UnsupportedAlgorithm. Why it is limited |
Compressing data before encrypting it can leak information about the plaintext (RFC 8725 §3.6), so compression is off unless you turn it on.