Gitea SSL憑證安裝與SSH連線設定

1. Gitea SSL憑證安裝與SSH連線設定

1.1. 動機

單位計畫以 HTTPS 提供 Git 服務，已申請相關網域並預計透過 TWCA 認證單位完成 SSL 設定。然而，網路上缺乏針對 TWCA 與 Gitea 整合的完整教學。為此，整理並實作相關流程，記錄於此，方便日後參考，也希望能幫助有相同需求的人。

啟用Gitea Server的SSH服務，可大幅增加連線速度

原本為了方便，直接使用 HTTP 網址來複製儲存庫，但較大的儲存庫同步速度非常慢（例如 420MB 的儲存庫需要 18 分鐘）。後來查閱文件並啟用 SSH 服務，發現同一個儲存庫透過 SSH 只需約 2 分鐘即可完成，速度差異非常明顯。以下整理在 Gitea 啟用 SSH 的步驟。
參考來源：https://jdev.tw/blog/5246/gitea-server-ssh-settings#google_vignette

1.2. 安裝openSSL

在gitea伺服器上安裝openSSL軟體，以下是安裝過程記錄。

1.2.1. 下載openSSL

在windows底下安裝openssl，下載連結->https://slproweb.com/products/Win32OpenSSL.html，其中有提到LTS為3.0.x，

November 30, 2023 - OpenSSL 3.2 is available. Users should currently install a 3.x series and generally only need a Light edition. All application developers should have migrated their applications to use the OpenSSL 3.x series. Note that 3.0.x is a LTS release series while 3.2.x is not.

因此，這次就以3.0.x下載為目標。

1.2.2. 設定環境變數

輸入以下指令

sysdm.cpl

輸入指令介面如下：

接著找到進階，再點選環境變數，如下：

在使用者變數這邊新增一個變數名稱為OPENSSL_CONF，變數值為C:\Program Files\OpenSSL-Win64\bin\openssl.cfg，如下：

點選Path，新增一筆C:\Program Files\OpenSSL-Win64\bin，如下：

1.2.3. 驗證階段

輸入

openssl version

1.3. 建立憑證CSR檔

我們已經可以使用openssl指令了，接著要開始產生相關檔案，以下是相關筆記記錄。

1.3.1. 新增ssl.conf檔

先準備好ssl.conf，儲存路徑放在C:\gitea\custom\ssl，ssl.conf檔案內容如下：

ssl.conf

[req]
prompt = no
default_md = sha256
default_bits = 2048
distinguished_name = dn
x509_extensions = v3_req

[dn]
C = TW
ST = TAIWAN
L = TAIPEI
O = NTNU
OU = SEC
CN = gitsrv.xxx.xxx

[v3_req]

結果如下：

1.3.2. 執行指令產生CSR檔案

建立私密金鑰並同時建立 CSR (Certificate Signing Request) 憑證要求檔：

openssl req -new -nodes -sha256 -utf8 -newkey rsa:2048 -keyout server.key -out server.csr -config ssl.conf

執行結果如下：

會看到這個資料夾底下出現兩個檔案server.csr、server.key，結果如下：

產生出來的檔案格式是PEM (Privacy Enhanced Mail)，也就是文字型的，詳細的檔案類型保哥文章寫的很完整，可以參考相關連結研讀。server.csr內容窺探如下：

server.csr

