SSL 절

WebtoB에서 사용할 SSL의 기능을 설정합니다. 해당 절에 정의된 형태로 SSL 서비스를 제공합니다.

설정 항목

다음은 SSL 절의 환경 설정 형식입니다.

#"ssl": {
    #"common_config": {                                 # COMMON
        #"verify_depth": integer,                       # 0 (0-INT_MAX)
        #"protocols": [string],                         # ["TLSv1", "TLSv1.1", "TLSv1.2", "TLSv1.3"]
        #"required_ciphers": string,                    # "HIGH:!RSA"
        #"tls13_required_ciphers": string               # "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
    },
    #"ssl_configs": [
        {
            "name": string,
            "certificate_file": string,                 # $ENV
            "certificate_key_file": string,             # $ENV
            #"certificate_chain_file": string,          # $ENV
            #"certificate_key_password": string,        # "builtin"
            #"ca_certificate_file": string,             # $ENV
            #"ca_certificate_path": string,             # $ENV
            #"ssl_server_name": [string],
            #"verify_client": integer,                  # 0 (0-3)
            #"renegotiation_level": string,             # "secure"
            #"enable_stapling": boolean,                # false
            #"common_config": {...}                     # COMMON
        }
    ],
    #"proxy_ssl_configs": [
        {
            "name": string,
            #"proxy_certificate_file": string,          # $ENV
            #"proxy_certificate_key_file": string,      # $ENV
            #"proxy_certificate_chain_file": string,    # $ENV
            #"proxy_certificate_key_password": string,  # "builtin"
            #"proxy_ca_certificate_file": string,       # $ENV
            #"proxy_ca_certificate_path": string,       # $ENV
            #"ssl_server_name": [string],
            #"enable_insecure": boolean,                # false
            #"common_config": {...}                     # COMMON
        }
    ]
}

절과 설정 항목의 구성에 대한 기호나 내용에 대한 자세한 내용은 설정 항목 값의 형식 및 설정 방법을 참고합니다.

common_config

SSL 절의 공통적인 설정입니다. 상위 항목에 설정하면 하위 항목에는 설정하지 않아도 상위 항목의 설정이 반영됩니다.

구분 설명

자료형

object

설정 우선순위

설정할 때 적용되는 우선순위는 다음과 같습니다.

  1. "ssl_configs", "proxy_ssl_configs"

  2. "ssl"

common_config/verify_depth

인증 시 연결된 CA들의 깊이를 얼마나 깊게 추적할지를 설정합니다. 단 하나의 인증 CA만 필요하다면 1로 설정합니다.

구분 설명

자료형

integer

범위

0 ~ INT_MAX

기본값

0

common_config/protocols

서버가 사용할 수 있는 프로토콜을 설정합니다. 이때 특정 TLS 버전에 대한 지원 여부를 설정할 수 있으며, 특정 프로토콜을 사용하지 않을 경우 프로토콜 이름 앞에 하이픈(-)을 붙여 설정합니다.

구분 설명

자료형

array(string)

범위

1개 이상 4개 이내("TLSv1" | "TLSv1.1" | "TLSv1.2" | "TLSv1.3")

기본값

["TLSv1", "TLSv1.1", "TLSv1.2", "TLSv1.3"]

"SSLv2", "SSLv3"는 지원하지 않습니다.

common_config/required_ciphers

서버가 사용할 수 있는 cipher를 설정합니다. 이때 특정 cipher와 SSL/TLS 버전에 대한 지원 여부를 설정할 수 있습니다.

구분 설명

자료형

string

범위

1023자 이내

기본값

"HIGH:!RSA"

WebtoB는 OpenSSL을 사용하기 때문에 cipher 이름은 OpenSSL 설명서를 참고합니다.

common_config/tls13_required_ciphers

사용할 수 있는 TLS 1.3 cipher를 설정합니다. 이때 특정 cipher와 SSL/TLS 버전에 대한 지원 여부를 설정할 수 있습니다.

