1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
---
title: "Application Secure Key"
sidebar:
label: Application Secure Key
---
To enhance the protection of application data, GpgFrontend automatically
generates and manages a dedicated Application Secure Key. This key is used to
encrypt sensitive internal data—such as certain configuration files, key server
settings, and key generation profiles—distinct from user PGP keys. Key
management adapts according to the configured security level and user
preferences.
## Key Features
### Automatic Key Generation
- Upon first use or initialization, GpgFrontend generates a high-entropy random
key. Since v2.1.9, this is done using OpenSSL’s secure random generator for
maximum security. Prior to v2.1.9, QRandom’s generator was used.
- If OpenSSL secure random is unavailable, a fallback random generator is used,
with a warning provided for lower security levels.
- Application secure keys are stored with operating system file permissions set
to restrict access to the current user only, even if stored in plaintext.
:::tip[HOW TO]
SecureLevel is configured in the same way as described in the memory security
documentation: simply add or edit a line such as `SecureLevel=1` in your
`ENV.ini` file located in the working directory. This allows flexible adjustment
of both memory and key security to fit your needs.
:::
### Data Encryption Algorithms
- Default Encryption: Application data (such as dynamic configuration, key
server settings, and key generation profiles) is encrypted using AES-GCM 128
for confidentiality and integrity.
- PIN-based Key Encryption (SecureLevel ≥ 3): Starting from SecureLevel 3, the
application secure key itself is encrypted on disk using a key derived from
the user’s PIN via Argon2ID and then AES-GCM 256. This means that upon
startup, the user must enter their PIN to decrypt the secure key and access
protected application data.
- General Configuration: Most standard, non-sensitive configuration data is not
encrypted by default.
## Key Storage and File Protection
Application secure keys are stored in the application’s secure key directory,
identified by a partial HMAC of their encrypted content. Even when stored in
plaintext (SecureLevel < 3), file system permissions ensure that only the
current user can access the key files.
### PIN Protection & Key Structure (SecureLevel ≥ 3)
At SecureLevel 3 or higher:
- The user is prompted to enter a PIN at application startup.
- The master key (application secure key) is encrypted with a PIN-derived key
and stored using AES-GCM 256.
- After PIN entry, only the encryption key (derived and rotated weekly) is used
for encrypting/decrypting application data. The master key itself is not used
directly for data encryption.
- The encrypted master key must be successfully decrypted with the PIN-derived
key for the application to function.
### Key Rotation and Data Migration
- **Key Rotation**: For maximum security, GpgFrontend automatically rotates the
encryption key on a weekly basis. Each new key is derived using Argon2ID and a
time-based salt.
- **Automatic Data Migration:** When the encryption key is rotated, existing
application data is automatically re-encrypted with the new key. This ensures
ongoing data protection with minimal user intervention.
### Historical Changes
- Before v2.1.9:
- Application data was encrypted with AES-ECB 256 (a less secure mode).
- Random keys were generated using QRandom.
- The master key was used directly for data encryption.
- Since v2.1.9:
- Encryption uses AES-GCM 128 for data, and AES-GCM 256 for PIN-based key
wrapping.
- Key generation relies on OpenSSL’s random number generator.
- The introduction of key hierarchy and rotation enhances security, with
legacy data seamlessly migrated to new standards.
## Security Levels and Functionality
| SecureLevel | Key Generation | PIN Protection | Key Rotation | Key Storage | User Prompt at Startup |
| ----------- | ---------------------------- | -------------- | ------------ | ------------------------------- | ---------------------- |
| 0, 1, 2 | Automatic, plaintext storage | No | No | File permissions | No |
| 3 or higher | Automatic, encrypted storage | Yes | Yes | PIN-encrypted, file permissions | Yes |
- At SecureLevel < 3, the key is generated and stored in plaintext (with OS
permissions).
- At SecureLevel ≥ 3, PIN protection and regular key rotation are enforced; application startup requires PIN entry.
## **Downgrade Support and Data Separation**
GpgFrontend supports **downgrade** operations for SecureLevel. If you initially
start GpgFrontend with SecureLevel set to 3 or higher (enabling PIN protection
and advanced encryption), you can later change the SecureLevel to a lower value
(such as 0, 1, or 2). In this case:
- GpgFrontend will start normally and will restore all application data
associated with the lower SecureLevel. Any data previously created or modified
under this SecureLevel will be accessible as before, while the data protected
under SecureLevel 3 remains securely stored and inaccessible in this mode.
- You can switch the SecureLevel back to 3 (or higher) at any time. After you
enter the correct PIN, all your previous application data—including
configuration, key server settings, and other protected content—will be fully
restored and available.
- You can freely alternate between SecureLevel 3 and any lower level. Each time
you return to SecureLevel 3 and successfully authenticate with your PIN, your
original encrypted application data will be available. When you downgrade
again, the application data from the lower SecureLevel (as it was before
upgrading) will be restored.
:::caution
You must initially set SecureLevel to 3 or higher on the first launch
to enable this feature. It is not possible to enable SecureLevel 3 for the first
time if the application was previously initialized with a lower SecureLevel.
:::
## Technical Notes
- **Encryption Algorithms:**
- Application data: AES-GCM 128
- Key encryption (PIN-derived): AES-GCM 256
- **Key Derivation:** Argon2ID with robust parameters for resistance to
brute-force attacks.
- **Key IDs:** Calculated using HMAC-SHA256 for uniqueness and integrity.
- **Secure Memory:** All key material is managed in secure memory (if enabled),
and sensitive values are securely erased after use.
## Best Practices & Recommendations
- For the best protection of application data, set SecureLevel to 3 or higher
and use a strong, memorable PIN.
- Keep a backup of your PIN in a safe place, as losing the PIN may render
encrypted data inaccessible.
- Watch for application warnings about key generation, encryption, or system
cryptography support.
## Troubleshooting
- Key File Cannot Be Saved: Ensure the application has permission to write to
its secure key directory.
- PIN Incorrect: If you forget your PIN or cannot unlock your key, you may need
to reinitialize the secure key. This will create a new key, making old
encrypted data inaccessible.
- Cryptographic Support Warning: If OpenSSL or secure random functions are
unavailable, less secure fallback methods are used and the application will
notify you.
## Feedback and Development
All secure key management and related enhancements have been introduced in
v2.1.9. GpgFrontend’s secure key management continues to evolve. Users are
encouraged to review the implementation, report issues, and suggest
improvements. The development team is committed to maintaining robust security
standards and welcomes community participation.
|
