SSLトラブルシューティング

このページには、GitLabの作業中に発生する可能性のある一般的なSSL関連のエラーとシナリオのリストが含まれています。これは、主要なSSLドキュメントへの追加として役立つはずです:

• Linuxパッケージインストール用のSSLを設定。
• GitLab Runnerの自己署名証明書またはカスタム認証局。
• 手動でHTTPSを設定。

役立つOpenSSLデバッグコマンド

場合によっては、SSL証明書チェーンをソースで直接表示することで、より良い全体像を把握するのに役立ちます。これらのコマンドは、診断およびデバッグのための標準OpenSSLツールライブラリの一部です。

• HTTPS経由でホストへのテスト接続を実行します。HOSTNAMEをGitLab URL (HTTPSを除く) に置き換え、portをHTTPS接続を提供するポート (通常443) に置き換えてください:

  echo | /opt/gitlab/embedded/bin/openssl s_client -connect HOSTNAME:port

  echoコマンドはサーバーにnullリクエストを送信し、追加の入力を待つのではなく、接続を閉じさせます。同じコマンドを使用して、HOSTNAME:portをリモートホストのドメインとポート番号に置き換えることで、リモートホスト（例えば、外部リポジトリをホストしているサーバー）をテストできます。

  このコマンドの出力は、証明書チェーン、サーバーが提示する公開証明書、および発生した場合は検証または接続エラーを示します。これにより、SSL設定に関する即時的な問題をすばやく確認できます。

• x509を使用して証明書の詳細をテキスト形式で表示します。/path/to/certificate.crtを証明書のパスに置き換えてください:

  /opt/gitlab/embedded/bin/openssl x509 -in /path/to/certificate.crt -text -noout

  例えば、GitLabはLet’s Encryptから取得した証明書を自動的に/etc/gitlab/ssl/hostname.crtにフェッチして配置します。そのパスとx509コマンドを使用して、証明書の情報（例：ホスト名、発行者、有効期間など）をすばやく表示できます。

  証明書に問題がある場合は、エラーが発生します。

• サーバーから証明書をフェッチしてデコードします。これは、上記の2つのコマンドを組み合わせて、サーバーのSSL証明書をフェッチし、テキストにデコードします:

  echo | /opt/gitlab/embedded/bin/openssl s_client -connect HOSTNAME:port | /opt/gitlab/embedded/bin/openssl x509 -text -noout

一般的なSSLエラー

1. SSL certificate problem: unable to get local issuer certificate

   このエラーは、クライアントがルートCAを取得できないことを示します。これを修正するには、クライアント上で接続しようとしているサーバーのルートCAを信頼するか、接続しようとしているサーバー上で完全なチェーン証明書を提示するように証明書を変更するかのいずれかの方法があります。

   クライアントが接続する際のSSLエラーを防ぐために、完全な証明書チェーンを使用することをお勧めします。完全な証明書チェーンの順序は、サーバー証明書を最初とし、すべての中間証明書が続き、ルートCAが最後であるべきです。

2. unable to verify the first certificate

   このエラーは、サーバーによって不完全な証明書チェーンが提示されていることを示します。このエラーを修正するには、サーバーの証明書を完全なチェーン証明書に置き換える必要があります。完全な証明書チェーンの順序は、サーバー証明書を最初とし、すべての中間証明書が続き、ルートCAが最後であるべきです。

   /opt/gitlab/embedded/bin/opensslユーティリティの代わりにシステムOpenSSLユーティリティを実行中にこのエラーが発生した場合は、CA証明書をOSレベルで更新して修正してください。

3. certificate signed by unknown authority

   このエラーは、クライアントが証明書またはCAを信頼していないことを示します。このエラーを修正するには、サーバーに接続するクライアントが証明書またはCAを信頼する必要があります。

4. SSL certificate problem: self signed certificate in certificate chain

   このエラーは、クライアントが証明書またはCAを信頼していないことを示します。このエラーを修正するには、サーバーに接続するクライアントが証明書またはCAを信頼する必要があります。

5. x509: certificate relies on legacy Common Name field, use SANs instead

   このエラーは、証明書にSAN (subjectAltName) を設定する必要があることを示します。詳細については、こちらのイシューを参照してください。

証明書が原因で再設定が失敗する

ERROR: Not a certificate: /opt/gitlab/embedded/ssl/certs/FILE. Move it from /opt/gitlab/embedded/ssl/certs to a different location and reconfigure again.

/opt/gitlab/embedded/ssl/certsを確認し、有効なX.509証明書ではないREADME.md以外のファイルをすべて削除してください。

カスタム証明書が見つからないかスキップされた

/opt/gitlab/embedded/ssl/certs/にシンボリックリンクが作成されず、gitlab-ctl reconfigure実行後に「Skipping cert.pem」というメッセージが表示される場合、以下の4つの問題のいずれかである可能性があります:

