SMIME

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

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

Crypt()#

crypt a message

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)

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

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

Sign()#

sign a message

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)

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:

%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()#

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.

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

or

Returns list of all certificates.

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

or

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

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.

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.

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

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

Returns:

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

ConvertCertFormat()#

Convert certificate strings into importable PEM format.

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

Returns:

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

CertificateAdd()#

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

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

CertificateGet()#

get a local certificate

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

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

CertificateRemove()#

remove a local certificate

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

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

CertificateList()#

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

or

Array of filenames

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

CertificateAttributes()#

get certificate attributes

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

CertificateRead()#

show a local certificate in plain text

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.

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

PrivateSearch()#

Returns a list of private keys searching using indexable attributes.

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

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

PrivateAdd()#

add private key

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

PrivateGet()#

get private key

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

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

PrivateRemove()#

remove private key

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

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

PrivateList()#

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

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

PrivateAttributes()#

returns attributes of private key

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

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

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

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

SignerCertRelationExists ()#

returns the ID if the relation exists

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

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

SignerCertRelationDelete ()#

returns 1 if success

# 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.

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()#

Reindexes certificates from local file system to database.

my $Result = $CryptObject->ReIndexCertificate(
    CanReHash => 1 # Required, Allow to rehash certificates.
);

ReIndexPrivate()#

Reindexes private files from local file system to database.

my $Result = $CryptObject->ReIndexPrivate(
    CanNormalize => 1 # Required, Allow to normalize private keys and secrets.
);