Error: Certificate verification failed 에러 해결법 – 원인 분석부터 완벽 해결까지

🚨 도입부

Node.js 개발을 하다 보면 ‘Error: Certificate verification failed’라는 에러 메시지와 마주하는 순간이 있습니다. 이 에러는 특히 외부 API를 호출하거나 HTTPS 요청을 보낼 때 자주 발생합니다. 많은 개발자들이 이 에러에 좌절을 겪습니다. 특히 프로젝트 마감이 임박한 상황에서, 이 에러는 개발자의 발목을 잡습니다. 예를 들어, 배포 직전에 외부 인증서 문제로 인해 기능이 중단된다면, 그 당혹감은 이루 말할 수 없습니다.

이 에러는 다음과 같은 상황에서 발생할 수 있습니다:

• 외부 API에 HTTPS 요청을 보낼 때
• 서드파티 라이브러리가 인증서를 요구할 때
• 로컬 개발 환경에서 SSL 인증서가 유효하지 않을 때
• 클라이언트가 서버의 인증서를 검증할 수 없을 때

이 글을 통해 여러분은 이 에러의 원인을 정확히 이해하고, 다양한 해결책을 통해 문제를 빠르게 해결할 수 있습니다. 일반적으로 이 에러를 해결하는 데는 10분에서 30분 정도가 소요될 수 있으며, 난이도는 중급 정도로 판단됩니다.

🔍 에러 메시지 상세 분석

이 에러의 정확한 메시지는 ‘Error: Certificate verification failed’이며, 상황에 따라 약간의 변형이 있을 수 있습니다. 예를 들어, ‘UNABLE_TO_VERIFY_LEAF_SIGNATURE’, ‘CERT_HAS_EXPIRED’와 같은 추가 정보가 포함될 수 있습니다. 이 에러는 다음과 같은 다양한 상황에서 발생할 수 있습니다:

• 서버의 인증서가 만료되었거나 잘못된 경우
• 루트 인증서가 신뢰할 수 없는 경우
• 네트워크 설정에 문제가 있는 경우
• 프록시 서버 설정 오류
• 인증서 체인에 누락된 요소가 있는 경우

에러 메시지의 각 부분을 해석해 보겠습니다:

• Error: 문제가 발생했음을 나타냅니다.
• Certificate verification failed: 인증서 검증에 실패했음을 의미합니다. 이는 클라이언트가 서버의 인증서를 신뢰할 수 없음을 나타냅니다.

초보자라면 에러 메시지를 읽는 법을 익히는 것도 중요합니다. 기본적으로 에러 메시지는 무엇이 잘못되었는지를 알려주며, 각 부분은 문제의 원인을 파악하는 데 도움을 줍니다. 이 에러와 혼동하기 쉬운 비슷한 에러로는 ‘DEPTH_ZERO_SELF_SIGNED_CERT’나 ‘SELF_SIGNED_CERT_IN_CHAIN’ 등이 있습니다. 이들은 모두 인증서와 관련된 문제지만, 각각의 의미와 해결 방법은 다를 수 있습니다.

🧐 발생 원인 분석

이 에러가 발생하는 주요 원인을 알아봅시다. 주로 다음과 같은 5-7가지 원인이 있습니다:

1. 만료된 인증서: 서버의 인증서가 만료되면 클라이언트는 이를 신뢰할 수 없습니다.
2. 잘못된 도메인: 인증서의 도메인과 요청의 도메인이 일치하지 않을 경우 문제가 발생합니다.
3. 자체 서명된 인증서: 자체 서명된 인증서는 기본적으로 신뢰할 수 없는 것으로 간주됩니다.
4. 루트 인증서 미설치: 클라이언트 시스템에 필요한 루트 인증서가 설치되지 않으면 오류가 발생할 수 있습니다.
5. 중간 인증서 누락: 인증서 체인에서 중간 인증서가 누락되면 검증이 실패합니다.
6. 잘못된 네트워크 설정: 프록시 서버나 방화벽 설정이 올바르지 않은 경우 문제가 발생할 수 있습니다.
7. 서드파티 라이브러리 문제: 사용 중인 라이브러리가 잘못된 인증서 체인을 사용하거나 인증서를 제대로 처리하지 못할 수 있습니다.

각 원인별 발생 시나리오와 구체적 예시를 살펴보겠습니다. 예를 들어, 만료된 인증서는 보통 SSL 인증서를 갱신하지 않았을 때 발생합니다. 이는 단순한 실수일 수 있지만, 자동 갱신 설정이 누락되었거나 인증서 발급 주체의 문제일 수도 있습니다. 잘못된 도메인은 예를 들어, 인증서가 ‘www.example.com’에 발급되었지만 요청이 ‘api.example.com’으로 발송될 때 발생할 수 있습니다.

개발 환경에 따라 이 에러는 다르게 발생할 수 있습니다. 예를 들어, Windows에서는 루트 인증서가 자동으로 관리되지만, Linux에서는 수동으로 ca-certificates를 업데이트해야 할 수 있습니다. OS, Node.js 버전, 사용 중인 라이브러리에 따라 문제의 원인과 해결책이 달라질 수 있습니다.

각 원인별로 간단한 확인 방법도 존재합니다. 예를 들어, 인증서 만료 여부는 브라우저에서 직접 인증서를 확인하거나 OpenSSL을 사용하여 명령줄에서 확인할 수 있습니다. 잘못된 도메인은 인증서 세부 정보를 확인하여 쉽게 식별할 수 있습니다.

✅ 해결 방법

이제 이 에러를 해결하기 위한 다양한 방법을 살펴보겠습니다.

