diff options
author | Tom Ryder <tom@sanctum.geek.nz> | 2017-10-14 12:02:15 +1300 |
---|---|---|
committer | Tom Ryder <tom@sanctum.geek.nz> | 2017-10-14 12:11:13 +1300 |
commit | 5f2beb6dfccc4b7b1ac4fba719bf008f6ab02773 (patch) | |
tree | a8058658713ccafed2cf7146734800eaf9b128d0 | |
parent | Fix typo (diff) | |
download | Mail-Run-Crypt-5f2beb6dfccc4b7b1ac4fba719bf008f6ab02773.tar.gz Mail-Run-Crypt-5f2beb6dfccc4b7b1ac4fba719bf008f6ab02773.zip |
Fix lots of documentation and formatting
-rw-r--r-- | README.markdown | 105 | ||||
-rwxr-xr-x | bin/runcrypt | 58 | ||||
-rw-r--r-- | lib/Mail/Run/Crypt.pm | 111 |
3 files changed, 164 insertions, 110 deletions
diff --git a/README.markdown b/README.markdown index 5327928..6e6515e 100644 --- a/README.markdown +++ b/README.markdown @@ -8,21 +8,22 @@ Version 0.01 # DESCRIPTION -This module runs commands with `IPC::Run3::run3()`, and collects any standard -output and standard error it emits. If there is any standard output or standard -error content, it is signed and/or encrypted with GnuPG, and then mailed to a -specified recipient address (each stream separately). +This module runs a system command with [IPC::Run3](https://metacpan.org/pod/IPC::Run3), and collects any +standard output and standard error it emits. If there is any standard output or +standard error content, it is encrypted and optionally signed with GnuPG, and +then each stream's content is mailed separately to a specified recipient +address. The idea is to allow you to view the output of automated commands while having -the content encrypted as it passes through to your mailserver, and (optionally) -have some assurance that the content was actually generated by the server -concerned. `cron(8)` scripts are the ideal use case, but this would also work -with `at(1)` or anything else that might non-interactively run jobs for which +the content encrypted as it passes through to your mailserver, and optionally +to have some assurance that the content was actually generated by the server +concerned. **cron(8)** scripts are the ideal use case, but this would also work +with **at(1)**, or anything else that might non-interactively run jobs for which output is significant. -You probably want to call this with the `runcrypt(1)` program installed by -this distribution, which provides a means to set the properties for the module -via environment variables or command-line options. +You will probably want to call this with the [**runcrypt(1)**](https://metacpan.org/pod/runcrypt) program +provided by this distribution, which includes a means to set the properties for +the module via environment variables or command line options. # SYNOPSIS @@ -35,7 +36,7 @@ via environment variables or command-line options. ... my $mrc = Mail::Run::Crypt->new( sign => 1, - keyid => 0x1234DEAD, + keyid => '0x1234DEAD5678BEEF', passphrase => 'able was i ere i saw elba', mailto => 'you@example.net', ); @@ -44,85 +45,99 @@ via environment variables or command-line options. # SUBROUTINES/METHODS -## **new(%opts)** +## `new(%opts)` -Constructor accepts the following named parameters: +Constructor method; accepts the following named parameters: + +- `mailto` + + The recipient email address for the content. This is always required. - `sign` - Whether to sign the command output. This defaults to off. A key ID and - passphrase will be required for signing. + Whether to sign the command output. This defaults to 0. A `keyid` and + `passphrase` will be required for signing. - `encrypt` - Whether to encrypt the command output. This defaults to on. + Whether to encrypt the command output. This defaults to 1. - `keyid` - The GnuPG key ID that should be used to encrypt the messages. + The GnuPG key ID that should be used to encrypt the messages. This is required + for signing. It can be any means of identifying the key acceptable to GnuPG; + the key's 16-byte ("long") hexadecimal ID prefixed with `0x` is probably the + best way. - `passphrase` - The passphrase used to decrypt the key. - -- `mailto` - - The recipient email address for the content. + The passphrase used to decrypt the key. This is required for signing. - `name` - (Optional) The name of the object. When called from the `runcrypt(1)` - program, this will be the string "runcrypt". + (Optional) The name of the object. When called from the + [**runcrypt(1)**](https://metacpan.org/pod/runcrypt) program, this will be the string "runcrypt". + Otherwise, it will default to this package's name. -## **run(@command)** +## `run(@command)` -Run the specified arguments as a command with `IPC::Run3::run3()`, and email -any output or error content to the email recipient. +Run the specified arguments as a command with [IPC::Run3](https://metacpan.org/pod/IPC::Run3), and email +any output or error content to the email recipient, encrypting and/or signing +as configured. Returns 1 if the command succeeded, 0 otherwise. Use +[`bail()`](#bail) to get the actual exit code if needed. -## **bail()** +## `bail()` Return the exit status of the most recently run command, or 127 if no command has been successfully run. # DIAGNOSTICS -- mailto required +- `mailto required` The required `mailto` property was not passed in the constructor. -- keyid required for signing +- `keyid required for signing` Signing was specified, but no `keyid` attribute was passed in the constructor. -- passphrase required for signing +- `passphrase required for signing` Signing was specified, but no `passphrase` attribute was passed in the constructor. -- command failed: %s +- `command failed: %s` - The command did not merely fail, it could not even be started, with the given - error string. This is typically due to problems finding the executable. + The command could not be run at all, raising the given error string. This is + typically due to problems finding the executable. # CONFIGURATION AND ENVIRONMENT You will need to have a functioning GnuPG public key setup for this to work, -including the secret key. You should definitely not use your personal key; -generate one specifically for mail signing and encryption instead. +including stored keys or a key retrieval system for your recipients. You will +also need a secret key if you want to sign the messages. + +You should _definitely not_ use your personal key for this; generate one +specifically for mail signing and encryption instead. + +I wrote a tutorial on GnuPG key setup, including agent configuration, as part +of this series: + +[https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/](https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/) # DEPENDENCIES - Perl v5.10.0 or newer -- `Carp` -- `Const::Fast` -- `English` -- `IPC::Run3` -- `Mail::GnuPG` -- `MIME::Entity` +- [Carp](https://metacpan.org/pod/Carp) +- [Const::Fast](https://metacpan.org/pod/Const::Fast) +- [English](https://metacpan.org/pod/English) +- [IPC::Run3](https://metacpan.org/pod/IPC::Run3) +- [Mail::GnuPG](https://metacpan.org/pod/Mail::GnuPG) +- [MIME::Entity](https://metacpan.org/pod/MIME::Entity) # INCOMPATIBILITIES -This module uses `Mail::GnuPG` and other GPG-specific code, so it won't work -with any other OpenPGP implementations. +This module uses [Mail::GnuPG](https://metacpan.org/pod/Mail::GnuPG) and other GnuPG-specific code, so +it won't work with other OpenPGP implementations. # BUGS AND LIMITATIONS diff --git a/bin/runcrypt b/bin/runcrypt index 9d207a4..fe0f3b3 100755 --- a/bin/runcrypt +++ b/bin/runcrypt @@ -81,7 +81,7 @@ if ( !@ARGV ) { exit 2; } -# Create an MRC object +# Build option set for MRC constructor my %opts = ( sign => $opt->sign, encrypt => $opt->encrypt, @@ -141,9 +141,9 @@ runcrypt - Encrypt and mail output from command in arguments =head1 DESCRIPTION -This program applies C<Mail::Run::Crypt> to run a command and send any output -or error content to the specified address. More information is available in the -documentation for that module. +This program applies L<Mail::Run::Crypt|Mail::Run::Crypt> to run a command and +send any output or error content to the specified address. More information is +available in the documentation for that module. =head1 REQUIRED ARGUMENTS @@ -157,17 +157,20 @@ The arguments beyond the options are used as the command name to run: =item C<--sign> -Whether to sign the output. This defaults to off. A key ID and passphrase file -will need to be provided for signing to work. +Whether to sign the output. This defaults to 0. An ID and passphrase file will +need to be provided for signing to work. =item C<--encrypt> -Whether to encrypt the output to the recipient. This defaults to on. +Whether to encrypt the output to the recipient. This defaults to 1. =item C<--keyid> -The GnuPG key ID that should be used to sign and encrypt the messages. This -defaults to the value of the environment variable C<RUNCRYPT_KEYID>. +The GnuPG key ID that should be used to encrypt the messages. This is required +for signing. It can be any means of identifying the key acceptable to GnuPG; +the key's 16-byte ("long") hexadecimal ID prefixed with C<0x> is probably the +best way. This defaults to the value of the environment variable +C<RUNCRYPT_KEYID>. It is I<strongly> recommended that a dedicated key and passphrase be used for signatures if this is needed. You should carefully consider the consequences of @@ -188,7 +191,7 @@ This has too many negative security implications. The recipient address for the encryption portion of the email. This defaults to the value of the environment variable C<RUNCRYPT_MAILTO> if that is set, or -C<MAILTO> failing that, to make it suitable for use in a C<crontab(5)> file. +C<MAILTO> failing that, to make it suitable for use in a B<crontab(5)> file. =item C<--name> @@ -223,14 +226,23 @@ The specified passphrase file could not be closed. This is not a fatal error. =head1 EXIT STATUS The program exits with the same exit value of the command that it ran, or 127 -if the command could not be run at all. See the C<bail()> method in -C<Mail::Run::Crypt>. +if the command could not be run at all. See the +L<C<bail()>|Mail::Run::Crypt/bail()> method in +L<Mail::Run::Crypt|Mail::Run::Crypt>. =head1 CONFIGURATION You will need to have a functioning GnuPG public key setup for this to work, -including the secret key. You should definitely not use your personal key; -generate one specifically for mail signing and encryption instead. +including stored keys or a key retrieval system for your recipients. You will +also need a secret key if you want to sign the messages. + +You should I<definitely not> use your personal key for this; generate one +specifically for mail signing and encryption instead. + +I wrote a tutorial on GnuPG key setup, including agent configuration, as part +of this series: + +L<https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/> =head1 DEPENDENCIES @@ -242,22 +254,30 @@ Perl 5.10 or newer =item * -C<Carp> +L<Carp|Carp> + +=item * + +L<English|English> + +=item * + +L<File::stat|File::stat> =item * -C<Getopt::Long::Descriptive> +L<Getopt::Long::Descriptive|Getopt::Long::Descriptive> =item * -C<Mail::Run::Crypt> +L<Mail::Run::Crypt|Mail::Run::Crypt> =back =head1 INCOMPATIBILITIES -This module uses C<Mail::GnuPG> and other GPG-specific code, so it won't work -with any other OpenPGP implementations. +This module uses L<Mail::GnuPG|Mail::GnuPG> and other GPG-specific code, so it +won't work with any other OpenPGP implementations. =head1 BUGS AND LIMITATIONS diff --git a/lib/Mail/Run/Crypt.pm b/lib/Mail/Run/Crypt.pm index 5631acb..64dd7e5 100644 --- a/lib/Mail/Run/Crypt.pm +++ b/lib/Mail/Run/Crypt.pm @@ -35,7 +35,7 @@ sub new { or croak 'mailto required'; # Default the instance name to the package name if it wasn't given; - # runcrypt(1p) will pass it in + # runcrypt(1) will pass it in $self->{name} //= $class; # We default to encrypting but not signing @@ -139,21 +139,22 @@ Version 0.01 =head1 DESCRIPTION -This module runs commands with C<IPC::Run3::run3()>, and collects any standard -output and standard error it emits. If there is any standard output or standard -error content, it is signed and/or encrypted with GnuPG, and then mailed to a -specified recipient address (each stream separately). +This module runs a system command with L<IPC::Run3|IPC::Run3>, and collects any +standard output and standard error it emits. If there is any standard output or +standard error content, it is encrypted and optionally signed with GnuPG, and +then each stream's content is mailed separately to a specified recipient +address. The idea is to allow you to view the output of automated commands while having -the content encrypted as it passes through to your mailserver, and (optionally) -have some assurance that the content was actually generated by the server -concerned. C<cron(8)> scripts are the ideal use case, but this would also work -with C<at(1)> or anything else that might non-interactively run jobs for which +the content encrypted as it passes through to your mailserver, and optionally +to have some assurance that the content was actually generated by the server +concerned. B<cron(8)> scripts are the ideal use case, but this would also work +with B<at(1)>, or anything else that might non-interactively run jobs for which output is significant. -You probably want to call this with the C<runcrypt(1)> program installed by -this distribution, which provides a means to set the properties for the module -via environment variables or command-line options. +You will probably want to call this with the L<B<runcrypt(1)>|runcrypt> program +provided by this distribution, which includes a means to set the properties for +the module via environment variables or command line options. =head1 SYNOPSIS @@ -166,7 +167,7 @@ via environment variables or command-line options. ... my $mrc = Mail::Run::Crypt->new( sign => 1, - keyid => 0x1234DEAD, + keyid => '0x1234DEAD5678BEEF', passphrase => 'able was i ere i saw elba', mailto => 'you@example.net', ); @@ -174,46 +175,56 @@ via environment variables or command-line options. =head1 SUBROUTINES/METHODS -=head2 B<new(%opts)> +=head2 C<new(%opts)> -Constructor accepts the following named parameters: +Constructor method; accepts the following named parameters: =over 4 +=item C<mailto> + +The recipient email address for the content. This is always required. + =item C<sign> -Whether to sign the command output. This defaults to off. A key ID and -passphrase will be required for signing. +Whether to sign the command output. This defaults to 0. A C<keyid> and +C<passphrase> will be required for signing. =item C<encrypt> -Whether to encrypt the command output. This defaults to on. +Whether to encrypt the command output. This defaults to 1. =item C<keyid> -The GnuPG key ID that should be used to encrypt the messages. - -=item C<passphrase> +The GnuPG key ID that should be used to encrypt the messages. This is required +for signing. It can be any means of identifying the key acceptable to GnuPG; +the key's 16-byte ("long") hexadecimal ID prefixed with C<0x> is probably the +best way. -The passphrase used to decrypt the key. +It is I<strongly> recommended that a dedicated key and passphrase be used for +signatures if this is needed. You should carefully consider the consequences of +a compromised key. -=item C<mailto> +=item C<passphrase> -The recipient email address for the content. +The passphrase used to decrypt the key. This is required for signing. =item C<name> -(Optional) The name of the object. When called from the C<runcrypt(1)> -program, this will be the string "runcrypt". +(Optional) The name of the object. When called from the +L<B<runcrypt(1)>|runcrypt> program, this will be the string "runcrypt". +Otherwise, it will default to this package's name. =back -=head2 B<run(@command)> +=head2 C<run(@command)> -Run the specified arguments as a command with C<IPC::Run3::run3()>, and email -any output or error content to the email recipient. +Run the specified arguments as a command with L<IPC::Run3|IPC::Run3>, and email +any output or error content to the email recipient, encrypting and/or signing +as configured. Returns 1 if the command succeeded, 0 otherwise. Use +L<C<bail()>|/bail()> to get the actual exit code if needed. -=head2 B<bail()> +=head2 C<bail()> Return the exit status of the most recently run command, or 127 if no command has been successfully run. @@ -222,30 +233,38 @@ has been successfully run. =over 4 -=item mailto required +=item C<mailto required> The required C<mailto> property was not passed in the constructor. -=item keyid required for signing +=item C<keyid required for signing> Signing was specified, but no C<keyid> attribute was passed in the constructor. -=item passphrase required for signing +=item C<passphrase required for signing> Signing was specified, but no C<passphrase> attribute was passed in the constructor. -=item command failed: %s +=item C<command failed: %s> -The command did not merely fail, it could not even be started, with the given -error string. This is typically due to problems finding the executable. +The command could not be run at all, raising the given error string. This is +typically due to problems finding the executable. =back =head1 CONFIGURATION AND ENVIRONMENT You will need to have a functioning GnuPG public key setup for this to work, -including the secret key. You should definitely not use your personal key; -generate one specifically for mail signing and encryption instead. +including stored keys or a key retrieval system for your recipients. You will +also need a secret key if you want to sign the messages. + +You should I<definitely not> use your personal key for this; generate one +specifically for mail signing and encryption instead. + +I wrote a tutorial on GnuPG key setup, including agent configuration, as part +of this series: + +L<https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/> =head1 DEPENDENCIES @@ -257,34 +276,34 @@ Perl v5.10.0 or newer =item * -C<Carp> +L<Carp|Carp> =item * -C<Const::Fast> +L<Const::Fast|Const::Fast> =item * -C<English> +L<English|English> =item * -C<IPC::Run3> +L<IPC::Run3|IPC::Run3> =item * -C<Mail::GnuPG> +L<Mail::GnuPG|Mail::GnuPG> =item * -C<MIME::Entity> +L<MIME::Entity|MIME::Entity> =back =head1 INCOMPATIBILITIES -This module uses C<Mail::GnuPG> and other GPG-specific code, so it won't work -with any other OpenPGP implementations. +This module uses L<Mail::GnuPG|Mail::GnuPG> and other GnuPG-specific code, so +it won't work with other OpenPGP implementations. =head1 BUGS AND LIMITATIONS |