smoa/docs/reference/IMPLEMENTATION_REQUIREMENTS.md

# SMOA Implementation Requirements
## Detailed Technical Requirements for Compliance Gaps

**Document Classification:** Internal Development  
**Date:** 2024-12-20  
**Application:** Secure Mobile Operations Application (SMOA)  
**Version:** 1.0

---

## Table of Contents

1. [PDF417 Barcode Implementation Requirements](#1-pdf417-barcode-implementation-requirements)
2. [AS4 Gateway Implementation Requirements](#2-as4-gateway-implementation-requirements)
3. [eIDAS Compliance Requirements](#3-eidas-compliance-requirements)
4. [Digital Signature Requirements](#4-digital-signature-requirements)
5. [Certificate Management Requirements](#5-certificate-management-requirements)
6. [NCIC/III Integration Requirements](#6-nciciii-integration-requirements)
7. [ATF Integration Requirements](#7-atf-integration-requirements)
8. [See Also](#see-also)
9. [Version History](#version-history)

---  

---

## 1. PDF417 Barcode Implementation Requirements

### 1.1 Functional Requirements

**FR-PDF417-001:** The application SHALL generate PDF417 barcodes compliant with ISO/IEC 15438:2015.

**FR-PDF417-002:** The application SHALL support error correction levels 0 through 8, with level 5 as default.

**FR-PDF417-003:** The application SHALL support the following data structure formats:
- AAMVA DL/ID (American Association of Motor Vehicle Administrators Driver License/ID Card)
- ICAO 9303 (Machine Readable Travel Documents)
- MIL-STD-129 (Military identification)

**FR-PDF417-004:** The application SHALL display PDF417 barcodes at minimum 200 DPI resolution.

**FR-PDF417-005:** The application SHALL support PDF417 text compression mode (Mode 902).

**FR-PDF417-006:** The application SHALL provide barcode scanning capability using device camera.

### 1.2 Technical Specifications

**Library Requirements:**
- ZXing (Zebra Crossing) library for PDF417 encoding/decoding
- Minimum version: 3.5.0
- Alternative: iText PDF library with barcode module

**Data Encoding:**
```kotlin
// Example data structure for AAMVA format
data class AAMVACredential(
    val documentDiscriminator: String,
    val firstName: String,
    val middleName: String?,
    val lastName: String,
    val address: String,
    val city: String,
    val state: String,
    val zipCode: String,
    val dateOfBirth: String, // YYYYMMDD
    val expirationDate: String, // YYYYMMDD
    val issueDate: String, // YYYYMMDD
    val licenseNumber: String,
    val restrictions: String?,
    val endorsements: String?,
    val vehicleClass: String?
)
```

**Display Requirements:**
- Minimum display size: 2.0" x 0.8" (50.8mm x 20.3mm)
- Error correction level: 5 (default)
- Quiet zone: Minimum 10X (where X = module width)

---

## 2. AS4 Gateway Implementation Requirements

### 2.1 Functional Requirements

**FR-AS4-001:** The application SHALL construct AS4 message envelopes per OASIS AS4 Profile 1.0.

**FR-AS4-002:** The application SHALL implement WS-Security SOAP headers with:
- XML Digital Signature (XMLDSig)
- XML Encryption (XMLEnc)
- X.509 certificate-based authentication

**FR-AS4-003:** The application SHALL implement WS-ReliableMessaging for guaranteed message delivery.

**FR-AS4-004:** The application SHALL support both AS4 push and pull protocols.

**FR-AS4-005:** The application SHALL generate and process AS4 receipts with non-repudiation.

**FR-AS4-006:** The application SHALL handle AS4 error signal messages per specification.

### 2.2 Technical Specifications

**Library Requirements:**
- Apache CXF with AS4 support, OR
- Custom implementation based on OASIS AS4 Profile specification
- Apache Santuario for XML security (XMLDSig/XMLEnc)

**Message Structure:**
```kotlin
// AS4 Message structure (simplified)
data class AS4Message(
    val messageId: String, // UUID
    val timestamp: String, // ISO 8601
    val fromParty: AS4Party,
    val toParty: AS4Party,
    val conversationId: String?,
    val service: String?,
    val action: String?,
    val payload: ByteArray,
    val security: AS4Security,
    val reliability: AS4Reliability?
)

data class AS4Security(
    val signature: XMLSignature,
    val encryption: XMLEncryption?,
    val certificate: X509Certificate
)
```

**Security Requirements:**
- TLS 1.2 or higher for transport
- RSA 2048-bit or ECC P-256 for signatures
- AES-256-GCM for encryption
- SHA-256 for hashing

---

## 3. ATF Form Support Requirements

### 3.1 Functional Requirements

**FR-ATF-001:** The application SHALL support ATF Form 4473 (Firearms Transaction Record) data entry and submission.

**FR-ATF-002:** The application SHALL integrate with ATF eTrace system for firearms tracing.

**FR-ATF-003:** The application SHALL support ATF Form 1 (Application to Make and Register a Firearm) processing.

**FR-ATF-004:** The application SHALL support ATF Form 4 (Application for Tax Paid Transfer and Registration) processing.

**FR-ATF-005:** The application SHALL validate form data against ATF validation rules.

**FR-ATF-006:** The application SHALL store form submissions with cryptographic integrity protection.

### 3.2 Technical Specifications

**API Requirements:**
- ATF eTrace API integration (requires federal approval)
- RESTful API for form submission
- OAuth 2.0 for API authentication

**Data Models:**
```kotlin
data class ATFForm4473(
    val transactionId: String,
    val transactionDate: Date,
    val firearmManufacturer: String,
    val firearmModel: String,
    val firearmSerialNumber: String,
    val firearmCaliber: String,
    val firearmType: FirearmType,
    val transfereeInfo: PersonInfo,
    val transferorInfo: PersonInfo,
    val nicsCheckNumber: String?,
    val nicsCheckDate: Date?,
    val signatures: List<DigitalSignature>
)

enum class FirearmType {
    HANDGUN,
    RIFLE,
    SHOTGUN,
    OTHER
}
```

**Security Requirements:**
- All form data encrypted at rest
- Digital signatures on form submissions
- Audit trail for all form access/modifications
- Role-based access control (only authorized ATF personnel)

---

## 4. NCIC/III Integration Requirements

### 4.1 Functional Requirements

**FR-NCIC-001:** The application SHALL provide interface for NCIC database queries.

**FR-NCIC-002:** The application SHALL support III (Interstate Identification Index) queries.

**FR-NCIC-003:** The application SHALL implement ORI (Originating Agency Identifier) management.

**FR-NCIC-004:** The application SHALL generate and validate UCNs (Unique Control Numbers).

**FR-NCIC-005:** The application SHALL handle NCIC response codes per NCIC specifications.

**FR-NCIC-006:** The application SHALL maintain audit log of all NCIC/III queries.

### 4.2 Technical Specifications

**API Requirements:**
- NCIC/III API access (requires CJIS approval)
- Secure communication channel (typically VPN or dedicated line)
- Message format: NCIC 2000 or N-DEx format

**Data Models:**
```kotlin
data class NCICQuery(
    val queryId: String,
    val ori: String, // Originating Agency Identifier
    val ucn: String, // Unique Control Number
    val queryType: NCICQueryType,
    val searchCriteria: Map<String, String>,
    val timestamp: Date,
    val operatorId: String
)

enum class NCICQueryType {
    PERSON,
    VEHICLE,
    ARTICLE,
    BOAT,
    GUN,
    LICENSE_PLATE
}

data class NCICResponse(
    val queryId: String,
    val responseCode: NCICResponseCode,
    val records: List<NCICRecord>?,
    val timestamp: Date,
    val message: String?
)

enum class NCICResponseCode {
    HIT,
    NO_HIT,
    ERROR,
    RESTRICTED
}
```

**Security Requirements:**
- CJIS Security Policy compliance (minimum)
- Background checks for all operators
- Encryption of all queries/responses
- Access logging and monitoring
- Two-factor authentication for operators

---

## 5. Orders Management Requirements

### 5.1 Functional Requirements

**FR-ORD-001:** The application SHALL provide digital orders creation and management.

**FR-ORD-002:** The application SHALL support multiple order types:
- Authorization orders
- Assignment orders
- Search warrants
- Arrest warrants
- Court orders
- Administrative orders

**FR-ORD-003:** The application SHALL track order lifecycle:
- Draft
- Pending approval
- Approved
- Issued
- Executed
- Expired
- Revoked

**FR-ORD-004:** The application SHALL enforce order expiration dates and automatic revocation.

**FR-ORD-005:** The application SHALL generate authenticated copies of orders.

**FR-ORD-006:** The application SHALL validate order authenticity upon receipt.

**FR-ORD-007:** The application SHALL support order templates for common order types.

### 5.2 Technical Specifications

**Data Models:**
```kotlin
data class Order(
    val orderId: String,
    val orderType: OrderType,
    val title: String,
    val content: String,
    val issuedBy: String, // Authority/author
    val issuedTo: String?,
    val issueDate: Date,
    val effectiveDate: Date,
    val expirationDate: Date?,
    val status: OrderStatus,
    val attachments: List<OrderAttachment>,
    val signatures: List<DigitalSignature>,
    val metadata: OrderMetadata
)

enum class OrderType {
    AUTHORIZATION,
    ASSIGNMENT,
    SEARCH_WARRANT,
    ARREST_WARRANT,
    COURT_ORDER,
    ADMINISTRATIVE
}

enum class OrderStatus {
    DRAFT,
    PENDING_APPROVAL,
    APPROVED,
    ISSUED,
    EXECUTED,
    EXPIRED,
    REVOKED
}

data class OrderMetadata(
    val classification: ClassificationLevel?,
    val jurisdiction: String,
    val caseNumber: String?,
    val relatedOrders: List<String>,
    val keywords: List<String>
)

data class OrderCopy(
    val originalOrderId: String,
    val copyId: String,
    val generatedDate: Date,
    val generatedBy: String,
    val copyType: CopyType,
    val authenticationCode: String, // For verification
    val orderContent: ByteArray // Encrypted/signed
)

enum class CopyType {
    CERTIFIED_TRUE_COPY,
    INFORMATIONAL_COPY,
    REDACTED_COPY
}
```

**Security Requirements:**
- Digital signatures on all orders
- Encryption of order content
- Role-based access control
- Immutable audit trail
- Copy authentication codes (HMAC-based)

---

## 6. Evidence Chain of Custody Requirements

### 6.1 Functional Requirements

**FR-EVID-001:** The application SHALL track evidence chain of custody per NIST SP 800-88.

**FR-EVID-002:** The application SHALL record all custody transfers with:
- Timestamp
- Transferring party
- Receiving party
- Reason for transfer
- Evidence condition
- Digital signatures

**FR-EVID-003:** The application SHALL generate chain of custody reports.

**FR-EVID-004:** The application SHALL prevent unauthorized custody transfers.

**FR-EVID-005:** The application SHALL support evidence metadata:
- Evidence ID
- Description
- Location found
- Collection date/time
- Collection method
- Chain of custody history

### 6.2 Technical Specifications

**Data Models:**
```kotlin
data class Evidence(
    val evidenceId: String,
    val caseNumber: String,
    val description: String,
    val evidenceType: EvidenceType,
    val collectionDate: Date,
    val collectionLocation: String,
    val collectionMethod: String,
    val collectedBy: String,
    val currentCustodian: String,
    val storageLocation: String?,
    val chainOfCustody: List<CustodyTransfer>,
    val metadata: EvidenceMetadata
)

data class CustodyTransfer(
    val transferId: String,
    val timestamp: Date,
    val fromCustodian: String,
    val toCustodian: String,
    val reason: String,
    val evidenceCondition: String,
    val signature: DigitalSignature,
    val notes: String?
)

enum class EvidenceType {
    PHYSICAL,
    DIGITAL,
    BIOLOGICAL,
    CHEMICAL,
    FIREARM,
    DOCUMENT
}
```

**Security Requirements:**
- Cryptographic integrity protection
- Immutable chain records
- Digital signatures on transfers
- Access control based on case assignment
- Audit logging

---

## 7. Report Generation Requirements

### 7.1 Functional Requirements

**FR-REPT-001:** The application SHALL generate reports in multiple formats:
- PDF (Portable Document Format)
- XML (eXtensible Markup Language)
- JSON (JavaScript Object Notation)
- CSV (Comma-Separated Values)

**FR-REPT-002:** The application SHALL support configurable report templates.

**FR-REPT-003:** The application SHALL support scheduled report generation.

**FR-REPT-004:** The application SHALL include digital signatures on reports.

**FR-REPT-005:** The application SHALL support report distribution:
- Email
- Secure file transfer
- Print
- Export to storage

### 7.2 Technical Specifications

**Report Types:**
- Operational reports
- Compliance reports
- Audit reports
- Evidence reports
- Activity reports
- Regulatory reports (NIBRS, UCR, etc.)

**Library Requirements:**
- Apache PDFBox or iText for PDF generation
- Jackson or Gson for JSON
- JAXB or similar for XML
- Apache POI for Excel/CSV

---

## 8. Implementation Priority Matrix

| Requirement Set | Priority | Estimated Effort | Dependencies | Blocking For |
|----------------|----------|-----------------|--------------|--------------|
| PDF417 Barcode | P1 | 2-3 months | ZXing library | Credential display |
| Orders Management | P1 | 3-4 months | Digital signatures | Operational authorization |
| AS4 Gateway | P1 | 9-12 months | AS4 library, WS-Security | Inter-agency messaging |
| ATF Forms | P1 | 4-6 months | ATF API approval | ATF operations |
| NCIC/III | P1 | 6-9 months | CJIS approval | Law enforcement ops |
| Evidence CoC | P1 | 2-3 months | Digital signatures | Legal admissibility |
| Report Generation | P1 | 2-3 months | PDF/XML libraries | Operational reporting |

---

**Document Version:** 1.0  
**Status:** Requirements Definition Complete  
**Next Step:** Technical Design and Architecture Documentation