Difference between revisions of "ReproMutualTLSAuthenticationJitsi"

From reSIProcate
Jump to navigation Jump to search
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
!! Background
+
== Background ==
  
 
As of reSIProcate 1.8, the ''repro'' proxy supports Mutual (client) TLS authentication.
 
As of reSIProcate 1.8, the ''repro'' proxy supports Mutual (client) TLS authentication.
Line 9: Line 9:
 
* this works with or without a challenge password: you can still demand the local user to pass DIGEST authentication, or you can turn off DIGEST authentication and just rely on the client certificate
 
* this works with or without a challenge password: you can still demand the local user to pass DIGEST authentication, or you can turn off DIGEST authentication and just rely on the client certificate
  
!! Using it in practice - with Jitsi
+
== Using it in practice - with Jitsi ==
  
 
Jitsi is an excellent, free and open source softphone.  It has support for mutual TLS authentication.
 
Jitsi is an excellent, free and open source softphone.  It has support for mutual TLS authentication.
Line 15: Line 15:
 
This guide explains how to use that feature with ''repro''
 
This guide explains how to use that feature with ''repro''
  
!! Minimum requirements
+
== Minimum requirements ==
  
 
* Require repro v1.8.2 or greater
 
* Require repro v1.8.2 or greater
Line 27: Line 27:
 
* Normal CN certificates were tested (without subjectAltName or other extensions - that is for another day)
 
* Normal CN certificates were tested (without subjectAltName or other extensions - that is for another day)
  
!! Setup the repro server
+
== Setup the repro server ==
  
 
* Install the latest Debian 7.0 wheezy build
 
* Install the latest Debian 7.0 wheezy build
Line 33: Line 33:
  
 
<code>
 
<code>
# apt-get update
+
# apt-get update
# apt-get install repro openssl
+
# apt-get install repro openssl
 
</code>
 
</code>
 +
 +
* Create server certificates (note we are giving examples for '''pocock.com.au''' - insert your own domain instead)
 +
 +
<code>
 +
# openssl genrsa -out /etc/repro/ssl/domain_key_pocock.com.au.pem 4096
 +
# chmod 0640 /etc/repro/ssl/domain_key_pocock.com.au.pem
 +
# chgrp repro /etc/repro/ssl/domain_key_pocock.com.au.pem
 +
# openssl req -new -key /etc/repro/ssl/domain_key_pocock.com.au.pem -out /etc/repro/ssl/pocock.com.au.csr -subj '/CN=pocock.com.au'
 +
# cat /etc/repro/ssl/pocock.com.au.csr
 +
</code>
 +
 +
* Go to the CACert.org certificate request web form.  Cut and paste the contents of the CSR file (the output of the ''cat'' command)
 +
* The CA will now give you a certificate.  Install it on the repro server:
 +
 +
<code>
 +
# cat > /etc/repro/ssl/domain_cert_pocock.com.au.pem << EOF
 +
-----BEGIN CERTIFICATE-----
 +
MIIF5zCCA8+gAwIBAgIDAQKKMA0GCSqGSIb3DQEBBQUAMFQxFDASBgNVBAoTC0NB
 +
Y2VydCBJbmMuMR4wHAYDVQQLExVodHRwOi8vd3d3LkNBY2VydC5vcmcxHDAaBgNV
 +
BAMTE0NBY2VydCBDbGFzcyAzIFJvb3QwHhcNMTIwODAxMTQzOTA3WhcNMTQwODAx
 +
.
 +
.
 +
.
 +
vcx9+LYSwVLCr33NkDx9zqBn3Qp2ZcaUxOdSo/QxdnE2Wj7J06D309RuDRCxZA7E
 +
cvfc3qE1Q0ESbEOAmN+ZYHhCHZjKe3jNlxED
 +
-----END CERTIFICATE-----
 +
EOF
 +
</code>
 +
 +
* Now edit the repro config file, /etc/repro/repro.config
 +
 +
