#####
SMIME
#####


****
NAME
****


Kernel::System::Crypt::SMIME - smime crypt backend lib


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


This is a sub module of Kernel::System::Crypt and contains all smime 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,
         Certificates => [
             {
                 Filename => $CertificateFilename,
             },
             {
                 Hash        => $CertificateHash,
                 Fingerprint => $CertificateFingerprint,
             },
             # ...
         ]
     );
 
     my $Message = $CryptObject->Crypt(
         Message  => $Message,
         Filename => $CertificateFilename,
     );
 
     my $Message = $CryptObject->Crypt(
         Message     => $Message,
         Hash        => $CertificateHash,
         Fingerprint => $CertificateFingerprint,
     );



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


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


.. code-block:: perl

     my %Message = $CryptObject->Decrypt(
         Message  => $CryptedMessage,
         Filename => $Filename,
     );
 
     my %Message = $CryptObject->Decrypt(
         Message     => $CryptedMessage,
         Hash        => $Hash,
         Fingerprint => $Fingerprint,
     );



Sign()
======


sign a message


.. code-block:: perl

     my $Sign = $CryptObject->Sign(
         Message  => $Message,
         Filename => $PrivateFilename,
     );
     my $Sign = $CryptObject->Sign(
         Message     => $Message,
         Hash        => $Hash,
         Fingerprint => $Fingerprint,
     );



Verify()
========


verify a message with signature and returns a hash (Successful, Message, Signers, SignerCertificate)


.. code-block:: perl

     my %Data = $CryptObject->Verify(
         Message => $Message,
         CACert  => $PathtoCACert,                   # the certificates autority that endorse a self
                                                     # signed certificate
         RetryWithNoVerify => 0,                     # optional; if config option SMIME::NoVerify is set,
                                                     # verification will be tried with '-noverify' option
                                                     # after initial failure
     );


returns:


.. code-block:: perl

     %Data = (
         SignatureFound    => 1,                     # or 0 if no signature was found
         Successful        => 1,                     # or 0 if the verification process failed
         Message           => $Message,              # short version of the verification output
         MessageLong       => $MessageLong,          # full verification output
         Signers           => [                      # optional, array reference to all signers
             'someone@company.com',                  #    addresses
         ],
         SignerCertificate => $SignerCertificate,    # the certificate that signs the message
         Content           => $Content,              # the message content
     );



KeysList()
==========



.. code-block:: perl

     Return list of all SMIME public and private keys with their attributes.
 
     my @Result = $CryptObject->KeysList()



Search()
========


Search for public and private certificates within files.


.. code-block:: perl

     my @Result = $CryptObject->Search(
         Search => 'some text to search',
     );


or

Returns list of all certificates.


.. code-block:: perl

     my @Result = $CryptObject->Search(
         IndexedSearch => 1 # Optional.
     );


or

Search for public and private certificates within files using indexed values.


.. code-block:: perl

     my @Result = $CryptObject->Search(
         Search => 'some text to search',
         SearchType => 'e-mail/hash/filename/id', # Default lookup by e-mail
         IndexedSearch => 1 # Required if want to search via indexed attributes.
     );



CertificateSearch()
===================


Returns a list of certificates searching using indexable attributes.


.. code-block:: perl

     my @Result = $CryptObject->CertificateSearch(
         Search => $Search,
         SearchType => 'e-mail/hash/filename/id/fingerprint', # Default lookup by e-mail
         Valid  => 1
     );
 
     or
 
     my @Result = $CryptObject->CertificateSearch(); # For all certificates.



CertificateFileSearch()
=======================


Looks for a given "Search" in physical certificates, not recommended for indexed attributes.


.. code-block:: perl

     my @Result = $CryptObject->CertificateFileSearch(
         Search       => 'some text to search',
         Valid        => 1, # Optional, default doesn't check if valid.
         Certificates => $Certificates # Optional, list of certificates to check.
     );



