authentication

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 9, 2023 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Examples

Constants

View Source 
const SharedKeySizeBytes = 16

SharedKeySizeBytes is the length of the cryptographic key shared by a Signer and a Verifier.

Variables

View Source 
var (
	// ErrInvalidPublicKey is an Error raised when a remote peer provides an invalid public key.
	ErrInvalidPublicKey = newError(errCodeBadParameter, "invalid public key")
	// ErrInvalidPrivateKey indicates the local peer tried to load an unsupported or malformed
	// private key.
	ErrInvalidPrivateKey = errors.New("invalid private key")
)
View Source 
var (

	// ErrMetadataFieldTooLong indicates an authenticated field (such as a verifier name) is too
	// long to be compatible with the serialization format.
	ErrMetadataFieldTooLong = errors.New("metadata fields can't be more than 255 bytes long")
)

Functions

This section is empty.

Types

type Dispatcher 

type Dispatcher struct {
	ECDHPrivateKey
}

Dispatcher facilitates creating connections to multiple vehicles using the same ECDHPrivateKey.

Example 
const carCount = 10
const messagesPerCar = 5
var challenges [][]byte

// Create dispatcher
dispatcherPrivateKey, err := NewECDHPrivateKey(rand.Reader)
if err != nil {
	panic(fmt.Sprintf("Failed to generate dispatcher key: %s", err))
}
dispatcher := Dispatcher{dispatcherPrivateKey}
// Initialize cars, provision dispatcher public key
cars := make([]*Verifier, carCount)
for i := 0; i < carCount; i++ {
	vin := []byte(fmt.Sprintf("%d", i))
	VCSECKey, err := NewECDHPrivateKey(rand.Reader)
	var challenge [16]byte
	if _, err := rand.Read(challenge[:]); err != nil {
		panic(fmt.Sprintf("Failed to generate random challenge: %s", err))
	} else {
		challenges = append(challenges, challenge[:])
	}
	if err != nil {
		panic(fmt.Sprintf("Failed to generate car key: %s", err))
	}
	cars[i], err = NewVerifier(VCSECKey,
		vin, universal.Domain_DOMAIN_VEHICLE_SECURITY,
		dispatcherPrivateKey.PublicBytes())
	if err != nil {
		panic(fmt.Sprintf("Failed to initialize car: %s", err))
	}
}

message := &universal.RoutableMessage{
	ToDestination: &universal.Destination{
		SubDestination: &universal.Destination_Domain{Domain: universal.Domain_DOMAIN_VEHICLE_SECURITY},
	},
}
for i := 0; i < carCount; i++ {
	// Fetch session info from vehicle
	sessionInfo, tag, err := cars[i].SignedSessionInfo(challenges[i])
	if err != nil {
		panic(fmt.Sprintf("Error obtaining session info from car %d: %s", i, err))
	}
	// Give it to the signer (dispatcher). The UUID used to fetch the
	// session info can be used as the challenge.
	connection, err := dispatcher.ConnectAuthenticated(cars[i].verifierName, challenges[i], sessionInfo, tag)
	if err != nil {
		panic(fmt.Sprintf("Error creating authenticated connection to car %d: %s", i, err))
	}

	// Send several messages to vehicle using connection
	for j := 0; j < messagesPerCar; j++ {
		original := []byte(fmt.Sprintf("Message %d for car %d", j, i))
		message.Payload = &universal.RoutableMessage_ProtobufMessageAsBytes{ProtobufMessageAsBytes: original}
		if err := connection.Encrypt(message, time.Minute); err != nil {
			panic(fmt.Sprintf("Failed to encrypt message: %s", err))
		}

		// This won't happen if err above is nil, just here for illustrative purposes.
		if bytes.Equal(message.GetProtobufMessageAsBytes(), original) {
			panic("Message wasn't encrypted!")
		}

		if plaintext, err := cars[i].Verify(message); err != nil {
			panic(fmt.Sprintf("Decryption error :%s", err))
		} else if !bytes.Equal(plaintext, original) {
			panic("Failed to recover original plaintext")
		}
	}
}

Output:

func (*Dispatcher) Connect 

