pEpCOMServerAdapter/pEpCOMServerAdapter.idl

// pEpCOMServerAdapter.idl : IDL source for pEpCOMServerAdapter
//

// This file will be processed by the MIDL tool to
// produce the type library (pEpCOMServerAdapter.tlb) and marshalling code.

import "oaidl.idl";
import "ocidl.idl";

[
    object,
    uuid(4DA92647-A858-448E-B01F-BE4DCB8C86A1),
    oleautomation,
    nonextensible,
    pointer_default(unique)
]
interface IpEpEngineCallbacks : IUnknown {
    typedef [v1_enum] enum SyncHandshakeSignal {
        SyncNotifyUndefined = 0,

        // request show handshake dialog
        SyncNotifyInitAddOurDevice = 1,
        SyncNotifyInitAddOtherDevice = 2,
        SyncNotifyInitFormGroup = 3,
        // SyncNotifyInitMoveOurDevice = 4,

        // handshake process timed out
        SyncNotifyTimeout = 5,

        // handshake accepted by user
        SyncNotifyAcceptedDeviceAdded = 6,
        SyncNotifyAcceptedGroupCreated = 7,
        SyncNotifyAcceptedDeviceAccepted = 8,

        // handshake dialog must be closed
        // SyncNotifyOvertaken = 9,

        // forming group
        // SyncNotifyFormingGroup = 10,

        SyncNotifyStart = 126,
        SyncNotifyStop = 127,

        // message cannot be sent, need passphrase
        SyncNotifyPassphraseRequired = 128,

        // notificaton of actual group status
        SyncNotifySole = 254,
        SyncNotifyInGroup = 255
    } SyncHandshakeSignal;

    [id(1)] HRESULT MessageToSend([in] struct TextMessage * msg);

    [id(2)] HRESULT NotifyHandshake([in] struct pEpIdentity * self, [in] struct pEpIdentity * partner, [in] SyncHandshakeSignal signal);
};

[
    object,
    uuid(045E49AF-0975-4876-A53B-8CA5AB28C0F8),
    oleautomation,
    nonextensible,
    pointer_default(unique)
]
interface IpEpEngine : IUnknown {

    // runtime config of the adapter

    [id(1)] HRESULT VerboseLogging([in] VARIANT_BOOL enable);

    // runtime config of the engine

    [id(2)] HRESULT PassiveMode([in] VARIANT_BOOL enable);
    [id(3)] HRESULT UnencryptedSubject([in] VARIANT_BOOL enable);

    // basic API

    [id(4)] HRESULT ExportKey([in] BSTR fpr, [out, retval] BSTR * keyData);
    [id(5)] HRESULT Log([in] BSTR title, [in] BSTR entity, [in, defaultvalue("")] BSTR description, [in, defaultvalue("")] BSTR comment);
    [id(6)] HRESULT Trustwords([in] BSTR fpr, [in, defaultvalue("en")] BSTR lang, [in, defaultvalue(0)] LONG maxWords, [out, retval] BSTR * words);
    [id(7)] HRESULT GetTrustwords([in] struct pEpIdentity * id1, [in] struct pEpIdentity * id2, [in, defaultvalue("en")] BSTR lang, [in, defaultvalue(0)] VARIANT_BOOL full, [out, retval] BSTR * words);
    [id(8)] HRESULT GetCrashdumpLog([in, defaultvalue(0)] LONG maxlines, [out, retval] BSTR * log);
    [id(9)] HRESULT GetEngineVersion([out, retval] BSTR * engineVersion);
    [id(10)] HRESULT GetLanguageList([out, retval] BSTR * languages);

