add detailed error message s3 checksum mismatch

Have the s3 RemoteClient return a detailed error message to the user in
the case of a mismatch state checksum.

backend/remote-state/s3/client.go

@@ -42,9 +42,6 @@ var (
 
 	// delay when polling the state
 	consistencyRetryPollInterval = 2 * time.Second
-
-	// checksum didn't match the remote state
-	errBadChecksum = errors.New("invalid state checksum")
 )
 
 // test hook called when checksums don't match
@@ -77,7 +74,7 @@ func (c *RemoteClient) Get() (payload *remote.Payload, err error) {
 				continue
 			}
 
-			return nil, errBadChecksum
+			return nil, fmt.Errorf(errBadChecksumFmt, payload.MD5)
 		}
 
 		break
@@ -369,3 +366,12 @@ func (c *RemoteClient) Unlock(id string) error {
 func (c *RemoteClient) lockPath() string {
 	return fmt.Sprintf("%s/%s", c.bucketName, c.path)
 }
+
+const errBadChecksumFmt = `state data in S3 does not have the expected content.
+
+This may be caused by unusually long delays in S3 processing a previous state
+update.  Please wait for a minute or two and try again. If this problem
+persists, and neither S3 nor DynamoDB are experiencing an outage, you may need
+to manually verify the remote state and update the Digest value stored in the
+DynamoDB table to the following value: %x
+`

backend/remote-state/s3/client_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"crypto/md5"
 	"fmt"
+	"strings"
 	"testing"
 	"time"
 
@@ -204,7 +205,7 @@ func TestRemoteClient_stateChecksum(t *testing.T) {
 
 	// fetching the state through client1 should now error out due to a
 	// mismatched checksum.
-	if _, err := client1.Get(); err != errBadChecksum {
+	if _, err := client1.Get(); !strings.HasPrefix(err.Error(), errBadChecksumFmt[:80]) {
 		t.Fatalf("expected state checksum error: got %s", err)
 	}