Adding a new client
-------------------

First, you will need to tell the server about the new client.
Each client is represented by a file in the /etc/burp/clientconfdir directory
on the server.

So, to add a client called 'data_store', you would create a file on the server
called /etc/burp/clientconfdir/data_store.
As a minimum, the file needs to contain a line like this (unless you are using
the 'password_check = 0' option):

password = abcedfgh

Now, you can install the burp client.
If you are using Windows, the installer will walk you through the steps (see
the separate documentation on this).

On other operating systems, you will need to edit the client burp.conf so that
the 'cname' line matches the clientconfdir file name on the server, the
'password' line matches the its the clientconfdir file's contents, and the
'server' line contains the address of the server. In our example's case, those
three lines will look like this:

cname = data_store
password = abcdefgh
server= 1.2.3.4

(Note that you don't necessarily have to specify cname - see the 'automatic
client names' section below) 

You will also need to set up a timed job on the client, to run 'burp -a t'.
This is done automatically on Windows. On other operating systems, you will
need to add a cron job.

The first time that the new client connects to the server, it will perform the
SSL certificate exchange (see the separate documentation on this).

I find it useful to run 'burp -a l' by hand initially, to see the exchange
happen and be sure that the connection is working. 'burp -a l' is a request
for a list of backups. With your new client, there will of course be no
backups, but you will see successful communication between client and server.
The Windows equivalent of this command is:
C:\Program Files\Burp\bin\burp.exe -a l


Disabling a client
------------------

To stop a client from successfully interacting with the server, you should
move the /etc/burp/clientconfdir/<client> file aside. The client, if it still
exists, will keep trying to connect.

For example:

mv /etc/burp/clientconfdir/<client> /etc/burp/clientconfdir/<client>.disable

However, this will not stop the client trying to connect to the server based on
its timed job. If you can still access the client, I would recommend turning
off the timed job.


Revoking a client
-----------------

The fact that the client uses a certificate, with the correct CN, signed by
the server is what allows it to complete the SSL part of the connection.
To make a particular certificate stop working, you need to revoke it.

There is currently no automatic mechanism in burp that will let you do
this (see https://github.com/grke/burp/issues/89).

The following procedure is for burp-2 only.

Revoking a client certificate will cause the server to reject a client
connection, from the moment the 'ca_crl_check' option has been enabled
in the burp-server.conf configuration file.

Before you can revoke certificates with the following method, you need to
enable the Certificate Revocation List (CRL). See the documentation page on
'certificate authority and certificates' for details on this.

The procedure below will revoke a client certificate which has been signed by
the server certificate authority. These commands are run on the server.

   1. Get the certificate serial of the client:
      openssl x509 -serial -noout -in /etc/burp/CA/<client name>.crt

   2. Revoke the certificate ('01' is the serial number output in step 2):
      burp_ca --name burpCA --revoke 01

   3. Regenerate the crl:
      burp_ca --name burpCA --crl

   4. Check the certificate has been revoked:
      openssl crl -in /etc/burp/CA/CA_burpCA.crl -text

   The client will not be able to connect any more.

   5. Left over files for the client can now be deleted on the server:
      rm /etc/burp/CA/<client>.*
      rm /etc/burp/clientconfdir/<client>

   6. You may, or may not, also want to delete any backups left on the server:
      rm -r /var/spool/burp/<client>

   7. To see a list of revoked certificates:
      openssl crl -in /etc/burp/CA/CA_burpCA.crl -text -noout

Notes:

 1. The presence of the '/etc/burp/CA/<client>.*' files will prevent a
    client with the same CN doing a certificate signing process.

 2. If not deleted, the presence of '/etc/burp/clientconfdir/<client>'
    could present a security risk as somebody knowing the client name and
    password could start a certificate signing process and then access any
    remaining backup files.

 3. The procedure above checks the certificate against the burp_ca CRL. If
    the certificate authority is different, it is recommended to use
    the provided 'ssl_extra_checks_script' which will download the
    certificate authority CRL for validation before allowing the
    client to proceed further with the backup/list/restore operations.

 4. <client>.csr is the client's initial signing request and <client>.crt is
    the signed certificate that the server gave back to the client.


Automatic client names
----------------------

The following procedure is for burp-2 only.

If you do not specify a cname in the client burp.conf, and it hasn't yet
generated its SSL certificates, it will use its own fully qualified domain
name as the common name in its new SSL certificate.

If you do not specify a cname in the client burp.conf, and you have generated
its SSL certificate, it will use the common name in the certificate as the
cname.

There are some further options related to the automatic cname on the client
side:
*) cname_fqdn=[0|1] - If you want to use the hostname instead of the whole
                      fqdn, set this to 0. The default is 1.
*) cname_lowecase=[0|1] - If you want to force it to lowercase, use 1. The
                          default is 0.

If you have already generated the SSL certificate before using these options,
you will need adjust a few things. Assume the cname was originally
testclient.f.q.d.n and now you want to set cname_fqdn=0 on the client side.
Now, on the server:

  1) Make sure that no backup of the client is already running.
  2) You have to move your storage directory if you already have backups:
     cd /var/spool/burp && mv testclient.f.q.d.n testclient
  3) You have to setup clientconfdir accordingly:
     cd /etc/burp/clientconfdir && mv testclient.f.q.d.n testclient
  4) The certificate won't match on the server side because it has the common
     name testclient.f.q.d.n and we are now looking for testclient. You can
     add 'ssl_peer_cn=testclient.f.q.d.n' in /etc/burp/clientconfdir/testclient
     and it will work again.
  5) On the client, run 'burp -a l' to check that things work correctly.

The cname_fqdn and cname_lowercase options are also available server-side, in
burp-server.conf. When set here, they adjust the cname server side.
So, following the example above, the client would still be sending
'testclient.f.q.d.n', but the server will treat it according to its own
options.
Again, if you set these options once a client has already introduced itself,
you will have to follow the same steps above.