Telecom Authentication Center (AuC)

Production-grade Go implementation of a 3GPP-compliant Authentication Center for GSM/UMTS/LTE/5G networks.

Enterprise Authentication Center (AuC) for mobile telecommunications. Implements 3GPP TS 33.102, TS 35.205-209 MILENAGE algorithm set and GSM COMP128 for subscriber authentication across 2G (GSM), 3G (UMTS), 4G (LTE), and 5G (NR) networks. Production-ready with PostgreSQL persistence, Prometheus metrics, and HSM integration support.

Overview

The Authentication Center (AuC) is a critical security element in telecom networks (2G/3G/4G/5G). It is responsible for:

Securely storing subscriber authentication keys (Ki)
Generating authentication vectors (AVs) for network authentication
Verifying subscriber responses during the authentication challenge
Managing sequence numbers (SQN) for replay attack prevention
Deriving session keys (CK, IK) for ciphering and integrity protection

Implemented Standards

Standard	Description	Status
3GPP TS 35.206	Milenage Algorithm	✅ Complete
3GPP TS 33.102	3G Security Architecture	✅ Complete
3GPP TS 33.401	LTE/EPS Security	✅ Complete
3GPP TS 33.501	5G System Security	✅ Complete
GSM 03.20	Security-Related Network Functions	✅ Complete

Authentication Algorithms

Algorithm	Network	Key Size	Output
Milenage	UMTS/LTE/5G	128-bit	RAND, XRES, CK, IK, AUTN
COMP128-3	GSM	64-bit	RAND, SRES, Kc
5G-AKA	5G	128-bit	RAND, XRES, CK, IK, AUTN, HXRES

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AuC Server (Go 1.23)                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │              HTTP API Layer                         │    │
│  │  Middleware: Auth → Rate Limit → Logger → Security  │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                   │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │              Use Case Layer                         │    │
│  │  • AuthService (vector generation, verification)    │    │
│  │  • SubscriberService (CRUD, status management)      │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                   │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │           Cryptographic Algorithms                  │    │
│  │  • Milenage (f1-f5 functions, AES-128 based)        │    │
│  │  • COMP128-3 (GSM A3/A8)                            │    │
│  │  • 5G Key Derivation (XRES*, HXRES*)                │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │                                   │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │              Repository Layer                       │    │
│  │  • PostgreSQL (pgx/v5 connection pool)              │    │
│  │  • Subscriber persistence, SQN management           │    │
│  │  • Audit logging                                    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

Go 1.23+
PostgreSQL 15+
Docker & Docker Compose (optional)

Option 1: Docker Compose (Recommended)

# Start everything (PostgreSQL + AuC Server)
make docker-up

# Or directly:
docker-compose up -d --build

Option 2: Manual Setup

# 1. Clone and enter
cd auc

# 2. Download dependencies
make deps

# 3. Run PostgreSQL
docker run -d --name postgres \
  -e POSTGRES_USER=auc_user \
  -e POSTGRES_PASSWORD=auc_secure_password \
  -e POSTGRES_DB=auc_db \
  -p 5432:5432 postgres:16-alpine

# 4. Run migrations
psql "postgres://auc_user:auc_secure_password@localhost:5432/auc_db" \
  -f migrations/001_initial.sql

# 5. Seed test data
chmod +x scripts/seed.sh
./scripts/seed.sh "postgres://auc_user:auc_secure_password@localhost:5432/auc_db"

# 6. Build and run
make run

API Reference

Authentication

All authenticated endpoints require the X-AUC-API-Key header:

export AUC_API_KEY="your-api-key-here"

Health Check

curl http://localhost:8080/health

Register Subscriber

curl -X POST http://localhost:8080/api/v1/subscribers \
  -H "X-AUC-API-Key: $AUC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "310410123456789",
    "ki_hex": "23232323232323232323232323232323",
    "op_hex": "22222222222222222222222222222222",
    "network_type": "LTE",
    "amf_hex": "8000"
  }'

