README.md in fluent-plugin-secure-forward-0.2.6 vs README.md in fluent-plugin-secure-forward-0.3.0
- old
+ new
@@ -3,62 +3,212 @@
[Fluentd](http://fluentd.org) input/output plugin to forward fluentd messages over SSL with authentication.
This plugin makes you to be able to:
* protect your data from others in transferring with SSL
- * with certificate signed and registered correctly
- * with self-signed certificate (and generate certificate in in\_secure\_forward automatically)
+ * with certificate signed and registered correctly/publicly
+ * with private CA certificates generated by users
+ * with automatically generated and self-signed certificates **in vulnerable way**
* authenticate by shared\_key check from both of client(out\_secure\_forward) and server(in\_secure\_forward)
* authenticate with username / password pairs
## Installation
install with gem or fluent-gem command as:
-`````
-### native gem
+```
+ ### native gem
$ gem install fluent-plugin-secure-forward
-
-### fluentd gem
+
+ ### fluentd gem
$ fluent-gem install fluent-plugin-secure-forward
-`````
+```
+### Using SSL certificates issued from trusted CA
+
+To communicate over SSL with valid certificate issued from public CA, configure params below for input plugin:
+
+* `secure`: set `yes` or `true`
+* `cert_path`: set path of certificate file issued from CA
+* `private_key_path`: set path of private key file
+* `private_key_passphrase`: set passphrase of private key
+
+```apache
+<source>
+ type secure_forward
+
+ # bind 0.0.0.0 # default
+ # port 24284 # default
+ self_hostname server.fqdn.example.com
+ shared_key secret_string
+
+ secure yes
+
+ cert_path /path/for/certificate/cert.pem
+ private_key_path /path/for/certificate/key.pem
+ private_key_passphrase secret_foo_bar_baz
+</source>
+```
+
+For output plugin, specify just 2 options below:
+
+* `secure`: set `yes` or `true`
+* `enable_strict_verification`: specify `yes` or `true` to verify FQDN of servers (input plugin)
+
+```apache
+<match secret.data.**>
+ type secure_forward
+
+ self_hostname client.fqdn.local
+ shared_key secret_string
+
+ secure yes
+ enable_strict_verification yes
+
+ <server>
+ host server.fqdn.example.com # or IP
+ # port 24284
+ </server>
+ <server>
+ host 203.0.113.8 # ip address to connect
+ hostlabel server.fqdn.example.com # specify hostlabel for FQDN verification if ipaddress is used for host
+ </server>
+</match>
+```
+
+### Using private CA file and key
+
+This plugin has a simple utility command to generate private CA cert/key files just for secure-forward.
+
+```
+$ secure-forward-ca-generate /path/for/dir/of/certs "passphrase for private CA secret key"
+```
+
+This command generates `ca_cert.pem` and `ca_key.pem` on `/path/for/dir/of/certs`. For SSL communication with private CA, users must deploy both files for input plugins, and also must deploy `ca_cert.pem` for output plugins.
+And then, configure Fluentd with these files and the passphrase. With this configuration, server certificates are automatically generated and issued by private CA.
+
+```apache
+<source>
+ type secure_forward
+
+ # bind 0.0.0.0 # default
+ # port 24284 # default
+ self_hostname myserver.local
+ shared_key secret_string
+
+ secure yes
+
+ ca_cert_path /path/for/certificate/ca_cert.pem
+ ca_private_key_path /path/for/certificate/ca_key.pem
+ ca_private_key_passphrase passphrase for private CA secret key
+</source>
+```
+
+For output plugin, specify just 2 options below:
+
+* `secure`: set `yes` or `true`
+* `enable_strict_verification`: specify `yes` or `true`
+
+```apache
+<match secret.data.**>
+ type secure_forward
+
+ self_hostname myclient.local
+ shared_key secret_string
+
+ secure yes
+ ca_cert_path /path/for/certificate/ca_cert.pem
+ # enable_strict_verification yes
+
+ <server>
+ host server.fqdn.example.com # or IP
+ # port 24284
+ </server>
+ <server>
+ host 203.0.113.8 # ip address to connect
+ hostlabel server.fqdn.example.com # specify hostlabel for FQDN verification if ipaddress is used for host
+ </server>
+</match>
+```
+
+### Using insecure self-signed certificates
+
+**This is very dangerous and vulnerable to man-in-the-middle attacks**
+
+For just testing or data center internal communications, this plugin has a feature to communicate without any verification of certificates. Turn `secure` option to `false` to use this feature.
+
+```apache
+<source>
+ type secure_forward
+
+ self_hostname myserver.local
+ shared_key secret_string
+
+ secure no
+</source>
+```
+
+Configure output plugin just same way:
+
+```apache
+<match data.**>
+ type secure_forward
+
+ self_hostname myclient.local
+ shared_key secret_string
+
+ secure no
+
+ <server>
+ host server.fqdn.example.com # or IP
+ </server>
+</match>
+```
+
+In this mode, output plugin cannot verify peer node of connections. Man-in-the-middle attackers can spoof messages from output plugins under many various situations.
+
## Configuration
### SecureForwardInput
Default settings:
* listen 0.0.0.0:24284
* `bind 192.168.0.101`
- * `port 24285`
+ * `port 24284`
* allow to accept from any sources
* allow to connect without authentications
* use certificate automatically generated
* `generate_private_key_length 2048`
* `generate_cert_country US`
* `generate_cert_state CA`
* `generate_cert_locality Mountain View`
* `generate_cert_common_name SAME_WITH_SELF_HOSTNAME_PARAMETER`
+ * use TLSv1.2
Minimal configurations like below:
```apache
<source>
type secure_forward
shared_key secret_string
self_hostname server.fqdn.local # This fqdn is used as CN (Common Name) of certificates
- cert_auto_generate yes # This parameter MUST be specified
+
+ secure yes
+ # and configurations for certs
</source>
```
To check username/password from clients, like this:
```apache
<source>
type secure_forward
shared_key secret_string
self_hostname server.fqdn.local
- cert_auto_generate yes
+
+ secure yes
+ # and configurations for certs
+
authentication yes # Deny clients without valid username/password
<user>
username tagomoris
password foobar012
</user>
@@ -74,11 +224,14 @@
```apache
<source>
type secure_forward
shared_key secret_string
self_hostname server.fqdn.local
- cert_auto_generate yes
+
+ secure yes
+ # and configurations for certs
+
allow_anonymous_source no # Allow to accept from nodes of <client>
<client>
host 192.168.10.30
</client>
<client>
@@ -96,11 +249,14 @@
```apache
<source>
type secure_forward
shared_key secret_string
self_hostname server.fqdn.local
- cert_auto_generate yes
+
+ secure yes
+ # and configurations for certs
+
allow_anonymous_source no # Allow to accept from nodes of <client>
authentication yes # Deny clients without valid username/password
<user>
username tagomoris
password foobar012
@@ -128,20 +284,21 @@
</source>
```
### SecureForwardOutput
-Default settings:
- * allow to connect server using self-signed certificates
-
Minimal configurations like this:
```apache
<match secret.data.**>
type secure_forward
shared_key secret_string
self_hostname client.fqdn.local
+
+ secure yes
+ # and configurations for certs/verification
+
<server>
host server.fqdn.local # or IP
# port 24284
</server>
</match>
@@ -152,10 +309,14 @@
```apache
<match secret.data.**>
type secure_forward
shared_key secret_string
self_hostname ${hostname}
+
+ secure yes
+ # and configurations for certs/verification
+
<server>
host server.fqdn.local # or IP
# port 24284
</server>
</match>
@@ -168,10 +329,14 @@
```apache
<match secret.data.**>
type secure_forward
shared_key secret_string
self_hostname client.fqdn.local
+
+ secure yes
+ # and configurations for certs/verification
+
<server>
host first.fqdn.local
hostlabel server.fqdn.local
username repeatedly
password sushi
@@ -199,10 +364,14 @@
```apache
<match secret.data.**>
type secure_forward
shared_key secret_string
self_hostname client.fqdn.local
+
+ secure yes
+ # and configurations for certs/verification
+
keepalive 3600
<server>
host server.fqdn.local # or IP
# port 24284
</server>
@@ -214,36 +383,10 @@
* server
* in\_secure\_forward
* client
* out\_secure\_forward
-### Setup Phase (server)
-
-1. SSLContext
- * with certificate file / private key file
- 1. read cert file
- 2. generate SSLContext object
- * without certificate file
- 1. generate key pair
- 2. generate cert data
- 3. sign cert data with generated private key
-2. shared key
- * read shared key from configuration
-3. username / password pairs
- * read from configuration
-
-### Setup Phase (client)
-
-1. SSLContext
- 1. certificate
- * with certificate file, read from file
- * without certificate file, `new SSLContext` without any options
- 2. set SSLContext option which allow self signed key option or not
-2. shared key
- * read shared key from configuration
-3. read server list with username / password pairs from configuration
-
### Handshake
1. (client) connect to server
* on SSL socket handshake, checks certificate and its significate (in client)
2. (server)
@@ -280,20 +423,18 @@
* pipeline mode and one-by-one mode ?
* data sequence number in keepalive session ?
## TODO
-* test for non self-signed certificates
* ACK mode (protocol)
* support disabling keepalive (input/output)
* access control (input plugin)
* network acl / domain acl
* check connecting source ip and its dns reverse lookup result (for domaian acl)
* access deny on accept (against DoS)
* pluggable authentication database (input plugin)
* RDBMS, LDAP, or ...
* Authentication by clients certificate
-* encryption algorithm option (output plugin)
* TESTS!
## Copyright
* Copyright (c) 2013- TAGOMORI Satoshi (tagomoris)