Users Guide 2.x - Verification, Configuration and Other Tasks
Installation and Initialization
Creating, Viewing and Editing Notes
Encrypting and Decrypting Files and Directories
Customizing the PDS Application
Verification, Configuration and Other Tasks
Verifying the PDS Application
It is strongly advised that you verify your copy of the PDS application before use.
PDS will zero (overwrite with 0's) both the KeyStore and Key passphrases as soon as they are no longer needed. In most cases, this is immediately after use. The two cases where this is not true is when creating or editing Notes; in both cases, the Note is open for edit and is expected to be saved soon. Whenever a Note is open for editing, the Keys passphrase is kept in memory in a byte array. Then, when a Note needs to be saved, the passphrase is accessed to obtain the Key, the Note is encrypted, and the reference to the Key is deleted. Once the Note is closed there is no further need to obtain the Key, so the associated passphrase is zero'd as well.
To observe the aforementioned zeroing of passphrases, set the "showpassclear" argument in PDS to "true". This will print what passphrases are being zero'd to STDOUT, in real time.
$ java -Dshowpassclear=true -jar /path/to/pds.jar
The trickier part, however, which is zeroing the actual Key material, cannot be not addressed well by PDS. Using Java for this application provides many advantages, but it also has one or two pitfalls; one of those being how to clear the Key material from memory, as well as any copies of that Key material that are used to create another type of object (the Secret Key Specification) that is used to generate the Cipher. Certainly the references to the objects are deleted, but the content of those Objects remains, waiting for Java's garbage collector to reclaim that memory. There's no known way to zero out a Key object, though Java 8 does add a Destroyable interface to the SecretKey class. But, even if that Destroyable addition actually zero'd out the Key material, which it does not seem to guarantee, the garbage collector may do things with objects, referenced or not, that make it impossible to guarantee that a unreferenced copy of the Key material does not reside in RAM somewhere, or worse, has been paged out to a more persistent form of storage.
In short, if you are concerned that that someone might dump the memory on your system and take it off to supercomputer for recovery of your Key material, then PDS is probably not for you. But, if you really needed that level of data security, you probably knew that already... :)
Similar to the aforementioned verifying security section, another argument that can be enabled provides some basic cryptography information. This can be used to verify the algorithm, etc.
To observe the cryptography output, set the "showcrypto" argument in PDS to true. This will print the information to STDOUT, in real time.
Combined with the previous, we have:
$ java -Dshowpassclear=true -Dshowcrypto=true -jar /path/to/pds.jar
As mentioned in the Troubleshooting chapter, newer versions of Mac will need to run PDS from the Command Line Interface as well to observe these messages. In this mode, the Mac look and feel will not be present. However, if on 10.7 or earlier, you should be able to add the following code to the Info.plist for PDS and see the output on the console while also using the Mac look and feel:
<key>Arguments</key> <array> <string>-Dshowcrypto=true</string> <string>-Dshowpassclear=true</string> </array>
Verifying a KeyStore
PDS provides a Gui interface to the KeyStore. In it, you can verify:
1. The number of Keys in the KeyStore.
2. The Creation Date of each Key.
3. The Alias of each Key.
4. That the KeyStore is not corrupted.
To view this information, select "KeyStore -> View" from the main Gui. You will be presented with a file chooser to select the KeyStore, and once selected, the aforementioned information will be displayed (Figure 1).
Verifying a Key
PDS provides two Gui interfaces to the Keys. One interface is for non-modifying actions and the other interface is for modifying actions. Looking at the non-modifying, or "view" actions, you may verify:
1. The number of Keys in the KeyStore.
2. The Creation Date of each Key.
3. The Alias of each Key.
4. That the KeyStore is not corrupted.
5. The current Default Key.
6. The passphrase associated with any Key.
7. The Algorithm (AES, DES) of any Key.
8. The size of any Key, in bits.
9. The actual bits of any Key.
To view this information, select "Key -> View" from the main Gui. You will be presented with a file chooser to select the KeyStore, and once selected, an interface (Figure 2) similar to Figure 1 will be displayed.
Selecting the Show Default Key button will bring up the dialog shown in Figure 3, indicating the Alias of your Default Key, as well as the fully qualified path to the KeyStore containing that Key. Should you wish to change the Default Key, please see the section of the manual on Customizing PDS. Don't worry that your path to the Default Key contains Operating System (OS) specific information, as PDS will find your Keys using your custom, OS-specific KeyStore Search Path.
Moving from left to right, the second button is Key Info, and selecting it provides basic information about the currently selected Key. This information is shown in Figure 4.
Moving to the 3rd button, Key Details, this brings up a dialog showing a superset of the Key Info button. After successfully authenticating your credentials, a dialog containing the details of the Key will be displayed (Figure 5).
Modifying a Key
Similar to the options to Verify a Key, PDS also provides an interface that provides modifying operations related to encryption keys. Looking at the modifying, or "edit" actions, you may:
1. Change the Default Key for encryption operations.
2. Modify the credentials (passphrase) for a Key.
3. Delete a Key.
This dialog can be reached by selecting "Key -> Edit" from the main Gui, or by selecting the KeyEdit icon on the ToolBar. As with other dialogs, you will be presented with a file chooser to select the KeyStore, and once selected, a familiar interface will be presented (Figure 6). As with the View Keys dialog, you will again need to select one of the Keys to enable all the options.
The final dialog in this set is that seen when setting a new default Key (Figure 7).
Modifying a Key's Alias
An Alias is a reference to an Encryption Key. When a Key is created, an Alias must be provided. PDS uses the Alias as a reference to obtain the Key. Within a KeyStore, Keys may not have the same Alias. Aliases are not case sensitive.
The Java KeyStore API does not provide a programmatic way to change the Alias of a Key, so PDS does not provide this ability via the GUI. However, should you need to change the Alias of a Key, the "keytool" command line executable may be used.
Should you change the Alias of a Key that is encrypting PDS Notes or Files, those Notes and Files will no longer be able to be used by PDS in their current state.
In the case of PDS Notes, there is a "simple" modification to support the changing of Key Aliases; for PDS Files there is not. The reason for the difference between the two has to do with the difference in their file headers. Notes are meant to be smaller, more flexible files; thus they have a text header with Base64 encoded encrypted data. PDS Files, on the other hand, are meant to be larger, less flexible files; thus both the header and data are binary.
For PDS Notes, a simple text editor could be used change the Alias of the Key in a PDS Note, but modifying a PDS File is another matter.
In summary, PDS supports the renaming of a Key Alias, but only for PDS Notes.
The procedure to change the Alias for a Key that is only used for PDS Notes is as follows:
1. Make a backup of both the Note and the KeyStore. Archive those files somewhere away from your work space.
2. Use the "keytool" utility to verify the Alias in the KeyStore.
$ keytool -list -v -storetype jceks -keystore MyKeyStore.JCEKS
3. Use the "keytool" utility to change the Alias of the Key.
$ keytool -changealias -alias myoldalias -storetype jceks -keystore MyKeyStore.JCEKS Enter destination alias name: mynewalias Enter keystore password: ****************
4. Once complete, use your favorite text editor (vim, sed, etc.) to change the name of the Alias in the PDS Notes protected by the Key referred to by that Alias.
5. Verify that you can view the PDS Note using the modified versions of the Note and KeyStore.
Working with larger Notes
As mentioned in the Notes section of this Users Guide, the size of the Notes is limited by the amount of memory available to the JVM. Some JVM settings that can be used to enable larger Notes are:
-Xmn16m (set the initial heap size to 16 MB)
-Xmx256m (set the maximum heap size to 256 MB)
And used like:
$ java -Xmn16m -Xmx256m -jar /path/to/pds.jar
Mac users should be able to modify the Info.plist configuration file using the following syntax:
<key>VMOptions</key> <array> <string>-Xmn16m</string> <string>-Xmx256m</string> </array>
Adding a USB Drive instance of PDS *after* configuring a Desktop instance
At start up, PDS searches a series of locations for its configuration file. The first configuration file it locates is used. If you have previously configured a Desktop instance, then PDS will locate that configuration file. This will prevent configuration of a USB instance.
As you may have guessed, to configure a USB instance after a Desktop instance has been configured, move or rename the existing configuration file. Once that is done, start your USB instance and perform a configuration that will support your USB flash drive. Once complete, put the Desktop configuration file back into place. The PDS configuration file for a Desktop installation is $HOME/.pdsState.
Starting a Mac USB instance of PDS when running on Linux or Windows
In order to provide Mac users the Look and Feel they are familiar with, the packaging of the Mac release of PDS differs from the Linux and Windows release. For on thing, when using the Mac PDS release on Linux and Windows, you would need to navigate through the Mac packaging looking for the PDS executable to start. To avoid that, scripts for both Linux and Windows are provided within the Mac release. Those scripts can be found in PDS.app/Contents/Resources/PDS/. Depending upon where you will be running the Mac release, one or both scripts should be copied to the parent directory of the PDS.app directory and used to start PDS when not on Mac.
The Mac release is the only release that will provide Linux, Mac and Windows look and feel when running PDS from a USB drive. If you expect to run PDS from a USB drive on only Linux and/or Windows, then either the Linux or Windows releases will better suit your needs.
Import a plain text file into a PDS Note
A plain text file may be imported into a PDS Note by encrypting the text file and using Base64 encoding. PDS Notes are written Base64, and PDS files are written (by default) as binary files. So, by choosing to create a PDS File, and selecting the option to write the file out as Base64, you will create a PDS Note from a plain text file.
Press enter in the last field to submit
To improve the GUI interface, pressing the ENTER key in the final "text field" will submit the information, thus avoiding having to "click" the \"OK\" button. In selected dialogs, this functionality is also enabled in earlier text fields.
Double click enabled to select
In hopefully helpful places, a shortcut to selecting an option and then selecting the "OK" button is accomplished by double clicking the option. Once such instance when opening a Note or File and a KeyStore is found, but not in the expected path. In this case, double click the new KeyStore location an the Authentication dialog will appear.
File Dialog sizing on Mac
On Mac, PDS uses Java's JFileDialog class instead of the JFileChooser class to display a file selector dialog. The JFileDialog is recommended by Apple as it provides more of a native feel for Mac users. Noted in the PDS release notes (JDK-8074185) is that the JFileDialog is "sticky" between invocations. This suggests that you should be able to resize the JFileDialog to the desired size for your display, and subsequent calls from PDS to the JFileDialog will show the file dialog at the desired size.
Resetting PDS to its default settings
This is really easy. All you need to do is delete the ".pdsState" file and restart PDS. Where is the .pdsState file? If you are running PDS using a Desktop installation, the file will be in the root of your home directory. If you are running PDS from a USB drive, the file will be kept inside the PDS directory on your USB drive. If you use PDS in both the Desktop and USB modes, then there will be a .pdsState file in both locations; one for running in USB mode and the other for running in Desktop mode.
Using PDS with tape drives
This section provides a little bit of information about using a Linux instance of PDS 2 with a tape drive. First, here are some suggestions regarding setting up the environment.
1. Create a "tape" group. 2. Set the tape device(s) to be group "tape". 3. Set the tape device(s) to be readable and writeable by users in the "tape" group. 4. Add your non-root account to the the "tape" group.
Next, you should tell PDS the path to your primary tape device:
1. Select Options -> Locations, then select the Default Raw Device tab. 2. Change the default raw device from "/dev/null" to the non-rewinding device (e.g. /dev/nst0).
Load a new tape, and you are ready to encrypt a file or directory to tape using PDS.
As PDS does not move the tape (except when reading or writing), positioning the tape to the desired tape mark will need to be done outside of PDS. To position the tape via the command line, the "mt" command may be used. To avoid having to provide "mt" with the device path each time it is run, you may set the default tape device to the variable "TAPE", such as:
With the default tape device set to TAPE, the following scenario shows how to position a tape for PDS to write a second entry:
$ mt rewind $ mt fsf 1 $ mt status
At this point you will be ready to append a second entry to tape.
Using Java with Mac
Does managing Java on Mac seem challenging? Maybe even frustrating? If so, this should help.
Apple used to love Java, and for a while provided their own JDK. That ended with Java 6, and now Oracle is the provider of Java for Mac.
Oracle provides both a JDK and a JRE for Apple in package format. Oracle also provides a JRE in tar.gz format. We recommend only using the JRE in package format.
Generally speaking, you can only have one JRE installed, but you can have many JDKs installed. This is because installing a second JRE overwrites the existing JRE.
JDKs and JREs may seem to be installed in odd places.
To clarify, appending this to your startup script (.bash_profile) may help:
## Java on Mac
## JRE HOME
export JAVA_HOME="/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home"
## JDK HOME
## Show installed JRE/JDKs:
alias lsjre='echo $JAVA_HOME;"$JAVA_HOME"/bin/java -version'
alias lsjdk="echo $JDK_HOME;ls -l $JDK_HOME 2>/dev/null|grep -v total"
## System Java
## CLI Java
java version "1.8.0_161"
Java(TM) SE Runtime Environment (build 1.8.0_161-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.161-b12, mixed mode)
drwxr-xr-x 3 root wheel 96 Dec 26 16:12 jdk-9.0.1.jdk
To install a second JDK, simply download the package and install it. But since the JRE does not have the version information, installing JRE 9 will overwrite the existing JRE 8. One easy way around this is solved by the command line, using these commands:
$ sudo mv JavaAppletPlugin.plugin JavaAppletPlugin.plugin-8