1. /etc/gitlab/trusted-certs/のファイルがシンボリックリンクである
2. ファイルが有効なPEMまたはDERエンコードされた証明書ではない
3. 証明書に文字列TRUSTEDが含まれている

以下のコマンドを使用して証明書の有効性をテストします:

/opt/gitlab/embedded/bin/openssl x509 -in /etc/gitlab/trusted-certs/example.pem -text -noout
/opt/gitlab/embedded/bin/openssl x509 -inform DER -in /etc/gitlab/trusted-certs/example.der -text -noout

無効な証明書ファイルは以下の出力を生成します:

• unable to load certificate
  140663131141784:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:701:Expecting: TRUSTED CERTIFICATE

• cannot load certificate
  PEM_read_bio_X509_AUX() failed (SSL: error:0909006C:PEM routines:get_name:no start line:Expecting: TRUSTED CERTIFICATE)

どちらの場合でも、証明書が以下のもの以外で開始および終了している場合:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

その場合、それらはGitLabと互換性がありません。それらを証明書コンポーネント（サーバー、中間、ルート）に分離し、互換性のあるPEM形式に変換する必要があります。

証明書自体を調べるときは、文字列TRUSTEDを探してください:

-----BEGIN TRUSTED CERTIFICATE-----
...
-----END TRUSTED CERTIFICATE-----

上記の例のように存在する場合は、文字列TRUSTEDを削除し、gitlab-ctl reconfigureを再度実行してみてください。

カスタム証明書が検出されない

gitlab-ctl reconfigureを実行した後で:

1. /opt/gitlab/embedded/ssl/certs/にシンボリックリンクが作成されない;
2. カスタム証明書を/etc/gitlab/trusted-certs/に配置している; かつ
3. スキップされたカスタム証明書やシンボリックリンクされたカスタム証明書のメッセージが表示されない

これは、Linuxパッケージインストールがカスタム証明書がすでに追加されていると認識している問題に遭遇している可能性があります。

解決するには、信頼された証明書ディレクトリハッシュを削除します:

rm /var/opt/gitlab/trusted-certs-directory-hash

その後、gitlab-ctl reconfigureを再度実行します。再設定により、カスタム証明書が検出され、シンボリックリンクが作成されるはずです。

不明な認証局によって署名されたLet’s Encrypt証明書

Let’s Encryptインテグレーションの初期実装では、証明書のみが使用され、完全な証明書チェーンは使用されませんでした。

10.5.4バージョン以降では、完全な証明書チェーンが使用されます。すでに証明書を使用しているインストールの場合、証明書が有効期限切れに近づいていることを更新ロジックが示すまで、切り替えは行われません。それを早めるには、以下を実行します

rm /etc/gitlab/ssl/HOSTNAME*
gitlab-ctl reconfigure

ここでHOSTNAMEは証明書のホスト名です。

再設定時にLet’s Encryptが失敗する

再設定時に、Let’s Encryptが失敗する一般的なシナリオがいくつかあります:

• サーバーがLet’s Encrypt検証サーバーに到達できない場合、またはその逆の場合、Let’s Encryptは失敗する可能性があります:

  letsencrypt_certificate[gitlab.domain.com] (letsencrypt::http_authorization line 3) had an error: RuntimeError: acme_certificate[staging]  (/opt/gitlab/embedded/cookbooks/cache/cookbooks/letsencrypt/resources/certificate.rb line 20) had an error: RuntimeError: [gitlab.domain.com] Validation failed for domain gitlab.domain.com

  Let’s Encryptが原因でGitLabの再設定に問題が発生した場合は、ポート80と443が開いてアクセス可能であることを確認してください。

• ドメインの認証局認可(CAA) レコードは、Let’s Encryptがドメインの証明書を発行することを許可していません。再設定出力で次のエラーを探してください:

  letsencrypt_certificate[gitlab.domain.net] (letsencrypt::http_authorization line 5) had an error: RuntimeError: acme_certificate[staging]   (/opt/gitlab/embedded/cookbooks/cache/cookbooks/letsencrypt/resources/certificate.rb line 25) had an error: RuntimeError: ruby_block[create certificate for gitlab.domain.net] (/opt/gitlab/embedded/cookbooks/cache/cookbooks/acme/resources/certificate.rb line 108) had an error: RuntimeError: [gitlab.domain.com] Validation failed, unable to request certificate

• gitlab.example.comのようなテストドメインを証明書なしで使用している場合、上記のunable to request certificateエラーが表示されます。その場合は、/etc/gitlab/gitlab.rbでletsencrypt['enable'] = falseを設定してLet’s Encryptを無効にしてください。

