summaryrefslogtreecommitdiffstats
path: root/toolkit/components/contentanalysis/nsIContentAnalysis.idl
blob: 63ac8d12fbfe4994531b96bf9b149e72089ea5b1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
/* -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 8 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIURI;
webidl WindowGlobalParent;

[scriptable, uuid(06e6a60f-3a2b-41fa-a63b-fea7a7f71649)]
interface nsIContentAnalysisAcknowledgement : nsISupports
{
  // These values must stay synchronized with ContentAnalysisAcknowledgement
  // in analysis.proto!
  // Acknowledgement of analysis response.
  cenum Result: 32 {
    eSuccess = 1, // The response was handled as specified by the agent.
    eInvalidResponse = 2, // The response from the agent was not properly formatted.
    eTooLate = 3, // The response from the agent was too late.
  };

  readonly attribute nsIContentAnalysisAcknowledgement_Result result;

  // These values must stay synchronized with ContentAnalysisAcknowledgement
  // in analysis.proto!
  // The final action that the browser took with this request.
  cenum FinalAction : 32 {
    eUnspecified = 0,
    eAllow = 1,
    eReportOnly = 2,
    eWarn = 3,
    eBlock = 4,
  };

  readonly attribute nsIContentAnalysisAcknowledgement_FinalAction finalAction;
};

[scriptable, uuid(89088c61-15f6-4ace-a880-a1b5ea47ca66)]
interface nsIContentAnalysisResponse : nsISupports
{
  // These values must stay synchronized with ContentAnalysisResponse
  // in analysis.proto!
  // Action requested in response to a successful analysis.
  cenum Action : 32 {
    eUnspecified = 0,
    eReportOnly = 1,
    eWarn = 2,
    eBlock = 3,
    // Values that do not appear in analysis.proto
    eAllow = 1000,
    eCanceled = 1001,
  };

  cenum CancelError : 32 {
    eUserInitiated = 0,
    eNoAgent = 1,
    eInvalidAgentSignature = 2,
    eErrorOther = 3,
  };

  readonly attribute nsIContentAnalysisResponse_Action action;
  readonly attribute boolean shouldAllowContent;
  // If action is eCanceled, this is the error explaining why the request was canceled,
  // or eUserInitiated if the user canceled it.
  readonly attribute nsIContentAnalysisResponse_CancelError cancelError;

  // Identifier for the corresponding nsIContentAnalysisRequest
  readonly attribute ACString requestToken;

  /**
   * Acknowledge receipt of an analysis response.
   * If false is passed for aAutoAcknowledge to AnalyzeContentRequest,
   * the caller is responsible for calling this after successful
   * resolution of the promise.
   */
  void acknowledge(in nsIContentAnalysisAcknowledgement aCaa);
};

[scriptable, uuid(48d31df1-204d-42ce-a57f-f156bb870d89)]
interface nsIClientDownloadResource : nsISupports
{
  readonly attribute AString url;

  // These values must stay synchronized with ClientDownloadResource
  // in analysis.proto!
  // The final URL of the download payload.  The resource URL should
  // correspond to the URL field above.
  const unsigned long DOWNLOAD_URL = 0;
  // A redirect URL that was fetched before hitting the final DOWNLOAD_URL.
  const unsigned long DOWNLOAD_REDIRECT = 1;
  // The final top-level URL of the tab that triggered the download.
  const unsigned long TAB_URL = 2;
  // A redirect URL thas was fetched before hitting the final TAB_URL.
  const unsigned long TAB_REDIRECT = 3;
  // The document URL for a PPAPI plugin instance that initiated the download.
  // This is the document.url for the container element for the plugin
  // instance.
  const unsigned long PPAPI_DOCUMENT = 4;
  // The plugin URL for a PPAPI plugin instance that initiated the download.
  const unsigned long PPAPI_PLUGIN = 5;

  readonly attribute unsigned long type;
};

/**
 * A nsIContentAnalysisRequest represents a request that the browser
 * consult any required content analysis resources (like external data-loss
 * prevention applications) to determine if the attempted operation should
 * be permitted to complete.
 */
[scriptable, uuid(c11a6636-da2a-4afc-bdd1-0bcae2310e6d)]
interface nsIContentAnalysisRequest : nsISupports
{
  // These values must stay synchronized with ContentAnalysisRequest
  // in analysis.proto!
  // Type of analysis being requested.
  // For meaning, see analysis.proto in the content analysis module.
  cenum AnalysisType : 32 {
    eUnspecified = 0,
    eFileDownloaded = 1,
    eFileAttached = 2,
    eBulkDataEntry = 3,
    ePrint = 4,
    eFileTransfer = 5,
  };
  readonly attribute nsIContentAnalysisRequest_AnalysisType analysisType;

  // Enumeration of what operation is happening, to be displayed to the user
  cenum OperationType : 32 {
    eCustomDisplayString = 0,
    eClipboard = 1,
    eDroppedText = 2,
    eOperationPrint = 3,
  };
  readonly attribute nsIContentAnalysisRequest_OperationType operationTypeForDisplay;
  readonly attribute AString operationDisplayString;

  // Text content to analyze.  Only one of textContent or filePath is defined.
  readonly attribute AString textContent;

  // Name of file to analyze.  Only one of textContent or filePath is defined.
  readonly attribute AString filePath;

