OTRS Academy » Documentation » OTRS API Reference Perl » Kernel::System::Crypt::SMIME

Kernel::System::Crypt::SMIME

October 26, 2023

NAME

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

DESCRIPTION

This is a sub module of Kernel::System::Crypt and contains all S/MIME 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  => $EncryptedMessage,
        Filename => $Filename,
    );

    my %Message = $CryptObject->Decrypt(
        Message     => $EncryptedMessage,
        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 authority that endorse a self
                                                    # signed certificate
    );

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
    );

search a certificate or an private key

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

CertificateSearch()

search a local certificate

    my @Result = $CryptObject->CertificateSearch(
        Search          => 'some text to search',    # default ''
        SMIMESigning    => 1,                        # default 0, search certificates for S/MIME Signing purpose
        SMIMEEncryption => 1,                        # default 0, search certificates for S/MIME Encryption purpose
        Valid           => 1,                        # default 0
    );

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 list of local certificates filenames

    my @CertList = $CryptObject->CertificateList();

CertificateAttributes()

get certificate attributes

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

CertificateRead()

show a local certificate in plain text

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

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

PrivateSearch()

returns private keys

    my @Result = $CryptObject->PrivateSearch(
        Search => 'some text to search',             # default ''
        SMIMESigning    => 1,                        # default 0, search certificates for S/MIME Signing purpose
        SMIMEEncryption => 1,                        # default 0, search certificates for S/MIME Encryption purpose
        Valid           => 1,                        # default 0
    );

KeyExpiredCheck()

returns if S/MIME 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 list of private key hashes

    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)
        SkipCache => 1,                     # optional (skip cache read)
    );

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
    };
FacebookXEmailLinkedIn
Scroll to Top