{"record":{"id":"312b1ff8b0e6e49c","repo":"jwtk/jjwt","slug":"jwa-base64urluint-values-must-be-0-non-negativ","errorCode":null,"errorMessage":"JWA Base64urlUInt values MUST be >= 0 (non-negative) per the 'Base64urlUInt' definition in [JWA RFC 7518, Section 2](https://www.rfc-editor.org/rfc/rfc7518.html#section-2)","messagePattern":"JWA Base64urlUInt values MUST be >= 0 \\(non-negative\\) per the 'Base64urlUInt' definition in \\[JWA RFC 7518, Section 2\\]\\(https://www\\.rfc-editor\\.org/rfc/rfc7518\\.html#section-2\\)","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/lang/BigIntegerUBytesConverter.java","lineNumber":32,"sourceCode":" * limitations under the License.\n */\npackage io.jsonwebtoken.impl.lang;\n\nimport io.jsonwebtoken.lang.Assert;\n\nimport java.math.BigInteger;\n\npublic class BigIntegerUBytesConverter implements Converter<BigInteger, byte[]> {\n\n    private static final String NEGATIVE_MSG =\n        \"JWA Base64urlUInt values MUST be >= 0 (non-negative) per the 'Base64urlUInt' definition in \" +\n            \"[JWA RFC 7518, Section 2](https://www.rfc-editor.org/rfc/rfc7518.html#section-2)\";\n\n    @Override\n    public byte[] applyTo(BigInteger bigInt) {\n        Assert.notNull(bigInt, \"BigInteger argument cannot be null.\");\n        if (BigInteger.ZERO.compareTo(bigInt) > 0) {\n            throw new IllegalArgumentException(NEGATIVE_MSG);\n        }\n\n        final int bitLen = bigInt.bitLength();\n        final byte[] bytes = bigInt.toByteArray();\n        // Determine minimal number of bytes necessary to represent an unsigned byte array.\n        // It must be 1 or more because zero still requires one byte\n        final int unsignedByteLen = Math.max(1, Bytes.length(bitLen)); // always need at least one byte\n\n        if (bytes.length == unsignedByteLen) { // already in the form we need\n            return bytes;\n        }\n        //otherwise, we need to strip the sign byte (start copying at index 1 instead of 0):\n        byte[] ubytes = new byte[unsignedByteLen];\n        System.arraycopy(bytes, 1, ubytes, 0, unsignedByteLen);\n        return ubytes;\n    }\n\n    @Override","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/lang/BigIntegerUBytesConverter.java#L14-L50","documentation":"BigIntegerUBytesConverter converts a BigInteger into the minimal unsigned byte array used by JWA (RFC 7518) for values like EC coordinates and 'kid'-related unsigned integers. JWA's Base64urlUInt definition requires the integer be non-negative, so applyTo explicitly rejects negative BigIntegers with an IllegalArgumentException. Negative numbers have no valid unsigned big-endian JWA representation.","triggerScenarios":"Calling applyTo (directly or via JWT header/claim serialization) with a negative BigInteger, e.g. passing a negative ECDSA signature component (r or s), a negative x/y coordinate, or computing a value via modular arithmetic that wrapped negative.","commonSituations":"Hand-rolling ECDSA signature r/s values and accidentally producing negatives; decoding a byte array with sign-preserving BigInteger(byte[]) on data whose high bit is set; copying key material from a library that encodes values as signed.","solutions":["Ensure the BigInteger is non-negative before conversion: if (v.signum() < 0) v = v.add(modulus) (two's complement wrap into range) or fix the upstream computation.","Use BigInteger(1, signedBytes) with an explicit positive sign when constructing from raw bytes instead of new BigInteger(byte[]).","If the value is genuinely negative, it is not valid JWA data - regenerate the key material or signature."],"exampleFix":"// before\nBigInteger r = new BigInteger(signatureBytes); // may be negative\nbyte[] encoded = converter.applyTo(r);\n// after\nBigInteger r = new BigInteger(1, signatureBytes); // always non-negative\nif (r.signum() < 0) { /* invalid key material - handle */ }\nbyte[] encoded = converter.applyTo(r);","handlingStrategy":"validation","validationCode":"if (value == null || value.signum() < 0) {\n    throw new IllegalArgumentException(\"JWA Base64urlUInt value must be non-negative: \" + value);\n}","typeGuard":null,"tryCatchPattern":"try {\n    byte[] encoded = converter.applyTo(bigInt);\n} catch (IllegalArgumentException e) {\n    // handle negative/invalid BigInteger\n}","preventionTips":["Always construct BigIntegers from bytes with sign=1: new BigInteger(1, bytes)","Check signum() >= 0 before any JWA integer encoding","For ECDSA, normalize s values (s = n - s when s > n/2) and never emit negatives"],"tags":["jwt","jwa","biginteger","base64url"],"backgroundTag":"invalid-argument-value","analyzedSha":"fb71496164c71442d08adec4571d9616ed5e1b8d","analyzedAt":"2026-09-09T00:33:09.982Z","contentChangedAt":"2026-09-09T00:33:09.982Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}