Skip to content

FunctionalAnalysis.md

Latest commit

 

History

History
1348 lines (961 loc) · 33.6 KB

FunctionalAnalysis.md

File metadata and controls

1348 lines (961 loc) · 33.6 KB
Raw

Below is a formal Functional Analysis suitable as a starting point for a software architecture / technical specification document. I’ll use Secure File Access Service (SFAS) as the working name.

Functional Analysis — Secure File Access Service

1. Document Purpose

The purpose of the Secure File Access Service (SFAS) is to centralize and secure access to filesystem resources used by applications, portals, batch procedures, and other consumers.

The service acts as the single controlled access point between consuming applications and the protected filesystem.

The solution provides:

  • centralized file and directory operations;
  • authentication and authorization of consumers;
  • logical-to-physical resource resolution;
  • protection against unauthorized filesystem access;
  • transparent file encryption at rest;
  • transparent decryption when authorized content is retrieved;
  • auditability and traceability of file operations.

The underlying filesystem is considered an internal protected resource and must not be directly accessible by consuming applications.

2. Scope

2.1 In scope

The SFAS provides:

  1. File creation
  2. File reading
  3. File modification
  4. File deletion
  5. File copying
  6. File moving/renaming
  7. Directory creation
  8. Directory deletion
  9. Directory listing
  10. File metadata retrieval
  11. Authentication
  12. Authorization
  13. Logical path validation
  14. File encryption
  15. File decryption
  16. Cryptographic key management integration
  17. Audit logging
  18. Error handling
  19. Request correlation and traceability
  20. API versioning

2.2 Out of scope

The following are not responsibilities of the SFAS:

  • business processing of file contents;
  • interpretation of business-specific document formats;
  • modification of document contents;
  • business workflow management;
  • user interface implementation;
  • business-specific approval processes;
  • general-purpose storage management.

The service manages access to files, not the business meaning of the files.

3. Architectural Principles

The solution is based on the following principles.

AP-01 — Centralized Access

All filesystem operations must pass through the SFAS.

Application
     |
     | HTTPS
     v
+----------------------+
| Secure File Access   |
| Service              |
+----------+-----------+
           |
           v
    Protected File System

AP-02 — No Direct Filesystem Access

Consumer applications must not have operating-system permissions allowing direct access to the protected filesystem.

AP-03 — Least Privilege

Each consumer must receive only the permissions required to perform its authorized operations.

AP-04 — Logical Resource Abstraction

Consumers should interact with logical resources rather than physical filesystem paths.

AP-05 — Encryption at Rest

Files persisted on the protected filesystem may be stored encrypted.

AP-06 — Transparent Cryptography

Encryption and decryption should be transparent to authorized consumers.

AP-07 — Auditable Operations

Security-relevant file operations must be traceable to an authenticated consumer.

4. Actors

4.1 Consumer Application

Represents any application requiring filesystem operations.

Examples:

  • Web portal
  • Backend application
  • Batch process
  • Integration service
  • Document management application

Responsibilities:

  • authenticate with SFAS;
  • invoke authorized APIs;
  • provide valid logical resources;
  • process returned files.

4.2 Service Administrator

Responsible for configuring the SFAS.

Typical activities:

  • configure logical storage areas;
  • configure authorization policies;
  • configure consumers;
  • configure encryption policies;
  • configure retention/audit policies;
  • monitor service status.

4.3 Identity Provider

External authentication component.

Examples include:

  • OAuth/OIDC provider;
  • enterprise identity system;
  • certificate infrastructure.

It establishes the identity of the requesting consumer.

4.4 Key Management Service

External or internal cryptographic key-management component.

Responsibilities:

  • key generation;
  • key storage;
  • key retrieval;
  • key rotation;
  • key lifecycle management.

The SFAS should preferably not store encryption keys as ordinary application configuration or alongside encrypted files.

4.5 Protected File System

The physical storage layer.

Examples:

  • local filesystem;
  • SAN;
  • NAS;
  • mounted storage.

It is an infrastructure component rather than an application actor.

4.6 Security/Audit Platform

Optional external system receiving audit and security events.

Examples:

  • SIEM;
  • centralized logging platform;
  • security monitoring system.

5. Use Case Model

The principal use cases are:

                         +----------------------+
                         | Secure File Access   |
                         | Service              |
                         |                      |