    typedef [v1_enum] enum pEpComType {
        pEpCtUnknown = 0,

        // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable

        pEpCtNoEncryption = 0x01,                // generic
        pEpCtNoEncryptedChannel = 0x02,
        pEpCtKeyNotFound = 0x03,
        pEpCtKeyExpired = 0x04,
        pEpCtKeyRevoked = 0x05,
        pEpCtKeyB0rken = 0x06,
        pEpCtMyKeyNotIncluded = 0x09,

        pEpCtSecurityByObscurity = 0x0a,
        pEpCtB0rkenCrypto = 0x0b,
        pEpCtKeyTooShort = 0x0c,

        pEpCtCompromised = 0x0e,                 // known compromized connection
        pEpCtMistrusted = 0x0f,                  // known mistrusted key

        // range 0x10 to 0x3f: unconfirmed encryption

        pEpCtUnconfirmedEncryption = 0x10,       // generic
        pEpCtOpenPGPWeakUnconfirmed = 0x11,      // RSA 1024 is weak

        pEpCtToBeChecked = 0x20,                 // generic
        pEpCtSMIMEUnconfirmed = 0x21,
        pEpCtCMSUnconfirmed = 0x22,

        pEpCtStrongButUnconfirmed = 0x30,        // generic
        pEpCtOpenPGPUnconfirmed = 0x38,          // key at least 2048 bit RSA or EC
        pEpCtOTRUnconfirmed = 0x3a,

        // range 0x40 to 0x7f: unconfirmed encryption and anonymization

        pEpCtUnconfirmedEncAnon = 0x40,          // generic
        pEpCtpEpUnconfirmed = 0x7f,

        pEpCtConfirmed = 0x80,                   // this bit decides if trust is confirmed

        // range 0x81 to 0x8f: reserved
        // range 0x90 to 0xbf: confirmed encryption

        pEpCtConfirmedEncryption = 0x90,         // generic
        pEpCtOpenPGPWeak = 0x91,                 // RSA 1024 is weak

        pEpCtToBeCheckedConfirmed = 0xa0,        // generic
        pEpCtSMIME = 0xa1,
        pEpCtCMS = 0xa2,

        pEpCtStrongEncryption = 0xb0,            // generic
        pEpCtOpenPGP = 0xb8,                     // key at least 2048 bit RSA or EC
        pEpCtOTR = 0xba,

        // range 0xc0 to 0xff: confirmed encryption and anonymization

        pEpCtConfirmedEncAnon = 0xc0,            // generic
        pEpCtpEp = 0xff
    } pEpComType;

    typedef enum pEpStatus {
        pEpStatusOk = 0,

        pEpInitCannotLoadGpgme = 0x0110,
        pEpInitGpgmeInitFailed = 0x0111,
        pEpInitNoGpgHome = 0x0112,
        pEpInitNetpgpInitFailed = 0x0113,
        pEpInitCannotDetermineGpgVersion = 0x0114,
        pEpInitUnsupportedGpgVersion = 0x0115,
        pEpInitCannotConfigGpgAgent = 0x0116,

        pEpInitSqlite3WithoutMutex = 0x0120,
        pEpInitCannotOpenDb = 0x0121,
        pEpInitCannotOpenSystemDb = 0x0122,

        pEpKeyNotFound = 0x0201,
        pEpKeyHasAmbigName = 0x0202,
        pEpGetKeyFailed = 0x0203,
        pEpCannotExportKey = 0x0204,
        pEpCannotEditKey = 0x0205,
        pEpKeyUnsuitable = 0x0206,

        pEpCannotFindIdentity = 0x0301,
        pEpCannotSetPerson = 0x0381,
        pEpCannotSetPgpKeypair = 0x0382,
        pEpCannotSetIdentity = 0x0383,
        pEpCannotSetTrust = 0x0384,
        pEpKeyBlacklisted = 0x0385,
        pEpCannotFindPerson = 0x0386,

        pEpCannotFindAlias = 0x0391,
        pEpCannotSetAlias = 0x0392,

        pEpUnencrypted = 0x0400,
        pEpVerified = 0x0401,
        pEpDecrypted = 0x0402,
        pEpDecryptedAndVerified = 0x0403,
        pEpDecryptWrongFormat = 0x0404,
        pEpDecryptNoKey = 0x0405,
        pEpDecryptSignatureDoesNotMatch = 0x0406,
        pEpVerifyNoKey = 0x0407,
        pEpVerifiedAndTrusted = 0x0408,
        pEpCannotDecryptUnknown = 0x04ff,

        pEpTrustwordNotFound = 0x0501,
        pEpTrustwordsFprWrongLength = 0x0502,
        pEpTrustwordsDuplicateFpr = 0x0503,

        pEpCannotCreateKey = 0x0601,
        pEpCannotSendKey = 0x0602,

        pEpPhraseNotFound = 0x0701,

        pEpSendFunctionNotRegistered = 0x0801,
        pEpContraintsViolated = 0x0802,
        pEpCannotEncode = 0x0803,

        pEpSyncNoNotifyCallback = 0x0901,
        pEpSyncIllegalMessage = 0x0902,
        pEpSyncNoInjectCallback = 0x0903,

        pEpSequenceViolated = 0x0970,
        pEpCannotIncreaseSequence = 0x0971,
        pEpCannotSetSequenceValue = 0x0972,
        pEpOwnSequence = 0x097f,

        pEpSyncStatemachineError = 0x0980,
        pEpSyncNoTrust = 0x0981,
        pEpStatemachineInvalidState = 0x0982,
        pEpStatemachineInvalidEvent = 0x0983,
        pEpStatemachineInvalidCondition = 0x0984,
        pEpStatemachineInvalidAction = 0x0985,
        pEpStatemachineInhibitedEvent = 0x0986,

        pEpCommitFailed = 0xff01,
        pEpMessageConsume = 0xff02,
        pEpMessageIgnore = 0xff03,

        pEpRecordNotFound = -6,
        pEpCannotCreateTempFile = -5,
        pEpIllegalValue = -4,
        pEpBufferTooSmall = -3,
        pEpOutOfMemory = -2,
        pEpUnknownError = -1,

        pEpVersionMismatch = -7,
    } pEpStatus;

    typedef [v1_enum] enum pEpIdentityFlags {
        pEpIdfNone = 0,
        pEpIdfNotForSync = 0x0001,
        pEpIdfList = 0x0002,
        pEpIdfDevicegroup = 0x0100
    } pEpIdentityFlags;

    [uuid(C3A3814E-567F-4D1C-9F44-9B1DA3957A89)] struct pEpIdentity {
        BSTR Address;
        BSTR Fpr;
        BSTR UserId;
        BSTR UserName;
        pEpComType CommType;
        BSTR Lang;
        VARIANT_BOOL Me;
        pEpIdentityFlags Flags;
    };

    [id(11)] HRESULT SetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);
    [id(12)] HRESULT UnsetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);

    // Keymanagement API

    [id(13)] HRESULT StartKeyserverLookup();
    [id(14)] HRESULT StopKeyserverLookup();

    [id(15)] HRESULT Myself([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
    [id(16)] HRESULT UpdateIdentity([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
    [id(17)] HRESULT KeyMistrusted([in] struct pEpIdentity *ident);
    [id(18)] HRESULT KeyResetTrust([in] struct pEpIdentity *ident);
    [id(19)] HRESULT TrustPersonalKey([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
    [id(20)] HRESULT OwnIdentitiesRetrieve([out, retval] SAFEARRAY(struct pEpIdentity)* ownIdentities);
    // [id(21)] HRESULT UndoLastMistrust(); NOT IMPLEMENTED ANY MORE - USE KeyResetTrust() instead
    [id(22)] HRESULT IspEpUser([in] struct pEpIdentity *ident, [out, retval] VARIANT_BOOL *ispEp);

    // Blacklist API
    
    [id(23)] HRESULT BlacklistAdd([in] BSTR fpr);
    [id(24)] HRESULT BlacklistDelete([in] BSTR fpr);
    [id(25)] HRESULT BlacklistIsListed([in] BSTR fpr, [out, retval] VARIANT_BOOL *listed);
    [id(26)] HRESULT BlacklistRetrieve([out, retval] SAFEARRAY(BSTR) *blacklist);

    // PGP compatibility functions

    [id(27)] HRESULT OpenPGPListKeyinfo([in] BSTR searchPattern, [out, retval] SAFEARRAY(struct StringPair)* keyinfoList);

    // Message API

    typedef [v1_enum] enum pEpRating {
        pEpRatingUndefined = 0,
        pEpRatingCannotDecrypt,
        pEpRatingHaveNoKey,
        pEpRatingUnencrypted,
        pEpRatingUnencryptedForSome,
        pEpRatingUnreliable,
        pEpRatingReliable,
        pEpRatingTrusted,
        pEpRatingTrustedAndAnonymized,
        pEpRatingFullyAnonymous,

        pEpRatingMistrust = -1,
        pEpRatingB0rken = -2,
        pEpRatingUnderAttack = -3
    } pEpRating;

    typedef [v1_enum] enum pEpColor {
        pEpColorNoColor = 0,
        pEpColorYellow,
        pEpColorGreen,
        pEpColorRed = -1,
    } pEpColor;

    typedef [v1_enum] enum pEpEncryptFlags {
        pEpEncryptFlagDefault = 0,
        pEpEncryptFlagForceEncryption = 0x1,

        // This flag is for special uses and should not be used
        // by normal pEp clients!
        pEpEncryptFlagForceUnsigned = 0x2,

        // This flag is for special uses and should not be used
        // by normal pEp clients!
        pEpEncryptFlagForceNoAttachedKey = 0x4,

        //<2F>This is mainly used by pEp clients to send private keys to 
        // their own PGP-only device
        pEpEncryptFlagForceVersion1 = 0x16
    } pEpEncryptFlags;

    typedef [v1_enum] enum pEpDecryptFlags {
        pEpDecryptFlagsNone = 0,
        pEpDecryptFlagOwnPrivateKey = 0x1,
        pEpDecryptFlagConsume = 0x2,
        pEpDecryptFlagIgnore = 0x4,
        pEpDecryptFlagSrcModified = 0x8,
        pEpDecryptFlagUntrustedServer = 0x100,
        pEpDecryptFlagDontTriggerSync = 0x200
    } pEpDecryptFlags;

    typedef [v1_enum] enum pEpMsgDirection {
        pEpDirIncoming = 0,
        pEpDirOutgoing
    } pEpMsgDirection;

    typedef [v1_enum] enum pEpEncFormat {
        pEpEncNone = 0,                       // message is not encrypted
        pEpEncPieces,                         // inline PGP + PGP extensions
        pEpEncSMime,                          // RFC5751
        pEpEncPgpMime,                        // RFC3156
        pEpEncPep,                            // pEp encryption format
        pEpEncPgpMimeOutlook1                 // Message B0rken by Outlook type 1
    } pEpEncFormat;

    [uuid(47FB0795-6B64-455C-BB0E-54998CAB8ACB)] struct StringPair {
        BSTR Name;
        BSTR Value;
    };

    [uuid(634EB7CE-99AA-460D-BDF8-F7CDA7232CA6)] struct Blob {
        SAFEARRAY(BYTE) value;
        BSTR MimeType;
        BSTR Filename;
    };

    [uuid(B6F40887-E761-4A47-B204-A0193EE0284D)] struct TextMessage {
        pEpMsgDirection Dir;
        BSTR Id;
        BSTR ShortMsg;
        BSTR LongMsg;
        BSTR LongMsgFormatted;
        SAFEARRAY(struct Blob) Attachments;
        hyper Sent; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
        hyper Recv; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
        struct pEpIdentity From;
        SAFEARRAY(struct pEpIdentity) To;
        struct pEpIdentity RecvBy;
        SAFEARRAY(struct pEpIdentity) Cc;
        SAFEARRAY(struct pEpIdentity) Bcc;
        SAFEARRAY(struct pEpIdentity) ReplyTo;
        SAFEARRAY(BSTR) References;
        SAFEARRAY(BSTR) Keywords;
        BSTR Comments;
        SAFEARRAY(struct StringPair) OptFields;
        pEpEncFormat EncFormat;
        [readonly] BSTR SenderFpr;
    };

    [id(28)] HRESULT EncryptMessage(
        [in, out] struct TextMessage *src,
        [out] struct TextMessage * dst,
        [in] SAFEARRAY(BSTR) extra,
        [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags,
        // Use pEpEncFormat.pEpEncNone for unencrypted, outgoing messages.
        // Default is pEpEncFormat.pEpEncPep, all other formats are only 
        // for compatibility and not intended for normal use.
        [in, defaultvalue(pEpEncPep)] pEpEncFormat encFormat);

    [id(29)] HRESULT DecryptMessage(
        [in, out] struct TextMessage *src,
        [out] struct TextMessage * dst,
        [in, out] SAFEARRAY(BSTR) *keylist,
        [in, out] pEpDecryptFlags* flags,
        [out, retval] pEpRating *rating);

    [id(30)] HRESULT OutgoingMessageRating([in] struct TextMessage *msg, [out, retval] pEpRating * pVal);
    [id(31)] HRESULT IdentityRating([in] struct pEpIdentity * ident, [out, retval] pEpRating * pVal);
    [id(32)] HRESULT ColorFromRating([in] pEpRating rating, [out, retval] pEpColor* pVal);

    [id(33)] HRESULT GetMessageTrustwords(
        [in] struct TextMessage *msg,
        [in] struct pEpIdentity * receivedBy,
        [in] SAFEARRAY(BSTR) keylist,
        [in, defaultvalue("en")] BSTR lang,
        [in, defaultvalue(0)] VARIANT_BOOL full,
        [out, retval] BSTR * words
    );

    [id(34)] HRESULT EncryptMessageForSelf(
        [in] struct pEpIdentity* targetId,
        [in] struct TextMessage* src,
        [in] SAFEARRAY(BSTR) extra, // Fingerprints for extra keys for encryption.
        [out] struct TextMessage* dst,
        [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags
    );

    [id(35)] HRESULT ReEvaluateMessageRating(
        [in, out] struct TextMessage *src,
        [in] SAFEARRAY(BSTR) x_KeyList, // referring to X-KeyList mail header
        [in] pEpRating x_EncStatus, // referring to X-EncStatus mail header
        [out, retval] pEpRating *rating
    );

    // callback / keysync API
    [id(36)] HRESULT RegisterCallbacks([in] IpEpEngineCallbacks* newCallback);
    [id(37)] HRESULT UnregisterCallbacks();

    // mark imported keys as trusted

    [id(38)] HRESULT SetOwnKey(
        [in] struct pEpIdentity * ident,
        [in] BSTR fpr,
        [out, retval] struct pEpIdentity * result
    );

    [id(39)] HRESULT EncryptMessageAndAddPrivKey(
        [in] struct TextMessage *src,
        [out] struct TextMessage * dst,
        [in] BSTR to_fpr,
        [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags,
        // Use pEpEncFormat.pEpEncNone for unencrypted, outgoing messages.
        // Default is pEpEncFormat.pEpEncPep, all other formats are only 
        // for compatibility and not intended for normal use.
        [in, defaultvalue(pEpEncPep)] pEpEncFormat encFormat);

    // Trigger an immediate update check.
    [id(40)] HRESULT UpdateNow([in] BSTR productCode, [out] VARIANT_BOOL *didUpdate);

    // Get a preview of the outgoint message rating
    [id(41)] HRESULT OutgoingMessageRatingPreview([in] struct TextMessage *msg, [out, retval] pEpRating *rating);

    // Trust own public key. To be used for manual key import.
    [id(42)] HRESULT TrustOwnKey([in] struct pEpIdentity * ident);

    // Engine startup and shutdown
    [id(43)] HRESULT Startup();

    // Get the rating for a specific key
    [id(44)] HRESULT GetKeyRatingForUser([in] BSTR userId, [in] BSTR fpr, [out, retval] pEpRating *rating);

    // Resets the database status for a key
    [id(45)] HRESULT KeyResetIdentity([in] struct pEpIdentity ident, [in] BSTR fpr);

    // Resets the default database status for the user / keypair provided
    [id(46)] HRESULT KeyResetUser([in] BSTR userId, [in] BSTR fpr);

    // revoke and mistrust all own keys, generate new keys for all own identities, and opportunistically communicate
    // key reset information to people we have recently contacted. 
    [id(47)] HRESULT KeyResetAllOwnKeys();

    // sync API

    typedef [v1_enum] enum SyncHandshakeResult {
        SyncHandshakeCancel = -1,
        SyncHandshakeAccepted = 0,
        SyncHandshakeRejected = 1
    } SyncHandshakeResult;

    [id(48)] HRESULT DeliverHandshakeResult([in] enum SyncHandshakeResult result, [in] SAFEARRAY(struct pEpIdentity) identities_sharing);

    // Imports keys from data
    [id(49)] HRESULT ImportKey([in] BSTR keyData, [out] SAFEARRAY(struct pEpIdentity)* privateKeys);

    typedef [v1_enum] enum pEpCipherSuite {
        pEpCipherSuiteDefault = 0,
        pEpCipherSuiteCV25519 = 1,
        pEpCipherSuiteP256 = 2,
        pEpCipherSuiteP384 = 3,
        pEpCipherSuiteP521 = 4,
        pEpCipherSuiteRSA2K = 5,
        pEpCipherSuiteRSA3K = 6,
        pEpCipherSuiteRSA4K = 7,
        pEpCipherSuiteRSA8K = 8
    } pEpCipherSuite;

    // Sets the cipher suite
    [id(50)] HRESULT ConfigCipherSuite([in, defaultvalue(pEpCipherSuiteDefault)] pEpCipherSuite cipherSuite);

    // Leave the device group
    [id(51)] HRESULT LeaveDeviceGroup();

    // Get Trustwords for a pair of fprs
    [id(52)] HRESULT GetTrustwordsForFprs([in] BSTR fpr1, [in] BSTR fpr2, [in, defaultvalue("en")] BSTR lang, [in, defaultvalue(0)] VARIANT_BOOL full, [out, retval] BSTR * words);

    // Get the comm type a bare key has
    [id(53)] HRESULT GetKeyRating([in] BSTR fpr, [out, retval] pEpComType *commType);

    // Decode a Sync message from PER into XER
    [id(54)] HRESULT PERToXERSyncMessage([in] struct TextMessage *msg, [out, retval] BSTR *xer);

    // Disable Sync for this identity
    [id(55)] HRESULT DisableIdentityForSync([in] struct pEpIdentity * ident);

    // Enable Sync for this identity
    [id(56)] HRESULT EnableIdentityForSync([in] struct pEpIdentity * ident);

    // Gets the directory where shared files are stored
    [id(57)] HRESULT PerMachineDirectory([out, retval] BSTR *directory);

    // Gets the directory for user files
    [id(58)] HRESULT PerUserDirectory([out, retval] BSTR *directory);

    // Converts a comm type to a pEp rating
    [id(59)] HRESULT RatingFromCommType([in] pEpComType commType, [out, retval] pEpRating * rating);

    // Gets if sync is enabled
    [id(60)] HRESULT GetIsSyncRunning([out, retval] VARIANT_BOOL *running);

    // Shuts down sync
    [id(61)] HRESULT ShutDownSync();

    // Decodes a MIME message
    [id(62)] HRESULT MIMEDecodeMessage([in] BSTR mimeText, [out, retval] struct TextMessage *msg);

    // Encodes a MIME message
    [id(63)] HRESULT MIMEEncodeMessage([in] struct TextMessage *msg, [in] VARIANT_BOOL omitFields, [out, retval] BSTR *mimeText);

    // Configures a key passphrase for the current session
    [id(64)] HRESULT ConfigPassphrase([in] BSTR passphrase);

    // Passphrase enablement for newly-generated secret keys
    [id(65)] HRESULT ConfigPassphraseForNewKeys([in] VARIANT_BOOL enable, [in] BSTR passphrase);

    // Shows a notification in the notification tray
    [id(66)] HRESULT ShowNotification([in] BSTR title, [in] BSTR message);
};

[
    uuid(564A4350-419E-47F1-B0DF-6FCCF0CD0BBC),
    version(1.0),
]
library pEpCOMServerAdapterLib
{
    importlib("stdole2.tlb");

    [
        uuid(5FF6682B-727B-4DFE-A68D-28982874C0C7)
    ]
    coclass pEpEngine {
        [default] interface IpEpEngine;
        interface IpEpEngineCallbacks;
    };
};