Fossil SCM
Expanded on the "Certificates" section of www/ssl.wiki to fill in some details. The key improvement is making the first line of the OpenSSL error when the CA trust store isn't set up searchable. As it was, you pretty much had to know the solution already in order to seek out this documentation!
Commit
b3c0c07c0703a21cf363d7481a33fa9056b6f06132dbc83bddfead155aa23465
Parent
c00e9123cb89aac…
1 file changed
+26
-13
+26
-13
| --- www/ssl.wiki | ||
| +++ www/ssl.wiki | ||
| @@ -104,25 +104,36 @@ | ||
| 104 | 104 | |
| 105 | 105 | |
| 106 | 106 | <h3 id="certs">Certificates</h3> |
| 107 | 107 | |
| 108 | 108 | To verify the identify of a server, TLS uses |
| 109 | -[https://en.wikipedia.org/wiki/X.509#Certificates|X.509 certificates]. | |
| 109 | +[https://en.wikipedia.org/wiki/X.509#Certificates|X.509 certificates], a | |
| 110 | +scheme that depends on a trust hierarchy of so-called | |
| 111 | +[https://en.wikipedia.org/wiki/Certificate_authority | Certificate | |
| 112 | +Authorities]. The tree of trust relationships ultimately ends in the | |
| 113 | +CA roots, which are considered the ultimate arbiters of who to trust in | |
| 114 | +this scheme. | |
| 115 | + | |
| 116 | +The question then is, what CA roots does Fossil trust? | |
| 110 | 117 | |
| 111 | -If you are using a self-signed certificate, you'll be asked if you want | |
| 118 | +If you are using a self-signed certificate, Fossil will initially not | |
| 119 | +know that it can trust your certificate, so you'll be asked if you want | |
| 112 | 120 | to accept the certificate the first time you communicate with the |
| 113 | 121 | server. Verify the certificate fingerprint is correct, then answer |
| 114 | -"always" to remember your decision. | |
| 122 | +"always" if you want Fossil to remember your decision. | |
| 115 | 123 | |
| 116 | 124 | If you are cloning from or syncing to Fossil servers that use a |
| 117 | -certificate signed by a | |
| 118 | -[https://en.wikipedia.org/wiki/Certificate_authority|certificate | |
| 119 | -authority] (CA), Fossil needs to know which CAs you trust to sign those | |
| 120 | -certificates. Fossil relies on the OpenSSL library to have some way to | |
| 121 | -check a trusted list of CA signing keys. | |
| 125 | +certificate signed by a well-known CA or one of its delegates, Fossil | |
| 126 | +still has to know which CA roots to trust. When this fails, you get a | |
| 127 | +big long error message that starts with this text: | |
| 128 | + | |
| 129 | +<pre> | |
| 130 | + SSL verification failed: unable to get local issuer certificate | |
| 131 | +</pre> | |
| 122 | 132 | |
| 123 | -There are two common ways this fails: | |
| 133 | +Fossil relies on the OpenSSL library to have some way to check a trusted | |
| 134 | +list of CA signing keys. There are two common ways this fails: | |
| 124 | 135 | |
| 125 | 136 | # <p>The OpenSSL library Fossil is linked to doesn't have a CA |
| 126 | 137 | signing key set at all, so that it initially trusts no certificates |
| 127 | 138 | at all.</p> |
| 128 | 139 | # <p>The OpenSSL library does have a CA cert set, but your Fossil server's |
| @@ -137,11 +148,13 @@ | ||
| 137 | 148 | fossil set --global ssl-ca-location /path/to/local-ca.pem |
| 138 | 149 | </pre> |
| 139 | 150 | |
| 140 | 151 | The use of <tt>--global</tt> with this option is common, since you may |
| 141 | 152 | have multiple reposotories served under certificates signed by that same |
| 142 | -CA. | |
| 153 | +CA. However, if you have a mix of publicly-signed and locally-signed | |
| 154 | +certificates, you might want to drop the <tt>--global</tt> flag and set | |
| 155 | +this option on a per-repository basis instead. | |
| 143 | 156 | |
| 144 | 157 | A common way to run into the broader first problem is that you're on |
| 145 | 158 | FreeBSD, which does not install a CA certificate set by default, even as |
| 146 | 159 | a dependency of the OpenSSL library. If you're using a certificate |
| 147 | 160 | signed by one of the major public CAs, you can solve this by installing |
| @@ -155,15 +168,15 @@ | ||
| 155 | 168 | certificate set, but it's not in a format that OpenSSL understands how |
| 156 | 169 | to use. Rather than try to find a way to convert the data format, you |
| 157 | 170 | may find it acceptable to use the same Mozilla NSS cert set. I do not |
| 158 | 171 | know of a way to easily get this from Mozilla themselves, but I did find |
| 159 | 172 | a [https://curl.haxx.se/docs/caextract.html|third party source] for the |
| 160 | -<tt>cacert.pem</tt> file. Install it somewhere on your system, then | |
| 161 | -point Fossil at it like so: | |
| 173 | +<tt>cacert.pem</tt> file. I suggest placing the file into your Windows | |
| 174 | +user home directory so that you can then point Fossil at it like so: | |
| 162 | 175 | |
| 163 | 176 | <pre> |
| 164 | - fossil set --global ssl-ca-location /path/to/cacert.pem | |
| 177 | + fossil set --global ssl-ca-location %userprofile%\cacert.pem | |
| 165 | 178 | </pre> |
| 166 | 179 | |
| 167 | 180 | This can also happen if you've linked Fossil to a version of OpenSSL |
| 168 | 181 | [#openssl-src|built from source]. That same <tt>cacert.pem</tt> fix can |
| 169 | 182 | work in that case, too. |
| 170 | 183 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -104,25 +104,36 @@ | |
| 104 | |
| 105 | |
| 106 | <h3 id="certs">Certificates</h3> |
| 107 | |
| 108 | To verify the identify of a server, TLS uses |
| 109 | [https://en.wikipedia.org/wiki/X.509#Certificates|X.509 certificates]. |
| 110 | |
| 111 | If you are using a self-signed certificate, you'll be asked if you want |
| 112 | to accept the certificate the first time you communicate with the |
| 113 | server. Verify the certificate fingerprint is correct, then answer |
| 114 | "always" to remember your decision. |
| 115 | |
| 116 | If you are cloning from or syncing to Fossil servers that use a |
| 117 | certificate signed by a |
| 118 | [https://en.wikipedia.org/wiki/Certificate_authority|certificate |
| 119 | authority] (CA), Fossil needs to know which CAs you trust to sign those |
| 120 | certificates. Fossil relies on the OpenSSL library to have some way to |
| 121 | check a trusted list of CA signing keys. |
| 122 | |
| 123 | There are two common ways this fails: |
| 124 | |
| 125 | # <p>The OpenSSL library Fossil is linked to doesn't have a CA |
| 126 | signing key set at all, so that it initially trusts no certificates |
| 127 | at all.</p> |
| 128 | # <p>The OpenSSL library does have a CA cert set, but your Fossil server's |
| @@ -137,11 +148,13 @@ | |
| 137 | fossil set --global ssl-ca-location /path/to/local-ca.pem |
| 138 | </pre> |
| 139 | |
| 140 | The use of <tt>--global</tt> with this option is common, since you may |
| 141 | have multiple reposotories served under certificates signed by that same |
| 142 | CA. |
| 143 | |
| 144 | A common way to run into the broader first problem is that you're on |
| 145 | FreeBSD, which does not install a CA certificate set by default, even as |
| 146 | a dependency of the OpenSSL library. If you're using a certificate |
| 147 | signed by one of the major public CAs, you can solve this by installing |
| @@ -155,15 +168,15 @@ | |
| 155 | certificate set, but it's not in a format that OpenSSL understands how |
| 156 | to use. Rather than try to find a way to convert the data format, you |
| 157 | may find it acceptable to use the same Mozilla NSS cert set. I do not |
| 158 | know of a way to easily get this from Mozilla themselves, but I did find |
| 159 | a [https://curl.haxx.se/docs/caextract.html|third party source] for the |
| 160 | <tt>cacert.pem</tt> file. Install it somewhere on your system, then |
| 161 | point Fossil at it like so: |
| 162 | |
| 163 | <pre> |
| 164 | fossil set --global ssl-ca-location /path/to/cacert.pem |
| 165 | </pre> |
| 166 | |
| 167 | This can also happen if you've linked Fossil to a version of OpenSSL |
| 168 | [#openssl-src|built from source]. That same <tt>cacert.pem</tt> fix can |
| 169 | work in that case, too. |
| 170 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -104,25 +104,36 @@ | |
| 104 | |
| 105 | |
| 106 | <h3 id="certs">Certificates</h3> |
| 107 | |
| 108 | To verify the identify of a server, TLS uses |
| 109 | [https://en.wikipedia.org/wiki/X.509#Certificates|X.509 certificates], a |
| 110 | scheme that depends on a trust hierarchy of so-called |
| 111 | [https://en.wikipedia.org/wiki/Certificate_authority | Certificate |
| 112 | Authorities]. The tree of trust relationships ultimately ends in the |
| 113 | CA roots, which are considered the ultimate arbiters of who to trust in |
| 114 | this scheme. |
| 115 | |
| 116 | The question then is, what CA roots does Fossil trust? |
| 117 | |
| 118 | If you are using a self-signed certificate, Fossil will initially not |
| 119 | know that it can trust your certificate, so you'll be asked if you want |
| 120 | to accept the certificate the first time you communicate with the |
| 121 | server. Verify the certificate fingerprint is correct, then answer |
| 122 | "always" if you want Fossil to remember your decision. |
| 123 | |
| 124 | If you are cloning from or syncing to Fossil servers that use a |
| 125 | certificate signed by a well-known CA or one of its delegates, Fossil |
| 126 | still has to know which CA roots to trust. When this fails, you get a |
| 127 | big long error message that starts with this text: |
| 128 | |
| 129 | <pre> |
| 130 | SSL verification failed: unable to get local issuer certificate |
| 131 | </pre> |
| 132 | |
| 133 | Fossil relies on the OpenSSL library to have some way to check a trusted |
| 134 | list of CA signing keys. There are two common ways this fails: |
| 135 | |
| 136 | # <p>The OpenSSL library Fossil is linked to doesn't have a CA |
| 137 | signing key set at all, so that it initially trusts no certificates |
| 138 | at all.</p> |
| 139 | # <p>The OpenSSL library does have a CA cert set, but your Fossil server's |
| @@ -137,11 +148,13 @@ | |
| 148 | fossil set --global ssl-ca-location /path/to/local-ca.pem |
| 149 | </pre> |
| 150 | |
| 151 | The use of <tt>--global</tt> with this option is common, since you may |
| 152 | have multiple reposotories served under certificates signed by that same |
| 153 | CA. However, if you have a mix of publicly-signed and locally-signed |
| 154 | certificates, you might want to drop the <tt>--global</tt> flag and set |
| 155 | this option on a per-repository basis instead. |
| 156 | |
| 157 | A common way to run into the broader first problem is that you're on |
| 158 | FreeBSD, which does not install a CA certificate set by default, even as |
| 159 | a dependency of the OpenSSL library. If you're using a certificate |
| 160 | signed by one of the major public CAs, you can solve this by installing |
| @@ -155,15 +168,15 @@ | |
| 168 | certificate set, but it's not in a format that OpenSSL understands how |
| 169 | to use. Rather than try to find a way to convert the data format, you |
| 170 | may find it acceptable to use the same Mozilla NSS cert set. I do not |
| 171 | know of a way to easily get this from Mozilla themselves, but I did find |
| 172 | a [https://curl.haxx.se/docs/caextract.html|third party source] for the |
| 173 | <tt>cacert.pem</tt> file. I suggest placing the file into your Windows |
| 174 | user home directory so that you can then point Fossil at it like so: |
| 175 | |
| 176 | <pre> |
| 177 | fossil set --global ssl-ca-location %userprofile%\cacert.pem |
| 178 | </pre> |
| 179 | |
| 180 | This can also happen if you've linked Fossil to a version of OpenSSL |
| 181 | [#openssl-src|built from source]. That same <tt>cacert.pem</tt> fix can |
| 182 | work in that case, too. |
| 183 |