milenage

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2020 License: BSD-3-Clause Imports: 8 Imported by: 0

README

milenage

Go implementation of milenage ciphers

This implementation is a standalone refactor of magma's milenage crypto functions to allow the standalone module use.

Documentation

Overview

This source code is licensed under the BSD-style license found in the LICENSE file in the root directory of this source tree.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

View Source 
const (
	// ExpectedKeyBytes is the number of bytes for the subscriber key.
	ExpectedKeyBytes = 16
	// ExpectedOpcBytes is the number of bytes for the operator variant algorithm configuration field.
	ExpectedOpcBytes = 16
	// ExpectedPlmnBytes is the number of bytes for the network identifier.
	ExpectedPlmnBytes = 3
	// ExpectedAmfBytes is the number of bytes for the authentication management field.
	ExpectedAmfBytes = 2
	// ExpectedOpBytes is the number of bytes for the operator variant configuration field.
	ExpectedOpBytes = 16
	// ExpectedAutsBytes is the number of bytes for the authentication token from the client key.
	ExpectedAutsBytes = 14
	// RandChallengeBytes is the number of bytes for the random challenge.
	RandChallengeBytes = 16
	// XresBytes is the number of bytes for the expected response.
	XresBytes = 8
	// AutnBytes is the number of bytes for the authentication token.
	AutnBytes = 16
	// KasmeBytes is the number of bytes for the base network authentication token.
	KasmeBytes = 32
	// ConfidentialityKeyBytes is the number of bytes for the confidentiality key.
	ConfidentialityKeyBytes = 16
	// IntegrityKeyBytes is the number of bytes for the integrity key.
	IntegrityKeyBytes = 16
	// AnonymityKeyBytes is the number of bytes for the anonymity key.
	AnonymityKeyBytes = 16

	// The highest valid sequence number (since sequence numbers are 48 bits).
	MaxSqn = (1 << 48) - 1
)

Variables

This section is empty.

Functions

func F1 

func F1(key, sqn, rand, opc, amf []byte) ([]byte, []byte, error)

f1 and f1* implementation, the network authentication function and the re-synchronisation message authentication function according to 3GPP 35.206 4.1

Inputs: 

key: 128 bit subscriber key
sqn: 48 bit sequence number
rand: 128 bit random challenge
opc: 128 bit computed from OP and subscriber key
amf: 16 bit authentication management field

Outputs: (64 bit Network auth code, 64 bit Resync auth code) or an error

func F2F5 

func F2F5(key, rand, opc []byte) ([]byte, []byte, error)

f2F5 implements f2 and f5, the compute anonymity key and response to challenge functions according to 3GPP 35.206 4.1 Inputs: 

  key: 128 bit subscriber key
  rand: 128 bit random challenge
  opc: 128 bit computed from OP and subscriber key
	Outputs:
  (xres, ak) = (64 bit response to challenge, 48 bit anonymity key) or an error

func F3 

func F3(key, rand, opc []byte) ([]byte, error)

f3 implementation, the compute confidentiality key according to 3GPP 35.206 4.1

Inputs: 

key: 128 bit subscriber key
rand: 128 bit random challenge
opc: 128 bit computed from OP and subscriber key

Outputs: 128 bit confidentiality key or an error

func F4 

func F4(key, rand, opc []byte) ([]byte, error)

f4 implementation, the integrity key according to 3GPP 35.206 4.1

Inputs: 

key: 128 bit subscriber key
rand: 128 bit random challenge
opc: 128 bit computed from OP and subscriber key

Outputs: 128 bit integrity key or an error

func F5Star 

func F5Star(key, rand, opc []byte) ([]byte, error)

f5* implementation, the anonymity key according to 3GPP 35.206 4.1 Inputs: 

key: 128 bit subscriber key
rand: 128 bit random challenge
opc: 128 bit computed from OP and subscriber key

Outputs: ak, 48 bit anonymity key or an error

func GenerateAutn 

func GenerateAutn(sqn, ak, macA, amf []byte) []byte

GenerateAutn generates network authentication tokens as defined in 3GPP 25.205 7.2

Inputs: 

sqn: 48 bit sequence number
ak: 48 bit anonymity key
macA: 64 bit network authentication code
amf: 16 bit authentication management field

Outputs: 128 bit authentication token

func GenerateKasme 

func GenerateKasme(ck, ik, plmn, sqn, ak []byte) ([]byte, error)

GenerateKasme is the KASME derivation function (S_2) according to 3GPP 33.401 Annex A.2. This function creates an input string to a key derivation function.