FetchFromCustomer()
===================


add certificates from CustomerUserAttributes to local certificates
returns an array of filenames of added certificates


.. code-block:: perl

     my @Result = $CryptObject->FetchFromCustomer(
         Search => $SearchEmailAddress,
     );


Returns:


.. code-block:: perl

     @Result = ( '6e620dcc.0', '8096d0a9.0', 'c01cdfa2.0' );



ConvertCertFormat()
===================


Convert certificate strings into importable \ ``PEM``\  format.


.. code-block:: perl

     my $Result = $CryptObject->ConvertCertFormat(
         String     => $CertificationString,
         Passphrase => Password for PFX (optional)
     );


Returns:


.. code-block:: perl

     $Result =
     "-----BEGIN CERTIFICATE-----
     MIIEXjCCA0agAwIBAgIJAPIBQyBe/HbpMA0GCSqGSIb3DQEBBQUAMHwxCzAJBgNV
     # ...
     nj2wbQO4KjM12YLUuvahk5se
     -----END CERTIFICATE-----
     ";



CertificateAdd()
================


add a certificate to local certificates
returns result message and new certificate filename


.. code-block:: perl

     my %Result = $CryptObject->CertificateAdd(
         Certificate => $CertificateString,
     );



CertificateGet()
================


get a local certificate


.. code-block:: perl

     my $Certificate = $CryptObject->CertificateGet(
         Filename => $CertificateFilename,
     );
 
     my $Certificate = $CryptObject->CertificateGet(
         Fingerprint => $Fingerprint,
         Hash        => $Hash,
     );



CertificateRemove()
===================


remove a local certificate


.. code-block:: perl

     $CryptObject->CertificateRemove(
         Filename => $CertificateHash,
     );
 
     $CryptObject->CertificateRemove(
         Hash        => $CertificateHash,
         Fingerprint => $CertificateHash,
     );



CertificateList()
=================


Get hash ref of local certificates filenames(ID => Filename)

or

Array of filenames


.. code-block:: perl

     my $CertList = $CryptObject->CertificateList(
         ResultType => 'ARRAY/HASH' # 'ARRAY' by default
     );



CertificateAttributes()
=======================


get certificate attributes


.. code-block:: perl

     my %CertificateAttributes = $CryptObject->CertificateAttributes(
         Certificate => $CertificateString,
         Filename    => '12345.1',              # optional (useful to use cache)
     );



CertificateRead()
=================


show a local certificate in plain text


.. code-block:: perl

     my $CertificateText = $CryptObject->CertificateRead(
         Filename => $CertificateFilename,
     );
 
     my $CertificateText = $CryptObject->CertificateRead(
         Fingerprint => $Fingerprint,
         Hash        => $Hash,
     );



PrivateFileSearch()
===================


Looks for a given search parameter in physical certificates, not recommended for indexed attributes.


.. code-block:: perl

     my @Result = $CryptObject->PrivateFileSearch(
         Search => 'some text to search',
         Valid  => 1  # optional
     );



PrivateSearch()
===============


Returns a list of private keys searching using indexable attributes.


.. code-block:: perl

     my @Result = $CryptObject->PrivateSearch(
         Search => $Search,
         SearchType => 'e-mail/hash/filename/id/fingerprint', # Default e-mail.
         Valid  => 1  # optional
     );
 
     or
 
     my @Result = $CryptObject->PrivateSearch(); # For all private keys.



KeyExpiredCheck()
=================


returns if SMIME key is expired


.. code-block:: perl

     my $Valid = $CryptObject->KeyExpiredCheck(
         EndDate => 'May 12 23:50:40 2018 GMT',
     );



PrivateAdd()
============


add private key


.. code-block:: perl

     my %Result = $CryptObject->PrivateAdd(
         Private => $PrivateKeyString,
         Secret  => 'Password',
     );



PrivateGet()
============


get private key


