SSL Section

The SSL section configures SSL functions used in WebtoB. SSL service operates according to these settings.

Configuration Items

The following is the configuration format of the SSL section.

#"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,
            "certificate_key_file": string,
            #"certificate_chain_file": string,
            #"certificate_key_password": string,        # "builtin"
            #"ca_certificate_file": string,
            #"ca_certificate_path": string,
            #"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,
            #"proxy_certificate_key_file": string,
            #"proxy_certificate_chain_file": string,
            #"proxy_certificate_key_password": string,  # "builtin"
            #"proxy_ca_certificate_file": string,
            #"proxy_ca_certificate_path": string,
            #"ssl_server_name": [string],
            #"enable_insecure": boolean,                # false
            #"common_config": {...}                     # COMMON
        }
    ]
}

Refer to Types of Setting Values and Configuration Methods for more information on symbols and details of the SSL section configuration items.

common_config

A common setting for SSL sections. If set in the parent item, the settings will be reflected to the child items without the need for additional configuration.

Item Description

Data Type

Object

Priority

The priority of the setting is as follows:

  1. "ssl_configs", "proxy_ssl_configs"

  2. "ssl"

common_config/verify_depth

Specifies the level to trace and validate the chain of CAs for authentication. If verification from a single CA is sufficient, set this value to 1.

Item Description

Data Type

Integer

Range

0 ~ INT_MAX

Default Value

0

common_config/protocols

Specifies the protocols that can be used by the server. This can determine whether to support a specific TLS version. To disable a specific protocol, add a hyphen (-) before the protocol name.

Item Description

Data Type

Array (string)

Range

1 to 4 items ("TLSv1" | "TLSv1.1" | "TLSv1.2" | "TLSv1.3")

Default Value

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

'SSLv2' and 'SSLv3' are not supported.

common_config/required_ciphers

Specifies the ciphers that can be used by the server. You can also configure support for specific ciphers and SSL/TLS versions.

Item Description

Data Type

String

Range

Up to 1023 characters

Default Value

"HIGH:!RSA"

Since WebtoB uses OpenSSL, refer to the OpenSSL guide for cipher names.

common_config/tls13_required_ciphers

Specifies the TLS 1.3 cipher suites that can be enabled. You can also configure support for specific ciphers and SSL/TLS versions.

Item Description

Data Type

String

Range

Up to 1023 characters

Default Value

"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

Since WebtoB uses OpenSSL, refer to the OpenSSL guide for cipher names.

ssl_configs

Settings for when WebtoB operates as an SSL server.

Item Description

Data Type

Array (object)

Range

Up to 100 items

ssl_configs/name (Required)

The name of the SSL server configuration. You must set this 'name' when using SSL server configuration in other sections.

Item Description

Data Type

String

Range

Up to 31 characters

ssl_configs/certificate_file (Required)

Specifies the server certificate encoded in PEM.

The certificate is encoded using DER rules and transmitted on the web in ASCII format. If the certificate is encrypted, you will be asked to enter a passphrase.

Item Description

Data Type

String

Range

Up to 255 characters

ssl_configs/certificate_key_file (Required)

Specifies the private key of the PEM-encoded certificate used on the server.

If the key is not combined with the certificate, use this directive to specify the location of the key. Generally, this file is placed in the WebtoB SSL directory.

Item Description

Data Type

String

Range

Up to 255 characters

ssl_configs/certificate_chain_file

Specifies the path to CA certificates used to create a server certificate chain. For client authentication, the ca_certificate_file or ca_certificate_path item must be set.

Item Description

Data Type

String

Range

Up to 255 characters

ssl_configs/certificate_key_password

Specifies how to retrieve the passphrase for an encrypted private key file when SSL is used.

Item Description

Data Type

String

Default Value

"builtin"

The following describes each configuration value.

Value Description

builtin

Asks for a passphrase when starting WebtoB.

exec:<program path>

When starting WebtoB, a program is executed and its output is used as a passphrase. A file that is executed with 'exec' can be a compiled executable or a shell script.

raw:<passphrase>

Uses this passphrase when WebtoB starts up.

file:<passphrase file path>

Uses the passphrase from this file that was generated by the mkpwd tool when WebtoB is started.

The following is an example of configuring the 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

Use this directive to verify the server from a single CA (Certificate Authority). The certificate file must be encoded in PEM.

Item Description

Data Type

String

Range

Up to 255 characters

ssl_configs/ca_certificate_path

Specifies the directory where the certificate will be saved. The certificate contains the information required for user authentication and should generally be encoded in PEM format.

Item Description

Data Type

String

Range

Up to 255 characters

ssl_configs/ssl_server_name

Sets the server name that can be used as an alias in SSL.

Item Description

Data Type

Array (string)

Range

Up to 100 items

