acme/autocert: update Manager.Client and Cache docs

Fixes golang/go#22064 Change-Id: Icb3f5b2c1967630a3dcbd9661b3492f5d3acc654 Reviewed-on: https://go-review.googlesource.com/115937 Reviewed-by: Alex Vaghin <ddos@google.com>
2018-06-06 00:37:54 +00:00
parent 8f8078c97f
commit 78e79280f6
3 changed files with 26 additions and 68 deletions
@@ -98,8 +98,9 @@ type Manager struct {
 	// To always accept the terms, the callers can use AcceptTOS.
 	Prompt func(tosURL string) bool

-	// Cache optionally stores and retrieves previously-obtained certificates.
-	// If nil, certs will only be cached for the lifetime of the Manager.
+	// Cache optionally stores and retrieves previously-obtained certificates
+	// and other state. If nil, certs will only be cached for the lifetime of
+	// the Manager. Multiple Managers can share the same Cache.
 	//
 	// Using a persistent Cache, such as DirCache, is strongly recommended.
 	Cache Cache
@@ -126,8 +127,10 @@ type Manager struct {

 	// Client is used to perform low-level operations, such as account registration
 	// and requesting new certificates.
+	//
 	// If Client is nil, a zero-value acme.Client is used with acme.LetsEncryptURL
-	// directory endpoint and a newly-generated ECDSA P-256 key.
+	// as directory endpoint. If the Client.Key is nil, a new ECDSA P-256 key is
+	// generated and, if Cache is not nil, stored in cache.
 	//
 	// Mutating the field after the first call of GetCertificate method will have no effect.
 	Client *acme.Client
@@ -232,14 +232,7 @@ func TestGetCertificate_nilPrompt(t *testing.T) {
 	defer man.stopRenew()
 	url, finish := startACMEServerStub(t, getCertificateFromManager(man, true), "example.org")
 	defer finish()
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	man.Client = &acme.Client{
-		Key:          key,
-		DirectoryURL: url,
-	}
+	man.Client = &acme.Client{DirectoryURL: url}
 	hello := clientHelloInfo("example.org", true)
 	if _, err := man.GetCertificate(hello); err == nil {
 		t.Error("got certificate for example.org; wanted error")
@@ -299,14 +292,9 @@ func TestGetCertificate_failedAttempt(t *testing.T) {
 		close(done)
 	}

-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
 	man := &Manager{
 		Prompt: AcceptTOS,
 		Client: &acme.Client{
-			Key:          key,
 			DirectoryURL: ts.URL,
 		},
 	}
@@ -346,14 +334,7 @@ func testGetCertificate_tokenCache(t *testing.T, ecdsaSupport bool) {
 	// initiated the authorization, when they share caches.
 	url, finish := startACMEServerStub(t, getCertificateFromManager(man2, ecdsaSupport), "example.org")
 	defer finish()
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	man1.Client = &acme.Client{
-		Key:          key,
-		DirectoryURL: url,
-	}
+	man1.Client = &acme.Client{DirectoryURL: url}
 	hello := clientHelloInfo("example.org", true)
 	if _, err := man1.GetCertificate(hello); err != nil {
 		t.Error(err)
@@ -378,14 +359,7 @@ func TestGetCertificate_ecdsaVsRSA(t *testing.T) {
 	defer man.stopRenew()
 	url, finish := startACMEServerStub(t, getCertificateFromManager(man, true), "example.org")
 	defer finish()
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	man.Client = &acme.Client{
-		Key:          key,
-		DirectoryURL: url,
-	}
+	man.Client = &acme.Client{DirectoryURL: url}

 	cert, err := man.GetCertificate(clientHelloInfo("example.org", true))
 	if err != nil {
@@ -420,14 +394,7 @@ func TestGetCertificate_wrongCacheKeyType(t *testing.T) {
 	defer man.stopRenew()
 	url, finish := startACMEServerStub(t, getCertificateFromManager(man, true), exampleDomain)
 	defer finish()
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	man.Client = &acme.Client{
-		Key:          key,
-		DirectoryURL: url,
-	}
+	man.Client = &acme.Client{DirectoryURL: url}

 	// Make an RSA cert and cache it without suffix.
 	pk, err := rsa.GenerateKey(rand.Reader, 512)
@@ -586,19 +553,11 @@ func startACMEServerStub(t *testing.T, getCertificate func(string) error, domain
 func testGetCertificate(t *testing.T, man *Manager, domain string, hello *tls.ClientHelloInfo) {
 	url, finish := startACMEServerStub(t, getCertificateFromManager(man, true), domain)
 	defer finish()
-
-	// use EC key to run faster on 386
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	man.Client = &acme.Client{
-		Key:          key,
-		DirectoryURL: url,
-	}
+	man.Client = &acme.Client{DirectoryURL: url}

 	// simulate tls.Config.GetCertificate
 	var tlscert *tls.Certificate
+	var err error
 	done := make(chan struct{})
 	go func() {
 		tlscert, err = man.GetCertificate(hello)
@@ -702,18 +661,18 @@ func TestVerifyHTTP01(t *testing.T) {
 	}))
 	defer ca.Close()

-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
 	m := &Manager{
 		Client: &acme.Client{
-			Key:          key,
 			DirectoryURL: ca.URL,
 		},
 	}
 	http01 = m.HTTPHandler(nil)
-	if err := m.verify(context.Background(), m.Client, "example.org"); err != nil {
+	ctx := context.Background()
+	client, err := m.acmeClient(ctx)
+	if err != nil {
+		t.Fatalf("m.acmeClient: %v", err)
+	}
+	if err := m.verify(ctx, client, "example.org"); err != nil {
 		t.Errorf("m.verify: %v", err)
 	}
 	// Only tls-sni-01, tls-sni-02 and http-01 must be accepted
@@ -103,23 +103,21 @@ func TestRenewFromCache(t *testing.T) {
 	}))
 	defer ca.Close()

-	// use EC key to run faster on 386
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
 	man := &Manager{
 		Prompt:      AcceptTOS,
 		Cache:       newMemCache(t),
 		RenewBefore: 24 * time.Hour,
 		Client: &acme.Client{
-			Key:          key,
 			DirectoryURL: ca.URL,
 		},
 	}
 	defer man.stopRenew()

 	// cache an almost expired cert
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
 	now := time.Now()
 	cert, err := dateDummyCert(key.Public(), now.Add(-2*time.Hour), now.Add(time.Minute), exampleDomain)
 	if err != nil {
@@ -189,17 +187,11 @@ func TestRenewFromCache(t *testing.T) {
 }

 func TestRenewFromCacheAlreadyRenewed(t *testing.T) {
-	// use EC key to run faster on 386
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
 	man := &Manager{
 		Prompt:      AcceptTOS,
 		Cache:       newMemCache(t),
 		RenewBefore: 24 * time.Hour,
 		Client: &acme.Client{
-			Key:          key,
 			DirectoryURL: "invalid",
 		},
 	}
@@ -225,6 +217,10 @@ func TestRenewFromCacheAlreadyRenewed(t *testing.T) {
 	}

 	// set internal state to an almost expired cert
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
 	oldCert, err := dateDummyCert(key.Public(), now.Add(-2*time.Hour), now.Add(time.Minute), exampleDomain)
 	if err != nil {
 		t.Fatal(err)