###
PGP
###


****
NAME
****


Kernel::System::Crypt::PGP - pgp crypt backend lib


***********
DESCRIPTION
***********


This is a sub module of Kernel::System::Crypt and contains all pgp functions.


****************
PUBLIC INTERFACE
****************


Check()
=======


check if environment is working


.. code-block:: perl

     my $Message = $CryptObject->Check();



Crypt()
=======


crypt a message


.. code-block:: perl

     my $Message = $CryptObject->Crypt(
         Message => $Message,
         Key     => [
             $PGPPublicKeyID,
             $PGPPublicKeyID2,
             # ...
         ],
     );
 
     my $Message = $CryptObject->Crypt(
         Message => $Message,
         Key     => $PGPPublicKeyID,
     );



Decrypt()
=========


Decrypt a message and returns a hash (Successful, Message, Data)


.. code-block:: perl

     my %Result = $CryptObject->Decrypt(
         Message => $CryptedMessage,
     );


The returned hash %Result has the following keys:


.. code-block:: perl

     Successful => '1',        # could the given data be decrypted at all (0 or 1)
     Data       => '...',      # the decrypted data
     KeyID      => 'FA23FB24', # hex ID of PGP-(secret-)key that was used for decryption
     Message    => '...'       # descriptive text containing the result status



Sign()
======


sign a message


.. code-block:: perl

     my $Sign = $CryptObject->Sign(
         Message => $Message,
         Key     => $PGPPrivateKeyID,
         Type    => 'Detached'  # Detached|Inline
     );



Verify()
========


verify a message signature and returns a hash (Successful, Message, Data)

Inline sign:


.. code-block:: perl

     my %Result = $CryptObject->Verify(
         Message => $Message,
         Charset => 'utf-8',             # optional, 'ISO-8859-1', 'UTF-8', etc.
     );


Attached sign:


.. code-block:: perl

     my %Result = $CryptObject->Verify(
         Message => $Message,
         Sign    => $Sign,
     );


The returned hash %Result has the following keys:


.. code-block:: perl

     SignatureFound => 1,                          # was a signature found at all (0 or 1)
     Successful     => 1,                          # could the signature be verified (0 or 1)
     KeyID          => 'FA23FB24',                 # hex ID of PGP-key that was used for signing
     KeyUserID      => 'username <user@test.org>', # PGP-User-ID (e-mail address) used for signing
     Message        => '...',                      # descriptive text containing the result status
     MessageLong    => '...'                       # full output of GPG binary



KeySearch()
===========


returns a array with search result (private and public keys)


.. code-block:: perl

     my @Keys = $CryptObject->KeySearch(
         Search => 'something to search'
     );



PrivateKeySearch()
==================


returns an array with search result (private keys)


.. code-block:: perl

     my @Keys = $CryptObject->PrivateKeySearch(
         Search => 'something to search'
     );



PublicKeySearch()
=================


returns an array with search result (public keys)


.. code-block:: perl

     my @Keys = $CryptObject->PublicKeySearch(
         Search => 'something to search'
     );



PublicKeyGet()
==============


returns public key in ascii


.. code-block:: perl

     my $Key = $CryptObject->PublicKeyGet(
         Key => $KeyID,
     );



SecretKeyGet()
==============


returns secret key in ascii


.. code-block:: perl

     my $Key = $CryptObject->SecretKeyGet(
         Key => $KeyID,
     );



PublicKeyDelete()
=================


remove public key from key ring


.. code-block:: perl

     $CryptObject->PublicKeyDelete(
         Key => $KeyID,
     );



SecretKeyDelete()
=================


remove secret key from key ring


.. code-block:: perl

     $CryptObject->SecretKeyDelete(
         Key => $KeyID,
     );



KeyAdd()
========


add key to key ring


.. code-block:: perl

     my $Message = $CryptObject->KeyAdd(
         Key => $KeyString,
     );



_HandleLog()
============


Clean and build the log


.. code-block:: perl

     my %Log = $PGPObject->_HandleLog(
         LogString => $LogMessage,
     );



_ParseGPGKeyList()
==================


parses given key list (as received from gpg) and returns an array with key infos


_QuoteShellArgument()
=====================


Quote passed string to be safe to use as a shell argument.


.. code-block:: perl

     my $Result = $Self->_QuoteShellArgument(
         "Safe string for 'shell arguments'."   # string to quote
     );


Returns quoted string if supplied or undef otherwise:


.. code-block:: perl

     $Result = <<'EOS';
 'Safe string for '"'"'shell arguments'"'"'.'
 EOS