opto22/groov-cert-signer

groov Cert Signer

A web-based certificate signing tool for Opto 22 groov EPIC and groov RIO devices. Connect to your device, sign a certificate with your private CA, and push it back — all without leaving the app.

Ephemeral by design. CA materials are held in memory only. When the session ends or the container stops, all private data is gone.

How It Works

mermaid
flowchart TD
    START([Open the app]) --> INTRO[Accept Terms of Use]
    INTRO --> STEP1[Upload CSR]

    STEP1 --> HOW{How do you want<br/>to load the CSR?}

    HOW -->|Connect to device| CONNECT[Enter device address & API key]
    HOW -->|Upload a file| MANUAL[Select CSR file from your computer]

    CONNECT --> FETCHING[App connects to your groov device<br/>and fetches the CSR automatically]
    FETCHING --> STATUS{CSR status?}

    STATUS -->|Ready| GOT_CSR[CSR loaded successfully<br/>Device hostname & IPs detected]
    STATUS -->|No CSR on device| CREATE[Fill in hostname & country<br/>App creates a new certificate on the device]
    STATUS -->|Outdated CSR| CREATE

    CREATE --> GOT_CSR

    MANUAL --> PARSED[CSR parsed and details shown]

    GOT_CSR --> SANS[Review & edit SAN entries<br/>Pre-populated from device network info]
    PARSED --> SANS2[Review & edit SAN entries]

    SANS --> EXPIRY[Choose certificate expiration period]
    SANS2 --> EXPIRY

    EXPIRY --> CA{CA already loaded<br/>from previous signing?}
    CA -->|Yes| SIGN[Click Sign Certificate]
    CA -->|No| UPLOAD_CA[Upload CA certificate & key]
    UPLOAD_CA --> SIGN

    SIGN --> REVIEW[Review signed certificate details<br/>Subject, Issuer, SANs, validity, fingerprint]

    REVIEW --> DELIVER[Download & Deliver]

    DELIVER --> DOWNLOAD[Download certificate .pem]
    DELIVER --> REPORT[Download signing report .md]
    DELIVER --> PUSH_Q{Connected to device?}

    PUSH_Q -->|Yes| PUSH[Push certificate directly to device<br/>Device restarts with new cert]
    PUSH_Q -->|No| MANUAL_INSTALL[Upload cert to device manually<br/>via groov Manage]

    DELIVER --> NEXT{What next?}
    NEXT -->|Sign another| STEP1
    NEXT -->|Done| CLEAR[End session — all data cleared]

    classDef action fill:#e8f4f8,stroke:#2196F3,stroke-width:2px
    classDef choice fill:#fff9c4,stroke:#FFC107,stroke-width:2px
    classDef success fill:#e8f5e9,stroke:#4CAF50,stroke-width:2px
    classDef device fill:#fff3e0,stroke:#FF9800,stroke-width:2px

    class INTRO,STEP1,CONNECT,MANUAL,UPLOAD_CA,SIGN,REVIEW,DELIVER action
    class HOW,STATUS,CA,PUSH_Q,NEXT choice
    class GOT_CSR,PARSED,DOWNLOAD,REPORT,PUSH,CLEAR success
    class CREATE,FETCHING,MANUAL_INSTALL device

Quick Start

bash
docker run -d -p 2222:3000 --name groov-cert-signer --restart unless-stopped opto22/groov-cert-signer:latest

Open http://localhost:2222 in your browser.

Port 2222 is the external port on your machine. Change it if needed — for example, -p 8080:3000 opens the app at http://localhost:8080.

The image is on Docker Hub: https://hub.docker.com/r/opto22/groov-cert-signer

Supported platforms: linux/amd64 and linux/arm64 (macOS Apple Silicon & Intel, Windows x86-64, Linux)

Stop or remove

bash
docker stop groov-cert-signer    # stop the container
docker rm groov-cert-signer      # remove it entirely

Before You Start

1. Commission your groov device

Your groov EPIC or RIO should be commissioned following Opto 22 best practices. We recommend using an Incognito / Private browser window:

