Merge pull request #19 from conwetlab/develop

Add instructions to secure the Notification Callback

README.md

@@ -15,6 +15,7 @@ Install this extension in your CKAN is instance is as easy as intall any other C
 * If you want you can also add some preferences to set if the Acquire URL should be shown when the user is creating and/or editing a dataset:
   * To show the Acquire URL when the user is **creating** a dataset, you should set the following preference: `ckan.privatedatasets.show_acquire_url_on_create = True`. By default, the value of this preference is set to `False`.
   * To show the Acquire URL when the user is **editing** a dataset, you should set the following preference: `ckan.privatedatasets.show_acquire_url_on_edit = True`. By default, the value of this preference is set to `False`.
+* In some cases you will want to secure the notification callback in order to filter the entities (user, machines...) that can send them. To do so, you can follow the instructions in the section [Securing the Notification Callback](#securing-the-notification-callback). 
 * Restart your apache2 reserver (`sudo service apache2 restart`)
 * That's All!
 
@@ -41,6 +42,85 @@ At this point, you will be able to add users via API by accessing the following
 http://<CKAN_SERVER>:<CKAN_PORT>/api/action/dataset_acquired
 ```
 
+Securing the Notification Callback
+-----------------------------------
+In some cases, you are required to filter the entities (users, machines...) that can send notifications to the notification callback. To do so, you must relay on Client Side Verification over HTTPs, so the first step here is to deploy your CKAN instance over HTTPs. If you haven't already done it, you can use the following tutorial: [Starting CKAN over HTTPs](https://github.com/conwetlab/ckanext-oauth2/wiki/Starting-CKAN-over-HTTPs).
+
+Once that your CKAN instance is running over HTTPs, you have to configure the Client Side Verification. To achieve this, the first thing that you must do is creating an OpenSSL config file. You can use the following one or modify it to your liking:
+
+```
+[ req ]
+default_md = sha1
+distinguished_name = req_distinguished_name
+
+[ req_distinguished_name ]
+countryName = Country
+countryName_default = SP
+countryName_min = 2
+countryName_max = 2
+localityName = Locality
+localityName_default = Madrid
+organizationName = Organization
+organizationName_default = FIWARE
+commonName = Common Name
+commonName_max = 64
+
+[ certauth ]
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always,issuer:always
+basicConstraints = CA:true
+crlDistributionPoints = @crl
+
+[ server ]
+basicConstraints = CA:FALSE
+keyUsage = digitalSignature, keyEncipherment, dataEncipherment
+extendedKeyUsage = serverAuth
+nsCertType = server
+crlDistributionPoints = @crl
+
+[ client ]
+basicConstraints = CA:FALSE
+keyUsage = digitalSignature, keyEncipherment, dataEncipherment
+extendedKeyUsage = clientAuth
+nsCertType = client
+crlDistributionPoints = @crl
+
+[ crl ]
+URI=http://testca.local/ca.crl
+```
+
+Then, you should create your CA using the previous config file. To do so, you can execure the following line (replace `<PATH_TO_SSL_CONFIG_FILE>` by the real path of your OpenSSL config file):
+
+```
+$ openssl req -config <PATH_TO_SSL_CONFIG_FILE> -newkey rsa:2048 -nodes -keyform PEM -keyout ca.key -x509 -days 3650 -extensions certauth -outform PEM -out ca.cer
+```
+
+Afterwards, you will need to filter the notification callback to be callable only by those entities that use a valid certificate (the one signed by the CA created previously). To achieve this, edit the file `/etc/apache2/sites-available/ckan_default` and add the following lines inmediatly after the SSL configuration (replace `<PATH_TO_SSL_CONFIG_FILE>` by the real path of your OpenSSL config file):
+
+```
+    <Location /api/action/dataset_acquired>
+        SSLCACertificateFile    <PATH_TO_THE_CA_FILE_CREATED_PREVIOUSLY>
+        SSLVerifyClient         require
+    </Location>
+```
+
+Finally, you must restart your Apache server. To do so, execute the following command:
+
+```
+$ sudo service apache2 restart
+```
+
+From now own, you should consider that a valid certificate will be required to call the notification callback. To generate a new certificate you can execute the following lines (replace `<PATH_TO_SSL_CONFIG_FILE>` by the real path of your OpenSSL config file):
+
+```
+$ openssl genrsa -out client.key 2048
+$ openssl req -config <PATH_TO_SSL_CONFIG_FILE> -new -key client.key -out client.req
+$ openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extfile <PATH_TO_SSL_CONFIG_FILE> -extensions client -days 365 -outform PEM -out client.cer
+$ openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
+```
+
+That's all! You notification callback is completly secure now! Enjoy it :)
+
 Tests
 -----
 This sofware contains a set of test to detect errors and failures. You can run this tests by running the following command: