Message-ID: <1933737228.5541.1710836876212.JavaMail.appbox@confluence> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_5540_344837778.1710836876212" ------=_Part_5540_344837778.1710836876212 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html How to Connect to Server using SSL and Client Certificate</title= > <!--[if gte mso 9]> <xml> <o:OfficeDocumentSettings> <o:TargetScreenSize>1024x640</o:TargetScreenSize> <o:PixelsPerInch>72</o:PixelsPerInch> <o:AllowPNG/> </o:OfficeDocumentSettings> <w:WordDocument> <w:View>Print</w:View> <w:Zoom>90</w:Zoom> <w:DoNotOptimizeForBrowser/> </w:WordDocument> </xml> <![endif]--> <style> <!-- @page Section1 { size: 8.5in 11.0in; margin: 1.0in; mso-header-margin: .5in; mso-footer-margin: .5in; mso-paper-source: 0; } table { border: solid 1px; border-collapse: collapse; } table td, table th { border: solid 1px; padding: 5px; } td { page-break-inside: avoid; } tr { page-break-after: avoid; } div.Section1 { page: Section1; } /* Confluence print stylesheet. Common to all themes for print medi= a */ /* Full of !important until we improve batching for print CSS */ @media print { #main { padding-bottom: 1em !important; /* The default padding of 6em is to= o much for printouts */ } body { font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 10pt; line-height: 1.2; } body, #full-height-container, #main, #page, #content, .has-personal-sid= ebar #content { background: #fff !important; color: #000 !important; border: 0 !important; width: 100% !important; height: auto !important; min-height: auto !important; margin: 0 !important; padding: 0 !important; display: block !important; } a, a:link, a:visited, a:focus, a:hover, a:active { color: #000; } #content h1, #content h2, #content h3, #content h4, #content h5, #content h6 { font-family: Arial, Helvetica, FreeSans, sans-serif; page-break-after: avoid; } pre { font-family: Monaco, "Courier New", monospace; } #header, .aui-header-inner, #navigation, #sidebar, .sidebar, #personal-info-sidebar, .ia-fixed-sidebar, .page-actions, .navmenu, .ajs-menu-bar, .noprint, .inline-control-link, .inline-control-link a, a.show-labels-editor, .global-comment-actions, .comment-actions, .quick-comment-container, #addcomment { display: none !important; } /* CONF-28544 cannot print multiple pages in IE */ #splitter-content { position: relative !important; } .comment .date::before { content: none !important; /* remove middot for print view */ } h1.pagetitle img { height: auto; width: auto; } .print-only { display: block; } #footer { position: relative !important; /* CONF-17506 Place the footer at en= d of the content */ margin: 0; padding: 0; background: none; clear: both; } #poweredby { border-top: none; background: none; } #poweredby li.print-only { display: list-item; font-style: italic; } #poweredby li.noprint { display: none; } /* no width controls in print */ .wiki-content .table-wrap, .wiki-content p, .panel .codeContent, .panel .codeContent pre, .image-wrap { overflow: visible !important; } /* TODO - should this work? */ #children-section, #comments-section .comment, #comments-section .comment .comment-body, #comments-section .comment .comment-content, #comments-section .comment p { page-break-inside: avoid; } #page-children a { text-decoration: none; } /** hide twixies the specificity here is a hack because print styles are getting loaded before the base styles. */ #comments-section.pageSection .section-header, #comments-section.pageSection .section-title, #children-section.pageSection .section-header, #children-section.pageSection .section-title, .children-show-hide { padding-left: 0; margin-left: 0; } .children-show-hide.icon { display: none; } /* personal sidebar */ .has-personal-sidebar #content { margin-right: 0px; } .has-personal-sidebar #content .pageSection { margin-right: 0px; } .no-print, .no-print * { display: none !important; } } --> </style> </head> <body> <h1>How to Connect to Server using SSL and Client Certificate</h1> <div class=3D"Section1"> <div class=3D"panel" style=3D"border-width: 1px;"> <div class=3D"panelContent">=20 <p>This article applies to: <strong>Deskzilla 1.x-2.x, JIRA Client 1.x-2.x<= /strong>, and connecting to Bugzilla and JIRA servers via https://... conne= ctions.<br> For clarity, this article is written about JIRA Client and JIRA= , but it applies to Deskzilla / Bugzilla as well.</p>=20 </div> </div>=20 <h3 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-Problem">Problem= </h3>=20 <p>You need to use a client SSL certificate to connect to the server. In mo= st cases, client certificate is not used. But in some high-security configu= rations it may be required. </p>=20 <p>When a connection is attempted to a server that requires a client certif= icate, it may result in the following error from JIRA Client: </p>=20 <div class=3D"panel" style=3D"border-width: 1px;"> <div class=3D"panelContent">=20 <p>Connection problem: Software caused connection abort: recv failed</p>=20 </div> </div>=20 <p>JIRA Client does not have a direct way to specify a certificate. This ar= ticle explains how to set up JIRA Client for using client certificate with = standard Java tools.</p>=20 <div class=3D"confluence-information-macro confluence-information-macro-tip= "> <span class=3D"aui-icon aui-icon-small aui-iconfont-approve confluence-info= rmation-macro-icon"></span> <div class=3D"confluence-information-macro-body"> <p>The server certificate, which is used by the server to authenticate the = connection, may be self-signed. In that case you will also need to apply th= e <a href=3D"/display/kb/Connecting+to+a+Bugzilla%2C+JIRA+server+with+a+sel= f-signed+SSL+certificate">solution for self-signed server certificate</a>.<= /p> </div> </div>=20 <h3 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-Solution">Soluti= on</h3>=20 <p>The solution is to create a secure file for storing your client certific= ate and specify it in command-line properties for JIRA Client.</p>=20 <h4 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-1.ObtainPKCS12(.= p12)filewiththeclientcertificate">1. Obtain PKCS12 (.p12) file with the cli= ent certificate</h4>=20 <p>You may already have it, but if you don't, it's easy to export the certi= ficate from your browser. (We are assuming that you can access JIRA with yo= ur browser, hence the browser does have the certificate.)</p>=20 <div class=3D"confluence-information-macro confluence-information-macro-not= e"> <span class=3D"aui-icon aui-icon-small aui-iconfont-warning confluence-info= rmation-macro-icon"></span> <div class=3D"confluence-information-macro-body"> <p>When specifying password for the exported certificate, enter <strong>at = least 6 characters</strong>, and also <strong>without any space or special = characters</strong>. Otherwise you may not be able to proceed later.</p> </div> </div>=20 <p>To export client certificate from <strong>Firefox</strong>, open Tools |= Options menu, Advanced tab, and click on View Certificates. Select certifi= cate that matches your server and click Backup button. Enter a file name fo= r .p12 file, and then backup password. Remember backup password.</p>=20 <p>To export client certificate from <strong>Internet Explorer</strong>, op= en Tools | Internet Options dialog, Content tab, then click on Certificates= button. Find your certificate and click Export. Follow the wizard. Include= private key in export. Select PKCS 12 format (although the extension will = be PFX, you can rename it to P12). Don't include extra options. Enter passw= ord and remember it.</p>=20 <p>As a result of this step, you should have .p12 file, let's call it my-ce= rtificate.p12 and the password for it.</p>=20 <h4 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-2.CreateJavakeys= toreusingkeytool">2. Create Java keystore using keytool</h4>=20 <p>Use "keytool" program to transform the .p12 file. Keytool may be found i= n <JIRA Client Install Dir>\jre\bin (C:\Program Files\JIRA Client\jre= \bin), or in any Java installation on your computer.</p>=20 <p>Run the following command:</p>=20 <div class=3D"code panel pdl" style=3D"border-width: 1px;"> <div class=3D"codeContent panelContent pdl">=20 <pre class=3D"syntaxhighlighter-pre" data-syntaxhighlighter-params=3D"brush= : java; gutter: false; theme: Confluence" data-theme=3D"Confluence">keytool= -importkeystore -srckeystore c:\path\to\p12\my-certificate.p12 -srcstorety= pe pkcs12 -destkeystore c:\temporary\path\jiraclient.jks -deststoretype jk= s</pre>=20 </div> </div>=20 <p>Substitute path to the exported .p12 file instead of c:\path\to\p12\my-c= ertificate.p12, and any temporary directory instead of c:\temporary\path.</= p>=20 <p>Keytool will ask for password two times - for the source and destination= keystores. You should enter the password you created on the previous step = - every time. It will be <strong>the same password</strong> for both key st= ores. </p>=20 <div class=3D"confluence-information-macro confluence-information-macro-not= e"> <span class=3D"aui-icon aui-icon-small aui-iconfont-warning confluence-info= rmation-macro-icon"></span> <div class=3D"confluence-information-macro-body"> <p>If passwords are different, it may result in the same errors on the clie= nt side and the following error in the server logs:</p>=20 <div class=3D"code panel pdl" style=3D"border-width: 1px;"> <div class=3D"codeContent panelContent pdl">=20 <pre class=3D"syntaxhighlighter-pre" data-syntaxhighlighter-params=3D"brush= : java; gutter: false; theme: Confluence" data-theme=3D"Confluence">SSL Lib= rary Error: 336105671 error:140890C7:SSL routines:SSL3_GET_CLIENT_CERTIFICA= TE: peer did not return a certificate No CAs known to server for verification?<= /pre>=20 </div> </div> </div> </div>=20 <p>As a result of this step, you should have file jiraclient.jks in a tempo= rary directory.</p>=20 <h4 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-3.Placejiraclien= t.jksintoinstallationdirectoryandadjustshortcutforlaunchingJIRAClient">3. P= lace jiraclient.jks into installation directory and adjust shortcut for lau= nching JIRA Client</h4>=20 <p>Copy jiraclient.jks from the previous step to C:\Program Files\JIRA Clie= nt, or whereever you have JIRA Client installed.</p>=20 <p>To run JIRA Client with the client certificate, you will need to pass th= ree additional parameters via command-line. To avoid typing them each time,= you will need to modify the shortcut or script that you use to start JIRA = Client.</p>=20 <h5 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-OnWindows">On Wi= ndows</h5>=20 <p>Find "JIRA Client" start menu item (or other shortcut that you use to la= unch JIRA Client), <em>Right-Click</em> on it and select <em>Properties</em= >. The <em>Shortcut</em> tab will appear, with the <em>Target</em> field co= ntaining something like <em>"C:\Program Files\JIRA Client\bin\jiraclient.ex= e"</em>. </p>=20 <p>Click on the Target field and modify it so it says </p>=20 <div class=3D"code panel pdl" style=3D"border-width: 1px;"> <div class=3D"codeContent panelContent pdl">=20 <pre class=3D"syntaxhighlighter-pre" data-syntaxhighlighter-params=3D"brush= : java; gutter: false; theme: Confluence" data-theme=3D"Confluence">"C:\Pro= gram Files\JIRA Client\bin\jiraclient.exe" -J-Dforce.http.jre.executor=3Dtr= ue -J-Djavax.net.ssl.keyStore=3Djiraclient.jks -J-Djavax.net.ssl.keyStorePa= ssword=3D<your password created at step 1></pre>=20 </div> </div>=20 <p>Use copy&paste from this article to avoid typos. Substitute your pas= sword in place of <your password created at step 1>.</p>=20 <div class=3D"confluence-information-macro confluence-information-macro-tip= "> <span class=3D"aui-icon aui-icon-small aui-iconfont-approve confluence-info= rmation-macro-icon"></span> <div class=3D"confluence-information-macro-body"> <p>Note the quotes in this example. Don't put additional parameters inside = the quotes around the .exe file path.</p> </div> </div>=20 <h5 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-OnLinux">On Linu= x</h5>=20 <p>Modify "jiraclient.sh" script. Find line that says <em>JAVA_OPTIONS=3D"-= Xmx600m -Duse.metal=3Dtrue"</em>. Modify it so it says</p>=20 <div class=3D"code panel pdl" style=3D"border-width: 1px;"> <div class=3D"codeContent panelContent pdl">=20 <pre class=3D"syntaxhighlighter-pre" data-syntaxhighlighter-params=3D"brush= : java; gutter: false; theme: Confluence" data-theme=3D"Confluence"> JAVA_OPTIONS=3D"-Xmx600m -Duse.metal=3Dtrue -Dforce.http.jre.executor=3Dtru= e -Djavax.net.ssl.keyStore=3D/path/to/jiraclient.jks -Djavax.net.ssl.keySto= rePassword=3D<your password created at step 1>" </pre>=20 </div> </div>=20 <p>Note the quotes are around all the line. Use full path to specify the lo= cation of jiraclient.jks.</p>=20 <h5 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-OnMac">On Mac</h= 5>=20 <p>Right-click on JIRA Client application and select <em>Show Package Conte= nts</em>. Open <em>Contents</em> folder. Double-click on the <em>Info.plist= </em> file. Plist editor should start. Open <em>Java</em> section, then <em= >Properties</em> subsection. Use "+" button to add the following properties= :</p>=20 <div class=3D"table-wrap"> <table class=3D"confluenceTable"> <tbody>=20 <tr>=20 <th class=3D"confluenceTh"><p>Name</p></th>=20 <th class=3D"confluenceTh"><p>Value</p></th>=20 </tr>=20 <tr>=20 <td class=3D"confluenceTd"><p>force.http.jre.executor</p></td>=20 <td class=3D"confluenceTd"><p>true</p></td>=20 </tr>=20 <tr>=20 <td class=3D"confluenceTd"><p>javax.net.ssl.keyStore</p></td>=20 <td class=3D"confluenceTd"><p>/path/to/jiraclient.jks</p></td>=20 </tr>=20 <tr>=20 <td class=3D"confluenceTd"><p>javax.net.ssl.keyStorePassword</p></td>=20 <td class=3D"confluenceTd"><p><your password created at step 1></p></= td>=20 </tr>=20 </tbody> </table> </div>=20 <p>Use full path to specify the location of jiraclient.jks.</p>=20 <div class=3D"panel" style=3D"border-width: 1px;"> <div class=3D"panelHeader" style=3D"border-bottom-width: 1px;"> <b>For self-signed server certificates</b> </div> <div class=3D"panelContent">=20 <p>If the server uses a self-signed certificate (or a certificate signed by= an unknown CA), you will need to explicitly import server's certificate in= to the Java's trust keystore. (See <a href=3D"/display/kb/Connecting+to+a+B= ugzilla%2C+JIRA+server+with+a+self-signed+SSL+certificate">instructions</a>= .) By default, the trust keystore is called <em>cacerts</em> and it resides= in C:\Program Files\JIRA Client\jre\lib\security\cacerts. With the same me= thod you used for setting the three properties described above, it's possib= le to specify a different location for cacerts: you need to set <em>javax.n= et.ssl.trustStore</em> property to <em></path/to/your/cacerts></em>, = and, if the password is not default (<em>changeit</em>), set <em>javax.net.= ssl.trustStorePassword</em> property.</p>=20 </div> </div>=20 <h4 id=3D"HowtoConnecttoServerusingSSLandClientCertificate-Thisisit!">This = is it!</h4>=20 <p>Start JIRA Client. Try to connect. If it doesn't work, double-check that= </p>=20 <ul>=20 <li>jiraclient.jks file exists and has at least 500 bytes;</li>=20 <li>It is correctly pointed to using command-line properties;</li>=20 <li>you really launch the same shortcut / script that you have edited.</li>= =20 </ul>=20 <p>If all looks correct but it doesn't work, please contact support.</p> </div> </body> </html> ------=_Part_5540_344837778.1710836876212--