crypto

Documentation

Overview

Package crypto implements LoRaWAN crypto.

Package crypto implements LoRaWAN crypto.

Index

• func ComputeDownlinkMIC(key types.AES128Key, addr types.DevAddr, confFCnt uint32, fCnt uint32, ...) ([4]byte, error)
• func ComputeJoinAcceptMIC(jsIntKey types.AES128Key, joinReqType byte, joinEUI types.EUI64, ...) ([4]byte, error)
• func ComputeJoinRequestMIC(key types.AES128Key, payload []byte) ([4]byte, error)
• func ComputeLegacyDownlinkMIC(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte) ([4]byte, error)
• func ComputeLegacyJoinAcceptMIC(key types.AES128Key, payload []byte) ([4]byte, error)
• func ComputeLegacyUplinkMIC(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte) ([4]byte, error)
• func ComputePingOffset(beaconTime uint32, devAddr types.DevAddr, pingPeriod uint16) (uint16, error)
• func ComputeRejoinRequestMIC(key types.AES128Key, payload []byte) ([4]byte, error)
• func ComputeUplinkMIC(sNwkSIntKey, fNwkSIntKey types.AES128Key, confFCnt uint32, txDRIdx uint8, ...) ([4]byte, error)
• func ComputeUplinkMICFromLegacy(cmacF [4]byte, sNwkSIntKey types.AES128Key, confFCnt uint32, txDRIdx uint8, ...) ([4]byte, error)
• func Decrypt(key types.AES128Key, encrypted []byte) ([]byte, error)
• func DecryptDownlink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, ...) ([]byte, error)
• func DecryptJoinAccept(key types.AES128Key, encrypted []byte) ([]byte, error)
• func DecryptUplink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, ...) ([]byte, error)
• func DeriveAppSKey(key types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, ...) types.AES128Key
• func DeriveFNwkSIntKey(nwkKey types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, ...) types.AES128Key
• func DeriveJSEncKey(key types.AES128Key, devEUI types.EUI64) types.AES128Key
• func DeriveJSIntKey(key types.AES128Key, devEUI types.EUI64) types.AES128Key
• func DeriveLegacyAppSKey(key types.AES128Key, jn types.JoinNonce, nid types.NetID, dn types.DevNonce) types.AES128Key
• func DeriveLegacyNwkSKey(appKey types.AES128Key, jn types.JoinNonce, nid types.NetID, dn types.DevNonce) types.AES128Key
• func DeriveNwkSEncKey(nwkKey types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, ...) types.AES128Key
• func DeriveSNwkSIntKey(nwkKey types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, ...) types.AES128Key
• func Encrypt(key types.AES128Key, plaintext []byte) ([]byte, error)
• func EncryptDownlink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, ...) ([]byte, error)
• func EncryptJoinAccept(key types.AES128Key, payload []byte) ([]byte, error)
• func EncryptUplink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, ...) ([]byte, error)
• func RegisterCacheHit(ctx context.Context, cache string)
• func RegisterCacheMiss(ctx context.Context, cache string)
• func UnwrapKey(ciphertext, kek []byte) ([]byte, error)
• func WrapKey(plaintext, kek []byte) ([]byte, error)
• type ComponentKEKLabeler
• type KeyVault

Functions

func ComputeDownlinkMIC

func ComputeDownlinkMIC(key types.AES128Key, addr types.DevAddr, confFCnt uint32, fCnt uint32, payload []byte) ([4]byte, error)

ComputeDownlinkMIC computes the Downlink Message Integrity Code. - The payload contains MHDR | FHDR | FPort | FRMPayload - If this downlink has the ACK bit set, confFCnt must be set to the FCnt of the last uplink - The SNwkSIntKey is used

func ComputeJoinAcceptMIC

func ComputeJoinAcceptMIC(jsIntKey types.AES128Key, joinReqType byte, joinEUI types.EUI64, dn types.DevNonce, payload []byte) ([4]byte, error)

ComputeJoinAcceptMIC computes the Message Integrity Code for a join-accept message - The payload contains MHDR | JoinNonce | NetID | DevAddr | DLSettings | RxDelay | (CFList | CFListType) - the joinReqType is 0xFF in reply to a join-request or the rejoin type in reply to a RejoinRequest

func ComputeJoinRequestMIC

func ComputeJoinRequestMIC(key types.AES128Key, payload []byte) ([4]byte, error)

ComputeJoinRequestMIC computes the Message Integrity Code for a join-request message - The payload contains MHDR | JoinEUI/AppEUI | DevEUI | DevNonce - In LoRaWAN 1.0, the AppKey is used - In LoRaWAN 1.1, the NwkKey is used

func ComputeLegacyDownlinkMIC

func ComputeLegacyDownlinkMIC(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte) ([4]byte, error)

ComputeLegacyDownlinkMIC computes the Downlink Message Integrity Code. - The payload contains MHDR | FHDR | FPort | FRMPayload - The NwkSKey is used

func ComputeLegacyJoinAcceptMIC

func ComputeLegacyJoinAcceptMIC(key types.AES128Key, payload []byte) ([4]byte, error)