구분 설명

자료형

string

범위

1023자 이내

기본값

"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

WebtoB는 OpenSSL을 사용하기 때문에 cipher 이름은 OpenSSL 설명서를 참고합니다.

ssl_configs

WebtoB가 SSL 서버 역할로 동작할 때의 설정입니다.

구분 설명

자료형

array(object)

범위

100개 이내

ssl_configs/name (필수 항목)

SSL 서버 설정의 이름입니다. 다른 절에서 SSL 서버 설정을 사용할 때는 이 'name’을 설정해야 합니다.

구분 설명

자료형

string

범위

31자 이내

ssl_configs/certificate_file (필수 항목)

PEM 방식으로 인코딩된 서버 인증서를 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

PEM은 DER 규칙으로 인코딩되어 ASCII 형식으로 웹에서 전송됩니다. 만약 인증서가 암호화된 상태일 경우 비밀번호(passphrase)를 입력해야 합니다.

구분 설명

자료형

string

범위

255자 이내

ssl_configs/certificate_key_file (필수 항목)

서버에서 사용되는 PEM 방식으로 인코딩된 인증서의 개인 Key를 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

인증서와 개인 Key가 함께 조합되지 않은 경우 이 지시자를 사용하여 Key의 위치를 지정해야 합니다. 일반적으로 WebtoB의 SSL 디렉터리에 위치시킵니다.

구분 설명

자료형

string

범위

255자 이내

ssl_configs/certificate_chain_file

서버 인증서의 인증서 연쇄(Certificate Chain)를 구성할 때 필요한 상위 인증 기관의 인증서 경로를 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

단, 클라이언트 인증을 위해서는 ca_certificate_file 또는 ca_certificate_path에 설정해야 합니다.

구분 설명

자료형

string

범위

255자 이내

ssl_configs/certificate_key_password

SSL을 사용하는 경우 암호화된 개인 Key 파일에 대한 암호문을 얻기 위한 방식을 설정합니다.

구분 설명

자료형

string

기본값

"builtin"

다음은 설정값에 대한 설명입니다.

설정값 내용

builtin

WebtoB가 기동될 때 암호문을 입력할 것을 요구합니다.

exec:<프로그램 경로>

WebtoB가 기동될 때 해당 프로그램을 실행하고, 그 출력 결과를 암호문으로 사용합니다. exec로 실행되는 파일은 컴파일된 실행 파일이나 셸 스크립트가 이용될 수 있습니다.

raw:<패스워드>

WebtoB가 기동될 때 해당 패스워드를 암호문으로 사용합니다.

file:<패스워드 파일 경로>

WebtoB가 기동될 때 mkpwd 툴을 이용하여 생성된 패스워드 파일을 이용하여 암호문으로 사용합니다.

다음은 certificate_key_password 설정 예시입니다.

    "ssl_configs":[{
      "name":"ssl1",
      "certificate_file":"/home/webtob6/ssl/server.crt",
      "certificate_key_file":"/home/webtob6/ssl/server.key",
      "certificate_key_password":"exec:/home/webtob6/ssl/password.sh"
    }],

ssl_configs/ca_certificate_file

단일 CA로부터 사용자 인증만 받고 싶다면 이 지시자를 사용하여 단일 PEM으로 인코딩된 인증 파일을 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

구분 설명

자료형

string

범위

255자 이내

ssl_configs/ca_certificate_path

인증서를 저장할 디렉터리를 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

인증서는 사용자 인증을 위해 필요한 내용을 담고 있으며, 일반적으로 PEM 방식으로 인코딩되어야 합니다.

구분 설명

자료형

string

범위

255자 이내

ssl_configs/ssl_server_name

SSL에서 alias로 사용할 수 있는 서버 이름을 설정합니다.

구분 설명

자료형

array(string)

