SecureGeoPackage

User manual, plugin version 1.3. 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. The public ID is what you hand out, always as a small file name.publicid (Save public ID...); it holds nothing private. The private ID never leaves your computer: it is not shown, not copied, not mailed, and every button that comes near it warns you first. Anyone who has your private ID is you. The admin of a file grants you access by adding your public ID 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.

2. Install and first start

1. 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.
2. 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 with a small menu: Quick start, the one-page card with the five steps; Manual, this document; the version and the day it was installed; and License.... The quick-start card opens by itself the first time the panel is shown; tick Don't show this again to stop that.
3. On the Access tab, under Own identity, press Set up... and then Create a 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.
4. 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).

2b. The look, the theme, the words

The plugin, the standalone program and the ArcGIS Pro add-in share one look: the same sections in the same order (Identity, File, Layers, the verbs, Roster, Contributions, Log), the same words (Open..., Decrypt, Encrypt, Readable copy..., Verify, Grant..., Set up...), and the same colours: one action blue; a coloured chip for every role (admin, writer, contributor, reader) and every row state (definitive, validated, pending, untrusted); a lock for an encrypted layer, green when your key opens it, grey BLOB when it does not. The theme switch at the top right offers Auto, which follows QGIS, Light and Dark; the choice is remembered.

3. The three tabs

Access

Own identity: your fingerprint, where the identity is stored, Unlock (when the authenticator is on), Set up..., Save public ID.... The private ID is not shown.
Access control: the roster of the current file (pseudonym, role, fingerprint, since, expiry, contact, and the name when you can read it); Grant..., 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.

Content

Open... and the name of the open file; a status line; Output (for a file that is not encrypted yet); the tree of layers and columns with a tick per encrypted item; Tick all, Untick all, Readable copy..., Decrypt (Add to QGIS for an unencrypted file), Add from QGIS...; and Encrypt.

The tree shows an encrypted file as your key opens it. A layer your key opens is listed as it really is: its original type (features or attributes), its geometry with the geometry type, every column with its declared type, and the row count. A layer your key does not open is shown as what it is on disk: one egpkg_payload BLOB column. For an encrypted file the Output field is hidden, because Encrypt writes the file in place; the status line says how many encrypted layers your key opens, or that you are not on the roster.

Log

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

4. Encrypt a file

1. Content, Open.... 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.
2. The Output is proposed: name.secure.gpkg. Change it if you like.
3. 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.
4. Optional: on Access, 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).
5. 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.
6. You are the first admin of the new file. The dialog switches to Access 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.

5. Grant access

1. Ask the person for their public ID file. On their side: Save public ID... writes name.publicid to mail you, and Request access... (section 7) does that and opens the mail in one go.
2. Open the encrypted file, Access, Grant.... Press Pick public ID file... and choose the file: the public identity, the pseudonym and the contact are filled in. A private ID file is refused with a warning: if you get one, tell the person never to send it again. Choose a role, check the pseudonym, 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.
3. Check the fingerprint with the person by phone or in person if the file came by a channel you do not fully trust; the fingerprint is the 16 characters on the second line of the file.
4. 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

1. Content, Open..., choose the encrypted GeoPackage. The tree shows the layers; encrypted ones are ticked, and the ones your key opens are listed with their real columns and row counts (without a key they stay a single BLOB column). Access shows the roster, the notice and your role.
2. Select the layers you want in the tree (click, Ctrl-click for several), or none for the whole file, 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.
3. 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, Access, Request access.... Your public ID is saved as name.publicid and, if the file's admins published a contact address, your mail program opens with a message to them: attach that file and send. Otherwise send the file 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.

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 Log 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 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 Log 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".

12. Export or decrypt

Readable copy... asks where to write the copy (proposed: name.open.gpkg beside the file). 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; Encrypt then removes the encryption in place (admin).

13. Your identity: move, back up, replace

• Another computer. Set up..., Back up private ID... makes a locked backup file and shows a one-time code. On the other computer: Restore private ID..., choose the file, type the code. Carry the file and the code by different channels; delete both afterwards. Both buttons show the private-ID warning first.
• Back up. The backup 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 a 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.

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 (Readable copy... 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

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

19. Glossary

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