-----BEGIN CERTIFICATE REQUEST-----
MIIC6TCCAdECAQAwgaMxCzAJBgNVBAYTAlRXMQ8wDQYDVQQIDAZUQUlXQU4xDzAN
BgNVBAcMBlRBSVBFSTEqMCgGA1UECgwhTmF0aW9uYWwgVGFpd2FuIE5vcm1hbCBV
bml2ZXJzaXR5MSUwIwYDVQQLDBxUaGUgU2NpZW5jZSBFZHVjYXRpb24gQ2VudGVy
MR8wHQYDVQQDDBZnaXRzcnYudHFlLm50bnUuZWR1LnR3MIIBIjANBgkqhkiG9w0B
AQEFAAOCAQ8AMIIBCgKCAQEAvFTtnxVYnfUBplPT25WOCu57XWPuupp3YOtu1hiN
gZLnzGOFjuY38pRllqm5lTiyt8Z0bGmD1bsgfIeu7JTvFesM7x1xz0jGFC9G9kAH
opunvnbgORmpzSKgBo/m5DLj/P0fP6FgfKzmkDu+Ap3S+0zrA34pjxZ//clMWsiS
CYzwlyQbXxlK3q5tll3vkDh44MesDW1FnllFvzDNHGLPPZbzaJiOw/qgrZ80EV/h
7Fl56aeOutOzLUVgFjYSG9QKL3Xuln1+QQVlwW46Zf12YDsiBdo7NTxZbl+heYkO
JzS8eaWKkO6ZjLo2YyWpLF6nxywIWS7KGD9dbqq26DOtywIDAQABoAAwDQYJKoZI
hvcNAQELBQADggEBACI1XTy7P9Q4iby5mERlEuUOz6UZ/eDMqSuOP2Ql4LeWu/qd
l9iunWzqK3bBu8GAL1dYDKnzab689RgwM1K5g4KdhEGeFRTSpmPl1NwXjlaZ6W3m
2L0iIrrFTXSU0SVi+PN/XKpp0LDC6GubFXz4lanCYV92J6Zq2lml7qdlIyknvXMc
+NDxBQCEHLTBihw7ghwFZL1zVwl2NCfVqFEw9BstFeYM+zgfu3oikQxZ5xBNlzJs
Ax+XBR9Y0+ob6qwwQXZ1YRLzBk7pYOPoMnCbcInVreW0UV4rlCSwGQ4ncV0E5Edp
o8EwA6X3CcyXpGT0GXzsGPWn3VeK+sz250lMWc8=
-----END CERTIFICATE REQUEST-----

當然，你也可以透過 OpenSSL 工具查看 CSR 檔案的請求內容，命令如下：

openssl req -noout -text -in server.csr

接下來就是把server.csr檔再給TWCA單位即可。(這一段是請網管人員用的，不到30min就馬上給我後續的檔案)

1.4. 取得TWCA提供的zip檔

走完TWCA申請流程後，會拿到一個zip檔，查看zip內容，最重要的是server.cer檔，如下：

截取保哥文章文字：

由於 PKI 基礎建設，需要一個公開憑證 (server.cer) 與一個私密金鑰 (server.key) 才能運作，因此你必須同時擁有這兩個檔案，才能完成整個 TLS 加解密的過程。

複習一下，在這之前，其實我們就已經有server.key及server.csr，後續不會用到server.csr。

請將server.cer、server.key擺放到C:\gitea\custom(依個人喜好自行決定路徑)，結果如下：

1.5. gitea 伺服器 app.ini 調整參數

接著，調整app.ini檔案的相關設定，實際路徑會是在C:\gitea\custom\conf。過程中會有try error，所以建議可以參考我的方式建立三個檔案，錯了再比對或還原改回來。三個檔案分別是app.ini、app_no_ssl.ini、app_ssl.ini，說明如下：

• app.ini

  • gitea 預設執行都是吃這個檔案

• app_no_ssl.ini

  • 這個檔案算是在未ssl之前，先複製一份，並重新命名而已

• app_ssl.ini

  • 這個檔案是設定ssl相關設定之後

最後，調整內容如下：

app.ini

[server]
PROTOCOL=https
REDIRECT_OTHER_PORT=true

#請填寫正確的cer路徑
CERT_FILE= C:/gitea/custom/server.cer

#請填寫正確的私鑰key路徑
KEY_FILE= C:/gitea/custom/server.key

#網管申請好的domain，以下是示意，請改為自己申請的domain
SSH_DOMAIN = kite.com.tw

#網管申請好的domain，以下是示意，請改為自己申請的domain
DOMAIN = kite.com.tw
HTTP_PORT = 443

#網管申請好的domain，以下是示意，請改為自己申請的domain
ROOT_URL = https://kite.com.tw

PORT_TO_REDIRECT = 80
START_SSH_SERVER = true
BUILTIN_SSH_SERVER_USER = git

APP_DATA_PATH = C:\gitea/data
DISABLE_SSH = false
SSH_PORT = 22
LFS_START_SERVER = true
LFS_JWT_SECRET = eO57YqkdnirS8VsGh0efQNOFj-PvfSXZUOU2yHi8OmI
OFFLINE_MODE = false

調整好後記得重新啟動gitea服務。

1.6. 調整伺服器本機防火牆

在實測過程，發現只有伺服器本機能訪問https網站，個人電腦訪問不到，發現是忘記在伺服器本身的防火牆設定port 443，而port 22是給ssh連線用的，先一併設定好。設定內容結果如下：

