milenage

README

MILENAGE

MILENAGE algorithm implemented in the Go Programming Language.

Quickstart

Initialize Milenage first with K, OP, RAND, SQN, and AMF.

mil := milenage.New(
	// K
	[]byte{0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff},
	// OP
	[]byte{0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff},
	// RAND
	[]byte{0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff},
	0x000000000001, // SQN
	0x8000,         // AMF
)

Or, with OPc.

mil := milenage.NewWithOPc(
	// K
	[]byte{0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff},
	// OPc
	[]byte{0x62, 0xe7, 0x5b, 0x8d, 0x6f, 0xa5, 0xbf, 0x46, 0xec, 0x87, 0xa9, 0x27, 0x6f, 0x9d, 0xf5, 0x4d},
	// RAND
	[]byte{0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff},
	0x000000000001, // SQN
	0x8000,         // AMF
)

Get MAC-A and MAC-S. This also fills each field.

macA, err := mil.F1()
if err != nil {
	// ...
}

macS, err := mil.F1Star()
if err != nil {
	// ...
}

Get RES, CK, IK, AK. This also fills each field.

res, ck, ik, ak, err := mil.F2345()
if err != nil {
	// ...
}

Get RES* for 5G with ComputeRESStar() by giving MCC and MNC.

resStar, err := mil.ComputeRESStar("001", "01")
if err != nil {
	// ...
}

Get OPc from K and OP. This is not the method on *Milenage. An example program can be found here.

opc, err := milenage.ComputeOPc(
	[]byte{0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff},
	[]byte{0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff},
)
if err != nil {
	// ...
}

Get AUTN and AUTS which are used in authentication procedure. Be sure that the required calculation has done before calling these methods.

autn, err := mil.GenerateAUTN()
if err != nil {
	// ...
}

// Note that this re-calcurates MAC-S and AKS with AMF=0x0000
// as described in 6.3.3, TS 33.102.
auts, err := mil.GenerateAUTS()
if err != nil {
	// ...
}

Fill all fields(except 5G RES*) at once using ComputeAll(). Be sure that this uses the bare AMF value in *Milenage and the MAC-S value might be a unwanted one. Call each function with the right parameters to get the right values.

if err := mil.ComputeAll(); err != nil {
	// ...
}

Notes

This implementation may not pass all of the test cases defined in TS 35.207 because it contains a case whose payload to compute is not aligned to byte, which I believe won't happen in the real-world implementation as of 2022.

Author

Yoshiyuki Kurauchi (Website / Twitter)

License

MIT

Documentation

Overview

Package milenage provides the set of functions of MILENAGE algorithm set defined in 3GPP TS 35.205 and some helpers to be used during the authentication procedure.

Index

• func ComputeOPc(k, op []byte) ([]byte, error)
• type Milenage
  • func New(k, op, rand []byte, sqn uint64, amf uint16) *Milenage
  • func NewWithOPc(k, opc, rand []byte, sqn uint64, amf uint16) *Milenage
  • func (m *Milenage) ComputeAll() error
  • func (m *Milenage) ComputeRESStar(mcc, mnc string) ([]byte, error)
  • func (m *Milenage) F1() ([]byte, error)
  • func (m *Milenage) F1Star(sqn, amf []byte) ([]byte, error)
  • func (m *Milenage) F2345() (res, ck, ik, ak []byte, err error)
  • func (m *Milenage) F5Star() (aks []byte, err error)
  • func (m *Milenage) GenerateAUTN() ([]byte, error)
  • func (m *Milenage) GenerateAUTS() ([]byte, error)

Functions

func ComputeOPc

func ComputeOPc(k, op []byte) ([]byte, error)

ComputeOPc is a helper that provides users to retrieve OPc value from the K and OP given.

Types

type Milenage

