SSL 문제 해결

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

이 페이지에는 GitLab 작업 중에 발생할 수있는 일반적인 SSL 관련 오류 및 시나리오가 나열되어 있습니다. 이는 메인 SSL 문서에 추가되어 사용될 것입니다:

유용한 OpenSSL 디버깅 명령어

때로는 SSL 인증서 체인을 직접 확인하여 더 나은 그림을 얻는 것이 도움이 될 수 있습니다. 이러한 명령어는 진단 및 디버깅을 위한 표준 OpenSSL 라이브러리의 일부입니다.

note
GitLab은 자체 커스텀 컴파일된 OpenSSL 버전을 포함하고 있으며, GitLab 라이브러리는 모두 이러한 OpenSSL 버전에 연결됩니다. 따라서 다음 명령을 해당 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를 신뢰하도록 하거나, 서버에서 전체 체인 인증서를 제시하도록 인증서를 수정할 수 있습니다.

    note
    클라이언트가 SSL 연결시 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 the 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 인증서가 아닌 파일을 제거하십시오.

note
gitlab-ctl reconfigure를 실행하면 사용자 지정 공개 인증서의 주제 해시명을 기반으로 심볼릭 링크를 생성하고 /opt/gitlab/embedded/ssl/certs/에 배치합니다. /opt/gitlab/embedded/ssl/certs/에 있는 끊어진 심볼릭 링크는 자동으로 제거됩니다. /opt/gitlab/embedded/ssl/certs/에 저장된 cacert.pemREADME.md 이외의 파일은 /etc/gitlab/trusted-certs/로 이동됩니다.

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

GitLab 버전 8.9.0, 8.9.18.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 실패

note
Let’s Debug 진단 도구를 사용하여 도메인을 테스트할 수 있습니다. 이 도구를 사용하면 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 재구성 중에 문제가 발생하는 경우, Let’s Encrypt을 사용하도록 설정되어 있는지 확인하십시오 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.rbletsencrypt['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과 함께 사용

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 인스턴스에서 미러를 설정하는 중 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 출력 예시입니다:

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 러너 사용

내부 CA 인증서로 GitLab 사용 중 발생하는 오류에서 언급된 오류 외에도 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 러너에 사용의 단원을 참조하세요.

자체 서명 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 젬에서 생성될 수 있으며, 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 확인을 무시할 수 있습니다:

caution
전역 수준에서 이 옵션을 비활성화하는 것과 관련된 잠재적인 보안 문제로 인해 SSL 무시에 주의해야 합니다. 이 옵션은 문제 해결 시에만 사용하고, 즉시 SSL 확인을 복구해야 합니다.
git config --global http.sslVerify false