즉시 해결: 1분 내 적용 가능한 빠른 방법

1. NODE_TLS_REJECT_UNAUTHORIZED 설정: 개발 환경에서 임시로 SSL 인증서 검사를 비활성화할 수 있습니다. 이는 프로덕션 환경에서는 사용하지 말아야 합니다.

   process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
   

   이 코드는 인증서 검사를 비활성화하여 모든 SSL 요청을 허용합니다. 하지만 이는 보안에 취약하므로 개발 환경에서만 사용해야 합니다.

2. 인증서 체인 포함: 서버 설정에서 인증서 체인을 포함하도록 구성합니다. 이는 특히 중간 인증서가 누락된 경우 유효합니다.
3. 루트 인증서 업데이트: 클라이언트 시스템의 루트 인증서를 업데이트하여 최신 상태로 유지합니다. 이는 Linux 시스템에서 ‘sudo update-ca-certificates’ 명령을 통해 가능합니다.

표준 해결: 일반적이고 안전한 해결법

1. 인증서 갱신: 만료된 인증서를 갱신합니다. Let’s Encrypt 같은 무료 인증서 발급 서비스를 이용할 수 있습니다. 자동 갱신을 설정하여 만료를 방지합니다.
2. 도메인 일치 확인: 인증서의 도메인과 요청의 도메인이 일치하는지 확인합니다. 이는 보통 인증서 발급 시 주의하여 설정해야 합니다.
3. 신뢰할 수 있는 CA 인증서 사용: 자체 서명된 인증서 대신 신뢰할 수 있는 CA에서 인증서를 발급받습니다.
4. 중간 인증서 포함: 중간 인증서를 포함하여 서버에 설치합니다. 이는 인증서 체인을 완전하게 만들어줍니다.
5. 네트워크 설정 검사: 프록시 서버나 방화벽 설정을 점검하여 HTTPS 트래픽이 올바르게 전달되는지 확인합니다.

고급 해결: 복잡한 상황을 위한 해결법

1. Custom CA 사용: 고급 환경에서는 자체적으로 신뢰할 수 있는 CA를 구성하여 사용할 수 있습니다.

   const https = require('https');
   const fs = require('fs');
   
   const options = {
     hostname: 'example.com',
     port: 443,
     path: '/',
     method: 'GET',
     ca: fs.readFileSync('/path/to/custom/ca.pem')
   };
   
   const req = https.request(options, (res) => {
     console.log(`statusCode: ${res.statusCode}`);
   });
   
   req.on('error', (error) => {
     console.error(error);
   });
   
   req.end();
   

   이 코드는 사용자 정의 CA를 사용하여 HTTPS 요청을 보냅니다.

2. 프록시 서버 설정: 프록시 서버를 올바르게 설정하여 SSL 인증서 오류를 방지합니다. 이는 특히 기업 환경에서 중요합니다.
3. 라이브러리 업데이트: 사용 중인 서드파티 라이브러리를 최신 버전으로 업데이트하여 인증서 관련 문제를 해결합니다. 이는 라이브러리의 버그가 원인일 경우 효과적입니다.

각 해결 방법마다 장단점이 있습니다. 예를 들어, NODE_TLS_REJECT_UNAUTHORIZED를 사용하는 것은 빠르지만 보안에 취약합니다. 반면에, 인증서 체인을 올바르게 설정하는 것은 시간이 걸리지만 가장 안전한 방법입니다. 해결 후에는 브라우저나 Node.js 클라이언트를 통해 인증서 검증이 제대로 이루어지는지 확인할 수 있습니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하기 위해 다음과 같은 방법들을 사용할 수 있습니다:

• 인증서 자동 갱신 설정: Let’s Encrypt와 같은 서비스를 통해 인증서를 자동으로 갱신하도록 설정합니다.
• 도메인과 인증서 일치 점검: 정기적으로 도메인과 인증서의 일치를 점검하여 문제를 사전에 방지합니다.
• SSL/TLS 검사 도구 사용: SSL Labs와 같은 도구를 사용하여 서버의 SSL/TLS 설정을 검사합니다.
• 코드 리뷰 체크리스트: 코드 리뷰 시 SSL/TLS 설정과 관련된 부분을 점검하는 체크리스트를 마련합니다.
• 팀 개발 가이드라인 공유: 팀 내에서 SSL/TLS와 관련된 베스트 프랙티스를 공유하고, 이를 문서화하여 지속적으로 참고합니다.

🎯 마무리 및 추가 팁

이번 포스트에서는 ‘Error: Certificate verification failed’ 에러의 원인과 해결 방법에 대해 자세히 알아보았습니다. 다음은 핵심 요약입니다:

1. 인증서 관련 문제는 주로 만료, 도메인 불일치, 미설치된 루트 인증서로 인해 발생합니다.
2. 즉시 해결 방법은 개발 환경에서 사용하고, 프로덕션에서는 안전한 방법을 사용해야 합니다.
3. 재발 방지를 위해 인증서 자동 갱신과 정기적인 점검을 수행하세요.

비슷한 에러에 대한 정보는 다음 링크를 참조하세요:

• Error: DEPTH_ZERO_SELF_SIGNED_CERT 해결법
• Error: SELF_SIGNED_CERT_IN_CHAIN 해결법

추가 학습을 위해 SSL/TLS와 관련된 공식 문서를 참고하시기 바랍니다. 이 에러는 해결하기 까다로울 수 있지만, 차근차근 따라가면 충분히 해결할 수 있습니다. 계속해서 발전하는 여러분을 응원합니다!