CipherGin

A Go library for an encrypted application-layer channel on Gin, built with TLS 1.3, X25519, HKDF, and AES-256-GCM.

CipherGin provides:

• Server middleware — handshake routes, session decrypt/encrypt, key rotation
• Client SDK — Dial, PostSecure, RotateKey

How it works

CipherGin adds an encrypted application channel on top of TLS 1.3. The client and server agree on a session AES key via X25519 + HKDF, then exchange payloads with AES-256-GCM. Nonces are tracked to block replays; keys can be rotated without a full re-handshake.

Phase	What happens
1. Init	Client calls GET /api/init and receives the server’s X25519 public key.
2. Handshake	Client sends its public key (POST /api/handshake). Both sides derive a shared secret; the server returns a session_id and a wrapped AES key.
3. Secure exchange	Requests use header X-Session-ID and an AES-GCM body (encrypted_data + nonce). Responses are encrypted the same way.
4. Key rotation	POST /api/rotate-key issues a new AES key encrypted under the old one.

Install

go get github.com/Tarunno/CipherGin@latest

Server usage

import (
    ciphergin "github.com/Tarunno/CipherGin"
    "github.com/gin-gonic/gin"
)

func main() {
    ecdh, err := ciphergin.NewECDHKeyManager(nil)
    if err != nil {
        panic(err)
    }
    sessions := ciphergin.NewSessionManager(nil)

    r := gin.Default()
    api := r.Group("/api")

    ciphergin.RegisterECDHRoutes(api, ecdh, sessions)   // GET /init, POST /handshake
    ciphergin.RegisterRotateKeyRoute(api, sessions)     // POST /rotate-key

    secure := api.Group("")
    secure.Use(ciphergin.SecureSessionMiddleware(sessions))
    secure.Use(ciphergin.EncryptResponseMiddleware())
    {
        secure.POST("/orders", func(c *gin.Context) {
            data, _ := ciphergin.GetDecryptedDataFromContext(c)
            // handle plaintext in data...
            ciphergin.SetResponseData(c, gin.H{"ok": true, "echo": string(data)})
        })
    }

    r.RunTLS(":8443", "cert.pem", "key.pem")
}

Client usage

import (
    "crypto/tls"
    "github.com/Tarunno/CipherGin/client"
)

func main() {
    c, err := client.Dial("https://api.example.com",
        client.WithTLSConfig(&tls.Config{MinVersion: tls.VersionTLS13}),
    )
    if err != nil {
        panic(err)
    }

    resp, err := c.PostSecure("/api/orders", []byte(`{"item":"widget"}`))
    if err != nil {
        panic(err)
    }
    _ = resp

    _ = c.RotateKey()
}

Project layout

.
├── crypto.go            # HKDF / AES helpers
├── session.go           # In-memory session manager
├── ecdh.go              # X25519 manager + handshake / rotate routes
├── middleware.go        # Gin decrypt / encrypt middleware
├── client/              # Client SDK
├── examples/
│   ├── server/          # Demo HTTPS server
│   └── client/          # Demo SDK client
└── api.png              # Protocol diagram

Run the examples

go run ./examples/server

In another terminal:

go run ./examples/client

The example server listens on https://localhost:8443.

API endpoints (convention)

Method	Path	Purpose
GET	/api/init	Server X25519 public key
POST	/api/handshake	Establish encrypted session
POST	/api/secure-data	Example encrypted route
POST	/api/rotate-key	Rotate session AES key

Mount paths are yours to choose; the client defaults to the /api prefix (client.DialWithAPIPath for others).

License

Private — all rights reserved.