|
| 1 | +[](https://maven-badges.herokuapp.com/maven-central/io.bspk/httpsig) |
| 2 | + |
| 3 | +This is a Java implementation of [HTTP Message Signatures](https://www.ietf.org/archive/id/draft-ietf-httpbis-message-signatures-08.html). An online sandbox for testing and viewing HTTP Message Signatures is available at <https://httpsig.org>. |
| 4 | + |
| 5 | +Requires Java 14+. |
| 6 | + |
| 7 | +## Maven Coordinates |
| 8 | + |
| 9 | +``` xml |
| 10 | +<dependency> |
| 11 | + <groupId>${project.groupId}</groupId> |
| 12 | + <artifactId>${project.artifactId}</artifactId> |
| 13 | + <version>${project.version}</version> |
| 14 | +</dependency> |
| 15 | +``` |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +To use this library, you need to supply an implementation of `ComponentProvider` to provide the message components for the signature base. Several providers are included for Java Spring, for both server-side and client side HTTP. Custom implementations of this interface can also be provided. |
| 20 | + |
| 21 | +### Signing |
| 22 | + |
| 23 | +To sign an HTTP message, first create the set of `SignatureParameters` and add the required covered component identifiers. Then create the signature base string, and finally pass this to the signing primitive. |
| 24 | + |
| 25 | +In this example, `signingKey` is a `JWK` object from the Nimbus JOSE JWT library, and the Apache Commons Lang `RandomStringUtils` is used to provide randomized values in several places. The `request` variable is a `HttpRequest` object from a Spring Rest Template, here accessed using a `ClientHttpRequestInterceptor` implementation. |
| 26 | + |
| 27 | +First, we create our parameters: |
| 28 | + |
| 29 | +``` java |
| 30 | +SignatureParameters sigParams = new SignatureParameters() |
| 31 | + .setCreated(Instant.now()) |
| 32 | + .setKeyid(signingKey.getKeyID()) |
| 33 | + .setNonce(RandomStringUtils.randomAlphanumeric(13)) |
| 34 | + .addComponentIdentifier("@target-uri") |
| 35 | + .addComponentIdentifier("@method") |
| 36 | + .addComponentIdentifier("Authorization"); |
| 37 | +``` |
| 38 | + |
| 39 | +We then create our signature base, in this case using the `RestTemplateProvider` implementation for Spring Rest Templates. |
| 40 | + |
| 41 | +``` java |
| 42 | +SignatureContext ctx = new RestTemplateProvider(request); |
| 43 | +SignatureBaseBuilder baseBuilder = new SignatureBaseBuilder(sigParams, ctx); |
| 44 | +byte[] baseBytes = baseBuilder.createSignatureBase(); |
| 45 | +``` |
| 46 | + |
| 47 | +We can now pass this signature base into the cryptographic primative, with our signing key. Note that we have to explicitly provide an `HttpSigAlgorithm` here even though we didn't specify it in the signature parameters. |
| 48 | + |
| 49 | +``` java |
| 50 | +HttpSign httpSign = new HttpSign(httpSigAlgorithm, signingKey); |
| 51 | +byte[] s = httpSign.sign(baseBytes); |
| 52 | +``` |
| 53 | + |
| 54 | +Finally, we can take our signature parameters and signed content to create headers that we can add to our request message. |
| 55 | + |
| 56 | +``` java |
| 57 | +String sigId = RandomStringUtils.randomAlphabetic(5).toLowerCase(); |
| 58 | + |
| 59 | +Dictionary sigHeader = Dictionary.valueOf(Map.of( |
| 60 | + sigId, ByteSequenceItem.valueOf(s))); |
| 61 | + |
| 62 | +Dictionary sigInputHeader = Dictionary.valueOf(Map.of( |
| 63 | + sigId, sigParams.toComponentValue())); |
| 64 | + |
| 65 | +request.getHeaders().add("Signature", sigHeader.serialize()); |
| 66 | +request.getHeaders().add("Signature-Input", sigInputHeader.serialize()); |
| 67 | +``` |
| 68 | + |
| 69 | +### Verify |
| 70 | + |
| 71 | +To sign an HTTP message, first extract the signature value and `SignatureParameters` from the headers of the request message. Next, ensure that the expected parts of the message are covered by the signature. Then create the signature base string, and finally pass this to the verification primitive. |
| 72 | + |
| 73 | +In this example, we're running on a Spring servlet container and using the `HttpServletRequestProvider` implementation from the library. The string `sigId` is the identifier of the signature we are verifying. The variable `verificationKey` is a `JWK` object that contains the public verification key. |
| 74 | + |
| 75 | +First, we extract the values from the headers. Both `signature` and `signatureInput` have already been parsed as `Dictionary` structured headers. |
| 76 | + |
| 77 | +``` java |
| 78 | +SignatureParameters sigParams = SignatureParameters.fromDictionaryEntry(signatureInput, sigId); |
| 79 | +ByteSequenceItem sigValue = (ByteSequenceItem) signature.get().get(sigId); |
| 80 | +``` |
| 81 | + |
| 82 | +Next, we make sure the covered components include the required items. |
| 83 | + |
| 84 | +``` java |
| 85 | +if (sigParams.containsComponentIdentifier("@method") |
| 86 | + && (sigParams.containsComponentIdentifier("@target-uri")) |
| 87 | + && (sigParams.containsComponentIdentifier("Authorization"))) { |
| 88 | +``` |
| 89 | + |
| 90 | +Next, we create a provider context and create the signature base. |
| 91 | + |
| 92 | +``` java |
| 93 | +SignatureContext ctx = new HttpServletRequestProvider(request); |
| 94 | + |
| 95 | +SignatureBaseBuilder baseBuilder = new SignatureBaseBuilder(sigParams, ctx); |
| 96 | + |
| 97 | +byte[] baseBytes = baseBuilder.createSignatureBase(); |
| 98 | +``` |
| 99 | + |
| 100 | +Now, we extract the signature and pass it to the verification function along with our verification key. Note that we have to pass in an explicit `HttpSigAlgorithm` value to create the verifier, whether or not one is included in the signature parameters. |
| 101 | + |
| 102 | +``` java |
| 103 | +HttpVerify verify = new HttpVerify(httpSigAlgorithm, verifyKey); |
| 104 | + |
| 105 | +ByteBuffer bb = sigValue.get(); |
| 106 | +byte[] sigBytes = new byte[bb.remaining()]; |
| 107 | +bb.get(sigBytes); |
| 108 | + |
| 109 | +if (!verify.verify(baseBytes, sigBytes)) { |
| 110 | + throw new RuntimeException("Bad Signature, no biscuit"); |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +The `verify()` function returns a boolean that indicates whether the signature verified or not given the input parameters. In this case we throw an error if it doesn't verify. |
0 commit comments