Gpg and macosx

Welcome to Simone Giustetti's wiki pages.

Languages: English - Italiano

---

GPG for MacOsX

Gnu Privacy Guard is a cryptographic software suite for personal use running on a wide variety of architectures among them the Macintosh family of operating systems. Three distinct versions of GPG can run on the Mac:

• MacGPG is a port of the 1.4 development branch of GPG. Development has come to a halt and packages are meant for old versions of OsX, providing support for legacy installations.
• GPGOsX is a port of the 2.1 stable branch of GPG. All of the new functionality of the 2.0 and recent 2.1 releases are included.
• GPGTools is an alternate port of the 2.0 stable branch of GPG. GPGTools includes many an integration to the standard software as the Apple Mail plug-in and a native GUI.

Both GPGOsX and GPGTools support recent OsX releases only. The minimum required version for both programs is 10.6 or 10.7. MacGPG is rather suitable for old architectures and as such is ideal for owners of PowerPC Macs, who will have to accustom themselves to the command line interface because no graphical one is provided.

Installing

The install procedures slightly differ for each software. You are invited to visit the home page of each one where you'll find updated information and detailed instructions. Some links to web pages detailing the GPGTools installation procedure are available below:

• Step by step instructions to install GPGTools.
• Another good tutorial rich in images and details.

Key Pair and Configuration

The above linked pages contain information about key pair creation. GPG uses a key pair to encrypt and decrypt files. The key pair is fundamental to GPG and encryption strength heavily depends on it. Please consult the program documentation for more in depth information. The basic concepts about encryption and GPG internals will be summarized below:

• GPG uses asymmetric cryptography also known as public key cryptography.
• Asymmetric cryptography requires a key pair: a public key, used to encrypt information, and a private key needed to decrypt data.
• A copy of the public key should be delivered to whoever wishes to send you encrypted e-mails or files.
• The private key is secret and should never be shared with anyone.
• Information encrypted with the public key can be decrypted with the private one only.
• The private key can be protected using a passphrase. If stolen, a protected key cannot be used by unauthorized people who do not know the passphrase.

The key pair is the building block for GPG to work and as such should be created soon after the installation to allow the program to work. Key length is a sensitive matter and frequent subject to discussion. A longer key grants a stronger security in theory, but using longer keys involves some disadvantages to be taken into account. GPG supports a maximum key length of 4096 bit, but still you are recommended to set the standard value of 2048 bit. The standard length is a good compromise between security and performances and it grants use of external devices like smart cards and such. The GPG FAQ includes a discussion of key length where advantages of using more than 2048 bits are weighed against disadvantages.

The procedure for key generation is described below. Although some versions of GPG for Mac can be administered through a GUI, I'll use the command line interface because it is the only one common to all three programs.

• Start a terminal.
• Run command gpg --gen-key providing all of the requested information as in the example below:

  hostname:~ user1$ gpg --gen-key
  gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
  This is free software: you are free to change and redistribute it.
  There is NO WARRANTY, to the extent permitted by law.
  
  Please select what kind of key you want:
     (1) DSA and Elgamal (default)
     (2) DSA (sign only)
     (5) RSA (sign only)
  Your selection? 1
  DSA keypair will have 1024 bits.
  ELG-E keys may be between 1024 and 4096 bits long.
  What keysize do you want? (2048) 
  Requested keysize is 2048 bits
  Please specify how long the key should be valid.
           0 = key does not expire
        <n>  = key expires in n days
        <n>w = key expires in n weeks
        <n>m = key expires in n months
        <n>y = key expires in n years
  Key is valid for? (0) 0
  Key does not expire at all
  Is this correct? (y/N) y
  
  You need a user ID to identify your key; the software constructs the user ID
  from the Real Name, Comment and Email Address in this form:
  "Heinrich heine (Der Dichter) <heinrichh@dusseldorf.de>"
  
  Real name: StudioSG
  Email address: studiosg@giustetti.net
  Comment: sg_test_03
  You selected this USER-ID:
     "StudioSG (sg_test_03) <studiosg@giustetti.net>"
  
  Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
  You need a Passphrase to protect your secret key.
  
  We need to generate a lot of random bytes. It is a good idea to perform
  some other action (type on the keyboard, move the mouse, utilize the
  disks) during the prime generation; this gives the random number
  generator a better chance to gain enough entropy.
  We need to generate a lot of random bytes. It is a good idea to perform
  some other action (type on the keyboard, move the mouse, utilize the
  disks) during the prime generation; this gives the random number
  generator a better chance to gain enough entropy.
  gpg: key CE95C1E9 marked as ultimately trusted
  public and secret key created and signed.
  
  gpg: checking the trustdb
  gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
  gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
  pub   1024R/CE95C1E9 2016-03-22
        Key fingerprint = 4313 91CC F222 161E 3B19  54CE AC09 5248 CE95 C1E9
  uid                  StudioSG (sg_test_03) <studiosg@giustetti.net>
  sub   2048g/1C97007E 2016-03-22

The procedure requires to provide a unique identifier and some more personal information used to distinguish keys. To get a list of saved keys use the command: gpg --list-keys:

  hostname:~ user1$ gpg --list-keys
  /home/user1/.gnupg/pubring.gpg
  -----------------------------
  pub   1024D/CE95C1E9 2016-03-22
  uid                  StudioSG (sg_test_03) <studiosg@giustetti.net>
  sub   2048g/1C97007E 2016-03-22

During key creation you can provide an optional passphrase for the private key. You are encouraged to always use a passphrase, which safeguards users in case the device where thee keys are saved is stolen. A passphrase too short or too easy cold be discovered by a brute force attack. Please use a passphrase longer than 8 characters containing letters, numbers and special characters to defend against such attacks.

GPG standard behavior can be customized setting proper values for the program options. Configuration options are saved in text files in MacOsX and can be edited recurring to any text editor. Every configured user has his or her personal copy of the configuration files, which are located in the home directory. The standard GPG configuration file for any user is /Users/<user name>/.gnupg/gpg.conf. For example, the configuration file of a hypothetical user1 user is: /Users/user1/.gnupg/gpg.conf. The dot preceding the .gnupg directory name means that the directory is a hidden one. To list a hidden directory when inspecting the content of its father one use option -a of command ls:

ls -la

To read or update your own configuration file:

/Applications/TextEdit.app/Contents/MacOS/TextEdit /Users/<user name>/.gnupg/gpg.conf

The file is fully commented, but still refer to the program manual for a description of all the options contained therein. Standard values are suitable for almost all private or professional uses. Please set different values only when you are certain of the outcome.

GPGOsX and GPGTools users should replace command gpg with gpg2 when using the command line interface instead of the graphical one.

Key Pair Back-up

The key pair is mandatory to open encrypted files: its loss could prove to be catastrophic as currently available processors are not powerful enough to decrypt files without. A whole document archive cold be lost for want of a key. It is a good idea to keep a safety copy of both keys stored in a safe place, different from the machine where they were created. All keys are stored inside directory /Users/<user name>/.gnupg in the form of binary files. A safe and easy way to generate a copy of the key pair consists of creating a password protected compressed archive of the directory:

zip -er key_backup.zip /Users/<user name>/.gnupg

The zip command will ask the user to provide a password for the archive, then to confirm the provided value by retyping it. The resulting archive, key_backup.zip, can be opened only by providing the password. The zip version shipping with OsX 10.4 or earlier releases does not support cryptography. Users should remove the -e option or the program will return error "(encryption not supported)" and fail:

zip -r key_backup.zip /Users/<nome utente>/.gnupg

How-to Encrypt and Decrypt Files

Commands to encrypt and decrypt files with GPG vary with the program installed on your Mac. Please refer to the documentation of the specific program. Below are some links to the web pages of GPGTool:

