interop

package
v3.30.0 Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2024 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Overview

Package interop implements a LoRaWAN Backend Interfaces server and client.

Index

Constants

View Source 
const (
	// InteropClientConfigurationName represents the filename of interop client configuration.
	InteropClientConfigurationName = "config.yml"
	// SenderClientCAsConfigurationName represents the filename of sender client CAs configuration.
	SenderClientCAsConfigurationName = "config.yml"
)
View Source 
const (
	// ProtocolV1_0 is LoRaWAN Backend Interfaces (TS002) 1.0.
	ProtocolV1_0 = "1.0"
	// ProtocolV1_1 is LoRaWAN Backend Interfaces (TS002) 1.1.x.
	ProtocolV1_1 = "1.1"
)

Variables

View Source 
var (
	ErrNoAction           = errors.DefineAborted("no_action", "no action", "result_description")
	ErrMIC                = errors.DefineInvalidArgument("mic", "MIC failed", "result_description")
	ErrFrameReplayed      = errors.DefineAborted("frame_replayed", "frame replayed", "result_description")
	ErrJoinReq            = errors.DefineAborted("join_req", "join-request failed", "result_description")
	ErrNoRoamingAgreement = errors.DefineFailedPrecondition("no_roaming_agreement", "no roaming agreement",
		"result_description",
	)
	ErrDeviceRoaming = errors.DefineFailedPrecondition("device_roaming", "device roaming disallowed",
		"result_description",
	)
	ErrRoamingActivation = errors.DefineFailedPrecondition("roaming_activation", "roaming activation disallowed",
		"result_description",
	)
	ErrActivation      = errors.DefineFailedPrecondition("activation", "activation disallowed", "result_description")
	ErrUnknownDevEUI   = errors.DefineNotFound("unknown_dev_eui", "unknown DevEUI", "result_description")
	ErrUnknownDevAddr  = errors.DefineNotFound("unknown_dev_addr", "unknown DevAddr", "result_description")
	ErrUnknownSender   = errors.DefineNotFound("unknown_sender", "unknown sender", "result_description")
	ErrUnknownReceiver = errors.DefineNotFound("unknown_receiver", "unknown receiver", "result_description")
	ErrDeferred        = errors.DefineAborted("deferred", "deferred", "result_description")
	ErrTransmitFailed  = errors.DefineAborted("transmit_failed", "transmit failed", "result_description")
	ErrFPort           = errors.DefineInvalidArgument("f_port", "invalid FPort", "result_description")
	ErrProtocolVersion = errors.DefineInvalidArgument("protocol_version", "invalid protocol version",
		"result_description",
	)
	ErrStaleDeviceProfile = errors.DefineFailedPrecondition("stale_device_profile", "stale device profile",
		"result_description",
	)
	ErrMalformedMessage = errors.DefineInvalidArgument("malformed_message", "malformed message", "result_description")
	ErrFrameSize        = errors.DefineInvalidArgument("frame_size", "frame size error", "result_description")
)

LoRaWAN Backend Interfaces 1.0 errors.

View Source 
var TTIVendorID = VendorID{0xec, 0x65, 0x6e}

TTIVendorID is the vendor ID of The Things Industries.

Functions

func GeneratedSessionKeyID 

func GeneratedSessionKeyID(id []byte) bool

GeneratedSessionKeyID returns whether the session key ID is generated locally and not by the Join Server.

func NewContextWithApplicationServerAuthInfo added in v3.15.2 

func NewContextWithApplicationServerAuthInfo(
	parent context.Context, authInfo *ApplicationServerAuthInfo,
) context.Context

NewContextWithApplicationServerAuthInfo returns a derived context with the given authentication information of the Application Server.

func NewContextWithNetworkServerAuthInfo added in v3.15.2 

func NewContextWithNetworkServerAuthInfo(parent context.Context, authInfo *NetworkServerAuthInfo) context.Context

NewContextWithNetworkServerAuthInfo returns a derived context with the given authentication information of the Network Server.

Types

type AppSKeyAns 

type AppSKeyAns struct {
	JsAsMessageHeader
	Result       Result
	DevEUI       EUI64
	AppSKey      *KeyEnvelope
	SessionKeyID Buffer
}

AppSKeyAns is an answer to an AppSKeyReq message.

type AppSKeyReq 

type AppSKeyReq struct {
	AsJsMessageHeader
	DevEUI       EUI64
	SessionKeyID Buffer
}

AppSKeyReq is a AppSKey request message.

type ApplicationServerAuthInfo added in v3.15.2 

