-
Notifications
You must be signed in to change notification settings - Fork 26
Intercept Configuration REST API
This page documents the REST-like API that can be used to add, modify or remove active interceptions within a running instance of OpenLI.
There is now a simple web UI available that uses this REST API for intercept configuration. More details on how to install and use the web UI can be found on this wiki page.
From OpenLI 1.0.6, it will be possible to configure the REST API to require user authentication via either Digest-Auth or an API key. See the REST API authentication wiki page for more details on how to enable this feature.
By default, the OpenLI provisioner will listen on TCP port 8992 on all interfaces for requests against the REST API. You can change this by setting the updateaddr and updateport configuration options in the provisioner configuration file. See the Provisioner documentation for more details.
The service itself is implemented using libmicrohttpd.
The REST API can be used to add or modify the following provisioner configuration options:
- IP intercepts (including UMTS / mobile intercepts)
- VOIP intercepts
- Email intercepts (from v1.1.0 onwards)
- IP addresses and port numbers for "core" servers (such as SIP servers, RADIUS servers or GTP servers).
- Law Enforcement Agencies
- Default RADIUS usernames
The running intercept configuration is stored in a file on disk, which will be updated after each REST API call has completed. Note that manual edits to this file will not take effect unless the provisioner is restarted (or receives a SIGHUP). Any manual edits will also be overwritten if the REST API is used to modify the running intercept without either restarting the provisioner or telling it to reload its configuration with a SIGHUP.
Security and access control for the REST API socket is the responsibility of the OpenLI user. We plan to add more security features (e.g. authentication) eventually, but we strongly recommend the use of access controls to prevent unwanted hosts from making connections to the REST API socket.
(only applies from OpenLI 1.0.5 onwards)
If the OpenLI provisioner is configured to use TLS to encrypt its communications with the other components, then the update socket will only accept connections that are using HTTPS. HTTP is only available if TLS is disabled entirely (but you really should be using TLS for all OpenLI components anyway).
If you are using a self-signed certificate for OpenLI TLS, then the client that you use to send requests to the update socket may require access to the certificate for the CA that you used to sign the certificate on the provisioner. For example, requests made using curl over HTTPS to a provisioner with a self-signed certificate will fail by default, if you do not explicitly provide the CA certificate to curl as well.
For curl, you can resolve this by adding the --cacert option to your curl command, e.g.
curl --cacert /etc/openli/openli-ca-crt.pem -X DELETE https://10.100.100.1:9001/ipintercept/EXAMPLE1
You also make sure that your provisioner certificate has been created with a CN that matches the hostname / IP of the interface that your update socket will be listening on. In the above example, that means the certificate must have a CN of 10.100.100.1, but ideally you would assign a proper hostname (e.g provisioner-openli.mynetwork.net) to the provisioner host and use that as a CN when creating the provisioner certificate. See the OpenLI TLS documentation for more information about creating certificates.
New intercept configuration may be added to the running provisioner by using an HTTP POST to send a JSON object describing the new configuration item to the appropriate URL. Depending on the item being configured (intercept vs agency vs core server), some fields in the JSON object may be optional (in which case OpenLI will set a reasonable default value), but others will be mandatory and the request will fail if those fields are missing.
The following tables list the URLs to POST to (replace "host" and "port" with the IP and port number configured for your update socket) and the fields that can appear in the JSON object being POSTed for each of the configuration objects that the REST API supports. More detail on the exact meaning of each of the fields can be found in the provisioner documentation. Fields marked as "Key" are used to uniquely identify that object within the configuration system -- this becomes important when you wish to modify or delete the object (see PUT and DELETE sections further below).
| Object | URL | Field | Comment |
|---|---|---|---|
| IP intercept | http://host:port/ipintercept | "liid" | Mandatory, Key |
| "authcc" | Mandatory | ||
| "delivcc" | Mandatory | ||
| "agencyid" | Mandatory | ||
| "mediator" | Mandatory | ||
| "vendmirrorid" | Optional | ||
| "user" | Mandatory | ||
| "accesstype" | Optional, defaults to "undefined" | ||
| "radiusident" | Optional, defaults to no restriction | ||
| "staticips" | Optional, List | ||
| "starttime" | Added in v1.0.10, optional, must be a unix timestamp | ||
| "endtime" | Added in v1.0.10, optional, must be a unix timestamp | ||
| "outputhandovers" | Added in v1.1.0, optional, must be {0, 1, or 2} |
Static IPs are expressed as a list of JSON objects, each containing just two fields: iprange and sessionid. iprange should be expressed as an IP prefix (e.g. 192.168.0.0/16). sessionid is the CIN that should be assigned to any intercepted traffic from that IP range.
The vendmirrorid must be expressed as a decimal integer (as opposed to the hexadecimal format used in the running intercept config file). For example, if your Vendor Mirroring Session ID is 0x50, then you will need to provide the decimal equivalent (80) in your vendmirrorid field in the JSON object that you POST to the REST API socket.
starttime and endtime, if specified, will only intercept packets between the time boundaries given by these fields. By default, each is set to 0 -- an endtime of 0 means that the intercept will continue forever.
outputhandovers, if specified, can be used to designate an intercept to produce only IRIs, only CCs, or both. By default, both handovers are produced. For IRI only intercepts, set this value to 1. For CC only intercepts, set this value to 2. Setting it to 0 will result in both IRIs and CCs being emitted for this intercept.
| Object | URL | Field | Comment |
|---|---|---|---|
| VOIP intercept | http://host:port/voipintercept | "liid" | Mandatory, Key |
| "authcc" | Mandatory | ||
| "delivcc" | Mandatory | ||
| "agencyid" | Mandatory | ||
| "mediator" | Mandatory | ||
| "siptargets" | Mandatory, List | ||
| "starttime" | Added in v1.0.10, optional, must be a unix timestamp | ||
| "endtime" | Added in v1.0.10, optional, must be a unix timestamp | ||
| "outputhandovers" | Added in v1.1.0, optional, must be {0, 1, or 2} |
SIP targets are expressed as a list of JSON objects, each containing just two fields: username and realm. realm is an optional field -- if not included, then the intercept applies to all SIP users with the given username, regardless of their realm.
starttime and endtime, if specified, will only intercept packets between the time boundaries given by these fields. By default, each is set to 0 -- an endtime of 0 means that the intercept will continue forever.
outputhandovers, if specified, can be used to designate an intercept to produce only IRIs, only CCs, or both. By default, both handovers are produced. For IRI only intercepts, set this value to 1. For CC only intercepts, set this value to 2. Setting it to 0 will result in both IRIs and CCs being emitted for this intercept.
| Object | URL | Field | Comment |
|---|---|---|---|
| Email intercept | http://host:port/emailintercept | "liid" | Mandatory, Key |
| "authcc" | Mandatory | ||
| "delivcc" | Mandatory | ||
| "agencyid" | Mandatory | ||
| "mediator" | Mandatory | ||
| "targets" | Mandatory, List | ||
| "starttime" | optional, must be a unix timestamp | ||
| "endtime" | optional, must be a unix timestamp | ||
| "outputhandovers" | Added in v1.1.0, optional, must be {0, 1, or 2} |
Email targets are expressed as a list of JSON objects, each containing just the one field: address. An address is the email address of the intercept target. Multiple email addresses are expressed as additional objects in the list.
Email interception is only available in OpenLI 1.1.0 onwards.
starttime and endtime, if specified, will only intercept packets between the time boundaries given by these fields. By default, each is set to 0 -- an endtime of 0 means that the intercept will continue forever.
outputhandovers, if specified, can be used to designate an intercept to produce only IRIs, only CCs, or both. By default, both handovers are produced. For IRI only intercepts, set this value to 1. For CC only intercepts, set this value to 2. Setting it to 0 will result in both IRIs and CCs being emitted for this intercept.
| Object | URL | Field | Comment |
|---|---|---|---|
| Agency | http://host:port/agency | "agencyid" | Mandatory, Key |
| "hi2address" | Mandatory | ||
| "hi3address" | Mandatory | ||
| "hi2port" | Mandatory | ||
| "hi3port" | Mandatory | ||
| "keepalivefreq" | Optional, defaults to 300 seconds | ||
| "keepalivewait" | Optional, defaults to 30 seconds |
| Object | URL | Field | Comment | Added in Version |
|---|---|---|---|---|
| RADIUS Server | http://host:port/radiusserver | "ipaddress" | Mandatory | |
| "port" | Mandatory | |||
| SIP Server | http://host:port/sipserver | "ipaddress" | Mandatory | |
| "port" | Mandatory | |||
| GTP Server | http://host:port/gtpserver | "ipaddress" | Mandatory | |
| "port" | Mandatory | |||
| SMTP Server | http://host:port/smtpserver | "ipaddress" | Mandatory | 1.1.0 |
| "port" | Mandatory | |||
| IMAP Server | http://host:port/imapserver | "ipaddress" | Mandatory | 1.1.0 |
| "port" | Mandatory | |||
| POP3 Server | http://host:port/pop3server | "ipaddress" | Mandatory | 1.1.0 |
| "port" | Mandatory | |||
| Default RADIUS Username | http://host:port/defaultradius | "username" | Mandatory |
The following examples use curl to POST JSON objects to an OpenLI configuration REST API listening on 10.100.100.1:9001. Assumes that we have a running mediator (ID: 6001).
Adding a LEA called "police", with default keepalive policy:
curl -X POST -H "Content-Type: application/json" -d '{"agencyid": "police", "hi2address": "192.168.100.1", "hi2port": "12345", "hi3address": "192.168.100.1", "hi3port": "12346"}' http://10.100.100.1:9001/agency
Adding a standard IP intercept for a target username "roger":
curl -X POST -H "Content-Type: application/json" -d '{"liid": "EXAMPLE1", "authcc": "NZ", "delivcc": "NZ", "agencyid": "police", "mediator": "6001", "user": "roger", "accesstype": "fibre"}' http://10.100.100.1:9001/ipintercept
Adding an IP intercept for a target user called "benny", using static IPs:
curl -X POST -H "Content-Type: application/json" -d '{"liid": "EXAMPLE2", "authcc": "NZ", "delivcc": "NZ", "agencyid": "police", "mediator": "6001", "user": "benny", "accesstype": "LAN", "staticips": [ {"iprange": "6.7.8.9/32", "sessionid": "11223"}, {"iprange": "2001:1234:5678:9abc::1/64", "sessionid": "11223"} ] }' http://10.100.100.1:9001/ipintercept
Adding a VOIP intercept for a target "steve@myrealm.com":
curl -X POST -H "Content-Type: application/json" -d '{"liid": "EXAMPLE3", "authcc": "NZ", "delivcc": "NZ", "agencyid": "police", "mediator": "6001", "siptargets": [ {"username": "steve", "realm": "myrealm.com"} ] }' http://10.100.100.1:9001/voipintercept
Adding an email intercept for a target "jim@example.org":
curl -X POST -H "Content-Type: application/json" -d '{"liid": "EXAMPLE4", "authcc": "NZ", "delivcc": "NZ", "agencyid": "police", "mediator": "6001", "targets": [ {"address": "jim@example.org"} ] }' http://10.100.100.1:9001/emailintercept
Adding 192.168.250.100:5060 as a SIP server:
curl -X POST -H "Content-Type: application/json" -d '{"ipaddress": "192.168.250.100", "port": "5060"}' http://10.100.100.1:9001/sipserver
Adding 10.250.100.1:1845 as a RADIUS server:
curl -X POST -H "Content-Type: application/json" -d '{"ipaddress": "10.250.100.1", "port": "1845"}' http://10.100.100.1:9001/radiusserver
Adding "customer@myisp.com" as a default RADIUS username:
curl -X POST -H "Content-Type: application/json" -d '{"username": "customer@myisp.com"}' http://10.100.100.1:9001/defaultradius
Intercepts (both VOIP and IP) and agencies can be removed by sending an HTTP DELETE to the appropriate URL, where the path portion of the URL takes the format:
:objecttype/:key
where :objecttype is one of voipintercept | ipintercept | agency and :key is the value of the "Key" field for that object type (as described in the POST section above). For intercepts, the key is the LIID. For agencies, the key is the agency ID.
For example, to remove an IP intercept which has an LIID of EXAMPLE1, we could do the following:
curl -X DELETE http://10.100.100.1:9001/ipintercept/EXAMPLE1
Core servers (SIP, RADIUS, GTP, SMTP, IMAP, POP3) can be removed in a similar manner, but the key in this case takes on a slightly different format (note the dash between the IP and the port):
:objecttype/:ipaddr-:port
For example, removing a SIP server on 192.168.250.100:5060:
curl -X DELETE http://10.100.100.1:9001/sipserver/192.168.250.100-5060
Default RADIUS usernames are also simple to remove; the key for a RADIUS username is the username itself. For example:
curl -X DELETE http://10.100.100.1:9001/defaultradius/customer@myisp.com
To modify any of the parameters of an existing intercept or agency (other than its key), you can use the HTTP PUT method to send a JSON object to the update socket containing the new field values that you would like OpenLI to adopt for that intercept or agency. The JSON object must include the Key field and that Key field must match an existing intercept or agency.
Any other unchanged fields do not need to be included in your JSON object; just the fields that are changing. One exception: if you are modifying fields that are expressed as lists, like staticips and siptargets, you will need to include all items that you want to remain in the list after modification.
The URL that you send your request to is constructed using the same rules as when sending a POST request. For example, if we had made an error when configuring the intercept for "benny" and wanted to change the IPv4 address from 6.7.8.9/32 to 6.7.8.99/32, then we would do the following:
curl -X PUT -H "Content-Type: application/json" -d '{"liid": "EXAMPLE2", "staticips": [ {"iprange": "6.7.8.99/32", "sessionid": "11223"}, {"iprange": "2001:1234:5678:9abc::1/64", "sessionid": "11223"} ] }' http://10.100.100.1:9001/ipintercept
Three key things to note in the above example:
- The LIID field (i.e. the Key) is present in the JSON object, so OpenLI knows which intercept to modify.
- We've changed only the IPv4 static IP, but our list includes the IPv6 one as well. If we had left it out, OpenLI would have assumed that we wanted to remove it from the static IP list for this intercept.
- All other fields are not modified, so they can be safely left out. There is no harm in including them, though, if we had wanted to.
OpenLI does not support the modification of these objects using a PUT request. If you wish to modify a core server or RADIUS username, simply delete it and then use a POST to add it again with the correct parameters.
The running intercept configuration can be requested using an HTTP GET request to an appropriate URL. As always, you should make sure that only authorised users can send GET requests to the REST API socket, so as to prevent unauthorised persons from browsing your list of running intercepts.
Responses to GET requests are in the JSON format, either as a list of objects or a single object (depending on the request that was made).
For IP intercepts, VOIP intercepts and agencies, the REST API can be used to either request a list of all configured entities of that type or to request just the configuration for a specific intercept / agency.
All configured entities can be queried by sending a GET request to the following URLs:
| Object | URL |
|---|---|
| IP intercept | http://host:port/ipintercept/ |
| VOIP intercept | http://host:port/voipintercept/ |
| Email intercept | http://host:port/emailintercept/ |
| Agency | http://host:port/agency/ |
To get the configuration for a specific intercept / agency, use the same URL with the LIID or Agency ID of the request target appended after the trailing slash. For example:
curl -X GET http://10.100.100.1:9001/ipintercept/EXAMPLE1
curl -X GET http://10.100.100.1:9001/agency/police
Requesting the list of core servers (RADIUS, SIP, GTP etc.) and default RADIUS usernames works in much the same way as with intercepts and agencies. The difference is that you can only request the full set of servers or usernames using the base URL; requesting individual servers or usernames is not supported using the REST API.
| Object | URL |
|---|---|
| RADIUS servers | http://host:port/radiusserver/ |
| SIP servers | http://host:port/sipserver/ |
| GTP servers | http://host:port/gtpserver/ |
| SMTP servers | http://host:port/smtpserver/ |
| IMAP servers | http://host:port/imapserver/ |
| Default RADIUS usernames | http://host:port/defaultradius/ |