<code>
 +
# vi /etc/repro/repro.config
 +
</code>
 +
 +
* Here is a sample of the config settings that you change from defaults:
 +
 +
IPAddress = 195.8.117.19
 +
UDPPort = 0
 +
TCPPort = 0
 +
TLSPort = 5061
 +
DTLSPort = 0
 +
TLSDomainName = pocock.com.au
 +
TLSClientVerification = Mandatory
 +
TLSUseEmailAsSIP = true
 +
Transport1Interface = 195.8.117.19:5061
 +
Transport1Type = TLS
 +
Transport1TlsDomain = pocock.com.au
 +
Transport1TlsClientVerification = Mandatory
 +
Transport1RecordRouteUri = sip:pocock.com.au;transport=TLS
 +
HttpAdminPassword = admin
 +
RecordRouteUri = sip:pocock.com.au;transport=tls
 +
ForceRecordRouting = true
 +
EnumSuffixes = e164.arpa, sip5060.net, e164.org
 +
DisableOutbound = false
 +
OutboundVersion = 5626
 +
EnableFlowTokens = false
 +
ClientNatDetectionMode = DISABLED
 +
FlowTimer = 0
 +
EnableCertificateAuthenticator = True
 +
DisableAuth = true
 +
 +
* Things you MUST change in the sample config file above:
 +
** all instances of the domain '''pocock.com.au''' should be replaced with your domain
 +
** all instances of the IP address '''195.8.117.19''' should be replaced with your IP address
 +
** all the passwords ('''HttpAdminPassword''')
 +
* Notice that UDP and TCP ports are '''0''' to disable them --- when you rely on TLS authentication, you don't want non-TLS users to connect.
 +
 +
* Now you can start the proxy
 +
 +
# /etc/init.d/repro start
 +
 +
== Getting a client certificate for Jitsi ==
 +
 +
* An email certificate is sufficient - it does not need to have a dedicated SIP extension in the certificate
 +
 +
