EIR (Equipment Identity Register)

Overview

The HSS includes a built-in EIR (Equipment Identity Register) that provides equipment identity verification for mobile devices. The EIR validates IMEI (International Mobile Equipment Identity) numbers to determine if mobile equipment is authorized, stolen, or under observation before allowing network access.

Key Capabilities

• S13 Interface: Equipment identity checking via Diameter protocol
• IMEI Validation: Verify equipment identity using IMEI/IMEISV
• Flexible Matching: Regex-based pattern matching for IMEI, IMEISV, and IMSI
• Three-Tier Classification: Whitelist, blacklist, and greylist support
• Configurable Policies: Customizable behavior for unknown equipment
• REST API: Full CRUD operations for EIR rule management

Architecture

Diameter Interface

Interface	Application ID	Peer	Purpose
S13	16,777,252	MME/SGSN	Equipment identity verification

Equipment Rules Database

The EIR uses a flexible rule-based matching system:

Rule Actions:

• whitelist - Allow equipment
• blacklist - Block equipment
• greylist - Monitor equipment

Regex Patterns: Match against IMEI, IMEISV, or IMSI

Equipment Status Values

Status	Code	Meaning	Network Action
Whitelist	0	Equipment approved	Allow network access
Blacklist	1	Equipment stolen/blocked	Deny network access
Greylist	2	Equipment under observation	Allow with monitoring

S13 Interface

Supported Operations

Equipment Identity Check Request (ECR) / Equipment Identity Check Answer (ECA)

Direction: MME/SGSN → HSS (EIR)

Trigger: MME verifies equipment identity during attach or tracking area update

Request AVPs:

• Session-Id
• Origin-Host, Origin-Realm
• Destination-Realm
• Auth-Session-State
• Terminal-Information
  • IMEI (15 digits)
  • Software-Version (2 digits, optional)
• User-Name (IMSI, optional)
• Vendor-Specific-Application-Id

EIR Actions:

1. Extract IMEI, Software-Version (if present), and IMSI (if present)
2. If IMSI provided:
   • Validate subscriber exists and is enabled
   • Update subscriber state with last seen information
3. Attempt equipment lookup in priority order:
   • IMEISV match (IMEI + Software-Version concatenated)
   • IMEI match (IMEI only)
   • IMSI match (if provided in request)
   • Unknown equipment policy (configured default behavior)
4. Return equipment status

Response AVPs:

• Session-Id (echoed from request)
• Result-Code: 2001 (success)
• Equipment-Status: 0 (whitelist) / 1 (blacklist) / 2 (greylist)

Error Responses:

• Experimental-Result: 5422 (equipment/subscriber not found)
• Experimental-Result: 5012 (general error)

Equipment Matching Logic

Priority Order

The EIR uses a cascading lookup strategy to maximize matching flexibility:

1. IMEISV (IMEI + Software-Version)
   ↓ (if no match)
2. IMEI only
   ↓ (if no match)
3. IMSI (if provided in request)
   ↓ (if no match)
4. Unknown Equipment Policy

Matching Algorithm

Step 1: IMEISV Matching

• Concatenate IMEI + Software-Version: "35979139461611" + "08" = "3597913946161108"
• Test against all EIR rule regex patterns
• Return action ("whitelist", "blacklist", "greylist") of first matching rule

Step 2: IMEI Matching (fallback)

• Use IMEI only: "35979139461611"
• Test against all EIR rule regex patterns
• Return action of first matching rule

Step 3: IMSI Matching (fallback if IMSI provided)

• Use IMSI from request: "999999876543210"
• Test against all EIR rule regex patterns
• Return action of first matching rule
• Use case: Block all equipment for a specific subscriber

Step 4: Unknown Equipment Policy (final fallback)

• Configuration setting: eir_unknown_equipment_behaviour
• Options:
  • :whitelist - Allow unknown equipment (permissive)
  • :blacklist - Block unknown equipment (restrictive)
  • :greylist - Observe unknown equipment (moderate)
  • :reject_unknown_equipment - Return error 5422 (strict)

Regex Pattern Examples

Pattern	Matches	Use Case
"35979139461650"	Exact IMEI	Single device whitelist/blacklist
"3597913946165.*"	IMEI prefix wildcard	Manufacturer/model range
"3597913946161108"	Exact IMEISV	Specific device with software version
"999999876543210"	IMSI	Block all equipment for subscriber
"359791.*"	TAC wildcard	Entire device type allocation

Common Message Flows

Flow 1: Equipment Check - Known Whitelisted IMEI

Flow 2: Equipment Check - Blacklisted IMEI (Stolen Device)

Flow 3: Equipment Check - Unknown Equipment (Whitelist Policy)

Flow 4: Equipment Check - Unknown Equipment (Reject Policy)

Flow 5: Equipment Check - Unknown Subscriber

Flow 6: Equipment Check - IMEISV Match

Flow 7: Equipment Check - IMSI Blocking

REST API

EIR Rule Management

Base path: /api/eir/rule

List All EIR Rules

Request:

GET /api/eir/rule

Response (HTTP 200):

{
  "data": [
    {
      "id": 1,
      "action": "whitelist",
      "regex": "3597913946165.*",
      "inserted_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "action": "blacklist",
      "regex": "35979139461640",
      "inserted_at": "2025-01-16T14:20:00Z",
      "updated_at": "2025-01-16T14:20:00Z"
    }
  ]
}

Get Specific EIR Rule

Request:

GET /api/eir/rule/{id}

Response (HTTP 200):

{
  "data": {
    "id": 1,
    "action": "whitelist",
    "regex": "3597913946165.*"
  }
}

Create EIR Rule

Request:

POST /api/eir/rule
Content-Type: application/json

{
  "action": "blacklist",
  "regex": "35979139461640"
}

Validation:

• action: Required, must be "whitelist", "blacklist", or "greylist"
• regex: Required, must be valid regex pattern, unique across all rules

Response (HTTP 201):

{
  "data": {
    "id": 3,
    "action": "blacklist",
    "regex": "35979139461640"
  }
}

Error Response (HTTP 400):

{
  "errors": {
    "regex": ["has already been taken"]
  }
}

Update EIR Rule (Partial)

Request:

PATCH /api/eir/rule/{id}
Content-Type: application/json

{
  "action": "greylist"
}

Response (HTTP 200):

{
  "data": {
    "id": 3,
    "action": "greylist",
    "regex": "35979139461640"
  }
}

Replace EIR Rule

Request:

PUT /api/eir/rule/{id}
Content-Type: application/json

{
  "action": "whitelist",
  "regex": "359791394616.*"
}

Response (HTTP 200):

{
  "data": {
    "id": 3,
    "action": "whitelist",
    "regex": "359791394616.*"
  }
}

Delete EIR Rule

Request:

DELETE /api/eir/rule/{id}

Response (HTTP 204 No Content)

Configuration

Diameter Service Setup

S13 Application (config/runtime.exs):

%{
  application_name: :s13,
  application_dictionary: :diameter_gen_3gpp_s13,
  vendor_specific_application_ids: [
    %{vendor_id: 10415, auth_application_id: 16_777_252}
  ]
}

Unknown Equipment Behavior

Configure the default behavior for equipment not matching any rules in config/runtime.exs:

Example:

config :hss, :eir,
  unknown_equipment_behaviour: :whitelist

Valid Values:

• :whitelist - Allow unknown equipment (default, permissive)
• :blacklist - Block unknown equipment (restrictive)
• :greylist - Monitor unknown equipment (moderate)
• :reject_unknown_equipment - Return Diameter error 5422 (strict)

Use Cases:

• Development/Testing: :whitelist - Allow all devices
• Production (permissive): :whitelist - Only block known bad devices
• Production (moderate): :greylist - Log unknown devices for review
• Production (strict): :reject_unknown_equipment - Only allow registered devices

Error Handling

Result Code	Type	Meaning	Cause
2001	Success	DIAMETER_SUCCESS	Equipment check completed
5422	Experimental	DIAMETER_ERROR_EQUIPMENT_UNKNOWN	Subscriber not found or unknown equipment rejected
5012	Experimental	DIAMETER_ERROR_UNKNOWN	Processing error