Generate UMTS/LTE Authentication Vectors

curl -X POST http://localhost:8080/api/v1/auth/umts/vectors \
  -H "X-AUC-API-Key: $AUC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imsi": "310410123456789", "count": 5}'

Response:

{
  "imsi": "310410123456789",
  "network": "UMTS/LTE",
  "count": 5,
  "vectors": [
    {
      "rand": "a1b2c3d4e5f6...",
      "xres": "1234567890ab...",
      "ck": "abcdef0123456789...",
      "ik": "9876543210fedcba...",
      "autn": "0011223344556677..."
    }
  ]
}

Generate 5G-AKA Vectors

curl -X POST http://localhost:8080/api/v1/auth/5g/vectors \
  -H "X-AUC-API-Key: $AUC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imsi": "310410987654321", "count": 5}'

Generate GSM Vectors

curl -X POST http://localhost:8080/api/v1/auth/gsm/vectors \
  -H "X-AUC-API-Key: $AUC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imsi": "310410123456789", "count": 3}'

Verify Authentication

curl -X POST http://localhost:8080/api/v1/auth/verify \
  -H "X-AUC-API-Key: $AUC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "310410123456789",
    "rand": "a1b2c3d4e5f6...",
    "res": "1234567890ab..."
  }'

List Subscribers

curl http://localhost:8080/api/v1/subscribers \
  -H "X-AUC-API-Key: $AUC_API_KEY"

Get Subscriber

curl http://localhost:8080/api/v1/subscribers/310410123456789 \
  -H "X-AUC-API-Key: $AUC_API_KEY"

Update Subscriber Status

curl -X PATCH http://localhost:8080/api/v1/subscribers/310410123456789/status \
  -H "X-AUC-API-Key: $AUC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "barred"}'

Testing

# Run all tests
make test

# Verbose output
make test-verbose

# Coverage report
make test-coverage

Test Coverage

The Milenage algorithm is tested against 3GPP TS 35.906 test vectors:

OPc derivation verification
Full vector generation (RAND, XRES, CK, IK, AUTN)
Deterministic output verification
SQN uniqueness validation
Input validation and error handling
AES block cipher correctness (NIST vectors)

Security

Production Hardening Checklist

Data Protection

Ki and OPc are stored as BYTEA (binary) — never exposed in hex via API
API responses never include secret key material
All authentication operations are logged to the audit table
Rate limiting prevents brute-force attacks
SQN management prevents replay attacks

Project Structure

auc/
├── cmd/server/
│   └── main.go                 # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go           # Environment-based configuration
│   ├── domain/
│   │   ├── subscriber.go       # Domain entities & DTOs
│   │   └── errors.go           # Domain-specific errors
│   ├── repository/
│   │   └── subscriber.go       # Repository interface
│   ├── postgres/
│   │   └── subscriber_repo.go  # PostgreSQL implementation
│   ├── usecase/
│   │   ├── auth.go             # Authentication business logic
│   │   └── subscriber.go       # Subscriber management logic
│   ├── delivery/http/
│   │   ├── handlers.go         # HTTP request handlers
│   │   └── middleware.go       # Auth, rate limiting, logging
│   ├── algorithm/
│   │   ├── milenage.go         # 3GPP Milenage (f1-f5)
│   │   ├── milenage_test.go    # Algorithm unit tests
│   │   ├── comp128.go          # GSM COMP128 algorithm
│   │   └── rijndael.go         # AES-128 block cipher
│   └── security/
│       └── key.go              # 5G key derivation functions
├── migrations/
│   └── 001_initial.sql         # Database schema
├── scripts/
│   └── seed.sh                 # Test data seeder
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── README.md

🔧 Configuration

All configuration via environment variables:

