Lawful Intercept: Management API

Dovecot Pro's Lawful Intercept system provides a generic management API for interception-related services.

Currently, this API is only used by utimaco.

Configuration Options

intercept_api_utimaco_sql_query_surveillance

Default	SELECT uuid, UNIX_TIMESTAMP(created) AS created FROM targets WHERE userid_hash = '%{user | md5 | hexlify}'
Value	string
Advanced Setting; this should not normally be changed.

The SQL query used to obtain surveillance information (from the Utimaco X1 service) about a particular e-mail address.

See intercept_utimaco_x1_sql_query_check_surveillance for variable substitution information.

Example Configuration

See utimaco example configuration.

API (v1)

The Intercept Management API provides a generic internal interface for exchanging interception-related information between Dovecot and other systems that are part of the interception infrastructure.

This section describes version 1 of the of the Intercept API.

The only application of this API is currently to allow SMTP servers to check whether a certain user is under surveillance. When surveilled, the API will return additional information that a SMTP interception module needs to be able to submit an event to the Utimaco X3 event receiver.

Terminology

• Surveillance Database: The database containing information about the users targeted for surveillance. The Utimaco X1 is used to manage the records in this database. The Intercept API has only read access.
• Utimaco X1: A surveillance management API run by the e-mail provider. Lawful intercept warrants are managed by Utimaco though this interface.
• Utimaco X3: A surveillance event submission interface run by Utimaco. This is where the interception software run by the e-mail provider will submit captured surveillance events.

Protocol Structure

All messages are exchanged over HTTP, preferably protected by a TLS layer.

For Utimaco, the base URL path is /utimaco/v1.

The only allowed HTTP method is POST.

The API request method name is provided as an additional path element: /utimaco/v1/<method>

The Intercept API uses JSON objects for both requests and responses. All request and normal response messages MUST have MIME content-type application/json; charset=utf-8.

API errors produced by the server use the application/problem+json MIME content-type as defined in RFC 7807. This is a standard JSON format for API errors.

Authentication

The authentication of the client (and server) is currently assumed to take place in the SSL layer.

Methods

surveillance

This method is used to check whether a user is currently under surveillance.

The method returns the surveillance status. Additional information is returned when surveillance is active for the indicated user.

This method does not verify whether the user exists in the user database: it only checks whether this user is listed in the surveillance database. Therefore, a user that does not exist at all is equivalent to an existing user that is not currently under surveillance.

Parameters

The surveillance method has the following mandatory parameters:

• userId: The user identifier (username) of the user. In some cases this is equivalent to the user's primary e-mail address, but it may also be a username without a domain part.

Response

The response for the surveillance method has the following fields:

• status: Indicates whether the user is currently under surveillance. The following values can be returned:
  • ignored: this user is to be ignored for surveillance purposes.
  • surveilled: this user is currently under surveillance.
• uuid: The universally unique identifier created for the this surveillance activity. This value is an opaque string of at most 38 octets. This value is used in the Utimaco X1 and X3 protocols as the target identifier.
• created: This is the unix timestamp for the moment when the surveillance record was created. This is a JSON number. The unix timestamp is always represented in UTC.
• x3URL: The HTTPS URL of the Utimaco X3 event submission service.

Fields other than status are only returned when the queried user is under surveillance.

Examples

Request

POST /utimaco/v1/surveillance HTTP/1.1
Host: provider.example.com:7172
Content-Length: 36
Content-Type: application/json; charset="utf-8"

{
  "userId": "harrie@example.com"
}

Response

HTTP/1.1 200 OK
Date: Sun, 04 Sep 2016 18:56:22 GMT
Content-Length: 137
Content-Type: application/json; charset="utf-8"

{
 "status": "surveilled",
 "uuid": "389bb10d136acc57392000009a857bf2",
 "started": 1473014291,
 "x3URL": "https://10.168.3.1:4443/li"
}

Request

POST /utimaco/v1/surveillance HTTP/1.1
Host: provider.example.com:7172
Content-Length: 34
Content-Type: application/json; charset="utf-8"

{
  "userId": "theo@example.com"
}

Response

HTTP/1.1 200 OK
Date: Sun, 04 Sep 2016 19:45:59 GMT
Content-Length: 25
Content-Type: application/json; charset="utf-8"

{
 "status": "ignored"
}