{"action":"created","comment":{"url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/comments/24769838","id":24769838,"diff_hunk":"@@ -0,0 +1,24 @@\n+# Managing nginx HTTPS Certificates\n+\n+nginx needs to provide secure HTTP communication between clients and servers. This means that the server needs to be able to verify itself to the client so that the client is confident it's sending messages to the correct place, and that the client can communicate in a secure fashion with this server. nginx achieves this through HTTPS (HTTP over SSL). This involves the server sending a signed certifcate (or public key) to the client, who is able to verify the signature. The client may also request the certificate authority (CA) certificate signing request (CSR) which was used to sign the certificate. Once the client has verified the signed certificate, it can use it to securely send a means of encryption for subsequent messages to the server. The server can read this using the private key, and the server and client can now exchange information securely. There are three options for generating the secure certificate.\n+\n+## Self-signed certificate\n+\n+This requires the client accepting un-trusted certificates, and is the default option for the clearwater-nginx package. It involves the server creating its own CSR, which it uses to sign its certificate. Currently the post-install script for clearwater-nginx handles this using the openssl library.\n+\n+    openssl req -nodes -sha256 -newkey rsa:2048 -keyout nginx.key -out nginx.csr -config nginx_openssl_config\n+    openssl x509 -sha256 -req -in nginx.csr -signkey nginx.key -out nginx.crt\n+\n+The first command creates a private key and a CSR from a very basic default set of config. The second command creates a signed certificate using the private key and the CSR. Since this is all done at start of life, clients won't be able to verify the certificate, and so will have to accept un-trusted certificates, which is not secure.\n+\n+## Certificate signed by the service provider as a CA\n+\n+This involves generating the CSR before deploying nginx. This CSR then needs to be uploaded to all clients that need to contact the nginx server, and the nginx server itself. It can then be used to create a signed certificate on the nginx server which the clients can verify. This is the recommended option, but it does require being able to upload the certificate to your clients.\n+\n+The CSR can be generated using openssl, as in the first option above. The config file should have the format of [nginx_openssl_config](https://github.com/Metaswitch/clearwater-nginx/blob/master/clearwater-nginx/etc/nginx/ssl/nginx_openssl_config), with the default fields replaced. The CSR and private key can then be uploaded onto the nginx server and used to generate a signed certificate, again as in the first option above. The CSR then needs to be uploaded to your clients.\n+\n+There are other means of generating your own CSR. However, note that bullet 1) of section 5.3.0 of the 3GPP specification 33.222 suggests that the client should check that the FQDN in the certificate is the same as the FQDN used to set up the HTTPS connection.","path":"docs/HTTPSCertificates.md","position":20,"original_position":20,"commit_id":"b78958cb69c4124a757dd3a398c6788f199513c6","original_commit_id":"b78958cb69c4124a757dd3a398c6788f199513c6","user":{"login":"bossmc","id":1073983,"avatar_url":"https://avatars.githubusercontent.com/u/1073983?v=3","gravatar_id":"","url":"https://api.github.com/users/bossmc","html_url":"https://github.com/bossmc","followers_url":"https://api.github.com/users/bossmc/followers","following_url":"https://api.github.com/users/bossmc/following{/other_user}","gists_url":"https://api.github.com/users/bossmc/gists{/gist_id}","starred_url":"https://api.github.com/users/bossmc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bossmc/subscriptions","organizations_url":"https://api.github.com/users/bossmc/orgs","repos_url":"https://api.github.com/users/bossmc/repos","events_url":"https://api.github.com/users/bossmc/events{/privacy}","received_events_url":"https://api.github.com/users/bossmc/received_events","type":"User","site_admin":false},"body":"> There are other means of generating your own CSR.\r\n\r\nSuch as?  Why does the reader care?  How does the next sentence follow from this one?","created_at":"2015-02-16T19:13:36Z","updated_at":"2015-02-16T19:13:36Z","html_url":"https://github.com/Metaswitch/clearwater-nginx/pull/14#discussion_r24769838","pull_request_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14","_links":{"self":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/comments/24769838"},"html":{"href":"https://github.com/Metaswitch/clearwater-nginx/pull/14#discussion_r24769838"},"pull_request":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14"}}},"pull_request":{"url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14","id":29389584,"html_url":"https://github.com/Metaswitch/clearwater-nginx/pull/14","diff_url":"https://github.com/Metaswitch/clearwater-nginx/pull/14.diff","patch_url":"https://github.com/Metaswitch/clearwater-nginx/pull/14.patch","issue_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/14","number":14,"state":"open","locked":false,"title":"Reviewer AMC: Add doc on managing HTTPS certificates","user":{"login":"graemerobertson","id":5907876,"avatar_url":"https://avatars.githubusercontent.com/u/5907876?v=3","gravatar_id":"","url":"https://api.github.com/users/graemerobertson","html_url":"https://github.com/graemerobertson","followers_url":"https://api.github.com/users/graemerobertson/followers","following_url":"https://api.github.com/users/graemerobertson/following{/other_user}","gists_url":"https://api.github.com/users/graemerobertson/gists{/gist_id}","starred_url":"https://api.github.com/users/graemerobertson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/graemerobertson/subscriptions","organizations_url":"https://api.github.com/users/graemerobertson/orgs","repos_url":"https://api.github.com/users/graemerobertson/repos","events_url":"https://api.github.com/users/graemerobertson/events{/privacy}","received_events_url":"https://api.github.com/users/graemerobertson/received_events","type":"User","site_admin":false},"body":"Andy,\r\n\r\nPlease can you review this document on generating HTTPS certificates for nginx. I have a memento doc too which is coming in a separate PR.\r\n\r\nThanks,\r\nGraeme","created_at":"2015-02-16T17:34:59Z","updated_at":"2015-02-16T19:13:36Z","closed_at":null,"merged_at":null,"merge_commit_sha":"47af995feef8953b6ca878450bfa018bc395dfb2","assignee":{"login":"bossmc","id":1073983,"avatar_url":"https://avatars.githubusercontent.com/u/1073983?v=3","gravatar_id":"","url":"https://api.github.com/users/bossmc","html_url":"https://github.com/bossmc","followers_url":"https://api.github.com/users/bossmc/followers","following_url":"https://api.github.com/users/bossmc/following{/other_user}","gists_url":"https://api.github.com/users/bossmc/gists{/gist_id}","starred_url":"https://api.github.com/users/bossmc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bossmc/subscriptions","organizations_url":"https://api.github.com/users/bossmc/orgs","repos_url":"https://api.github.com/users/bossmc/repos","events_url":"https://api.github.com/users/bossmc/events{/privacy}","received_events_url":"https://api.github.com/users/bossmc/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14/commits","review_comments_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14/comments","review_comment_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/comments/{number}","comments_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/14/comments","statuses_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/statuses/b78958cb69c4124a757dd3a398c6788f199513c6","head":{"label":"Metaswitch:certificates_doc","ref":"certificates_doc","sha":"b78958cb69c4124a757dd3a398c6788f199513c6","user":{"login":"Metaswitch","id":453759,"avatar_url":"https://avatars.githubusercontent.com/u/453759?v=3","gravatar_id":"","url":"https://api.github.com/users/Metaswitch","html_url":"https://github.com/Metaswitch","followers_url":"https://api.github.com/users/Metaswitch/followers","following_url":"https://api.github.com/users/Metaswitch/following{/other_user}","gists_url":"https://api.github.com/users/Metaswitch/gists{/gist_id}","starred_url":"https://api.github.com/users/Metaswitch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Metaswitch/subscriptions","organizations_url":"https://api.github.com/users/Metaswitch/orgs","repos_url":"https://api.github.com/users/Metaswitch/repos","events_url":"https://api.github.com/users/Metaswitch/events{/privacy}","received_events_url":"https://api.github.com/users/Metaswitch/received_events","type":"Organization","site_admin":false},"repo":{"id":23232000,"name":"clearwater-nginx","full_name":"Metaswitch/clearwater-nginx","owner":{"login":"Metaswitch","id":453759,"avatar_url":"https://avatars.githubusercontent.com/u/453759?v=3","gravatar_id":"","url":"https://api.github.com/users/Metaswitch","html_url":"https://github.com/Metaswitch","followers_url":"https://api.github.com/users/Metaswitch/followers","following_url":"https://api.github.com/users/Metaswitch/following{/other_user}","gists_url":"https://api.github.com/users/Metaswitch/gists{/gist_id}","starred_url":"https://api.github.com/users/Metaswitch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Metaswitch/subscriptions","organizations_url":"https://api.github.com/users/Metaswitch/orgs","repos_url":"https://api.github.com/users/Metaswitch/repos","events_url":"https://api.github.com/users/Metaswitch/events{/privacy}","received_events_url":"https://api.github.com/users/Metaswitch/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Metaswitch/clearwater-nginx","description":"","fork":false,"url":"https://api.github.com/repos/Metaswitch/clearwater-nginx","forks_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/forks","keys_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/teams","hooks_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/hooks","issue_events_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/events{/number}","events_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/events","assignees_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/assignees{/user}","branches_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/branches{/branch}","tags_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/tags","blobs_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/refs{/sha}","trees_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/statuses/{sha}","languages_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/languages","stargazers_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/stargazers","contributors_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/contributors","subscribers_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/subscribers","subscription_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/subscription","commits_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/commits{/sha}","git_commits_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/commits{/sha}","comments_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/comments{/number}","issue_comment_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/comments/{number}","contents_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/contents/{+path}","compare_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/merges","archive_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/downloads","issues_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues{/number}","pulls_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls{/number}","milestones_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/milestones{/number}","notifications_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/labels{/name}","releases_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/releases{/id}","created_at":"2014-08-22T16:32:35Z","updated_at":"2015-01-16T12:10:54Z","pushed_at":"2015-02-16T17:34:45Z","git_url":"git://github.com/Metaswitch/clearwater-nginx.git","ssh_url":"git@github.com:Metaswitch/clearwater-nginx.git","clone_url":"https://github.com/Metaswitch/clearwater-nginx.git","svn_url":"https://github.com/Metaswitch/clearwater-nginx","homepage":null,"size":285,"stargazers_count":0,"watchers_count":0,"language":"Makefile","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":3,"forks":1,"open_issues":3,"watchers":0,"default_branch":"master"}},"base":{"label":"Metaswitch:master","ref":"master","sha":"2338950beaff1229843f6494160ad1c5a886aa29","user":{"login":"Metaswitch","id":453759,"avatar_url":"https://avatars.githubusercontent.com/u/453759?v=3","gravatar_id":"","url":"https://api.github.com/users/Metaswitch","html_url":"https://github.com/Metaswitch","followers_url":"https://api.github.com/users/Metaswitch/followers","following_url":"https://api.github.com/users/Metaswitch/following{/other_user}","gists_url":"https://api.github.com/users/Metaswitch/gists{/gist_id}","starred_url":"https://api.github.com/users/Metaswitch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Metaswitch/subscriptions","organizations_url":"https://api.github.com/users/Metaswitch/orgs","repos_url":"https://api.github.com/users/Metaswitch/repos","events_url":"https://api.github.com/users/Metaswitch/events{/privacy}","received_events_url":"https://api.github.com/users/Metaswitch/received_events","type":"Organization","site_admin":false},"repo":{"id":23232000,"name":"clearwater-nginx","full_name":"Metaswitch/clearwater-nginx","owner":{"login":"Metaswitch","id":453759,"avatar_url":"https://avatars.githubusercontent.com/u/453759?v=3","gravatar_id":"","url":"https://api.github.com/users/Metaswitch","html_url":"https://github.com/Metaswitch","followers_url":"https://api.github.com/users/Metaswitch/followers","following_url":"https://api.github.com/users/Metaswitch/following{/other_user}","gists_url":"https://api.github.com/users/Metaswitch/gists{/gist_id}","starred_url":"https://api.github.com/users/Metaswitch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Metaswitch/subscriptions","organizations_url":"https://api.github.com/users/Metaswitch/orgs","repos_url":"https://api.github.com/users/Metaswitch/repos","events_url":"https://api.github.com/users/Metaswitch/events{/privacy}","received_events_url":"https://api.github.com/users/Metaswitch/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Metaswitch/clearwater-nginx","description":"","fork":false,"url":"https://api.github.com/repos/Metaswitch/clearwater-nginx","forks_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/forks","keys_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/teams","hooks_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/hooks","issue_events_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/events{/number}","events_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/events","assignees_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/assignees{/user}","branches_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/branches{/branch}","tags_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/tags","blobs_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/refs{/sha}","trees_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/statuses/{sha}","languages_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/languages","stargazers_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/stargazers","contributors_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/contributors","subscribers_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/subscribers","subscription_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/subscription","commits_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/commits{/sha}","git_commits_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/git/commits{/sha}","comments_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/comments{/number}","issue_comment_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/comments/{number}","contents_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/contents/{+path}","compare_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/merges","archive_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/downloads","issues_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues{/number}","pulls_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls{/number}","milestones_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/milestones{/number}","notifications_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/labels{/name}","releases_url":"https://api.github.com/repos/Metaswitch/clearwater-nginx/releases{/id}","created_at":"2014-08-22T16:32:35Z","updated_at":"2015-01-16T12:10:54Z","pushed_at":"2015-02-16T17:34:45Z","git_url":"git://github.com/Metaswitch/clearwater-nginx.git","ssh_url":"git@github.com:Metaswitch/clearwater-nginx.git","clone_url":"https://github.com/Metaswitch/clearwater-nginx.git","svn_url":"https://github.com/Metaswitch/clearwater-nginx","homepage":null,"size":285,"stargazers_count":0,"watchers_count":0,"language":"Makefile","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":3,"forks":1,"open_issues":3,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14"},"html":{"href":"https://github.com/Metaswitch/clearwater-nginx/pull/14"},"issue":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/14"},"comments":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/issues/14/comments"},"review_comments":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14/comments"},"review_comment":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/pulls/14/commits"},"statuses":{"href":"https://api.github.com/repos/Metaswitch/clearwater-nginx/statuses/b78958cb69c4124a757dd3a398c6788f199513c6"}}}}