Initial commit
This commit is contained in:
defiQUG
335
docs/integrations/ncic-integration.md
Normal file
335
docs/integrations/ncic-integration.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user