mirror of https://github.com/tailscale/tailscale/
types/key: add a special key with custom serialization for control private keys (#2792)
* Revert "Revert "types/key: add MachinePrivate and MachinePublic.""
This reverts commit 61c3b98a24.
Signed-off-by: David Anderson <danderson@tailscale.com>
* types/key: add ControlPrivate, with custom serialization.
ControlPrivate is just a MachinePrivate that serializes differently
in JSON, to be compatible with how the Tailscale control plane
historically serialized its private key.
Signed-off-by: David Anderson <danderson@tailscale.com>
pull/2795/head
Dave Anderson
3 years ago
committed by
GitHub
parent
61c3b98a24
commit
980acc38ba
@ -0,0 +1,64 @@
|
||||
// Copyright (c) 2021 Tailscale Inc & 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 key
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// ControlPrivate is a Tailscale control plane private key.
|
||||
//
|
||||
// It is functionally equivalent to a MachinePrivate, but serializes
|
||||
// to JSON as a byte array rather than a typed string, because our
|
||||
// control plane database stores the key that way.
|
||||
//
|
||||
// Deprecated: this type should only be used in Tailscale's control
|
||||
// plane, where existing database serializations require this
|
||||
// less-good serialization format to persist. Other control plane
|
||||
// implementations can use MachinePrivate with no downsides.
|
||||
type ControlPrivate struct {
|
||||
mkey MachinePrivate // unexported so we can limit the API surface to only exactly what we need
|
||||
}
|
||||
|
||||
// NewControl generates and returns a new control plane private key.
|
||||
func NewControl() ControlPrivate {
|
||||
return ControlPrivate{NewMachine()}
|
||||
}
|
||||
|
||||
// IsZero reports whether k is the zero value.
|
||||
func (k ControlPrivate) IsZero() bool {
|
||||
return k.mkey.IsZero()
|
||||
}
|
||||
|
||||
// Public returns the MachinePublic for k.
|
||||
// Panics if ControlPrivate is zero.
|
||||
func (k ControlPrivate) Public() MachinePublic {
|
||||
return k.mkey.Public()
|
||||
}
|
||||
|
||||
// MarshalJSON implements json.Marshaler.
|
||||
func (k ControlPrivate) MarshalJSON() ([]byte, error) {
|
||||
return json.Marshal(k.mkey.k)
|
||||
}
|
||||
|
||||
// UnmarshalJSON implements json.Unmarshaler.
|
||||
func (k *ControlPrivate) UnmarshalJSON(bs []byte) error {
|
||||
return json.Unmarshal(bs, &k.mkey.k)
|
||||
}
|
||||
|
||||
// SealTo wraps cleartext into a NaCl box (see
|
||||
// golang.org/x/crypto/nacl) to p, authenticated from k, using a
|
||||
// random nonce.
|
||||
//
|
||||
// The returned ciphertext is a 24-byte nonce concatenated with the
|
||||
// box value.
|
||||
func (k ControlPrivate) SealTo(p MachinePublic, cleartext []byte) (ciphertext []byte) {
|
||||
return k.mkey.SealTo(p, cleartext)
|
||||
}
|
||||
|
||||
// OpenFrom opens the NaCl box ciphertext, which must be a value
|
||||
// created by SealTo, and returns the inner cleartext if ciphertext is
|
||||
// a valid box from p to k.
|
||||
func (k ControlPrivate) OpenFrom(p MachinePublic, ciphertext []byte) (cleartext []byte, ok bool) {
|
||||
return k.mkey.OpenFrom(p, ciphertext)
|
||||
}
|
||||
@ -0,0 +1,39 @@
|
||||
// Copyright (c) 2021 Tailscale Inc & 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 key
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestControlKey(t *testing.T) {
|
||||
serialized := `{"PrivateKey":[36,132,249,6,73,141,249,49,9,96,49,60,240,217,253,57,3,69,248,64,178,62,121,73,121,88,115,218,130,145,68,254]}`
|
||||
want := ControlPrivate{
|
||||
MachinePrivate{
|
||||
k: [32]byte{36, 132, 249, 6, 73, 141, 249, 49, 9, 96, 49, 60, 240, 217, 253, 57, 3, 69, 248, 64, 178, 62, 121, 73, 121, 88, 115, 218, 130, 145, 68, 254},
|
||||
},
|
||||
}
|
||||
|
||||
var got struct {
|
||||
PrivateKey ControlPrivate
|
||||
}
|
||||
if err := json.Unmarshal([]byte(serialized), &got); err != nil {
|
||||
t.Fatalf("decoding serialized ControlPrivate: %v", err)
|
||||
}
|
||||
|
||||
if !got.PrivateKey.mkey.Equal(want.mkey) {
|
||||
t.Fatalf("Serialized ControlPrivate didn't deserialize as expected, got %v want %v", got.PrivateKey, want)
|
||||
}
|
||||
|
||||
bs, err := json.Marshal(got)
|
||||
if err != nil {
|
||||
t.Fatalf("json reserialization of ControlPrivate failed: %v", err)
|
||||
}
|
||||
|
||||
if got, want := string(bs), serialized; got != want {
|
||||
t.Fatalf("ControlPrivate didn't round-trip, got %q want %q", got, want)
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,173 @@
|
||||
// Copyright (c) 2021 Tailscale Inc & 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 key
|
||||
|
||||
import (
|
||||
"crypto/subtle"
|
||||
"encoding/hex"
|
||||
|
||||
"go4.org/mem"
|
||||
"golang.org/x/crypto/curve25519"
|
||||
"golang.org/x/crypto/nacl/box"
|
||||
"tailscale.com/types/structs"
|
||||
)
|
||||
|
||||
const (
|
||||
// machinePrivateHexPrefix is the prefix used to identify a
|
||||
// hex-encoded machine private key.
|
||||
//
|
||||
// This prefix name is a little unfortunate, in that it comes from
|
||||
// WireGuard's own key types. Unfortunately we're stuck with it for
|
||||
// machine keys, because we serialize them to disk with this prefix.
|
||||
machinePrivateHexPrefix = "privkey:"
|
||||
|
||||
// machinePublicHexPrefix is the prefix used to identify a
|
||||
// hex-encoded machine public key.
|
||||
//
|
||||
// This prefix is used in the control protocol, so cannot be
|
||||
// changed.
|
||||
machinePublicHexPrefix = "mkey:"
|
||||
)
|
||||
|
||||
// MachinePrivate is a machine key, used for communication with the
|
||||
// Tailscale coordination server.
|
||||
type MachinePrivate struct {
|
||||
_ structs.Incomparable // == isn't constant-time
|
||||
k [32]byte
|
||||
}
|
||||
|
||||
// NewMachine creates and returns a new machine private key.
|
||||
func NewMachine() MachinePrivate {
|
||||
var ret MachinePrivate
|
||||
rand(ret.k[:])
|
||||
clamp25519Private(ret.k[:])
|
||||
return ret
|
||||
}
|
||||
|
||||
// IsZero reports whether k is the zero value.
|
||||
func (k MachinePrivate) IsZero() bool {
|
||||
return k.Equal(MachinePrivate{})
|
||||
}
|
||||
|
||||
// Equal reports whether k and other are the same key.
|
||||
func (k MachinePrivate) Equal(other MachinePrivate) bool {
|
||||
return subtle.ConstantTimeCompare(k.k[:], other.k[:]) == 1
|
||||
}
|
||||
|
||||
// Public returns the MachinePublic for k.
|
||||
// Panics if MachinePrivate is zero.
|
||||
func (k MachinePrivate) Public() MachinePublic {
|
||||
if k.IsZero() {
|
||||
panic("can't take the public key of a zero MachinePrivate")
|
||||
}
|
||||
var ret MachinePublic
|
||||
curve25519.ScalarBaseMult(&ret.k, &k.k)
|
||||
return ret
|
||||
}
|
||||
|
||||
// MarshalText implements encoding.TextMarshaler.
|
||||
func (k MachinePrivate) MarshalText() ([]byte, error) {
|
||||
return toHex(k.k[:], machinePrivateHexPrefix), nil
|
||||
}
|
||||
|
||||
// MarshalText implements encoding.TextUnmarshaler.
|
||||
func (k *MachinePrivate) UnmarshalText(b []byte) error {
|
||||
return parseHex(k.k[:], mem.B(b), mem.S(machinePrivateHexPrefix))
|
||||
}
|
||||
|
||||
// SealTo wraps cleartext into a NaCl box (see
|
||||
// golang.org/x/crypto/nacl) to p, authenticated from k, using a
|
||||
// random nonce.
|
||||
//
|
||||
// The returned ciphertext is a 24-byte nonce concatenated with the
|
||||
// box value.
|
||||
func (k MachinePrivate) SealTo(p MachinePublic, cleartext []byte) (ciphertext []byte) {
|
||||
if k.IsZero() || p.IsZero() {
|
||||
panic("can't seal with zero keys")
|
||||
}
|
||||
var nonce [24]byte
|
||||
rand(nonce[:])
|
||||
return box.Seal(nonce[:], cleartext, &nonce, &p.k, &k.k)
|
||||
}
|
||||
|
||||
// OpenFrom opens the NaCl box ciphertext, which must be a value
|
||||
// created by SealTo, and returns the inner cleartext if ciphertext is
|
||||
// a valid box from p to k.
|
||||
func (k MachinePrivate) OpenFrom(p MachinePublic, ciphertext []byte) (cleartext []byte, ok bool) {
|
||||
if k.IsZero() || p.IsZero() {
|
||||
panic("can't open with zero keys")
|
||||
}
|
||||
if len(ciphertext) < 24 {
|
||||
return nil, false
|
||||
}
|
||||
var nonce [24]byte
|
||||
copy(nonce[:], ciphertext)
|
||||
return box.Open(nil, ciphertext[len(nonce):], &nonce, &p.k, &k.k)
|
||||
}
|
||||
|
||||
// MachinePublic is the public portion of a a MachinePrivate.
|
||||
type MachinePublic struct {
|
||||
k [32]byte
|
||||
}
|
||||
|
||||
// ParseMachinePublicUntyped parses an untyped 64-character hex value
|
||||
// as a MachinePublic.
|
||||
//
|
||||
// Deprecated: this function is risky to use, because it cannot verify
|
||||
// that the hex string was intended to be a MachinePublic. This can
|
||||
// lead to accidentally decoding one type of key as another. For new
|
||||
// uses that don't require backwards compatibility with the untyped
|
||||
// string format, please use MarshalText/UnmarshalText.
|
||||
func ParseMachinePublicUntyped(raw mem.RO) (MachinePublic, error) {
|
||||
var ret MachinePublic
|
||||
if err := parseHex(ret.k[:], raw, mem.B(nil)); err != nil {
|
||||
return MachinePublic{}, err
|
||||
}
|
||||
return ret, nil
|
||||
}
|
||||
|
||||
// IsZero reports whether k is the zero value.
|
||||
func (k MachinePublic) IsZero() bool {
|
||||
return k == MachinePublic{}
|
||||
}
|
||||
|
||||
// ShortString returns the Tailscale conventional debug representation
|
||||
// of a public key: the first five base64 digits of the key, in square
|
||||
// brackets.
|
||||
func (k MachinePublic) ShortString() string {
|
||||
return debug32(k.k)
|
||||
}
|
||||
|
||||
// UntypedHexString returns k, encoded as an untyped 64-character hex
|
||||
// string.
|
||||
//
|
||||
// Deprecated: this function is risky to use, because it produces
|
||||
// serialized values that do not identify themselves as a
|
||||
// MachinePublic, allowing other code to potentially parse it back in
|
||||
// as the wrong key type. For new uses that don't require backwards
|
||||
// compatibility with the untyped string format, please use
|
||||
// MarshalText/UnmarshalText.
|
||||
func (k MachinePublic) UntypedHexString() string {
|
||||
return hex.EncodeToString(k.k[:])
|
||||
}
|
||||
|
||||
// String returns the output of MarshalText as a string.
|
||||
func (k MachinePublic) String() string {
|
||||
bs, err := k.MarshalText()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
return string(bs)
|
||||
}
|
||||
|
||||
// MarshalText implements encoding.TextMarshaler.
|
||||
func (k MachinePublic) MarshalText() ([]byte, error) {
|
||||
return toHex(k.k[:], machinePublicHexPrefix), nil
|
||||
}
|
||||
|
||||
// MarshalText implements encoding.TextUnmarshaler.
|
||||
func (k *MachinePublic) UnmarshalText(b []byte) error {
|
||||
return parseHex(k.k[:], mem.B(b), mem.S(machinePublicHexPrefix))
|
||||
}
|
||||
@ -0,0 +1,92 @@
|
||||
// Copyright (c) 2021 Tailscale Inc & 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 key
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestMachineKey(t *testing.T) {
|
||||
k := NewMachine()
|
||||
if k.IsZero() {
|
||||
t.Fatal("MachinePrivate should not be zero")
|
||||
}
|
||||
|
||||
p := k.Public()
|
||||
if p.IsZero() {
|
||||
t.Fatal("MachinePublic should not be zero")
|
||||
}
|
||||
|
||||
bs, err := p.MarshalText()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if full, got := string(bs), ":"+p.UntypedHexString(); !strings.HasSuffix(full, got) {
|
||||
t.Fatalf("MachinePublic.UntypedHexString is not a suffix of the typed serialization, got %q want suffix of %q", got, full)
|
||||
}
|
||||
|
||||
z := MachinePublic{}
|
||||
if !z.IsZero() {
|
||||
t.Fatal("IsZero(MachinePublic{}) is false")
|
||||
}
|
||||
if s := z.ShortString(); s != "" {
|
||||
t.Fatalf("MachinePublic{}.ShortString() is %q, want \"\"", s)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMachineSerialization(t *testing.T) {
|
||||
serialized := `{
|
||||
"Priv": "privkey:40ab1b58e9076c7a4d9d07291f5edf9d1aa017eb949624ba683317f48a640369",
|
||||
"Pub":"mkey:50d20b455ecf12bc453f83c2cfdb2a24925d06cf2598dcaa54e91af82ce9f765"
|
||||
}`
|
||||
|
||||
// Carefully check that the expected serialized data decodes and
|
||||
// reencodes to the expected keys. These types are serialized to
|
||||
// disk all over the place and need to be stable.
|
||||
priv := MachinePrivate{
|
||||
k: [32]uint8{
|
||||
0x40, 0xab, 0x1b, 0x58, 0xe9, 0x7, 0x6c, 0x7a, 0x4d, 0x9d, 0x7,
|
||||
0x29, 0x1f, 0x5e, 0xdf, 0x9d, 0x1a, 0xa0, 0x17, 0xeb, 0x94,
|
||||
0x96, 0x24, 0xba, 0x68, 0x33, 0x17, 0xf4, 0x8a, 0x64, 0x3, 0x69,
|
||||
},
|
||||
}
|
||||
pub := MachinePublic{
|
||||
k: [32]uint8{
|
||||
0x50, 0xd2, 0xb, 0x45, 0x5e, 0xcf, 0x12, 0xbc, 0x45, 0x3f, 0x83,
|
||||
0xc2, 0xcf, 0xdb, 0x2a, 0x24, 0x92, 0x5d, 0x6, 0xcf, 0x25, 0x98,
|
||||
0xdc, 0xaa, 0x54, 0xe9, 0x1a, 0xf8, 0x2c, 0xe9, 0xf7, 0x65,
|
||||
},
|
||||
}
|
||||
|
||||
type keypair struct {
|
||||
Priv MachinePrivate
|
||||
Pub MachinePublic
|
||||
}
|
||||
|
||||
var a keypair
|
||||
if err := json.Unmarshal([]byte(serialized), &a); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !a.Priv.Equal(priv) {
|
||||
t.Errorf("wrong deserialization of private key, got %#v want %#v", a.Priv, priv)
|
||||
}
|
||||
if a.Pub != pub {
|
||||
t.Errorf("wrong deserialization of public key, got %#v want %#v", a.Pub, pub)
|
||||
}
|
||||
|
||||
bs, err := json.MarshalIndent(a, "", " ")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
var b bytes.Buffer
|
||||
json.Indent(&b, []byte(serialized), "", " ")
|
||||
if got, want := string(bs), b.String(); got != want {
|
||||
t.Error("json serialization doesn't roundtrip")
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,111 @@
|
||||
// Copyright (c) 2021 Tailscale Inc & 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 key
|
||||
|
||||
import (
|
||||
crand "crypto/rand"
|
||||
"encoding/base64"
|
||||
"encoding/hex"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
|
||||
"go4.org/mem"
|
||||
)
|
||||
|
||||
// rand fills b with cryptographically strong random bytes. Panics if
|
||||
// no random bytes are available.
|
||||
func rand(b []byte) {
|
||||
if _, err := io.ReadFull(crand.Reader, b[:]); err != nil {
|
||||
panic(fmt.Sprintf("unable to read random bytes from OS: %v", err))
|
||||
}
|
||||
}
|
||||
|
||||
// clamp25519 clamps b, which must be a 32-byte Curve25519 private
|
||||
// key, to a safe value.
|
||||
//
|
||||
// The clamping effectively constrains the key to a number between
|
||||
// 2^251 and 2^252-1, which is then multiplied by 8 (the cofactor of
|
||||
// Curve25519). This produces a value that doesn't have any unsafe
|
||||
// properties when doing operations like ScalarMult.
|
||||
//
|
||||
// See
|
||||
// https://web.archive.org/web/20210228105330/https://neilmadden.blog/2020/05/28/whats-the-curve25519-clamping-all-about/
|
||||
// for a more in-depth explanation of the constraints that led to this
|
||||
// clamping requirement.
|
||||
//
|
||||
// PLEASE NOTE that not all Curve25519 values require clamping. When
|
||||
// implementing a new key type that uses Curve25519, you must evaluate
|
||||
// whether that particular key's use requires clamping. Here are some
|
||||
// existing uses and whether you should clamp private keys at
|
||||
// creation.
|
||||
//
|
||||
// - NaCl box: yes, clamp at creation.
|
||||
// - WireGuard (userspace uapi or kernel): no, do not clamp.
|
||||
// - Noise protocols: no, do not clamp.
|
||||
func clamp25519Private(b []byte) {
|
||||
b[0] &= 248
|
||||
b[31] = (b[31] & 127) | 64
|
||||
}
|
||||
|
||||
func toHex(k []byte, prefix string) []byte {
|
||||
ret := make([]byte, len(prefix)+len(k)*2)
|
||||
copy(ret, prefix)
|
||||
hex.Encode(ret[len(prefix):], k)
|
||||
return ret
|
||||
}
|
||||
|
||||
// parseHex decodes a key string of the form "<prefix><hex string>"
|
||||
// into out. The prefix must match, and the decoded base64 must fit
|
||||
// exactly into out.
|
||||
//
|
||||
// Note the errors in this function deliberately do not echo the
|
||||
// contents of in, because it might be a private key or part of a
|
||||
// private key.
|
||||
func parseHex(out []byte, in, prefix mem.RO) error {
|
||||
if !mem.HasPrefix(in, prefix) {
|
||||
return fmt.Errorf("key hex string doesn't have expected type prefix %s", prefix.StringCopy())
|
||||
}
|
||||
in = in.SliceFrom(prefix.Len())
|
||||
if want := len(out) * 2; in.Len() != want {
|
||||
return fmt.Errorf("key hex has the wrong size, got %d want %d", in.Len(), want)
|
||||
}
|
||||
for i := range out {
|
||||
a, ok1 := fromHexChar(in.At(i*2 + 0))
|
||||
b, ok2 := fromHexChar(in.At(i*2 + 1))
|
||||
if !ok1 || !ok2 {
|
||||
return errors.New("invalid hex character in key")
|
||||
}
|
||||
out[i] = (a << 4) | b
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// fromHexChar converts a hex character into its value and a success flag.
|
||||
func fromHexChar(c byte) (byte, bool) {
|
||||
switch {
|
||||
case '0' <= c && c <= '9':
|
||||
return c - '0', true
|
||||
case 'a' <= c && c <= 'f':
|
||||
return c - 'a' + 10, true
|
||||
case 'A' <= c && c <= 'F':
|
||||
return c - 'A' + 10, true
|
||||
}
|
||||
|
||||
return 0, false
|
||||
}
|
||||
|
||||
// debug32 returns the Tailscale conventional debug representation of
|
||||
// a key: the first five base64 digits of the key, in square brackets.
|
||||
func debug32(k [32]byte) string {
|
||||
if k == [32]byte{} {
|
||||
return ""
|
||||
}
|
||||
var b [45]byte // 32 bytes expands to 44 bytes in base64, plus 1 for the leading '['
|
||||
base64.StdEncoding.Encode(b[1:], k[:])
|
||||
b[0] = '['
|
||||
b[6] = ']'
|
||||
return string(b[:7])
|
||||
}
|
||||
@ -0,0 +1,38 @@
|
||||
// Copyright (c) 2021 Tailscale Inc & 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 key
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestRand(t *testing.T) {
|
||||
var bs [32]byte
|
||||
rand(bs[:])
|
||||
if bs == [32]byte{} {
|
||||
t.Fatal("rand didn't provide randomness")
|
||||
}
|
||||
var bs2 [32]byte
|
||||
rand(bs2[:])
|
||||
if bytes.Equal(bs[:], bs2[:]) {
|
||||
t.Fatal("rand returned the same data twice")
|
||||
}
|
||||
}
|
||||
|
||||
func TestClamp25519Private(t *testing.T) {
|
||||
for i := 0; i < 100; i++ {
|
||||
var k [32]byte
|
||||
rand(k[:])
|
||||
clamp25519Private(k[:])
|
||||
if k[0]&0b111 != 0 {
|
||||
t.Fatalf("Bogus clamping in first byte: %#08b", k[0])
|
||||
return
|
||||
}
|
||||
if k[31]>>6 != 1 {
|
||||
t.Fatalf("Bogus clamping in last byte: %#08b", k[0])
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue