Download the PHP package dbeurive/gpg without Composer

• Introduction
• License
• Installation
• Synopsis
• Signing a document (using the private key)
  • Command line
  • API
• Clear signing a document (using the private key)
  • Command line
  • API
• Creating a detached signature (using the private key)
  • Command line
  • API
• Encrypting a document (using a public key)
  • Command line
  • API
• Decrypt a encrypted file
  • Command line
  • API
• Key management
  • API
• Other methods
• Testing the package
  • Importing these keys
  • Getting IDs and fingerprints
• Creating printed backups of private keys
• Regenerate keys from their graphical representations
• Useful links

Introduction

This package implements a wrapper around the PGP command line tool.

Please note that the ambition of this wrapper is not to be "complete". This wrapper has been developed in order to automat the GPG processing of a large number of files. Therefore, only the basic GPG functionalities have been wrapped (signing, encryption, decryption and signature verification).

License

This code is published under the following license:

Creative Common Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)

See the file LICENSE.TXT

Installation

From the command line:

composer require dbeurive/gpg

Or, from within the file composer.json:

"require": {
    "dbeurive/gpg": "*"
}

Synopsis

For a detailed description of the return codes, please consult this file.

Signing a document (using the private key)

To sign a document means: encrypt the document using the private key.

Command line

Command:

gpg --armor -u 03DEC874738344206A1A7D31E07D9D14954C8DC5 --output document.pgp --sign document

# For automation inside a script:

exec 3> /tmp/status; echo 'password' | gpg --batch --yes --always-trust --status-fd 3 --passphrase-fd 0 --armor -u 03DEC874738344206A1A7D31E07D9D14954C8DC5 --output document.pgp --sign document; echo $?; exec 3>&-

Then to decrypt the document (using the public key)

gpg --output document.decrypted --decrypt document.pgp
gpg --output - --decrypt document.pgp

Please note that you can use the sub key associated to the private key instead of the private key itself.

API

Sign:

static function signFile($inAPath, $inPrivateKeyFingerPrint, $inOptPassword=null, $inOptSignaturePath=null)
static function signString($inString, $inPrivateKeyFingerPrint, $inPassword=null, $inOptSignaturePath=null)

Decrypt:

static function decryptFile($inAbsolutePath, $inOptPassword=null, $inOptOutputFile=null)
static function decryptString($inString, $inOptPassword=null, $inOptOutputFile=null)

Clear signing a document (using the private key)

To "clear sign" a document means:

• generate a hash of the document (using SHA1, for example).
• encrypt the previously generated hash with the private key.
• append the encrypted hash to the end of the document (which remains clear).

Command line

Command:

gpg --armor -u 03DEC874738344206A1A7D31E07D9D14954C8DC5 --output document.pgp --clearsign document

# For automation inside a script:

exec 3> /tmp/status; echo 'password' | gpg --batch --yes --always-trust --status-fd 3 --passphrase-fd 0 --armor -u 03DEC874738344206A1A7D31E07D9D14954C8DC5 --output document.pgp --clearsign document; echo $?; exec 3>&-

Verify the signature:

gpg --verify document.pgp

API

Sign:

static function clearSignFile($inPath, $inPrivateKeyFingerPrint, $inOptPassword=null, $inOptSignaturePath=null)
static function clearSignString($inString, $inPrivateKeyFingerPrint, $inPassword=null, $inOptSignaturePath=null)

Verify the signature:

static function verifyClearSignedFile($inFilePath, &$outWarning)
static function verifyClearSignedString($inString, &$outWarning) {

Creating a detached signature (using the private key)

Creating a "detached signature" means:

• generate a hash of the document (using SHA1, for example).
• encrypt the previously generated hash with the private key.
• write the encrypted hash in a (specified) file.

Please note that a "detached signature" and a "clear signature" are identical. The difference between a "detached signature" and a "clear signature" is that the former is put into a separate file, whereas the latter is appended to the end of the signed document.

Command line

Command:

gpg --armor -u 03DEC874738344206A1A7D31E07D9D14954C8DC5 --output document.PGP --detach-sign document

# For automation inside a script:

exec 3> /tmp/status; echo 'password' | gpg --batch --yes --always-trust --status-fd 3 --passphrase-fd 0 --armor -u 03DEC874738344206A1A7D31E07D9D14954C8DC5 --output document.pgp --detach-sign document; echo $?; exec 3>&-

Verify the signature:

gpg --verify document.pgp document

API

Sign:

static function detachSignFile($inPath, $inPrivateKeyFingerPrint, $inOptPassword=null, $inOptSignaturePath=null)
static function detachSignString($inString, $inPrivateKeyFingerPrint, $inPassword=null, $inOptSignaturePath=null)

Verify a signature:

static function verifyDetachedSignedFile($inSignatureFilePath, $inDocument, &$outWarning)
static function verifyDetachedSignedString($inSignature, $inDocument, &$outWarning)

Encrypting a document (using a public key)

Please note that in GPG lingo, encryption using a private key is called "signing" (which, technically speaking, is an encryption).

Command line

Command:

gpg --armor --output encrypted_file --encrypt --recipient 03DEC874738344206A1A7D31E07D9D14954C8DC5 document

# For automation inside a script:

exec 3> /tmp/status; gpg --batch --yes --status-fd 3 --always-trust --armor --output document.pgp --encrypt --recipient 03DEC874738344206A1A7D31E07D9D14954C8DC5 document; echo $?; exec 3>&-

Decrypt the file (using a private key):

gpg --output document --decrypt document.pgp

API

static function encryptAsymmetricFile($inInputPath, $inPublicKeyFingerPrint, $inOptOutputFile=null)
static function encryptAsymmetricString($inString, $inPublicKeyFingerPrint, $inOptOutputFile=null)

Decrypt a encrypted file

Please note that the document may have been encrypted using a public key or a secret key (that is, signed).

• If the document has been encrypted with a public key (probably yours), you will need a private key to decrypt it.
• If the document has been signed with a private key, you will need a public key to decrypt it.

Command line

Command:

gpg --output document --decrypt document.pgp

For automation inside a script:

exec 3> /tmp/status; echo 'password' | gpg --batch --yes --status-fd 3 --passphrase-fd 0 --always-trust --output document --decrypt document.pgp; echo $?; exec 3>&-

API

static function decryptFile($inAbsolutePath, $inOptPassword=null, $inOptOutputFile=null)
static function decryptString($inString, $inOptPassword=null, $inOptOutputFile=null)

Key management

Except when calling the methods that returns the fingerprints (getPublicKeyFingerPrint and getPrivateKeyFingerPrint), the keys are identified by their fingerprints This ensures maximum security against "side effects" that may occur when specifying keys' IDs.

API

static function getPublicKeyFingerPrint($inPublicKey)
static function getPrivateKeyFingerPrint($inPrivateKey)
static function isPrivateKeyPresent($inPrivateKeyFingerPrint)
static function isPublicKeyPresent($inPublicKeyFingerPrint)
static function removePrivateKey($inPrivateKeyFingerPrint)
static function removePublicKey($inPublicKeyFingerPrint)
static function importPrivateKey($inPrivateKeyPath)
static function importPublicKey($inPublicKeyPath)

Other methods

static function version()
static function checkVersion()

Testing the package

This package contains two pairs of keys:

• One pair which secret key is protected by a password.
• One pair which secret key is not protected.

These keys are located in the directory tests/data:

• open.prv / open.pub: this pair of keys is not protected.
• protected.prv / protected.pub: this pair of keys is protected.

Importing these keys

cd tests/data
gpg --import open.prv; gpg --import open.pub; gpg --import protected.prv; gpg --import protected.pub

Getting IDs and fingerprints

For public keys:

gpg --batch --list-keys --fingerprint --with-colon

For private keys:

gpg --batch --list-secret-keys --fingerprint --with-colon

See this document for a detailed description of the output of the option --with-colon.

The Perl script list-keys.pl may be used to print the list of public keys.

gpg --list-keys --with-colon --fingerprint | perl list-keys.pl
gpg --list-secret-keys --with-colon --fingerprint | perl list-keys.pl

Example:

gpg --list-secret-keys --with-colon --fingerprint | perl list-keys.pl

Outputs:

6   sec E07D9D14954C8DC5 03DEC874738344206A1A7D31E07D9D14954C8DC5 0C185D728E760EC0 open key <[email protected]>
6   sec 29A778386005B911 881C41F8B8FD138E86E7230929A778386005B911 6A492A01B27F4819 protected key <[email protected]>

Whith:

Column 1: the total number of columns for the current line.
Column 2: the type of key (pub: public, sec: secret).
Column 3: the UID of the key.
Column 4: the fingerprint of the key.
Column 5: the UID of the associated sub key.
Column 6: the ID of the key.

Please note that

• the last field of each line may have spaces (ex: PHP coder <[email protected]>).
• a key may have more than one sub key. Therefore, a line may have more than 6 columns.

Creating printed backups of private keys

You can produce graphical representations of your private keys. These representations can be printed on paper.

Please note that you should not need to produce graphical representations of your public keys. Indeed, public keys do not need to be protected. Therefore you can make copies of your public keys everywhere.

Install Data Matrix tools:

Generate a very long RSA keys:

Find the ID or the fingerprint of the generated keys:

By ID:

By fingerprint:

Then generate images that represent the private key:

The list of images that represents the private key is:

Regenerate keys from their graphical representations

Please note that you need the public key in order to regenerate the private key! The public key can be stored within the public keyring, or within a file.

Compare the restored key against the original:

If you try to import the restored private key:

Sign a document with the original private key:

Remove the original private key from its keyring:

Restore the secret key using the backup:

Then, make sure that the restored secret key works as expected:

Useful links

https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/

http://www.spywarewarrior.com/uiuc/gpg/gpg-com-4.htm