• How to encrypt and decrypt files using GPGTools].
• Some more GPGTools examples.

The command line interface is uniform for all of the three programs. You can retrieve information and some examples in the GPG documentation, where commands and related options usage is explained. The base encryption command is:

gpg --encrypt <file>

GPG will ask you to provide the unique identifier for the public key of the file recipient. The key will be used to encrypt the file as in the example below:

 hostname:~ user1$ gpg --encrypt st_test01.pdf
  You did not specify a user ID. (you may use "-r")
  
  Current recipients:
  
  Enter the user ID.  End with an empty line: StudioSG
  
  Current recipients:
  2048g/1C97007E 2016-03-22 "StudioSG (sg_test_03) <studiosg@giustetti.net>"
  
  Enter the user ID.  End with an empty line: 
  
  hostname:~ user1$

The encrypted file retains the name of the original one but a different extension: .gpg.

You can provide a list of recipients one for each line. An empty line of text marks the archive end. A list of saved keys available to encrypt files can be retrieved recurring to the --list-keys option:

  hostname:~ user1$ gpg --list-keys
  /Users/user1/.gnupg/pubring.gpg
  -----------------------------
  pub   1024D/CE95C1E9 2016-03-22
  uid                  StudioSG (sg_test_03) <studiosg@giustetti.net>
  sub   2048g/1C97007E 2016-03-22

Many files can be encrypted at once recurring to the --multi option. You'll have to provide a recipients list for each file. This could prove to be a lot of work and GPG provides option -r to simplify it. Using -r the recipient list can be added to the command line. In the example below three documents are encrypted using the key of recipient StudioSG:

  hostname:~ user1$ ls -la
  total 48
  drwx------  3 user1 user1 4096 Mar 18 18:50 .
  drwx------ 17 root  admin 4096 Mar 18 18:37 ..
  -rw-------  1 user1 user1 7737 Mar 18 18:50 st_test01.pdf
  -rw-------  1 user1 user1 7844 Mar 18 18:50 st_test02.pdf
  -rw-------  1 user1 user1 7932 Mar 18 18:50 st_test03.pdf
  hostname:~ user1$ gpg -r StudioSG --multi --encrypt st_test0*
  hostname:~ user1$ ls -la
  total 72
  drwx------  3 user1 user1 4096 Mar 18 18:50 .
  drwx------ 17 root  admin 4096 Mar 18 18:37 ..
  -rw-------  1 user1 user1 7737 Mar 18 18:50 st_test01.pdf
  -rw-------  1 user1 user1 7378 Mar 18 18:50 st_test01.pdf.gpg
  -rw-------  1 user1 user1 7844 Mar 18 18:50 st_test02.pdf
  -rw-------  1 user1 user1 7487 Mar 18 18:50 st_test02.pdf.gpg
  -rw-------  1 user1 user1 7932 Mar 18 18:50 st_test03.pdf
  -rw-------  1 user1 user1 7574 Mar 18 18:50 st_test03.pdf.gpg

A file is decrypted with the --decrypt option of the gpg command. GPG will prompt the user for a password and, once inserted, will output the "clear text" content of the encrypted file on the standard output. To save a decrypted version of the file the --output option and the name of the saved file are needed:

gpg --output <decrypted file> --decrypt <encrypted file>

  hostname:~ user1$ gpg --output st_test01.pdf --decrypt st_test01.pdf.gpg
  
  You need a passphrase to unlock the secret key for
  user: "StudioSG (sg_test_03) <studiosg@giustetti.net>"
  2048-bit ELG-E key, ID 1C97007E, created 2016-03-22 (main key ID CE95C1E9)
  
  gpg: encrypted with 2048-bit ELG-E key, ID 1C97007E, created 2016-03-22
        "StudioSG (sg_test_03) <studiosg@giustetti.net>"
  hostname:~ user1$ ls -la
  total 56
  drwx------  3 user1 user1 4096 Mar 18 18:50 .
  drwx------ 17 root  admin 4096 Mar 18 18:37 ..
  -rw-------  1 user1 user1 7737 Mar 18 18:50 st_test01.pdf
  -rw-------  1 user1 user1 7378 Mar 18 18:50 st_test01.pdf.gpg
  -rw-------  1 user1 user1 7487 Mar 18 18:50 st_test02.pdf.gpg
  -rw-------  1 user1 user1 7574 Mar 18 18:50 st_test03.pdf.gpg