범위

100개 이내

ssl_configs/verify_client

SSL 클라이언트에게 요청할 인증 레벨을 설정합니다.

구분 설명

자료형

integer

범위

0 ~ 3

기본값

0

다음은 설정값에 대한 설명입니다.

설정값 설명

0

아무런 인증 요청을 하지 않습니다.

1

사용자는 사용 가능한 인증 정보를 서버에 제공해야 합니다.

2

사용 가능한 인증 정보를 반드시 서버에 제공해야 합니다.

3

사용자는 사용 가능한 인증 정보를 제공해야 하며, 만일 서버가 인증서를 가지고 있지 않은 상황에서는 인증서 인증 과정이 필요 없습니다.

ssl_configs/renegotiation_level

SSL을 사용하는 경우 재협상(Renetotiation)의 레벨을 설정합니다.

구분 설명

자료형

string

범위

"secure" | "insecure" | "disable"

기본값

"secure"

다음은 설정값에 대한 설명입니다.

설정값 내용

secure

클라이언트와 웹 서버가 모두 안전한 경우 재협상을 진행합니다. (예: RFC5746)

insecure

클라이언트와 웹 서버가 안전하지 않더라도 재협상을 진행합니다. (예: CVE-2009-3555)

disable

어떠한 경우에도 재협상을 진행하지 않습니다.

안전하지 않은 경우 재협상이 진행되면 MITM(Man in the Middle) 공격 또는 DoS(Denial of Service) 공격에 취약할 수 있기 때문에 주의해야 합니다.

ssl_configs/enable_stapling

WebtoB SSL이 OCSP(Online Certificate Status Protocol) stapling 방식으로 동작할지 여부를 설정합니다.

구분 설명

자료형

boolean

기본값

false

ssl_configs/common_config

SSL 절의 공통적인 설정입니다. 상위 항목에 설정하면 하위 항목에는 설정하지 않아도 상위 항목의 설정이 반영됩니다.

구분 설명

자료형

object

설정 우선순위

설정할 때 적용되는 우선순위는 다음과 같습니다.

  1. "ssl_configs", "proxy_ssl_configs"

  2. "ssl"

proxy_ssl_configs

WebtoB가 SSL 클라이언트 역할로 동작할 때의 설정입니다. WebtoB가 역방향 프록시로 동작하면서 SSL 통신을 할 때 사용됩니다.

구분 설명

자료형

array(object)

범위

100개 이내

proxy_ssl_configs/name(필수 항목)

SSL 클라이언트 설정의 이름입니다. 역방향 프록시 설정에서 SSL를 사용할 때는 이 'name’을 설정해야 합니다.

구분 설명

자료형

string

범위

31자 이내

proxy_ssl_configs/enable_insecure

내부 서버의 인증서가 유효하지 않을 때 SSL 연결을 허용할지 여부를 설정합니다.

구분 설명

자료형

boolean

기본값

false

다음은 설정값에 대한 설명입니다.

설정값 설명

true

SSL 연결을 허용합니다.

proxy_ssl_configs/proxy_certificate_file

PEM 방식으로 인코딩된 클라이언트 인증서를 설정합니다. 설정 시 환경 변수 사용이 가능하며, 내부 서버가 클라이언트 인증을 요구하는 경우 반드시 설정해야 합니다.

PEM은 DER 규칙으로 인코딩되어 ASCII 형식으로 웹에서 전송됩니다. 만약 인증서가 암호화된 상태일 경우 비밀번호(passphrase)를 입력해야 합니다.

구분 설명

자료형

string

범위

255자 이내

proxy_ssl_configs/proxy_certificate_key_file

클라이언트 인증 수행 시 사용되는 PEM 방식으로 인코딩된 인증서의 개인 Key를 설정합니다. 설정 시 환경 변수 사용이 가능하며, 내부 서버가 클라이언트 인증을 원하는 경우 반드시 설정해야 합니다.

