acme: support RFC 8555 account management

Most important change in this CL is that Client is now able
to correctly format and sign requests in KID form with a valid
"kid" value.

According to the RFC, most requests must include KID field
in the protected head of JWS requests. The KID value is the account
identity provided by the CA during registration.

The KID value is also the Account URL. Hence, the CL is tied to
account management.

Updates golang/go#21081

Change-Id: I13f51e1fc52db7596eb933b47fa2014beb93c1ab
Reviewed-on: https://go-review.googlesource.com/c/crypto/+/191602
Run-TryBot: Alex Vaghin <ddos@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

acme/acme.go

@@ -119,21 +119,49 @@ type Client struct {
 	// identifiable by the server, in case they are causing issues.
 	UserAgent string
 
-	dirMu sync.Mutex // guards writes to dir
-	dir   *Directory // cached result of Client's Discover method
+	cacheMu sync.Mutex
+	dir     *Directory // cached result of Client's Discover method
+	kid     keyID      // cached Account.URI obtained from registerRFC or getAccountRFC
 
 	noncesMu sync.Mutex
 	nonces   map[string]struct{} // nonces collected from previous responses
 }
 
+// accountKID returns a key ID associated with c.Key, the account identity
+// provided by the CA during RFC based registration.
+// It assumes c.Discover has already been called.
+//
+// accountKID requires at most one network roundtrip.
+// It caches only successful result.
+//
+// When in pre-RFC mode or when c.getRegRFC responds with an error, accountKID
+// returns noKeyID.
+func (c *Client) accountKID(ctx context.Context) keyID {
+	c.cacheMu.Lock()
+	defer c.cacheMu.Unlock()
+	if c.dir.OrderURL == "" {
+		// Assume legacy CA.
+		return noKeyID
+	}
+	if c.kid != noKeyID {
+		return c.kid
+	}
+	a, err := c.getRegRFC(ctx)
+	if err != nil {
+		return noKeyID
+	}
+	c.kid = keyID(a.URI)
+	return c.kid
+}
+
 // Discover performs ACME server discovery using c.DirectoryURL.
 //
 // It caches successful result. So, subsequent calls will not result in
 // a network round-trip. This also means mutating c.DirectoryURL after successful call
 // of this method will have no effect.
 func (c *Client) Discover(ctx context.Context) (Directory, error) {
-	c.dirMu.Lock()
-	defer c.dirMu.Unlock()
+	c.cacheMu.Lock()
+	defer c.cacheMu.Unlock()
 	if c.dir != nil {
 		return *c.dir, nil
 	}
@@ -235,7 +263,7 @@ func (c *Client) CreateCert(ctx context.Context, csr []byte, exp time.Duration,
 		req.NotAfter = now.Add(exp).Format(time.RFC3339)
 	}
 
-	res, err := c.post(ctx, c.Key, c.dir.CertURL, req, wantStatus(http.StatusCreated))
+	res, err := c.post(ctx, nil, c.dir.CertURL, req, wantStatus(http.StatusCreated))
 	if err != nil {
 		return nil, "", err
 	}
@@ -289,9 +317,6 @@ func (c *Client) RevokeCert(ctx context.Context, key crypto.Signer, cert []byte,
 		Cert:     base64.RawURLEncoding.EncodeToString(cert),
 		Reason:   int(reason),
 	}
-	if key == nil {
-		key = c.Key
-	}
 	res, err := c.post(ctx, key, c.dir.RevokeURL, body, wantStatus(http.StatusOK))
 	if err != nil {
 		return err
@@ -304,20 +329,32 @@ func (c *Client) RevokeCert(ctx context.Context, key crypto.Signer, cert []byte,
 // during account registration. See Register method of Client for more details.
 func AcceptTOS(tosURL string) bool { return true }
 
-// Register creates a new account registration by following the "new-reg" flow.
-// It returns the registered account. The account is not modified.
+// Register creates a new account with the CA using c.Key.
+// It returns the registered account. The account acct is not modified.
 //
 // The registration may require the caller to agree to the CA's Terms of Service (TOS).
 // If so, and the account has not indicated the acceptance of the terms (see Account for details),
 // Register calls prompt with a TOS URL provided by the CA. Prompt should report
 // whether the caller agrees to the terms. To always accept the terms, the caller can use AcceptTOS.
-func (c *Client) Register(ctx context.Context, a *Account, prompt func(tosURL string) bool) (*Account, error) {
-	if _, err := c.Discover(ctx); err != nil {
+//
+// When interfacing with RFC compliant CA, non-RFC8555 compliant fields of acct are ignored
+// and prompt is called if Directory's Terms field is non-zero.
+// Also see Error's Instance field for when a CA requires already registered accounts to agree
+// to an updated Terms of Service.
+func (c *Client) Register(ctx context.Context, acct *Account, prompt func(tosURL string) bool) (*Account, error) {
+	dir, err := c.Discover(ctx)
+	if err != nil {
 		return nil, err
 	}
 
-	var err error
-	if a, err = c.doReg(ctx, c.dir.RegURL, "new-reg", a); err != nil {
+	// RFC8555 compliant account registration.
+	if dir.OrderURL != "" {
+		return c.registerRFC(ctx, acct, prompt)
+	}
+
+	// Legacy ACME draft registration flow.
+	a, err := c.doReg(ctx, dir.RegURL, "new-reg", acct)
+	if err != nil {
 		return nil, err
 	}
 	var accept bool
@@ -331,9 +368,22 @@ func (c *Client) Register(ctx context.Context, a *Account, prompt func(tosURL st
 	return a, err
 }
 
-// GetReg retrieves an existing registration.
-// The url argument is an Account URI.
+// GetReg retrieves an existing account associated with c.Key.
+//
+// The url argument is an Account URI used with pre-RFC8555 CAs.
+// It is ignored when interfacing with an RFC compliant CA.
 func (c *Client) GetReg(ctx context.Context, url string) (*Account, error) {
+	dir, err := c.Discover(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	// Assume RFC8555 compliant CA.
+	if dir.OrderURL != "" {
+		return c.getRegRFC(ctx)
+	}
+
+	// Legacy CA.
 	a, err := c.doReg(ctx, url, "reg", nil)
 	if err != nil {
 		return nil, err
@@ -344,9 +394,23 @@ func (c *Client) GetReg(ctx context.Context, url string) (*Account, error) {
 
 // UpdateReg updates an existing registration.
 // It returns an updated account copy. The provided account is not modified.
-func (c *Client) UpdateReg(ctx context.Context, a *Account) (*Account, error) {
-	uri := a.URI
-	a, err := c.doReg(ctx, uri, "reg", a)
+//
+// When interfacing with RFC compliant CAs, a.URI is ignored and the account URL
+// associated with c.Key is used instead.
+func (c *Client) UpdateReg(ctx context.Context, acct *Account) (*Account, error) {
+	dir, err := c.Discover(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	// Assume RFC8555 compliant CA.
+	if dir.OrderURL != "" {
+		return c.updateRegRFC(ctx, acct)
+	}
+
+	// Legacy CA.
+	uri := acct.URI
+	a, err := c.doReg(ctx, uri, "reg", acct)
 	if err != nil {
 		return nil, err
 	}
@@ -391,7 +455,7 @@ func (c *Client) authorize(ctx context.Context, typ, val string) (*Authorization
 		Resource:   "new-authz",
 		Identifier: authzID{Type: typ, Value: val},
 	}
-	res, err := c.post(ctx, c.Key, c.dir.AuthzURL, req, wantStatus(http.StatusCreated))
+	res, err := c.post(ctx, nil, c.dir.AuthzURL, req, wantStatus(http.StatusCreated))
 	if err != nil {
 		return nil, err
 	}
@@ -434,6 +498,11 @@ func (c *Client) GetAuthorization(ctx context.Context, url string) (*Authorizati
 //
 // It does not revoke existing certificates.
 func (c *Client) RevokeAuthorization(ctx context.Context, url string) error {
+	// Required for c.accountKID() when in RFC mode.
+	if _, err := c.Discover(ctx); err != nil {
+		return err
+	}
+
 	req := struct {
 		Resource string `json:"resource"`
 		Status   string `json:"status"`
@@ -443,7 +512,7 @@ func (c *Client) RevokeAuthorization(ctx context.Context, url string) error {
 		Status:   "deactivated",
 		Delete:   true,
 	}
-	res, err := c.post(ctx, c.Key, url, req, wantStatus(http.StatusOK))
+	res, err := c.post(ctx, nil, url, req, wantStatus(http.StatusOK))
 	if err != nil {
 		return err
 	}
@@ -520,6 +589,11 @@ func (c *Client) GetChallenge(ctx context.Context, url string) (*Challenge, erro
 //
 // The server will then perform the validation asynchronously.
 func (c *Client) Accept(ctx context.Context, chal *Challenge) (*Challenge, error) {
+	// Required for c.accountKID() when in RFC mode.
+	if _, err := c.Discover(ctx); err != nil {
+		return nil, err
+	}
+
 	auth, err := keyAuth(c.Key.Public(), chal.Token)
 	if err != nil {
 		return nil, err
@@ -534,7 +608,7 @@ func (c *Client) Accept(ctx context.Context, chal *Challenge) (*Challenge, error
 		Type:     chal.Type,
 		Auth:     auth,
 	}
-	res, err := c.post(ctx, c.Key, chal.URI, req, wantStatus(
+	res, err := c.post(ctx, nil, chal.URI, req, wantStatus(
 		http.StatusOK,       // according to the spec
 		http.StatusAccepted, // Let's Encrypt: see https://goo.gl/WsJ7VT (acme-divergences.md)
 	))
@@ -711,7 +785,7 @@ func (c *Client) doReg(ctx context.Context, url string, typ string, acct *Accoun
 		req.Contact = acct.Contact
 		req.Agreement = acct.AgreedTerms
 	}
-	res, err := c.post(ctx, c.Key, url, req, wantStatus(
+	res, err := c.post(ctx, nil, url, req, wantStatus(
 		http.StatusOK,       // updates and deletes
 		http.StatusCreated,  // new account creation
 		http.StatusAccepted, // Let's Encrypt divergent implementation

acme/acme_test.go

@@ -16,6 +16,7 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
+	"io"
 	"math/big"
 	"net/http"
 	"net/http/httptest"
@@ -28,10 +29,10 @@ import (
 
 // Decodes a JWS-encoded request and unmarshals the decoded JSON into a provided
 // interface.
-func decodeJWSRequest(t *testing.T, v interface{}, r *http.Request) {
+func decodeJWSRequest(t *testing.T, v interface{}, r io.Reader) {
 	// Decode request
 	var req struct{ Payload string }
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+	if err := json.NewDecoder(r).Decode(&req); err != nil {
 		t.Fatal(err)
 	}
 	payload, err := base64.RawURLEncoding.DecodeString(req.Payload)
@@ -47,12 +48,14 @@ func decodeJWSRequest(t *testing.T, v interface{}, r *http.Request) {
 type jwsHead struct {
 	Alg   string
 	Nonce string
+	URL   string            `json:"url"`
+	KID   string            `json:"kid"`
 	JWK   map[string]string `json:"jwk"`
 }
 
-func decodeJWSHead(r *http.Request) (*jwsHead, error) {
+func decodeJWSHead(r io.Reader) (*jwsHead, error) {
 	var req struct{ Protected string }
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+	if err := json.NewDecoder(r).Decode(&req); err != nil {
 		return nil, err
 	}
 	b, err := base64.RawURLEncoding.DecodeString(req.Protected)
@@ -123,7 +126,7 @@ func TestRegister(t *testing.T) {
 			Contact   []string
 			Agreement string
 		}
-		decodeJWSRequest(t, &j, r)
+		decodeJWSRequest(t, &j, r.Body)
 
 		// Test request
 		if j.Resource != "new-reg" {
@@ -193,7 +196,7 @@ func TestUpdateReg(t *testing.T) {
 			Contact   []string
 			Agreement string
 		}
-		decodeJWSRequest(t, &j, r)
+		decodeJWSRequest(t, &j, r.Body)
 
 		// Test request
 		if j.Resource != "reg" {
@@ -215,7 +218,11 @@ func TestUpdateReg(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	c := Client{Key: testKeyEC}
+	c := Client{
+		Key:          testKeyEC,
+		DirectoryURL: ts.URL,       // don't dial outside of localhost
+		dir:          &Directory{}, // don't do discovery
+	}
 	a := &Account{URI: ts.URL, Contact: contacts, AgreedTerms: terms}
 	var err error
 	if a, err = c.UpdateReg(context.Background(), a); err != nil {
@@ -254,7 +261,7 @@ func TestGetReg(t *testing.T) {
 			Contact   []string
 			Agreement string
 		}
-		decodeJWSRequest(t, &j, r)
+		decodeJWSRequest(t, &j, r.Body)
 
 		// Test request
 		if j.Resource != "reg" {
@@ -276,7 +283,11 @@ func TestGetReg(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	c := Client{Key: testKeyEC}
+	c := Client{
+		Key:          testKeyEC,
+		DirectoryURL: ts.URL,       // don't dial outside of localhost
+		dir:          &Directory{}, // don't do discovery
+	}
 	a, err := c.GetReg(context.Background(), ts.URL)
 	if err != nil {
 		t.Fatal(err)
@@ -318,7 +329,7 @@ func TestAuthorize(t *testing.T) {
 						Value string
 					}
 				}
-				decodeJWSRequest(t, &j, r)
+				decodeJWSRequest(t, &j, r.Body)
 
 				// Test request
 				if j.Resource != "new-authz" {
@@ -629,7 +640,7 @@ func TestRevokeAuthorization(t *testing.T) {
 				Status   string
 				Delete   bool
 			}
-			decodeJWSRequest(t, &req, r)
+			decodeJWSRequest(t, &req, r.Body)
 			if req.Resource != "authz" {
 				t.Errorf("req.Resource = %q; want authz", req.Resource)
 			}
@@ -644,7 +655,11 @@ func TestRevokeAuthorization(t *testing.T) {
 		}
 	}))
 	defer ts.Close()
-	client := &Client{Key: testKey}
+	client := &Client{
+		Key:          testKey,
+		DirectoryURL: ts.URL,       // don't dial outside of localhost
+		dir:          &Directory{}, // don't do discovery
+	}
 	ctx := context.Background()
 	if err := client.RevokeAuthorization(ctx, ts.URL+"/1"); err != nil {
 		t.Errorf("err = %v", err)
@@ -704,7 +719,7 @@ func TestAcceptChallenge(t *testing.T) {
 			Type     string
 			Auth     string `json:"keyAuthorization"`
 		}
-		decodeJWSRequest(t, &j, r)
+		decodeJWSRequest(t, &j, r.Body)
 
 		// Test request
 		if j.Resource != "challenge" {
@@ -730,7 +745,11 @@ func TestAcceptChallenge(t *testing.T) {
 	}))
 	defer ts.Close()
 
-	cl := Client{Key: testKeyEC}
+	cl := Client{
+		Key:          testKeyEC,
+		DirectoryURL: ts.URL,       // don't dial outside of localhost
+		dir:          &Directory{}, // don't do discovery
+	}
 	c, err := cl.Accept(context.Background(), &Challenge{
 		URI:   ts.URL,
 		Token: "token1",
@@ -771,7 +790,7 @@ func TestNewCert(t *testing.T) {
 			NotBefore string `json:"notBefore,omitempty"`
 			NotAfter  string `json:"notAfter,omitempty"`
 		}
-		decodeJWSRequest(t, &j, r)
+		decodeJWSRequest(t, &j, r.Body)
 
 		// Test request
 		if j.Resource != "new-cert" {
@@ -956,7 +975,7 @@ func TestRevokeCert(t *testing.T) {
 			Certificate string
 			Reason      int
 		}
-		decodeJWSRequest(t, &req, r)
+		decodeJWSRequest(t, &req, r.Body)
 		if req.Resource != "revoke-cert" {
 			t.Errorf("req.Resource = %q; want revoke-cert", req.Resource)
 		}
@@ -1117,7 +1136,7 @@ func TestNonce_postJWS(t *testing.T) {
 			w.Write([]byte(`{"status":"valid"}`))
 		}()
 
-		head, err := decodeJWSHead(r)
+		head, err := decodeJWSHead(r.Body)
 		if err != nil {
 			t.Errorf("decodeJWSHead: %v", err)
 			return

acme/http.go

@@ -156,7 +156,7 @@ func (c *Client) get(ctx context.Context, url string, ok resOkay) (*http.Respons
 }
 
 // post issues a signed POST request in JWS format using the provided key
-// to the specified URL.
+// to the specified URL. If key is nil, c.Key is used instead.
 // It returns a non-error value only when ok reports true.
 //
 // post retries unsuccessful attempts according to c.RetryBackoff
@@ -193,14 +193,28 @@ func (c *Client) post(ctx context.Context, key crypto.Signer, url string, body i
 }
 
 // postNoRetry signs the body with the given key and POSTs it to the provided url.
-// The body argument must be JSON-serializable.
 // It is used by c.post to retry unsuccessful attempts.
+// The body argument must be JSON-serializable.
+//
+// If key argument is nil, c.Key is used to sign the request.
+// If key argument is nil and c.accountKID returns a non-zero keyID,
+// the request is sent in KID form. Otherwise, JWK form is used.
+//
+// In practice, when interfacing with RFC compliant CAs most requests are sent in KID form
+// and JWK is used only when KID is unavailable: new account endpoint and certificate
+// revocation requests authenticated by a cert key.
+// See jwsEncodeJSON for other details.
 func (c *Client) postNoRetry(ctx context.Context, key crypto.Signer, url string, body interface{}) (*http.Response, *http.Request, error) {
+	kid := noKeyID
+	if key == nil {
+		key = c.Key
+		kid = c.accountKID(ctx)
+	}
 	nonce, err := c.popNonce(ctx, url)
 	if err != nil {
 		return nil, nil, err
 	}
-	b, err := jwsEncodeJSON(body, key, noKeyID, nonce, url)
+	b, err := jwsEncodeJSON(body, key, kid, nonce, url)
 	if err != nil {
 		return nil, nil, err
 	}

acme/http_test.go

@@ -87,7 +87,7 @@ func TestPostWithRetries(t *testing.T) {
 			return
 		}
 
-		head, err := decodeJWSHead(r)
+		head, err := decodeJWSHead(r.Body)
 		switch {
 		case err != nil:
 			t.Errorf("decodeJWSHead: %v", err)

acme/jws.go

@@ -30,7 +30,7 @@ const noKeyID = keyID("")
 //
 // If kid is non-empty, its quoted value is inserted in the protected head
 // as "kid" field value. Otherwise, JWK is computed using jwkEncode and inserted
-// as "jwk" field value.
+// as "jwk" field value. The "jwk" and "kid" fields are mutually exclusive.
 //
 // See https://tools.ietf.org/html/rfc7515#section-7.
 func jwsEncodeJSON(claimset interface{}, key crypto.Signer, kid keyID, nonce, url string) ([]byte, error) {

acme/rfc8555.go

@@ -0,0 +1,122 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package acme
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+)
+
+// DeactivateReg permanently disables an existing account associated with c.Key.
+// A deactivated account can no longer request certificate issuance or access
+// resources related to the account, such as orders or authorizations.
+//
+// It works only with RFC8555 compliant CAs.
+func (c *Client) DeactivateReg(ctx context.Context) error {
+	url := string(c.accountKID(ctx))
+	if url == "" {
+		return ErrNoAccount
+	}
+	req := json.RawMessage(`{"status": "deactivated"}`)
+	res, err := c.post(ctx, nil, url, req, wantStatus(http.StatusOK))
+	if err != nil {
+		return err
+	}
+	res.Body.Close()
+	return nil
+}
+
+// registerRFC is quivalent to c.Register but for RFC-compliant CAs.
+// It expects c.Discover to have already been called.
+// TODO: Implement externalAccountBinding.
+func (c *Client) registerRFC(ctx context.Context, acct *Account, prompt func(tosURL string) bool) (*Account, error) {
+	c.cacheMu.Lock() // guard c.kid access
+	defer c.cacheMu.Unlock()
+
+	req := struct {
+		TermsAgreed bool     `json:"termsOfServiceAgreed,omitempty"`
+		Contact     []string `json:"contact,omitempty"`
+	}{
+		Contact: acct.Contact,
+	}
+	if c.dir.Terms != "" {
+		req.TermsAgreed = prompt(c.dir.Terms)
+	}
+	res, err := c.post(ctx, c.Key, c.dir.RegURL, req, wantStatus(
+		http.StatusOK,      // account with this key already registered
+		http.StatusCreated, // new account created
+	))
+	if err != nil {
+		return nil, err
+	}
+
+	defer res.Body.Close()
+	a, err := responseAccount(res)
+	if err != nil {
+		return nil, err
+	}
+	// Cache Account URL even if we return an error to the caller.
+	// It is by all means a valid and usable "kid" value for future requests.
+	c.kid = keyID(a.URI)
+	if res.StatusCode == http.StatusOK {
+		return nil, ErrAccountAlreadyExists
+	}
+	return a, nil
+}
+
+// updateGegRFC is equivalent to c.UpdateReg but for RFC-compliant CAs.
+// It expects c.Discover to have already been called.
+func (c *Client) updateRegRFC(ctx context.Context, a *Account) (*Account, error) {
+	url := string(c.accountKID(ctx))
+	if url == "" {
+		return nil, ErrNoAccount
+	}
+	req := struct {
+		Contact []string `json:"contact,omitempty"`
+	}{
+		Contact: a.Contact,
+	}
+	res, err := c.post(ctx, nil, url, req, wantStatus(http.StatusOK))
+	if err != nil {
+		return nil, err
+	}
+	defer res.Body.Close()
+	return responseAccount(res)
+}
+
+// getGegRFC is equivalent to c.GetReg but for RFC-compliant CAs.
+// It expects c.Discover to have already been called.
+func (c *Client) getRegRFC(ctx context.Context) (*Account, error) {
+	req := json.RawMessage(`{"onlyReturnExisting": true}`)
+	res, err := c.post(ctx, c.Key, c.dir.RegURL, req, wantStatus(http.StatusOK))
+	if e, ok := err.(*Error); ok && e.ProblemType == "urn:ietf:params:acme:error:accountDoesNotExist" {
+		return nil, ErrNoAccount
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	defer res.Body.Close()
+	return responseAccount(res)
+}
+
+func responseAccount(res *http.Response) (*Account, error) {
+	var v struct {
+		Status  string
+		Contact []string
+		Orders  string
+	}
+	if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
+		return nil, fmt.Errorf("acme: invalid response: %v", err)
+	}
+	return &Account{
+		URI:       res.Header.Get("Location"),
+		Status:    v.Status,
+		Contact:   v.Contact,
+		OrdersURL: v.Orders,
+	}, nil
+}

acme/rfc8555_test.go

@@ -5,11 +5,17 @@
 package acme
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"fmt"
+	"io/ioutil"
 	"net/http"
 	"net/http/httptest"
+	"reflect"
+	"sync"
 	"testing"
+	"time"
 )
 
 // While contents of this file is pertinent only to RFC8555,
@@ -121,3 +127,350 @@ func TestRFC_popNonce(t *testing.T) {
 		t.Error("last cl.popNonce returned nil error")
 	}
 }
+
+func TestRFC_postKID(t *testing.T) {
+	var ts *httptest.Server
+	ts = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/new-nonce":
+			w.Header().Set("Replay-Nonce", "nonce")
+		case "/new-account":
+			w.Header().Set("Location", "/account-1")
+			w.Write([]byte(`{"status":"valid"}`))
+		case "/post":
+			b, _ := ioutil.ReadAll(r.Body) // check err later in decodeJWSxxx
+			head, err := decodeJWSHead(bytes.NewReader(b))
+			if err != nil {
+				t.Errorf("decodeJWSHead: %v", err)
+				return
+			}
+			if head.KID != "/account-1" {
+				t.Errorf("head.KID = %q; want /account-1", head.KID)
+			}
+			if len(head.JWK) != 0 {
+				t.Errorf("head.JWK = %q; want zero map", head.JWK)
+			}
+			if v := ts.URL + "/post"; head.URL != v {
+				t.Errorf("head.URL = %q; want %q", head.URL, v)
+			}
+
+			var payload struct{ Msg string }
+			decodeJWSRequest(t, &payload, bytes.NewReader(b))
+			if payload.Msg != "ping" {
+				t.Errorf("payload.Msg = %q; want ping", payload.Msg)
+			}
+			w.Write([]byte("pong"))
+		default:
+			t.Errorf("unhandled %s %s", r.Method, r.URL)
+			w.WriteHeader(http.StatusBadRequest)
+		}
+	}))
+	defer ts.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	cl := &Client{
+		Key:          testKey,
+		DirectoryURL: ts.URL,
+		dir: &Directory{
+			NonceURL: ts.URL + "/new-nonce",
+			RegURL:   ts.URL + "/new-account",
+			OrderURL: "/force-rfc-mode",
+		},
+	}
+	req := json.RawMessage(`{"msg":"ping"}`)
+	res, err := cl.post(ctx, nil /* use kid */, ts.URL+"/post", req, wantStatus(http.StatusOK))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	b, _ := ioutil.ReadAll(res.Body) // don't care about err - just checking b
+	if string(b) != "pong" {
+		t.Errorf("res.Body = %q; want pong", b)
+	}
+}
+
+// acmeServer simulates a subset of RFC8555 compliant CA.
+//
+// TODO: We also have x/crypto/acme/autocert/acmetest and startACMEServerStub in autocert_test.go.
+// It feels like this acmeServer is a sweet spot between usefulness and added complexity.
+// Also, acmetest and startACMEServerStub were both written for draft-02, no RFC support.
+// The goal is to consolidate all into one ACME test server.
+type acmeServer struct {
+	ts      *httptest.Server
+	handler map[string]http.HandlerFunc // keyed by r.URL.Path
+
+	mu     sync.Mutex
+	nnonce int
+}
+
+func newACMEServer() *acmeServer {
+	return &acmeServer{handler: make(map[string]http.HandlerFunc)}
+}
+
+func (s *acmeServer) handle(path string, f func(http.ResponseWriter, *http.Request)) {
+	s.handler[path] = http.HandlerFunc(f)
+}
+
+func (s *acmeServer) start() {
+	s.ts = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+
+		// Directory request.
+		if r.URL.Path == "/" {
+			fmt.Fprintf(w, `{
+				"newNonce": %q,
+				"newAccount": %q,
+				"newOrder": %q,
+				"newAuthz": %q,
+				"revokeCert": %q,
+				"meta": {"termsOfService": %q}
+				}`,
+				s.url("/acme/new-nonce"),
+				s.url("/acme/new-account"),
+				s.url("/acme/new-order"),
+				s.url("/acme/new-authz"),
+				s.url("/acme/revoke-cert"),
+				s.url("/terms"),
+			)
+			return
+		}
+
+		// All other responses contain a nonce value unconditionally.
+		w.Header().Set("Replay-Nonce", s.nonce())
+		if r.URL.Path == "/acme/new-nonce" {
+			return
+		}
+
+		h := s.handler[r.URL.Path]
+		if h == nil {
+			w.WriteHeader(http.StatusBadRequest)
+			fmt.Fprintf(w, "Unhandled %s", r.URL.Path)
+			return
+		}
+		h.ServeHTTP(w, r)
+	}))
+}
+
+func (s *acmeServer) close() {
+	s.ts.Close()
+}
+
+func (s *acmeServer) url(path string) string {
+	return s.ts.URL + path
+}
+
+func (s *acmeServer) nonce() string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.nnonce++
+	return fmt.Sprintf("nonce%d", s.nnonce)
+}
+
+func (s *acmeServer) error(w http.ResponseWriter, e *wireError) {
+	w.WriteHeader(e.Status)
+	json.NewEncoder(w).Encode(e)
+}
+
+func TestRFC_Register(t *testing.T) {
+	const email = "mailto:user@example.org"
+
+	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.StatusCreated) // 201 means new account created
+		fmt.Fprintf(w, `{
+			"status": "valid",
+			"contact": [%q],
+			"orders": %q
+		}`, email, s.url("/accounts/1/orders"))
+
+		b, _ := ioutil.ReadAll(r.Body) // check err later in decodeJWSxxx
+		head, err := decodeJWSHead(bytes.NewReader(b))
+		if err != nil {
+			t.Errorf("decodeJWSHead: %v", err)
+			return
+		}
+		if len(head.JWK) == 0 {
+			t.Error("head.JWK is empty")
+		}
+
+		var req struct{ Contact []string }
+		decodeJWSRequest(t, &req, bytes.NewReader(b))
+		if len(req.Contact) != 1 || req.Contact[0] != email {
+			t.Errorf("req.Contact = %q; want [%q]", req.Contact, email)
+		}
+	})
+	s.start()
+	defer s.close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	cl := &Client{
+		Key:          testKeyEC,
+		DirectoryURL: s.url("/"),
+	}
+
+	var didPrompt bool
+	a := &Account{Contact: []string{email}}
+	acct, err := cl.Register(ctx, a, func(tos string) bool {
+		didPrompt = true
+		terms := s.url("/terms")
+		if tos != terms {
+			t.Errorf("tos = %q; want %q", tos, terms)
+		}
+		return true
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	okAccount := &Account{
+		URI:       s.url("/accounts/1"),
+		Status:    StatusValid,
+		Contact:   []string{email},
+		OrdersURL: s.url("/accounts/1/orders"),
+	}
+	if !reflect.DeepEqual(acct, okAccount) {
+		t.Errorf("acct = %+v; want %+v", acct, okAccount)
+	}
+	if !didPrompt {
+		t.Error("tos prompt wasn't called")
+	}
+	if v := cl.accountKID(ctx); v != keyID(okAccount.URI) {
+		t.Errorf("account kid = %q; want %q", v, okAccount.URI)
+	}
+}
+
+func TestRFC_RegisterExisting(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) // 200 means account already exists
+		w.Write([]byte(`{"status": "valid"}`))
+	})
+	s.start()
+	defer s.close()
+
+	cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+	_, err := cl.Register(context.Background(), &Account{}, AcceptTOS)
+	if err != ErrAccountAlreadyExists {
+		t.Errorf("err = %v; want %v", err, ErrAccountAlreadyExists)
+	}
+	kid := keyID(s.url("/accounts/1"))
+	if v := cl.accountKID(context.Background()); v != kid {
+		t.Errorf("account kid = %q; want %q", v, kid)
+	}
+}
+
+func TestRFC_UpdateReg(t *testing.T) {
+	const email = "mailto:user@example.org"
+
+	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 didUpdate bool
+	s.handle("/accounts/1", func(w http.ResponseWriter, r *http.Request) {
+		didUpdate = true
+		w.Header().Set("Location", s.url("/accounts/1"))
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"status": "valid"}`))
+
+		b, _ := ioutil.ReadAll(r.Body) // check err later in decodeJWSxxx
+		head, err := decodeJWSHead(bytes.NewReader(b))
+		if err != nil {
+			t.Errorf("decodeJWSHead: %v", err)
+			return
+		}
+		if len(head.JWK) != 0 {
+			t.Error("head.JWK is non-zero")
+		}
+		kid := s.url("/accounts/1")
+		if head.KID != kid {
+			t.Errorf("head.KID = %q; want %q", head.KID, kid)
+		}
+
+		var req struct{ Contact []string }
+		decodeJWSRequest(t, &req, bytes.NewReader(b))
+		if len(req.Contact) != 1 || req.Contact[0] != email {
+			t.Errorf("req.Contact = %q; want [%q]", req.Contact, email)
+		}
+	})
+	s.start()
+	defer s.close()
+
+	cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+	_, err := cl.UpdateReg(context.Background(), &Account{Contact: []string{email}})
+	if err != nil {
+		t.Error(err)
+	}
+	if !didUpdate {
+		t.Error("UpdateReg didn't update the account")
+	}
+}
+
+func TestRFC_GetReg(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"}`))
+
+		head, err := decodeJWSHead(r.Body)
+		if err != nil {
+			t.Errorf("decodeJWSHead: %v", err)
+			return
+		}
+		if len(head.JWK) == 0 {
+			t.Error("head.JWK is empty")
+		}
+	})
+	s.start()
+	defer s.close()
+
+	cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+	acct, err := cl.GetReg(context.Background(), "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	okAccount := &Account{
+		URI:    s.url("/accounts/1"),
+		Status: StatusValid,
+	}
+	if !reflect.DeepEqual(acct, okAccount) {
+		t.Errorf("acct = %+v; want %+v", acct, okAccount)
+	}
+}
+
+func TestRFC_GetRegNoAccount(t *testing.T) {
+	s := newACMEServer()
+	s.handle("/acme/new-account", func(w http.ResponseWriter, r *http.Request) {
+		s.error(w, &wireError{
+			Status: http.StatusBadRequest,
+			Type:   "urn:ietf:params:acme:error:accountDoesNotExist",
+		})
+	})
+	s.start()
+	defer s.close()
+
+	cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+	if _, err := cl.GetReg(context.Background(), ""); err != ErrNoAccount {
+		t.Errorf("err = %v; want %v", err, ErrNoAccount)
+	}
+}
+
+func TestRFC_GetRegOtherError(t *testing.T) {
+	s := newACMEServer()
+	s.handle("/acme/new-account", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadRequest)
+	})
+	s.start()
+	defer s.close()
+
+	cl := &Client{Key: testKeyEC, DirectoryURL: s.url("/")}
+	if _, err := cl.GetReg(context.Background(), ""); err == nil || err == ErrNoAccount {
+		t.Errorf("GetReg: %v; want any other non-nil err", err)
+	}
+}

acme/types.go

@@ -16,12 +16,13 @@ import (
 
 // ACME server response statuses used to describe Authorization and Challenge states.
 const (
-	StatusUnknown    = "unknown"
-	StatusPending    = "pending"
-	StatusProcessing = "processing"
-	StatusValid      = "valid"
-	StatusInvalid    = "invalid"
-	StatusRevoked    = "revoked"
+	StatusDeactivated = "deactivated"
+	StatusInvalid     = "invalid"
+	StatusPending     = "pending"
+	StatusProcessing  = "processing"
+	StatusRevoked     = "revoked"
+	StatusUnknown     = "unknown"
+	StatusValid       = "valid"
 )
 
 // CRLReasonCode identifies the reason for a certificate revocation.
@@ -41,8 +42,17 @@ const (
 	CRLReasonAACompromise         CRLReasonCode = 10
 )
 
-// ErrUnsupportedKey is returned when an unsupported key type is encountered.
-var ErrUnsupportedKey = errors.New("acme: unknown key type; only RSA and ECDSA are supported")
+var (
+	// ErrUnsupportedKey is returned when an unsupported key type is encountered.
+	ErrUnsupportedKey = errors.New("acme: unknown key type; only RSA and ECDSA are supported")
+
+	// ErrAccountAlreadyExists indicates that the Client's key has already been registered
+	// with the CA. It is returned by Register method.
+	ErrAccountAlreadyExists = errors.New("acme: account already exists")
+
+	// ErrNoAccount indicates that the Client's key has not been registered with the CA.
+	ErrNoAccount = errors.New("acme: account does not exist")
+)
 
 // Error is an ACME error, defined in Problem Details for HTTP APIs doc
 // http://tools.ietf.org/html/draft-ietf-appsawg-http-problem.
@@ -54,6 +64,12 @@ type Error struct {
 	ProblemType string
 	// Detail is a human-readable explanation specific to this occurrence of the problem.
 	Detail string
+	// Instance indicates a URL that the client should direct a human user to visit
+	// in order for instructions on how to agree to the updated Terms of Service.
+	// In such an event CA sets StatusCode to 403, ProblemType to
+	// "urn:ietf:params:acme:error:userActionRequired" and a Link header with relation
+	// "terms-of-service" containing the latest TOS URL.
+	Instance string
 	// Header is the original server error response headers.
 	// It may be nil.
 	Header http.Header
@@ -108,31 +124,57 @@ func RateLimit(err error) (time.Duration, bool) {
 }
 
 // Account is a user account. It is associated with a private key.
+// Non-RFC8555 fields are empty when interfacing with a compliant CA.
 type Account struct {
 	// URI is the account unique ID, which is also a URL used to retrieve
 	// account data from the CA.
+	// When interfacing with RFC8555-compliant CAs, URI is the "kid" field
+	// value in JWS signed requests.
 	URI string
 
 	// Contact is a slice of contact info used during registration.
+	// See https://tools.ietf.org/html/rfc8555#section-7.3 for supported
+	// formats.
 	Contact []string
 
+	// Status indicates current account status as returned by the CA.
+	// Possible values are "valid", "deactivated", and "revoked".
+	Status string
+
+	// OrdersURL is a URL from which a list of orders submitted by this account
+	// can be fetched.
+	OrdersURL string
+
 	// The terms user has agreed to.
 	// A value not matching CurrentTerms indicates that the user hasn't agreed
 	// to the actual Terms of Service of the CA.
+	//
+	// It is non-RFC8555 compliant. Package users can store the ToS they agree to
+	// during Client's Register call in the prompt callback function.
 	AgreedTerms string
 
 	// Actual terms of a CA.
+	//
+	// It is non-RFC8555 compliant. Use Directory's Terms field.
+	// When a CA updates their terms and requires an account agreement,
+	// a URL at which instructions to do so is available in Error's Instance field.
 	CurrentTerms string
 
 	// Authz is the authorization URL used to initiate a new authz flow.
+	//
+	// It is non-RFC8555 compliant. Use Directory's AuthzURL or OrderURL.
 	Authz string
 
 	// Authorizations is a URI from which a list of authorizations
 	// granted to this account can be fetched via a GET request.
+	//
+	// It is non-RFC8555 compliant and is obsoleted by OrdersURL.
 	Authorizations string
 
 	// Certificates is a URI from which a list of certificates
 	// issued for this account can be fetched via a GET request.
+	//
+	// It is non-RFC8555 compliant and is obsoleted by OrdersURL.
 	Certificates string
 }
 
@@ -142,8 +184,8 @@ type Directory struct {
 	// NonceURL indicates an endpoint where to fetch fresh nonce values from.
 	NonceURL string
 
-	// RegURL is an account endpoint URL, allowing for creating new
-	// and modifying existing accounts.
+	// RegURL is an account endpoint URL, allowing for creating new accounts.
+	// Pre-RFC8555 CAs also allow modifying existing accounts at this URL.
 	RegURL string
 
 	// OrderURL is used to initiate the certificate issuance flow
@@ -299,9 +341,10 @@ func (c *wireChallenge) challenge() *Challenge {
 // wireError is a subset of fields of the Problem Details object
 // as described in https://tools.ietf.org/html/rfc7807#section-3.1.
 type wireError struct {
-	Status int
-	Type   string
-	Detail string
+	Status   int
+	Type     string
+	Detail   string
+	Instance string
 }
 
 func (e *wireError) error(h http.Header) *Error {
@@ -309,6 +352,7 @@ func (e *wireError) error(h http.Header) *Error {
 		StatusCode:  e.Status,
 		ProblemType: e.Type,
 		Detail:      e.Detail,
+		Instance:    e.Instance,
 		Header:      h,
 	}
 }