Base Diameter Protocol¶

Overview¶

The Diameter Base Protocol is a fundamental authentication, authorization, and accounting (AAA) protocol used in telecommunications networks. It is the successor to RADIUS and provides enhanced features for reliability, security, and extensibility.

Protocol Structure¶

Message Format¶

Diameter messages consist of a header followed by Attribute-Value Pairs (AVPs):

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    Version    |                 Message Length                   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Command Flags |                  Command Code                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Application-ID                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      Hop-by-Hop Identifier                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      End-to-End Identifier                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  AVPs ...
+-+-+-+-+-+-+-+-+-+-+-+-+-

Common AVPs¶

AVP Name	Code	Description
Session-Id	263	Unique session identifier
Origin-Host	264	Identity of the sender
Origin-Realm	296	Realm of the sender
Destination-Host	293	Identity of the intended recipient
Destination-Realm	283	Realm of the intended recipient
Result-Code	268	Indicates success or failure

Implementation Examples¶

Basic Client Connection¶

from telcoapi.diameter import base

# Initialize Diameter client
client = base.DiameterClient(
    host="client.example.com",
    realm="example.com",
    destination_host="server.example.com",
    destination_realm="example.com"
)

# Connect to peer
client.connect()

# Send Capabilities-Exchange-Request
response = client.send_cer()
print(f"CER Response: {response}")

Handling Watchdog Messages¶

# Configure Device-Watchdog settings
client.set_watchdog_config(
    interval=30,  # seconds
    timeout=10,   # seconds
    retries=3
)

# Register watchdog callback
@client.on_watchdog_timeout
def handle_watchdog_timeout(peer):
    print(f"Lost connection to peer: {peer}")
    # Implement reconnection logic

Vendor Integration¶

Nokia PCRF Integration¶

# Nokia-specific configuration
client.set_vendor_config({
    "vendor_id": 28458,  # Nokia vendor ID
    "product_name": "Nokia PCRF",
    "firmware_revision": 1
})

Ericsson DRA Integration¶

# Ericsson-specific configuration
client.set_vendor_config({
    "vendor_id": 193,    # Ericsson vendor ID
    "product_name": "Ericsson DRA",
    "firmware_revision": 1,
    "dra_features": ["load_balancing", "topology_hiding"]
})

Error Handling¶

Common Error Codes¶

Result Code	Name	Description	Action
3001	DIAMETER_COMMAND_UNSUPPORTED	Command not supported	Check command code
3002	DIAMETER_UNABLE_TO_DELIVER	Unable to deliver message	Verify routing
3003	DIAMETER_REALM_NOT_SERVED	Unknown realm	Check realm configuration
3004	DIAMETER_TOO_BUSY	Server too busy	Implement backoff
3005	DIAMETER_LOOP_DETECTED	Routing loop detected	Check routing config

Error Handling Example¶

from telcoapi.diameter.exceptions import DiameterError

try:
    response = client.send_message(command_code=123)
except DiameterError as e:
    if e.result_code == 3004:  # TOO_BUSY
        # Implement exponential backoff
        retry_with_backoff(e.command)
    else:
        # Log error and take appropriate action
        logger.error(f"Diameter error: {e}")

Monitoring¶

Key Metrics¶

Transaction Response Time
Message Success/Failure Rate
Active Sessions Count
Peer Connection Status
Watchdog Round Trip Time

Monitoring Example¶

# Register monitoring callbacks
@client.on_metrics
def collect_metrics(metrics):
    print(f"Response time: {metrics.response_time}ms")
    print(f"Active sessions: {metrics.active_sessions}")
    print(f"Success rate: {metrics.success_rate}%")

Configuration Examples¶

Basic Configuration¶

diameter:
  host: "client.example.com"
  realm: "example.com"
  port: 3868
  security:
    tls_enabled: true
    certificate: "/path/to/cert.pem"
    private_key: "/path/to/key.pem"
  watchdog:
    interval: 30
    timeout: 10
    retries: 3
  peers:
    - host: "server1.example.com"
      realm: "example.com"
      port: 3868
      role: "server"
    - host: "server2.example.com"
      realm: "example.com"
      port: 3868
      role: "server"

Advanced Configuration¶

diameter:
  host: "client.example.com"
  realm: "example.com"
  port: 3868
  vendor_specific:
    vendor_id: 28458
    product_name: "Example Product"
    firmware_revision: 1
  security:
    tls_enabled: true
    certificate: "/path/to/cert.pem"
    private_key: "/path/to/key.pem"
    cipher_suites:
      - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
      - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
  routing:
    strategy: "round_robin"
    failover_enabled: true
    retry_count: 3
    timeout: 5000
  watchdog:
    interval: 30
    timeout: 10
    retries: 3
  peers:
    - host: "server1.example.com"
      realm: "example.com"
      port: 3868
      role: "server"
      weight: 100
    - host: "server2.example.com"
      realm: "example.com"
      port: 3868
      role: "server"
      weight: 100
  applications:
    - id: 16777216
      vendor_id: 28458
      acct_enabled: true
      auth_enabled: true

Best Practices¶

Always use TLS for secure communication
Implement proper peer failover mechanisms
Monitor and tune watchdog parameters
Use appropriate timeout values
Implement rate limiting
Log all significant events
Use unique Session-Ids
Implement proper AVP validation
Handle retransmissions correctly
Keep connection pools optimized