Security Policy

Comprehensive security architecture and protocols for the Credence platform. Defense-in-depth strategy, cryptographic security, data protection, and vulnerability reporting.

Supported Versions

This software is an academic research prototype intended to demonstrate the viability of blockchain-based credential verification. However, it is built with production-grade security standards. The following table outlines the versions that currently receive security updates.

Version	Supported	Security Updates
1.x.x	Yes	Yes

Security Architecture Overview

Credence implements a defense-in-depth security strategy. This approach involves layering multiple defensive mechanisms so that if one control fails, others are in place to protect the system's integrity and confidentiality.

Cryptographic Security

The tamper-evidence of the system relies on industry-standard cryptographic primitives.

SHA-256 Hashing Algorithm (Model 1)

Every certificate issued is converted into a unique 256-bit hash using the SHA-256 algorithm. This ensures the following security properties:

H : {0,1}* → {0,1}²⁵⁶
P(tamper undetected) = 1 / 2²⁵⁶ ≈ 8.6 × 10⁻⁷⁸

Collision Resistance: It is computationally infeasible to find two different credential sets that produce the same hash.
Pre-image Resistance: It is impossible to reverse-engineer the original credential data from the hash alone.
Avalanche Effect: A minor change in the credential data results in a completely different hash value.

Certificate Key Uniqueness (Model 3)

Each certificate is assigned a globally unique identifier using a composite key generation scheme that combines timestamp encoding with random values.

Key Space = 2⁷⁴ · P(collision) < 2.6 × 10⁻¹¹
Format: CRD-T_base36-R_hex

This provides approximately 1.89 × 10²² possible unique combinations, ensuring no two certificates will ever share the same identifier.

Merkle Tree Integrity (Model 6)

The system implements a binary Merkle tree structure to ensure the integrity of the entire certificate set, enabling efficient verification with O(log n) complexity.

R = root · Layer_k+1 = H(min(l, r) ‖ max(l, r))
Depth = ⌈log₂N⌉ · Mutation prob. = 1 / 2²⁵⁶

Any modification to the certificate set is immediately detected through root hash comparison.

Reset Token Security (Model 5)

Password reset tokens are generated using a cryptographically secure pseudo-random number generator (CSPRNG) with 256 bits of entropy.

Token ∈ {0,1}²⁵⁶ · P(guess) = 1 / 2²⁵⁶
32 random bytes from CSPRNG · 1-hour expiry

Even with 1 billion guesses per second, the expected time to brute-force a single token exceeds the age of the universe.

Hash-Chained, Append-Only Ledger

Certificates are anchored on the Credence Ledger. Every block contains the hash of the previous block, so altering or removing any block breaks the chain and is detected by full-chain validation. Database triggers additionally reject any update, delete or truncate of the ledger table. This provides a tamper-evident audit trail for all issued credentials. See Blockchain Integrity below for the limits of this design.

Digital Signatures (Ed25519 and ECDSA)

Every block on the Credence Ledger is signed with an Ed25519 key that is held only on the ledger server, so the origin of every block can be cryptographically verified and a rewritten history requires that key. In the Hyperledger Fabric design target, transactions are signed with ECDSA by the organisation's enrolled identity.

Application Security

The application layer is protected by a suite of middleware and validation protocols to prevent common web vulnerabilities.

Authentication and Session Management

JSON Web Tokens (JWT): We use stateless JWT authentication. The accessToken has a short lifespan to minimize the impact of token theft, while the refreshToken allows for secure session renewal.
Automatic Token Rotation: The system automatically refreshes expired access tokens in the background using the secure HttpOnly refresh token, ensuring a seamless user experience without compromising security.
Secure Password Storage: User passwords are never stored in plain text. They are hashed and salted using bcrypt, ensuring that even in the event of a database breach, user credentials remain protected.

Input Validation and Sanitization

Zod Schemas: All incoming data payloads are validated against strict Zod schemas on both the frontend and backend. This prevents type coercion attacks and ensures data integrity.
XSS Prevention: User inputs are sanitized to prevent Cross-Site Scripting attacks. The Content Security Policy (CSP) header is configured to restrict the sources from which scripts can be loaded.

Network Security

Strict CORS Policy: Cross-Origin Resource Sharing (CORS) is configured to only allow requests from whitelisted domains. This prevents unauthorized third-party websites from making API calls to our backend.
Multi-Tier Rate Limiting: To mitigate Denial of Service (DoS) and brute-force attacks, we enforce strict rate limits:
• Authentication Endpoints: 5 requests per 15 minutes
• Upload Endpoints: 10 requests per hour
• Certificate Endpoints: 20 requests per hour
• General API: 100 requests per 15 minutes
IP-Based Tracking: Rate limiting is enforced at the IP level to prevent circumvention via token rotation.

Security Headers

We employ Helmet.js to set critical HTTP headers:

HSTS (HTTP Strict Transport Security): Forces browsers to communicate over HTTPS only.
X-Frame-Options: Prevents the application from being embedded in iframes, mitigating clickjacking attacks.
X-Content-Type-Options: Prevents MIME-sniffing attacks.
Content Security Policy (CSP): Restricts resources (scripts, styles, images) to approved sources.

Data Protection and Privacy

We prioritize the privacy of student data in compliance with the Nigeria Data Protection Regulation (NDPR).

Role-Based Access Control (RBAC)

Access to system features is strictly regulated based on user roles.

Administrators: Can issue and revoke certificates.
Graduates: Can only view and share their own certificates.
Employers: Can only verify certificates and view limited public data.
All API routes are protected by middleware that validates the user's role before processing requests.

Data Segregation

Off-Chain Storage: Personally Identifiable Information (PII), such as names, matric numbers, and contact details, is stored in a secure PostgreSQL database and is never written to the public blockchain ledger. This ensures student privacy.
On-Chain Storage: Only the cryptographic hash of the certificate is stored on the blockchain. This proves authenticity without exposing sensitive data to the distributed network.

Email Domain Validation

To ensure that only authorized personnel can issue credentials or access official records, the system enforces strict email validation. Only users with an @futa.edu.ng email address can register as Administrators or Graduates.

Blockchain Integrity

Active Ledger: Credence Ledger

The live system runs the Credence Ledger: a single-node, permissioned, SHA-256 hash-chained and Ed25519-signed ledger stored in an append-only database schema. It is tamper-evident: any edit to a block, a signature or the order of blocks is detected by full-chain validation, and a certificate whose database record was altered after issuance fails verification. It is not a distributed ledger. One operator runs the only node, so someone controlling both the database and the signing key could rewrite history. To limit this, the head hash of the chain is recorded as an external anchor.

Data Minimisation

Only a digest of the certificate key, the certificate hash and non-personal descriptive fields are written to the ledger. Names, matric numbers and CGPAs are never stored on it, which keeps personal data out of an append-only record in line with the NDPR.

Fail-Closed Verification

If the ledger cannot be reached, verification, issuance and revocation return a clear error and write nothing. Production never falls back to a simulated ledger. Revocations are recorded on the ledger before the database so the two cannot disagree.

Permissioned Network (Hyperledger Fabric design target)

The research design uses a Hyperledger Fabric network, which unlike a public blockchain is permissioned: only authorized nodes operated by the institution take part in consensus. It remains the intended multi-organisation deployment, available when the managed Fabric network is.

Private Channels and Raft Consensus (Fabric design target)

In the Fabric design, private channels isolate data so transactions are visible only to the relevant parties, and the Raft ordering service keeps the network consistent while tolerating node failures.

Reporting a Vulnerability

The security of the Credence platform is a collaborative effort. We actively encourage responsible disclosure of security vulnerabilities.

Do not open a public GitHub issue for security vulnerabilities.

How to Report

Send an email to oyedokunkjifs2020@futa.edu.ng with the subject line: [SECURITY] Credence Vulnerability Report.

Please include the following details:

Description: A clear explanation of the vulnerability.
Impact: The potential consequences of the vulnerability if exploited.
Affected Component: Whether the issue resides in the Frontend, Backend, or Blockchain chaincode.
Reproduction Steps: Detailed steps or proof-of-concept code to reproduce the issue.
Mitigation: Any suggested fixes or workarounds, if known.

What to Expect

Acknowledgement: We will acknowledge receipt of your report within 48 hours.
Assessment: We will provide an initial assessment of the severity within 7 days.
Resolution: We will work to patch the vulnerability and release a security update as soon as possible.
Credit: With your permission, we will credit you in the changelog for discovering the vulnerability.

Known Limitations

As an academic prototype, the system has specific security limitations that should be noted for full production deployment:

Trust in the Issuer: The blockchain secures data after it is issued. It cannot prevent a malicious insider with administrative privileges from entering fraudulent data into the system before the hash is created.
Key Management: The prototype does not currently utilize Hardware Security Modules (HSMs) for managing private keys, which is a recommended best practice for high-security financial or national infrastructure deployments.
Email Delivery: Security features such as OTP verification rely on the security of the user's email provider. If a user's email account is compromised, their account on Credence is also at risk.

Dependency Security

We actively maintain the security of our dependencies. We strongly recommend running the following audits before deploying any version of the software.

# Backend Dependency Audit
cd backend && npm audit

# Frontend Dependency Audit
cd frontend && npm audit

All high-severity vulnerabilities found in the dependency tree are addressed promptly by updating to patched versions.

Security Questions?

If you have questions about our security practices or need to report a concern, please contact us.