# ReceivedKeyProcessorApp - Quick Reference Guide

**User and System Administration Documentation**

This document provides user guidance and system administration information. For technical implementation details, tag structures, and cryptographic algorithms, see [DEVELOPER.md](DEVELOPER.md).

---

## Application Overview

The **Received Key Processor Application** is a Windows desktop application for processing, managing, and analyzing cryptographic keys and mission data. It supports multiple key formats including MIDS JTRS, DS-100-1 TrKEK, and 8727 binary files with EKMS2 integration.

**Key Capabilities:**
- Parse and decode cryptographic key tags (MIDS JTRS, DS-100-1, JMPS, TR, IFF)
- View and edit MIDS JTRS tags with full field support
- Import 8727 binary files via EKMS2.exe integration
- SQLite database storage with hierarchical view
- Mission planning and key assignment
- Serial port communication for key transfer
- Calculate and validate ECU KEK IDs

---

## Quick Start - 5 Steps to Get Started

1. **Launch the Application**
   - Run `ReceivedKeyProcessorApp.exe` or press F5 in Visual Studio

2. **Select a Navigation Option**
   - Use the hamburger menu (left side) to access:
     - Main Page - Dashboard and status
     - Mission Plan - Configure missions
     - Database - View and search stored keys
     - 8727 FDU Viewer - View and edit tags
     - Send Keys - Transfer keys via serial
     - Test Key Generation - Generate test keys
     - Settings - Configure application
     - Log Viewer - View application logs

3. **View FDUs** (if you have FDU data)
   - Navigate to "8727 FDU Viewer"
   - Click "Browse" to select an FDU file (.8727, .bin, .key)
   - Click "Read File" to parse and display tag data

4. **Edit MIDS JTRS Tags**
   - In FDU Viewer, locate the MIDS JTRS Tag section
   - Click "Edit" to enable edit mode
   - Modify fields using dropdowns or text boxes
   - Click "Save" to update (CRCs auto-calculate)
   - Click "Cancel" to discard changes

5. **Search Database**
   - Navigate to "Database"
   - Use the search bar to filter by Short Title, Edition, or Segment
   - Click on entries to view details
   - Use "Add Test Data" to populate with sample records

---

## Main Navigation - Key Screens

| Screen | Purpose | Key Features |
|--------|---------|--------------|
| **Main Page** | Dashboard & status | Task selection, real-time processing status, system configuration |
| **Mission Plan** | Mission configuration | Create/manage missions, assign keys, validate plans |
| **Database** | Key storage & retrieval | Hierarchical tree view, search/filter, data export |
| **8727 FDU Viewer** | Tag analysis | View/decode tags, edit MIDS JTRS fields, calculate ECU KEK ID |
| **Send Keys** | Key transfer | Serial port communication, FDU transmission, Prepend FDU option |
| **Test Key Generation** | Create test keys | DS-100-1 TrKEK generation, multiple modes (Random, KnownValue, CustomRepeat, FileBased) |
| **Settings** | Configuration | Baud rate, protocol, database path, EKMS2 location |
| **Log Viewer** | View logs | Application logs, error tracking, debugging |

---

## Common Tasks

### View FDUs

1. Navigate to **8727 FDU Viewer**
2. Click **Browse** button
3. Select FDU file (.8727, .bin, .key, .8287, .xml, .json)
4. Click **Read File**
5. View decoded tag data in the display area

**Supported Formats:**
- 8727 Binary (.8727, .8287, .bin, .key)
- XML (.xml)
- JSON (.json)

---

### Edit MIDS JTRS Tags

1. Navigate to **8727 FDU Viewer**
2. Load an FDU file containing a MIDS JTRS tag
3. Click the **Edit** button in the MIDS JTRS Tag section
4. Modify fields:
   - **Dropdown fields**: Classification, Compartment, Waveform Affiliation, Control Method, Update Method, Update Rule, Crypto Period, Key Function, Source Tag Data Format Type
   - **Text fields**: Waveform Instance ID, Key Slot Reference ID, Short Title, Edition
   - **Numeric fields**: Internal JTRS Key ID, ECU KEK ID, Start Time, Update Count
   - **Hex fields**: Control Tag CRC, Overall Tag CRC (read-only, auto-calculated)
5. Click **Save** to apply changes (CRCs automatically recalculated)
6. Click **Cancel** to discard changes

**Important Notes:**
- CRC fields (Control Tag CRC and Overall Tag CRC) are always read-only
- CRCs are automatically recalculated when you save changes
- ECU KEK ID can be calculated from Short Title, Edition, and Segment using the "Calculate ECU KEK ID" button
- 0x00000000 ECU KEK ID indicates Red Key (No ECU KEK)

