acme: implement new order-based issuance methods

The order based issuance flow is different from pre-authorization
in that users tell upfront which identifiers they want a future
certificate to contain and the CA responds with a set of authorizations
to satisfy.

Similar to pre-authorization where users start with Client's
Authorize method, fulfill challenges and then call GetAuthorization
or WaitAuthorization, the order based flow starts with AuthorizeOrder
and then GetOrder or WaitOrder.

Once all order authorizations are satisfied, users can call
CreateOrderCert, as opposed to the old CreateCert, and FetchCert as before.
The new method implementation and updates to the existing methods
is in golang.org/cl/194379.

More on order based flow can be found in
https://tools.ietf.org/html/rfc8555#section-7.4.

Updates golang/go#21081

Change-Id: I37c37203b50785d7681f65f815d7b19d9c15b96d
Reviewed-on: https://go-review.googlesource.com/c/crypto/+/192779
Run-TryBot: Alex Vaghin <ddos@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Filippo Valsorda <filippo@golang.org>

acme/acme_test.go

@@ -900,7 +900,7 @@ func TestFetchCertRetry(t *testing.T) {
 func TestFetchCertCancel(t *testing.T) {
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Retry-After", "0")
-		w.WriteHeader(http.StatusAccepted)
+		w.WriteHeader(http.StatusBadRequest)
 	}))
 	defer ts.Close()
 	ctx, cancel := context.WithCancel(context.Background())

acme/jws.go

@@ -24,6 +24,12 @@ type keyID string
 // See jwsEncodeJSON for details.
 const noKeyID = keyID("")
 
+// noPayload indicates jwsEncodeJSON will encode zero-length octet string
+// in a JWS request. This is called POST-as-GET in RFC 8555 and is used to make
+// authenticated GET requests via POSTing with an empty payload.
+// See https://tools.ietf.org/html/rfc8555#section-6.3 for more details.
+const noPayload = ""
+
 // jwsEncodeJSON signs claimset using provided key and a nonce.
 // The result is serialized in JSON format containing either kid or jwk
 // fields based on the provided keyID value.
@@ -50,11 +56,14 @@ func jwsEncodeJSON(claimset interface{}, key crypto.Signer, kid keyID, nonce, ur
 		phead = fmt.Sprintf(`{"alg":%q,"kid":%q,"nonce":%q,"url":%q}`, alg, kid, nonce, url)
 	}
 	phead = base64.RawURLEncoding.EncodeToString([]byte(phead))
-	cs, err := json.Marshal(claimset)
-	if err != nil {
-		return nil, err
+	var payload string
+	if claimset != noPayload {
+		cs, err := json.Marshal(claimset)
+		if err != nil {
+			return nil, err
+		}
+		payload = base64.RawURLEncoding.EncodeToString(cs)
 	}
-	payload := base64.RawURLEncoding.EncodeToString(cs)
 	hash := sha.New()
 	hash.Write([]byte(phead + "." + payload))
 	sig, err := jwsSign(key, sha, hash.Sum(nil))

acme/rfc8555.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
+	"time"
 )
 
 // DeactivateReg permanently disables an existing account associated with c.Key.
@@ -111,7 +112,7 @@ func responseAccount(res *http.Response) (*Account, error) {
 		Orders  string
 	}
 	if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
-		return nil, fmt.Errorf("acme: invalid response: %v", err)
+		return nil, fmt.Errorf("acme: invalid account response: %v", err)
 	}
 	return &Account{
 		URI:       res.Header.Get("Location"),
@@ -120,3 +121,143 @@ func responseAccount(res *http.Response) (*Account, error) {
 		OrdersURL: v.Orders,
 	}, nil
 }
