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.

The following are required to use DeGPG:

• GPG
• Perl
• The ability to run daemons on your server

The following are required to use some features of DeGPG:

• mySQL
• Perl DBI interface to mySQL
• Perl MD5
• A suitable SMTP service, for example Sendmail or qmail

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.

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

• mySQL: store encrypted data in a database, retrieve and decrypt it from the database
• HMAC MD5: In addition the generating MD5 hashes of decrypted data, you may generate even more secure HMAC MD5 hashes
• One-time retrieval of encrypted data, requiring a passphrase to be supplied each time

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.

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:

• When designing forms that will be used to sensitive information, always use the "POST" method to submit them, never "GET". If you use "GET", any information submitted will be recorded as plain text in your web server log.
• Set the access permissions on your forms so that no one but you will be able to modify them. If they are modified, the form input could be sent to someone else's website, or they could change the submission method to "GET", and then access sensitive information from your server logs.
• Use secure HTTP (HTTPS) for any forms that will be used to submit sensitive information. Do not depend on people to have loaded the form itsself using secure HTTP--instead put the full URL, including "https://", in the form action to ensure that information is never submitted insecurely.

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:

• reply: The name of a named pipe which your script has created for DeGPG to send replies through. It must be located inside the directory indicated by $returnFIFOs in degpg.pl.
• cmd: "Command"--the requested action. Valid values are "unlock", "retrieve", and "encrypt".
• key: The name of the file or database key on which to perform the action. If indicating a filename, the file must be located inside the directory indicated by 'datadir' (in %store_file) in degpg.pl. Only one key may be specified for "encrypt" and "retrieve", but multiple keys may be indicated for "unlock". When indicating multiple keys, separate then with spaces.
• m-store: The storage method. Valid values are 1 (file) and 2 (mySQL database--full version only).
• mysql-db_name: Overrides the database name indicated in degpg.pl.
• mysql-table_name: Overrides the table name indicated in degpg.pl.
• mysql-key_field: Overrides the key field name indicated in degpg.pl.
• mysql-data_field: Overrides the data field name name indicated in degpg.pl.
• mysql-username: Overrides the username indicated in degpg.pl.
• mysql-password: Overrides the password indicated in degpg.pl.

Encrypt:

• m-encrypt: The encryption method to use. Valid values are 0 (recipient) and 1 (passphrase). When indicating recipient, the recipient's public key must be in the keyring used by DeGPG.
• recipient: The recipient for whom to encrypt the data. This is required if m-encrypt is 0.
• passphrase: The passphrase to use to encrypt the data. This is required if m-encrypt is 1.
• data: The data to encrypt. In this version of DeGPG, the data may not contain tabs or newlines. A future version may add the ability containing these characters. To ensure compatibility with future versions, data should always be the last argument send to DeGPG.

Decrypt and store internally for later retrieval:

• m-retrieve: The retrieval methods to allow for this data. Add all of the following which you wish to allow: 2 (raw), 4 (MD5 hash), 8 (HMAC MD5 hash--full version only). NOTE: Allowing raw retrieval will make data accessible to anyone who can log into your system who understands how to use DeGPG. Do not allow raw retrieval unless MD5 and MD5 HMAC access are not sufficient for your needs.
• passphrase: The passphrase to use to decrypt the data.

Retrieve:

• m-retrieve: The retrieval methods to use. Indicate one of following: 2 (raw), 4 (MD5 hash), 8 (HMAC MD5 hash). If the data has not yet been decrypted, or if the retrieval method you are indicating was not enabled when it was decrypted, add 1 to the above number and indicate the passphrase (full version only).
• passphrase: The passphrase to use to decrypt the data. Omit this unless adding 1 to m-retrieve as noted above.
• pre: Indicate any data to prepend to the decrypted data before applying the MD5 or HMAC MD5 hashing algorithm.
• post: Indicate any data to append to the decrypted data before applying the MD5 or HMAC MD5 hashing algorithm.
• decrypted-is-key: When using the HMAC MD5 retrieval method, indicate 0 to use the decrypted data as the key, and 1 to use data supplied as an argument as the key.
• data: When using the HMAC MD5 retrieval method, this data plays the role not indicated by "decrypted-is-key".

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.