---

### Calculate ECU KEK ID

1. Navigate to **8727 FDU Viewer**
2. Load an FDU file with a MIDS JTRS tag
3. Click the **Calculate ECU KEK ID** button
4. View the calculated ECU KEK ID in the dialog
5. Click **Close** to exit (calculation mode only - does not update tag)

**Algorithm:**
- Uses ECU KEK ID calculation based on Short Title, Edition, and Segment Number
- Follows EKMS specification for hash-based validation

---

### Search Database

1. Navigate to **Database**
2. Use the search bar to filter by:
   - Short Title
   - Edition
   - Segment Number
3. Browse hierarchical tree view:
   - Keys (root level)
   - Short Titles (expandable)
   - Editions (expandable)
   - Segments (leaf nodes with key data)
4. Click on any node to view details
5. Use **Add Test Data** to populate with sample records

**Database Location:**
`%LOCALAPPDATA%\ReceivedKeyProcessorApp\keys.db`

---

### Import Keys

**From 8727 Binary Files:**

1. Navigate to **8727 FDU Viewer**
2. Click **Browse** to select binary file (.8727, .bin, .key)
3. Click **Read File**
4. Application automatically:
   - Converts binary to XML using EKMS2.exe
   - Validates generated XML
   - Imports data to SQLite database
   - Securely cleans up temporary files

**Requirements:**
- `EKMS2.exe` must be in the application directory
- Supported formats: .8727, .8287, .bin, .key, .xml, .json

---

### Generate Test Keys

1. Navigate to **Test Key Generation**
2. Configure basic information:
   - **Short Title**: Enter key short title (max 24 chars, 6-bit ASCII)
   - **Starting Edition**: Starting edition (A-ZZZZ)
   - **Ending Edition**: Ending edition (A-ZZZZ)
3. Configure key properties:
   - **Key Use**: Select key use type (FFK, KEK, TEK, TrKEK, etc.)
   - **Key Type**: Auto-populated based on Key Use
   - **Classification**: Select classification level
   - **Key Source**: Select key source device
   - **Key Length**: Enter key length in bytes (1-4000)
   - **Key Status**: Select key status (default: ISSUED)
   - **Caveat**: Select caveat level (default: CRYPTO)
4. Configure date and period settings:
   - **Starting Effective Date**: Set start date
   - **Crypto Period**: Select crypto period (daily, weekly, monthly, etc.)
   - **Supersession Rate**: Select supersession rate
   - **Text ID**: Enter optional Text ID
   - **Use TrKEK Identifier Logic**: Check to auto-generate TextID for TrKEK
5. Configure additional settings:
   - **ALC**: Select Accounting Legend Code
   - **NATO Ownership**: Select NATO ownership
6. Select **Key Generation Mode**:
   - **Random**: Generate cryptographically random bytes
   - **KnownValue**: Repeat pattern 0102030405060708090A0B0C0D0E0F
   - **CustomRepeat**: Repeat user-specified hex pattern
   - **FileBased**: Read key data from assigned files
7. For **FileBased** mode:
   - Click **Select Files for Segments...** to open file selection dialog
   - Assign files to individual segments or use global file assignment
   - All files must have the same size (validation enforced)
   - Key Length is auto-calculated from file(s)
8. Click **Calculate Segments** to preview segment configuration
9. Click **Generate Keys** to generate test keys
10. Click **Save to Database** to save generated keys

**Key Generation Modes:**

| Mode | Description |
|------|-------------|
| **Random** | Generates cryptographically random bytes of specified length |
| **KnownValue** | Repeats the pattern: 0102030405060708090A0B0C0D0E0F |
| **CustomRepeat** | Repeats a user-specified hex pattern |
| **FileBased** | Reads key data from assigned files (per-segment or global) |

**File-Based Key Generation:**

- **Per-Segment Assignment**: Select different files for each segment
- **Global Assignment**: Select one file to apply to all segments
- **Multi-Key Files**: Single file can contain multiple keys separated by newlines (raw binary)
- **Validation**: All files/keys must have the same size; errors displayed inline and in summary
- **Key Length Auto-fill**: Automatically calculated from file(s) when in file mode

**TrKEK Special Handling:**

- When Key Use is TrKEK (8), TextID is required
- TextID can be auto-generated from short title using "Use TrKEK Identifier Logic" checkbox
- Short title format warning displayed if non-standard format detected