인증서와 개인 Key가 함께 조합되지 않은 경우 이 지시자를 사용하여 Key의 위치를 지정해야 합니다. 일반적으로 WebtoB의 SSL 디렉터리에 위치시킵니다.

구분 설명

자료형

string

범위

255자 이내

proxy_ssl_configs/proxy_certificate_chain_file

클라이언트 인증서의 인증서 연쇄(Certificate Chain)를 구성할 때 필요한 상위 인증기관의 인증서 경로를 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

구분 설명

자료형

string

범위

255자 이내

proxy_ssl_configs/proxy_certificate_key_password

PROXY_SSL에서 클라이언트 인증(proxy_certificate_file, proxy_certificate_key_file)을 사용하는 경우 암호화된 개인 Key 파일에 대한 암호문을 얻기 위한 방식을 설정합니다.

구분 설명

자료형

string

기본값

"builtin"

다음은 설정값에 대한 설명입니다.

설정값 내용

builtin

WebtoB가 기동될 때 암호문을 입력할 것을 요구합니다.

exec:<프로그램 경로>

WebtoB가 기동될 때 해당 프로그램을 실행하고, 그 출력 결과를 암호문으로 사용합니다. exec로 실행되는 파일은 컴파일된 실행 파일이나 셸 스크립트가 이용될 수 있습니다.

raw:<패스워드>

WebtoB가 기동될 때 해당 패스워드를 암호문으로 사용합니다.

file:<패스워드 파일 경로>

WebtoB가 기동될 때 mkpwd 툴을 이용하여 생성된 패스워드 파일을 이용하여 암호문으로 사용합니다.

proxy_ssl_configs/proxy_ca_certificate_file

단일 CA로부터 사용자 인증만 받고 싶다면 이 지시자를 사용하여 단일 PEM으로 인코딩된 인증 파일을 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

구분 설명

자료형

string

범위

255자 이내

proxy_ssl_configs/proxy_ca_certificate_path

인증서를 저장할 디렉터리를 설정합니다. 설정 시 환경 변수 사용이 가능합니다.

인증서는 연결할 서버의 인증서를 인증하기 위해 필요한 내용을 담고 있으며, 일반적으로 PEM 방식으로 인코딩되어야 합니다.

구분 설명

자료형

string

범위

255자 이내

proxy_ssl_configs/ssl_server_name

SSL에서 alias로 사용할 수 있는 서버 이름을 설정합니다.

구분 설명

자료형

array(string)

범위

100개 이내(255자 이내)

proxy_ssl_configs/common_config

SSL 절의 공통적인 설정입니다. 상위 항목에 설정하면 하위 항목에는 설정하지 않아도 상위 항목의 설정이 반영됩니다.

구분 설명

자료형

object

설정 우선순위

설정할 때 적용되는 우선순위는 다음과 같습니다.

  1. "ssl_configs", "proxy_ssl_configs"

  2. "ssl"

설정 예시

다음은 SSL 절을 설정한 예시입니다.

{
    "ssl": {
        "ssl_configs": [
            {
                "name": "ssl1",
                "certificate_file": "server.crt",
                "certificate_key_file": "server_key.crt",
                "certificate_chain_file": "server_chain.crt",
                "certificate_key_password": "builtin",
                "ca_certificate_file": "server_ca.crt",
                "ssl_server_name": [
                    "example.com"
                ],
                "verify_client": 0,
                "renegotiation_level": "secure"
            }
        ],
        "proxy_ssl_configs": [
            {
                "name": "proxy_ssl1",
                "proxy_certificate_file": "server.crt",
                "proxy_certificate_key_file": "server_key.crt",
                "proxy_certificate_chain_file": "server_chain.crt",
                "proxy_certificate_key_password": "builtin",
                "proxy_ca_certificate_file": "internal_server_ca.crt"
            }
        ]
    }
}