github.com/core-coin/go-core/v2@v2.1.9/p2p/enr/enr.go (about)

     1  // Copyright 2017 by the Authors
     2  // This file is part of the go-core library.
     3  //
     4  // The go-core library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The go-core library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the go-core library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  // Package enr implements Core Node Records as defined in CIP-778. A node record holds
    18  // arbitrary information about a node on the peer-to-peer network. Node information is
    19  // stored in key/value pairs. To store and retrieve key/values in a record, use the Entry
    20  // interface.
    21  //
    22  // # Signature Handling
    23  //
    24  // Records must be signed before transmitting them to another node.
    25  //
    26  // Decoding a record doesn't check its signature. Code working with records from an
    27  // untrusted source must always verify two things: that the record uses an identity scheme
    28  // deemed secure, and that the signature is valid according to the declared scheme.
    29  //
    30  // When creating a record, set the entries you want and use a signing function provided by
    31  // the identity scheme to add the signature. Modifying a record invalidates the signature.
    32  //
    33  // Package enr supports the "ed448-keccak" identity scheme.
    34  package enr
    35  
    36  import (
    37  	"bytes"
    38  	"errors"
    39  	"fmt"
    40  	"io"
    41  	"sort"
    42  
    43  	"github.com/core-coin/go-core/v2/rlp"
    44  )
    45  
    46  const SizeLimit = 600 // maximum encoded size of a node record in bytes
    47  
    48  var (
    49  	ErrInvalidSig     = errors.New("invalid signature on node record")
    50  	errNotSorted      = errors.New("record key/value pairs are not sorted by key")
    51  	errDuplicateKey   = errors.New("record contains duplicate key")
    52  	errIncompletePair = errors.New("record contains incomplete k/v pair")
    53  	errTooBig         = fmt.Errorf("record bigger than %d bytes", SizeLimit)
    54  	errEncodeUnsigned = errors.New("can't encode unsigned record")
    55  	errNotFound       = errors.New("no such key in record")
    56  )
    57  
    58  // An IdentityScheme is capable of verifying record signatures and
    59  // deriving node addresses.
    60  type IdentityScheme interface {
    61  	Verify(r *Record, sig []byte) error
    62  	NodeAddr(r *Record) []byte
    63  }
    64  
    65  // SchemeMap is a registry of named identity schemes.
    66  type SchemeMap map[string]IdentityScheme
    67  
    68  func (m SchemeMap) Verify(r *Record, sig []byte) error {
    69  	s := m[r.IdentityScheme()]
    70  	if s == nil {
    71  		return ErrInvalidSig
    72  	}
    73  	return s.Verify(r, sig)
    74  }
    75  
    76  func (m SchemeMap) NodeAddr(r *Record) []byte {
    77  	s := m[r.IdentityScheme()]
    78  	if s == nil {
    79  		return nil
    80  	}
    81  	return s.NodeAddr(r)
    82  }
    83  
    84  // Record represents a node record. The zero value is an empty record.
    85  type Record struct {
    86  	seq       uint64 // sequence number
    87  	signature []byte // the signature
    88  	raw       []byte // RLP encoded record
    89  	pairs     []pair // sorted list of all key/value pairs
    90  }
    91  
    92  // pair is a key/value pair in a record.
    93  type pair struct {
    94  	k string
    95  	v rlp.RawValue
    96  }
    97  
    98  // Seq returns the sequence number.
    99  func (r *Record) Seq() uint64 {
   100  	return r.seq
   101  }
   102  
   103  // SetSeq updates the record sequence number. This invalidates any signature on the record.
   104  // Calling SetSeq is usually not required because setting any key in a signed record
   105  // increments the sequence number.
   106  func (r *Record) SetSeq(s uint64) {
   107  	r.signature = nil
   108  	r.raw = nil
   109  	r.seq = s
   110  }
   111  
   112  // Load retrieves the value of a key/value pair. The given Entry must be a pointer and will
   113  // be set to the value of the entry in the record.
   114  //
   115  // Errors returned by Load are wrapped in KeyError. You can distinguish decoding errors
   116  // from missing keys using the IsNotFound function.
   117  func (r *Record) Load(e Entry) error {
   118  	i := sort.Search(len(r.pairs), func(i int) bool { return r.pairs[i].k >= e.ENRKey() })
   119  	if i < len(r.pairs) && r.pairs[i].k == e.ENRKey() {
   120  		if err := rlp.DecodeBytes(r.pairs[i].v, e); err != nil {
   121  			return &KeyError{Key: e.ENRKey(), Err: err}
   122  		}
   123  		return nil
   124  	}
   125  	return &KeyError{Key: e.ENRKey(), Err: errNotFound}
   126  }
   127  
   128  // Set adds or updates the given entry in the record. It panics if the value can't be
   129  // encoded. If the record is signed, Set increments the sequence number and invalidates
   130  // the sequence number.
   131  func (r *Record) Set(e Entry) {
   132  	blob, err := rlp.EncodeToBytes(e)
   133  	if err != nil {
   134  		panic(fmt.Errorf("enr: can't encode %s: %v", e.ENRKey(), err))
   135  	}
   136  	r.invalidate()
   137  
   138  	pairs := make([]pair, len(r.pairs))
   139  	copy(pairs, r.pairs)
   140  	i := sort.Search(len(pairs), func(i int) bool { return pairs[i].k >= e.ENRKey() })
   141  	switch {
   142  	case i < len(pairs) && pairs[i].k == e.ENRKey():
   143  		// element is present at r.pairs[i]
   144  		pairs[i].v = blob
   145  	case i < len(r.pairs):
   146  		// insert pair before i-th elem
   147  		el := pair{e.ENRKey(), blob}
   148  		pairs = append(pairs, pair{})
   149  		copy(pairs[i+1:], pairs[i:])
   150  		pairs[i] = el
   151  	default:
   152  		// element should be placed at the end of r.pairs
   153  		pairs = append(pairs, pair{e.ENRKey(), blob})
   154  	}
   155  	r.pairs = pairs
   156  }
   157  
   158  func (r *Record) invalidate() {
   159  	if r.signature != nil {
   160  		r.seq++
   161  	}
   162  	r.signature = nil
   163  	r.raw = nil
   164  }
   165  
   166  // Signature returns the signature of the record.
   167  func (r *Record) Signature() []byte {
   168  	if r.signature == nil {
   169  		return nil
   170  	}
   171  	cpy := make([]byte, len(r.signature))
   172  	copy(cpy, r.signature)
   173  	return cpy
   174  }
   175  
   176  // EncodeRLP implements rlp.Encoder. Encoding fails if
   177  // the record is unsigned.
   178  func (r Record) EncodeRLP(w io.Writer) error {
   179  	if r.signature == nil {
   180  		return errEncodeUnsigned
   181  	}
   182  	_, err := w.Write(r.raw)
   183  	return err
   184  }
   185  
   186  // DecodeRLP implements rlp.Decoder. Decoding doesn't verify the signature.
   187  func (r *Record) DecodeRLP(s *rlp.Stream) error {
   188  	dec, raw, err := decodeRecord(s)
   189  	if err != nil {
   190  		return err
   191  	}
   192  	*r = dec
   193  	r.raw = raw
   194  	return nil
   195  }
   196  
   197  func decodeRecord(s *rlp.Stream) (dec Record, raw []byte, err error) {
   198  	raw, err = s.Raw()
   199  	if err != nil {
   200  		return dec, raw, err
   201  	}
   202  	if len(raw) > SizeLimit {
   203  		return dec, raw, errTooBig
   204  	}
   205  
   206  	// Decode the RLP container.
   207  	s = rlp.NewStream(bytes.NewReader(raw), 0)
   208  	if _, err := s.List(); err != nil {
   209  		return dec, raw, err
   210  	}
   211  	if err = s.Decode(&dec.signature); err != nil {
   212  		return dec, raw, err
   213  	}
   214  	if err = s.Decode(&dec.seq); err != nil {
   215  		return dec, raw, err
   216  	}
   217  	// The rest of the record contains sorted k/v pairs.
   218  	var prevkey string
   219  	for i := 0; ; i++ {
   220  		var kv pair
   221  		if err := s.Decode(&kv.k); err != nil {
   222  			if err == rlp.EOL {
   223  				break
   224  			}
   225  			return dec, raw, err
   226  		}
   227  		if err := s.Decode(&kv.v); err != nil {
   228  			if err == rlp.EOL {
   229  				return dec, raw, errIncompletePair
   230  			}
   231  			return dec, raw, err
   232  		}
   233  		if i > 0 {
   234  			if kv.k == prevkey {
   235  				return dec, raw, errDuplicateKey
   236  			}
   237  			if kv.k < prevkey {
   238  				return dec, raw, errNotSorted
   239  			}
   240  		}
   241  		dec.pairs = append(dec.pairs, kv)
   242  		prevkey = kv.k
   243  	}
   244  	return dec, raw, s.ListEnd()
   245  }
   246  
   247  // IdentityScheme returns the name of the identity scheme in the record.
   248  func (r *Record) IdentityScheme() string {
   249  	var id ID
   250  	r.Load(&id)
   251  	return string(id)
   252  }
   253  
   254  // VerifySignature checks whether the record is signed using the given identity scheme.
   255  func (r *Record) VerifySignature(s IdentityScheme) error {
   256  	return s.Verify(r, r.signature)
   257  }
   258  
   259  // SetSig sets the record signature. It returns an error if the encoded record is larger
   260  // than the size limit or if the signature is invalid according to the passed scheme.
   261  //
   262  // You can also use SetSig to remove the signature explicitly by passing a nil scheme
   263  // and signature.
   264  //
   265  // SetSig panics when either the scheme or the signature (but not both) are nil.
   266  func (r *Record) SetSig(s IdentityScheme, sig []byte) error {
   267  	switch {
   268  	// Prevent storing invalid data.
   269  	case s == nil && sig != nil:
   270  		panic("enr: invalid call to SetSig with non-nil signature but nil scheme")
   271  	case s != nil && sig == nil:
   272  		panic("enr: invalid call to SetSig with nil signature but non-nil scheme")
   273  	// Verify if we have a scheme.
   274  	case s != nil:
   275  		if err := s.Verify(r, sig); err != nil {
   276  			return err
   277  		}
   278  		raw, err := r.encode(sig)
   279  		if err != nil {
   280  			return err
   281  		}
   282  		r.signature, r.raw = sig, raw
   283  	// Reset otherwise.
   284  	default:
   285  		r.signature, r.raw = nil, nil
   286  	}
   287  	return nil
   288  }
   289  
   290  // AppendElements appends the sequence number and entries to the given slice.
   291  func (r *Record) AppendElements(list []interface{}) []interface{} {
   292  	list = append(list, r.seq)
   293  	for _, p := range r.pairs {
   294  		list = append(list, p.k, p.v)
   295  	}
   296  	return list
   297  }
   298  
   299  func (r *Record) encode(sig []byte) (raw []byte, err error) {
   300  	list := make([]interface{}, 1, 2*len(r.pairs)+1)
   301  	list[0] = sig
   302  	list = r.AppendElements(list)
   303  	if raw, err = rlp.EncodeToBytes(list); err != nil {
   304  		return nil, err
   305  	}
   306  	if len(raw) > SizeLimit {
   307  		return nil, errTooBig
   308  	}
   309  	return raw, nil
   310  }