nacl/auth: add crypto_auth primitive

This matches the implementation in NaCL, so a user can generate
a crypto_auth digest in another language and verify it with Go, or
vice versa.

Fixes golang/go#20265.

Change-Id: Ice96abb9347a5318a16ced5152ebfa7d9ebdd285
Reviewed-on: https://go-review.googlesource.com/51932
Reviewed-by: Adam Langley <agl@golang.org>
Run-TryBot: Adam Langley <agl@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

nacl/auth/example_test.go

@@ -0,0 +1,36 @@
+// Copyright 2017 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 auth_test
+
+import (
+	"encoding/hex"
+	"fmt"
+
+	"golang.org/x/crypto/nacl/auth"
+)
+
+func Example() {
+	// Load your secret key from a safe place and reuse it across multiple
+	// Sum calls. (Obviously don't use this example key for anything
+	// real.) If you want to convert a passphrase to a key, use a suitable
+	// package like bcrypt or scrypt.
+	secretKeyBytes, err := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
+	if err != nil {
+		panic(err)
+	}
+
+	var secretKey [32]byte
+	copy(secretKey[:], secretKeyBytes)
+
+	mac := auth.Sum([]byte("hello world"), &secretKey)
+	fmt.Printf("%x\n", *mac)
+	result := auth.Verify(mac[:], []byte("hello world"), &secretKey)
+	fmt.Println(result)
+	badResult := auth.Verify(mac[:], []byte("different message"), &secretKey)
+	fmt.Println(badResult)
+	// Output: eca5a521f3d77b63f567fb0cb6f5f2d200641bc8dada42f60c5f881260c30317
+	// true
+	// false
+}