  // HANDLE to the printed data in PDF format.
  readonly attribute unsigned long long printDataHandle;

  // Size of the data stored in printDataHandle.
  readonly attribute unsigned long long printDataSize;

  // Name of the printer being printed to.
  readonly attribute AString printerName;

  // The URL containing the file download/upload or to which web content is
  // being uploaded.
  readonly attribute nsIURI url;

  // Sha256 digest of file. Callers may pass in an empty string to have the
  // content analysis code calculate this.
  readonly attribute ACString sha256Digest;

  // URLs involved in the download (empty for non-downloads).
  readonly attribute Array<nsIClientDownloadResource> resources;

  // Email address of user.
  readonly attribute AString email;

  // Unique identifier for this request
  readonly attribute ACString requestToken;

  // The window associated with this request
  readonly attribute WindowGlobalParent windowGlobalParent;
};

[scriptable, builtinclass, uuid(9679545f-4256-4c90-9654-90292c355d25)]
interface nsIContentAnalysisResult : nsISupports
{
  [infallible] readonly attribute boolean shouldAllowContent;
};

[scriptable, uuid(cb09fc88-118c-411b-aa89-2e1bc5e3eba6)]
interface nsIContentAnalysisCallback : nsISupports
{
  void contentResult(in nsIContentAnalysisResponse aResult);

  void error(in nsresult aResult);
};

[scriptable, builtinclass, uuid(a430f6ef-a526-4055-8a82-7741ea757367)]
interface nsIContentAnalysisDiagnosticInfo : nsISupports
{
  [infallible] readonly attribute boolean connectedToAgent;
  readonly attribute AString agentPath;
  [infallible] readonly attribute boolean failedSignatureVerification;
  [infallible] readonly attribute long long requestCount;
};

[scriptable, uuid(61497587-2bba-4a88-acd3-3fbb2cedf163)]
interface nsIContentAnalysis : nsISupports
{
  /**
   * True if content analysis should be consulted. Must only be accessed from
   * the parent process's main thread.
   */
  readonly attribute boolean isActive;

  /**
   * True if content analysis might be active, and False if content analysis
   * is definitely not active. Reading this property is guaranteed
   * to work from a content process, and can be used to avoid having to call
   * into the parent process to determine whether content analysis is actually
   * active.
   */
  readonly attribute boolean mightBeActive;

  /**
   * True if content-analysis activation was determined by enterprise policy,
   * as opposed to enabled with the `allow-content-analysis` command-line
   * parameter.
   */
  attribute boolean isSetByEnterprisePolicy;

  /**
   * Consults content analysis server, if any, to request a permission
   * decision for a network operation.  Allows blocking downloading/
   * uploading/printing/etc, based on the request.
   * Consultation with the content analysis tool follows the conventional
   * request, response, acknowledgement protocol.
   *
   * The resulting Promise resolves to a nsIContentAnalysisResponse,
   * which may take some time to get from the analysis server.  It will
   * be rejected, with an string error description, if any error occurs.
   *
   * @param aCar
   *        The request to analyze.
   * @param aAutoAcknowledge
   *        Whether to send an acknowledge message to the agent after the agent sends a response.
   *        Passing false means that the caller is responsible for
   *        calling nsIContentAnalysisResponse::acknowledge() if the Promise is resolved.
   */
  [implicit_jscontext]
  Promise analyzeContentRequest(in nsIContentAnalysisRequest aCar, in boolean aAutoAcknowledge);

  /**
   * Same functionality as AnalyzeContentRequest(), but more convenient to call
   * from C++ since it takes a callback instead of returning a Promise.
   *
   * @param aCar
   *        The request to analyze.
   * @param aAutoAcknowledge
   *        Whether to send an acknowledge message to the agent after the agent sends a response.
   *        Passing false means that the caller is responsible for
   *        calling nsIContentAnalysisResponse::acknowledge() if nsIContentAnalysisCallback::contentResult()
   *        is called.
   * @param callback
   *        Callbacks to be called when the agent sends a response message (or when there is an error).
   */
  void analyzeContentRequestCallback(in nsIContentAnalysisRequest aCar, in boolean aAutoAcknowledge, in nsIContentAnalysisCallback callback);

  /**
   * Cancels the request that is in progress. This may not actually cancel the request
   * with the analysis server, but it means that Gecko will immediately act like the request
   * was denied.
   *
   * @param aRequestToken
   *        The token for the request to cancel.
   */
  void cancelContentAnalysisRequest(in ACString aRequestToken);

  /**
   * Indicates that the user has responded to a WARN dialog. aAllowContent represents
   * whether the user wants to allow the request to go through.
   */
  void respondToWarnDialog(in ACString aRequestToken, in boolean aAllowContent);

  /**
   * Cancels all outstanding DLP requests. Used on shutdown.
   */
  void cancelAllRequests();

  /**
   * Test-only function that pretends that "-allow-content-analysis" was
   * given to Gecko on the command line.
   */
  void testOnlySetCACmdLineArg(in boolean aVal);

  /**
   * Gets diagnostic information about content analysis. Returns a
   * nsIContentAnalysisDiagnosticInfo via the returned promise.
   */
  [implicit_jscontext]
  Promise getDiagnosticInfo();
};