scadalink-design/lmxproxy/docs/requirements/Component-Security.md

Component: Security

Purpose

Provides API key-based authentication and role-based authorization for the gRPC service, along with TLS certificate management for transport security.

Location

• src/ZB.MOM.WW.LmxProxy.Host/Security/ApiKeyService.cs — API key storage and validation.
• src/ZB.MOM.WW.LmxProxy.Host/Security/ApiKeyInterceptor.cs — gRPC server interceptor for authentication/authorization.
• src/ZB.MOM.WW.LmxProxy.Client/Security/GrpcChannelFactory.cs — Client-side TLS channel factory.

Responsibilities

• Load and hot-reload API keys from a JSON configuration file.
• Validate API keys on every gRPC request via a server interceptor.
• Enforce role-based access control (ReadOnly vs ReadWrite).
• Manage TLS certificates for server and optional mutual TLS.

1. API Key Service

1.1 Key Storage

• Keys are stored in a JSON file (default apikeys.json).
• File format: { "ApiKeys": [{ "Key": "...", "Description": "...", "Role": "ReadOnly|ReadWrite", "Enabled": true|false }] }.
• If the file does not exist at startup, the service auto-generates a default file with two random keys: one ReadOnly and one ReadWrite.

1.2 Hot Reload

• A FileSystemWatcher monitors the API key file for changes.
• Rapid changes are debounced (1-second minimum between reloads).
• ReloadConfigurationAsync uses a SemaphoreSlim to serialize reload operations.
• New and modified keys take effect on the next request. Removed or disabled keys reject future requests immediately.
• Active sessions are not affected by key changes — sessions are tracked independently by SessionManager.

1.3 Validation

• ValidateApiKey(apiKey) — Returns the ApiKey object if the key exists and Enabled is true, otherwise null.
• HasRole(apiKey, requiredRole) — Returns true if the key has the required role. Role hierarchy: ReadWrite implies ReadOnly.

2. API Key Interceptor

2.1 Authentication Flow

The ApiKeyInterceptor intercepts every unary and server-streaming RPC:

1. Extracts the x-api-key header from gRPC request metadata.
2. Calls ApiKeyService.ValidateApiKey().
3. If the key is invalid or missing, returns StatusCode.Unauthenticated.
4. For write-protected methods (Write, WriteBatch, WriteBatchAndWait), checks that the key has the ReadWrite role. Returns StatusCode.PermissionDenied if the key is ReadOnly.
5. Adds the validated ApiKey to context.UserState["ApiKey"] for downstream use.
6. Continues to the service method.

2.2 Write-Protected Methods

These RPCs require the ReadWrite role:

• Write
• WriteBatch
• WriteBatchAndWait

All other RPCs (Connect, Disconnect, GetConnectionState, Read, ReadBatch, Subscribe, CheckApiKey) are allowed for ReadOnly keys.

3. API Key Model

Field	Type	Description
Key	string	The secret API key value
Description	string	Human-readable name for the key
Role	ApiKeyRole	ReadOnly or ReadWrite
Enabled	bool	Whether the key is active

ApiKeyRole enum: ReadOnly (read and subscribe only), ReadWrite (full access including writes).

4. TLS Configuration

4.1 Server-Side (Host)

Configured via TlsConfiguration in appsettings.json:

Setting	Default	Description
Enabled	false	Enable TLS on the gRPC server
ServerCertificatePath	certs/server.crt	PEM server certificate
ServerKeyPath	certs/server.key	PEM server private key
ClientCaCertificatePath	certs/ca.crt	CA certificate for mTLS client validation
RequireClientCertificate	false	Require client certificates (mutual TLS)
CheckCertificateRevocation	false	Check certificate revocation lists

If TLS is enabled but certificates are missing, the service generates self-signed certificates at startup.

4.2 Client-Side

ClientTlsConfiguration in the client library:

Setting	Default	Description
UseTls	false	Enable TLS on the client connection
ClientCertificatePath	null	Client certificate for mTLS
ClientKeyPath	null	Client private key for mTLS
ServerCaCertificatePath	null	Custom CA for server validation
ServerNameOverride	null	SNI/hostname override
ValidateServerCertificate	true	Validate the server certificate chain
AllowSelfSignedCertificates	false	Accept self-signed server certificates
IgnoreAllCertificateErrors	false	Skip all certificate validation (dangerous)

• SSL protocols: TLS 1.2 and TLS 1.3.
• Client certificates loaded from PEM files and converted to PKCS12.
• Custom CA trust store support via chain building.

Dependencies

• Configuration — TLS settings and API key file path from appsettings.json.
• System.IO.FileSystemWatcher — API key file change detection.

Interactions

• GrpcServer — the ApiKeyInterceptor runs before every RPC in ScadaGrpcService.
• ServiceHost — creates ApiKeyService and ApiKeyInterceptor at startup, configures gRPC server credentials.
• Client — GrpcChannelFactory creates TLS-configured gRPC channels in LmxProxyClient.