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