type Milenage struct {
	// K is a 128-bit subscriber key that is an input to the functions f1, f1*, f2, f3, f4, f5 and f5*.
	K []byte
	// OP is a 128-bit Operator Variant Algorithm Configuration Field that is a component of the
	// functions f1, f1*, f2, f3, f4, f5 and f5*.
	OP []byte
	// OPc is a 128-bit value derived from OP and K and used within the computation of the functions.
	OPc []byte
	// RAND is a 128-bit random challenge that is an input to the functions f1, f1*, f2, f3, f4, f5 and f5*.
	RAND []byte

	// SQN is a 48-bit sequence number that is an input to either of the functions f1 and f1*.
	// (For f1* this input is more precisely called SQNMS.)
	SQN []byte
	// AMF is a 16-bit authentication management field that is an input to the functions f1 and f1*.
	AMF []byte

	// MACA is a 64-bit network authentication code that is the output of the function f1.
	MACA []byte
	// MACS is a 64-bit resynchronisation authentication code that is the output of the function f1*.
	MACS []byte

	// RES is a 64-bit signed response that is the output of the function f2.
	RES []byte
	// CK is a 128-bit confidentiality key that is the output of the function f3.
	CK []byte
	// IK is a 128-bit integrity key that is the output of the function f4.
	IK []byte
	// AK is a 48-bit anonymity key that is the output of either of the functions f5.
	AK []byte
	// AKS is a 48-bit anonymity key that is the output of either of the functions f5*.
	AKS []byte

	// RESStar or RES* is a 128-bit response that is used in 5G.
	RESStar []byte
}

Milenage is a set of parameters used/generated in MILENAGE algorithm.

func New

func New(k, op, rand []byte, sqn uint64, amf uint16) *Milenage

New initializes a new MILENAGE algorithm.

func NewWithOPc

func NewWithOPc(k, opc, rand []byte, sqn uint64, amf uint16) *Milenage

NewWithOPc initializes a new MILENAGE algorithm using OPc instead of OP.

func (*Milenage) ComputeAll

func (m *Milenage) ComputeAll() error

ComputeAll fills all the fields in *Milenage struct.

func (*Milenage) ComputeRESStar

func (m *Milenage) ComputeRESStar(mcc, mnc string) ([]byte, error)

ComputeRESStar computes RESStar from serving network name, RAND and RES as described in A.4 RES* and XRES* derivation function, TS 33.501.

Note that this function should be called after all other calculations is done (to generate RAND and RES).

func (*Milenage) F1

func (m *Milenage) F1() ([]byte, error)

F1 is the network authentication function. F1 computes network authentication code MAC-A from key K, random challenge RAND, sequence number SQN and authentication management field AMF.

func (*Milenage) F1Star

func (m *Milenage) F1Star(sqn, amf []byte) ([]byte, error)

F1Star is the re-synchronisation message authentication function. F1Star computes resynch authentication code MAC-S from key K, random challenge RAND, sequence number SQN and authentication management field AMF.

Note that the AMF value should be zero to be compliant with the specification TS 33.102 6.3.3 (This method just computes with the given value).

func (*Milenage) F2345

func (m *Milenage) F2345() (res, ck, ik, ak []byte, err error)

F2345 takes key K and random challenge RAND, and returns response RES, confidentiality key CK, integrity key IK and anonymity key AK.

func (*Milenage) F5Star

func (m *Milenage) F5Star() (aks []byte, err error)

F5Star is the anonymity key derivation function for the re-synchronisation message. F5Star takes key K and random challenge RAND, and returns resynch anonymity key AK.

func (*Milenage) GenerateAUTN

func (m *Milenage) GenerateAUTN() ([]byte, error)

GenerateAUTN generates AUTN uing the current values in Milenage in the way described in 5.1.1.1, TS 33.105 and 6.3.2, TS 33.102.

func (*Milenage) GenerateAUTS

func (m *Milenage) GenerateAUTS() ([]byte, error)

GenerateAUTS generates AUTS using the current values in Milenage in the way described in 5.1.1.3, TS 33.105 and 6.3.3, TS 33.102.

Note: MAC-S and AK-S are re-calculated with AMF=0x0000.