* The email address can be in the Common Name (that is how it was for this test) - ''repro'' will accept email addresses in '''subjectAltName'' too
 +
 +
* You typically want to create the keystore on the machine where you will run Jitsi (or create it on another machine and then copy it to the Jitsi machine)
 +
 +
* Generate the keypair and the certificate request (CSR) for the CA, set a password (we use '''mysecret''' in these examples):
 +
 +
$ keytool -genkey -alias jitsi1 -keyalg RSA -keysize 4096  -keystore  ~/.jitsi.keytool -dname 'CN=daniel@pocock.com.au'
 +
Enter keystore password: 
 +
Re-enter new password:
 +
Enter key password for <jitsi1>
 +
(RETURN if same as keystore password): 
 +
$ keytool -certreq -alias jitsi1  -file /tmp/jitsi1.csr -keystore ~/.jitsi.keytool -storepass mysecret
 +
$ cat /tmp/jitsi1.csr
 +
-----BEGIN NEW CERTIFICATE REQUEST-----
 +
MIIEZDCCAkwCAQAwHzEdMBsGA1UEAwwUZGFuaWVsQHBvY29jay5jb20uYXUwggIiMA0GCSqGSIb3
 +
DQEBAQUAA4ICDwAwggIKAoICAQC/ySJt3ZNulDnWG7MtrE+Y6Rkl6ln/ovdefxFdoaBSkg4Bqg8K
 +
.
 +
.
 +
.
 +
cfsbPXSEcdZTYKzPaQpTtkCeWMRKh5R4M61IOd40tANhVbZbf32sZlAeRos7
 +
-----END NEW CERTIFICATE REQUEST-----
 +
 +
* Log in to CAcert.org.  Follow the link to create a '''Client certificate'''.  Cut and paste the certificate request text into the CAcert.org web form.
 +
 +
* CACert.org will give you a certificate, put it on the Jitsi machine in a file called /tmp/jitsi1.crt:
 +
 +
# cat > /tmp/jitsi1.crt << EOF
 +
-----BEGIN CERTIFICATE-----
 +
MIIF5zCCA8+gAwIBAgIDAQKKMA0GCSqGSIb3DQEBBQUAMFQxFDASBgNVBAoTC0NB
 +
Y2VydCBJbmMuMR4wHAYDVQQLExVodHRwOi8vd3d3LkNBY2VydC5vcmcxHDAaBgNV
 +
BAMTE0NBY2VydCBDbGFzcyAzIFJvb3QwHhcNMTIwODAxMTQzOTA3WhcNMTQwODAx
 +
.
 +
.
 +
.
 +
vcx9+LYSwVLCr33NkDx9zqBn3Qp2ZcaUxOdSo/QxdnE2Wj7J06D309RuDRCxZA7E
 +
cvfc3qE1Q0ESbEOAmN+ZYHhCHZjKe3jNlxED
 +
-----END CERTIFICATE-----
 +
EOF
 +
 +
* Import the CA root certificate into the keystore (otherwise keytool won't like the CAcert.org root that signs your client certificate).  We assume you are on a Debian system with a copy of the CAcert.org roots in '''/etc/ssl/certs/cacert.org.pem''':
 +
 +
$ keytool -import -alias root -keystore ~/.jitsi.keytool -storepass mysecret -trustcacerts -file /etc/ssl/certs/cacert.org.pem
 +
...
 +
Trust this certificate? [no]:  '''yes'''
 +
Certificate was added to keystore
 +
 +
* Now import the reply from the CA:
 +
 +
$ keytool -importcert -alias jitsi1 -file /tmp/jitsi1.crt -keystore ~/.jitsi.keytool -storepass jitsi1
 +
Certificate reply was installed in keystore
 +
 +
== Setting up the account in the repro web interface ==
 +
 +
* Go to the repro web interface, be default, it listens on port 5080
 +
 +
* Log in using the password you set in the '''repro.config''' file
 +
 +
* Click '''Domains''' and add your domain.  Leave the port blank.
 +
 +
* Click '''Add User''' and add your user name (must match the user portion of the email address in your client certificate)
 +
 +
* At this point, you could check in the database, make sure the user exists in the '''users''' table.  Check the '''syslog''' if it didn't work.
 +
 +
== Setting up Jitsi ==
 +
 +
* Go to the '''Tools''' menu, click '''Options''', and find the '''Advanced''' tab.
 +
 +
* Click '''SIP''' and then remove the check marks next to '''SSLv2Hello''' and '''SSLv3'''.  Only the '''TLSv1''' option should have a check mark.
 +
 +
* You '''must restart Jitsi''' after that change
 +
 +
* Click '''TLS Configuration''' and the '''Add''' button.
 +
** In the '''Display Name''', put some arbitrary name, for example '''testcert'''
 +
** Click the '''Browse''' button and locate the file '''~/.jitsi.keytool''' that you created.  Click '''OK''' to dismiss the file chooser dialog.
 +
** Click the '''Type''' pulldown and choose the '''jks''' options
 +
** In the '''Password''' field, put '''mysecret''', or whatever password you used with the '''keytool''' command in earlier steps.
 +
** In the field '''Alias name in KeyStore, choose '''jitsi1''' or whatever alias name you used with '''keytool''' in earlier steps.
 +
** Now click '''OK'''
 +
* Your certificate details should appear in the table in the '''Options''' window
 +
* Now go to the '''Accounts''' tab and click the '''Add''' button
 +
** In the '''Network''' menu, choose '''SIP'''.
 +
** Enter the email address as the '''SIP Id'''.  Leave the '''Password''' field blank.
 +
** Click the '''Advanced''' button.
 +
** Go to the '''Connection''' tab
 +
** In the '''Client TLS certificate''' pull down, choose the name that matches the '''Display Name''' you chose when you were in the '''TLS Configuration''' panel.
 +
