[Other doc versions]
[Doc downloads]
[Other doc versions]
[Doc downloads]
Stash is now known as Bitbucket Server.
See the
of this page, or visit the Bitbucket Server documentation home page.
This page in intended for administrators setting up Stash for a small team, and describes how to enable SSL access for Tomcat, the webserver distributed with Stash, using a self-signed certificate. You should consider running Stash with HTTPS (HTTP over SSL) and making secure access mandatory, if Stash will be internet-facing where usernames, passwords and other proprietary data may be at risk.
Those setting up a production instance should consider using a CA certificate, briefly described below.
Be aware that you can set up Stash to run behind a web server, such as Apache HTTP Server. To secure Stash when Apache HTTP Server acts as a reverse proxy for Stash see Integrating Stash with Apache HTTP Server.
Please note that Atlassian Support will refer SSL-related support to the issuing authority for the certificate. The documentation on this page is for reference only.
Users may receive a warning that the site is untrusted and have to "accept" the certificate before they can access the site. This usually will only occur the first time they access the site.
The following approach to creating a certificate uses Java's keytool, for Java 1.6. Other tools for generating certificates are available.
To generate a self-signed certificate:
Log in with the user account that Stash will run under, and run the following command:
Windows | "%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA
|
---|---|
Linux, MacOS and Unix | $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA |
This will create (if it doesn't already exist) a new .keystore
file located in the home directory of the user you used to run the keytool command.
次の点にご注意ください。
What is your first and last name?
conf/server.xml
by adding the following attribute to the <Connector/>
tag: keystorePass="<password value>"
To configure HTTPS in Tomcat:
Edit conf/server.xml
and, at the bottom, before the </Service>
tag, add this section (or uncomment it if it already exists):
<Connector port="8443" maxHttpHeaderSize="8192" SSLEnabled="true" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" useBodyEncodingForURI="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />
This enables SSL access on port 8443 (the default for HTTPS is 443, but 8443 is used instead of 443 to avoid conflicts).
Here are some troubleshooting tips if you are using a self-signed key created by keytool, as described above.
When you enter "https://localhost:8443/" in your browser, if you get a message such as "Cannot establish a connection to the server at localhost:8443", look for error messages in your logs/catalina.out
log file. Here are some possible errors with explanations:
Some people have reported errors when uploading attachments over SSL using IE. This is due to an IE bug, and can be fixed in Apache by setting:
BrowserMatch ".MSIE." \ nokeepalive ssl-unclean-shutdown \ downgrade-1.0 force-response-1.0
Google has plenty more on this.
java.io.FileNotFoundException: /home/user/.keystore (No such file or directory)
これは、Tomcat がキーストアを見つけられなかったことを意味します。キーツール ユーティリティは、現在のユーザーのホーム ディレクトリに .keystore
という名称のキーストアをファイルとして作成します。Unix / Linux ではホーム ディレクトリは多くの場合 /home/<username>
です。Windows では多くの場合 C:\User\<UserName>
です。
Make sure you are running Stash as the same user who created the keystore. If this is not the case, or if you are running Stash on Windows as a service, you will need to specify where the keystore file is in conf/server.xml
. Add the following attribute to the connector tag you uncommented:
keystoreFile="<Keystore ファイルの場所>"
java.io.IOException: Keystore was tampered with, or password was incorrect
"changeit" 以外のパスワードが使われています。Tomcat のキー パスワードとキーストア パスワードの両方で "changeit" を使用するか、異なるパスワードを使用する場合は、前述のように Connector タグの keystorePass
属性にそれを指定する必要があります。
java.io.IOException: Cannot recover key
Tomcat のキーストアパスワードとキーパスワードに異なるパスワードが使われていることを意味します。この二つのパスワードは同一でなければなりません。
javax.net.ssl.SSLException:有効化されている SSL 暗号化スイートと一致する、利用可能な証明書がありません。
キーストア内に複数の証明書がある場合、conf/server.xml
内の SSL Connector タグで指定がある場合を除き、Tomcat は最初に返された証明書を使用します。
次の例に示すように、コメントを解除した Connector タグに keyAlias
属性を追加し、関連するエイリアスを設定します。
<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" useBodyEncodingForURI="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="/opt/local/.keystore" keystorePass="removed" keyAlias="tomcat"/>
APR では異なる SSL エンジンが使用されており、次のような例外処理情報がログに記録されることがあります。
SEVERE: Failed to initialize connector [Connector[HTTP/1.1-8443]] LifecycleException: Protocol handler initialization failed: java.lang.Exception: No Certificate file specified or invalid file format
これは APR コネクターが OpenSSL を使用しており、キーストアの使用方法が異なることが原因です。この問題の解決策は 2 通りあります :
Edit the server.xml so that the SSL Connector tag you just uncommented specifies the Http11Protocol instead of the APR protocol:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol" maxHttpHeaderSize="8192" SSLEnabled="true" keystoreFile="${user.home}/.keystore" maxThreads="150" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true" />
This is only possible if you have PEM encoded certificates and private keys. If you have used OpenSSL to generate your key, then you will have these PEM encoded files - in all other cases contact your certificate provider for assistance.
<Connector port="8443" maxThreads="200" scheme="https" secure="true" SSLEnabled="true" SSLCertificateFile="${user.home}/certificate.pem" SSLCertificateKeyFile="${user.home}/key.pem" clientAuth="optional" SSLProtocol="TLSv1"/>
To enable client authentication in Tomcat, ensure that the value of the clientAuth
attribute in your Connector
element of your Tomcat's server.xml
file is true
.
<Connector ... clientAuth="true" ... />
For more information about Connector
element parameters, please refer to the 'SSL Support' section of the Tomcat 6.0 documentation.
If Stash will run as the user who ran the keytool --genkey
command, you do not need to export the certificate.
You may need to export the self-signed certificate, so that you can import it into a different keystore, if Stash will not be run as the user executing keytool --genkey
. You can do so with the following command:
Windows | "%JAVA_HOME%\bin\keytool" -export -alias tomcat -file file.cer |
---|---|
Linux, MacOS and Unix | $JAVA_HOME/bin/keytool -export -alias tomcat -file file.cer |
If you generate the certificate as one user and run Stash as another, you'll need to do the certificate export as the generating user and the import as the target user.
Digital certificates that are issued by trusted 3rd party CAs (Certification Authorities) provide verification that your website does indeed represent your company.
When running Stash in a production environment, you will need a certificate issued by a CA, such as VeriSign, Thawte or TrustCenter. The instructions below are adapted from the Tomcat documentation.
First, you will generate a local certificate and create a 'certificate signing request' (CSR) based on that certificate. You then submit the CSR to your chosen certificate authority. The CA will use that CSR to generate a certificate for you.
keytool
utility to generate a local certificate, as described in the section above.Use the keytool
utility to generate a CSR, replacing the text <MY_KEYSTORE_FILENAME>
with the path to and file name of the .keystore
file generated for your local certificate:
Windows | "%JAVA_HOME%\bin\keytool" -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME> |
---|---|
Linux, MacOS and Unix | $JAVA_HOME/bin/keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME> |
certreq.csr
to your chosen certificate authority. Refer to the documentation on the CA's website to find out how to do this.Import the new certificate into your local keystore. Assuming your certificate is called "file.cer" whether obtained from a CA or self-generated, the following command will add the certificate to the keystore:
Windows | "%JAVA_HOME%\bin\keytool" -import -alias tomcat -file file.cer |
---|---|
Linux, MacOS and Unix | $JAVA_HOME/bin/keytool -import -alias tomcat -file file.cer |
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.