Documentation
7.13. Encrypt / decrypt using OpenPGP / GPG¶
The openpgp event handler can be configured to encrypt or decrypt files using the OpenPGP standard (tools like PGP or GPG).
All files with the .pgp or .gpg extensions are decrypted, all the other files are encrypted.
Encrypted files will have the .pgp extension appended to their filename.
The handler can be associated with events containing a list of files. It will try to handle each file associated with the event and will stop at the first failure.
7.13.1. name¶
- Default value
''
- Optional
No
- From version
2.10.0
- Values
Any text.
- Description
Human-readable short text used to identify this event handler.
7.13.2. description¶
- Default value
''
- Optional
Yes
- From version
2.10.0
- Values
Any text.
- Description
Human-readable text that describes the purpose of this event handler.
7.13.3. type¶
- Default value
''
- Optional
No
- From version
2.10.0
- Values
file-dispatcher - Dispatch a file into one or multiple paths.
http - HTTP POST request (unsecured).
local-file - Append events to a file located on the local file system.
email-sender - Send emails as an SMTP client.
windows-eventlog - Send events to Windows EventLog Service.
standard-stream - Send events to standard output.
syslog - Local Unix socket or remote IP:PORT address for Syslog.
create-archive - Create/Compresses one or more files.
extract-archive - Extract/Uncompressed a file.
external-executable - Execute an external script or program.
openpgp - Encrypt/Decrypt files using OpenPGP.
rabbitmq - Publish event to RabbitMQ AMQP 0-9-1 server.
extension - For custom event handlers implemented using our API.
- Description
This option specifies the type of the event handler. Each type has a set of specific configuration options.
7.13.4. target¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of event ids.
Comma separated list of event ids starting with an exclamation mark.
Leave empty to handle all events.
- From version
2.10.0
- Description
Define a comma separated list of event ids to have the event handler triggered only for those events.
When you want to have it triggered for all the events, excepting a few events you should prefix each event id with the exclamation mark (!).
Leave it empty to handle all events.
Note
Combining the two methods is not supported as the same result can be achieved by allowing only the desired events, all the others will be ignored.
7.13.5. groups¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of event groups.
Comma separated list of event groups starting with an exclamation mark.
Empty.
- From version
3.39.0
- Description
Defines the list of event groups for which this handler is active.
When you want to handle all the events, except for the ones from a set of groups, prefix the group names with the exclamation mark (!).
An event can be a member of one or multiple groups. The event is handled if any of its groups is found in the list of configured allowed groups. The event is not handled if any of its groups is found in the list of configured ignored groups (starting with !).
Leave it empty to handle events from all groups.
7.13.6. usernames¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of usernames.
Comma separated list of usernames starting with an exclamation mark.
Leave empty to handle all events.
- From version
3.9.0
- Description
Comma separated list of usernames whose events are handled by this event handler. A username can include OS accounts, application accounts, and any accounts accepted by any authentication method including external HTTP accounts.
When you want to have it triggered for all the events, excepting a few events you should prefix each username with the exclamation mark (!).
Leave it empty to handle events from any users or events which are not associated with any user.
7.13.7. components¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of UUIDs.
Comma separated list of UUIDs starting with an exclamation mark.
Leave empty to handle all events.
- From version
3.18.0
- Description
Comma separated list of component UUIDs for which events are handled by this event handler.
When you want to have it triggered for all the events, excepting a few events you should prefix each UUID with the exclamation mark (!).
Leave it empty to handle events emitted by any component.
7.13.8. source_addresses¶
- Default value
Empty
- Optional
Yes
- Values
Comma separated list of IP addresses.
List of IP addresses starting with an exclamation mark.
Empty.
- From version
3.40.0
- Description
Comma separated list of source IP addresses of the remote peers, which are handled by this event handler.
When you want to have it triggered for all the addresses, excepting a few addresses you should prefix each address with the exclamation mark (!).
Leave it empty to handle events emitted by any source address.
7.13.9. data_filter¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of data member name and filter expression.
Leave empty to handle all events.
- From version
3.22.0
- Description
Comma separated definition with name of attribute data member and the targeted matching expression.
Data member names are configured with insensitive cases.
For more details about the available expressions see the matching expression documentation.
The following example will extract the to be matched/filtered value from the path data member of the event. The extracted value is then matched against the
*/folderA/*globbing expression:[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f] data_filter = path, */folderA/*
See the usage instructions for more operational details.
You can filter only based on a single data member with a single matching expression.
Leave it empty to not filter based on the event's attached data.
7.13.10. fail_after_errors¶
- Default value
10
- Optional
Yes
- From version
3.0.0
- Values
An integer number greater than 0.
0 Disabled.
- Description
Number of consecutive errors after which the event handler will automatically stop with a failed state.
Setting this to 0 will disable the feature. The event handler will no longer stop regardless of the number of errors encountered.
7.13.11. encryption_public_keys¶
- Default value
''
- Optional
Yes
- Values
ASCII armored public PGP keys
- From version
4.0.0
- Description
Lists of public PGP keys used for the encryption operation.
It can contain one or multiple public PGP keys in printable ASCII format.
Leave it empty if you don't want to use asymmetric encryption.
7.13.12. decryption_private_keys¶
- Default value
''
- Optional
Yes
- Values
ASCII armored private PGP keys
- From version
4.0.0
- Description
Lists of private PGP keys used for the decryption operation.
It can contain one or multiple private PGP keys in printable ASCII format.
Leave it empty if you don't want to use asymmetric encryption.
7.13.13. passphrase¶
- Default value
Empty
- Optional
No
- Values
Text
- From version
4.0.0
- Description
Passphrase/password for encrypting/decrypting files using symmetric OpenPGP cryptography.
Leave it empty if you don't want to use symmetric encryption.
7.13.14. encryption_extension¶
- Default value
.pgp
- Optional
Yes
- Values
Text to be appended after the file name.
- From version
4.0.0
- Description
File extension used for the files encrypted by the handler.
Encrypted files will have the configured text appended to the original name.
This value is case-sensitive.
7.13.15. encryption_cipher¶
- Default value
AES128
- Optional
Yes
- Values
AES128
AES192
AES256
CAST5
3DES
- From version
4.0.0
- Description
Cipher used for symmetric encryption.
This value is not used when passphrase is not defined, as that is required for symmetric encryption.
This value is case-insensitive.
7.13.16. source_attribute¶
- Default value
real_path- Optional
Yes
- Values
Event data member name.
- From version
4.0.0
- Description
Name of the event's structured data member used to get the path to be handled.
This is a case-insensitive value.
7.13.17. destination_path¶
- Default value
empty
- Optional
Yes
- Values
Absolute path on the local filesystem.
- From version
4.0.0
- Description
The path where the resulting files are encrypted/decrypted.
Leave it empty to perform file operations in the path of the source files.
7.13.18. overwrite_rule¶
- Default value
fail
- Optional
Yes
- From version
4.7.0
- Values
fail - abort transfer if destination file already exists.
overwrite - always overwrite existing files with the content of the new source files.
disable - don't check for existing file and always try to transfer the file.
skip - don't transfer the source file when destination exists.
- Description
Rule used to decide how to handle the overwriting of an existing file at the destination.
When set to overwrite it will emit an event when the destination file is overwritten.
When set to skip it will not handle the file and the source file is not removed. An event is emitted to inform that the file was skipped.
7.13.19. delete_source_on_success¶
- Default value
Yes
- Optional
yes
- Values
Yes
No
- From version
4.0.0
- Description
Whether to delete the source file after a successful operation.
If encrypting/decrypting the source file fails, the source is not removed, even when this is set to Yes.