Documentation

IMP_Pgp
in package

Contains code related to handling PGP data within IMP.

Tags
author

Michael Slusarz slusarz@horde.org

category

Horde

copyright

2002-2017 Horde LLC

license

http://www.horde.org/licenses/gpl GPL

Table of Contents

Constants

ENCRYPT  = 'pgp_encrypt'
PUBKEY_FIELD  = 'pgpPublicKey'
SIGN  = 'pgp_sign'
SIGNENC  = 'pgp_signenc'
SYM_ENCRYPT  = 'pgp_sym_enc'
SYM_SIGNENC  = 'pgp_syn_sign'

Properties

$_pgp  : Horde_Crypt_Pgp
Pgp object.

Methods

__construct()  : mixed
Constructor.
addPersonalPrivateKey()  : mixed
Add the personal private key to the prefs.
addPersonalPublicKey()  : mixed
Add the personal public key to the prefs.
addPublicKey()  : array<string|int, mixed>
Add a public key to an address book.
decryptMessage()  : stdClass
Decrypt a message with user's public/private keypair or a passphrase.
deletePersonalKeys()  : mixed
Deletes the specified personal keys from the prefs.
deletePublicKey()  : mixed
Deletes a public key from a user's address book(s) by e-mail.
enabled()  : bool
Return whether PGP support is current enabled in IMP.
encryptedSymmetrically()  : bool
Returns whether a text has been encrypted symmetrically.
encryptList()  : array<string|int, mixed>
Return the list of available encryption options for composing.
encryptMimePart()  : Horde_Mime_Part
Encrypt a Horde_Mime_Part using PGP using IMP default parameters.
generatePersonalKeys()  : mixed
Generate the personal Public/Private keypair and store in prefs.
getKeyIdString()  : mixed
getKeys()  : array<string|int, mixed>
Extracts public/private keys from armor data.
getPassphrase()  : mixed
Gets a passphrase from the session cache.
getPersonalPrivateKey()  : string
Get the personal private key from the prefs.
getPersonalPublicKey()  : string
Get the personal public key from the prefs.
getPublicKey()  : string
Retrieves a public key by e-mail.
getSymmetricId()  : string
Generates a cache ID for symmetric message data.
listPublicKeys()  : array<string|int, mixed>
Retrieves all public keys from a user's address book(s).
pgpPacketInformation()  : array<string|int, mixed>
Returns information on a PGP data block.
pgpPacketSignature()  : array<string|int, mixed>
Returns only information on the first ID that matches the email address input.
prettyKey()  : string
Returns human readable information on a PGP key.
publicKeyMimePart()  : Horde_Mime_Part
Generate a Horde_Mime_Part object, in accordance with RFC 2015/3156, that contains the user's public key.
sendToPublicKeyserver()  : mixed
Send a public key to a public PGP keyserver.
signAndEncryptMimePart()  : Horde_Mime_Part
Sign and Encrypt a Horde_Mime_Part using PGP using IMP default parameters.
signMimePart()  : Horde_Mime_Part
Sign a Horde_Mime_Part using PGP using IMP default parameters.
storePassphrase()  : bool
Store's the user's passphrase in the session cache.
unsetPassphrase()  : mixed
Clear the passphrase from the session cache.
verifySignature()  : stdClass
Verifies a signed message with a given public key.
_encryptParameters()  : array<string|int, mixed>
Provide the list of parameters needed for encrypting a message.
_keyserverList()  : array<string|int, mixed>
Return list of keyserver objects.
_signParameters()  : array<string|int, mixed>
Provide the list of parameters needed for signing a message.

Constants

ENCRYPT

public mixed ENCRYPT = 'pgp_encrypt'

PUBKEY_FIELD

public mixed PUBKEY_FIELD = 'pgpPublicKey'

SIGN

public mixed SIGN = 'pgp_sign'

SIGNENC

public mixed SIGNENC = 'pgp_signenc'

SYM_ENCRYPT

public mixed SYM_ENCRYPT = 'pgp_sym_enc'

SYM_SIGNENC

public mixed SYM_SIGNENC = 'pgp_syn_sign'

Properties

$_pgp

Pgp object.

protected Horde_Crypt_Pgp $_pgp

Methods

__construct()

Constructor.

