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

// NCIC gateway endpoint
ncicGatewayEndpoint = "https://ncic-gateway.example.com/ncic"
ncicGatewayCertificate = "ncic-cert.pem"

ORI Configuration

// Originating Agency Identifier
ori = "XX12345" // Assigned by FBI
oriName = "Agency Name"
oriType = "LE" // Law Enforcement

UCN Configuration

// 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

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

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

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
• NCIC Documentation
• Architecture Documentation

---

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