GPG-AGENT

Gpg-agent is a daemon that stores in an internal cache all of the user provided passphrases then forwards them to all programs asking for one later. You basically have to insert any password only once and not each time a document is opened. The time saving is considerable for the staff of an office that needs to read and handle large amounts of documents every day.

The daemon must be up and running to store passwords and the environment must be properly configured in order for programs to know of the daemon existence and to query it when needed. To start gpg-agent automatically in MacOsX you have to configure a launch agent:

• Open the terminal window.
• Move to the launch agent root directory:

cd ~/Library/LaunchAgents

• Create a file containing the gpg-agent configuration:

/Applications/TextEdit.app/Contents/MacOS/TextEdit org.gnupg.gpg-agent.plist

• Populate the file with the XML formatted gpg-agent configuration:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
      <key>Label</key>
      <string>org.gnupg.gpg-agent</string>
      <key>ProgramArguments</key>
      <array>
         <string>/Users/<user name>/bin/gpg_agent_start.sh</string>
      </array>
      <key>RunAtLoad</key>
      <true/>
   </dict>
   </plist>

• Move back to your home directory and create a sub directory named bin where to save the start script for GPG:

mkdir /Users/<user name>/bin

• Create the start script:

/Applications/TextEdit.app/Contents/MacOS/TextEdit gpg_agent_start.sh

   if test -f $HOME/.gpg-agent-info && \
      kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then
      GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info`
      export GPG_AGENT_INFO
   else
      eval `/usr/local/bin/gpg-agent --daemon --write-env-file $HOME/.gpg-agent-info`
   fi
   export GPG_TTY=`tty`

• Make the file executable:

chmod 700 gpg_agent_start.sh

• Update the terminal configuration in order for all commands to know about the agent. The standard terminal uses a bash shell then the file to update is the bash configuration file:

cd

/Applications/TextEdit.app/Contents/MacOS/TextEdit .bash_profile

   export GPG_TTY=$(tty)
   if [[ -f "${HOME}/.gpg-agent-info" ]]; then
      . "${HOME}/.gpg-agent-info"
      export GPG_AGENT_INFO
   fi

The configuration parameters for gpg-agent reside in the /Users/<user name>/.gnupg/gpg-agent.conf file. Some are worth mentioning. Among them is default-cache-ttl responsible for the amount of time a password is kept in the cache. When the period expires the password entry is removed and asked for again to the user when needed. The standard lifetime of a password is 600 seconds or 10 minutes. To increase the period to 1 hour update line:

  default-cache-ttl 600

in

  default-cache-ttl 3600

then restart the gpg-agent daemon.

Users of the OsX 10.4 release or earlier cannot use the gpg-agent service as it was introduced in release 2.0 of GPG.

Conclusions

This paper provides a brief description of the MacosX optimized versions of GNU Privacy Guard. The installation and the basic operation of the program were described. For more information you are encouraged to read the manual and the many articles available on the net and in this very same website. Were You interested in our offerings or simply looking for more information, please refer to our contacts page. Thank You.

To contact me or leave me your feedback, Please e-mail at studiosg [at] giustetti [dot] net.

External links

---

• GNU Privacy Guard home page
• GPG 1.4 for MacOsX
• GPG versione 2.0 for MacOsX
• Another version of GPG 2.0 for MacOsX

---

---

Languages: English - Italiano