pEpCOMServerAdapter.idl
author Markus Schaber <markus@pep-security.net>
Wed, 07 Feb 2018 18:53:25 +0100
branchCOM-74
changeset 270 c713a265866f
parent 267 ae02fcd56811
child 271 92866cd8b0c4
permissions -rw-r--r--
COM-74: Expose _PEP_enc_format to app for EncryptMessage

Remove obsolete (and now wrong) assertion of fpr != null
     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     [id(2)] HRESULT NotifyHandshake([in] struct pEpIdentity * self, [in] struct pEpIdentity * partner, [in] SyncHandshakeSignal signal, [out, retval] SyncHandshakeResult * result);
    47 };
    48 
    49 [
    50     object,
    51     uuid(64E964B2-880A-4E92-B0B5-66FF4286A3B3),
    52     oleautomation,
    53     nonextensible,
    54     pointer_default(unique)
    55 ]
    56 interface IpEpEngineCallbacks2 : IpEpEngineCallbacks 
    57 {
    58     [id(3)] HRESULT NeedFastPolling([in] VARIANT_BOOL enableFastPolling);
    59 };
    60 
    61 [
    62     object,
    63     uuid(045E49AF-0975-4876-A53B-8CA5AB28C0F8),
    64     oleautomation,
    65     nonextensible,
    66     pointer_default(unique)
    67 ]
    68 interface IpEpEngine : IUnknown {
    69 
    70     // runtime config of the adapter
    71 
    72     HRESULT VerboseLogging([in] VARIANT_BOOL enable);
    73 
    74     // runtime config of the engine
    75 
    76     HRESULT PassiveMode([in] VARIANT_BOOL enable);
    77     HRESULT UnencryptedSubject([in] VARIANT_BOOL enable);
    78 
    79     // basic API
    80 
    81     HRESULT ExportKey([in] BSTR fpr, [out, retval] BSTR * keyData);
    82     HRESULT Log([in] BSTR title, [in] BSTR entity, [in, defaultvalue("")] BSTR description, [in, defaultvalue("")] BSTR comment);
    83     HRESULT Trustwords([in] BSTR fpr, [in, defaultvalue("en")] BSTR lang, [in, defaultvalue(0)] LONG maxWords, [out, retval] BSTR * words);
    84     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);
    85     HRESULT GetCrashdumpLog([in, defaultvalue(0)] LONG maxlines, [out, retval] BSTR * log);
    86     HRESULT GetEngineVersion([out, retval] BSTR * engineVersion);
    87     HRESULT GetLanguageList([out, retval] BSTR * languages);
    88 
    89     typedef [v1_enum] enum pEpComType {
    90         pEpCtUnknown = 0,
    91 
    92         // range 0x01 to 0x09: no encryption, 0x0a to 0x0e: nothing reasonable
    93 
    94         pEpCtNoEncryption = 0x01,                // generic
    95         pEpCtNoEncryptedChannel = 0x02,
    96         pEpCtKeyNotFound = 0x03,
    97         pEpCtKeyExpired = 0x04,
    98         pEpCtKeyRevoked = 0x05,
    99         pEpCtKeyB0rken = 0x06,
   100         pEpCtMyKeyNotIncluded = 0x09,
   101 
   102         pEpCtSecurityByObscurity = 0x0a,
   103         pEpCtB0rkenCrypto = 0x0b,
   104         pEpCtKeyTooShort = 0x0c,
   105 
   106         pEpCtCompromised = 0x0e,                 // known compromized connection
   107         pEpCtMistrusted = 0x0f,                  // known mistrusted key
   108 
   109         // range 0x10 to 0x3f: unconfirmed encryption
   110 
   111         pEpCtUnconfirmedEncryption = 0x10,       // generic
   112         pEpCtOpenPGPWeakUnconfirmed = 0x11,      // RSA 1024 is weak
   113 
   114         pEpCtToBeChecked = 0x20,                 // generic
   115         pEpCtSMIMEUnconfirmed = 0x21,
   116         pEpCtCMSUnconfirmed = 0x22,
   117 
   118         pEpCtStrongButUnconfirmed = 0x30,        // generic
   119         pEpCtOpenPGPUnconfirmed = 0x38,          // key at least 2048 bit RSA or EC
   120         pEpCtOTRUnconfirmed = 0x3a,
   121 
   122         // range 0x40 to 0x7f: unconfirmed encryption and anonymization
   123 
   124         pEpCtUnconfirmedEncAnon = 0x40,          // generic
   125         pEpCtpEpUnconfirmed = 0x7f,
   126 
   127         pEpCtConfirmed = 0x80,                   // this bit decides if trust is confirmed
   128 
   129         // range 0x81 to 0x8f: reserved
   130         // range 0x90 to 0xbf: confirmed encryption
   131 
   132         pEpCtConfirmedEncryption = 0x90,         // generic
   133         pEpCtOpenPGPWeak = 0x91,                 // RSA 1024 is weak
   134 
   135         pEpCtToBeCheckedConfirmed = 0xa0,        // generic
   136         pEpCtSMIME = 0xa1,
   137         pEpCtCMS = 0xa2,
   138 
   139         pEpCtStrongEncryption = 0xb0,            // generic
   140         pEpCtOpenPGP = 0xb8,                     // key at least 2048 bit RSA or EC
   141         pEpCtOTR = 0xba,
   142 
   143         // range 0xc0 to 0xff: confirmed encryption and anonymization
   144 
   145         pEpCtConfirmedEncAnon = 0xc0,            // generic
   146         pEpCtpEp = 0xff
   147     } pEpComType;
   148 
   149     typedef [v1_enum] enum pEpIdentityFlags {
   150         pEpIdfNone = 0,
   151         pEpIdfNotForSync = 0x0001,
   152         pEpIdfList = 0x0002,
   153         pEpIdfDevicegroup = 0x0100
   154     } pEpIdentityFlags;
   155 
   156     [uuid(C3A3814E-567F-4D1C-9F44-9B1DA3957A89)] struct pEpIdentity {
   157         BSTR Address;
   158         BSTR Fpr;
   159         BSTR UserId;
   160         BSTR UserName;
   161         pEpComType CommType;
   162         BSTR Lang;
   163         pEpIdentityFlags Flags;
   164     };
   165 
   166     HRESULT SetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);
   167     HRESULT UnsetIdentityFlags([in] struct pEpIdentity *identity, [in] pEpIdentityFlags flags);
   168 
   169     // Keymanagement API
   170 
   171     HRESULT StartKeyserverLookup();
   172     HRESULT StopKeyserverLookup();
   173 
   174     HRESULT Myself([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   175     HRESULT UpdateIdentity([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   176     HRESULT KeyMistrusted([in] struct pEpIdentity *ident);
   177     HRESULT KeyResetTrust([in] struct pEpIdentity *ident);
   178     HRESULT TrustPersonalKey([in] struct pEpIdentity *ident, [out, retval] struct pEpIdentity *result);
   179     HRESULT OwnIdentitiesRetrieve([out, retval] SAFEARRAY(struct pEpIdentity)* ownIdentities);
   180 
   181     // Blacklist API
   182 
   183     HRESULT BlacklistAdd([in] BSTR fpr);
   184     HRESULT BlacklistDelete([in] BSTR fpr);
   185     HRESULT BlacklistIsListed([in] BSTR fpr, [out, retval] VARIANT_BOOL *listed);
   186     HRESULT BlacklistRetrieve([out, retval] SAFEARRAY(BSTR) *blacklist);
   187 
   188     // PGP compatibility functions
   189 
   190     HRESULT OpenPGPListKeyinfo([in] BSTR searchPattern, [out, retval] SAFEARRAY(struct StringPair)* keyinfoList);
   191 
   192     // Message API
   193 
   194     typedef [v1_enum] enum pEpRating {
   195         pEpRatingUndefined = 0,
   196         pEpRatingCannotDecrypt,
   197         pEpRatingHaveNoKey,
   198         pEpRatingUnencrypted,
   199         pEpRatingUnencryptedForSome,
   200         pEpRatingUnreliable,
   201         pEpRatingReliable,
   202         pEpRatingTrusted,
   203         pEpRatingTrustedAndAnonymized,
   204         pEpRatingFullyAnonymous,
   205 
   206         pEpRatingMistrust = -1,
   207         pEpRatingB0rken = -2,
   208         pEpRatingUnderAttack = -3
   209     } pEpRating;
   210 
   211     typedef [v1_enum] enum pEpColor {
   212         pEpColorNoColor = 0,
   213         pEpColorYellow,
   214         pEpColorGreen,
   215         pEpColorRed = -1,
   216     } pEpColor;
   217 
   218     typedef [v1_enum] enum pEpEncryptFlags {
   219         pEpEncryptFlagDefault = 0,
   220         pEpEncryptFlagForceEncryption = 0x1,
   221 
   222         // This flag is for special uses and should not be used
   223         // by normal pEp clients!
   224         pEpEncryptFlagForceUnsigned = 0x2,
   225 
   226         // This flag is for special uses and should not be used
   227         // by normal pEp clients!
   228         pEpEncryptFlagForceNoAttachedKey = 0x4,
   229 
   230     } pEpEncryptFlags;
   231 
   232     typedef [v1_enum] enum pEpDecryptFlags {
   233         pEpDecryptFlagsNone = 0,
   234         pEpDecryptFlagOwnPrivateKey = 0x1,
   235         pEpDecryptFlagConsume = 0x2,
   236         pEpDecryptFlagIgnore = 0x4
   237     } pEpDecryptFlags;
   238 
   239     typedef [v1_enum] enum pEpMsgDirection {
   240         pEpDirIncoming = 0,
   241         pEpDirOutgoing
   242     } pEpMsgDirection;
   243 
   244     [uuid(47FB0795-6B64-455C-BB0E-54998CAB8ACB)] struct StringPair {
   245         BSTR Name;
   246         BSTR Value;
   247     };
   248 
   249     [uuid(634EB7CE-99AA-460D-BDF8-F7CDA7232CA6)] struct Blob {
   250         SAFEARRAY(BYTE) value;
   251         BSTR MimeType;
   252         BSTR Filename;
   253     };
   254 
   255     [uuid(B6F40887-E761-4A47-B204-A0193EE0284D)] struct TextMessage {
   256         pEpMsgDirection Dir;
   257         BSTR Id;
   258         BSTR ShortMsg;
   259         BSTR LongMsg;
   260         BSTR LongMsgFormatted;
   261         SAFEARRAY(struct Blob) Attachments;
   262         hyper Sent; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
   263         hyper Recv; // Timestamp: 64 Bit time_t from mktime(), seconds since January 1, 1970, 0:00 UTC.
   264         struct pEpIdentity From;
   265         SAFEARRAY(struct pEpIdentity) To;
   266         struct pEpIdentity RecvBy;
   267         SAFEARRAY(struct pEpIdentity) Cc;
   268         SAFEARRAY(struct pEpIdentity) Bcc;
   269         SAFEARRAY(struct pEpIdentity) ReplyTo;
   270         SAFEARRAY(BSTR) References;
   271         SAFEARRAY(BSTR) Keywords;
   272         BSTR Comments;
   273         SAFEARRAY(struct StringPair) OptFields;
   274     };
   275 
   276     HRESULT EncryptMessage(
   277         [in] struct TextMessage *src,
   278         [out] struct TextMessage * dst,
   279         [in] SAFEARRAY(BSTR) extra,
   280         [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags);
   281 
   282     HRESULT DecryptMessage(
   283         [in] struct TextMessage *src,
   284         [out] struct TextMessage * dst,
   285         [out] SAFEARRAY(BSTR) *keylist,
   286         [out] pEpDecryptFlags* flags,
   287         [out, retval] pEpRating *rating);
   288 
   289     HRESULT OutgoingMessageRating([in] struct TextMessage *msg, [out, retval] pEpRating * pVal);
   290     HRESULT IdentityRating([in] struct pEpIdentity * ident, [out, retval] pEpRating * pVal);
   291     HRESULT ColorFromRating([in] pEpRating rating, [out, retval] pEpColor* pVal);
   292 
   293     // callback / keysync API
   294     HRESULT RegisterCallbacks([in] IpEpEngineCallbacks* newCallback);
   295     HRESULT UnregisterCallbacks();
   296 };
   297 
   298 [
   299     object,
   300     uuid(8A042123-D433-4DEA-ADA2-2E5E61A00292),
   301     oleautomation,
   302     nonextensible,
   303     pointer_default(unique)
   304 ]
   305 interface IpEpEngine2 : IpEpEngine
   306 {
   307     typedef [v1_enum] enum pEpEncFormat {
   308         pEpEncNone = 0,                       // message is not encrypted
   309         pEpEncPieces,                         // inline PGP + PGP extensions
   310         pEpEncSMime,                          // RFC5751
   311         pEpEncPgpMime,                        // RFC3156
   312         pEpEncPep,                            // pEp encryption format
   313         pEpEncPgpMimeOutlook1                 // Message B0rken by Outlook type 1
   314     } pEpEncFormat;
   315 
   316     HRESULT GetMessageTrustwords(
   317         [in] struct TextMessage *msg,
   318         [in] struct pEpIdentity * receivedBy,
   319         [in] SAFEARRAY(BSTR) keylist,
   320         [in, defaultvalue("en")] BSTR lang,
   321         [in, defaultvalue(0)] VARIANT_BOOL full,
   322         [out, retval] BSTR * words
   323     );
   324 
   325     HRESULT EncryptMessageForSelf(
   326         [in] struct pEpIdentity* targetId,
   327         [in] struct TextMessage* src, 
   328         [out] struct TextMessage* dst,
   329         [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags
   330     );
   331 
   332     HRESULT ReEvaluateMessageRating(
   333         [in] struct TextMessage *src,
   334         [in] SAFEARRAY(BSTR) x_KeyList, // referring to X-KeyList mail header
   335         [in] pEpRating x_EncStatus, // referring to X-EncStatus mail header
   336         [out, retval] pEpRating *rating
   337     );
   338 
   339     HRESULT UndoLastMistrust();
   340 
   341     HRESULT EncryptMessage2(
   342         [in] struct TextMessage *src,
   343         [out] struct TextMessage * dst,
   344         [in] SAFEARRAY(BSTR) extra,
   345         [in, defaultvalue(pEpEncryptFlagDefault)] pEpEncryptFlags flags,
   346         // Use pEpEncFormat.pEpEncNone for unencrypted, outgoing messages.
   347         // Default is pEpEncFormat.pEpEncPep, all other formats are only 
   348         // for compatibility and not intended for normal use.
   349         [in, defaultvalue(pEpEncPep)] pEpEncFormat encFormat);
   350 };
   351 
   352 [
   353     uuid(564A4350-419E-47F1-B0DF-6FCCF0CD0BBC),
   354     version(1.0),
   355 ]
   356 library pEpCOMServerAdapterLib
   357 {
   358     importlib("stdole2.tlb");
   359 
   360     [
   361         uuid(5FF6682B-727B-4DFE-A68D-28982874C0C7)
   362     ]
   363     coclass pEpEngine {
   364         [default] interface IpEpEngine2;
   365         interface IpEpEngine;
   366         interface IpEpEngineCallbacks2;
   367     };
   368 };