1. Create the first Administrator account
2. Set the system time zone (System > Time)
3. Change the hostname (Network > Configure) from the factory default (opto-xx-xx-xx) to a name that makes sense for your environment
4. Configure network interfaces as needed (DHCP, static IP, Wi-Fi, Open***, etc.)
5. Go to Security > Web Server Certificate and click Create Certificate

2. Create an API key on the device

The app connects directly to your groov device to fetch the CSR, read network info, and push the signed certificate back. This requires a groov Manage API key:

1. In groov Manage, go to Accounts > Users and create a new account (e.g., CertSigner)
2. Grant the account System-wide Administrator permissions
3. Open the account and copy the API Key — you'll use this when connecting from the app

Don't have network access to your device? You can still use the app by uploading a CSR file manually — see Manual CSR Upload below.

3. Have your CA ready

You'll need a private Certificate Authority (CA) — specifically, the CA certificate (.pem) and the CA private key (.key or .pem). If you don't have one yet, the app can create one for you during the signing step.

New CA? After creating a CA, install the CA certificate into the Trusted Certificate Store on every computer that accesses your groov devices. This tells browsers to trust your CA-signed certificates:

• macOS: Open Keychain Access, import the certificate, set to "Always Trust"
• Windows: Open certmgr.msc, import into Trusted Root Certification Authorities
• Linux: Copy to /usr/local/share/ca-certificates/ and run update-ca-certificates

Signing a Certificate

Step 1 — Connect to your device

Click Fetch CSR from Device and enter your device's HTTPS address (e.g., https://epic-01 or https://192.168.1.100) along with the API key you created above.

The app will:

• Fetch the pending CSR from the device
• Read the device's hostname and IP addresses
• Check that the CSR is current (not stale or mismatched)

If the device has no CSR or the existing one is outdated, the app offers to create a new certificate on the device directly — no need to log into groov Manage.

Step 2 — Review SANs

Subject Alternative Name (SAN) entries are pre-populated from the device's current network configuration (hostname and IP addresses). You can add, edit, or remove entries, or proceed with no SANs if the certificate should use the Subject CN only.

Step 3 — Set expiration

Choose the certificate validity period. Common presets are provided (90, 365, 397 days), or enter a custom number.

Step 4 — Upload CA and sign

Upload your CA certificate and key (or use the cached CA from a previous signing). Click Sign Certificate to generate the signed certificate.

Step 5 — Review

Verify the certificate details: subject, issuer, SANs, validity period, key size, and fingerprint.

Step 6 — Push to device

Click Push Certificate to Device to generate a fresh key pair, sign a new certificate with your CA, and push everything to the device in one step. The device restarts its web server automatically (~10-15 seconds).

You can also:

• Download the certificate (.pem) for manual installation
• Download a signing report (.md) with all certificate details for your records

Optionally check "Include CA certificate as intermediate chain" to send your CA cert along with the signed cert.

Sign another

Click Sign Another Certificate to return to Step 1 with your CA still loaded. Click End Session to clear all data from memory.

Manual CSR Upload

If you can't reach your device from the machine running this app, you can upload a CSR file instead:

1. On the device, go to Security > Web Server Certificate and download the CSR
2. In the app, click Upload CSR File (below the device connection button) and select the .csr or .pem file
3. Continue with Steps 2-5 as normal
4. Download the signed certificate and upload it manually via groov Manage

Note: When uploading a CSR file manually, make sure it's current. If the device has had a new certificate created since the CSR was downloaded, it may be outdated.

Development

For working on the code locally. Requires Node.js 20+ and OpenSSL.

bash
npm install
npm run dev

• Frontend (React/Vite): http://localhost:5173
• Backend (Express): http://localhost:3000

The Vite dev server proxies /api requests to Express automatically.

Tech stack

Security

• CA key and certificate are never written to disk — held in server memory for the session only
• Temporary files for OpenSSL operations use secure temp directories with mode 0600 and are deleted immediately after use
• No database, no persistent storage, no logging of sensitive data
• Docker container runs as a non-root user
• Designed for trusted networks — no authentication layer

Resources

• groov EPIC SSL Certificate Tutorial
• Opto 22 Developer Portal
• https://hub.docker.com/r/opto22/groov-cert-signer