SSL 문제 해결

Tier: Free, Premium, Ultimate Offering: Self-managed

이 페이지에는 GitLab을 사용하는 동안 만날 수 있는 일반적인 SSL 관련 오류 및 시나리오 목록이 포함되어 있습니다. 이는 다음의 기본 SSL 문서에 추가로 제공될 것입니다:

유용한 OpenSSL 디버깅 명령어

가끔씩 SSL 인증서 체인을 직접 보는 것이 도움이 될 때가 있습니다. 이 명령어들은 진단과 디버깅을 위한 표준 OpenSSL 라이브러리의 일부입니다.

참고: GitLab에는 사용 중인 OpenSSL에 대한 자체 컴파일 버전이 포함되어 있으며, 이를 통해 모든 GitLab 라이브러리가 연결됩니다. 다음 명령어를 실행할 때 이 OpenSSL 버전을 사용하는 것이 중요합니다.

  • HTTPS를 통해 호스트로의 테스트 연결을 수행합니다. HOSTNAME을 GitLab URL로, port를 HTTPS 연결을 제공하는 포트로 대체하세요 (보통 443입니다): 

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

    echo 명령어는 서버에 빈 요청을 보내 연결을 기다리는 대신에 종료시킵니다. 동일한 명령어를 사용하여 원격 호스트(예: 외부 저장소를 호스팅하는 서버)를 테스트할 수 있습니다. 이를 위해서 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 명령어를 사용하여 인증서의 정보(예: 호스트명, 발급자, 유효 기간 등)를 빠르게 표시할 수 있습니다.

    인증서에 문제가 있는 경우, 오류가 발생합니다.

  • 서버에서 인증서를 검색하고 디코딩합니다. 이 명령은 서버의 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로 구성되어야 합니다.

  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

    이 오류는 SANs (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를 확인하고 README.md가 아닌 유효한 X.509 인증서가 아닌 다른 파일을 제거하세요.

참고: gitlab-ctl reconfigure를 실행하면 사용자 정의 공개 인증서의 주제 해시로 명명된 심볼릭 링크가 구성되어 /opt/gitlab/embedded/ssl/certs/에 만들어집니다. /opt/gitlab/embedded/ssl/certs/의 잘못된 심볼릭 링크는 자동으로 제거됩니다. /opt/gitlab/embedded/ssl/certs/에 cacert.pem과 README.md 이외의 파일이 있다면 /etc/gitlab/trusted-certs/로 이동됩니다.

사용자 정의 인증서 누락 또는 건너뜀

GitLab 버전 8.9.0, 8.9.1 및 8.9.2는 모두 실수로 /etc/gitlab/ssl/trusted-certs/ 디렉토리를 사용했습니다. 이 디렉토리가 비어 있다면 안전하게 제거할 수 있습니다. 사용자 정의 인증서가 여전히 있는 경우에는 이를 /etc/gitlab/trusted-certs/로 이동하고 gitlab-ctl reconfigure를 실행하세요.

/opt/gitlab/embedded/ssl/certs/에 심볼릭 링크가 생성되지 않고 gitlab-ctl reconfigure를 실행한 후 “Skipping cert.pem” 메시지가 표시된다면 다음 중 하나의 문제가 발생한 것입니다:

  1. /etc/gitlab/trusted-certs/의 파일이 심볼릭 링크입니다
  2. 파일이 유효한 PEM 또는 DER로 인코딩된 인증서가 아닙니다
  3. c_rehash가 올바르게 인증서를 심볼릭 링크화하기 위해 필요한 운영 체제에 설치된 Perl이 없습니다
  4. 인증서에 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 형식으로 구성 요소(서버, 중간, 루트)로 분리하고 변환해야 합니다.

c_rehash가 perl 해석기 누락으로 인해 인증서를 심볼릭 링크화하지 않는지 테스트하세요: 

$ /opt/gitlab/embedded/bin/c_rehash /etc/gitlab/trusted-certs

bash: /opt/gitlab/embedded/bin/c_rehash: /usr/bin/perl: bad interpreter: No such file or directory

이 메시지를 확인한다면, 배포의 패키지 관리자로 perl을 설치해야 합니다.

인증서 자체를 검사하려면, TRUSTED 문자열을 찾아보세요: 

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

위와 같은 예시처럼, 이 경우 해당 문자열을 제거하고 gitlab-ctl reconfigure를 다시 실행해보세요.

사용자 정의 인증서 감지되지 않음

gitlab-ctl reconfigure를 실행한 후:

  1. /opt/gitlab/embedded/ssl/certs/에 심볼릭 링크가 생성되지 않았다면;
  2. 사용자 정의 인증서를 /etc/gitlab/trusted-certs/에 놓았고;
  3. 건너뛰거나 심볼릭 링크된 사용자 정의 인증서 메시지가 표시되지 않는다면

사용자 정의 인증서가 이미 추가된 것으로 판단하는 문제가 발생했을 수 있습니다.

해결하려면, 신뢰된 인증서 디렉토리 해시를 삭제하세요: 

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 Debug 진단 도구를 사용하여 도메인을 테스트할 수 있습니다. 이 도구는 Let’s Encrypt 인증서를 발급할 수 없는 이유를 찾는 데 도움이 될 수 있습니다.

재구성 시, 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이 열려 있고 접근 가능한지 확인하세요.

  • 도메인의 Certification Authority Authorization (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는 속도 제한을 시행하며, 이는 최상위 도메인 기준입니다. 예를 들어 *.cloudapp.azure.com과 같은 클라우드 제공업체의 호스트 이름을 external_url로 사용하는 경우, 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 console를 사용하여 테스트하는 경우도 실패합니다: 

    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 인증서 제공업체에 문의하여 추가 지원을 받으세요.

내부 CA 인증서 또는 자체 서명된 인증서가 구성된 GitLab 인스턴스와 함께 GitLab Runner 사용하기

GitLab 내부 CA 인증서 사용에 언급된 오류 외에도 CI 파이프라인이 Pending 상태에 멈출 수 있습니다. 러너 로그에서 다음과 같은 오류 메시지가 표시될 수 있습니다: 

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 인스턴스에서 저장소를 미러링하려고 시도할 때 다음과 같은 오류 메시지도 받을 수 있습니다: 

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이 HTTPS 세션을 시작하도록 구성되어 있는 상황에서 발생할 수 있습니다. 이때 원격 서버가 HTTP만 제공하는 경우에 발생할 수 있습니다.

한 가지 시나리오는 객체 저장소(object storage)를 사용하는 것인데, 해당 저장소가 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 확인을 무시할 수 있습니다:

경고: 전역 수준에서 이 옵션을 비활성화하는 것과 관련된 잠재적 보안 문제로 인해 SSL을 무시할 때에는 주의해야 합니다. 이 옵션은 문제 해결 시에만 사용하고 즉시 SSL 확인을 다시 활성화해야 합니다. 

git config --global http.sslVerify false