pEpCOMServerAdapter.idl
author Thomas
Wed, 02 May 2018 09:46:48 +0200
branchCOM-87
changeset 287 99abd7d70c1e
parent 286 c6bf26cf7a08
child 289 71e95ca19464
permissions -rw-r--r--
Rename flags
     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 
    21         // request show handshake dialog
    22         SyncNotifyInitAddOurDevice = 1,
    23         SyncNotifyInitAddOtherDevice = 2,
    24         SyncNotifyInitFormGroup = 3,
    25         SyncNotifyInitMoveOurDevice = 4,
    26 
    27         // handshake process timed out
    28         SyncNotifyTimeout = 5,
    29 
    30         // handshake accepted by user
    31         SyncNotifyAcceptedDeviceAdded = 6,
    32         SyncNotifyAcceptedGroupCreated = 7,
    33         SyncNotifyAcceptedDeviceMoved = 8,
    34 
    35         // handshake dialog must be closed
    36         SyncNotifyOvertaken = 9,
    37     } SyncHandshakeSignal;
    38 
    39     typedef [v1_enum] enum SyncHandshakeResult {
    40         SyncHandshakeCancel = -1,
    41         SyncHandshakeAccepted = 0,
    42         SyncHandshakeRejected = 1
    43     } SyncHandshakeResult;
    44 
    45     [id(1)] HRESULT MessageToSend([in] struct TextMessage * msg);
    46 
    47     [id(2)] HRESULT NotifyHandshake([in] struct pEpIdentity * self, [in] struct pEpIdentity * partner, [in] SyncHandshakeSignal signal, [out, retval] SyncHandshakeResult * result);
    48 
    49     [id(3)] HRESULT NeedFastPolling([in] VARIANT_BOOL enableFastPolling);
    50 };
    51 
    52 [
    53     object,
    54     uuid(045E49AF-0975-4876-A53B-8CA5AB28C0F8),
    55     oleautomation,
    56     nonextensible,
    57     pointer_default(unique)
    58 ]
    59 interface IpEpEngine : IUnknown {
    60 
    61     // runtime config of the adapter
    62 
    63     [id(1)] HRESULT VerboseLogging([in] VARIANT_BOOL enable);
    64 
    65     // runtime config of the engine
    66 
    67     [id(2)] HRESULT PassiveMode([in] VARIANT_BOOL enable);
    68     [id(3)] HRESULT UnencryptedSubject([in] VARIANT_BOOL enable);
    69 
    70     // basic API
    71 
    72     [id(4)] HRESULT ExportKey([in] BSTR fpr, [out, retval] BSTR * keyData);
    73     [id(5)] HRESULT Log([in] BSTR title, [in] BSTR entity, [in, defaultvalue("")] BSTR description, [in, defaultvalue("")] BSTR comment);
    74     [id(6)] HRESULT Trustwords([in] BSTR fpr, [in, defaultvalue("en")] BSTR lang, [in, defaultvalue(0)] LONG maxWords, [out, retval] BSTR * words);
    75     [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);
    76     [id(8)] HRESULT GetCrashdumpLog([in, defaultvalue(0)] LONG maxlines, [out, retval] BSTR * log);
    77     [id(9)] HRESULT GetEngineVersion([out, retval] BSTR * engineVersion);
    78     [id(10)] HRESULT GetLanguageList([out, retval] BSTR * languages);
    79 
    80     typedef [v1_enum] enum pEpComType {
    81         pEpCtUnknown = 0,
    82 
    83         // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
    84 
    85         pEpCtNoEncryption = 0x01,                // generic
    86         pEpCtNoEncryptedChannel = 0x02,
    87         pEpCtKeyNotFound = 0x03,
    88         pEpCtKeyExpired = 0x04,
    89         pEpCtKeyRevoked = 0x05,
    90         pEpCtKeyB0rken = 0x06,
    91         pEpCtMyKeyNotIncluded = 0x09,
    92 
    93         pEpCtSecurityByObscurity = 0x0a,
    94         pEpCtB0rkenCrypto = 0x0b,
    95         pEpCtKeyTooShort = 0x0c,
    96 
    97         pEpCtCompromised = 0x0e,                 // known compromized connection
    98         pEpCtMistrusted = 0x0f,                  // known mistrusted key
    99 
   100         // range 0x10 to 0x3f: unconfirmed encryption
   101 
   102         pEpCtUnconfirmedEncryption = 0x10,       // generic
   103         pEpCtOpenPGPWeakUnconfirmed = 0x11,      // RSA 1024 is weak
   104 
   105         pEpCtToBeChecked = 0x20,                 // generic
   106         pEpCtSMIMEUnconfirmed = 0x21,
   107         pEpCtCMSUnconfirmed = 0x22,
   108 
   109         pEpCtStrongButUnconfirmed = 0x30,        // generic
   110         pEpCtOpenPGPUnconfirmed = 0x38,          // key at least 2048 bit RSA or EC
   111         pEpCtOTRUnconfirmed = 0x3a,
   112 
   113         // range 0x40 to 0x7f: unconfirmed encryption and anonymization
   114 
   115         pEpCtUnconfirmedEncAnon = 0x40,          // generic
   116         pEpCtpEpUnconfirmed = 0x7f,
   117 
   118         pEpCtConfirmed = 0x80,                   // this bit decides if trust is confirmed
   119 
   120         // range 0x81 to 0x8f: reserved
   121         // range 0x90 to 0xbf: confirmed encryption
   122 
   123         pEpCtConfirmedEncryption = 0x90,         // generic
   124         pEpCtOpenPGPWeak = 0x91,                 // RSA 1024 is weak
   125 
   126         pEpCtToBeCheckedConfirmed = 0xa0,        // generic
   127         pEpCtSMIME = 0xa1,
   128         pEpCtCMS = 0xa2,
   129 
   130         pEpCtStrongEncryption = 0xb0,            // generic
   131         pEpCtOpenPGP = 0xb8,                     // key at least 2048 bit RSA or EC
   132         pEpCtOTR = 0xba,
   133 
   134         // range 0xc0 to 0xff: confirmed encryption and anonymization
   135 
   136         pEpCtConfirmedEncAnon = 0xc0,            // generic
   137         pEpCtpEp = 0xff
   138     } pEpComType;
   139 
   140     typedef enum pEpStatus {
   141         pEpStatusOk = 0,
   142 
   143         pEpInitCannotLoadGpgme = 0x0110,
   144         pEpInitGpgmeInitFailed = 0x0111,
   145         pEpInitNoGpgHome = 0x0112,
   146         pEpInitNetpgpInitFailed = 0x0113,
   147         pEpInitCannotDetermineGpgVersion = 0x0114,
   148         pEpInitUnsupportedGpgVersion = 0x0115,
   149         pEpInitCannotConfigGpgAgent = 0x0116,
   150 
   151         pEpInitSqlite3WithoutMutex = 0x0120,
   152         pEpInitCannotOpenDb = 0x0121,
   153         pEpInitCannotOpenSystemDb = 0x0122,
   154 
   155         pEpKeyNotFound = 0x0201,
   156         pEpKeyHasAmbigName = 0x0202,
   157         pEpGetKeyFailed = 0x0203,
   158         pEpCannotExportKey = 0x0204,
   159         pEpCannotEditKey = 0x0205,
   160         pEpKeyUnsuitable = 0x0206,
   161 
   162         pEpCannotFindIdentity = 0x0301,
   163         pEpCannotSetPerson = 0x0381,
   164         pEpCannotSetPgpKeypair = 0x0382,
   165         pEpCannotSetIdentity = 0x0383,
   166         pEpCannotSetTrust = 0x0384,
   167         pEpKeyBlacklisted = 0x0385,
   168         pEpCannotFindPerson = 0x0386,
   169 
   170         pEpCannotFindAlias = 0x0391,
   171         pEpCannotSetAlias = 0x0392,
   172 
   173         pEpUnencrypted = 0x0400,
   174         pEpVerified = 0x0401,
   175         pEpDecrypted = 0x0402,
   176         pEpDecryptedAndVerified = 0x0403,
   177         pEpDecryptWrongFormat = 0x0404,
   178         pEpDecryptNoKey = 0x0405,
   179         pEpDecryptSignatureDoesNotMatch = 0x0406,
   180         pEpVerifyNoKey = 0x0407,
   181         pEpVerifiedAndTrusted = 0x0408,
   182         pEpCannotDecryptUnknown = 0x04ff,
   183 
   184         pEpTrustwordNotFound = 0x0501,
   185         pEpTrustwordsFprWrongLength = 0x0502,
   186         pEpTrustwordsDuplicateFpr = 0x0503,
   187 
   188         pEpCannotCreateKey = 0x0601,
   189         pEpCannotSendKey = 0x0602,
   190 
   191         pEpPhraseNotFound = 0x0701,
   192 
   193         pEpSendFunctionNotRegistered = 0x0801,
   194         pEpContraintsViolated = 0x0802,
   195         pEpCannotEncode = 0x0803,
   196 
   197         pEpSyncNoNotifyCallback = 0x0901,
   198         pEpSyncIllegalMessage = 0x0902,
   199         pEpSyncNoInjectCallback = 0x0903,
   200 
   201         pEpSequenceViolated = 0x0970,
   202         pEpCannotIncreaseSequence = 0x0971,
   203         pEpCannotSetSequenceValue = 0x0972,
   204         pEpOwnSequence = 0x097f,
   205 
   206         pEpSyncStatemachineError = 0x0980,
   207         pEpSyncNoTrust = 0x0981,
   208         pEpStatemachineInvalidState = 0x0982,
   209         pEpStatemachineInvalidEvent = 0x0983,
   210         pEpStatemachineInvalidCondition = 0x0984,
   211         pEpStatemachineInvalidAction = 0x0985,
   212         pEpStatemachineInhibitedEvent = 0x0986,
   213 
   214         pEpCommitFailed = 0xff01,
   215         pEpMessageConsume = 0xff02,
   216         pEpMessageIgnore = 0xff03,
   217 
   218         pEpRecordNotFound = -6,
   219         pEpCannotCreateTempFile = -5,
   220         pEpIllegalValue = -4,
   221         pEpBufferTooSmall = -3,
   222         pEpOutOfMemory = -2,
   223         pEpUnknownError = -1,
   224 
   225         pEpVersionMismatch = -7,
   226     } pEpStatus;
   227 
   228     typedef [v1_enum] enum pEpIdentityFlags {
   229         pEpIdfNone = 0,
   230         pEpIdfNotForSync = 0x0001,
   231         pEpIdfList = 0x0002,
   232         pEpIdfDevicegroup = 0x0100
   233     } pEpIdentityFlags;
   234 
   235     [uuid(C3A3814E-567F-4D1C-9F44-9B1DA3957A89)] struct pEpIdentity {
   236         BSTR Address;
   237         BSTR Fpr;
   238         BSTR UserId;
   239         BSTR UserName;
   240         pEpComType CommType;
   241         BSTR Lang;
   242         pEpIdentityFlags Flags;
   243     };
   244 
   245     [id(11)] HRESULT SetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);
   246     [id(12)] HRESULT UnsetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);
   247 
   248     // Keymanagement API
   249 
   250     [id(13)] HRESULT StartKeyserverLookup();
   251     [id(14)] HRESULT StopKeyserverLookup();
   252 
   253     [id(15)] HRESULT Myself([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   254     [id(16)] HRESULT UpdateIdentity([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   255     [id(17)] HRESULT KeyMistrusted([in] struct pEpIdentity *ident);
   256     [id(18)] HRESULT KeyResetTrust([in] struct pEpIdentity *ident);
   257     [id(19)] HRESULT TrustPersonalKey([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   258     [id(20)] HRESULT OwnIdentitiesRetrieve([out, retval] SAFEARRAY(struct pEpIdentity)* ownIdentities);
   259     [id(21)] HRESULT UndoLastMistrust();
   260     [id(22)] HRESULT IsPepUser([in] struct pEpIdentity *ident, [out, retval] VARIANT_BOOL *ispEp);
   261 
   262     // Blacklist API
   263 
   264     [id(23)] HRESULT BlacklistAdd([in] BSTR fpr);
   265     [id(24)] HRESULT BlacklistDelete([in] BSTR fpr);
   266     [id(25)] HRESULT BlacklistIsListed([in] BSTR fpr, [out, retval] VARIANT_BOOL *listed);
   267     [id(26)] HRESULT BlacklistRetrieve([out, retval] SAFEARRAY(BSTR) *blacklist);
   268 
   269     // PGP compatibility functions
   270 
   271     [id(27)] HRESULT OpenPGPListKeyinfo([in] BSTR searchPattern, [out, retval] SAFEARRAY(struct StringPair)* keyinfoList);
   272 
   273     // Message API
   274 
   275     typedef [v1_enum] enum pEpRating {
   276         pEpRatingUndefined = 0,
   277         pEpRatingCannotDecrypt,
   278         pEpRatingHaveNoKey,
   279         pEpRatingUnencrypted,
   280         pEpRatingUnencryptedForSome,
   281         pEpRatingUnreliable,
   282         pEpRatingReliable,
   283         pEpRatingTrusted,
   284         pEpRatingTrustedAndAnonymized,
   285         pEpRatingFullyAnonymous,
   286 
   287         pEpRatingMistrust = -1,
   288         pEpRatingB0rken = -2,
   289         pEpRatingUnderAttack = -3
   290     } pEpRating;
   291 
   292     typedef [v1_enum] enum pEpColor {
   293         pEpColorNoColor = 0,
   294         pEpColorYellow,
   295         pEpColorGreen,
   296         pEpColorRed = -1,
   297     } pEpColor;
   298 
   299     typedef [v1_enum] enum pEpEncryptFlags {
   300         pEpEncryptFlagDefault = 0,
   301         pEpEncryptFlagForceEncryption = 0x1,
   302 
   303         // This flag is for special uses and should not be used
   304         // by normal pEp clients!
   305         pEpEncryptFlagForceUnsigned = 0x2,
   306 
   307         // This flag is for special uses and should not be used
   308         // by normal pEp clients!
   309         pEpEncryptFlagForceNoAttachedKey = 0x4,
   310 
   311     } pEpEncryptFlags;
   312 
   313     typedef [v1_enum] enum pEpDecryptFlags {
   314         pEpDecryptFlagsNone = 0,
   315         pEpDecryptFlagOwnPrivateKey = 0x1,
   316         pEpDecryptFlagConsume = 0x2,
   317         pEpDecryptFlagIgnore = 0x4,
   318 		pEpDecryptFlagSrcModified = 0x8,
   319 		pEpDecryptFlagUntrustedServer = 0x100
   320     } pEpDecryptFlags;
   321 
   322     typedef [v1_enum] enum pEpMsgDirection {
   323         pEpDirIncoming = 0,
   324         pEpDirOutgoing
   325     } pEpMsgDirection;
   326 
   327     typedef [v1_enum] enum pEpEncFormat {
   328         pEpEncNone = 0,                       // message is not encrypted
   329         pEpEncPieces,                         // inline PGP + PGP extensions
   330         pEpEncSMime,                          // RFC5751
   331         pEpEncPgpMime,                        // RFC3156
   332         pEpEncPep,                            // pEp encryption format
   333         pEpEncPgpMimeOutlook1                 // Message B0rken by Outlook type 1
   334     } pEpEncFormat;
   335 
   336     [uuid(47FB0795-6B64-455C-BB0E-54998CAB8ACB)] struct StringPair {
   337         BSTR Name;
   338         BSTR Value;
   339     };
   340 
   341     [uuid(634EB7CE-99AA-460D-BDF8-F7CDA7232CA6)] struct Blob {
   342         SAFEARRAY(BYTE) value;
   343         BSTR MimeType;
   344         BSTR Filename;
   345     };
   346 
   347     [uuid(B6F40887-E761-4A47-B204-A0193EE0284D)] struct TextMessage {
   348         pEpMsgDirection Dir;
   349         BSTR Id;
   350         BSTR ShortMsg;
   351         BSTR LongMsg;
   352         BSTR LongMsgFormatted;
   353         SAFEARRAY(struct Blob) Attachments;
   354         hyper Sent; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
   355         hyper Recv; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
   356         struct pEpIdentity From;
   357         SAFEARRAY(struct pEpIdentity) To;
   358         struct pEpIdentity RecvBy;
   359         SAFEARRAY(struct pEpIdentity) Cc;
   360         SAFEARRAY(struct pEpIdentity) Bcc;
   361         SAFEARRAY(struct pEpIdentity) ReplyTo;
   362         SAFEARRAY(BSTR) References;
   363         SAFEARRAY(BSTR) Keywords;
   364         BSTR Comments;
   365         SAFEARRAY(struct StringPair) OptFields;
   366     };
   367 
   368     [id(28)] HRESULT EncryptMessage(
   369         [in,out] struct TextMessage *src,
   370         [out] struct TextMessage * dst,
   371         [in] SAFEARRAY(BSTR) extra,
   372         [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags,
   373         // Use pEpEncFormat.pEpEncNone for unencrypted, outgoing messages.
   374         // Default is pEpEncFormat.pEpEncPep, all other formats are only 
   375         // for compatibility and not intended for normal use.
   376         [in, defaultvalue(pEpEncPep)] pEpEncFormat encFormat);
   377 
   378     [id(29)] HRESULT DecryptMessage(
   379         [in, out] struct TextMessage *src,
   380         [out] struct TextMessage * dst,
   381         [out] SAFEARRAY(BSTR) *keylist,
   382         [in, out] pEpDecryptFlags* flags,
   383         [out, retval] pEpRating *rating);
   384 
   385     [id(30)] HRESULT OutgoingMessageRating([in] struct TextMessage *msg, [out, retval] pEpRating * pVal);
   386     [id(31)] HRESULT IdentityRating([in] struct pEpIdentity * ident, [out, retval] pEpRating * pVal);
   387     [id(32)] HRESULT ColorFromRating([in] pEpRating rating, [out, retval] pEpColor* pVal);
   388 
   389     [id(33)] HRESULT GetMessageTrustwords(
   390         [in] struct TextMessage *msg,
   391         [in] struct pEpIdentity * receivedBy,
   392         [in] SAFEARRAY(BSTR) keylist,
   393         [in, defaultvalue("en")] BSTR lang,
   394         [in, defaultvalue(0)] VARIANT_BOOL full,
   395         [out, retval] BSTR * words
   396     );
   397 
   398     [id(34)] HRESULT EncryptMessageForSelf(
   399         [in] struct pEpIdentity* targetId,
   400         [in] struct TextMessage* src,
   401         [in] SAFEARRAY(BSTR) extra, // Fingerprints for extra keys for encryption.
   402         [out] struct TextMessage* dst,
   403         [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags
   404     );
   405 
   406     [id(35)] HRESULT ReEvaluateMessageRating(
   407         [in] struct TextMessage *src,
   408         [in] SAFEARRAY(BSTR) x_KeyList, // referring to X-KeyList mail header
   409         [in] pEpRating x_EncStatus, // referring to X-EncStatus mail header
   410         [out, retval] pEpRating *rating
   411     );
   412 
   413     // callback / keysync API
   414     [id(36)] HRESULT RegisterCallbacks([in] IpEpEngineCallbacks* newCallback);
   415     [id(37)] HRESULT UnregisterCallbacks();
   416 
   417 	// mark imported keys as trusted
   418 
   419 	[id(38)] HRESULT SetOwnKey(
   420 		[in] struct pEpIdentity * ident,
   421 		[in] BSTR fpr,
   422 		[out, retval] struct pEpIdentity * result
   423 	);
   424 
   425     [id(39)] HRESULT EncryptMessageAndAddPrivKey(
   426         [in] struct TextMessage *src,
   427         [out] struct TextMessage * dst,
   428         [in] BSTR to_fpr,
   429         [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags,
   430         // Use pEpEncFormat.pEpEncNone for unencrypted, outgoing messages.
   431         // Default is pEpEncFormat.pEpEncPep, all other formats are only 
   432         // for compatibility and not intended for normal use.
   433         [in, defaultvalue(pEpEncPep)] pEpEncFormat encFormat);
   434 
   435     // Trigger an immediate update check.
   436     [id(40)] HRESULT UpdateNow();
   437 };
   438 
   439 [
   440     uuid(564A4350-419E-47F1-B0DF-6FCCF0CD0BBC),
   441     version(1.0),
   442 ]
   443 library pEpCOMServerAdapterLib
   444 {
   445     importlib("stdole2.tlb");
   446 
   447     [
   448         uuid(5FF6682B-727B-4DFE-A68D-28982874C0C7)
   449     ]
   450     coclass pEpEngine {
   451         [default] interface IpEpEngine;
   452         interface IpEpEngineCallbacks;
   453     };
   454 };