type ApplicationServerAuthInfo struct {
	ASID      string
	Addresses []string
}

ApplicationServerAuthInfo contains the authentication information of an Application Server.

func ApplicationServerAuthInfoFromContext added in v3.15.2 

func ApplicationServerAuthInfoFromContext(ctx context.Context) (*ApplicationServerAuthInfo, bool)

ApplicationServerAuthInfoFromContext returns the authentication information of the Application Server from context.

type AsJsMessageHeader 

type AsJsMessageHeader struct {
	MessageHeader
	SenderID string
	// ReceiverID is a JoinEUI.
	ReceiverID EUI64
}

AsJsMessageHeader contains the message header for AS to JS messages.

type AsMessageHeader added in v3.15.2 

type AsMessageHeader struct {
	MessageHeader
}

AsMessageHeader contains the message header for AS messages.

type Authorizer added in v3.15.2 

type Authorizer struct{}

Authorizer authorizes requests handled by the interop server.

func (Authorizer) RequireASID added in v3.15.2 

func (Authorizer) RequireASID(ctx context.Context, id string) error

RequireASID returns an error if the given AS-ID is not authorized in the context.

func (Authorizer) RequireAddress added in v3.15.2 

func (Authorizer) RequireAddress(ctx context.Context, addr string) error

RequireAddress returns an error if the given address is not authorized in the context.

func (Authorizer) RequireAuthorized added in v3.15.2 

func (Authorizer) RequireAuthorized(ctx context.Context) error

RequireAuthorized returns an error if the given context is not authorized as neither Network Server nor Application Server.

func (Authorizer) RequireNetID added in v3.15.2 

func (Authorizer) RequireNetID(ctx context.Context, netID types.NetID) error

RequireNetID returns an error if the given NetID is not authorized in the context.

type Buffer 

type Buffer []byte

Buffer is a binary buffer that is represented as hexadecimal in text.

func (Buffer) MarshalText added in v3.15.2 

func (b Buffer) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*Buffer) UnmarshalText added in v3.15.2 

func (b *Buffer) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type Client 

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

Client is an interop client.

func NewClient 

func NewClient(
	ctx context.Context, conf config.InteropClient, c ClientComponent, selector ComponentSelector,
) (*Client, error)

NewClient return new interop client.

func (Client) GetAppSKey 

func (cl Client) GetAppSKey(
	ctx context.Context, asID string, req *ttnpb.SessionKeyRequest,
) (*ttnpb.AppSKeyResponse, error)

GetAppSKey performs AppSKey request to Join Server associated with req.JoinEUI.

func (Client) HandleJoinRequest 

func (cl Client) HandleJoinRequest(
	ctx context.Context, netID types.NetID, nsID *types.EUI64, req *ttnpb.JoinRequest,
) (*ttnpb.JoinResponse, error)

HandleJoinRequest performs Join request to Join Server associated with req.JoinEUI.

type ClientComponent added in v3.24.0 

type ClientComponent interface {
	httpclient.Provider
	KeyService() crypto.KeyService
}

ClientComponent provides an interface to the component for the interop client.

type Component added in v3.12.0 

type Component interface {
	httpclient.Provider
	Context() context.Context
	RateLimiter() ratelimit.Interface
}

Component represents the Component to the Interop Server.

type ComponentSelector added in v3.21.0 

type ComponentSelector string

ComponentSelector is a component selector. 

const (
	SelectorNetworkServer     ComponentSelector = "ns"
	SelectorApplicationServer ComponentSelector = "as"
)

Component selectors.

type DevAddr 

type DevAddr types.DevAddr

DevAddr is a LoRaWAN DevAddr.

func (DevAddr) MarshalText added in v3.15.2 

func (n DevAddr) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*DevAddr) UnmarshalText added in v3.15.2 

func (n *DevAddr) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type EUI64 

type EUI64 types.EUI64

EUI64 is an 64-bit EUI, e.g. a DevEUI or JoinEUI.

func (EUI64) MarshalText added in v3.15.2 

func (n EUI64) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*EUI64) UnmarshalText added in v3.15.2 

func (n *EUI64) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type ErrorMessage 

type ErrorMessage struct {
	MessageHeader
	Result Result
}

ErrorMessage is a message with raw header and a result field.

type HomeNSAns 

type HomeNSAns struct {
	JsNsMessageHeader
	Result Result
	HNSID  *EUI64 `json:",omitempty"`
	HNetID NetID
}

HomeNSAns is an answer to a HomeNSReq message.

type HomeNSReq 

type HomeNSReq struct {
	NsJsMessageHeader
	DevEUI EUI64
}