.. code-block:: perl

     my ($PrivateKey, $Secret) = $CryptObject->PrivateGet(
         Filename => $PrivateFilename,
     );
 
     my ($PrivateKey, $Secret) = $CryptObject->PrivateGet(
         Hash    => $Hash,
         Modulus => $Modulus,
     );



PrivateRemove()
===============


remove private key


.. code-block:: perl

     $CryptObject->PrivateRemove(
         Filename => $Filename,
     );
 
     $CryptObject->PrivateRemove(
         Hash    => $Hash,
         Modulus => $Modulus,
     );



PrivateList()
=============


Returns a hash of private key hashes(ID => Filename).


.. code-block:: perl

     my $PrivateList = $CryptObject->PrivateList();



PrivateAttributes()
===================


returns attributes of private key


.. code-block:: perl

     my %Hash = $CryptObject->PrivateAttributes(
         Private  => $PrivateKeyString,
         Secret   => 'Password',
         Filename => '12345.1',              # optional (useful for cache)
     );



SignerCertRelationAdd ()
========================


add a relation between signer certificate and CA certificate to attach to the signature


.. code-block:: perl

     my $Success = $CryptObject->SignerCertRelationAdd(
         CertFingerprint => $CertFingerprint,
         CAFingerprint => $CAFingerprint,
         UserID => 1,
     );



SignerCertRelationGet ()
========================


get relation data by ID or by Certificate finger print
returns data Hash if ID given or Array of all relations if CertFingerprint given


.. code-block:: perl

     my %Data = $CryptObject->SignerCertRelationGet(
         ID => $RelationID,
     );
 
     my @Data = $CryptObject->SignerCertRelationGet(
         CertFingerprint => $CertificateFingerprint,
     );



SignerCertRelationExists ()
===========================


returns the ID if the relation exists


.. code-block:: perl

     my $Result = $CryptObject->SignerCertRelationExists(
         CertFingerprint => $CertificateFingerprint,
         CAFingerprint => $CAFingerprint,
     );
 
     my $Result = $CryptObject->SignerCertRelationExists(
         ID => $RelationID,
     );



SignerCertRelationDelete ()
===========================


returns 1 if success


.. code-block:: perl

     # delete all relations for a cert
     my $Success = $CryptObject->SignerCertRelationDelete (
         CertFingerprint => $CertFingerprint,
         UserID => 1,
     );
 
     # delete one relation by ID
     $Success = $CryptObject->SignerCertRelationDelete (
         ID => '45',
     );
 
     # delete one relation by CertFingerprint & CAFingerprint
     $Success = $CryptObject->SignerCertRelationDelete (
         CertFingerprint => $CertFingerprint,
         CAFingerprint   => $CAFingerprint,
     );
 
     # delete one relation by CAFingerprint
     $Success = $CryptObject->SignerCertRelationDelete (
         CAFingerprint   => $CAFingerprint,
     );



CheckCertPath()
===============


Checks and fixes the private secret files that do not have an index. (Needed because this
changed during the migration from OTRS 3.0 to 3.1.)

Checks and fixed certificates, private keys and secrets files to have a correct name
depending on the current OpenSSL hash algorithm.


.. code-block:: perl

     my $Result = $CryptObject->CheckCertPath ();
 
     a result could be:
 
     $Result = {
         Success => 1,               # or 0 if fails
         Details => $Details         # a readable string log of all activities and errors found
     };



ReIndexCertificate()
====================



.. code-block:: perl

     Reindexes certificates from local file system to database.
 
     my $Result = $CryptObject->ReIndexCertificate(
         CanReHash => 1 # Required, Allow to rehash certificates.
     );



ReIndexPrivate()
================



.. code-block:: perl

     Reindexes private files from local file system to database.
 
     my $Result = $CryptObject->ReIndexPrivate(
         CanNormalize => 1 # Required, Allow to normalize private keys and secrets.
     );