Variable	Default	Description
`DATABASE_URL`	`postgres://...`	PostgreSQL connection string
`AUC_SERVER_HOST`	`0.0.0.0`	Server bind address
`AUC_SERVER_PORT`	`8080`	Server port
`AUC_API_KEY`	`change-me-in-production`	API authentication key
`AUC_RATE_LIMIT_PER_MIN`	`100`	Rate limit per IP
`AUC_SQN_MAX_AHEAD`	`256`	Max SQN ahead threshold
`AUC_SQN_DELTA`	`32`	Max SQN behind threshold
`AUC_VECTOR_BATCH_SIZE`	`5`	Default vector batch size
`AUC_LOG_LEVEL`	`info`	Log level (debug/info/warn/error)
`AUC_LOG_FORMAT`	`json`	Log format (json/console)

📚 Telecom Background

How Authentication Works in Telecom

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│   UE/SIM │     │  MSC/MME │     │   HLR    │     │   AuC    │
│  (Phone) │     │  (RAN)   │     │(Subscriber│     │(Auth Ctr)│
│          │     │          │     │  Database)│     │          │
└────┬─────┘     └────┬─────┘     └─────┬─────┘     └────┬─────┘
     │                │                 │                 │
     │  1. Attach     │                 │                 │
     │ ──────────────>│                 │                 │
     │                │  2. Auth Info   │                 │
     │                │    Request      │                 │
     │                │ ───────────────>│                 │
     │                │                 │  3. Get Vectors │
     │                │                 │ ───────────────>│
     │                │                 │                 │
     │                │                 │  4. Generate AVs│
     │                │                 │    (Milenage)   │
     │                │                 │ <───────────────│
     │                │  5. Return AVs  │                 │
     │                │ <───────────────│                 │
     │  6. RAND+AUTN  │                 │                 │
     │ <──────────────│                 │                 │
     │                │                 │                 │
     │  7. Verify     │                 │                 │
     │    Network     │                 │                 │
     │    (check AUTN)│                 │                 │
     │                │                 │                 │
     │  8. Send RES   │                 │                 │
     │ ──────────────>│                 │                 │
     │                │  9. Verify RES  │                 │
     │                │ ───────────────>│                 │
     │                │                 │ ───────────────>│
     │                │  10. Auth OK    │                 │
     │                │ <───────────────│                 │
     │  11. Service   │                 │                 │
     │    Granted     │                 │                 │
     │ <──────────────│                 │                 │

Key Terms

IMSI — International Mobile Subscriber Identity (unique per SIM)
Ki — Secret 128-bit key burned into the SIM card
OP — Operator code (secret, operator-specific)
OPc — Derived from OP and Ki: OPc = E_K(OP) XOR OP
SQN — Sequence Number (prevents replay attacks, 48-bit)
RAND — Random challenge (16 bytes)
AUTN — Authentication Token (proves network legitimacy)
RES/XRES — Response / Expected Response
CK — Ciphering Key (encrypts air traffic)
IK — Integrity Key (protects signaling integrity)

📜 License

This is an educational/reference implementation for telecom professionals. For production use, ensure compliance with your operator's security policies and 3GPP standards.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
cmd/server		cmd/server
internal		internal
migrations		migrations
scripts		scripts
.env.example		.env.example
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

Telecom Authentication Center (AuC)

Overview

Implemented Standards

Authentication Algorithms

Architecture

Quick Start

Prerequisites

Option 1: Docker Compose (Recommended)

Option 2: Manual Setup

API Reference

Authentication

Health Check

Register Subscriber

Generate UMTS/LTE Authentication Vectors

Generate 5G-AKA Vectors

Generate GSM Vectors

Verify Authentication

List Subscribers

Get Subscriber

Update Subscriber Status

Testing

Test Coverage

Security

Production Hardening Checklist

Data Protection

Project Structure

🔧 Configuration

📚 Telecom Background

How Authentication Works in Telecom

Key Terms

📜 License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages