DeGPG

A program to facilitate more secure access to data

© 2004 Antone Roundy
Version 1.0.1 - 11/3/2004
Homepage & Latest Documentation

Contents


Introduction

DeGPG provides a web interface to GPG, to enable web scripts to access sensitive data in a manner more secure than storing it as plain text. GPG encrypts data using strong public key encryption so that even if someone gets access to the file or database containing the data, they will not be able to read it. Decrypting the data requires a passphrase. Without a program like DeGPG, web scripts needing access to the encrypted data would need the passphrase to be stored as plain text, or in some manner that offered only weak protection, which would render the GPG encryption next to useless or worse (worse because revealing the passphrase could comprimise additional encrypted data).

DeGPG gives web scripts access to encrypted data by decrypting it and storing it in memory, but not on disk. Note that if access to the raw encrypted data is required, then the protection offered by DeGPG is only a little greater storing the data unencrypted--not very strong--but if the web script only needs to access the MD5 hash or HMAC MD5 hash of the encrypted data, then DeGPG provides a valuable part of a significantly more secure system.

Requirements

The following are required to use DeGPG:
The following are required to use some features of DeGPG:
There may be other operating system requirements not listed here. DeGPG is only officially supported on UNIX-like systems (UNIX, Linux, BSD, etc.) You are encouraged to test the free version before purchasing the full version to ensure that your system supports all the functions required by DeGPG. No refunds will be provided if all or any features do not work on your system.

Free vs. Full Versions

The full version of DeGPG supports the following features, not available in the free version:

Installation

  1. Install and configure the software listed in the requirements section above.
  2. If desired (and if you have access to do so), create a new user account for DeGPG to execute as.
  3. If you create a new user, generate or copy GPG private and public keys to that user's .gnupg directory.
  4. Update "degpgusergrp" near the top of of degpg.sh with the username and groupname (in the form "username:groupname") you want DeGPG to execute as.
  5. [full version only] Create a "temp" directory in a suitable location where it will be accessible to degpg.pl. Ensure that the user of this directory is the user that degpg.pl will run as, and set its permissions to 700.
  6. Create an "encrypted" directory in a suitable location where it will be accessible to degpg.pl and give it the same permissions as the temp directory.
  7. Create a "fifos" directory in a suitable location where it will be accessible to degpg.pl and web scripts. Ensure that the user of this directory is the user that degpg.pl will run as, and set its permissions to 777, of for increased security, set its group to the group that your webserver runs as and set the permissions to 770. (If your webserver executes scripts as your user and group, set the group as appropriate).
  8. Update the path in the configuration section of degpg_interface.php to point to the same location.
  9. Update the paths in the configuration section of degpg.pl ($tempfiledir [full version only], $returnFIFOs, and %store_file{'datadir'}) to point to these directories.
  10. Update $frontdoor in the configuration section of degpg.pl to point to a location that will be writable by degpg.pl, and accessible to your web scripts. This value should include a path and a filename (degpg.pl will create the file).
  11. Update $frontdoor in the configuration sections of degpg_interface.php to point to the same location.
  12. Update $towho and $fromwho in the configuration section of degpg.pl with appropriate email addresses for any notifications sent by DeGPG.
  13. Verify that $mailcmd in the configuration section of degpg.pl points to your SMTP service.
  14. Upload degpg.pl to a suitable location such as /usr/bin, /usr/sbin, or some location in your user directory.
  15. Make sure that degpg.pl is executable by setting the "execute" bit in its permissions.
  16. Upload degpg_interface.php to a suitable location where it will be accessible to your web scripts.
  17. If you wish to use a mySQL database to store encrypted data (full verison only):
    • If necessary, create the database and/or table for the data using these commands (changing USERNAME and perhaps the database, table and field names as desired):
      create database degpg;
      use degpg;

      grant SELECT,INSERT,UPDATE,DELETE on degpg.* to USERNAME@localhost;

      create table degpg (
      keyname varchar(64),
      encrypted text
      );
    • Adjust the values in %store_mysql in degpg.pl as needed to match your database.
  18. The following steps assume you are running on a UNIX-like system. DeGPG may work, but is not supported, on other types of systems:
    Update the path in degpg.sh to point to the location where degpg.pl is located.
  19. Upload degpg.sh to /etc/init.d/ or whatever the location is where scripts are stored on your system to launch daemons.
  20. Make degpg.sh executable.
  21. Create symlinks to degpg.sh in your /etc/rd#.d/ directories, or whatever is necessary to launch DeGPG on your system.

Usage & Security

To use DeGPG, do the following (refer to degpg_test.php as an example or modify it as desired to fit your needs):
  1. Insert the following into your PHP code (changing the path as necessary to point to the location where you uploaded degpg_interface.php):
    require_once "/your/path/degpg_interface.php";
  2. Depending on which function you wish to perform, insert one of the following into your PHP code, substituting the appropriate values or variables in for the arguments to the function calls. See the following section (Protocol Technical Details) for explanations of the various function arguments. Note that in each function 'extras' refers to the 'mysql-?' options used to override the default mySQL settings. When indicating more than one of these, separate them with a tab character (\t). Arguments indicated in blue may be omitted as long as you do not need to enter a value for an aguement appearing later in the list:
    • $error_message = DeGPGEncrypt('key name', 'storage method', 'encryption method', 'passphrase', 'data', 'extras');
    • $error_message = DeGPGUnlock('key name(s)', 'storage method', 'retrieval methods allowed', 'passphrase', 'extras');
    • $decrypted_data = DeGPGRetrieve('key name', 'storage method', 'retrieval method', 'passphrase', 'prepend', 'append', 'extras', 'HMAC decrypted is key', 'HMAC data');

Note the following important security issues:

Protocol Technical Details

Commands are passed to the DeGPG daemon by writing a tab separated list of name=value pairs to the named pipe indicated by $frontdoor in degpg.pl. Except as noted, the order of the arguments does not matter (NOTE: this applies only when writing directly to the named pipe, not when calling the functions described above which are defined in degpg_interface.php). Values must not contain tabs, but may contain equals signs. The valid argument names for each command are as follows (names appearing in bold are required):

Common to all commands:

Encrypt:

Decrypt and store internally for later retrieval:

Retrieve:


Warning & Disclaimer

Any system which allows automated access to encrypted data is likely to become the weakest link in your security system. The purpose of DeGPG is to enable encrypted storage of sensitive data in situations where the data would otherwise have to be stored as plain text. We strongly recommend disabling DeGPG's "raw data" access method whenever possible (with the exception of one-time access where the user must supply the passphrase each time). "Raw data" access other than one-time access severly weakens the protection of the data. In cases where no other methods are suitable, you should carefully consider whether to use DeGPG at all.

We have made every effort to make DeGPG as secure as possible, but in no case can we guarantee that it will provide complete protection for your data. In particular, if a cracker is able to gain access to the memory where DeGPG stores decrytped data, or if they are able to gain access to data written out to a virtual memory cache, they may be able to access the decrypted data.

This software is provided as-is with no warrantee of suitability for any purpose. The user accepts all risks that this software may be compromised, enabling access to sensitive data. Use of this software in jurisdictions that do not permit such limitations of liability is prohibited.