smoa/docs/integrations/ncic-integration.md

# NCIC/III Integration Documentation

**Version:** 1.0  
**Last Updated:** 2024-12-20  
**Status:** Draft - In Progress  
**Classification:** Law Enforcement Use Only

---

## Integration Overview

### Purpose
SMOA integrates with NCIC (National Crime Information Center) and III (Interstate Identification Index) for law enforcement database queries.

### Integration Type
- **Protocol:** NCIC 2000 or N-DEx format
- **Transport:** Secure VPN or dedicated line
- **Authentication:** ORI/UCN-based authentication
- **Authorization:** CJIS Security Policy compliance required

### Integration Status
- **Status:** Framework Complete
- **Implementation:** Partial (pending CJIS approval and API access)
- **Testing:** Framework testing complete

---

## Integration Architecture

### NCIC Query Flow

```
SMOA Application
    ↓
NCIC Service Layer (modules:ncic)
    ↓
Query Construction
    ↓
ORI/UCN Generation
    ↓
Secure VPN/Dedicated Line
    ↓
NCIC/III Gateway
    ↓
NCIC/III Database
    ↓
Response Processing
    ↓
SMOA Application
```

### Components

#### NCIC Service Layer
- **Location:** `modules/ncic/src/main/java/com/smoa/modules/ncic/`
- **Components:**
  - NCICService
  - NCICQueryBuilder
  - ORI/UCN Manager
  - ResponseProcessor

---

## Configuration

### NCIC Gateway Configuration

#### Endpoint Configuration
```kotlin
// NCIC gateway endpoint
ncicGatewayEndpoint = "https://ncic-gateway.example.com/ncic"
ncicGatewayCertificate = "ncic-cert.pem"
```

#### ORI Configuration
```kotlin
// Originating Agency Identifier
ori = "XX12345" // Assigned by FBI
oriName = "Agency Name"
oriType = "LE" // Law Enforcement
```

#### UCN Configuration
```kotlin
// Unique Control Number generation
ucnPrefix = "XX12345"
ucnSequence = autoIncrement
ucnFormat = "XX12345-YYYYMMDD-HHMMSS-####"
```

### CJIS Compliance Configuration

#### Security Requirements
- **Background Checks:** All operators must pass background checks
- **Two-Factor Authentication:** Required for all operators
- **Encryption:** All queries/responses encrypted
- **Access Logging:** Complete access logging
- **Audit Trail:** Comprehensive audit trail

---

## Query Operations

### Query Types

#### Person Query
- **Query Type:** PERSON
- **Search Criteria:** Name, DOB, SSN, etc.
- **Response:** Person records, warrants, etc.

#### Vehicle Query
- **Query Type:** VEHICLE
- **Search Criteria:** VIN, license plate, etc.
- **Response:** Vehicle records, stolen vehicles, etc.

#### Article Query
- **Query Type:** ARTICLE
- **Search Criteria:** Serial number, description, etc.
- **Response:** Article records, stolen articles, etc.

#### Other Query Types
- **BOAT:** Boat queries
- **GUN:** Gun queries
- **LICENSE_PLATE:** License plate queries

### Query Construction

#### Query Format
```kotlin
val query = NCICQuery(
    queryId = UUID.randomUUID().toString(),
    ori = "XX12345",
    ucn = generateUCN(),
    queryType = NCICQueryType.PERSON,
    searchCriteria = mapOf(
        "firstName" to "John",
        "lastName" to "Doe",
        "dateOfBirth" to "1980-01-01"
    ),
    timestamp = Instant.now(),
    operatorId = currentUser.id
)
```

### Query Execution

#### Execute Query Procedure
1. **Validate Query:** Validate query parameters
2. **Generate UCN:** Generate Unique Control Number
3. **Construct Query:** Build NCIC query message
4. **Encrypt Query:** Encrypt query for transmission
5. **Send Query:** Send via secure connection
6. **Receive Response:** Receive and decrypt response
7. **Process Response:** Process response data
8. **Log Query:** Log query for audit

---

## Response Processing

### Response Types

#### Hit Response
- **Status:** HIT
- **Content:** Matching records
- **Action:** Process records, display to user

