EasyPGP Android Application - Copilot Instructions

Project Overview

EasyPGP is an Android application that provides PGP (Pretty Good Privacy) encryption and decryption functionality. The app allows users to generate PGP key pairs, import public keys from others, and encrypt/decrypt messages with a user-friendly interface.

Architecture Overview

Package Structure:

com.yourdev.easypgp

Core Components

1. MainActivity.kt

Purpose: Main activity providing encryption/decryption UI
Key Features:
- Text encryption/decryption interface
- Keyring timeout management (10 seconds)
- Password-protected keyring with automatic locking
- Clipboard integration for encrypted/decrypted text
- Status display showing keyring state (LOCKED/UNLOCKED/KEYS LOADED)
Key Variables:
- ```
keyringPassword: String
```
  - Current keyring password
- ```
timestamp: Long
```
  - Last activity timestamp for timeout
- ```
timeoutValue: Long
```
  - Timeout duration (10 seconds)
- ```
myPGPKeyPair: PGPKeyPair?
```
  - User's loaded key pair
- ```
importedKeys: List<ImportedPublicKey>
```
  - List of imported public keys

UI Elements:

btnSettings

btnEncrypt

btnDecrypt

btnUnlock

```
editTextInput
```
- Text input field
```
textViewOutput
```
- Output display
```
textViewStatus
```
- Status indicator
```
spinnerRecipients
```
- Recipient selection

2. SettingsActivity.kt

Purpose: Settings screen for key management
Key Features:
- PGP key pair generation with password protection
- Public key export to clipboard
- Import public keys from others with custom names
- RecyclerView for managing imported keys
Companion Object: Contains static
```
myPGPKeyPair
```
reference

3. PGPUtil.kt

Purpose: Core PGP cryptographic operations
Dependencies: BouncyCastle cryptographic library

Key Methods:

generateKeyPair(identity: String, passphrase: String): PGPKeyPair

encrypt(plaintext: String, publicKey: PGPPublicKey): String

decrypt(encryptedText: String, privateKey: PGPPrivateKey): String

getPublicKeyString(publicKeyRing: PGPPublicKeyRing): String

Data Classes:

PGPKeyPair(publicKey, publicKeyRing, secretKeyRing)

4. KeyManager.kt

Purpose: Secure key storage and management with AES-256-GCM encryption
Security Features:
- Android KeyStore integration for hardware-backed encryption
- AES-256-GCM encryption for private key storage
- Dual storage: unencrypted (initial) and encrypted (after timeout)
Key Methods:
- ```
saveMyKeyPair(keyPair: PGPKeyPair)
```
  - Save user's key pair
- ```
loadMyKeyPair(): PGPKeyPair?
```
  - Load user's key pair
- ```
encryptPrivateKeyAndStore()
```
  - Encrypt private key with AES
- ```
decryptStoredPrivateKey()
```
  - Decrypt private key from storage
- ```
saveImportedKey()
```
  ,
```
getImportedKeys()
```
  - Manage imported public keys
Storage Locations:
- SharedPreferences:
```
"pgp_keys"
```
- Public key:
```
"my_public_key"
```
- Unencrypted private key:
```
"my_private_key_unencrypted"
```
- Encrypted private key:
```
"my_private_key_encrypted"
```

5. PasswordDialog.kt

Purpose: Secure password input dialog
Features:
- Password masking input
- Callback interface for password handling
- Suspend function support for coroutines

Interface:

PasswordCallback

with

onPasswordEntered()

and

onPasswordCancelled()

6. ImportedPublicKey.kt

Purpose: Data class for imported public keys
Properties:
```
name
```
,
```
publicKey
```
,
```
keyId
```
,
```
keyString
```

7. ImportedKeysAdapter.kt

Purpose: RecyclerView adapter for managing imported keys list
Features: Delete functionality with confirmation

UI Layout Structure

activity_main.xml

Layout: ConstraintLayout
Key Elements:
- Title and version display
- Status indicator (
```
textViewStatus
```
  )
- Settings and Unlock buttons
- Recipient spinner
- Input text area
- Encrypt/Decrypt buttons
- Output text area (clickable for clipboard copy)

activity_settings.xml

Layout: ConstraintLayout
Sections:
- My PGP Keys section with generation/export
- Import Public Keys section
- RecyclerView for imported keys management

item_imported_key.xml

Layout: LinearLayout for RecyclerView items
Elements: Key name, key ID, delete button

Security Architecture

Encryption Layers

PGP Layer: Message encryption using RSA-2048 keys
AES Layer: Private key storage encryption (AES-256-GCM)
Android KeyStore: Hardware-backed key protection

Key Lifecycle

Generation: Keys created with user password in SettingsActivity
Initial Storage: Saved unencrypted in SharedPreferences
Timeout Encryption: After 10 seconds, private key encrypted with AES
Unlock Process: AES decryption + PGP password verification

Security Features

Automatic keyring locking after 10 seconds of inactivity
Hardware-backed encryption keys when available
No password storage - only encrypted private keys persist
Cryptographic verification during unlock process

Development Guidelines

Code Style

Language: Kotlin with coroutines for async operations
UI: Material Design components
Architecture: Activity-based with utility classes
Threading: Main thread for UI, IO dispatcher for crypto operations

Key Dependencies

BouncyCastle for PGP operations
Android KeyStore for AES encryption
Kotlin Coroutines for async operations
RecyclerView for list management
SharedPreferences for local storage

Error Handling

Try-catch blocks around all cryptographic operations
User-friendly error messages via Toast
Graceful degradation when keys are missing/corrupted
Status indicators for user feedback

Testing Considerations

Mock KeyManager for unit tests
Test key generation/storage/retrieval flows
Verify encryption/decryption round trips
Test timeout and unlock scenarios

Common Tasks

Adding New Features

UI Changes: Update appropriate activity layout XML
Business Logic: Add methods to relevant utility classes
Storage: Extend KeyManager if persistent data needed
Security: Follow existing AES encryption patterns

Debugging Key Issues

Check
```
textViewStatus
```
for current keyring state
Verify
```
hasMyKeys()
```
and
```
loadMyKeyPair()
```
results
Monitor SharedPreferences keys in debug mode
Test unlock flow with encryption/decryption verification

Performance Considerations

Crypto operations run on IO dispatcher
UI updates use
```
withContext(Dispatchers.Main)
```
Lazy loading of imported keys
Efficient RecyclerView updates

Integration Points

External Libraries

BouncyCastle: PGP operations (import/export format compatibility)
Android KeyStore: Hardware security module integration
Material Components: UI consistency

System Integration

Clipboard: Automatic copy of encrypted/decrypted text
Storage: SharedPreferences for app-private data
Security: Android permission model compliance

Troubleshooting Common Issues

Key Loading Problems

Ensure
```
keyManager.hasMyKeys()
```
returns true
Check if keys are encrypted vs unencrypted state
Verify SharedPreferences contains expected key data

Encryption/Decryption Failures

Validate PGP password during unlock process
Check BouncyCastle provider initialization
Verify key format compatibility

UI State Issues

Monitor keyring timeout timer lifecycle
Ensure proper UI thread updates
Check Activity lifecycle method integration

This documentation reflects the current state of EasyPGP as of September 26, 2025.