ssl_configs/verify_client

Sets the authentication level to request from SSL clients.

Item Description

Data Type

Integer

Range

0 ~ 3

Default Value

0

The following describes each configuration value.

Value Description

0

No authentication is requested.

1

The user must provide valid authentication information to the server.

2

The user must provide valid authentication information to the server.

3

The user must provide valid authentication information. If the server does not have a certificate, the verification process is not required.

ssl_configs/renegotiation_level

Specifies the renegotiation level when SSL is used.

Item Description

Data Type

String

Range

"secure" | "insecure" | "disable"

Default Value

"secure"

The following describes each configuration value.

Value Description

secure

Proceeds to renegotiate when the client and web server are secure. Example: RFC5746

insecure

Proceeds to renegotiate although the client and web server are not secure. Example: CVE-2009-3555

disable

Does not renegotiate under any circumstances.

If renegotiation proceeds in an insecure situation, it may be vulnerable to Man in the Middle (MITM) attacks or Denial of Service (DoS) attacks.

ssl_configs/enable_stapling

Specifies whether WebtoB SSL operates with Online Certificate Status Protocol (OCSP) stapling.

Item Description

Data Type

Boolean

Default Value

False

ssl_configs/common_config

A common setting for SSL sections. If set in the parent item, the settings will be reflected to the child items without the need for additional configuration.

Item Description

Data Type

Object

Priority

The priority of the setting is as follows:

  1. "ssl_configs", "proxy_ssl_configs"

  2. "ssl"

proxy_ssl_configs

Settings for when WebtoB operates as an SSL client. It is used when WebtoB acts as a reverse proxy and performs SSL communication.

Item Description

Data Type

Array (object)

Range

Up to 100 items

proxy_ssl_configs/name (Required)

The name of the SSL client configuration. You must set this 'name' when using SSL in reverse proxy configuration.

Item Description

Data Type

String

Range

Up to 31 characters

proxy_ssl_configs/enable_insecure

Sets whether to allow SSL connections when the internal server’s certificate is invalid.

Item Description

Data Type

Boolean

Default Value

False

The following describes each configuration value.

Value Description

true

Allows SSL connections.

proxy_ssl_configs/proxy_certificate_file

Specifies the client certificate file encoded in PEM. This must be configured if the internal server requires client authentication.

The certificate is encoded using DER rules and transmitted on the web in ASCII format. If the certificate is encrypted, you will be asked to enter a passphrase.

Item Description

Data Type

String

Range

Up to 255 characters

proxy_ssl_configs/proxy_certificate_key_file

Specifies the private key of the PEM-encoded certificate used for client authentication. This must be configured if the internal server requires client authentication.

If the key is not combined with the certificate, use this directive to specify the location of the key. Generally, this file is placed in the WebtoB SSL directory.

Item Description

Data Type

String

Range

Up to 255 characters

proxy_ssl_configs/proxy_certificate_chain_file

Specifies the path to CA certificates used to create a client certificate chain.

Item Description

Data Type

String

Range

Up to 255 characters

proxy_ssl_configs/proxy_certificate_key_password

Specifies how to retrieve the passphrase for an encrypted private key file when client authentication (proxy_certificate_file, proxy_certificate_key_file) is used in PROXY_SSL.

Item Description

Data Type

String

Default Value

"builtin"

The following describes each configuration value.

Value Description

builtin

Asks for a passphrase when starting WebtoB.

exec:<program path>

When starting WebtoB, a program is executed and its output is used as a passphrase. A file that is executed with 'exec' can be a compiled executable or a shell script.

raw:<passphrase>

Uses this passphrase when WebtoB starts up.

file:<passphrase file path>

Uses the passphrase from this file that was generated by the mkpwd tool when WebtoB is started.

proxy_ssl_configs/proxy_ca_certificate_file

Use this directive to verify the server from a single CA (Certificate Authority). The certificate file must be encoded in PEM.

Item Description

Data Type

String

Range

Up to 255 characters

proxy_ssl_configs/proxy_ca_certificate_path

Sets the directory where the certificate will be stored. The certificate contains the information required to verify the server’s certificate and should generally be encoded in PEM format.

Item Description

Data Type

String

Range

Up to 255 characters

proxy_ssl_configs/ssl_server_name

Sets the server name that can be used as an alias in SSL.

Item Description

Data Type

Array (string)

Range

Up to 100 items (within 255 characters)

proxy_ssl_configs/common_config

A common setting for SSL sections. If set in the parent item, the settings will be reflected to the child items without the need for additional configuration.

Item Description

Data Type

Object

Priority

The priority of the setting is as follows:

  1. "ssl_configs", "proxy_ssl_configs"

  2. "ssl"

Example

The following is an example of configuring the SSL sections:

{
    "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"
            }
        ]
    }
}