The commands here are all line oriented to illustrate that they can be automated by being called from GT.M or from a shell script. For interactive use, there are many graphical user interfaces (GUIs) usable with GPG. Although these examples were generated on Linux, usage on other UNIX systems should be virtually identical.
This is an example of key management using GPG and the reference implementation.
Helen Keymaster (helen@gt.m) is the master of keys, and provides a database key to Phil Keyuser (phil@gt.m). Helen does not manage the database. Phil is the database manager, but he is not the master of keys.In order to communicate securely, Helen and Phil each set up a GPG keyring, generate a public / private key pair, and exchange & authenticate each other's public keys. This permits a secure transfer of the key for the symmetric cipher used for the database.Warning: If you attempt key generation on a virtual machine, or other computer system that does not have a good supply of entropy, the gen_key_pair.sh script could take a very, very long time. Similarly, a key quality of 2 for the gen_sym_key.sh script on a machine without a plentiful supply of entropy can also tax your patience. Use a physical computer system with a lot of entropy. If you are able to, use an entropy gathering daemon such as egd (http://egd.sourceforge.net), or consider acquiring an entropy source such as the Entropy Key (http://www.entropykey.co.uk) that you can use to distribute entropy to your virtual machines.
The workflow is as follows:
-
Helen and Phil each create a new GPG keyring and a new public-private key pair[5]. In the gen_keypair.sh script GPG generates the key pair[6], putting public and private keys in the key ring; the latter locked with a passphrase. The public key is also exported to a text file, and its fingerprint is displayed in the terminal session. Each of them e-mails (or otherwise sends) her/his public key text file to the other[7]. This is illustrated below; first Helen, then Phil (if the GNUPGHOME environment variable is not set, it will default to
$HOME/.gnupg).
-
Helen e-mails helen@gt.m_pubkey.txt the file containing her exported public key to Phil, and Phil sends phil@gt.m_pubkey.txt, his exported public key to Helen. To protect against "man in the middle" attacks, they speak on the phone to exchange keyfingerprints, or send each other the fingerprints by text message,or facsimile - a different communication channel than that used to exchange the keys. Phil does likewise with Helen's key. They use the import_and_sign_key.sh shell script. After importing and signing each other's public keys, Phil and Helen can communicate securely with each other, even in the presence of eavesdroppers. Helen's keyring with Phil's imported key is shown below:
Using the gen_sym_key.sh script, Helen generates a symmetric cipher key for Phil to use in encrypting a new database file cust.dat. With a key strength of 2, a symmetric key is suitable for use in production and in the example is stored in file helen_cust_dat.txt encrypted with Helen's public key so that only she can decrypt it. The gen_sym_key.sh script never displays the symmetric cipher key; the key in the text file on disk can only be decrypted with Helen's private key.
-
With the encrypt_sign_db_key.sh script, Helen uses her private key to decrypt the symmetric cipher key in helen_cust_dat.txt, encrypts it with Phi's public key, and signs it with her private key, creating a file called phil_cust_dat.txt. She sends this file to Phil, either as an e-mail attachment, or putting it in a mutually agreed upon location on disk. As before, even though the key is on disk, it can be decrypted only with Phil's private key. Note that from this point on, even if Helen is hit by a truck, or resigns, Phil has access to the key and can use the same encrypt_sign_db_key.sh script to provide the key to, say, Xavier, Helen's successor. Helen preparing the key for Phil is shown below.
-
With the add_db_key.sh script, Phil now adds the key to his GT.M master key file. He can then create the encrypted database file with mupip create, load it with data and use it. Until the database is created and loaded with data, the key has no value and can be discarded at will. Once the database is created and loaded with the data, the key must be retained as long as access to the database - or even a backup thereof - is ever required. The entire process is illustrated below:
As a final check to make sure that the database was created with the correct symmetric cipher key and the correct cipher, Helen can use the gen_sym_hash.sh script to compute a hash from the key in helen_cust_dat.txt while Phil uses GT.M's dse dump -fileheader -all command to print the key from the file header of the database file he creates. If the hashes match, the database file has been correctly created.
Below are scripts of the key management example above.
Helen creates a new GPG keyring with a public and private key pair:
helen$ export GNUPGHOME=$PWD/.helengnupg helen$ $gtm_dist/plugin/gtmcrypt/gen_keypair.sh helen@gt.m Helen Keymaster Passphrase for new keyring: Verify passphrase: Key ring will be created in /home/helen/.helengnupg Key generation might take some time. Do something that will create entropy, like moving the mouse or typing in another session. gpg: checking the trustdb gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u /home/helen/.helengnupg/pubring.gpg --------------------------------- pub 1024D/BC4D0739 2010-05-07 Key fingerprint = B38B 2427 5921 FFFA 5278 8A91 1F90 4A46 BC4D 0739 uid Helen Keymaster <helen@gt.m> sub 2048R/A2E8A8E8 2010-05-07 Key pair created and public key exported in ASCII to helen@gt.m_pubkey.txt helen$
Phil creates a new GPG keyring with a public and private key pair:
phil$ export GNUPGHOME=$PWD/.philgnupg phil$ $gtm_dist/plugin/gtmcrypt/gen_keypair.sh phil@gt.m Phil Keyuser Passphrase for new keyring: Verify passphrase: Key ring will be created in /home/phil/.philgnupg Key generation might take some time. Do something that will create entropy, like moving the mouse or typing in another session. gpg: checking the trustdb gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u /home/phil/.philgnupg/pubring.gpg --------------------------------- pub 1024D/A5719A99 2010-05-07 Key fingerprint = 886A BAFC E156 A9AD 7EA9 06EA 8B8B 9FAC A571 9A99 uid Phil Keyuser <phil@gt.m> sub 2048R/AD37D5A0 2010-05-07 Key pair created and public key exported in ASCII to phil@gt.m_pubkey.txt phil$
Then Helen sends Phil the file helen@gt.m_pubkey.txt and Phil sends Helen the file phil@gt.m_pubkey.txt.
Helen imports Phil's public key into her keyring, verifying the fingerprint when she imports it, and signing it to confirm that she has verified the fingerprint:
helen$ $gtm_dist/plugin/gtmcrypt/import_and_sign_key.sh phil@gt.m_pubkey.txt phil@gt.m gpg: key A5719A99: public key "Phil Keyuser <phil@gt.m>" imported gpg: Total number processed: 1 gpg: imported: 1 ######################################################### pub 1024D/A5719A99 2010-05-07 Key fingerprint = 886A BAFC E156 A9AD 7EA9 06EA 8B8B 9FAC A571 9A99 uid Phil Keyuser <phil@gt.m> sub 2048R/AD37D5A0 2010-05-07 ######################################################### Please confirm validity of the fingerprint above (y/n/[?]): y Passphrase for keyring: Successfully signed public key for phil@gt.m received in phil@gt.m_pubkey.txt helen$
Phil likewise imports, verifies and sign's Helen's public key:
phil$ $gtm_dist/plugin/gtmcrypt/import_and_sign_key.sh helen@gt.m_pubkey.txt helen@gt.m gpg: key BC4D0739: public key "Helen Keymaster <helen@gt.m>" imported gpg: Total number processed: 1 gpg: imported: 1 ######################################################### pub 1024D/BC4D0739 2010-05-07 Key fingerprint = B38B 2427 5921 FFFA 5278 8A91 1F90 4A46 BC4D 0739 uid Helen Keymaster <helen@gt.m> sub 2048R/A2E8A8E8 2010-05-07 ######################################################### Please confirm validity of the fingerprint above (y/n/[?]): y Passphrase for keyring: Successfully signed public key for helen@gt.m received in helen@gt.m_pubkey.txt phil$
Helen and Phil can now securely exchange information.
Helen generates a symmetric cipher key for the new database file cust.dat:
helen$ $gtm_dist/plugin/gtmcrypt/gen_sym_key.sh 2 helen_cust_dat.txt helen$
Then she encrypts the symmetric cipher key with Phil's public key, signs it, and produces a file phil_cust_dat.txt that she can send Phil:
helen$ $gtm_dist/plugin/gtmcrypt/encrypt_sign_db_key.sh helen_cust_dat.txt phil_cust_dat.txt phil@gt.m Passphrase for keyring: gpg: checking the trustdb gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model gpg: depth: 0 valid: 1 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 1u gpg: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u helen$
Phil adds the key in phil_cust_dat.txt to his master key file $HOME/.gtm_dbkeys:
phil$ export gtm_dbkeys=$HOME/.gtm_dbkeysphil$ $gtm_dist/plugin/gtmcrypt/add_db_key.sh $PWD/gtm.dat phil_cust_dat.txt $gtm_dbkeys phil$
Phil creates a global directory, where he changes the configuration parameter for the database file cust.dat specifying that it be encrypted the next time it is created. (Remember that except for mapping from global variable names to database file names, configuration parameters in the global directory are used only when MUPIP creates new database files.) He then creates the database file, runs a DSE dump fileheader to extract the hash (highlighted in the output), and sends it to Helen for verification (notice that MUPIP CREATE generates an error for the mumps.dat file that exists already, but creates a new encrypted cust.dat file):
phil$ export gtmgbldir=gtm.gld phil$ export gtm_passwd="" phil$ $gtm_dist/mumps -dir Enter Passphrase: GTM>zsystem "$gtm_dist/mumps -run GDE" %GDE-I-LOADGD, Loading Global Directory file /var/myApp/databases/gtm.gld %GDE-I-VERIFY, Verification OK GDE> change -segment DEFAULT -encryption GDE> exit %GDE-I-VERIFY, Verification OK %GDE-I-GDUPDATE, Updating Global Directory file /var/myApp/databases/gtm.gld GTM>zsystem "$gtm_dist/mupip create" Created file /var/myApp/databases/gtm.dat Error opening file /var/myMpp/databases/mumps.dat : File exists %GTM-F-DBNOCRE, Not all specified database files, or their associated journal files were created GTM>zsystem "dse" File /var/myApp/databases/cust.dat Region CUST DSE> dump -fileheader -all File /var/myApp/databases/cust.dat Region CUST Date/Time 04-MAY-2010 11:24:10 [$H = 61850,41050] Access method BG Global Buffers 1024 Reserved Bytes 0 Block size (in bytes) 1024 Maximum record size 256 Starting VBN 129 Maximum key size 64 Total blocks 0x00000065 Null subscripts NEVER Free blocks 0x00000062 Standard Null Collation FALSE Free space 0x00000000 Last Record Backup 0x0000000000000001 Extension Count 100 Last Database Backup 0x0000000000000001 Number of local maps 1 Last Bytestream Backup 0x0000000000000001 Lock space 0x00000028 In critical section 0x00000000 Timers pending 0 Cache freeze id 0x00000000 Flush timer 00:00:01:00 Freeze match 0x00000000 Flush trigger 960 Current transaction 0x0000000000000001 No. of writes/flush 7 Maximum TN 0xFFFFFFFFE3FFFFFF Certified for Upgrade to V5 Maximum TN Warn 0xFFFFFFFF73FFFFFF Desired DB Format V5 Master Bitmap Size 112 Blocks to Upgrade 0x00000000 Create in progress FALSE Modified cache blocks 0 Reference count 1 Wait Disk 0 Journal State DISABLED Mutex Hard Spin Count 128 Mutex Sleep Spin Count 128 Mutex Spin Sleep Time 2048 KILLs in progress 0 Replication State OFF Region Seqno 0x0000000000000001 Zqgblmod Seqno 0x0000000000000000 Zqgblmod Trans 0x0000000000000000 Endian Format LITTLE Commit Wait Spin Count 16 Database file encrypted TRUE Dualsite Resync Seqno 0x0000000000000001 DB Current Minor Version 8 Blks Last Record Backup 0x00000000 Last GT.M Minor Version 8 Blks Last Stream Backup 0x00000000 DB Creation Version V5 Blks Last Comprehensive Backup 0x00000000 DB Creation Minor Version 8 Total Global Buffers 0x00000400 Phase2 commit pid count 0x00000000 Dirty Global Buffers 0x00000000 Write cache timer count 0xFFFFFFFF Free Global Buffers 0x00000400 wcs_wtstart pid count 0x00000000 Write Cache is Blocked FALSE wcs_wtstart intent cnt 0x00000000 Actual kills in progress 0 Abandoned Kills 0 Process(es) inhibiting KILLs 0 DB Trigger cycle of ^#t 0 MM defer_time 0 Database file encryption hash 12D119C93E28BBA9389C6A7FD53C2373CFF7181DF48FEF 213523B7B38199EF18B4BADB232D30CBDA2DBFC5F85D97D7A5C4A3E3D13276DCBB63B30EBDAA6B5 DD7 Full Block Writes OFF Full Block Write Len 0 TP blkmod nomod 0 TP blkmod gvcst_srch 0 TP blkmod t_qread 0 TP blkmod tp_tend 0 TP blkmod tp_hist 0 Free blocks 992 Backup blocks 0 Reformat blocks 0 Total blocks 992 Shmpool blocked FALSE File Offset 0x0000000000000000 Shmpool crit holder 0 Backup_errno 0 Backup Process ID 0 Backup TN 0x0000000000000000 Inc Backup TN 0x0000000000000000 Process Failed 0 Allocs since check 0 Backup Image Count 0 Temp File: Database is Fully Upgraded : TRUE Database WAS ONCE Fully Upgraded from V4 : TRUE Blocks to Upgrade subzero(negative) error : 0x00000000 TN when Blocks to Upgrade last became 0 : 0x0000000000000000 TN when Desired DB Format last changed : 0x0000000000000000 TN when REORG upgrd/dwngrd changed dbfmt : 0x0000000000000000 Block Number REORG upgrd/dwngrd will restart from : 0x00000000 Upd reserved area [% global buffers] 50 Avg blks read per 100 records 200 Pre read trigger factor [% upd rsrvd] 50 Upd writer trigger [%flshTrgr] 33 Snapshot in progress FALSE Number of active snapshots 0 Snapshot cycle 0 Active snapshot PID 0 Snapshot TN 0 Total blocks 0 Free blocks 0 Process failed 0 Failure errno 0 Snapshot shared memory identifier -1 Snapshot file name DSE> exit GTM>halt $
Phil calls Helen with the hash, texts her mobile, or sends e-mail. Helen ensures that the hash of the key she generated matches the hash of the database file created by Phil, and communicates her approval to Phil. Phil can now use the database. Either Phil or Helen can provide the key to other users who are authorized to access the database and with whom they have securely exchanged keys.
helen$ $gtm_dist/plugin/gtmcrypt/gen_sym_hash.sh helen_cust_dat.txt Passphrase for keyring:gpg: encrypted with 2048-bit RSA key, ID A2E8A8E8, created 2010-05-07" Helen Keymaster <helen@gt.m>"178E55E32DAD6BFF761BF917412EF31904C... helen$
The encrypted database file cust.dat is now ready for use. That file, all journal files, backups, and binary extracts will all have the same symmetric encryption cipher and key, which means that software libraries that provide that cipher and copies of the key (encrypted with the public keys of all those who are authorized to access them) must be retained as long as there may be any need to access data in that database file, its journal files, extracts and backups.
The following command sequence diagram illustrates how Helen and Phil operate with one another.
[5] This step can be omitted if they already have GPG keyrings and public and private keys. However, see the section below on operation with Gnu Privacy Guard version 2.
[6] Generatng a public-private keypair can consume a significant amount of the entropy in a computer system. Running out of entropy can cause the operation to stall until sufficient entropy becomes available. You may need to consider external entropy sources or entropy gathering daemons for computer systems on which key generation will occur frequently. For encrypted databases on virtual machines, you may need to generate public-private keypairs on host computers and then ship the keyrings to the virtual guests.
[7] One alternative to direct sending of of public keys is to upload them to a keyserver, such as the MIT PGP Public Key Server at http://pgp.mit.edu