ETA Signing Agent and Console

The EGKits ETA Signing Agent is a Windows app that signs ETA documents with the company's USB tax token (Egypt Trust, SafeNet, ePass2003). EGKits runs in the cloud and cannot reach a token plugged into your computer, so the agent does the signing locally and sends back only the signature. The private key stays inside the token.

The EGKits Signing Agent Console is a Windows app for checking and managing the agent: its tokens, certificates, settings, logs, and security events. Version 1.3.0 adds live views of the server's ETA configuration, certificate assignments, and the server's history of signing jobs with a next step for each one.

Download the installer from Downloads → ETA Signing Agent.

#How signing works

sequenceDiagram
  participant App as EGKits (cloud)
  participant Agent as Signing Agent (your PC)
  participant Token as USB token
  participant ETA as ETA portal
  Agent->>App: Ask for documents to sign (registered device identity)
  App-->>Agent: Canonical document
  Agent->>Token: Sign with the token's private key (PIN from the encrypted store)
  Token-->>Agent: CAdES-BES signature
  Agent->>App: Signature only
  App->>App: Verify signature, certificate, and taxpayer
  App->>ETA: Submit the signed document
  ETA-->>App: Accepted or rejected

EGKits verifies every signature itself before submission. A success reported by the agent is never treated as proof of a valid signature.

#Install

The installer adds two Start Menu shortcuts: EGKits ETA Signing Agent (the tray agent) and EGKits Signing Agent Console.

#First run

1. Start EGKits Signing Agent Console from the Start Menu, or double-click the agent's tray icon.
2. Choose Restart as administrator in the console header. Viewing status works for any local user; registering, setting PINs, scanning tokens, and changing settings need an elevated console.
3. Open Agent & Connection Settings, paste the registration key, and register the computer.
4. Set the token PIN for each company's token. The PIN goes straight to the agent's encrypted store on this computer and the field is cleared at once.
5. Open Dashboard and confirm the agent, server connection, token, and certificate are healthy.
6. In EGKits, confirm the computer shows as Active with its certificates on the Signing devices page.

The tray menu keeps the quick actions: Open console, Register device…, and Set token PIN….

#Console sections

The four configuration sections and the server history are read-only. They come from EGKits through the computer's device identity and carry no ETA client secret, access token, or PIN. Users with the ETA configuration permission change them in EGKits.

The console never signs and never holds a private key. Every action goes through the running agent.

#Certificate assignments

An assignment binds one certificate on one signing computer to one ETA e-invoice configuration. Once a configuration has an assignment, EGKits accepts its invoices' signatures only from assigned certificates. It also stops handing those invoices to computers without an assignment.

1. In EGKits, open E-Invoices → ETA Signing Devices (also under system settings). You need the ETA configuration permission.
2. Find the computer. Its reported certificates are listed under it.
3. Choose the link icon beside a certificate, then pick the configuration it signs for. Only e-invoice configurations of the certificate's own taxpayer appear.
4. Confirm. The assignment appears as a chip on the certificate and in the console under Signing Assignments.

To remove an assignment, close its chip and confirm. Every change is recorded and raises a security alert.

EGKits refuses an assignment when:

• the computer is revoked or not active;
• the computer never reported the certificate;
• the certificate has expired;
• the configuration is an e-receipt configuration (e-receipts use POS credentials and no certificate);
• the certificate's taxpayer differs from the configuration's company.

A configuration without assignments works as before: any active computer holding the taxpayer's certificate may sign, and EGKits still verifies every signature.

#Signing jobs and next steps

Signing Jobs → Server history lists the signing sessions this computer held, as EGKits recorded them. The console shows the server's guidance. Each action runs on the invoice in EGKits under your invoice permissions; the agent's device identity never resubmits a document.

Local activity remains a record of what the agent did since it started. The server history is the record of what was signed and submitted.

#Security model

• Private keys stay in the token. Signing runs inside the token's own cryptographic provider.
• Secrets stay encrypted on the signing computer. Token PINs and the device secret are kept in a Windows DPAPI-protected store under %ProgramData%\EGKits\EtaSigningAgent. They never appear in appsettings.json, EGKits, logs, diagnostics, or console responses.
• Revocable device identity. Each computer registers with its own key and can be revoked from the Signing devices page.
• Access-controlled control channel. The console talks to the agent over the local named pipe EGKits.EtaSigningAgent.Control.v1:
  • Network callers and anonymous callers are refused.
  • Authenticated local users can read status.
  • Admin operations need an elevated administrator or LocalSystem.
  • Only a fixed list of operations is accepted, and message size and time are limited.
  • The console checks that the pipe belongs to the agent installed beside it before sending anything.
• Audit trail. Refusals, malformed messages, and every admin action are written to security-events.log without request payloads.
• Narrow browser bridge. The local signer bridge for client-side signing accepts only the EGKits web addresses (plus any you add with ALLOWEDORIGINS). There is no other local web endpoint.

#Configuration

#Troubleshooting

Logs live under %ProgramData%\EGKits\EtaSigningAgent\logs: agent-YYYYMMDD.log for daily activity and security-events.log for console access. EGKits.EtaSigningAgent.exe --test-token (or Self-test in the console) signs a short sample text with the token, never a document, and checks the signature has the form ETA requires: SHA-256, the signing-certificate attribute, and a certificate valid today and issued for signing. The EGKits server checks every real signature again before anything reaches ETA.

#Upgrade and uninstall

• Run the newer MSI. Windows Installer replaces the previous version in place, and operator-edited appsettings.json is kept.
• Upgrading to 1.3.0 adds the configuration, assignment, and server history sections. Upgrading from 1.1.x also adds the console and its shortcut. Device registration, token PINs, and settings carry over unchanged.
• Upgrading from 1.0.x: register the computer on the Signing devices page. A TokenPin left in appsettings.json moves to the encrypted store at first start; then clear it from the file.
• Uninstall from Settings → Apps. The installer stops the agent and the console. Logs and the encrypted store remain under %ProgramData%; revoke the computer on the Signing devices page.

#Related guides

• E-Invoices
• E-Receipts
• ETA Document Flow
• Downloads