Using PGP Command Line with Encryption Management Server (USP)
search cancel

Using PGP Command Line with Encryption Management Server (USP)

book

Article ID: 159237

calendar_today

Updated On:

Products

Encryption Management Server Gateway Email Encryption Desktop Email Encryption Drive Encryption Endpoint Encryption File Share Encryption PGP Command Line PGP Key Management Server PGP Key Mgmt Client Access and CLI API PGP SDK

Issue/Introduction

A unique feature of PGP Command Line is that it can authenticate to the PGP Encryption Server (Symantec Encryption Management Server) using the USP (Universal Services Protocol/https). This is very similar to the way in which PGP Encryption Desktop (Symantec Encryption Desktop) users enroll to the PGP Encryption Server . In this configuration, the PGP Encryption 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 the PGP Encryption 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 the PGP Encryption 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.

 

Table of Contents

 

PGP Command Line USP options

Before accessing any of the keys on the PGP Encryption Server , the PGP Command Line user has to authenticate to the PGP Encryption 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:

  • PGP Encryption Server Server FQDN: keys.example.com
  • PGP Encryption Server Server username: user1
  • PGP Encryption Server user passphrase: mypassword
  • PGP Encryption 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: Results of example commands are italicized. 

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



 

Item 1: Authenticate to server and cache credentials

Authenticating to the PGP Encryption Server is compulsory in order to access keys from the server. It is the equivalent of enrolling from Encryption Desktop. If the PGP Encryption 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 the PGP Encryption Server policy that uses SKM (Server Key Mode) key management. This is so that the PGP Encryption 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)

IMSFR-1031/EPG-36765 - For a way to enter the password for authentication without displaying on the command line interface, reach out to Symantec Encryption Support and mention this article for further guidance.

 

Item 2: Instruct the PGP Encryption Server to create a user key

Authenticating to the PGP Encryption Server does not create a key on the PGP Encryption 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

 

Item 3: 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)

 

Item 4: 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)

 

 

Item 5: Encrypt and Sign a file using the authenticated user's key

To be able to encrypt and sign a file to a recipient's Key ID and specifying a signer using Email address, use the following command while removing the original file if it exists:

pgp -es FILENAME-HERE --overwrite remove -r 'EQ(KEY_ID,INSERT-KEYID-HERE)' --signer 'user <[email protected]>' --usp-server "Name-of-PGP Server-Here"

es = Encrypt and Sign
-r = Recipient

 

 

Item 6: 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)

 

 

Item 7: 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 the PGP Encryption 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)

 

 

Item 8: 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)

 

 

Item 9: 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 the PGP Encryption 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.

 

Item 10: List all users on the PGP server using the search-mak command

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]>

 

 

Item 11: 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)

 


Item 12: 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]>

 

 

Item 13: 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]>

 

 

Item 14: 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]>

 

 

Item 15: Find a User ID based on UUID

This is the UUID of the user as displayed in the user's record on the PGP Encryption 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]>

 


Item 16: List Key Details for a UUID via "--search-mak"

Once you know the UUID for the user, you can list the key details for that user:

Linux

pgp --usp-server keys.example.com --search-mak 'EQ(UUID,"009bcd12-8528-4289-84a6-b45f3008d39d")' --details

 

Windows
pgp --usp-server keys.example.com --search-mak "EQ(UUID, \"009bcd12-8528-4289-84a6-b45f3008d39d\")" --details
MAK Details: User1
       UUID: 009bcd12-8528-4289-84a6-b45f3008d39d
   Key mode: SKM
Key Details: User1
     Key ID: 0x052CE77A (0xB9355E820052CE77A)
       Type: RSA (v4) key pair
       Size: 2048
   Validity: Invalid
      Trust: Never (Not axiomatic)
    Created: 2020-04-09
    Expires: 2023-06-02
     Status: Active
     Cipher: AES-256
     Cipher: CAST5
     Cipher: TripleDES
     Cipher: IDEA
     Cipher: Twofish-256
       Hash: SHA-256
       Hash: SHA-384
       Hash: SHA-512
   Compress: ZLIB
   Compress: Zip
      Photo: No
  Revocable: Yes
      Token: No
  Keyserver: ldap://keys.example.com
    Default: No
    Wrapper: No
 Prop Flags: Sign user IDs
 Prop Flags: Sign messages
 Prop Flags: Private shared
 Prop Flags: PGP NetShare
 Prop Flags: PGP WDE
 Prop Flags: PGP ZIP
 Prop Flags: PGP Messaging
 Ksrv Flags: No modify
 Feat Flags: Modification detection
  Notations: 01 0x00000000 [email protected]=<binary data, length 1>
  Notations: 02 0x00000000 [email protected]=<binary data, length 1>
  Notations: 03 0x80000000 [email protected]=pgpmime
      Usage: Sign user IDs
      Usage: Sign messages

  Subkey ID: 0x08DD000F (0x1EED0F6108DD000F)
       Type: RSA (v4) subkey pair
       Size: 2048
    Created: 2020-04-09
    Expires: 2023-06-02
     Status: Active
  Revocable: Yes
      Token: No
      X.509: No
 Prop Flags: Encrypt communications
 Prop Flags: Encrypt storage
 Prop Flags: PGP NetShare
 Prop Flags: PGP WDE
 Prop Flags: PGP ZIP
 Prop Flags: PGP Messaging
  Notations: None
      Usage: Encrypt communications
      Usage: Encrypt storage
      Usage: PGP NetShare
      Usage: PGP WDE
      Usage: PGP ZIP
      Usage: PGP Messaging

        ADK: None

    Revoker: None

 

Additional Information

Attachments

PGP Command Line Commands_1603298595637.xlsx get_app
Powered by Wolken Software