3. P2DS User and Programmer’s Guide¶
3.1. Performing a Computation¶
This part manual is written mainly for the person who runs the group manager. If you run a peer, start reading from here.
3.1.1. Creating a Group¶
First, locate your administration key. This can be given to you by the
person who installed the group manager WAR file, since it is contained
in the web services web.xml
file. This administration key should
always be appended to any administration URL. For example, if the group
manager is installed on grpman.example.com
, then the initial URL
should be
https://grpman.example.com:8080/p2ds-group-management?adminKey=key
.
(Obviously, substitute the correct port numbers and key value.)
Navigate to the group manager GUI (typically .../p2ds-group-management/). There you will initially see a simple form field, asking you to supply a group name. Let’s say you enter “SimpleGroup” and click on “Create group!”. When you return to the main page and click on the name of your group, you will see something like this:
Next, you should set up a configuration. This configuraiton says what you want to compute and how to compute it. If you click on “Configuration”, you should see the following.
The first element to fill in is “MpcProtocol”. This answers the question “what do you want to compute?”. The only protocol we have definitive demand for is “additive”, meaning that you can compute a vector sum. So you have to put “additive” in that row. (Other protocols include top-k, where you can compute the top k elements of each column. For example, the maximum element would be top-1. However, at the time of writing, we have no demand for that protocol, and, while it is implemented, we do not support it.)
The next element you should fill in is “MaxElement”. This is the largest intermediate result you envisage. For “additive” it’s the largest value you think will occur in a result vector. For example, if you sample “number of attacks” in 1-minute intervals, you should hardly expect more than 1000 attacks, so 1000 is a good value.
Next should be “Field”. This is a prime number larger than MaxElement. In our case, 1013 does the trick. If you are in doubt, you can put the value 263 - 5 = 9223372036854775783 in that field, even though computations in that field will take longer.
Next you should take care of NumberOfTimeSlots and NumberOfItems. What this means is that of you have N = m x n items, you will serve these items n at a time, m times. For example, let’s say you have 6 numbers in your vector. You can choose to compute the vector sum by adding up two numbers, three times; three numbers, two times; one number, six times; or six numbers, once. They will all give the correct result, but some settings will be faster than others, and some settings will also be more robust. For example, if you have more items (large n), the computation will generally be faster, but if you have more time slots (large m), the computation will be more robust against peers failing occasionally. (In R terms, you can have a few “N/A” terms in your result vector.)
A special value for NumberOfTimeSlots is “-1”. This value will cause the peers to run in streaming mode. Usually, peers will run for NumberOfTimeSlots time slots and then shut down. When peers are running in streaming mode, they will forever wait for the next batch of numbers to process. Upside: you don’t have to initiate a new computation when you have new data. Downside: one downed or stuck peer will cause the whole computation to stall.
Finally, you can set ResultBufferSize to control in how many chunks the results are sent to the configured result endpoint (see the configuration guide on how to configure this). If you have ten timeslots and set the result buffer size to 1, then ten final results (one per timeslot) will be sent to the result endpoint. If you configure the result buffer size to be 10, only one large result will be sent, after all timeslots have completed.
If the computation fails, no results are sent. If a peer fails, restart the computation.
3.1.2. Registering the Peers¶
Next, talk to the administrators of all the participating organisations and give them the URL of your group manager service. They should deploy and configure a peer service on one of their application servers.
Now you can generate registration codes. These codes are one-time codes that peers use to authorise their registration. If you plan on having m input peers and n privacy peers, klick the “Create registration” button m + n times:
For each registration code, you should see one “Open registration code”:
Give one code per peer to the admins. They will need these codes to register the peers with the group manager. Eventually, you will find a picture like this:
Here we show only one peer, but every peer should be present. Peers have registered, and in registering, they have used up one of the registration codes. There should therefore be no open registration codes at this point.
Peers have registered, but they have not been activated. Only activated peers can participate in the protocol. To do that, talk to each of the admins of each participating organisation and read the public key of their peers to them. These should be identtical to the public keys of those peers that the admins have configured for their peers. Once that is done, click on “Mark as verified”. Rinse and repeat until all peers are verified.
The reason there is an additional verification step is that in principle, everyone can register a peer, but only you, the group manager, gets to decide who can participate in a computation. This step also serves as an authentication step to make sure that the public keys you got from the peers are authentic. This saves you from the hassle that is PKI.
3.1.3. Starting the Peers¶
Starting the peers is very simple: go to “Actions” and click on “Start peers”:
Once that is successful, you should see that “All peers are running”:
3.1.4. Giving the Peers Some Inputs¶
Once you have created input and privacy peers (refer to the API guide
how to do that), you need to give them some inputs. Ideally, you have a
web service that does that for you, but if not, you can do that by hand,
using curl
. Let’s say that your peer is called
swisscom:ddos-input-peer-1
and that your NumberOfItems in the peer
configuration (see the Group Manager guide above) is 6, since you are
sampling every 10 minutes per hour. You have seen 1, 4, 2, 8, 9, and 23
DDoS-attempts, respectively, so there is clearly something going on.
Your peer runs on p2ds.swisscom.ch:8080
and your registration code
is JKSdh3h7njs
(this is part of the peer service’s configuration).
Here is how to supply the peer with that input row:
curl -i -v -X POST --header "Content-Type: application/json" \
-d '{"peerName":"swisscom:ddos-input-peer-1","data":"1;4;2;8;9;23"}' \
https://p2ds.swisscom.ch:8080/p2ds-peer/input?registrationCode= JKSdh3h7njs
3.1.5. Viewing the Results¶
The input peers report results back to a URL that is set in the peer’s
configuration (the finalResultsURL
property). We deliver a very
simple results viewer with P2DS, which runs under /receiver
. If you
configure your input peer’s finalResultsURL
to read
https://p2ds.swisscom.ch:8080/receiver/receive (substitute correct
protocol, hostname, and port), then your results might look like this:
3.1.6. Useful Hints¶
- Always use https, never use plain http when feeding data to the input peers. The value of P2DS would be greatly diminished if the supposedly secret data were sent in plain text. The protocol between the peers can be plain http, since P2DS uses encrypted shares already and additional encryption doesn’t buy you much security.
- Always use https for talking to the group manager.
3.2. Using the APIs¶
Please refer to the API
Documentation. Exemplary
usage of the APIs can be found in the file grp.sh
in the source
code’s main directory, available from the github
page.
Here is a more verbose version of that file (with some parts skipped to
keep this guide shorter). We assume that the admin key is
default-admin-key
and that the registration codes for all peers is
TEST
.
Please don’t use default-admin-key
and testmode in a production
setting.
If you just want to experiment and/or play around otherwise on the shell
using curl setting testmode to on
can be quite convenient. If in
testmode the registration codes generated by the group management
service will not be random and Please don’t use testmode=on in
production.
#Set group-mgmt service to test mode
#Don't do that in production!
curl -i -v -X POST http://localhost:12001/p2ds-group-management/group-mgmt/testmode?on=true\&adminKey=default-admin-key
To get started we need to create a group on the group management service:
curl -i -v -X POST --header "Content-Type: application/json" -d '{"name":"SimpleGroup"}' http://localhost:12001/p2ds-group-management/group-mgmt/group?adminKey=default-admin-key
Once we have a group we can generate registration codes for peers. The
registration code is used by the peers to sign-up for a group. From the
output of the previous command (see above) we know the id of the group
(in this case 1
)
curl -i -v -X POST http://localhost:12001/p2ds-group-management/group-mgmt/registration/1?adminKey=default-admin-key
The above command will give the group management admin a registration
code that the admin needs to communicate to the peer operator. In this
case the registration code is TEST
. The peer operator can now create
a peer (named peerhans
) on the peer service:
curl -i -v -X POST --header "Content-Type: application/json" -d @./demo/files/peerhans.json http://localhost:12001/p2ds-peer/peer?adminKey=default-admin-key
./demo/files/peerhans.json
contains the configuration of the peer:
{
"finalResultsURL":"http://localhost:12001/p2ds-receiver/receiver/receive",
"peerType":1,
"name":"peerhans",
"privateKey":"MFECAQAwEAYHKoZIzj0CAQYFK4EEACQEOjA4AgEBBDNyjBeP85atxkIfiYqW+0kUB2H3guXcQWXT/tXVktbn3MyUdRmNIL99G3rK1XoGSRAM6js=",
"publicKey":"MH4wEAYHKoZIzj0CAQYFK4EEACQDagAEAJig6xXX4SuME5lRB2ADn7T7CgyH7LXbxy/oS5XhIElBPwz/40cwDAc/VgGbDKa+HGBc/AGzwSlScoCDHc7WA1tSkRUkaW/lL9NbA6gIzJLMw+FV3RPor0vpJIofVcAaV6WI1r99v8Y=",
"registrationCode":"TEST",
"groupMgmtURL":"http://localhost:12001/p2ds-group-management/group-mgmt"}
privateKey
and publicKey
must be PKCS resp. X.509 encoded as
base64. Please generate your own keypairs. peerType=1
refers to an
input peer
where as peerType=2
refers to a privacy peer
.
The peer will automatically sign-up for group membership and will be a
member of the group on the group management service but marked as
unverified
. The peer operater and group admin should exchange
fingerprints of the public key to verify the identity of the peer. If
the group admin has verified the keys he can then mark the peer as
verified:
curl -i -v -X POST http://localhost:12001/p2ds-group-management/group-mgmt/verify/hanspeer?adminKey=default-admin-key\&verified=true
Before we can start any peers we need to set a group configuration. The group configuration defines the parameters of the computation to do:
curl -i -v -X POST --header "Content-Type: application/json" -d '{"field":"1013","gid":"1","maxElement":"1000","mpcProtocol":"additive","numberOfItems":"2","numberOfTimeSlots":"2"}' http://localhost:12001/p2ds-group-management/group-mgmt/configuration?adminKey=default-admin-key
Please note that you will need at least three privacy peers and two input peers for the cryptographic protocol to work. You can start peers individually or let the group management service start all peers together. You can start individual peers by doing:
curl -i -v -X POST http://localhost:12001/p2ds-peer/start/hanspeer?registrationCode=TEST
Please note that the registration code is used as a means of authentication to prevent anybody from starting a peer. It is thus important that registration codes remain secret and are only known the the group management admin and the peer operator of the corresponding peer.
Once we have started all peers (in the case of grp.sh
you will have
two input peers and three privacy peers) we can add inputs:
curl -i -v -X POST --header "Content-Type: application/json" -d '{"peerName":"hanspeer","data":["1;3","4;5"]}' http://localhost:12001/p2ds-peer/inputs?registrationCode=TEST