func (d *Dispatcher) Connect(verifierId []byte, sessionInfo *signatures.SessionInfo) (*Signer, error)

func (*Dispatcher) ConnectAuthenticated 

func (d *Dispatcher) ConnectAuthenticated(verifierId, challenge, encodedSessionInfo, tag []byte) (*Signer, error)

type ECDHPrivateKey 

type ECDHPrivateKey interface {
	Exchange(remotePublicBytes []byte) (Session, error)
	PublicBytes() []byte
}

ECDHPrivateKey represents a local private key.

func LoadExternalECDHKey 

func LoadExternalECDHKey(filename string) (ECDHPrivateKey, error)

func NewECDHPrivateKey 

func NewECDHPrivateKey(rng io.Reader) (ECDHPrivateKey, error)

func UnmarshalECDHPrivateKey 

func UnmarshalECDHPrivateKey(privateScalar []byte) ECDHPrivateKey

type Error 

type Error struct {
	Code universal.MessageFault_E
	Info string
}

Error represents a protocol-layer error.

func (Error) Error 

func (e Error) Error() string

type InvalidSignatureError 

type InvalidSignatureError struct {
	Code        universal.MessageFault_E
	EncodedInfo []byte
	Tag         []byte
}

func (*InvalidSignatureError) Error 

func (e *InvalidSignatureError) Error() string

type NativeECDHKey 

type NativeECDHKey struct {
	*ecdsa.PrivateKey
}

func (*NativeECDHKey) Exchange 

func (n *NativeECDHKey) Exchange(publicBytes []byte) (Session, error)

func (*NativeECDHKey) Public 

func (n *NativeECDHKey) Public() *ecdsa.PublicKey

func (*NativeECDHKey) PublicBytes 

func (n *NativeECDHKey) PublicBytes() []byte

type NativeSession 

type NativeSession struct {
	// contains filtered or unexported fields
}

NativeSession implements the Session interface using native Go.

func (*NativeSession) Decrypt 

func (b *NativeSession) Decrypt(nonce, ciphertext, associatedData, tag []byte) (plaintext []byte, err error)

func (*NativeSession) Encrypt 

func (b *NativeSession) Encrypt(plaintext, associatedData []byte) (nonce, ciphertext, tag []byte, err error)

func (*NativeSession) LocalPublicBytes 

func (b *NativeSession) LocalPublicBytes() []byte

func (*NativeSession) NewHMAC 

func (b *NativeSession) NewHMAC(label string) hash.Hash

func (*NativeSession) SessionInfoHMAC 

func (b *NativeSession) SessionInfoHMAC(id, challenge, encodedInfo []byte) ([]byte, error)

type Peer 

type Peer struct {
	// contains filtered or unexported fields
}

A Peer is the parent type for Signer and Verifier.

type Session 

type Session interface {
	// Returns the session info HMAC tag for encodedInfo. The challenge is a Signer-provided
	// anti-replay value.
	SessionInfoHMAC(id, challenge, encodedInfo []byte) ([]byte, error)
	// Encrypt plaintext and generate a tag that can be used to authenticate
	// the ciphertext and associated data. The tag and ciphertext are part of
	// the same slice, but returned separately for convenience.
	Encrypt(plaintext, associatedData []byte) (nonce, ciphertext, tag []byte, err error)
	// Authenticate a ciphertext and its associated data using the tag, then
	// decrypt it and return the plaintext.
	Decrypt(nonce, ciphertext, associatedData, tag []byte) (plaintext []byte, err error)
	// Return the encoded local public key.
	LocalPublicBytes() []byte
	// Returns a hash.Hash context that can be used as a KDF rooted in the shared secret.
	NewHMAC(label string) hash.Hash
}

A Session allows encrypting/decrypting/authenticating data using a shared ECDH secret.

type Signer 

type Signer struct {
	Peer
	// contains filtered or unexported fields
}

Signers encrypt messages that are decrypted and verified by a designated Verifier. (Technically speaking, the name is a misnomer since Signers use symmetric-key operations following ECDH key agreement.)

func ImportSessionInfo 

func ImportSessionInfo(private ECDHPrivateKey, verifierName, encodedInfo []byte, generatedAt time.Time) (*Signer, error)

