Using PGP Command Line with Encryption Management Server
Article ID: 159237
Updated On:
Products
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
- Item 1: Authenticate to server and cache credentials
- Item 2: Instruct the PGP Encryption Server to create a user key
- Item 3: Clear Authentication Cache
- Item 4: Sign a file using the authenticated user's key
- Item 5: Encrypt and Sign a file using the authenticated user's key
- Item 6: Encrypt a file to the authenticated user's key and another user's key
- Item 7: Encrypt a file to the authenticated user's key and another user's key and sign
- Item 8: Decrypt a file using the authenticated user's key
- Item 9: Decrypt and verify a file using the authenticated user's key
- Item 10: List all users on the PGP server using the search-mak command
- Item 11: Find a Key ID based on email address
- Item 12: Find a User ID based on email address
- Item 13: Find a User ID based on name
- Item 14: Find a User ID based on Key ID
- Item 15: Find a User ID based on UUID
- Item 16: List Key Details for a UUID via "--search-mak"
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)
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
Feedback