---

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `F5` | Start debugging (Visual Studio) |
| `Ctrl+Shift+B` | Build solution |
| `Alt+Left` | Navigate back |
| `Ctrl+F` | Search (when in applicable view) |
| `Escape` | Cancel current edit/dialog |

---

## Quick Tips

**MIDS JTRS Tag Editing:**
- CRCs are automatically recalculated when you save - never edit them manually
- Use the "Calculate ECU KEK ID" button to verify the correct ECU KEK ID value
- 0xFFFFFFFF for StartTime means "Immediate" activation
- ECU KEK ID of 0x00000000 indicates a Red Key (no ECU KEK encryption)
- All dropdown fields display full names with hex/numeric values for clarity

**Database Management:**
- Use "Add Test Data" to quickly populate the database for testing
- The database is stored in `%LOCALAPPDATA%\ReceivedKeyProcessorApp\keys.db`
- Hierarchical view organizes keys by Short Title > Edition > Segment

**File Processing:**
- EKMS2.exe must be in the application directory for 8727 binary file processing
- Temporary files are securely zeroized after processing
- Log files are created in the temp directory for debugging

**Performance:**
- Large XML files (>10MB) may take up to 2 minutes to process
- Use the Log Viewer to track processing progress and errors
- For best performance, close unused views and applications

---

## Common Error Messages and Solutions

| Error Message | Cause | Solution |
|---------------|-------|----------|
| **EKMS2.exe not found** | EKMS2.exe missing from application directory | Place EKMS2.exe in the application's root folder |
| **Invalid binary file format** | File is not a valid 8727 binary | Verify file is a valid .8727, .bin, or .key file |
| **CRC validation failed** | Tag CRCs do not match calculated values | Verify tag data integrity; CRCs must be correct |
| **Database access denied** | Insufficient permissions for database file | Run as administrator or check folder permissions |
| **Serial port not available** | COM port in use or doesn't exist | Check COM port availability and close conflicting applications |
| **ECU KEK ID validation failed** | ECU KEK ID doesn't match SHA-1 hash | Use "Calculate ECU KEK ID" to verify correct value |
| **Failed to seed database** | NOT NULL constraint violations | Ensure string fields use empty strings instead of null |
| **Tag size incorrect** | MIDS JTRS tag not exactly 103 bytes | Verify tag structure and byte count |
| **Spare fields not zero** | Spare fields contain non-zero values | Ensure all spare fields (bits 32-33, 40-41, 336-341, 652-655) are 0 |
| **File size mismatch** | Files have inconsistent sizes for key generation | Ensure all assigned files have the same byte size |
| **No file assigned** | Segment has no file assigned in FileBased mode | Assign a file to each segment or use global file assignment |

**Where to Find Logs:**
- Application logs: Check **Log Viewer** page
- EF Core exceptions: `ef_core_exceptions.log` in application directory
- EKMS2 service: `RKPA_EKMS2_Service.log` in temp directory
- 8727 import: `RKPA_8727_Import.log` in temp directory

---

## Where to Get Help

**Documentation:**
- **README.md** - Complete application overview and architecture
- **Slick_Sheet.md** - This quick reference guide (User and System Administration)
- **DEVELOPER.md** - Developer documentation with technical details, tag structures, and cryptographic algorithms
- **EKMS2_Quick_Reference.md** - EKMS2.exe integration guide

**Testing:**
```bash
# Run all tests
dotnet test

# Run MIDS JTRS tests
dotnet test --filter "FullyQualifiedName~MIDS_JTRS"

# Run EKMS2 integration tests
dotnet test --filter "EKMS2IntegrationTests"
```

**Build and Run:**
```bash
# Build solution
dotnet build ReceivedKeyProcessorApp.sln

# Run application
dotnet run --project ReceivedKeyProcessorApp/ReceivedKeyProcessorApp.csproj
```

**Support Checklist:**
1. Check this slick sheet first
2. Review error logs in Log Viewer
3. Verify all prerequisites (.NET 8.0, EKMS2.exe location)
4. Test with known good file if available
5. Check application permissions

---

## Version Information

**Current Version:** v1.7.0

**Recent Enhancements:**
- ECU KEK ID Calculation UI with MSB-first byte ordering fix
- Real-time CRC recalculation during edit mode
- Dropdown-based editing for Classification, Compartment, Waveform Affiliation, Control Method, Update Method, Update Rule
- Complete MIDS JTRS tag editing with 23 fields
- DS-100-1 TrKEK support with multiple generation modes
- 8727 binary file processing with EKMS2.exe integration

---

**Print this guide and keep it handy for quick reference!**