ImportSessionInfo allows creation of a Signer with cached SessionInfo. This can be used to avoid a round trip with the Verifier.

func NewAuthenticatedSigner 

func NewAuthenticatedSigner(private ECDHPrivateKey, verifierName, challenge, encodedInfo, tag []byte) (*Signer, error)

NewAuthenticatedSigner creates a Signer from encoded and cryptographically verified session info.

func NewSigner 

func NewSigner(private ECDHPrivateKey, verifierName []byte, verifierInfo *signatures.SessionInfo) (*Signer, error)

NewSigner creates a Signer that sends authenticated messages to the Verifier named verifierName. In order to use this function, the client needs to obtain verifierInfo from the Verifier.

func (*Signer) AuthorizeHMAC 

func (s *Signer) AuthorizeHMAC(message *universal.RoutableMessage, expiresIn time.Duration) error

AuthorizeHMAC adds an authentication tag to message.

This allows the recipient to verify the message has not been tampered with, but the payload is not encrypted. Unencrypted (but authenticated) messages are required for an HTTP API which relays messages to vehicles but needs to state in order to determine when a sequence of replies terminates. Sensitive data, such as live camera streams, is encrypted on the application layer.

func (*Signer) Encrypt 

func (s *Signer) Encrypt(message *universal.RoutableMessage, expiresIn time.Duration) error

Encrypt message's payload in-place. This method adds (authenticated) metadata to the message as well, including the provided expiration time.

func (*Signer) ExportSessionInfo 

func (s *Signer) ExportSessionInfo() ([]byte, error)

ExportSessionInfo can be used to write session state to disk, allowing for later resumption using ImportSessionInfo.

func (*Signer) RemotePublicKeyBytes 

func (s *Signer) RemotePublicKeyBytes() []byte

RemotePublicKeyBytes returns the Verifer's public key encoded without point compression.

func (*Signer) UpdateSessionInfo 

func (s *Signer) UpdateSessionInfo(info *signatures.SessionInfo) error

UpdateSessionInfo allows s to resync session state with a Verifier. A Verifier may include info in an authentication error message when the error may have resulted from a desync. The Signer can update its session info and then reattempt transmission.

func (*Signer) UpdateSignedSessionInfo 

func (s *Signer) UpdateSignedSessionInfo(challenge, encodedInfo, tag []byte) error

UpdateSignedSessionInfo allows s to resync session state with a Verifier using cryptographically verified session state. See UpdateSessionInfo.

type Verifier 

type Verifier struct {
	Peer
	// contains filtered or unexported fields
}

A Verifier checks the authenticity of commands sent by a Signer.

func NewVerifier 

func NewVerifier(private ECDHPrivateKey, id []byte, domain universal.Domain, signerPublicBytes []byte) (*Verifier, error)

NewVerifier returns a Verifier. Set domain to universal.Domain_DOMAIN_BROADCAST if the Verifier shouldn't enforce domain checking. The Verifier's domain must be known in advance by the Signer.

func (*Verifier) SessionInfo 

func (v *Verifier) SessionInfo() (*signatures.SessionInfo, error)

SessionInfo contains metadata used to prevent replay and similar attacks. A Signer must have the Verifier's SessionInfo on initialization.

func (*Verifier) SetSessionInfo 

func (v *Verifier) SetSessionInfo(challenge []byte, message *universal.RoutableMessage) error

SetSessionInfo attaches up-to-date session info to a message. This is useful when v encounters an error while authenticating a message and wishes to include session info in the error response, thereby allowing the Signer to resync.

func (*Verifier) SignedSessionInfo 

func (v *Verifier) SignedSessionInfo(challenge []byte) (encodedInfo, tag []byte, err error)

SignedSessionInfo returns a protobuf-encoded signatures.SessionInfo along with an authentication tag that a Signer may use to verify the info has not been tampered with.

func (*Verifier) Verify 

func (v *Verifier) Verify(message *universal.RoutableMessage) (plaintext []byte, err error)

Verify message. If payload is encrypted, returns the plaintext. Otherwise extracts and returns the payload as-is.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.