The input string to the KDF is composed of 2 input parameters P0, P1 and their lengths L0, L1 a constant FC which identifies this algorithm. 

S = FC || P0 || L0 || P1 || L1

The FC = 0x10 and argument P0 is the 3 octets of the PLMN, and P1 is SQN XOR AK. The lengths are in bytes.

The Kasme is computed by calling the key derivation function with S using key CK || IK

Inputs: 

ck: 128 bit confidentiality key
ik: 128 bit integrity key
plmn: 24 bit network identifier
   Octet           Description
      1      MCC digit 2 | MCC digit 1
      2      MNC digit 3 | MCC digit 3
      3      MNC digit 2 | MNC digit 1
sqn: 48 bit sequence number
ak: 48 bit anonymity key

Outputs: 256 bit network base key or an error

func GenerateOpc 

func GenerateOpc(key, op []byte) ([ExpectedOpcBytes]byte, error)

GenerateOpc returns the OP_c according to 3GPP 35.205 8.2 Inputs: 

key: 128 bit subscriber key
op: 128 bit operator variant configuration field

func Rotate 

func Rotate(arr []byte, k int) []byte

Rotate a byte array by a number (k >= 0) of bytes

func ValidateGenerateEutranVectorInputs 

func ValidateGenerateEutranVectorInputs(key []byte, opc []byte, sqn uint64, plmn []byte) error

ValidateGenerateEutranVectorInputs ensures that each argument has the required form. Each byte slice must be the correct number of bytes and sqn must fit within 48 bits. Output: An error if any of the arguments is invalid or nil otherwise.

func ValidateGenerateResyncInputs 

func ValidateGenerateResyncInputs(auts, key, opc, rand []byte) error

ValidateGenerateResyncInputs ensures that each byte slice has the correct number of bytes. Output: An error if any of the arguments is invalid or nil otherwise.

func ValidateGenerateSIPAuthVectorInputs 

func ValidateGenerateSIPAuthVectorInputs(key []byte, opc []byte, sqn uint64) error

validateGenerateSIPAuthVectorInputs ensures that each argument has the required form. Each byte slice must be the correct number of bytes and sqn must fit within 48 bits. Output: An error if any of the arguments is invalid or nil otherwise.

func ValidateGenerateSIPAuthVectorWithRandInputs 

func ValidateGenerateSIPAuthVectorWithRandInputs(rand []byte, key []byte, opc []byte, sqn uint64) error

validateGenerateSIPAuthVectorWithRandInputs ensures that each argument has the required form. Each byte slice must be the correct number of bytes and sqn must fit within 48 bits. Output: An error if any of the arguments is invalid or nil otherwise.

Types

type Cipher 

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

Cipher implements the milenage algorithm (3GPP TS 35.205, .206, .207, .208)

func NewCipher 

func NewCipher(amf []byte) (*Cipher, error)

NewCipher instantiates the Milenage algo using crypto/rand for rng.

func NewMockCipher 

func NewMockCipher(amf []byte, rand []byte) (*Cipher, error)

NewMockCipher instantiates the Milenage algo using non-mutable mockRNG for rng

func (*Cipher) GenerateEutranVector 

func (milenage *Cipher) GenerateEutranVector(key, opc []byte, sqn uint64, plmn []byte) (*EutranVector, error)

GenerateEutranVector creates an E-UTRAN key vector. Inputs: 

key: 128 bit subscriber key
opc: 128 bit operator variant algorithm configuration field
sqn: 48 bit sequence number
plmn: 24 bit network identifier
   Octet           Description
      1      MCC digit 2 | MCC digit 1
      2      MNC digit 3 | MCC digit 3
      3      MNC digit 2 | MNC digit 1

Outputs: An EutranVector or an error. The EutranVector is not nil if and only if err == nil.

func (*Cipher) GenerateEutranVectorWithRand 

func (milenage *Cipher) GenerateEutranVectorWithRand(
	key, opc, rand []byte, sqn uint64, plmn []byte) (*EutranVector, error)

GenerateEutranVectorWithRand creates an E-UTRAN key vector. Inputs: 

key:  128 bit subscriber key
opc:  128 bit operator variant algorithm configuration field
rand: 128 bit random challenge
sqn:  48 bit sequence number
plmn: 24 bit network identifier
   Octet           Description
      1      MCC digit 2 | MCC digit 1
      2      MNC digit 3 | MCC digit 3
      3      MNC digit 2 | MNC digit 1

Outputs: An EutranVector or an error. The EutranVector is not nil if and only if err == nil.