#### No Hit Response
- **Status:** NO_HIT
- **Content:** No matching records
- **Action:** Log response, inform user

#### Error Response
- **Status:** ERROR
- **Content:** Error message
- **Action:** Log error, inform user, retry if appropriate

#### Restricted Response
- **Status:** RESTRICTED
- **Content:** Access restricted
- **Action:** Log restriction, inform user

### Response Processing Code
```kotlin
val response = ncicService.executeQuery(query)

when (response.responseCode) {
    NCICResponseCode.HIT -> {
        // Process records
        response.records?.forEach { record ->
            processRecord(record)
        }
    }
    NCICResponseCode.NO_HIT -> {
        // No records found
        logNoHit(query)
    }
    NCICResponseCode.ERROR -> {
        // Handle error
        handleError(response.message)
    }
    NCICResponseCode.RESTRICTED -> {
        // Handle restriction
        handleRestriction(response.message)
    }
}
```

---

## ORI/UCN Management

### ORI Management

#### ORI Assignment
- **Assignment:** ORI assigned by FBI
- **Registration:** Register ORI with NCIC
- **Validation:** Validate ORI before use
- **Storage:** Secure ORI storage

### UCN Generation

#### UCN Format
- **Format:** ORI-Date-Time-Sequence
- **Uniqueness:** Guaranteed unique per query
- **Validation:** UCN validation before use
- **Storage:** UCN storage for audit

#### UCN Generation Code
```kotlin
fun generateUCN(): String {
    val date = LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE)
    val time = LocalTime.now().format(DateTimeFormatter.ofPattern("HHmmss"))
    val sequence = ucnSequence.incrementAndGet()
    return "$ori-$date-$time-$sequence"
}
```

---

## Security

### Authentication
- **ORI-Based:** ORI-based authentication
- **Certificate-Based:** Certificate authentication
- **Two-Factor:** Two-factor authentication required

### Encryption
- **Query Encryption:** All queries encrypted
- **Response Encryption:** All responses encrypted
- **TLS:** TLS 1.2+ for transport

### Access Control
- **Operator Authorization:** Only authorized operators
- **Query Authorization:** Query type authorization
- **Data Access:** Data access restrictions

### Audit Logging
- **Query Logging:** All queries logged
- **Response Logging:** All responses logged
- **Access Logging:** All access logged
- **Audit Trail:** Complete audit trail

---

## Compliance

### CJIS Security Policy

#### Compliance Requirements
- **Background Checks:** All operators
- **Two-Factor Authentication:** Required
- **Encryption:** All data encrypted
- **Access Logging:** Complete logging
- **Audit Trail:** Comprehensive audit

#### Compliance Verification
- **Regular Audits:** Regular compliance audits
- **Policy Updates:** Policy update procedures
- **Training:** CJIS training requirements
- **Certification:** CJIS certification

---

## Testing

### Test Environment
- **Test Gateway:** NCIC test gateway
- **Test ORI:** Test ORI assignment
- **Test Queries:** Test query scenarios
- **Test Procedures:** Integration test procedures

### Test Scenarios
- **Person Query:** Test person queries
- **Vehicle Query:** Test vehicle queries
- **Error Handling:** Test error scenarios
- **Security:** Test security controls

---

## Troubleshooting

### Common Issues

#### Query Failures
- **Issue:** Queries not executing
- **Diagnosis:** Check network, ORI, certificates
- **Resolution:** Verify connectivity, ORI, certificates

#### Authentication Failures
- **Issue:** Authentication fails
- **Diagnosis:** Check ORI, certificates, credentials
- **Resolution:** Verify ORI, certificates, credentials

#### Response Processing Failures
- **Issue:** Responses not processing
- **Diagnosis:** Check response format, processing logic
- **Resolution:** Verify response format, fix processing

---

## References

- [CJIS Security Policy](https://www.fbi.gov/services/cjis/cjis-security-policy-resource-center)
- [NCIC Documentation](https://www.fbi.gov/services/cjis/ncic)
- [Architecture Documentation](../architecture/ARCHITECTURE.md)

---

**Document Owner:** Integration Developer  
**Last Updated:** 2024-12-20  
**Status:** Draft - In Progress  
**Classification:** Law Enforcement Use Only  
**Next Review:** 2024-12-27