eSign SDK - Complete Package

Aadhaar-based Digital Document Signing SDK for Java, Android, and JavaScript. Supports India's eSign framework (both v2.1 OTP-based and v3.2 eKYC-based flows).

---

🔒 Security Notice

IMPORTANT: This repository contains configuration files that require sensitive credentials. Never commit actual credentials, certificates, or license files to version control.

• All configuration files ending in .properties and config.js are gitignored
• Use the provided .example template files as references
• Store credentials securely using environment variables or secret managers
• See SECURITY.md for complete security guidelines

---

📋 Table of Contents

• Features
• Quick Start
• Package Contents
• Configuration
• Architecture
• Development Workflow
• API Documentation
• Security Guidelines
• Contributing
• License

---

✨ Features

• eSign 2.1 Support: OTP-based digital document signing
• eSign 3.2 Support: eKYC-based signing flow with enhanced verification
• Multi-Platform SDKs: Java/Spring Boot, Android AAR, JavaScript/Node.js
• REST API: Full-featured API with webhook support
• Web UI: Browser-based signing interface
• PDF Signing: iText-based digital signatures compliant with Indian standards
• Transaction Management: Complete audit trail and transaction tracking
• Async Processing: Optional Kafka integration for high-throughput scenarios

---

🚀 Quick Start (5 Steps)

Step 1: Clone & Install Prerequisites

# Windows (Run as Administrator)
install-prerequisites.bat

# Linux/Mac
chmod +x *.sh
./install-prerequisites.sh

Step 2: Build (One Time Only)

# Windows
build.bat

# Linux/Mac
./build.sh

Step 3: Configure Credentials

Copy the example configuration files and add your credentials:

# eSign API
cp esign-api/src/main/resources/application.properties.example esign-api/src/main/resources/application.properties

# Tomcat eSign (Web UI)
cp tomcat_esign/src/main/resources/application.properties.example tomcat_esign/src/main/resources/application.properties

# Sample Node.js App
cp "SampleSign2_Single Sign/config.js.example" "SampleSign2_Single Sign/config.js"

Edit the files with your actual credentials (ASP ID, certificate password, etc.)

Step 4: Start Server

# Windows
start.bat

# Linux/Mac
./start.sh

Step 5: Start ngrok (New Terminal)

ngrok http 8081

Copy the ngrok URL and update api.base-url in application.properties, then restart the server (no rebuild needed!).

---

⚡ NO REBUILD FOR CONFIG CHANGES!

What Changed	Action
application.properties	Just restart!
ngrok URL	Just restart!
License files	Just restart!
Java code (.java)	Rebuild required

Configuration files to edit:

esign-api/src/main/resources/application.properties  ← Main config (edit this)
tomcat_esign/src/main/resources/application.properties  ← Web UI config (if needed)

---

📦 Package Contents

esign_github/
├── esign-api/                          # REST API Layer (Spring Boot, Port 8081)
│   ├── src/main/java/                  # Java source files
│   ├── src/main/resources/             # Configuration files
│   └── pom.xml                         # Maven build file
│
├── tomcat_esign/                       # Core SDK + Web UI (Spring Boot, Port 8080)
│   ├── src/main/java/                  # Java source files
│   ├── src/main/resources/             # Configuration files
│   └── pom.xml                         # Maven build file
│
├── esign-javascript-sdk-complete/      # JavaScript SDK (Browser & Node.js)
│   ├── src/                            # Source code
│   ├── examples/                       # Usage examples
│   └── package.json                    # npm package config
│
├── esign-android-sdk-complete/         # Android SDK
│   ├── esign-sdk/                      # Android library project
│   ├── samples/                        # Integration examples
│   └── docs/                           # Documentation
│
├── SampleSign2_Single Sign/            # Standalone Node.js eSign sample app
│   ├── server.js                       # Express server
│   ├── services/                       # Service modules
│   └── routes/                         # API routes
│
├── documentation/                      # MkDocs documentation site
│   ├── docs/                           # Documentation markdown
│   └── mkdocs.yml                      # MkDocs config
│
├── test-requests/                      # API test request payloads
├── build.bat / build.sh                # Build scripts
├── start.bat / start.sh                # Start REST API
├── start-ui.bat / start-ui.sh          # Start Web UI (optional)
└── install-prerequisites.*             # Auto-install Java, Maven, ngrok

