SecureGeoPackage

User manual, plugin version 1.2. Encrypt layers and columns inside an ordinary GeoPackage, grant access by key, and open what you are allowed to read.

1. The idea in one minute

A GeoPackage is one file with layers and tables; anyone who can copy it can read all of it. SecureGeoPackage locks chosen layers (geometry included) or chosen columns (the map stays visible) inside that same file. Everything else stays a normal GeoPackage that opens in any GIS.

There are no passwords. Every person has an identity: a pair of keys made on their own computer. You hand out the public half (the identity card); the private half never leaves your machine. The admin of a file grants you access by adding your public half to the file. The file carries its own list of who may do what (the roster), under pseudonyms, and an admin signs the whole header, so tampering is detected when the file is opened.

Role	May
Reader	open the locked parts
Contributor	open; edit layers with encrypted columns and save the rows as pending contributions
Writer	open; edit any encrypted layer and save it back; validate contributions
Admin	everything, and alone: choose what is encrypted, grant, revoke, change the roster

2. Install and first start

Install the plugin from the plugin manager (or from a zip: Install from ZIP). It runs on QGIS 3.22 and later and on QGIS 4, on Windows, macOS and Linux, and brings its own cryptography.
Open it from the toolbar button or the Plugins menu. The panel docks on the right of the QGIS window; drag it to float it or to another side. It has three tabs and a ? button that opens this manual.
On the accessManager tab, under Own identity, press Manage identity... and then Create new identity.... The plugin stores your identity in the QGIS Authentication Manager (you will be asked for its master password if you never set one) or, without it, in the key store of your operating system.
Give yourself a pseudonym (what others see in rosters), a display name (stored only in the encrypted part of files you administer) and a public contact (how people can ask you for access).

Changing your pseudonym, display name or contact never changes your key. Only Create new identity..., Import from another machine... and Use identity file... replace it, and the plugin warns you in red before they do.

3. The three tabs

accessManager

Own identity: your fingerprint, where the identity is stored, Unlock (when the authenticator is on), Manage identity..., Copy identity card, Show as QR.
Access control: the roster of the current file (pseudonym, role, fingerprint, since, expiry, contact, and the name when you can read it); Grant access..., Change role..., Revoke, Request access.
File control: the public notice and the encryption algorithm.
Update access writes File control changes into the file and signs it.

contentManager

Open file... and the name of the open file; Output; the tree of layers and columns with a tick per encrypted item; Tick all, Untick all, Export unencrypted, Decrypt (Add to QGIS for an unencrypted file), Add from QGIS...; and Encrypt. A status line says how many layers are decrypted for editing.

editLog

The change log of the file (time, pseudonym, what), the filter Show edits since my last decrypt, and the Contributions section with Validate all pending and Verify.

4. Encrypt a file

contentManager, Open file.... Choose a GeoPackage, or any vector file: a shapefile, GeoJSON, KML or FlatGeobuf becomes name.gpkg beside the original and opens. If name.gpkg already exists you are asked whether to open it or make a new one.
The Output is proposed: name.secure.gpkg. Change it if you like.
In the tree, tick a layer to encrypt it whole, or expand it and tick columns to encrypt only those. The geometry row reminds you: the location on the map is hidden only when the whole layer is ticked. Tick all ticks every layer.
Optional: on accessManager, File control, write a public notice (for example "Restricted; ask the harbour master") and choose the algorithm (ChaCha20-Poly1305 is the default and the fastest without hardware support; AES-256-GCM is the other).
Press Encrypt. The plugin writes the output as a staging file and only renames it when everything succeeded: a failure never leaves a half-encrypted file under the output name.
You are the first admin of the new file. The dialog switches to accessManager so you can grant access. Your pseudonym, display name and contact are written into the file; the display name goes into the encrypted part only.

Layers that the plugin had added to the QGIS project and that are now encrypted leave the project; unencrypted ones stay.

5. Grant access

Ask the person for their identity card (accessManager, Copy identity card on their side; they can also mail it to you with Request access, see section 7).
Open the encrypted file, accessManager, Grant access.... Paste the egpkg-id:1:... line of the card into Public identity. Choose a role, type the pseudonym the card shows, an optional expiry date (2027-12-31 means the end of that day) and, if you wish, the real name, organisation and contact for the encrypted directory.
Check the fingerprint with the person by phone or in person if the card came by a channel you do not fully trust; the fingerprint is the first 16 characters shown on the card.
The grant is written and signed at once. Send the file, or tell the person where it is: the roster travels inside the file, so a copy on a network drive or a USB stick works.

Change role... and Revoke work on the selected roster row. Revoking removes the person's permit: they can no longer open the file. Copies they already made stay readable to them (section 17).

6. Open a file you were granted

contentManager, Open file..., choose the encrypted GeoPackage. The tree shows the layers; encrypted ones are ticked. accessManager shows the roster, the notice and your role.
Select layers (or none, for all) and press Decrypt. Behind the scenes the plugin makes a decrypted working copy in your temp folder and loads the layers from it. Writers and admins get editable layers; contributors can edit layers with encrypted columns; readers get read-only layers.
Press Encrypt when you are done, or close the plugin, lock it, or open another file: the layers leave the project and the working copy is deleted. Closing the plugin or QGIS with unencrypted edits asks first: Encrypt and close writes them into the file, Close without encrypting drops them, Cancel keeps everything open. Without a choice within five seconds the plugin encrypts and closes by itself. When the operating system ends the session (power button, log-off, shutdown) there is no time for a question: pending edits are encrypted at once.

Without a key you still see the unencrypted layers in any GIS, the notice, the roster (pseudonyms and roles) and whether the signature holds.

7. Ask for access

Open the file, accessManager, Request access. If the file's admins published a contact address, your mail program opens with a message to them and your identity card in the body. Otherwise your card is copied to the clipboard: paste it into a message to whoever gave you the file.

8. Edit encrypted layers

Writers and admins. Open the file, Decrypt, edit the layers in QGIS as usual (start editing, change, save). Then press Encrypt: the edited layers are written back into the encrypted file under its existing keys, so everyone who had access keeps it; the file is re-signed by you; the log records edited layers under your pseudonym; the layers leave the project and the working copy is removed. A writer cannot change which layers are encrypted; ticking a new layer or adding one is for an admin, whose Encrypt then re-encrypts with fresh keys.

Working with a colleague far away: encrypt and grant them as writer, mail the file; they Decrypt, edit, Encrypt, and mail it back; you open it and see their edits in the log, the content signed by them and the access list still signed by you. The mail provider in between sees nothing.

Column-encrypted layers can also be edited by GDAL, QGIS or any tool directly in the encrypted file, because the open columns are plain. Rows written that way by a contributor carry the contributor's signature and show as pending; rows written without a valid signature show as untrusted (section 10).

9. Add layers to an encrypted file

Admins only. Open the file, press Add from QGIS... and tick the project layers to add. They are copied into the working copy and appear in the tree; tick the ones that must be encrypted and press Encrypt. A layer whose name already exists in the file is refused: rename it in QGIS first. For an unencrypted working file, Add from QGIS... copies straight into the file.

10. Contributions and validation

A contributor opens the file, presses Decrypt (layers with encrypted columns are editable; wholly encrypted layers are not), adds or changes rows, and presses Encrypt. The new and changed rows go into the file with the contributor's signature; deleted rows are not carried over.

In a layer with encrypted columns every row carries the signature of the person who wrote it. The editLog tab shows, per such layer, how many rows are pending (written by a contributor, not yet validated) and how many are untrusted (no valid signature, or signed by someone without write rights). A writer or admin presses Validate all pending to countersign them. Editing a validated row makes it pending again, because its content changed. Verify checks the file signature and the integrity of every fully encrypted layer.

11. The edit log

The editLog tab lists what happened to the file: layers encrypted or decrypted, access granted, revoked or changed, notice changed, an admin who resigned, layers edited or added. Each line carries the time and the pseudonym of the admin who did it. The log lives in the encrypted part, so only key holders see it, and it survives re-encryption.

Show edits since my last decrypt keeps only the lines newer than the moment you last opened the file's content on this computer (added layers to QGIS, exported, or decrypted). The label shows that moment, or "never".

What the log proves: it is signed as a whole by the admin who last saved the file, so nobody without an admin key can alter it unnoticed. It does not prove each line separately, because any admin's software can write lines. Read it as the admins' account of the file, not as a forensic trail. Reads are not logged: a file cannot see who opens it; a file server can.

12. Export or decrypt

Export unencrypted writes to the Output path. Readers, contributors and writers get a readable copy: everything they hold keys for restored, everything else removed, no trace of the extension left. Admins get a full decrypt of the whole file. Untick all unticks every layer; with the Output set to the file itself, Encrypt then removes the encryption in place (admin).

13. Your identity: move, back up, replace

Another computer. Manage identity, Export for another machine... makes a transfer file and shows a one-time code. On the other computer: Import from another machine..., choose the file, type the code. Send the file and the code by different channels; delete both afterwards.
Back up. The transfer file with its code is your backup. Keep the code apart from the file. Without a backup and without the machine, the identity is gone; admins must grant a new one.
Replace. Create new identity... makes a new key. Every access you were granted under the old key is lost until each admin grants the new one. The plugin asks the authenticator code (when enabled) and shows a red warning first.
Where it lives. Windows, macOS and Linux with QGIS: the QGIS Authentication Manager, as an encrypted setting under its master password. Without a master password: Windows DPAPI, the macOS Keychain or the Linux Secret Service. The status line under Own identity says which.

14. The authenticator (second factor)

Manage identity, Enable authenticator.... Scan the QR code with an authenticator app (Microsoft Authenticator, Google Authenticator, Aegis, any RFC 6238 app) or type the setup key, then enter the six-digit code once. From then on the plugin asks a code when it starts and again before admin actions after five minutes. Disable authenticator... asks a code too.

Honest scope: this protects your identity against someone at your unlocked desk or with a copy of your key store. It does not protect against someone who controls your computer, and a file cannot check a code; the lock is in the plugin.

15. Admins, organisations, offboarding

A file can have several admins. Grant a second admin early: an admin cannot be demoted or revoked by another admin, and the last admin cannot resign.
An admin who wants to step down uses Change role... on their own row while another admin remains; the file records the resignation.
To leave a departed admin out, the remaining admins re-encrypt into a new file without them (Export unencrypted as admin, then encrypt the copy and grant everyone again).
An organisation can hold a central identity and grant it as admin on important files under a pseudonym that says so, for example "central identity (ISMS)". That identity opens every such file: keep it under dual control.
Offboarding a reader, contributor or writer: Revoke. For sensitive data also re-encrypt into a new file, because copies made before the revocation still open with the old key.

16. Public and private: what to share, what never

Share freely	Never share
Your identity card (Copy identity card, the QR): it starts with `egpkg-id:1:`. Holding someone's card gives you nothing of theirs; it only lets an admin grant them.	Your identity file (starts with `egpkg-identity:1:`), a transfer file together with its code, your QGIS master password, your authenticator setup key. Anyone with these is you for every file you were granted.

The encrypted file itself may be copied and mailed: without a key it shows only its public side.

17. What the plugin cannot do

Stop someone with access from taking a screenshot, exporting, or copying what they can read.
Log who opened the file. Use the file server's access log for that.
Reach copies that were made before an access was revoked.
Prevent someone from writing bytes into a file they can write on a shared drive; it can only make such writes visible (untrusted rows, a broken signature).
Hide row counts, layer and column names, or which values are empty.
Protect against a compromised computer or a stolen unlocked session.

18. Troubleshooting

Message or symptom	What to do
"is held by another program (a layer in QGIS?)"	Remove the layers of that file from the QGIS project (the plugin's own layers leave when you press Encrypt) and try again.
"An identity is stored but cannot be loaded"	Enter the QGIS master password (Settings, Options, Authentication) and reopen the plugin. Do not create a new identity: that would replace the stored one.
"Signature: INVALID - do not trust this file"	The header was altered after the last admin signed it, or the issuer was replaced. Ask an admin for a fresh copy. Nothing in it should be trusted.
"You hold no key for this file"	You are on the roster but your permit is missing or expired, or the file was re-encrypted without you. Ask an admin to grant you again.
"These layers exist already"	Rename the QGIS layer before Add from QGIS.
"Choose an output file"	For an unencrypted file the output must differ from the input; for an encrypted one it may be the file itself.
A working copy stays in the temp folder	QGIS still held the file, or QGIS crashed or lost power. The plugin retries on close and sweeps leftovers of earlier sessions at the next start, and says so in the QGIS log (SecureGeoPackage). Disk encryption on the computer (BitLocker, FileVault, LUKS) is the control for the minutes in between.
The code from the app is refused	Check the clock of the phone and the computer; each code is valid once.

19. Glossary

Identity	your key pair; public half shared, private half kept.
Identity card	the public half as text or QR, with your pseudonym and contact.
Fingerprint	16 characters that identify a public half; check it out of band.
Roster	the public list in the file of who has which role, under pseudonyms.
Permit	the keys of a file, wrapped for one identity; made when access is granted.
Notice	public text in the file, shown to everyone.
Working copy	a temporary decrypted copy the plugin uses to show and edit layers.
Pending, validated, definitive, untrusted	the four states of a row in a column-encrypted layer, derived from its signatures and the roster.
egpkg_encryption	the GeoPackage extension the files use; proposed to the OGC GeoPackage working group.

SecureGeoPackage, a private production by Captain Ahab & Cosmo, GPL-3.0-or-later. The embedded egpkg library is MIT. Manual for version 1.2.5, September 2026.