Use Cases

1. Stolen Device Management

Scenario: Device reported stolen

Action:

POST /api/eir/rule
{
  "action": "blacklist",
  "regex": "35979139461640"  # Exact IMEI
}

Result: Device denied network access on next attachment

2. Manufacturer Whitelist

Scenario: Pre-approve entire device model range

Action:

POST /api/eir/rule
{
  "action": "whitelist",
  "regex": "359791394.*"  # TAC for manufacturer/model
}

Result: All devices in TAC range approved

3. Subscriber Equipment Lock

Scenario: Block all equipment for specific subscriber (SIM lock)

Action:

POST /api/eir/rule
{
  "action": "blacklist",
  "regex": "999999876543210"  # IMSI
}

Result: Any equipment used with this SIM is blocked

4. Test Equipment Greylist

Scenario: Monitor test equipment in production

Action:

POST /api/eir/rule
{
  "action": "greylist",
  "regex": "35979139.*"  # Test equipment TAC range
}

Result: Equipment allowed but flagged for monitoring

5. Software Version Control

Scenario: Block specific vulnerable firmware version

Action:

POST /api/eir/rule
{
  "action": "blacklist",
  "regex": "359791394616.*05"  # IMEI range + Software Version 05
}

Result: Only devices with Software-Version "05" in IMEI range blocked

Implementation Details

Internal Components

The EIR functionality is implemented using several internal modules:

• S13 Protocol Handler - ECR/ECA message processing
• Equipment Matching Engine - Regex-based IMEI/IMEISV/IMSI matching
• EIR Rules Database - Pattern storage and lookup
• REST API Controller - Rule management endpoints

Equipment Status Lookup Function

The equipment status lookup follows this cascading logic:

1. IMEISV Matching: Check IMEI + Software-Version concatenated
2. IMEI Matching: Check IMEI only
3. IMSI Matching: Check IMSI (if provided)
4. Unknown Equipment: Apply configured default policy

Possible Results:

• whitelist - Equipment allowed
• blacklist - Equipment blocked
• greylist - Equipment under observation
• reject_unknown_equipment - Strict rejection

Security Considerations

IMEI Privacy

IMEI numbers are sensitive identifiers. The EIR:

• Does not log IMEI values in plaintext by default
• Uses hashed database lookups (if configured)
• Restricts API access to authenticated administrators

Rule Ordering

EIR rules are evaluated in database order (by ID). For conflicting patterns:

Rule 1: regex "359791.*" action "whitelist"  (broad)
Rule 2: regex "35979139461640" action "blacklist"  (specific)

Recommendation: Create specific rules before broad wildcards to ensure blacklist takes precedence.

Rate Limiting

Consider implementing rate limiting on:

• S13 ECR requests from untrusted peers
• REST API EIR rule modifications
• IMEI lookup queries to prevent enumeration attacks

Related Documentation

• Diameter Protocols - S13 protocol specification
• API Reference - Complete API documentation
• Architecture - Overall HSS architecture
• Operations Guide - Operational procedures

Appendix: IMEI Structure

IMEI Format (15 digits)

35 9791 394616 1
│  │    │      └─ Check digit (Luhn algorithm)
│  │    └─ Serial Number (6 digits)
│  └─ FAC (Final Assembly Code, 4 digits)
└─ TAC (Type Allocation Code, 8 digits total including RBI)
   │  └─ RBI (Reporting Body Identifier, 2 digits)
   └─ Manufacturer/Model (6 digits)

IMEISV Format (16 digits)

35 9791 394616 1 08
│  │    │      │ └─ Software Version (2 digits)
└─ IMEI (15 digits)

Example Patterns

IMEI/IMEISV	Pattern	Matches
359791394616108	3597913946161.*	All devices with TAC+FAC+Serial 359791394616*
359791394616140	35979139461614.	All check digits for Serial 359791394616141-9
35979139461640	35979139461640	Exact IMEI match
3597913946163008	3597913946163008	Exact IMEISV (IMEI + SV) match