• 유용한 OpenSSL 디버깅 명령어
• 일반적인 SSL 오류
• 인증서 재구성 실패로 인한 문제
• 사용자 정의 인증서 누락 또는 건너뛰기
• 사용자 지정 인증서가 감지되지 않음
• 알 수 없는 권한에서 서명된 Let’s Encrypt 인증서
• 재구성 시 Let’s Encrypt 실패
• GitLab에서 내부 CA 인증서 사용
• X.509 키 값 불일치 오류
• 내부 CA 인증서 또는 자체 서명 인증서로 구성된 GitLab 인스턴스와 함께 GitLab Runner 사용
• 자체 서명 SSL 인증서를 사용하는 원격 GitLab 리포지터리 미러링
• 내부 또는 자체 서명 인증서로 인해 Git 작업을 수행할 수 없음
• SSL_connect 오류 버전 번호가 맞지 않음
• schannel: SEC_E_UNTRUSTED_ROOT

SSL 문제 해결

이 페이지에는 GitLab을 사용하면서 발생할 수 있는 일반적인 SSL 관련 오류와 시나리오가 나열되어 있습니다. 이는 기본 SSL 문서에 추가될 수 있도록 작성되었습니다.

• Linux 패키지 설치를 위한 SSL 구성.
• GitLab Runner를 위한 자체 서명 인증서 또는 사용자 정의 인증 기관.
• 매뉴얼으로 HTTPS 구성.

유용한 OpenSSL 디버깅 명령어

SSL 인증서 체인의 전체적인 상황을 파악하기 위해 원본에서 직접 보는 것이 도움이 될 때가 있습니다. 이러한 명령어는 진단과 디버깅을 위한 표준 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 버전 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-----

예제와 같이 있다면, 해당 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 확인 서버에 도달할 수 없는 경우 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
  

• *.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
  

GitLab에서 내부 CA 인증서 사용

GitLab 인스턴스를 내부 CA 인증서로 구성한 후에, 다양한 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 인스턴스로부터 mirror를 설정하는 경우 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 파이프라인이 보류 상태에 멈출 수 있습니다. 러너 로그에서 다음과 같은 오류 메시지를 확인할 수 있습니다:

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 인스턴스의 /etc/gitlab/trusted-certs 디렉터리에 원격 GitLab 인스턴스에서 자체 서명 인증서를 추가한 다음, 사용자 정의 공개 인증서 설치 지침에 따라 sudo gitlab-ctl reconfigure를 실행하십시오.
• 로컬 GitLab 인스턴스가 Helm 차트를 사용하여 설치된 경우, 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 세션을 시작하도록 구성된 경우에 발생할 수 있습니다.

어떤 시나리오에서는 객체 리포지터리를 사용하고 있는데, 이는 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