public __construct(Horde_Crypt_Pgp $pgp) : mixed
Parameters
$pgp : Horde_Crypt_Pgp

PGP object.

addPersonalPrivateKey()

Add the personal private key to the prefs.

public addPersonalPrivateKey(mixed $private_key) : mixed
Parameters
$private_key : mixed

The private key to add (either string or array).

addPersonalPublicKey()

Add the personal public key to the prefs.

public addPersonalPublicKey(mixed $public_key) : mixed
Parameters
$public_key : mixed

The public key to add (either string or array).

addPublicKey()

Add a public key to an address book.

public addPublicKey(string $public_key) : array<string|int, mixed>
Parameters
$public_key : string

An PGP public key.

Tags
throws
Horde_Crypt_Exception
throws
Horde_Exception
Return values
array<string|int, mixed> —

See Horde_Crypt_Pgp::pgpPacketInformationMultiple()

decryptMessage()

Decrypt a message with user's public/private keypair or a passphrase.

public decryptMessage(string $text, string $type[, array<string|int, mixed> $opts = array() ]) : stdClass
Parameters
$text : string

The text to decrypt.

$type : string

Either 'literal', 'personal', or 'symmetric'.

$opts : array<string|int, mixed> = array()

Additional options:

  • passphrase: (boolean) If $type is 'personal' or 'symmetrical', the passphrase to use.
  • sender: (string) The sender of the message (used to check signature if message is both encrypted & signed).
Tags
throws
Horde_Crypt_Exception
Return values
stdClass —

See Horde_Crypt_Pgp::decrypt().

deletePersonalKeys()

Deletes the specified personal keys from the prefs.

public deletePersonalKeys() : mixed

deletePublicKey()

Deletes a public key from a user's address book(s) by e-mail.

public deletePublicKey(string $email) : mixed
Parameters
$email : string

The e-mail address to delete.

Tags
throws
Horde_Crypt_Exception

enabled()

Return whether PGP support is current enabled in IMP.

public static enabled() : bool
Return values
bool —

True if PGP support is enabled.

encryptedSymmetrically()

Returns whether a text has been encrypted symmetrically.

public encryptedSymmetrically(string $text) : bool
Parameters
$text : string

The PGP encrypted text.

Tags
todo

Return null, instead of exception, if tools are not available to determine whether data was encrypted symmetrically.

throws
Horde_Crypt_Exception
Return values
bool —

True if the text is symmetrically encrypted.

encryptList()

Return the list of available encryption options for composing.

public encryptList() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Keys are encryption type constants, values are gettext strings describing the encryption type.

encryptMimePart()

Encrypt a Horde_Mime_Part using PGP using IMP default parameters.

public encryptMimePart(Horde_Mime_Part $mime_part, Horde_Mail_Rfc822_List $addresses[, string $symmetric = null ]) : Horde_Mime_Part
Parameters
$mime_part : Horde_Mime_Part

The object to encrypt.

$addresses : Horde_Mail_Rfc822_List

The e-mail address of the keys to use for encryption.

$symmetric : string = null

If true, the symmetric password to use for encrypting. If null, uses the personal key.

Tags
throws
Horde_Crypt_Exception
Return values
Horde_Mime_Part —

See Horde_Crypt_Pgp::encryptMimePart().

generatePersonalKeys()

Generate the personal Public/Private keypair and store in prefs.

public generatePersonalKeys(string $name, string $email, string $passphrase[, string $comment = '' ][, string $keylength = 1024 ][, int $expire = null ]) : mixed
Parameters
$name : string

See Horde_Crypt_Pgp::.

$email : string

See Horde_Crypt_Pgp::.

$passphrase : string

See Horde_Crypt_Pgp::.

$comment : string = ''

See Horde_Crypt_Pgp::.

$keylength : string = 1024

See Horde_Crypt_Pgp::.

$expire : int = null

See Horde_Crypt_Pgp::.

Tags
throws
Horde_Crypt_Exception

getKeyIdString()

public getKeyIdString(mixed $keyid) : mixed
Parameters
$keyid : mixed

getKeys()

Extracts public/private keys from armor data.

public getKeys(string $data) : array<string|int, mixed>
Parameters
$data : string

Armor text.

Return values
array<string|int, mixed> —