ComputeLegacyJoinAcceptMIC computes the Message Integrity Code for a join-accept message - The payload contains MHDR | JoinNonce/AppNonce | NetID | DevAddr | DLSettings | RxDelay | (CFList | CFListType) - In LoRaWAN 1.0, the AppKey is used - In LoRaWAN 1.1 with OptNeg=0, the NwkKey is used

func ComputeLegacyUplinkMIC

func ComputeLegacyUplinkMIC(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte) ([4]byte, error)

ComputeLegacyUplinkMIC computes the Uplink Message Integrity Code. - The payload contains MHDR | FHDR | FPort | FRMPayload - The NwkSKey is used

func ComputePingOffset

func ComputePingOffset(beaconTime uint32, devAddr types.DevAddr, pingPeriod uint16) (uint16, error)

func ComputeRejoinRequestMIC

func ComputeRejoinRequestMIC(key types.AES128Key, payload []byte) ([4]byte, error)

ComputeRejoinRequestMIC computes the Message Integrity Code for a RejoinRequest message - For a type 0 or 2 RejoinRequest, the payload contains MHDR | RejoinType | NetID | DevEUI | RJcount0 - For a type 0 or 2 RejoinRequest, the SNwkSIntKey is used - For a type 1 RejoinRequest, the payload contains MHDR | RejoinType | JoinEUI | DevEUI | RJcount1 - For a type 1 RejoinRequest, the JSIntKey is used

func ComputeUplinkMIC

func ComputeUplinkMIC(sNwkSIntKey, fNwkSIntKey types.AES128Key, confFCnt uint32, txDRIdx uint8, txChIdx uint8, addr types.DevAddr, fCnt uint32, payload []byte) ([4]byte, error)

ComputeUplinkMIC computes the Uplink Message Integrity Code. - The payload contains MHDR | FHDR | FPort | FRMPayload - If this uplink has the ACK bit set, confFCnt must be set to the FCnt of the last downlink.

func ComputeUplinkMICFromLegacy

func ComputeUplinkMICFromLegacy(cmacF [4]byte, sNwkSIntKey types.AES128Key, confFCnt uint32, txDRIdx uint8, txChIdx uint8, addr types.DevAddr, fCnt uint32, payload []byte) ([4]byte, error)

ComputeUplinkMICFromLegacy computes the Uplink Message Integrity Code from legacy MIC. - The payload contains MHDR | FHDR | FPort | FRMPayload - If this uplink has the ACK bit set, confFCnt must be set to the FCnt of the last downlink.

func Decrypt

func Decrypt(key types.AES128Key, encrypted []byte) ([]byte, error)

Decrypt decrypts an encrypted message. Uses AES128 keys in GCM (Galois/Counter Mode).

func DecryptDownlink

func DecryptDownlink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, isFOpts bool) ([]byte, error)

DecryptDownlink decrypts a downlink payload - The payload contains the FRMPayload bytes - For FPort>0, the AppSKey is used - For FPort=0, the NwkSEncKey/NwkSKey is used

func DecryptJoinAccept

func DecryptJoinAccept(key types.AES128Key, encrypted []byte) ([]byte, error)

DecryptJoinAccept uses AES Encrypt to decrypt a join-accept message - The returned payload contains JoinNonce/AppNonce | NetID | DevAddr | DLSettings | RxDelay | (CFList | CFListType) | MIC - In LoRaWAN 1.0, the AppKey is used - In LoRaWAN 1.1, the NwkKey or JSEncKey is used

func DecryptUplink

func DecryptUplink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, isFOpts bool) ([]byte, error)

DecryptUplink decrypts an uplink payload - The payload contains the FRMPayload bytes - For FPort>0, the AppSKey is used - For FPort=0, the NwkSEncKey/NwkSKey is used

func DeriveAppSKey

func DeriveAppSKey(key types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, dn types.DevNonce) types.AES128Key

DeriveAppSKey derives the LoRaWAN Application Session Key - If a LoRaWAN 1.1 device joins a LoRaWAN 1.1 network, the AppKey is used as "key"

func DeriveFNwkSIntKey

func DeriveFNwkSIntKey(nwkKey types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, dn types.DevNonce) types.AES128Key

DeriveFNwkSIntKey derives the LoRaWAN 1.1 Forwarding Network Session Integrity Key

func DeriveJSEncKey

func DeriveJSEncKey(key types.AES128Key, devEUI types.EUI64) types.AES128Key

DeriveJSEncKey derives the Join Server Encryption Key

func DeriveJSIntKey

func DeriveJSIntKey(key types.AES128Key, devEUI types.EUI64) types.AES128Key

DeriveJSIntKey derives the Join Server Integrity Key

func DeriveLegacyAppSKey

func DeriveLegacyAppSKey(key types.AES128Key, jn types.JoinNonce, nid types.NetID, dn types.DevNonce) types.AES128Key

DeriveLegacyAppSKey derives the LoRaWAN Application Session Key - If a LoRaWAN 1.0 device joins a LoRaWAN 1.0/1.1 network, the AppKey is used as "key" - If a LoRaWAN 1.1 device joins a LoRaWAN 1.0 network, the NwkKey is used as "key"