HomeNSReq is a NetID request message.

type IdentityServer added in v3.15.2 

type IdentityServer interface {
	HomeNSRequest(context.Context, *HomeNSReq) (*TTIHomeNSAns, error)
}

IdentityServer represents an Identity Server.

type JoinAns 

type JoinAns struct {
	JsNsMessageHeader
	PHYPayload   Buffer
	Result       Result
	Lifetime     uint32
	SNwkSIntKey  *KeyEnvelope `json:",omitempty"`
	FNwkSIntKey  *KeyEnvelope `json:",omitempty"`
	NwkSEncKey   *KeyEnvelope `json:",omitempty"`
	NwkSKey      *KeyEnvelope `json:",omitempty"`
	AppSKey      *KeyEnvelope `json:",omitempty"`
	SessionKeyID Buffer       `json:",omitempty"`
}

JoinAns is an answer to a JoinReq message.

type JoinReq 

type JoinReq struct {
	NsJsMessageHeader
	MACVersion MACVersion
	PHYPayload Buffer
	DevEUI     EUI64
	DevAddr    DevAddr
	DLSettings Buffer
	RxDelay    ttnpb.RxDelay
	CFList     Buffer `json:",omitempty"`
}

JoinReq is a join-request message.

type JoinServer 

type JoinServer interface {
	JoinRequest(context.Context, *JoinReq) (*JoinAns, error)
	AppSKeyRequest(context.Context, *AppSKeyReq) (*AppSKeyAns, error)
	HomeNSRequest(context.Context, *HomeNSReq) (*TTIHomeNSAns, error)
}

JoinServer represents a Join Server as specified in LoRaWAN Backend Interfaces.

type JsAsMessageHeader 

type JsAsMessageHeader struct {
	MessageHeader
	// SenderID is a JoinEUI.
	SenderID   EUI64
	ReceiverID string
}

JsAsMessageHeader contains the message header for JS to AS messages.

type JsNsMessageHeader 

type JsNsMessageHeader struct {
	MessageHeader
	// SenderID is a JoinEUI.
	SenderID     EUI64
	ReceiverID   NetID
	ReceiverNSID *EUI64 `json:",omitempty"`
}

JsNsMessageHeader contains the message header for JS to NS messages.

type KeyEnvelope 

type KeyEnvelope ttnpb.KeyEnvelope

KeyEnvelope contains a (encrypted) key.

func (*KeyEnvelope) MarshalJSON 

func (k *KeyEnvelope) MarshalJSON() ([]byte, error)

MarshalJSON marshals the key envelope to JSON.

func (*KeyEnvelope) UnmarshalJSON 

func (k *KeyEnvelope) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the key envelope from JSON.

type MACVersion 

type MACVersion ttnpb.MACVersion

MACVersion is the MAC version.

func (MACVersion) MarshalText added in v3.15.2 

func (v MACVersion) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*MACVersion) UnmarshalText added in v3.15.2 

func (v *MACVersion) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type MessageHeader 

type MessageHeader struct {
	ProtocolVersion ProtocolVersion
	TransactionID   uint32
	MessageType     MessageType
	SenderID,
	ReceiverID string
	SenderNSID    *EUI64       `json:",omitempty"`
	ReceiverNSID  *EUI64       `json:",omitempty"`
	SenderToken   Buffer       `json:",omitempty"`
	ReceiverToken Buffer       `json:",omitempty"`
	VSExtension   *VSExtension `json:",omitempty"`
}

MessageHeader is the common LoRaWAN Backend Interfaces message header.

func (MessageHeader) AnswerHeader 

func (h MessageHeader) AnswerHeader() (MessageHeader, error)

AnswerHeader returns the header of the answer message.

type MessageType 

type MessageType string

MessageType is the message type. 

const (
	MessageTypeJoinReq     MessageType = "JoinReq"
	MessageTypeJoinAns     MessageType = "JoinAns"
	MessageTypeRejoinReq   MessageType = "RejoinReq"
	MessageTypeRejoinAns   MessageType = "RejoinAns"
	MessageTypeAppSKeyReq  MessageType = "AppSKeyReq"
	MessageTypeAppSKeyAns  MessageType = "AppSKeyAns"
	MessageTypePRStartReq  MessageType = "PRStartReq"
	MessageTypePRStartAns  MessageType = "PRStartAns"
	MessageTypePRStopReq   MessageType = "PRStopReq"
	MessageTypePRStopAns   MessageType = "PRStopAns"
	MessageTypeHRStartReq  MessageType = "HRStartReq"
	MessageTypeHRStartAns  MessageType = "HRStartAns"
	MessageTypeHRStopReq   MessageType = "HRStopReq"
	MessageTypeHRStopAns   MessageType = "HRStopAns"
	MessageTypeHomeNSReq   MessageType = "HomeNSReq"
	MessageTypeHomeNSAns   MessageType = "HomeNSAns"
	MessageTypeProfileReq  MessageType = "ProfileReq"
	MessageTypeProfileAns  MessageType = "ProfileAns"
	MessageTypeXmitDataReq MessageType = "XmitDataReq"
	MessageTypeXmitDataAns MessageType = "XmitDataAns"
)