Array with these keys:

  • public: (array) Array of public keys.
  • private: (array) Array of private keys.

getPassphrase()

Gets a passphrase from the session cache.

public getPassphrase(int $type[, string $id = null ]) : mixed
Parameters
$type : int

The type of passphrase. Either 'personal' or 'symmetric'.

$id : string = null

If $type is 'symmetric', the ID of the stored passphrase.

Return values
mixed —

The passphrase, if set, or null.

getPersonalPrivateKey()

Get the personal private key from the prefs.

public getPersonalPrivateKey() : string
Return values
string —

The personal PGP private key.

getPersonalPublicKey()

Get the personal public key from the prefs.

public getPersonalPublicKey() : string
Return values
string —

The personal PGP public key.

getPublicKey()

Retrieves a public key by e-mail.

public getPublicKey(string $address[, array<string|int, mixed> $options = array() ]) : string

First, the key will be attempted to be retrieved from a user's address book(s). Second, if unsuccessful, the key is attempted to be retrieved via a public PGP keyserver.

Parameters
$address : string

The e-mail address to search by.

$options : array<string|int, mixed> = array()

Additional options:

  • keyid: (string) The key ID of the user's key. DEFAULT: key ID not used
  • nocache: (boolean) Don't retrieve from cache? DEFAULT: false
  • nohooks: (boolean) Don't trigger hook when retrieving public key? DEFAULT: false
  • noserver: (boolean) Whether to check the public key servers for the key. DEFAULT: false
Tags
throws
Horde_Crypt_Exception
Return values
string —

The PGP public key requested.

getSymmetricId()

Generates a cache ID for symmetric message data.

public getSymmetricId(string $mailbox, int $uid, string $id) : string
Parameters
$mailbox : string

The mailbox of the message.

$uid : int

The UID of the message.

$id : string

The MIME ID of the message.

Return values
string —

A unique symmetric cache ID.

listPublicKeys()

Retrieves all public keys from a user's address book(s).

public listPublicKeys() : array<string|int, mixed>
Tags
throws
Horde_Crypt_Exception
Return values
array<string|int, mixed> —

All PGP public keys available.

pgpPacketInformation()

Returns information on a PGP data block.

public pgpPacketInformation(string $pgpdata) : array<string|int, mixed>
Parameters
$pgpdata : string

The PGP data block.

Return values
array<string|int, mixed> —

An array with information on the PGP data block. If an element is not present in the data block, it will likewise not be set in the array.

Array Format:
-------------
[public_key]/[secret_key] => Array
  (
    [created] => Key creation - UNIX timestamp
    [expires] => Key expiration - UNIX timestamp (0 = never expires)
    [size]    => Size of the key in bits
  )

[keyid] => Key ID of the PGP data (if available)
           16-bit hex value

[signature] => Array (
    [id{n}/'_SIGNATURE'] => Array (
        [name]        => Full Name
        [comment]     => Comment
        [email]       => E-mail Address
        [keyid]       => 16-bit hex value
        [created]     => Signature creation - UNIX timestamp
        [expires]     => Signature expiration - UNIX timestamp
        [micalg]      => The hash used to create the signature
        [sig_{hex}]   => Array [details of a sig verifying the ID] (
            [created]     => Signature creation - UNIX timestamp
            [expires]     => Signature expiration - UNIX timestamp
            [keyid]       => 16-bit hex value
            [micalg]      => The hash used to create the signature
        )
    )
)

Each user ID will be stored in the array 'signature' and have data associated with it, including an array for information on each signature that has signed that UID. Signatures not associated with a UID (e.g. revocation signatures and sub keys) will be stored under the special keyword '_SIGNATURE'.

pgpPacketSignature()

Returns only information on the first ID that matches the email address input.

public pgpPacketSignature(string $pgpdata, string $email) : array<string|int, mixed>
Parameters
$pgpdata : string

The PGP data block.

$email : string

An e-mail address.

Return values
array<string|int, mixed> —

An array with information on the PGP data block. If an element is not present in the data block, it will likewise not be set in the array. Array elements:

  • comment: Comment
  • created: Signature creation (UNIX timestamp)
  • email: E-mail Address
  • key_created: Key creation (UNIX timestamp)
  • key_expires: Key expiration (UNIX timestamp; 0 = never expires)
  • key_size: Size of the key in bits
  • key_type: The key type (public_key or secret_key)
  • keyid: 16-bit hex value
  • micalg: The hash used to create the signature
  • name: Full Name