---

⚙️ Configuration

Required Credentials

Obtain these from your eSign service provider (Capricorn Technologies):

Credential	Description	Example
esign.asp.id	Your assigned ASP ID	youraspid
esign.certificate.password	PFX certificate password	yourpassword
api.auth.token	API authentication token	YOUR_TOKEN
api.auth.key	API authentication key	YOUR_KEY
esign.3_2.signer.id	eSign 3.2 signer ID	user@domain.Provider

File Paths

Place your certificate and license files in:

esign-api/config/privatekey.pfx         # PFX certificate file
esign-api/config/eSignLicense           # Binary license file
tomcat_esign/config/privatekey.pfx      # PFX certificate file
tomcat_esign/config/eSignLicense        # Binary license file

These files are gitignored and must never be committed!

---

🏗️ Architecture

┌──────────────────────────────────────────────────────┐
│                    Client Applications                │
│         (Web UI, Mobile Apps, Third-party APIs)       │
└────────────────┬─────────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────────┐
│              eSign REST API (Port 8081)               │
│         Spring Boot + eSign SDK + iText              │
│                                                       │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  eSign 2.1  │  │  eSign 3.2   │  │   Webhook    │ │
│  │   (OTP)     │  │   (eKYC)     │  │  Callbacks   │ │
│  └─────────────┘  └──────────────┘  └──────────────┘ │
└────────────────┬─────────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────────┐
│              eSign Service Provider (ESP)             │
│         (Aadhaar eSign Infrastructure)                │
└──────────────────────────────────────────────────────┘

Technology Stack

Component	Technology
Backend	Java 17, Spring Boot 3.2.0
PDF Signing	iText 5.5.13.3
Cryptography	Bouncy Castle 1.64
HTTP Client	OkHttp 4.12.0
Android SDK	minSdk 21, compileSdk 34
JavaScript SDK	Node.js + Browser

---

🔄 Development Workflow

First time setup:
  install-prerequisites → build → configure → start

After config changes:
  Edit application.properties → restart (NO rebuild!)

After code changes:
  build → start

After adding new dependencies:
  build → start

---

📚 API Documentation

Quick API Testing

# Windows
api-test.bat

# Linux/Mac
./api-test.sh

See API_TESTING_GUIDE.md for detailed API examples.

Example Requests

Test request payloads are in test-requests/ directory.

---

🔐 Security Guidelines

DO Commit:

• ✅ Source code
• ✅ Configuration templates (.example files)
• ✅ Documentation
• ✅ Build scripts
• ✅ Example/test files (without credentials)

NEVER Commit:

• ❌ Actual credentials, tokens, or passwords
• ❌ .pfx or .p12 certificate files
• ❌ License files (eSignLicense)
• ❌ application.properties with real credentials
• ❌ node_modules/, target/, .gradle/
• ❌ Uploaded documents or signed PDFs
• ❌ Transaction data or logs

Best Practices:

1. Use environment variables for sensitive data in production
2. Rotate credentials regularly
3. Use separate credentials for development/production
4. Never log sensitive information
5. Use .gitignore to prevent accidental commits

See SECURITY.md for complete guidelines.

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

• Code of Conduct
• Development process
• Submitting pull requests
• Coding standards

---

📄 License

This project is proprietary software. All rights reserved.

© 2025 Capricorn Technologies

Unauthorized copying, distribution, or modification of this software is strictly prohibited without express written permission from Capricorn Technologies.

---

🆘 Support

• Documentation: See documentation/docs/
• Issues: Open a GitHub Issue
• Email: support@capricorn.online

---

📊 Project Status

• Version: 1.0.0
• Release Date: December 15, 2025
• Status: Stable

See CHANGELOG.md for version history.