1.7. 驗證測試

1.7.1. 測試網站(https)連結

瀏覽器輸入您註冊的網址，成功完成https設定，結果如下：

1.7.2. 測試佈署(git push)

使用git push指令時，會出現以下錯誤

Are you sure you want to continue connecting (yes/no/[fingerprint])? Host key verification failed.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

1.7.2.1. 產生金錀

安裝完git軟體之後，其實已內鍵ssh-keygen指令，請執行以下指令產生檔案，而產生的檔案實體路徑預設為C:\Users\使用者登入帳號\.ssh

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

執行完指令後，預期結果如下。觀查資料夾內容新增了兩個檔案，分別是id_rsa、id_rsa.pub，後續步驟會使用到id_rsa.pub檔案內容。

1.7.2.2. 伺服器設定金鑰

回到gitea伺服器，進行登入後，請點選右上角按鈕，點選設定

點選設定後，如下圖，請再點選SSH/GPG金鑰→增加金鑰

請將剛剛的id_rsa.pub內容貼到內容的部分，金鑰名稱自取(不限定)，示意圖如下：

1.7.2.3. 進行gitpush測試

git push 時會出現以下訊息：

The authenticity of host 'kite.com.tw (xxx.xxx.xxx.xxx)' can't be established.
RSA key fingerprint is SHA256:RbjX0POSgF1DBYFwsAiXdmiUqfJQvJBcyPG2rVFQIPk.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

請輸入fingerprint，接著出現以下問題請輸入 yes

Please type 'yes', 'no' or the fingerprint: yes

git push 成功，出現訊息如下：

Warning: Permanently added 'kite.com.tw' (RSA) to the list of known hosts.
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 205 bytes | 205.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote: . Processing 1 references
remote: Processed 1 references in total
To gitsrv.tqe.ntnu.edu.tw:administrator/hrm.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

可以觀查C:\Users\RESH\.ssh資料夾底下的know_host檔變化，已將此domain加入名單中：

know_host

kite.com.tw ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDqw3JJJkaOAZwrqCrsAkBpvPME1rW310sedo7obINQjLbGqipdb6Y0D/1Szu3j+AAO5wnWzDiyNQTVsvIFXDzo6CpcdNe4ffKsbr8dLqlv9ylmdnwIKbUuTPXljsBVFqXeuCaT6z3RJa48wzyN8lzQ2C2TJIVLMsit9RS4FZTcTpo6B0kCCOp3OXJQ/gYTxYJ+Zz7+3eihGm3xV7/j3pT9ng+LBkwe/fMv40il0yAuho//2nDGGxQpnwPZnqMF0HbvV+apUrx8v0tlgbZZKxsG97c2+5e7AgUG0+I4llMkU0YtRySoRiJtWJLFjJdFyng1wiHlSw/g8qHG99Wk4QMMM0e1WyfVGKWtlbnwR3FUXPm5RXaiHABSErH3C+RY1+AyUpEhxxb8+3CiN+7CtVVCVbkR0Ksmoe2gjNt7vbaWOzphrCcmaZHQ3LmT7Npzw3pR/DqVW4kt2DkmTdHzNSoy0TMRkzWEsHFe7tTUO2Mmq95R/6QHfU8S5AvdPVVwTPqnY2nsVglPwRIYRYGKfdiH9utog8SBihEKJsdsFliaix6FYDYW1dTqWPMvBnhopO5pf77XF4aUHSSRCOjD3X2DKTNJ0iC7rkVQhX34lBoZcce+yvWBnZQ7LY8m+o/XWyLFPkrIjiZY3SRX/E/tyAFGgF8MB4IE3p0apbd3k6ycHQ==

經過以上步驟，已經可以順利完成git 相關指令囉！

1.8. 參考資料

• 如何在Window上安裝 OpenSSL?
  • 參考這篇設定openssl的，寫的很完整。
• 認識 PKI 架構下的數位憑證格式與憑證格式轉換的心得分享
  • 很棒的知識整理，謝謝保哥
• 啟用Gitea Server的SSH服務，可大幅增加連線速度
  • 有教如何產生金鑰以及使用smartgit如何設定金鑰教學
• git遇到的问题之“Please make sure you have the correct access rights and the repository exists.”
• 何謂ssh？在Windows下如何使用ssh？如何在Windows透過ssh下載和上傳程式到github?
• 設定 Github SSH 金鑰 feat. Github SSH、HTTPS 的差異