SSL, HTTP 프록시 보안 설정

SSL, HTTP 프록시 보안 설정

구형 TTS 번들·구형 암호화를 사용하는 환경에 있다면 이 가이드를 따라 보세요. LiteLLM은 기본적으로 대부분의 최신 서버와 호환되는 certifi CA 번들을 SSL 검증에 사용해요. 하지만 SSL 검증을 비활성화하거나 사용자 지정 CA 번들을 사용해야 한다면 아래 단계를 따르면 돼요.

환경 변수는 SDK의 설정보다 우선한다는 점을 알아두세요. LiteLLM은 별도로 지정하지 않는 한 네트워크 요청에 HTTPX를 사용해요.

출처: 문서

본문

1. 사용자 지정 CA 번들 (Custom CA Bundle)

SSL_CERT_FILE 환경 변수나 ssl_verify 설정에 문자열을 전달해 사용자 지정 CA 번들 파일 경로를 설정할 수 있어요.

SDK:

import litellm
litellm.ssl_verify = "client.pem"

PROXY:

litellm_settings:
  ssl_verify: "client.pem"

환경 변수:

export SSL_CERT_FILE="client.pem"

2. SSL 검증 비활성화 (Disable SSL verification)

SDK:

import litellm
litellm.ssl_verify = False

PROXY:

litellm_settings:
  ssl_verify: false

환경 변수:

export SSL_VERIFY="False"

3. 낮은 보안 설정 (Lower security settings)

ssl_security_level로 SSL 연결의 보안 수준을 낮출 수 있어요.

SDK:

import litellm
litellm.ssl_security_level = "DEFAULT@SECLEVEL=1"

PROXY:

litellm_settings:
  ssl_security_level: "DEFAULT@SECLEVEL=1"

환경 변수:

export SSL_SECURITY_LEVEL="DEFAULT@SECLEVEL=1"

4. 인증서 인증 (Certificate authentication)

SSL_CERTIFICATE 환경 변수 또는 ssl_certificate 속성으로 클라이언트를 서버에 인증하는 클라이언트 측 인증서를 설정할 수 있어요.

SDK:

import litellm
litellm.ssl_certificate = "/path/to/certificate.pem"

PROXY:

litellm_settings:
  ssl_certificate: "/path/to/certificate.pem"

환경 변수:

export SSL_CERTIFICATE="/path/to/certificate.pem"

5. SSL/TLS 성능을 위한 ECDH 곡선 설정 (Configure ECDH Curve for SSL/TLS Performance)

ssl_ecdh_curve 설정으로 SSL/TLS 키 교환에 사용되는 ECDH(Elliptic Curve Diffie-Hellman) 곡선을 구성할 수 있어요. PQC(Post-Quantum Cryptography)가 필요 없는 환경에서 성능을 높이기 위해 PQC를 비활성화할 때 특히 유용해요.

사용 사례(Use Case): 일부 OpenSSL 3.x 시스템은 PQC를 기본으로 활성화해 TLS 핸드셰이크를 느리게 만들 수 있어요. ECDH 곡선을 X25519로 설정하면 PQC가 비활성화되고 연결 성능이 크게 개선될 수 있어요.

SDK:

import litellm
litellm.ssl_ecdh_curve = "X25519"  # Disables PQC for better performance

PROXY:

litellm_settings:
  ssl_ecdh_curve: "X25519"

환경 변수:

export SSL_ECDH_CURVE="X25519"

일반적인 유효 곡선 (Common Valid Curves):

  • X25519 — 현대적이고 빠른 곡선(PQC 비활성화에 권장)
  • prime256v1 — NIST P-256 곡선
  • secp384r1 — NIST P-384 곡선
  • secp521r1 — NIST P-521 곡선

참고: 잘못된 곡선 이름을 제공하거나 Python/OpenSSL 버전이 이 기능을 지원하지 않으면 LiteLLM이 경고를 기록하고 기본 곡선으로 계속 진행해요.

6. HTTP_PROXY 환경 변수 사용 (Use HTTP_PROXY environment variable)

LiteLLM은 기본 aiohttp 전송과 httpx 전송(DISABLE_AIOHTTP_TRANSPORT=True) 모두에서, force_ipv4 유무와 관계없이 모든 LLM 요청에 대해 환경의 HTTP_PROXY, HTTPS_PROXY, NO_PROXY를 해석해요. 추가 플래그는 필요 없고, 프록시나 SDK를 시작하기 전에 변수를 설정하면 돼요:

export HTTPS_PROXY='http://username:password@proxy_uri:port'
export NO_PROXY='localhost,127.0.0.1'

DISABLE_AIOHTTP_TRUST_ENV=True(또는 litellm.disable_aiohttp_trust_env = True)를 설정하면 aiohttp 전송이 이 변수들을 무시해요. AIOHTTP_TRUST_ENV(또는 litellm.aiohttp_trust_env)는 프록시 선택과는 무관해요. aiohttp 세션에 trust_env=True를 전달해 aiohttp 자체도 ~/.netrc와 SSL_CERT_FILE / SSL_CERT_DIR을 읽게 하는 거예요.

7. 서비스별 SSL 검증 (Per-Service SSL Verification)

LiteLLM으로 특정 서비스나 프로바이더 호출에 대해 SSL 검증 설정을 재정의할 수 있어요. 서로 다른 서비스(예: 내부 가드레일 vs 공개 LLM 프로바이더)가 서로 다른 CA 인증서를 요구할 때 유용하죠.

Bedrock (SDK)

completion 호출에서 ssl_verify를 직접 전달할 수 있어요.

import litellm

response = litellm.completion(
    model="bedrock/us.anthropic.claude-sonnet-5",
    messages=[{"role": "user", "content": "hi"}],
    ssl_verify="path/to/bedrock_cert.pem" # Or False to disable
)

AIM Guardrail (Proxy)

config.yaml에서 가드레일별로 ssl_verify를 구성할 수 있어요.

guardrails:
  - guardrail_name: aim-protected-app
    litellm_params:
      guardrail: aim
      ssl_verify: "/path/to/aim_cert.pem" # Use specific cert for AIM

Cato Networks Guardrail (Proxy)

config.yaml에서 가드레일별로 ssl_verify를 구성할 수 있어요.

guardrails:
  - guardrail_name: cato-protected-app
    litellm_params:
      guardrail: cato_networks
      ssl_verify: "/path/to/cato_cert.pem" # Use specific cert for AIM

우선순위 로직 (Priority Logic)

LiteLLM은 다음 우선순위로 ssl_verify를 해석해요:

  1. 명시적 파라미터: completion() 또는 가드레일 구성에서 전달.
  2. 환경 변수: SSL_VERIFY 환경 변수.
  3. 전역 설정: litellm.ssl_verify 설정.
  4. 시스템 표준: SSL_CERT_FILE 환경 변수.

더 알아보기 (Learn more)