libp2p/go-libp2p-core
1
0
Fork 0
mirror of https://github.com/libp2p/go-libp2p-core.git synced 2025-02-22 08:20:09 +08:00
Code Issues Projects Releases Wiki Activity

doc comments for envelopes

Browse Source
This commit is contained in:
Yusef Napora 2019-11-07 10:56:28 -05:00
parent 133f891544
commit cc866a8a18
1 changed files with 37 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
crypto/envelope.go
View File

@ -9,14 +9,40 @@ import (
"github.com/libp2p/go-libp2p-core/peer"
)
// SignedEnvelope contains an arbitrary []byte payload, signed by a libp2p peer.
// Envelopes are signed in the context of a particular "domain", which is a string
// specified when creating and verifying the envelope. You must know the domain
// string used to produce the envelope in order to verify the signature and
// access the contents.
type SignedEnvelope struct {
// The public key that can be used to verify the signature and derive the peer id of the signer.
PublicKey PubKey
// A binary identifier that indicates what kind of data is contained in the payload.
// TODO(yusef): enforce multicodec prefix
TypeHint []byte
// The envelope payload. This is private to discourage accessing the payload without verifying the signature.
// To access, use the Open method.
contents []byte
// The signature of the domain string, type hint, and contents.
signature []byte
}
var errEmptyDomain = errors.New("envelope domain must not be empty")
// MakeEnvelope constructs a new SignedEnvelope using the given privateKey.
//
// The required 'domain' string contextualizes the envelope for a particular purpose,
// and must be supplied when verifying the signature.
//
// The 'typeHint' field indicates what kind of data is contained and may be empty.
func MakeEnvelope(privateKey PrivKey, domain string, typeHint []byte, contents []byte) (*SignedEnvelope, error) {
if len(domain) == 0 {
return nil, errEmptyDomain
}
toSign := makeSigBuffer(domain, typeHint, contents)
sig, err := privateKey.Sign(toSign)
if err != nil {
@ -31,6 +57,8 @@ func MakeEnvelope(privateKey PrivKey, domain string, typeHint []byte, contents [
}, nil
}
// UnmarshalEnvelope converts a serialized protobuf representation of an envelope
// into a SignedEnvelope struct.
func UnmarshalEnvelope(serializedEnvelope []byte) (*SignedEnvelope, error) {
e := pb.SignedEnvelope{}
if err := proto.Unmarshal(serializedEnvelope, &e); err != nil {
@ -48,15 +76,20 @@ func UnmarshalEnvelope(serializedEnvelope []byte) (*SignedEnvelope, error) {
}, nil
}
// SignerID returns the peer.ID of the peer who produced the SignedEnvelope.
func (e *SignedEnvelope) SignerID() (peer.ID, error) {
return peer.IDFromPublicKey(e.PublicKey)
}
// Validate returns true if the envelope signature is valid for the given 'domain',
// or false if it is invalid. May return an error if signature validation fails.
func (e *SignedEnvelope) Validate(domain string) (bool, error) {
toVerify := makeSigBuffer(domain, e.TypeHint, e.contents)
return e.PublicKey.Verify(toVerify, e.signature)
}
// Marshal returns a []byte containing a serialized protobuf representation of
// the SignedEnvelope.
func (e *SignedEnvelope) Marshal() ([]byte, error) {
key, err := PublicKeyToProto(e.PublicKey)
if err != nil {
@ -71,6 +104,9 @@ func (e *SignedEnvelope) Marshal() ([]byte, error) {
return proto.Marshal(&msg)
}
// Open validates the signature (within the given 'domain') and returns
// the contents of the envelope. Will fail with an error if the signature
// is invalid.
func (e *SignedEnvelope) Open(domain string) ([]byte, error) {
valid, err := e.Validate(domain)
if err != nil {
@ -82,6 +118,7 @@ func (e *SignedEnvelope) Open(domain string) ([]byte, error) {
return e.contents, nil
}
// makeSigBuffer is a helper function that prepares a buffer to sign or verify.
func makeSigBuffer(domain string, typeHint []byte, content []byte) []byte {
b := bytes.Buffer{}
domainBytes := []byte(domain)