+
+// AuthorizeOrder initiates the order-based application for certificate issuance,
+// as opposed to pre-authorization in Authorize.
+//
+// The caller then needs to fetch each required authorization with GetAuthorization
+// and fulfill a challenge using Accept. Once all authorizations are satisfied,
+// the caller will typically want to poll order status using WaitOrder until it's in StatusReady state.
+// To finalize the order and obtain a certificate, the caller submits a CSR with CreateOrderCert.
+func (c *Client) AuthorizeOrder(ctx context.Context, id []AuthzID, opt ...OrderOption) (*Order, error) {
+	dir, err := c.Discover(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	req := struct {
+		Identifiers []wireAuthzID `json:"identifiers"`
+		NotBefore   string        `json:"notBefore,omitempty"`
+		NotAfter    string        `json:"notAfter,omitempty"`
+	}{}
+	for _, v := range id {
+		req.Identifiers = append(req.Identifiers, wireAuthzID{
+			Type:  v.Type,
+			Value: v.Value,
+		})
+	}
+	for _, o := range opt {
+		switch o := o.(type) {
+		case orderNotBeforeOpt:
+			req.NotBefore = time.Time(o).Format(time.RFC3339)
+		case orderNotAfterOpt:
+			req.NotAfter = time.Time(o).Format(time.RFC3339)
+		default:
+			// Package's fault if we let this happen.
+			panic(fmt.Sprintf("unsupported order option type %T", o))
+		}
+	}
+
+	res, err := c.post(ctx, nil, dir.OrderURL, req, wantStatus(http.StatusCreated))
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+	return responseOrder(res)
+}
+
+// GetOrder retrives an order identified by the given URL.
+// For orders created with AuthorizeOrder, the url value is Order.URI.
+//
+// If a caller needs to poll an order until its status is final,
+// see the WaitOrder method.
+func (c *Client) GetOrder(ctx context.Context, url string) (*Order, error) {
+	if _, err := c.Discover(ctx); err != nil {
+		return nil, err
+	}
+
+	res, err := c.post(ctx, nil, url, noPayload, wantStatus(http.StatusOK))
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+	return responseOrder(res)
+}
+
+// WaitOrder polls an order from the given URL until it is in one of the final states,
+// StatusReady, StatusValid or StatusInvalid, the CA responded with a non-retryable error
+// or the context is done.
+//
+// It returns a non-nil Order only if its Status is StatusReady or StatusValid.
+// In all other cases WaitOrder returns an error.
+// If the Status is StatusInvalid, the returned error is of type *WaitOrderError.
+func (c *Client) WaitOrder(ctx context.Context, url string) (*Order, error) {
+	if _, err := c.Discover(ctx); err != nil {
+		return nil, err
+	}
+	for {
+		res, err := c.post(ctx, nil, url, noPayload, wantStatus(http.StatusOK))
+		if err != nil {
+			return nil, err
+		}
+		o, err := responseOrder(res)
+		res.Body.Close()
+		switch {
+		case err != nil:
+			// Skip and retry.
+		case o.Status == StatusInvalid:
+			return nil, &WaitOrderError{OrderURL: o.URI, Status: o.Status}
+		case o.Status == StatusReady || o.Status == StatusValid:
+			return o, nil
+		}
+
+		d := retryAfter(res.Header.Get("Retry-After"))
+		if d == 0 {
+			// Default retry-after.
+			// Same reasoning as in WaitAuthorization.
+			d = time.Second
+		}
+		t := time.NewTimer(d)
+		select {
+		case <-ctx.Done():
+			t.Stop()
+			return nil, ctx.Err()
+		case <-t.C:
+			// Retry.
+		}
+	}
+}
+
+func responseOrder(res *http.Response) (*Order, error) {
+	var v struct {
+		Status         string
+		Expires        time.Time
+		Identifiers    []wireAuthzID
+		NotBefore      time.Time
+		NotAfter       time.Time
+		Error          *wireError
+		Authorizations []string
+		Finalize       string
+		Certificate    string
+	}
+	if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
+		return nil, fmt.Errorf("acme: error reading order: %v", err)
+	}
+	o := &Order{
+		URI:         res.Header.Get("Location"),
+		Status:      v.Status,
+		Expires:     v.Expires,
+		NotBefore:   v.NotBefore,
+		NotAfter:    v.NotAfter,
+		AuthzURLs:   v.Authorizations,
+		FinalizeURL: v.Finalize,
+		CertURL:     v.Certificate,
+	}
+	for _, id := range v.Identifiers {
+		o.Identifiers = append(o.Identifiers, AuthzID{Type: id.Type, Value: id.Value})
+	}
+	if v.Error != nil {
+		o.Error = v.Error.error(nil /* headers */)
+	}
+	return o, nil
+}

acme/rfc8555_test.go

@@ -474,3 +474,192 @@ func TestRFC_GetRegOtherError(t *testing.T) {
 		t.Errorf("GetReg: %v; want any other non-nil err", err)
 	}
 }
