ALERT: Some images may not load properly within the Knowledge Base Article. If you see a broken image, please right-click and select 'Open image in a new tab'. We apologize for this inconvenience.

Using PGP Command Line with Encryption Management Server

book

Article ID: 159237

calendar_today

Updated On:

Products

PGP Command Line Encryption Management Server Gateway Email Encryption

Issue/Introduction

A unique feature of PGP Command Line is that it can authenticate to Encryption Management Server using the USP (Universal Services Protocol). This is very similar to the way in which Encryption Desktop users enroll to Encryption Management Server. In this configuration, Encryption Management Server is sometimes referred to as a Key Management Server (KMS).

USP runs on https port 443 and the connection is secured with a TLS certificate.

Once authenticated, the PGP Command Line user can access their private PGP key directly from Encryption Management Server; they do not need to store the key in their local keyring. This allows for more secure key management.

This article includes examples of how PGP Command Line interacts with Encryption Management Server using the Universal Services Protocol.

For more information on FAQs for PGP Command Line, see the following articles:

180234 - HOW TO: License PGP Command Line 10.x

153244 - HOW TO: Set the PGP_HOME_DIR variable for PGP Command Line

180118 - HOW TO: Use PGP Command Line to Create and Manage PGP Keys

158454 - Using PGP Command Line

 

Environment

  • PGP Command Line 10.5 and above.
  • Encryption Management Server 10.5 and above.

Resolution

See the attachment PGP_Command_Line_Commands_1603298595637.xlsx for general PGP Command Line commands that apply where local keys are being used.

PGP Command Line USP options

Before accessing any of the keys on Encryption Management Server, the PGP Command Line user has to authenticate to Encryption Management Server. The authentication credentials are cached. At no point are keys stored in the local keyring.

In the examples below, the following values are used:

  • Encryption Management Server FQDN: keys.example.com
  • Encryption Management Server username: user1
  • Encryption Management Server user passphrase: mypassword
  • Encryption Management Server managed key name: "User One <[email protected]>"
  • File to sign and/or encrypt: test.txt
  • File to verify and/or decrypt: test.txt.pgp

Note that the managed key name must match exactly how it appears in the Name column of the Keys / Managed Keys page of the Encryption Management Server administration console.


Authenticate to server and cache credentials

Authenticating to Encryption Management Server is compulsory in order to access keys from the server. It is the equivalent of enrolling from Encryption Desktop. If Encryption Management Server uses Directory Synchronization with Active Directory then the --auth-username argument is the sAMAccountName or User Principal Name (UPN) of a user in Active Directory and the --auth-passphrase argument uses the user's Active Directory password.

The user should be in an Encryption Management Server policy that uses SKM (Server Key Mode) key management. This is so that Encryption Management Server can manage the key.

Once the credentials are cached, there is no need to use the credentials for subsequent commands. The credentials will stay cached until they are explicitly cleared. This is the only time that a password needs to be entered at the command line:
pgp --auth-username user1 --auth-passphrase mypass --usp-cache-auth --usp-server keys.example.com
keys.example.com:USP cache auth (0:Authentication cached)

Instruct Encryption Management Server to create a user key

Authenticating to Encryption Management Server does not create a key on Encryption Management Server. Use this command to instruct the server to create a key for the user:

pgp --create-mak --usp-server keys.example.com --name user1

Clear Authentication Cache

Under normal circumstances there is no need to clear the cache. Doing so will require the user to authenticate again:
pgp --usp-clear-cache --usp-server keys.example.com
keys.example.com:USP clear cache (0:Authentication no longer cached)


Once the cached credentials are cleared, a command like this fails:
pgp --usp-server keys.example.com --usp-cache-auth --encrypt test.txt --recipient "User One <[email protected]>"
pgp:encrypt (3090:operation failed, no secret key found)

Sign a file using the authenticated user's key

Because the user has authenticated to the server, all that is required is for the server's FQDN to be specified. The authenticated user's sAMAccountName can be used:

pgp --usp-server keys.example.com --sign test.txt --signer user1
test.txt.pgp:sign (0:output file test.txt.pgp)

Alternatively, the authenticated user's User ID can be used (their Key ID can also be used):

pgp --usp-server keys.example.com --sign test.txt --signer "User One <[email protected]>"
test.txt.pgp:sign (0:output file test.txt.pgp)

 

Encrypt a file to the authenticated user's key and another user's key

PGP Command Line will look up the key for the additional user. The --encrypt-to-self argument encrypts the file to the authenticated user's key. Unless you encrypt to your own key then you will not be able to decrypt the file: 