** Click '''Next''' and accept the settings
 +
* Jitsi will try and connect to your ''repro'' SIP proxy
 +
* If it doesn't work, try restarting Jitsi, use the '''Quit''' option in the menu - sometimes it doesn't appear to recognise the certificate until after a restart
 +
* You may get a warning to tell you that Jitsi doesn't trust the server's certificate.  For testing, just click the '''Continue Anyway''' button.
 +
** For production use, it is recommended that you either use a CA trusted by the JRE, or add your CA certificate to the JRE's built in keystore.
 +
* You may get a popup for '''jks authentication''', with a message like ''The jks server has requested your authentication''.  In the '''Password''' box, insert the password '''mysecret''', or whatever password you used with the '''keytool''' command in earlier steps.
 +
* You should now see the green light that says you are '''Online'''
 +
 +
== If it doesn't work ==
 +
 +
* In the ''repro'' web interface, you can click the '''REGISTRATIONS''' menu link to see which users are connected successfully
 +
 +
* Look at any console output from Jitsi
 +
 +
* You can run ''repro'' from the command line, for example:
 +
 +
# /etc/init/repro stop
 +
# /usr/sbin/repro /etc/repro/repro.config --Daemonize=false --LoggingType=cout --LogLevel=STACK

Latest revision as of 11:48, 1 August 2012

Background[edit]

As of reSIProcate 1.8, the repro proxy supports Mutual (client) TLS authentication.

This means various things:

  • external users can be trusted based on the client certificate they present
  • local users can be trusted based on the client certificate they present
  • this works with or without a challenge password: you can still demand the local user to pass DIGEST authentication, or you can turn off DIGEST authentication and just rely on the client certificate

Using it in practice - with Jitsi[edit]

Jitsi is an excellent, free and open source softphone. It has support for mutual TLS authentication.

This guide explains how to use that feature with repro

Minimum requirements[edit]

  • Require repro v1.8.2 or greater
  • Require Jitsi build 3912 or later (tested with 4142, the nightly build from 31 July 2012)

Other comments about the environment where this was tested:

  • Jitsi on a Debian 6.0 (squeeze, amd64) system with Oracle JRE 1.6.24
  • repro on a Debian 7.0 (wheezy pre-release, i386)
  • Free 4096 bit RSA certificates from [[1]] used on both client and server
  • Normal CN certificates were tested (without subjectAltName or other extensions - that is for another day)

Setup the repro server[edit]

  • Install the latest Debian 7.0 wheezy build
  • Install the repro package:

# apt-get update
# apt-get install repro openssl

  • Create server certificates (note we are giving examples for pocock.com.au - insert your own domain instead)

# openssl genrsa -out /etc/repro/ssl/domain_key_pocock.com.au.pem 4096
# chmod 0640 /etc/repro/ssl/domain_key_pocock.com.au.pem
# chgrp repro /etc/repro/ssl/domain_key_pocock.com.au.pem
# openssl req -new -key /etc/repro/ssl/domain_key_pocock.com.au.pem -out /etc/repro/ssl/pocock.com.au.csr -subj '/CN=pocock.com.au'
# cat /etc/repro/ssl/pocock.com.au.csr

  • Go to the CACert.org certificate request web form. Cut and paste the contents of the CSR file (the output of the cat command)
  • The CA will now give you a certificate. Install it on the repro server:

# cat > /etc/repro/ssl/domain_cert_pocock.com.au.pem << EOF
-----BEGIN CERTIFICATE-----
MIIF5zCCA8+gAwIBAgIDAQKKMA0GCSqGSIb3DQEBBQUAMFQxFDASBgNVBAoTC0NB
Y2VydCBJbmMuMR4wHAYDVQQLExVodHRwOi8vd3d3LkNBY2VydC5vcmcxHDAaBgNV
BAMTE0NBY2VydCBDbGFzcyAzIFJvb3QwHhcNMTIwODAxMTQzOTA3WhcNMTQwODAx
.
.
.
vcx9+LYSwVLCr33NkDx9zqBn3Qp2ZcaUxOdSo/QxdnE2Wj7J06D309RuDRCxZA7E
cvfc3qE1Q0ESbEOAmN+ZYHhCHZjKe3jNlxED
-----END CERTIFICATE-----
EOF

  • Now edit the repro config file, /etc/repro/repro.config

# vi /etc/repro/repro.config

  • Here is a sample of the config settings that you change from defaults:
IPAddress = 195.8.117.19
UDPPort = 0
TCPPort = 0
TLSPort = 5061
DTLSPort = 0
TLSDomainName = pocock.com.au
TLSClientVerification = Mandatory
TLSUseEmailAsSIP = true
Transport1Interface = 195.8.117.19:5061
Transport1Type = TLS
Transport1TlsDomain = pocock.com.au
Transport1TlsClientVerification = Mandatory
Transport1RecordRouteUri = sip:pocock.com.au;transport=TLS
HttpAdminPassword = admin
RecordRouteUri = sip:pocock.com.au;transport=tls
ForceRecordRouting = true
EnumSuffixes = e164.arpa, sip5060.net, e164.org
DisableOutbound = false
OutboundVersion = 5626
EnableFlowTokens = false
ClientNatDetectionMode = DISABLED
FlowTimer = 0
EnableCertificateAuthenticator = True
DisableAuth = true
  • Things you MUST change in the sample config file above:
    • all instances of the domain pocock.com.au should be replaced with your domain
    • all instances of the IP address 195.8.117.19 should be replaced with your IP address
    • all the passwords (HttpAdminPassword)
  • Notice that UDP and TCP ports are 0 to disable them --- when you rely on TLS authentication, you don't want non-TLS users to connect.
  • Now you can start the proxy
# /etc/init.d/repro start

Getting a client certificate for Jitsi[edit]

  • An email certificate is sufficient - it does not need to have a dedicated SIP extension in the certificate
  • The email address can be in the Common Name (that is how it was for this test) - repro will accept email addresses in 'subjectAltName too
  • You typically want to create the keystore on the machine where you will run Jitsi (or create it on another machine and then copy it to the Jitsi machine)
  • Generate the keypair and the certificate request (CSR) for the CA, set a password (we use mysecret in these examples):
$ keytool -genkey -alias jitsi1 -keyalg RSA -keysize 4096  -keystore  ~/.jitsi.keytool -dname 'CN=daniel@pocock.com.au'

Enter keystore password: Re-enter new password: Enter key password for <jitsi1> (RETURN if same as keystore password):

$ keytool -certreq -alias jitsi1   -file /tmp/jitsi1.csr -keystore ~/.jitsi.keytool -storepass mysecret
$ cat /tmp/jitsi1.csr 
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIEZDCCAkwCAQAwHzEdMBsGA1UEAwwUZGFuaWVsQHBvY29jay5jb20uYXUwggIiMA0GCSqGSIb3
DQEBAQUAA4ICDwAwggIKAoICAQC/ySJt3ZNulDnWG7MtrE+Y6Rkl6ln/ovdefxFdoaBSkg4Bqg8K
.
.
.
cfsbPXSEcdZTYKzPaQpTtkCeWMRKh5R4M61IOd40tANhVbZbf32sZlAeRos7
-----END NEW CERTIFICATE REQUEST-----
  • Log in to CAcert.org. Follow the link to create a Client certificate. Cut and paste the certificate request text into the CAcert.org web form.
  • CACert.org will give you a certificate, put it on the Jitsi machine in a file called /tmp/jitsi1.crt:
# cat > /tmp/jitsi1.crt << EOF
-----BEGIN CERTIFICATE-----
MIIF5zCCA8+gAwIBAgIDAQKKMA0GCSqGSIb3DQEBBQUAMFQxFDASBgNVBAoTC0NB
Y2VydCBJbmMuMR4wHAYDVQQLExVodHRwOi8vd3d3LkNBY2VydC5vcmcxHDAaBgNV
BAMTE0NBY2VydCBDbGFzcyAzIFJvb3QwHhcNMTIwODAxMTQzOTA3WhcNMTQwODAx
.
.
.
vcx9+LYSwVLCr33NkDx9zqBn3Qp2ZcaUxOdSo/QxdnE2Wj7J06D309RuDRCxZA7E
cvfc3qE1Q0ESbEOAmN+ZYHhCHZjKe3jNlxED
-----END CERTIFICATE-----
EOF
  • Import the CA root certificate into the keystore (otherwise keytool won't like the CAcert.org root that signs your client certificate). We assume you are on a Debian system with a copy of the CAcert.org roots in /etc/ssl/certs/cacert.org.pem:
$ keytool -import -alias root -keystore ~/.jitsi.keytool -storepass mysecret -trustcacerts -file /etc/ssl/certs/cacert.org.pem
...
Trust this certificate? [no]:  yes
Certificate was added to keystore
  • Now import the reply from the CA:
$ keytool -importcert -alias jitsi1 -file /tmp/jitsi1.crt -keystore ~/.jitsi.keytool -storepass jitsi1 
Certificate reply was installed in keystore

Setting up the account in the repro web interface[edit]

  • Go to the repro web interface, be default, it listens on port 5080
  • Log in using the password you set in the repro.config file
  • Click Domains and add your domain. Leave the port blank.
  • Click Add User and add your user name (must match the user portion of the email address in your client certificate)
  • At this point, you could check in the database, make sure the user exists in the users table. Check the syslog if it didn't work.

Setting up Jitsi[edit]

  • Go to the Tools menu, click Options, and find the Advanced tab.
  • Click SIP and then remove the check marks next to SSLv2Hello and SSLv3. Only the TLSv1 option should have a check mark.
  • You must restart Jitsi after that change
  • Click TLS Configuration and the Add button.
    • In the Display Name, put some arbitrary name, for example testcert
    • Click the Browse button and locate the file ~/.jitsi.keytool that you created. Click OK to dismiss the file chooser dialog.
    • Click the Type pulldown and choose the jks options
    • In the Password field, put mysecret, or whatever password you used with the keytool command in earlier steps.
    • In the field Alias name in KeyStore, choose jitsi1 or whatever alias name you used with keytool in earlier steps.
    • Now click OK
  • Your certificate details should appear in the table in the Options window
  • Now go to the Accounts tab and click the Add button
    • In the Network menu, choose SIP.
    • Enter the email address as the SIP Id. Leave the Password field blank.
    • Click the Advanced button.
    • Go to the Connection tab
    • In the Client TLS certificate pull down, choose the name that matches the Display Name you chose when you were in the TLS Configuration panel.
    • Click Next and accept the settings
  • Jitsi will try and connect to your repro SIP proxy
  • If it doesn't work, try restarting Jitsi, use the Quit option in the menu - sometimes it doesn't appear to recognise the certificate until after a restart
  • You may get a warning to tell you that Jitsi doesn't trust the server's certificate. For testing, just click the Continue Anyway button.
    • For production use, it is recommended that you either use a CA trusted by the JRE, or add your CA certificate to the JRE's built in keystore.
  • You may get a popup for jks authentication, with a message like The jks server has requested your authentication. In the Password box, insert the password mysecret, or whatever password you used with the keytool command in earlier steps.
  • You should now see the green light that says you are Online

If it doesn't work[edit]

  • In the repro web interface, you can click the REGISTRATIONS menu link to see which users are connected successfully
  • Look at any console output from Jitsi
  • You can run repro from the command line, for example:
# /etc/init/repro stop
# /usr/sbin/repro /etc/repro/repro.config --Daemonize=false --LoggingType=cout --LogLevel=STACK