pEpCOMServerAdapter.idl
author Markus Schaber <markus@pep-security.net>
Wed, 01 Feb 2017 21:37:07 +0100
changeset 232 4c6d44bed519
parent 231 fbe8c644918f
child 237 589b9cb32b07
permissions -rw-r--r--
COM-48 Implement timeout, and signal the app to poll inbox faster when waiting
on KeySync queue with a timeout.

First implementation draft.
     1 // pEpCOMServerAdapter.idl : IDL source for pEpCOMServerAdapter
     2 //
     3 
     4 // This file will be processed by the MIDL tool to
     5 // produce the type library (pEpCOMServerAdapter.tlb) and marshalling code.
     6 
     7 import "oaidl.idl";
     8 import "ocidl.idl";
     9 
    10 [
    11     object,
    12     uuid(4DA92647-A858-448E-B01F-BE4DCB8C86A1),
    13     oleautomation,
    14     nonextensible,
    15     pointer_default(unique)
    16 ]
    17 interface IpEpEngineCallbacks : IUnknown {
    18 	typedef [v1_enum] enum SyncHandshakeSignal {
    19         SyncNotifyUndefined = 0,
    20         SyncNotifyInitAddOurDevice = 1,
    21         SyncNotifyInitAddOtherDevice = 2,
    22         SyncNotifyInitFormGroup = 3,
    23         SyncNotifyTimeout = 4,
    24         SyncNotifyAcceptedDeviceAdded = 5,
    25         SyncNotifyAcceptedGroupCreated = 6
    26 	} SyncHandshakeSignal;
    27 
    28     typedef [v1_enum] enum SyncHandshakeResult {
    29         SyncHandshakeCancel = -1,
    30         SyncHandshakeAccepted = 0,
    31         SyncHandshakeRejected = 1
    32     } SyncHandshakeResult;
    33 
    34     [id(1)] HRESULT MessageToSend([in] struct TextMessage * msg);
    35     [id(2)] HRESULT NotifyHandshake([in] struct pEpIdentity * self, [in] struct pEpIdentity * partner, [in] SyncHandshakeSignal signal, [out, retval] SyncHandshakeResult * result);
    36 };
    37 
    38 [
    39     object,
    40     uuid(64E964B2-880A-4E92-B0B5-66FF4286A3B3),
    41     oleautomation,
    42     nonextensible,
    43     pointer_default(unique)
    44 ]
    45 interface IpEpEngineCallbacks2 : IpEpEngineCallbacks 
    46 {
    47     [id(3)] HRESULT NeedFastPolling([in] VARIANT_BOOL enableFastPolling);
    48 };
    49 
    50 [
    51     object,
    52     uuid(045E49AF-0975-4876-A53B-8CA5AB28C0F8),
    53     oleautomation,
    54     nonextensible,
    55     pointer_default(unique)
    56 ]
    57 interface IpEpEngine : IUnknown {
    58 
    59     // runtime config of the adapter
    60 
    61     HRESULT VerboseLogging([in] VARIANT_BOOL enable);
    62 
    63     // runtime config of the engine
    64 
    65     HRESULT PassiveMode([in] VARIANT_BOOL enable);
    66     HRESULT UnencryptedSubject([in] VARIANT_BOOL enable);
    67 
    68     // basic API
    69 
    70     HRESULT ExportKey([in] BSTR fpr, [out, retval] BSTR * keyData);
    71     HRESULT Log([in] BSTR title, [in] BSTR entity, [in, defaultvalue("")] BSTR description, [in, defaultvalue("")] BSTR comment);
    72     HRESULT Trustwords([in] BSTR fpr, [in, defaultvalue("en")] BSTR lang, [in, defaultvalue(0)] LONG maxWords, [out, retval] BSTR * words);
    73     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);
    74     HRESULT GetCrashdumpLog([in, defaultvalue(0)] LONG maxlines, [out, retval] BSTR * log);
    75     HRESULT GetEngineVersion([out, retval] BSTR * engineVersion);
    76     HRESULT GetLanguageList([out, retval] BSTR * languages);
    77 
    78     typedef [v1_enum] enum pEpComType {
    79         pEpCtUnknown = 0,
    80 
    81         // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
    82 
    83         pEpCtNoEncryption = 0x01,                // generic
    84         pEpCtNoEncryptedChannel = 0x02,
    85         pEpCtKeyNotFound = 0x03,
    86         pEpCtKeyExpired = 0x04,
    87         pEpCtKeyRevoked = 0x05,
    88         pEpCtKeyB0rken = 0x06,
    89         pEpCtMyKeyNotIncluded = 0x09,
    90 
    91         pEpCtSecurityByObscurity = 0x0a,
    92         pEpCtB0rkenCrypto = 0x0b,
    93         pEpCtKeyTooShort = 0x0c,
    94 
    95         pEpCtCompromised = 0x0e,                 // known compromized connection
    96         pEpCtMistrusted = 0x0f,                  // known mistrusted key
    97 
    98         // range 0x10 to 0x3f: unconfirmed encryption
    99 
   100         pEpCtUnconfirmedEncryption = 0x10,       // generic
   101         pEpCtOpenPGPWeakUnconfirmed = 0x11,      // RSA 1024 is weak
   102 
   103         pEpCtToBeChecked = 0x20,                 // generic
   104         pEpCtSMIMEUnconfirmed = 0x21,
   105         pEpCtCMSUnconfirmed = 0x22,
   106 
   107         pEpCtStrongButUnconfirmed = 0x30,        // generic
   108         pEpCtOpenPGPUnconfirmed = 0x38,          // key at least 2048 bit RSA or EC
   109         pEpCtOTRUnconfirmed = 0x3a,
   110 
   111         // range 0x40 to 0x7f: unconfirmed encryption and anonymization
   112 
   113         pEpCtUnconfirmedEncAnon = 0x40,          // generic
   114         pEpCtpEpUnconfirmed = 0x7f,
   115 
   116         pEpCtConfirmed = 0x80,                   // this bit decides if trust is confirmed
   117 
   118         // range 0x81 to 0x8f: reserved
   119         // range 0x90 to 0xbf: confirmed encryption
   120 
   121         pEpCtConfirmedEncryption = 0x90,         // generic
   122         pEpCtOpenPGPWeak = 0x91,                 // RSA 1024 is weak
   123 
   124         pEpCtToBeCheckedConfirmed = 0xa0,        // generic
   125         pEpCtSMIME = 0xa1,
   126         pEpCtCMS = 0xa2,
   127 
   128         pEpCtStrongEncryption = 0xb0,            // generic
   129         pEpCtOpenPGP = 0xb8,                     // key at least 2048 bit RSA or EC
   130         pEpCtOTR = 0xba,
   131 
   132         // range 0xc0 to 0xff: confirmed encryption and anonymization
   133 
   134         pEpCtConfirmedEncAnon = 0xc0,            // generic
   135         pEpCtpEp = 0xff
   136     } pEpComType;
   137 
   138 	typedef [v1_enum] enum pEpIdentityFlags {
   139 		pEpIdfNone = 0,
   140 		pEpIdfNotForSync = 0x0001,
   141 		pEpIdfList = 0x0002,
   142 		pEpIdfDevicegroup = 0x0100
   143 	} pEpIdentityFlags;
   144 
   145     [uuid(C3A3814E-567F-4D1C-9F44-9B1DA3957A89)] struct pEpIdentity {
   146         BSTR Address;
   147         BSTR Fpr;
   148         BSTR UserId;
   149         BSTR UserName;
   150         pEpComType CommType;
   151         BSTR Lang;
   152 		pEpIdentityFlags Flags;
   153     };
   154 
   155 	HRESULT SetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);
   156 	HRESULT UnsetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);
   157 
   158     // Keymanagement API
   159 
   160     HRESULT StartKeyserverLookup();
   161     HRESULT StopKeyserverLookup();
   162 
   163     HRESULT Myself([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   164     HRESULT UpdateIdentity([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   165     HRESULT KeyMistrusted([in] struct pEpIdentity *ident);
   166     HRESULT KeyResetTrust([in] struct pEpIdentity *ident);
   167     HRESULT TrustPersonalKey([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   168 	HRESULT OwnIdentitiesRetrieve([out, retval] SAFEARRAY(struct pEpIdentity)* own_identities);
   169 
   170     // Blacklist API
   171 
   172     HRESULT BlacklistAdd([in] BSTR fpr);
   173     HRESULT BlacklistDelete([in] BSTR fpr);
   174     HRESULT BlacklistIsListed([in] BSTR fpr, [out, retval] VARIANT_BOOL *listed);
   175     HRESULT BlacklistRetrieve([out, retval] SAFEARRAY(BSTR) *blacklist);
   176 
   177     // PGP compatibility functions
   178 
   179     HRESULT OpenPGPListKeyinfo([in] BSTR searchPattern, [out, retval] SAFEARRAY(struct StringPair)* keyinfoList);
   180 
   181     // Message API
   182 
   183     typedef [v1_enum] enum pEpRating {
   184         pEpRatingUndefined = 0,
   185         pEpRatingCannotDecrypt,
   186         pEpRatingHaveNoKey,
   187         pEpRatingUnencrypted,
   188         pEpRatingUnencryptedForSome,
   189         pEpRatingUnreliable,
   190         pEpRatingReliable,
   191         pEpRatingTrusted,
   192         pEpRatingTrustedAndAnonymized,
   193         pEpRatingFullyAnonymous,
   194 
   195         pEpRatingMistrust = -1,
   196         pEpRatingB0rken = -2,
   197         pEpRatingUnderAttack = -3
   198     } pEpRating;
   199 
   200     typedef [v1_enum] enum pEpColor {
   201         pEpColorNoColor = 0,
   202         pEpColorYellow,
   203         pEpColorGreen,
   204         pEpColorRed = -1,
   205     } pEpColor;
   206 
   207     typedef [v1_enum] enum pEpEncryptFlags {
   208         pEpEncryptFlagsNone = 0,
   209         pEpEncryptFlagForceEncryption = 0x1,
   210     } pEpEncryptFlags;
   211 
   212     typedef [v1_enum] enum pEpDecryptFlags {
   213         pEpDecryptFlagsNone = 0,
   214         pEpDecryptFlagOwnPrivateKey = 0x1,
   215         pEpDecryptFlagConsume = 0x2,
   216         pEpDecryptFlagIgnore = 0x4
   217     } pEpDecryptFlags;
   218 
   219     typedef [v1_enum] enum pEpMsgDirection {
   220         pEpDirIncoming = 0,
   221         pEpDirOutgoing
   222     } pEpMsgDirection;
   223 
   224     [uuid(47FB0795-6B64-455C-BB0E-54998CAB8ACB)] struct StringPair {
   225         BSTR Name;
   226         BSTR Value;
   227     };
   228 
   229     [uuid(634EB7CE-99AA-460D-BDF8-F7CDA7232CA6)] struct Blob {
   230         SAFEARRAY(BYTE) value;
   231         BSTR MimeType;
   232         BSTR Filename;
   233     };
   234 
   235     [uuid(B6F40887-E761-4A47-B204-A0193EE0284D)] struct TextMessage {
   236         pEpMsgDirection Dir;
   237         BSTR Id;
   238         BSTR ShortMsg;
   239         BSTR LongMsg;
   240         BSTR LongMsgFormatted;
   241         SAFEARRAY(struct Blob) Attachments;
   242         hyper Sent; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
   243         hyper Recv; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
   244         struct pEpIdentity From;
   245         SAFEARRAY(struct pEpIdentity) To;
   246         struct pEpIdentity RecvBy;
   247         SAFEARRAY(struct pEpIdentity) Cc;
   248         SAFEARRAY(struct pEpIdentity) Bcc;
   249         SAFEARRAY(struct pEpIdentity) ReplyTo;
   250         SAFEARRAY(BSTR) References;
   251         SAFEARRAY(BSTR) Keywords;
   252         BSTR Comments;
   253         SAFEARRAY(struct StringPair) OptFields;
   254     };
   255 
   256     HRESULT EncryptMessage([in] struct TextMessage *src, [out] struct TextMessage * dst, [in] SAFEARRAY(BSTR) extra, [in, defaultvalue(pEpEncryptFlagsNone)] pEpEncryptFlags flags);
   257     HRESULT DecryptMessage([in] struct TextMessage *src, [out] struct TextMessage * dst, [out] SAFEARRAY(BSTR) *keylist, [out] pEpDecryptFlags* flags, [out, retval] pEpRating *rating);
   258 
   259     HRESULT OutgoingMessageRating([in] struct TextMessage *msg, [out, retval] pEpRating * pVal);
   260     HRESULT IdentityRating([in] struct pEpIdentity * ident, [out, retval] pEpRating * pVal);
   261     HRESULT ColorFromRating([in] pEpRating rating, [out, retval] pEpColor* pVal);
   262 
   263     // callback / keysync API
   264     HRESULT RegisterCallbacks([in] IpEpEngineCallbacks* newCallback);
   265     HRESULT UnregisterCallbacks();
   266 };
   267 
   268 [
   269     object,
   270     uuid(8A042123-D433-4DEA-ADA2-2E5E61A00292),
   271     oleautomation,
   272     nonextensible,
   273     pointer_default(unique)
   274 ]
   275 interface IpEpEngine2 : IpEpEngine
   276 {
   277     HRESULT GetMessageTrustwords(
   278         [in] struct TextMessage *msg,
   279         [in] struct pEpIdentity * receivedBy,
   280         [in] SAFEARRAY(BSTR) keylist,
   281         [in, defaultvalue("en")] BSTR lang,
   282         [in, defaultvalue(0)] VARIANT_BOOL full,
   283         [out, retval] BSTR * words
   284     );
   285 };
   286 
   287 [
   288     uuid(564A4350-419E-47F1-B0DF-6FCCF0CD0BBC),
   289     version(1.0),
   290 ]
   291 library pEpCOMServerAdapterLib
   292 {
   293     importlib("stdole2.tlb");
   294 
   295     [
   296         uuid(5FF6682B-727B-4DFE-A68D-28982874C0C7)
   297     ]
   298     coclass pEpEngine {
   299         [default] interface IpEpEngine2;
   300         interface IpEpEngine;
   301         interface IpEpEngineCallbacks2;
   302     };
   303 };