Accept an optional address for http-01 challenge

acme4j-client/src/main/java/org/shredzone/acme4j/challenge/Http01Challenge.java

@@ -13,6 +13,9 @@
  */
 package org.shredzone.acme4j.challenge;
 
+import java.net.InetAddress;
+
+import org.shredzone.acme4j.util.ClaimBuilder;
 
 /**
  * Implements the {@value TYPE} challenge.
@@ -22,11 +25,15 @@ package org.shredzone.acme4j.challenge;
 public class Http01Challenge extends GenericTokenChallenge {
     private static final long serialVersionUID = 3322211185872544605L;
 
+    protected static final String KEY_ADDRESS = "address";
+
     /**
      * Challenge type name: {@value}
      */
     public static final String TYPE = "http-01";
 
+    private InetAddress address;
+
     /**
      * Returns the token to be used for this challenge.
      */
@@ -47,9 +54,34 @@ public class Http01Challenge extends GenericTokenChallenge {
         return super.getAuthorization();
     }
 
+    /**
+     * An address that the CA server should connect to in order to request the response.
+     * This address must be included in the set of IP addresses to which the domain name
+     * resolves.
+     * <p>
+     * It is at the discretion of the CA server to use this address for the request.
+     * However, if the address is not included in the set of IP addresses, the challenge
+     * will fail.
+     *
+     * @param address
+     *            Address to request the response from
+     */
+    public void setAddress(InetAddress address) {
+        this.address = address;
+    }
+
+    @Override
+    public void respond(ClaimBuilder cb) {
+        super.respond(cb);
+        if (address != null) {
+            cb.put(KEY_ADDRESS, address.getHostAddress());
+        }
+    }
+
     @Override
     protected boolean acceptable(String type) {
         return TYPE.equals(type);
     }
 
+
 }

acme4j-client/src/test/java/org/shredzone/acme4j/challenge/HttpChallengeTest.java

@@ -18,6 +18,7 @@ import static org.junit.Assert.*;
 import static uk.co.datumedge.hamcrest.json.SameJSONAs.sameJSONAs;
 
 import java.io.IOException;
+import java.net.InetAddress;
 import java.security.KeyPair;
 
 import org.junit.Test;
@@ -71,4 +72,27 @@ public class HttpChallengeTest {
             + KEY_AUTHORIZATION + "\"}").allowingExtraUnexpectedFields());
     }
 
+    /**
+     * Test that {@link Http01Challenge} uses the given address.
+     */
+    @Test
+    public void testAddress() throws IOException {
+        KeyPair keypair = TestUtils.createKeyPair();
+        Registration reg = new Registration(keypair);
+
+        Http01Challenge challenge = new Http01Challenge();
+        challenge.unmarshall(TestUtils.getJsonAsMap("httpChallenge"));
+
+        challenge.setAddress(InetAddress.getByName("198.051.100.012"));
+
+        challenge.authorize(reg);
+
+        ClaimBuilder cb = new ClaimBuilder();
+        challenge.respond(cb);
+
+        assertThat(cb.toString(), sameJSONAs("{\"keyAuthorization\"=\""
+            + KEY_AUTHORIZATION + "\", \"address\"=\"198.51.100.12\"}")
+                        .allowingExtraUnexpectedFields());
+    }
+
 }

src/site/markdown/challenge/http-01.md

@@ -21,3 +21,15 @@ http://${domain}/.well-known/acme-challenge/${token}
 ```
 
 The challenge is completed when the CA was able to download that file and found `content` in it.
+
+## Preferred Address
+
+If your domain name resolves to multiple IP adresses, you can set an explicit address that the CA server should prefer to send the request to. This address must be included in the set of IP addresses.
+
+```java
+Http01Challenge challenge = auth.findChallenge(Http01Challenge.TYPE);
+challenge.setAddress(InetAddress.getByName("198.51.100.12"))
+challenge.authorize(registration);
+```
+
+The server _should_ connect to this address, but is not required to do so.