Consumer Application --->| Authenticate         |
Consumer Application --->| Authorize            |
Consumer Application --->| Create File          |
Consumer Application --->| Read File            |
Consumer Application --->| Update File          |
Consumer Application --->| Delete File          |
Consumer Application --->| Copy File            |
Consumer Application --->| Move File            |
Consumer Application --->| List Directory       |
Consumer Application --->| Manage Directory     |
Consumer Application --->| Get Metadata         |
                         |                      |
                         | Encrypt File         |
                         | Decrypt File         |
                         | Audit Operation      |
                         +----------------------+
                                  |
                    +-------------+-------------+
                    |                           |
                    v                           v
              Identity Provider            Key Management

6. Use Case UC-01 — Authenticate Consumer

Objective

Establish the identity of the caller before allowing access to protected resources.

Primary Actor

Consumer Application

Supporting Actor

Identity Provider

Preconditions

  • Consumer is registered.
  • Consumer possesses valid credentials/certificate/token.

Main Flow

  1. Consumer sends an HTTPS request.
  2. SFAS receives authentication credentials.
  3. SFAS validates the credentials.
  4. Identity Provider confirms the consumer identity.
  5. SFAS establishes the security context.
  6. Request processing continues.

Alternative Flows

A1 — Invalid credentials

  1. Authentication fails.
  2. SFAS rejects the request.
  3. No filesystem operation is performed.
  4. Security event is logged.

A2 — Expired credentials

  1. SFAS detects expired credentials.
  2. Request is rejected.
  3. Authentication failure is logged.

7. Use Case UC-02 — Authorize File Operation

Objective

Determine whether an authenticated consumer can perform a specific operation on a specific logical resource.

Preconditions

  • Consumer is authenticated.
  • Requested resource exists or is valid for creation.

Main Flow

  1. SFAS extracts consumer identity.
  2. SFAS identifies requested operation.
  3. SFAS resolves the logical resource.
  4. Authorization policy is evaluated.
  5. Access is granted.
  6. Requested operation proceeds.

Alternative Flow

A1 — Access denied

  1. Authorization policy denies the operation.
  2. No filesystem operation is performed.
  3. SFAS returns an authorization error.
  4. Security event is logged.

Example:

Consumer: PORTAL-A
Resource: DOCUMENTS/customer123/*
Operation: READ

=> ALLOWED

while:

Consumer: PORTAL-A
Resource: SYSTEM/*
Operation: DELETE

=> DENIED

8. Use Case UC-03 — Create File

Objective

Create a new file in a logical storage area.

Main Flow

  1. Consumer sends a file creation request.
  2. SFAS authenticates the request.
  3. SFAS validates authorization.
  4. SFAS validates the logical resource identifier.
  5. SFAS resolves the logical resource to a physical location.
  6. SFAS receives file content.
  7. Encryption policy is evaluated.
  8. File is encrypted if required.
  9. Encrypted content is written to the filesystem.
  10. Operation is audited.
  11. Success response is returned.
Client
  |
  | plaintext
  v
API
  |
  v
Authorization
  |
  v
Path Resolution
  |
  v
Encryption
  |
  v
Protected FS

Alternative Flows

A1 — Unauthorized

Operation terminates before filesystem access.

A2 — Invalid logical path

Request is rejected.

A3 — File already exists

Depending on policy:

  • reject;
  • overwrite;
  • version;
  • return conflict.

A4 — Encryption failure

File must not be persisted as plaintext.

9. Use Case UC-04 — Read File

Objective

Retrieve a file from the protected filesystem.

Main Flow

  1. Consumer requests a logical file.
  2. SFAS authenticates the consumer.
  3. Authorization is evaluated.
  4. Logical resource is validated.
  5. Physical location is resolved.
  6. File is retrieved from storage.
  7. SFAS determines whether decryption is required.
  8. File is decrypted.
  9. Plaintext content is returned through HTTPS.
  10. Operation is audited.
Protected FS
     |
 encrypted
     v
File Access Service
     |
 decrypt
     v
 HTTPS
     |
     v
Consumer

Alternative Flows

A1 — File not found

Return Not Found.

A2 — Unauthorized

Return Forbidden.

A3 — Decryption failure

Do not return corrupted/invalid content.

A4 — Integrity verification failure

The operation is aborted and a security event is generated.

10. Use Case UC-05 — Update File

Objective

Replace or modify an existing file.

Main Flow

  1. Authenticate caller.
  2. Authorize WRITE operation.
  3. Validate resource.
  4. Resolve physical location.
  5. Encrypt new content.
  6. Persist encrypted content.
  7. Optionally perform atomic replacement.
  8. Audit operation.

Important requirement

The implementation should preferably avoid a state in which a partially written encrypted file is exposed.

For example:

temporary encrypted file
          |
          | successful write
          v
atomic rename
          |
          v
final file

11. Use Case UC-06 — Delete File

Main Flow

  1. Authenticate caller.
  2. Verify DELETE permission.
  3. Validate logical resource.
  4. Resolve physical resource.
  5. Delete file.
  6. Record audit event.
  7. Return result.

Alternative Flow

If the resource does not exist, behavior should be explicitly defined:

  • idempotent success; or
  • 404 Not Found.

12. Use Case UC-07 — Move / Rename File

The operation must remain internal to the SFAS.

The client should not need to know the physical filesystem path.

Logical Resource A
       |
       | MOVE
       v
Logical Resource B

The SFAS performs the corresponding physical operation after authorization.

13. Use Case UC-08 — List Directory

Objective

Retrieve the contents of an authorized logical directory.

Main Flow

  1. Authenticate.
  2. Authorize LIST operation.
  3. Validate logical directory.
  4. Resolve physical directory.
  5. Read directory metadata.
  6. Return logical resource information.
  7. Audit request.

The response should preferably expose logical identifiers, not physical filesystem paths.

14. Use Case UC-09 — Encryption

Encryption is an internal service capability rather than normally an externally invoked use case.

Main Flow

  1. File content enters the service.
  2. Encryption policy is retrieved.
  3. Required key is obtained through the Key Management component.
  4. Content is encrypted.
  5. Integrity/authentication information is generated.
  6. Encrypted representation is persisted.

The preferred cryptographic design should use an authenticated encryption mechanism, rather than encryption alone, so that unauthorized modification can be detected.

15. Use Case UC-10 — Decryption

Main Flow

  1. Encrypted file is retrieved.
  2. Encryption metadata is identified.
  3. Appropriate key is obtained.
  4. Integrity/authentication is verified.
  5. Content is decrypted.
  6. Plaintext is returned to the authorized caller.

If integrity verification fails, the content must not be returned.

16. Use Case UC-11 — Audit File Operation

Each relevant operation generates an audit event.

Example:

Timestamp
Correlation ID
Consumer ID
Operation
Logical Resource
Result
Authentication Context
Client Address
File Size
Error Code

For security reasons, the audit record should not contain the plaintext file contents.

17. Functional Requirements

FR-001 — HTTPS API

The system shall expose filesystem operations through a secured HTTPS API.

FR-002 — Authentication

The system shall authenticate every protected request.

FR-003 — Authorization

The system shall authorize each filesystem operation according to the authenticated consumer and requested resource.

FR-004 — File Creation

The system shall support creation of files.

FR-005 — File Retrieval

The system shall support retrieval of files.

FR-006 — File Update

The system shall support modification/replacement of files.

FR-007 — File Deletion

The system shall support deletion of files.

FR-008 — File Move

The system shall support moving/renaming files.

FR-009 — File Copy

The system shall support copying files where authorized.

FR-010 — Directory Operations

The system shall support authorized directory creation, deletion and listing.

FR-011 — Metadata

The system shall provide metadata associated with files and directories.

FR-012 — Logical Resource Resolution

The system shall translate logical resource identifiers into physical storage locations.

FR-013 — Path Traversal Protection

The system shall prevent callers from accessing resources outside their authorized logical storage area.

FR-014 — Encryption at Rest

The system shall support encryption of files before persistence.

FR-015 — Decryption on Retrieval

The system shall decrypt encrypted files before returning them to an authorized caller.

FR-016 — Key Management

The system shall obtain and manage cryptographic keys through a defined key-management mechanism.

FR-017 — Integrity Verification

The system shall detect unauthorized modification of encrypted files.

FR-018 — Audit

The system shall record security-relevant file operations.

FR-019 — Correlation

The system shall assign a correlation identifier to requests to enable end-to-end traceability.

FR-020 — Error Handling

The API shall return standardized errors without exposing internal filesystem information.

For example, avoid returning:

C:\Server\ProtectedData\Customer\123\file.dat

Instead:

{
  "code": "FILE_NOT_FOUND",
  "message": "The requested resource was not found.",
  "correlationId": "..."
}

18. Non-Functional Requirements

NFR-001 — Security

All communication between consumers and SFAS shall use HTTPS.

NFR-002 — Transport Encryption

TLS shall be used for data transmitted between clients and the service.

For high-security environments, mutual TLS (mTLS) may be used for service-to-service authentication.

NFR-003 — Least Privilege

The SFAS operating-system identity shall have only the filesystem permissions required by its configured storage areas.

NFR-004 — Isolation

Consumer applications shall not have direct operating-system permissions to protected storage.

NFR-005 — Confidentiality

Files configured for encryption shall never be persisted as plaintext.

NFR-006 — Integrity

The system shall be able to detect unauthorized modification of encrypted files.

NFR-007 — Availability

The service shall support the availability level defined by the applications depending on it.

NFR-008 — Performance

File transfers shall support streaming where appropriate to avoid loading entire large files into application memory.

This is particularly important for large documents.

Bad:

File -> Memory -> Encrypt -> Disk

Preferred:

File Stream -> Encryption Stream -> Disk

and:

Disk -> Decryption Stream -> HTTPS Response

NFR-009 — Scalability

The service should be horizontally scalable where filesystem architecture permits it.

NFR-010 — Observability

The system shall expose health, operational and security metrics.

NFR-011 — Auditability

Security events shall be retained according to the organization's audit/retention policies.

NFR-012 — Maintainability

API contracts, encryption mechanisms and authorization policies shall be independently configurable where practical.

NFR-013 — No Information Leakage

Errors shall not expose:

  • physical paths;
  • internal server structure;
  • cryptographic information;
  • operating-system details;
  • sensitive file metadata.

19. Logical Architecture

I would divide the service into the following logical components:

┌───────────────────────────────────────────────────────────────┐
│                    CONSUMER DOMAIN                            │
│                                                               │
│  Portal       Backend       Batch       Integration Service   │
└───────────────────────────┬───────────────────────────────────┘
                            │
                            │ HTTPS
                            ▼
┌───────────────────────────────────────────────────────────────┐
│                SECURE FILE ACCESS SERVICE                     │
│                                                               │
│ ┌──────────────────────┐                                      │
│ │ API Gateway /        │                                      │
│ │ REST API             │                                      │
│ └──────────┬───────────┘                                      │
│            ▼                                                  │
│ ┌──────────────────────┐                                      │
│ │ Authentication &     │                                      │
│ │ Authorization        │                                      │
│ └──────────┬───────────┘                                      │
│            ▼                                                  │
│ ┌──────────────────────┐                                      │
│ │ File Operation       │                                      │
│ │ Manager              │                                      │
│ └───────┬───────┬──────┘                                      │
│         │       │                                             │
│         ▼       ▼                                             │
│ ┌────────────┐ ┌────────────────────┐                         │
│ │ Resource   │ │ Encryption /       │                         │
│ │ Resolver   │ │ Decryption Engine  │                         │
│ └──────┬─────┘ └──────────┬─────────┘                         │
│        │                  │                                    │
│        │                  ▼                                    │
│        │          ┌─────────────────┐                          │
│        │          │ Key Management  │                          │
│        │          │ Adapter         │                          │
│        │          └────────┬────────┘                          │
│        │                   │                                   │
│        ▼                   │                                   │
│ ┌──────────────────────┐   │                                   │
│ │ File System Adapter  │   │                                   │
│ └──────────┬───────────┘   │                                   │
│            │               │                                   │
│ ┌──────────▼───────────┐   │                                   │
│ │ Audit / Logging      │◄──┘                                   │
│ └──────────────────────┘                                       │
└──────────────┬────────────────────────────────────────────────┘
               │
               ▼
       ┌─────────────────┐
       │ Protected       │
       │ File System     │
       └─────────────────┘

External:
       ┌─────────────────┐
       │ Identity        │
       │ Provider        │
       └─────────────────┘

       ┌─────────────────┐
       │ KMS / HSM       │
       └─────────────────┘

       ┌─────────────────┐
       │ SIEM / Logging  │
       └─────────────────┘

20. Component Responsibilities

Component Responsibility
API Layer HTTPS/API contract
Authentication Establish caller identity
Authorization Evaluate permissions
File Operation Manager Orchestrate file operations
Resource Resolver Logical → physical resource mapping
Encryption Engine Encrypt/decrypt content
KMS Adapter Interface with key management
Filesystem Adapter Isolate OS/filesystem operations
Audit Manager Generate audit events
Error Handler Standardize errors and prevent information leakage

The Filesystem Adapter is especially valuable architecturally.

It means that the rest of the application doesn't directly call:

java.io.File
System.IO
os.Open()

or equivalent APIs.

Instead:

File Operation Manager
          |
          v
   File System Adapter
          |
          v
     Physical FS

This creates a clean Storage Abstraction Layer.

21. Logical vs Physical Storage

A particularly important part of the architecture is:

              Logical Storage
                    │
                    ▼
          Resource Resolver
                    │
                    ▼
              Physical Storage

Example:

Logical:

DOCUMENTS/customer123/invoice.pdf

Physical:

/protected/storage/tenant01/documents/customer123/invoice.pdf

The consumer should know only the first representation.

This provides:

  • filesystem abstraction;
  • path security;
  • easier migration;
  • tenant isolation;
  • centralized authorization;
  • reduced information leakage.

22. Security Boundary

The SFAS should be explicitly documented as a Security Boundary.

                UNTRUSTED / CONSUMER DOMAIN

   Portal       Batch       Backend       Integration
      \           |            |              /
       \          |            |             /
        └─────────┴────────────┴────────────┘
                         |
                       HTTPS
                         |
                         ▼
              ╔══════════════════════╗
              ║ SECURITY BOUNDARY    ║
              ║                      ║
              ║ Secure File Access   ║
              ║ Service              ║
              ║                      ║
              ║ Auth                 ║
              ║ Authorization        ║
              ║ Validation           ║
              ║ Encryption           ║
              ║ Audit                ║
              ╚══════════╤═══════════╝
                         |
                         | OS-level access
                         ▼

                  PROTECTED DOMAIN

              ┌─────────────────────┐
              │ Encrypted Storage   │
              └─────────────────────┘

This is probably the strongest architectural characteristic of your proposal.

23. Security Model

The authorization decision can conceptually be expressed as:

ALLOW =
    Authenticated
    AND
    Authorized(Principal, Operation, Resource)
    AND
    ResourceValid

For example:

Principal = PORTAL_A
Operation = READ
Resource  = DOCUMENTS/123/file.pdf

             ↓

Authentication      ✓
Authorization       ✓
Path validation     ✓
Resource exists     ✓
Integrity            ✓
Decryption           ✓

             ↓

          ALLOW

Whereas:

Principal = PORTAL_A
Operation = DELETE
Resource  = SYSTEM/config.xml

             ↓

Authentication      ✓
Authorization       ✗

             ↓

           DENY

24. Encryption Architecture

A recommended logical model is:

                   ┌───────────────┐
                   │      KMS      │
                   └───────┬───────┘
                           │
                     Encryption Key
                           │
                           ▼
Client ──HTTPS──> Encryption Engine ──> Protected FS
                      │
                      │
                 Authenticated
                  Encryption

For modern implementations, use an authenticated encryption design, such as an AEAD construction, rather than merely encrypting bytes.

The encrypted representation should also carry sufficient metadata to determine:

  • encryption version;
  • algorithm/version;
  • key identifier/version;
  • nonce/IV;
  • authentication tag;
  • format version.

This allows future cryptographic migration and key rotation.

25. Key Rotation

Key rotation should be explicitly considered as a functional/security requirement.

For example:

Key v1
   |
   | old files
   v
Encrypted Files

Key v2
   |
   | new files
   v
Encrypted Files

You can later define whether existing files are:

  1. re-encrypted immediately;
  2. re-encrypted asynchronously;
  3. re-encrypted on access;
  4. left under the old key until their lifecycle ends.

The important thing is that the file format must support identifying the appropriate key/version.

26. Main End-to-End Flow — Write

1. Consumer
       |
       | HTTPS + credentials
       v
2. API Layer
       |
       v
3. Authentication
       |
       v
4. Authorization
       |
       v
5. Resource Validation
       |
       v
6. Logical → Physical Resolution
       |
       v
7. Encryption Engine
       |
       +----> KMS
       |
       v
8. Filesystem Adapter
       |
       v
9. Protected File System
       |
       v
10. Audit
       |
       v
11. Response

27. Main End-to-End Flow — Read

1. Consumer
       |
       | HTTPS
       v
2. API Layer
       |
       v
3. Authentication
       |
       v
4. Authorization
       |
       v
5. Resource Validation
       |
       v
6. Logical → Physical Resolution
       |
       v
7. Filesystem Adapter
       |
       v
8. Encrypted File
       |
       v
9. Decryption Engine
       |
       +----> KMS
       |
       v
10. Integrity Verification
       |
       v
11. HTTPS Response
       |
       v
12. Audit

28. Alternative/Error Flow

A fundamental design rule should be:

Security checks must occur before filesystem access.

For example:

Request
   |
Authentication
   |
   +---- FAIL ──> DENY
   |
Authorization
   |
   +---- FAIL ──> DENY
   |
Path Validation
   |
   +---- FAIL ──> DENY
   |
Filesystem Operation

Not:

Request
   |
Filesystem
   |
Authorization

because the latter potentially exposes information through filesystem behavior.

29. API Error Model

A standardized error model should be defined.

Example:

{
  "code": "ACCESS_DENIED",
  "message": "Access to the requested resource is not authorized.",
  "correlationId": "a8c92f..."
}

Possible codes:

Code Meaning
AUTHENTICATION_REQUIRED Caller not authenticated
AUTHENTICATION_FAILED Invalid authentication
ACCESS_DENIED Insufficient permissions
INVALID_RESOURCE Invalid logical resource
FILE_NOT_FOUND Resource does not exist
FILE_ALREADY_EXISTS Resource already exists
INVALID_OPERATION Operation not permitted
ENCRYPTION_ERROR Encryption failed
DECRYPTION_ERROR Decryption failed
INTEGRITY_ERROR File integrity verification failed
STORAGE_ERROR Storage operation failed
INTERNAL_ERROR Unexpected internal error

30. Important Architectural Decision

One decision should be made explicitly in the architecture document:

Is the SFAS itself the only process with filesystem permissions?

Recommended model: yes.

SFAS Service Account
        |
        | READ / WRITE
        v
Protected FS

while:

Portal Service Account ──X──> Protected FS
Batch Service Account  ──X──> Protected FS
Backend Service Account ─X──> Protected FS

This is what actually enforces the architectural principle.

The security model should therefore exist at two levels:

Application level

Authentication
Authorization
Path validation
Audit

Infrastructure/OS level

Filesystem ACL
Service account
Network isolation
Host permissions

The two layers should not be considered interchangeable.

31. Recommended Terminology

For the formal document, I would standardize on these terms:

Concept Technical Name
Main service Secure File Access Service (SFAS)
API Secure File Management API
Filesystem access Controlled File System Access
Logical path Logical Resource Identifier
Physical path Physical Storage Location
Mapping Logical-to-Physical Resource Resolution
Security layer Access Control Layer
Encryption Transparent File Encryption
Encryption at rest Data-at-Rest Encryption
Key handling Cryptographic Key Management
Storage abstraction File System Adapter
Logging File Access Audit
Security perimeter Security Boundary
Direct access prevention No Direct File System Access
Permissions Resource-Based Authorization
Path protection Path Traversal Protection

32. Executive Architecture Statement

A concise statement for the beginning of an architecture document could be:

The Secure File Access Service (SFAS) provides a centralized security boundary for filesystem operations. All applications and technical processes requiring access to protected file resources shall interact exclusively with the SFAS through a secured HTTPS API. The service authenticates and authorizes each request, validates logical resource identifiers, resolves logical resources to physical storage locations, executes the requested filesystem operation through an isolated storage adapter, and provides transparent encryption and decryption of file content. The underlying filesystem is not directly accessible by consumer applications and is protected through operating-system and infrastructure-level access controls. All relevant operations are auditable and traceable through a correlation and security logging mechanism.