pgp --usp-server keys.example.com --usp-cache-auth --encrypt test.txt --encrypt-to-self --recipient "User Two <[email protected]>"
test.txt:encrypt (0:output file test.txt.pgp)

Alternatively, the authenticated user's sAMAccountName (or User ID) can be used:

pgp --usp-server keys.example.com --usp-cache-auth --encrypt test.txt --recipient user1 --recipient "User Two <[email protected]>"
test.txt:encrypt (0:output file test.txt.pgp)

 

Encrypt a file to the authenticated user's key and another user's key and sign

Note that you must sign with the authenticated user's key. Even if the authenticated user has permission over other keys stored in Encryption Management Server, these other keys cannot be used to sign a file:

pgp --usp-server keys.example.com --usp-cache-auth --encrypt test.txt --encrypt-to-self --recipient "User Two <[email protected]>" --signer user1
test.txt:encrypt (0:output file test.txt.pgp)

 

Decrypt a file using the authenticated user's key

In this example, the file being decrypted is not signed:
pgp --decrypt test.txt.pgp --usp-server keys.example.com
test.txt.pgp:decrypt (0:output file test.txt)

 

Decrypt and verify a file using the authenticated user's key

In this example, the file being decrypted is signed. Note that unless the --verify-with argument is passed, a "cannot verify signature" warning will be displayed:
pgp --usp-server keys.example.com --decrypt test.txt.pgp --verify-with user1
test.txt.pgp:decrypt (0:output file test.txt)

 

Searching for keys on Encryption Management Server

Generally, PGP Command Line is used for batch processing and will use a relatively small number of keys to encrypt and decrypt a large number of files. The same Key IDs or User IDs will be used frequently so there will be no requirement to search for keys on the server. However, it is possible to do this.

List all users on the server

The --search-mak switch without parameters will retrieve all users. Note that the UUID is the UUID of the managed key:
pgp --usp-server keys.example.com --search-mak
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>
0136e884-aaf1-4dc7-9351-18b99d5c5f87  SKM   User Two <[email protected]>
0399183f-ec2b-4e38-9450-bc6d706caf2f  CKM   User Three <[email protected]>

 

Find a Key ID based on email address

Linux

pgp --usp-server keys.example.com --search-mak --details 'CI(EMAIL,"[email protected]")' |grep 'Key ID' 
Key ID: 0x052CE77A (0x685387E0052CE77A)

Windows

pgp --usp-server keys.example.com --search-mak --details "CI(EMAIL,\"[email protected]\")" |find "Key ID"
Key ID: 0x052CE77A (0x685387E0052CE77A)

 

Find a User ID based on email address

Linux

pgp --usp-server keys.example.com --search-mak 'CI(EMAIL,"[email protected]")' 
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

Windows

pgp --usp-server keys.example.com --search-mak "CI(EMAIL,\"[email protected]\")"
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

 

Find a User ID based on name

Linux

pgp --usp-server keys.example.com --search-mak 'CI(COMMON_NAME,"User One")' 
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

Windows

pgp --usp-server keys.example.com --search-mak "CI(COMMON_NAME, \"User One\")" 
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

 

Find a User ID based on Key ID

Note that either the short or long form of Key ID can be used.

Linux

pgp --usp-server keys.example.com --search-mak 'EQ(KEY_ID,0x052CE77A)'
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

Windows

pgp --usp-server keys.example.com --search-mak "EQ(KEY_ID,\0x052CE77A)"
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

 

Find a User ID based on UUID

This is the UUID of the user as displayed in the user's record on Encryption Management Server. This particular search is unlikely to be required very often.

Linux

pgp --usp-server keys.example.com --search-mak 'EQ(UUID,"009bcd12-8528-4289-84a6-b45f3008d39d")' 
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

Windows

pgp --usp-server keys.example.com --search-mak "EQ(UUID, \"009bcd12-8528-4289-84a6-b45f3008d39d\")"
UUID                                  Mode  Name
------------------------------------  ----  ----
009bcd12-8528-4289-84a6-b45f3008d39d  SKM   User One <[email protected]>

Additional Information

180234 - HOW TO: License PGP Command Line 10.x

153244 - HOW TO: Set the PGP_HOME_DIR variable for PGP Command Line

180118 - HOW TO: Use PGP Command Line to Create and Manage PGP Keys

158454 - Using PGP Command Line

Attachments

PGP Command Line Commands_1603298595637.xlsx get_app