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>
main
Dave Anderson
5 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