• Let’s Encryptはレート制限を適用しますが、これはトップレベルドメインで行われます。クラウドプロバイダーのホスト名をexternal_urlとして使用している場合（例: *.cloudapp.azure.com）、Let’s Encryptはazure.comに制限を適用し、証明書の作成が不完全になる可能性があります。

  その場合は、Let’s Encrypt証明書を手動で更新してみてください:

  sudo gitlab-ctl renew-le-certs

内部CA証明書をGitLabで使用する

内部CA証明書を使用してGitLabインスタンスを設定した後、さまざまなCLIツールを使用してそれにアクセスできない場合があります。次の問題が発生する可能性があります:

• curlが失敗します:

  curl "https://gitlab.domain.tld"
  curl: (60) SSL certificate problem: unable to get local issuer certificate
  More details here: https://curl.haxx.se/docs/sslcerts.html

• Railsコンソールを使用したテストも失敗します:

  uri = URI.parse("https://gitlab.domain.tld")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = 1
  response = http.request(Net::HTTP::Get.new(uri.request_uri))
  ...
  Traceback (most recent call last):
        1: from (irb):5
  OpenSSL::SSL::SSLError (SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate))

• このGitLabインスタンスからミラーを設定する際に、エラーSSL certificate problem: unable to get local issuer certificateが表示されます。

• 証明書のパスを指定するとopensslが機能します:

  /opt/gitlab/embedded/bin/openssl s_client -CAfile /root/my-cert.crt -connect gitlab.domain.tld:443

以前に説明した問題が発生した場合は、証明書を/etc/gitlab/trusted-certsに追加し、sudo gitlab-ctl reconfigureを実行してください。

X.509キー値不一致エラー

証明書バンドルでインスタンスを設定した後、NGINXは以下のエラーメッセージを表示する場合があります:

SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch

このエラーメッセージは、提供されたサーバー証明書とキーが一致しないことを意味します。以下のコマンドを実行し、出力を比較することでこれを確認できます:

openssl rsa -noout -modulus -in path/to/your/.key | openssl md5
openssl x509 -noout -modulus -in path/to/your/.crt | openssl md5

以下は、一致するキーと証明書間のmd5出力の例です。一致するmd5ハッシュに注意してください:

$ openssl rsa -noout -modulus -in private.key | openssl md5
4f49b61b25225abeb7542b29ae20e98c
$ openssl x509 -noout -modulus -in public.crt | openssl md5
4f49b61b25225abeb7542b29ae20e98c

これは、異なるmd5ハッシュを示す、一致しないキーと証明書との対立する出力です:

$ openssl rsa -noout -modulus -in private.key | openssl md5
d418865077299af27707b1d1fa83cd99
$ openssl x509 -noout -modulus -in public.crt | openssl md5
4f49b61b25225abeb7542b29ae20e98c

前の例のように両方の出力が異なる場合、証明書とキーの間に不一致があります。さらなるサポートについては、SSL証明書の提供元にお問い合わせください。

エラー: certificate signed by unknown authority

内部CA証明書をGitLabで使用するで言及されているエラーが発生する以外に、CIパイプラインがPendingステータスで停止する可能性があります。Runnerログに次のエラーメッセージが表示される場合があります:

Dec  6 02:43:17 runner-host01 gitlab-runner[15131]: #033[0;33mWARNING: Checking for jobs... failed
#033[0;m  #033[0;33mrunner#033[0;m=Bfkz1fyb #033[0;33mstatus#033[0;m=couldn't execute POST against
https://gitlab.domain.tld/api/v4/jobs/request: Post https://gitlab.domain.tld/api/v4/jobs/request:
x509: certificate signed by unknown authority

GitLab Runnerの自己署名証明書またはカスタム認証局の詳細に従ってください。

自己署名SSL証明書を使用するリモートGitLabリポジトリのミラーリング

自己署名証明書を使用するリモートGitLabインスタンスから、ローカルGitLabインスタンスにリポジトリをミラーリングするように設定すると、ユーザーインターフェースにSSL certificate problem: self signed certificateエラーメッセージが表示される場合があります。

問題の原因は、以下を確認することで確認できます:

• curlが失敗します:

  $ curl "https://gitlab.domain.tld"
  curl: (60) SSL certificate problem: self signed certificate
  More details here: https://curl.haxx.se/docs/sslcerts.html

• Railsコンソールを使用したテストも失敗します:

  uri = URI.parse("https://gitlab.domain.tld")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = 1
  response = http.request(Net::HTTP::Get.new(uri.request_uri))
  ...
  Traceback (most recent call last):
        1: from (irb):5
  OpenSSL::SSL::SSLError (SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate))

この問題を修正するには、以下を実行します。