prettyKey()

Returns human readable information on a PGP key.

public prettyKey(string $pgpdata) : string
Parameters
$pgpdata : string

The PGP data block.

Tags
throws
Horde_Pgp_Exception
Return values
string —

Tabular information on the PGP key.

publicKeyMimePart()

Generate a Horde_Mime_Part object, in accordance with RFC 2015/3156, that contains the user's public key.

public publicKeyMimePart() : Horde_Mime_Part
Return values
Horde_Mime_Part —

See Horde_Crypt_Pgp::publicKeyMimePart().

sendToPublicKeyserver()

Send a public key to a public PGP keyserver.

public sendToPublicKeyserver(string $pubkey) : mixed
Parameters
$pubkey : string

The PGP public key.

Tags
throws
Horde_Crypt_Exception

signAndEncryptMimePart()

Sign and Encrypt a Horde_Mime_Part using PGP using IMP default parameters.

public signAndEncryptMimePart(Horde_Mime_Part $mime_part, Horde_Mail_Rfc822_List $addresses[, string $symmetric = null ]) : Horde_Mime_Part
Parameters
$mime_part : Horde_Mime_Part

The object to sign and encrypt.

$addresses : Horde_Mail_Rfc822_List

The e-mail address of the keys to use for encryption.

$symmetric : string = null

If true, the symmetric password to use for encrypting. If null, uses the personal key.

Tags
throws
Horde_Crypt_Exception
Return values
Horde_Mime_Part —

See Horde_Crypt_Pgp::signAndencryptMimePart().

signMimePart()

Sign a Horde_Mime_Part using PGP using IMP default parameters.

public signMimePart(Horde_Mime_Part $mime_part) : Horde_Mime_Part
Parameters
$mime_part : Horde_Mime_Part

The object to sign.

Tags
throws
Horde_Crypt_Exception
Return values
Horde_Mime_Part —

See Horde_Crypt_Pgp::signMIMEPart().

storePassphrase()

Store's the user's passphrase in the session cache.

public storePassphrase(int $type, string $passphrase[, string $id = null ]) : bool
Parameters
$type : int

The type of passphrase. Either 'personal' or 'symmetric'.

$passphrase : string

The user's passphrase.

$id : string = null

If $type is 'symmetric', the ID of the stored passphrase.

Return values
bool —

Returns true if correct passphrase, false if incorrect.

unsetPassphrase()

Clear the passphrase from the session cache.

public unsetPassphrase(int $type[, string $id = null ]) : mixed
Parameters
$type : int

The type of passphrase. Either 'personal' or 'symmetric'.

$id : string = null

If $type is 'symmetric', the ID of the stored passphrase. Else, all passphrases are deleted.

verifySignature()

Verifies a signed message with a given public key.

public verifySignature(string $text, string $address[, string $signature = '' ][, string $charset = null ]) : stdClass
Parameters
$text : string

The text to verify.

$address : string

E-mail address of public key.

$signature : string = ''

A PGP signature block.

$charset : string = null

Charset to use.

Tags
throws
Horde_Crypt_Exception
Return values
stdClass —

See Horde_Crypt_Pgp::decrypt().

_encryptParameters()

Provide the list of parameters needed for encrypting a message.

protected _encryptParameters(Horde_Mail_Rfc822_List $addresses, string $symmetric) : array<string|int, mixed>
Parameters
$addresses : Horde_Mail_Rfc822_List

The e-mail address of the keys to use for encryption.

$symmetric : string

If true, the symmetric password to use for encrypting. If null, uses the personal key.

Tags
throws
Horde_Crypt_Exception
Return values
array<string|int, mixed> —

The list of parameters needed by encrypt().

_keyserverList()

Return list of keyserver objects.

protected _keyserverList() : array<string|int, mixed>
Tags
throws
Horde_Crypt_Exception
Return values
array<string|int, mixed> —

List of Horde_Crypt_Pgp_Keyserver objects.

_signParameters()

Provide the list of parameters needed for signing a message.

protected _signParameters() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The list of parameters needed by encrypt().


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results