func (*Cipher) GenerateResync 

func (milenage *Cipher) GenerateResync(auts, key, opc, rand []byte) (uint64, [8]byte, error)

GenerateResync computes SQN_MS and MAC-S from AUTS for re-synchronization. 

AUTS = SQN_MS ^ AK || f1*(SQN_MS || RAND || AMF*)

Inputs: 

auts: 112 bit authentication token from client key
opc: 128 bit operator variant algorithm configuration field
key: 128 bit subscriber key
rand: 128 bit random challenge

Outputs: (sqnMs, macS) or an error 

sqn_ms, 48 bit sequence number from client
mac_s, 64 bit resync authentication code

func (*Cipher) GenerateSIPAuthVector 

func (milenage *Cipher) GenerateSIPAuthVector(key []byte, opc []byte, sqn uint64) (*SIPAuthVector, error)

GenerateSIPAuthVector creates a SIP auth vector. Inputs: 

key: 128 bit subscriber key
opc: 128 bit operator variant algorithm configuration field
sqn: 48 bit sequence number

Outputs: A SIP auth vector or an error. The SIP auth vector is not nil if and only if err == nil.

func (*Cipher) GenerateSIPAuthVectorWithRand 

func (milenage *Cipher) GenerateSIPAuthVectorWithRand(rand []byte, key []byte, opc []byte, sqn uint64) (*SIPAuthVector, error)

GenerateSIPAuthVectorWithRand creates a SIP auth vector using a specific random challenge value. Inputs: 

rand: 128 bit random challenge
key:  128 bit subscriber key
opc:  128 bit operator variant algorithm configuration field
sqn:  48 bit sequence number

Outputs: A SIP auth vector or an error. The SIP auth vector is not nil if and only if err == nil.

func (*Cipher) GenerateUtranVector 

func (milenage *Cipher) GenerateUtranVector(key, opc []byte, sqn uint64) (*UtranVector, error)

GenerateUtranVector creates UTRAN auth vector Inputs: 

key:  128 bit subscriber key
opc:  128 bit operator variant algorithm configuration field
sqn:  48 bit sequence number

Outputs: A E-UTRAN & UTRAN auth vector or an error

func (*Cipher) GenerateUtranVectorWithRand 

func (milenage *Cipher) GenerateUtranVectorWithRand(key, opc, rand []byte, sqn uint64) (*UtranVector, error)

GenerateUtranVectorWithRand creates UTRAN auth vector Inputs: 

key:  128 bit subscriber key
opc:  128 bit operator variant algorithm configuration field
rand: 128 bit random challenge
sqn:  48 bit sequence number

Outputs: A E-UTRAN & UTRAN auth vector or an error

func (*Cipher) SetRng 

func (c *Cipher) SetRng(newRng io.Reader)

SetRng sets Random generator reader for cipher

type EutranVector 

type EutranVector struct {
	// Rand is a random challenge
	Rand [RandChallengeBytes]byte
	// Xres is the expected response
	Xres [XresBytes]byte
	// Autn is an authentication token
	Autn [AutnBytes]byte
	// Kasme is a base network authentication token
	Kasme [KasmeBytes]byte
}

EutranVector reprsents an E-UTRAN key vector.

type SIPAuthVector 

type SIPAuthVector struct {
	// Rand is a random challenge
	Rand [RandChallengeBytes]byte
	// Xres is the expected response
	Xres [XresBytes]byte
	// Autn is an authentication token
	Autn [AutnBytes]byte
	// Confidentialitykey is used to ensure the confidentiality of messages
	ConfidentialityKey [ConfidentialityKeyBytes]byte
	// IntegrityKey is u
	// sed to ensure the integrity of messages
	IntegrityKey [IntegrityKeyBytes]byte
	// AnonymityKey is used to ensure the anonymity of messages
	AnonymityKey [AnonymityKeyBytes]byte
}

SIPAuthVector represents the data encoded in a SIP auth data item.

type UtranVector 

type UtranVector struct {
	// Rand is a random challenge
	Rand [RandChallengeBytes]byte
	// Xres is the expected response
	Xres [XresBytes]byte
	// Autn is an authentication token
	Autn [AutnBytes]byte
	// Confidentialitykey is used to ensure the confidentiality of messages
	ConfidentialityKey [ConfidentialityKeyBytes]byte
	// IntegrityKey is used to ensure the integrity of messages
	IntegrityKey [IntegrityKeyBytes]byte
}

UtranVector represents a UTRAN key vector

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.