LoRaWAN Backend Interfaces message types.

func (MessageType) Answer added in v3.15.2 

func (m MessageType) Answer() (MessageType, bool)

Answer returns the answer message type. If the message type is not a request, this method returns false.

func (MessageType) IsRequest added in v3.15.2 

func (m MessageType) IsRequest() bool

IsRequest returns whether the message type is a request that has an answer message type defined.

func (MessageType) ToJoinServer added in v3.15.2 

func (m MessageType) ToJoinServer() bool

ToJoinServer indicates whether the message goes to a Join Server. If this method returns true, the message's ReceiverID must be a JoinEUI.

func (MessageType) Validate added in v3.15.2 

func (m MessageType) Validate(version ProtocolVersion) error

Validate returns an error if the message type is not valid for the given protocol version.

type NetID 

type NetID types.NetID

NetID is a LoRaWAN NetID.

func (NetID) MarshalText added in v3.15.2 

func (n NetID) MarshalText() ([]byte, error)

MarshalText marshals the NetID to text.

func (*NetID) UnmarshalText added in v3.15.2 

func (n *NetID) UnmarshalText(data []byte) error

UnmarshalText unmarshals the NetID from text.

type NetworkServerAuthInfo added in v3.15.2 

type NetworkServerAuthInfo struct {
	NetID     types.NetID
	Addresses []string
}

NetworkServerAuthInfo contains the authentication information of a Network Server.

func NetworkServerAuthInfoFromContext added in v3.15.2 

func NetworkServerAuthInfoFromContext(ctx context.Context) (*NetworkServerAuthInfo, bool)

NetworkServerAuthInfoFromContext returns the authentication information of the Network Server from context.

func (NetworkServerAuthInfo) Require added in v3.15.2 

func (n NetworkServerAuthInfo) Require(netID types.NetID, _ *EUI64) error

Require returns an error if the given NetID or NSID does not match.

type NsJsMessageHeader 

type NsJsMessageHeader struct {
	MessageHeader
	SenderID   NetID
	SenderNSID *EUI64 `json:",omitempty"`
	// ReceiverID is a JoinEUI.
	ReceiverID EUI64
}

NsJsMessageHeader contains the message header for NS to JS messages.

type NsMessageHeader added in v3.15.2 

type NsMessageHeader struct {
	MessageHeader
	SenderID   NetID
	SenderNSID *EUI64 `json:",omitempty"`
}

NsMessageHeader contains the message header for NS messages.

type ProtocolVersion added in v3.15.2 

type ProtocolVersion string

ProtocolVersion is the LoRaWAN Backend Interfaces protocol version.

func (ProtocolVersion) RequiresNSID added in v3.18.0 

func (p ProtocolVersion) RequiresNSID() bool

RequiresNSID returns true if the protocol version supports Network Server IDs (NSID).

func (*ProtocolVersion) UnmarshalYAML added in v3.15.2 

func (p *ProtocolVersion) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements yaml.Unmarshaler.

type Registerer 

type Registerer interface {
	RegisterInterop(s *Server)
}

Registerer allows components to register their interop services to the web server.

type Result 

type Result struct {
	ResultCode  ResultCode
	Description string `json:",omitempty"`
}

Result contains the result of an operation.

type ResultCode 

type ResultCode string

ResultCode is the result of an answer message. 