• リモートGitLabインスタンスからの自己署名証明書をローカルGitLabインスタンス上の/etc/gitlab/trusted-certsディレクトリに追加し、カスタム公開証明書をインストールする手順に従ってsudo gitlab-ctl reconfigureを実行してください。
• ローカルGitLabインスタンスがHelm Chartを使用してインストールされている場合は、自己署名証明書をGitLabインスタンスに追加できます。

また、自己署名証明書を使用するリモートGitLabインスタンスからリポジトリをミラーしようとすると、別のエラーメッセージが表示される場合があります:

2:Fetching remote upstream failed: fatal: unable to access 'https://gitlab.domain.tld/root/test-repo/':
SSL: unable to obtain common name from peer certificate

この場合、問題は証明書自体に関連している可能性があります:

1. 自己署名証明書にコモンネームが欠落していないことを検証します。もしそうであれば、有効な証明書を再生成します
2. 証明書を/etc/gitlab/trusted-certsに追加します。
3. sudo gitlab-ctl reconfigureを実行します。

内部または自己署名証明書が原因でGit操作を実行できない

GitLabインスタンスが自己署名証明書を使用している場合、または証明書が内部認証局（CA）によって署名されている場合、Git操作を実行しようとすると次のエラーが発生する可能性があります:

$ git clone https://gitlab.domain.tld/group/project.git
Cloning into 'project'...
fatal: unable to access 'https://gitlab.domain.tld/group/project.git/': SSL certificate problem: self signed certificate

$ git clone https://gitlab.domain.tld/group/project.git
Cloning into 'project'...
fatal: unable to access 'https://gitlab.domain.tld/group/project.git/': server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none

この問題を修正するには、以下を実行します。

• 可能であれば、すべてのGit操作にSSHリモートを使用してください。これは、より安全で便利であると考えられています。
• HTTPSリモートを使用する必要がある場合は、以下を試すことができます:

  • 自己署名証明書または内部ルートCA証明書をローカルディレクトリ（例: ~/.ssl）にコピーし、Gitが証明書を信頼するように設定します:

    git config --global http.sslCAInfo ~/.ssl/gitlab.domain.tld.crt

  • GitクライアントでSSL検証を無効にします。これは一時的な措置であり、セキュリティリスクと見なされる可能性があるためです。

    git config --global http.sslVerify false

SSL_connectバージョン番号が間違っています

設定ミスにより、次のような結果になる場合があります:

• gitlab-rails/exceptions_json.logのエントリに含まれるもの:

  "exception.class":"Excon::Error::Socket","exception.message":"SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)",
  "exception.class":"Excon::Error::Socket","exception.message":"SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)",

• gitlab-workhorse/currentに含まれるもの:

  http: server gave HTTP response to HTTPS client
  http: server gave HTTP response to HTTPS client

• gitlab-rails/sidekiq.logまたはsidekiq/currentに含まれるもの:

  message: SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)
  message: SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)

これらのエラーの一部はExcon Ruby gemに由来し、GitLabがHTTPのみを提供するリモートサーバーへのHTTPSセッションを開始するように設定されている状況で発生する可能性があります。

1つのシナリオは、HTTPSで提供されていないオブジェクトストレージを使用している場合です。GitLabが設定ミスを起こし、TLSハンドシェイクを試行しますが、オブジェクトストレージはプレーンなHTTPで応答します。

schannel: SEC_E_UNTRUSTED_ROOT

Windowsで以下のエラーが発生した場合:

Fatal: unable to access 'https://gitlab.domain.tld/group/project.git': schannel: SEC_E_UNTRUSTED_ROOT (0x80090325) - The certificate chain was issued by an authority that is not trusted."

GitがOpenSSLを使用するように指定する必要があります:

git config --system http.sslbackend openssl

あるいは、SSL検証を無視して実行することもできます:

git config --global http.sslVerify false

OpenSSL 3へのアップグレード

バージョン17.7以降、GitLabはOpenSSL 3を使用します。一部の古いTLSプロトコルと暗号スイート、または外部インテグレーション用のより脆弱なTLS証明書は、OpenSSL 3のデフォルト設定と互換性がない可能性があります。

OpenSSL 3へのアップグレードにより、以下が必要になります。

• すべての受信および送信TLS接続には、TLS 1.2以上が必要です。
• TLS証明書は、最低112ビットのセキュリティを備えている必要があります。2048ビット未満のRSA、DSA、DHキー、および224ビット未満のECCキーは禁止されています。

次のいずれかのエラーメッセージが表示される場合があります:

• TLS接続がTLS 1.2より古いプロトコルを使用している場合、no protocols available。
• TLS証明書のセキュリティが112ビット未満の場合、certificate key too weak。
• レガシー暗号がリクエストされた場合、unsupported cipher algorithm。

OpenSSL 3ガイドを使用して、外部インテグレーションの互換性を特定し、評価してください。