+
+func TestRFC_AuthorizeOrder(t *testing.T) {
+	s := newACMEServer()
+	s.handle("/acme/new-account", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/accounts/1"))
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"status": "valid"}`))
+	})
+	s.handle("/acme/new-order", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/orders/1"))
+		w.WriteHeader(http.StatusCreated)
+		fmt.Fprintf(w, `{
+			"status": "pending",
+			"expires": "2019-09-01T00:00:00Z",
+			"notBefore": "2019-08-31T00:00:00Z",
+			"notAfter": "2019-09-02T00:00:00Z",
+			"identifiers": [{"type":"dns", "value":"example.org"}],
+			"authorizations": [%q]
+		}`, s.url("/authz/1"))
+	})
+	s.start()
+	defer s.close()
+
+	cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+	o, err := cl.AuthorizeOrder(context.Background(), DomainIDs("example.org"),
+		WithOrderNotBefore(time.Date(2019, 8, 31, 0, 0, 0, 0, time.UTC)),
+		WithOrderNotAfter(time.Date(2019, 9, 2, 0, 0, 0, 0, time.UTC)),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	okOrder := &Order{
+		URI:         s.url("/orders/1"),
+		Status:      StatusPending,
+		Expires:     time.Date(2019, 9, 1, 0, 0, 0, 0, time.UTC),
+		NotBefore:   time.Date(2019, 8, 31, 0, 0, 0, 0, time.UTC),
+		NotAfter:    time.Date(2019, 9, 2, 0, 0, 0, 0, time.UTC),
+		Identifiers: []AuthzID{AuthzID{Type: "dns", Value: "example.org"}},
+		AuthzURLs:   []string{s.url("/authz/1")},
+	}
+	if !reflect.DeepEqual(o, okOrder) {
+		t.Errorf("AuthorizeOrder = %+v; want %+v", o, okOrder)
+	}
+}
+
+func TestRFC_GetOrder(t *testing.T) {
+	s := newACMEServer()
+	s.handle("/acme/new-account", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/accounts/1"))
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"status": "valid"}`))
+	})
+	s.handle("/orders/1", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/orders/1"))
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{
+			"status": "invalid",
+			"expires": "2019-09-01T00:00:00Z",
+			"notBefore": "2019-08-31T00:00:00Z",
+			"notAfter": "2019-09-02T00:00:00Z",
+			"identifiers": [{"type":"dns", "value":"example.org"}],
+			"authorizations": ["/authz/1"],
+			"finalize": "/orders/1/fin",
+			"certificate": "/orders/1/cert",
+			"error": {"type": "badRequest"}
+		}`))
+	})
+	s.start()
+	defer s.close()
+
+	cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+	o, err := cl.GetOrder(context.Background(), s.url("/orders/1"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	okOrder := &Order{
+		URI:         s.url("/orders/1"),
+		Status:      StatusInvalid,
+		Expires:     time.Date(2019, 9, 1, 0, 0, 0, 0, time.UTC),
+		NotBefore:   time.Date(2019, 8, 31, 0, 0, 0, 0, time.UTC),
+		NotAfter:    time.Date(2019, 9, 2, 0, 0, 0, 0, time.UTC),
+		Identifiers: []AuthzID{AuthzID{Type: "dns", Value: "example.org"}},
+		AuthzURLs:   []string{"/authz/1"},
+		FinalizeURL: "/orders/1/fin",
+		CertURL:     "/orders/1/cert",
+		Error:       &Error{ProblemType: "badRequest"},
+	}
+	if !reflect.DeepEqual(o, okOrder) {
+		t.Errorf("GetOrder = %+v\nwant %+v", o, okOrder)
+	}
+}
+
+func TestRFC_WaitOrder(t *testing.T) {
+	for _, st := range []string{StatusReady, StatusValid} {
+		t.Run(st, func(t *testing.T) {
+			testWaitOrder(t, st)
+		})
+	}
+}
+
+func testWaitOrder(t *testing.T, okStatus string) {
+	s := newACMEServer()
+	s.handle("/acme/new-account", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/accounts/1"))
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"status": "valid"}`))
+	})
+	var count int
+	s.handle("/orders/1", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/orders/1"))
+		w.WriteHeader(http.StatusOK)
+		s := StatusPending
+		if count > 0 {
+			s = okStatus
+		}
+		fmt.Fprintf(w, `{"status": %q}`, s)
+		count++
+	})
+	s.start()
+	defer s.close()
+
+	var order *Order
+	var err error
+	done := make(chan struct{})
+	go func() {
+		cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+		order, err = cl.WaitOrder(context.Background(), s.url("/orders/1"))
+		close(done)
+	}()
+	select {
+	case <-time.After(3 * time.Second):
+		t.Fatal("WaitOrder took too long to return")
+	case <-done:
+		if err != nil {
+			t.Fatalf("WaitOrder: %v", err)
+		}
+		if order.Status != okStatus {
+			t.Errorf("order.Status = %q; want %q", order.Status, okStatus)
+		}
+	}
+}
+
+func TestRFC_WaitOrderError(t *testing.T) {
+	s := newACMEServer()
+	s.handle("/acme/new-account", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/accounts/1"))
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"status": "valid"}`))
+	})
+	var count int
+	s.handle("/orders/1", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Location", s.url("/orders/1"))
+		w.WriteHeader(http.StatusOK)
+		s := StatusPending
+		if count > 0 {
+			s = StatusInvalid
+		}
+		fmt.Fprintf(w, `{"status": %q}`, s)
+		count++
+	})
+	s.start()
+	defer s.close()
+
+	var err error
+	done := make(chan struct{})
+	go func() {
+		cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+		_, err = cl.WaitOrder(context.Background(), s.url("/orders/1"))
+		close(done)
+	}()
+	select {
+	case <-time.After(3 * time.Second):
+		t.Fatal("WaitOrder took too long to return")
+	case <-done:
+		if err == nil {
+			t.Fatal("WaitOrder returned nil error")
+		}
+		e, ok := err.(*WaitOrderError)
+		if !ok {
+			t.Fatalf("err = %v (%T); want WaitOrderError", err, err)
+		}
+		if e.OrderURL != s.url("/orders/1") {
+			t.Errorf("e.OrderURL = %q; want %q", e.OrderURL, s.url("/orders/1"))
+		}
+		if e.Status != StatusInvalid {
+			t.Errorf("e.Status = %q; want %q", e.Status, StatusInvalid)
+		}
+	}
+}