const (
	ResultSuccess              ResultCode = "Success"
	ResultNoAction             ResultCode = "NoAction"
	ResultMICFailed            ResultCode = "MICFailed"
	ResultFrameReplayed        ResultCode = "FrameReplayed"
	ResultJoinReqFailed        ResultCode = "JoinReqFailed"
	ResultNoRoamingAgreement   ResultCode = "NoRoamingAgreement"
	ResultDevRoamingDisallowed ResultCode = "DevRoamingDisallowed"
	ResultRoamingActDisallowed ResultCode = "RoamingActDisallowed"
	ResultActivationDisallowed ResultCode = "ActivationDisallowed"
	ResultUnknownDevEUI        ResultCode = "UnknownDevEUI"
	ResultUnknownDevAddr       ResultCode = "UnknownDevAddr"
	ResultUnknownSender        ResultCode = "UnknownSender"
	ResultUnkownReceiver       ResultCode = "UnkownReceiver" // sic
	// ResultUnknownReceiver is not specified in LoRaWAN Backend Interfaces 1.0 but is processed as ResultUnkownReceiver.
	ResultUnknownReceiver        ResultCode = "UnknownReceiver"
	ResultDeferred               ResultCode = "Deferred"
	ResultXmitFailed             ResultCode = "XmitFailed"
	ResultInvalidFPort           ResultCode = "InvalidFPort"
	ResultInvalidProtocolVersion ResultCode = "InvalidProtocolVersion"
	ResultStaleDeviceProfile     ResultCode = "StaleDeviceProfile"
	ResultMalformedRequest       ResultCode = "MalformedRequest"
	ResultMalformedMessage       ResultCode = "MalformedMessage"
	ResultFrameSizeError         ResultCode = "FrameSizeError"
	ResultOther                  ResultCode = "Other"
)

LoRaWAN Backend Interfaces 1.0 result codes.

type Server 

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

Server is the server.

func NewServer 

func NewServer(c Component, contextFiller fillcontext.Filler, conf config.InteropServer) (*Server, error)

NewServer builds a new server.

func (*Server) ClientCAPool added in v3.15.2 

func (s *Server) ClientCAPool() *x509.CertPool

ClientCAPool returns a certificate pool of all configured client CAs. TODO: Remove (https://github.com/TheThingsNetwork/lorawan-stack/issues/6026)

func (*Server) RegisterIS added in v3.15.2 

func (s *Server) RegisterIS(is IdentityServer)

RegisterIS registers the Identity Server for answering to HomeNSRequest.

func (*Server) RegisterJS 

func (s *Server) RegisterJS(js JoinServer)

RegisterJS registers the Join Server for AS-JS, hNS-JS and vNS-JS messages. If an Identity Server is registered with RegisterIS, the Identity Server takes precedence for handling HomeNSRequest.

func (*Server) SenderClientCAs 

func (s *Server) SenderClientCAs(_ context.Context, senderID string) ([]*x509.Certificate, error)

SenderClientCAs returns the client certificate authorities that are trusted for the given SenderID. The SenderID is typically a NetID, but an AS-ID or JoinEUI can also be used to trust Application Servers and Join Servers respectively.

func (*Server) ServeHTTP 

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves the HTTP request.

type TTIHomeNSAns added in v3.15.2 

type TTIHomeNSAns struct {
	HomeNSAns
	TTIVSExtension
}

TTIHomeNSAns is HomeNSAns with vendor extension of The Things Industries.

func (TTIHomeNSAns) MarshalJSON added in v3.15.2 

func (m TTIHomeNSAns) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Unmarshaler.

func (*TTIHomeNSAns) UnmarshalJSON added in v3.15.2 

func (m *TTIHomeNSAns) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type TTIVSExtension added in v3.18.2 

type TTIVSExtension struct {
	// HTenantID is the Tenant ID within a host HNetID.
	HTenantID string
	// HNSAddress is the Home Network Server address.
	HNSAddress string
}

TTIVSExtension is vendor extension of The Things Industries.

type TTIVendorIDType added in v3.18.2 

type TTIVendorIDType VendorID

TTIVendorIDType is the custom type for The Things Industries vendor ID.

func (TTIVendorIDType) MarshalText added in v3.18.2 

func (TTIVendorIDType) MarshalText() ([]byte, error)

MarshalText returns the vendor ID of The Things Industries.

func (*TTIVendorIDType) UnmarshalText added in v3.18.2 

func (v *TTIVendorIDType) UnmarshalText(data []byte) error

UnmarshalText returns an error if the vendor ID is not of The Things Industries.

type VSExtension added in v3.15.2 

type VSExtension struct {
	VendorID VendorID
}

VSExtension is a vendor-specific extension.

type VendorID added in v3.15.2 

type VendorID [3]byte

VendorID is an IEEE MAC-L (OUI) assignment to indicate the vendor.

func (VendorID) MarshalNumber added in v3.18.2 

func (v VendorID) MarshalNumber() uint32

MarshalNumber returns the numeric value.

func (VendorID) MarshalText added in v3.15.2 

func (v VendorID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*VendorID) UnmarshalText added in v3.15.2 

func (v *VendorID) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

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.