func DeriveLegacyNwkSKey

func DeriveLegacyNwkSKey(appKey types.AES128Key, jn types.JoinNonce, nid types.NetID, dn types.DevNonce) types.AES128Key

DeriveLegacyNwkSKey derives the LoRaWAN 1.0 Network Session Key. AppNonce is entered as JoinNonce. - If a LoRaWAN 1.0 device joins a LoRaWAN 1.0/1.1 network, the AppKey is used as "key" - If a LoRaWAN 1.1 device joins a LoRaWAN 1.0 network, the NwkKey is used as "key"

func DeriveNwkSEncKey

func DeriveNwkSEncKey(nwkKey types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, dn types.DevNonce) types.AES128Key

DeriveNwkSEncKey derives the LoRaWAN 1.1 Network Session Encryption Key

func DeriveSNwkSIntKey

func DeriveSNwkSIntKey(nwkKey types.AES128Key, jn types.JoinNonce, joinEUI types.EUI64, dn types.DevNonce) types.AES128Key

DeriveSNwkSIntKey derives the LoRaWAN 1.1 Serving Network Session Integrity Key

func Encrypt

func Encrypt(key types.AES128Key, plaintext []byte) ([]byte, error)

Encrypt encrypts a plain text message. Uses AES128 keys in GCM (Galois/Counter Mode). Since GCM uses a nonce, the encrypted message will be different each time the operation is run for the same set of inputs. The returned cipher is in the format |nonce(12)|tag(16)|encrypted(plaintextLen)|.

func EncryptDownlink

func EncryptDownlink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, isFOpts bool) ([]byte, error)

EncryptDownlink encrypts a downlink payload - The payload contains the FRMPayload bytes - For FPort>0, the AppSKey is used - For FPort=0, the NwkSEncKey/NwkSKey is used

func EncryptJoinAccept

func EncryptJoinAccept(key types.AES128Key, payload []byte) ([]byte, error)

EncryptJoinAccept uses AES Decrypt to encrypt a join-accept message - The payload contains JoinNonce/AppNonce | NetID | DevAddr | DLSettings | RxDelay | (CFList | CFListType) | MIC - In LoRaWAN 1.0, the AppKey is used - In LoRaWAN 1.1, the NwkKey is used in reply to a JoinRequest - In LoRaWAN 1.1, the JSEncKey is used in reply to a RejoinRequest (type 0,1,2)

func EncryptUplink

func EncryptUplink(key types.AES128Key, addr types.DevAddr, fCnt uint32, payload []byte, isFOpts bool) ([]byte, error)

EncryptUplink encrypts an uplink payload - The payload contains the FRMPayload bytes - For FPort>0, the AppSKey is used - For FPort=0, the NwkSEncKey/NwkSKey is used

func RegisterCacheHit

func RegisterCacheHit(ctx context.Context, cache string)

RegisterCacheHit registers a cache hit for the provided cache.

func RegisterCacheMiss

func RegisterCacheMiss(ctx context.Context, cache string)

RegisterCacheMiss registers a cache miss for the provided cache.

func UnwrapKey

func UnwrapKey(ciphertext, kek []byte) ([]byte, error)

UnwrapKey implements the RFC 3394 Unwrap algorithm

func WrapKey

func WrapKey(plaintext, kek []byte) ([]byte, error)

WrapKey implements the RFC 3394 Wrap algorithm

Types

type ComponentKEKLabeler

type ComponentKEKLabeler interface {
	NsKEKLabel(ctx context.Context, netID *types.NetID, addr string) string
	AsKEKLabel(ctx context.Context, addr string) string
}

ComponentKEKLabeler provides KEK labels for components.

type KeyVault

type KeyVault interface {
	ComponentKEKLabeler

	// Wrap implements the RFC 3394 AES Key Wrap algorithm. Only keys of 16, 24 or 32 bytes are accepted.
	// Keys are referenced using the KEK labels.
	Wrap(ctx context.Context, plaintext []byte, kekLabel string) ([]byte, error)
	// UnwrapKey implements the RFC 3394 AES Key Unwrap algorithm. Only keys of 16, 24 or 32 bytes are accepted.
	// Keys are referenced using the KEK labels.
	Unwrap(ctx context.Context, ciphertext []byte, kekLabel string) ([]byte, error)

	// Encrypt encrypts messages of variable length using AES 128 GCM.
	// The encryption key is referenced using the ID.
	Encrypt(ctx context.Context, plaintext []byte, id string) ([]byte, error)
	// Decrypt decrypts messages of variable length using AES 128 GCM.
	// The encryption key is referenced using the ID.
	Decrypt(ctx context.Context, ciphertext []byte, id string) ([]byte, error)

	// GetCertificate gets the X.509 certificate of the given identifier.
	GetCertificate(ctx context.Context, id string) (*x509.Certificate, error)
	// ExportCertificate exports the X.509 certificate and private key of the given identifier.
	ExportCertificate(ctx context.Context, id string) (*tls.Certificate, error)
}

KeyVault provides wrapping and unwrapping keys using KEK labels.