SSL - Certificate Authority and certificates -------------------------------------------- As of burp-1.3.2, the process of generating SSL certificates has been automated with the use of burp_ca. Effectively, the automation means that you can set up a new client on the server (in /etc/burp/clientconfdir/), and the first client to connect that matches that client name and password will get its certificate signed and given back. If a different, second client, happens to connect with the same client name and password, it will be rejected because it doesn't have a matching certificate. The clientconfdir passwords can now be thought of as being 'first contact' passwords, as after that, SSL will provide assurance that the peers are who they claim to be (although the server will still check the passwords too). There is the option of setting 'password_check = 0' on the server, which will disable the checking of passwords completely (but won't disable the checking of SSL certificates). Of course, you should take into account the environment that your server and clients are running in before making the choice to either disable the passwords, leave them all the same, or make them all different. Server ------ Server CA options: ca_conf = /etc/burp/CA.cnf ca_name = burpCA ca_server_name = burpserver ca_burp_ca = /usr/sbin/burp_ca Server SSL options: ssl_dhfile = /etc/burp/dhfile.pem ssl_cert_ca = /etc/burp/ssl_cert_ca.pem ssl_cert = /etc/burp/ssl_cert-server.pem ssl_key = /etc/burp/ssl_cert-server.key ssl_key_password = password (only needed if you have an encrypted certificate) If you do not want the server to automate the CA stuff, do not set ca_conf. When the server starts, the ca_conf file will be read, and the CA_DIR value from that file will be read. If the CA_DIR directory already exists, the automatic CA setup finishes here. Next, if ssl_dhfile does not exist, an appropriate dhfile will be generated. The dhfile is used in encypting the SSL connection with the Diffie-Hellman protocol. Next, the CA directory is initialised using ca_burp_ca, which should point to the burp_ca script. The name of the CA will be the value of ca_name. A key for the burp server is then generated, along with a certificate signing request to give to the CA. The CA then signs the request. The ssl_cert_ca, ssl_cert and ssl_key paths are then overwritten with symlinks to the new keys and certificates. This concludes the CA setup on the server. Client ------ Client CA options: ca_burp_ca=/usr/sbin/burp_ca ca_csr_dir=/etc/burp/CA Client SSL options: ssl_cert_ca = /etc/burp/ssl_cert_ca.pem ssl_cert = /etc/burp/ssl_cert-client.pem ssl_key = /etc/burp/ssl_cert-client.key ssl_key_password = password (only needed if you have an encrypted certificate) ssl_peer_cn = burpserver If you do not want the client to automate the CA stuff, do not set ca_burp_ca. Clients as of 1.3.2 will not include the old default certificates, so if you want to install new clients connecting to a server that is using the old certificates, you will also have to copy the old certificates onto the client. When the client runs (for example, with 'burp -a b'), it will try to connect to the server using the burp client name (cname) and password. If you haven't got the client name and password right, everything stops here. If the path to ssl_key exists, the client will not try to generate a key and certificate signing request - it assumes that this has already been done. Otherwise, a client key is generated at the path of ssl_key, and a certificate request is generated in the ca_csr_dir directory, named after the client name. This is copied to CA_DIR on the server, unless the server already has a file named the same, or a signed certificate with the same name. If either already exists, the server will reject the request. If the server accepts the request, it will generate a signed certificate and send it back to the client, along with the CA certificate. The ssl_cert_ca and ssl_cert paths will be overwritten on the client, and burp.conf will be rewritten with ssl_peer_cn set correctly. The connection between server and client is dropped and the client will reconnect using the new certificates to start the real work (for example, a backup). In previous versions of burp, you needed to set ssl_peer_cn in the client's clientconfdir file on the server. You don't need to set this any more, because the server will default to using the client name instead. This concludes the certificate setup on the client. ----- The following is the (slightly tweaked) original documentation for burp_ca. It might still be of use in order to help understand the process, or if it is necessary to do it by hand. Note that there is a burp_ca.bat script if you are generating certificate signing requests on Windows. Setup the server: 1) generate Diffie-Hellman Parameters burp_ca --dhfile /etc/burp/dhfile.pem 2) Initialise CA burp_ca --init --ca myCA This creates /etc/burp/CA, generate private key for CA and self signed certificates. 3) Generate server key and cert signing request burp_ca --key --request --name myServer 4) Sign request burp_ca --sign --ca myCA --name myServer --batch 5) Link or copy cert and key to /etc/burp ln -s CA/CA_myCA.crt /etc/burp/ssl_cert_ca.pem ln -s CA/myServer.crt /etc/burp/ssl_cert-server.pem ln -s CA/myServer.key /etc/burp/ssl_cert-server.key (use the ssl_cert and ssl_key options in burp-server.conf !) Setup the client (the easy way - insecure) 1) Generate client key and cert __on the server__ burp_ca --name myClient --ca myCA --key --request --sign --batch 2) copy key and certs from server to client server:/etc/burp/ssl_cert_ca.pem -> client:/etc/burp/ssl_cert_ca.pem server:/etc/burp/CA/myClient.crt -> client:/etc/burp/ssl_cert-client.pem server:/etc/burp/CA/myClient.key -> client:/etc/burp/ssl_cert-client.key chmod 600 /etc/burp/ssl_cert-client.key (use the ssl_cert and ssl_key options in burp.conf !) Setup the client (the usual way) 1) on the client you dont need a CA, so just mkdir /etc/burp/CA chmod 700 /etc/burp/CA 2) Generate client key and cert signing request burp_ca --key --request --name myClient (on Windows: burp_ca.bat --key --keypath \ --request --requestpath --name myClient) 3) copy the request from client to the server client:/etc/burp/CA/myClient.csr -> server:/etc/burp/CA/myClient.csr 4) sign the request __on the server__ burp_ca --name myClient --ca myCA --sign --batch 5) copy the certs back to the client server:/etc/burp/CA/CA_myCA.crt -> client:/etc/burp/CA/CA_myCA.crt server:/etc/burp/CA/myClient.crt -> client:/etc/burp/CA/myClient.crt 6) link or copy the files ln -s CA/CA_myCA.crt /etc/burp/ssl_cert_ca.pem ln -s CA/myClient.crt /etc/burp/ssl_cert-client.pem ln -s CA/myClient.key /etc/burp/ssl_cert-client.key (use the ssl_cert and ssl_key options in burp.conf !)