readme.txt

=== WP PGP Encrypted Emails ===
Contributors: maymay
Donate link: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=TJLPJYXHSRBEE&lc=US&item_name=WP%20PGP%20Encrypted%20Emails&item_number=wp-pgp-encrypted-emails&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted
Tags: encryption, email, security, privacy, pgp, gpg, openpgp, smime
Requires at least: 4.4
Tested up to: 5.7
Stable tag: 0.8.0
License: GPL-3.0
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Signs and encrypts emails using PGP/GPG keys or X.509 certificates. Provides OpenPGP and S/MIME functions via WordPress plugin API.

== Description ==

WP PGP Encrypted Emails can automatically sign and encrypt any email that WordPress sends to your site's admin email address or your users's email addresses. You give it a copy of the recipient's OpenPGP public key and/or their S/MIME certificate, and it does the rest. You can even automatically generate an OpenPGP signing keypair for your site to use.

Encrypting outgoing emails protects your user's privacy by ensuring that emails intended for them can be read only by them, and them alone. Moreover, signing those emails helps your users verify that email they receive purporting to be from your site was *actually* sent by your server, and not some imposter. If you're a plugin or theme developer, you can encrypt and/or sign *arbitrary data* using this plugin's OpenPGP and S/MIME APIs, which are both built with familiar, standard WordPress filter hooks. This enables you to develop highly secure communication and publishing tools fully integrated with your WordPress install. See the [`README.markdown`](https://github.com/fabacab/wp-pgp-encrypted-emails/#readme) file for details on cryptographic implementation and API usage.

*Donations for this and my other free software plugins make up a chunk of my income. If you continue to enjoy this plugin, please consider [making a donation](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=TJLPJYXHSRBEE&lc=US&item_name=WP%20PGP%20Encrypted%20Emails&item_number=wp-pgp-encrypted-emails&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted). :) Thank you for your support!*

Plugin features:

* Processes *all* email your site generates, automatically and transparently.
* Configure outbound signing: sign email sent to *all* recipients, or just savvy ones.
* Per-user encryption keys and certificates; user manages their own OpenPGP keys and S/MIME certificates.
* Compatible with thousands (yes, thousands) of third-party contact form plugins.
* Full interoperability with all standards-compliant OpenPGP and S/MIME implementations.
* Options to enforce further privacy best practices (e.g., removing `Subject` lines).
* Fully multisite compatible, out of the box. No additional configuration for large networks!
* No binaries to install or configure; everything you need is in the plugin itself.
* Bells and whistles included! For instance, visitors can encrypt comments on posts so only the author can read them.
* Built-in, customizable integration with popular third-party plugins, such as [WooCommerce](https://wordpress.org/plugins/woocommerce/).
* Always **FREE**. Replaces paid email encryption "upgrades," and gets rid of yearly subscription fees. ([Donations](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=TJLPJYXHSRBEE&lc=US&item_name=WP%20PGP%20Encrypted%20Emails&item_number=wp-pgp-encrypted-emails&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted) appreciated!)
* And *more*, of course. ;)

The plugin works transparently for *all email* your site generates, and will also sign and encrypt outgoing email generated by other plugins (such as contact form plugins) or the built-in WordPress notification emails. All you have to do is add one or more OpenPGP keys or an S/MIME certificate to the Email Encryption screen (WordPress Admin Dashboard → Settings → Email Encryption). Each user can opt to also remove envelope information such as email subject lines, which encryption schemes cannot protect. With this plugin, there's no longer any need to pay for the "pro" version of your favorite contact form plugin to get the benefit of email privacy.

Each of your site's users can supply their own, personal OpenPGP public key and/or X.509 S/MIME certificate for their own email address to have WordPress automatically encrypt any email destined for them. (They merely need to update their user profile.) They can choose which encryption method to use. Once set up, all future emails WordPress sends to that user will be encrypted using the standards-based OpenPGP or S/MIME technologies.

The OpenPGP-encrypted emails can be decrypted by any OpenPGP-compatible mail client, such as [MacGPG](https://gpgtools.org/) (macOS), [GPG4Win](https://www.gpg4win.org/) (Windows), [Enigmail](https://www.enigmail.net/) (cross-platform), [OpenKeychain](https://openkeychain.org/) (Android), or [iPGMail](https://ipgmail.com/) (iPhone/iOS). For more information on reading encrypted emails, generating keys, and other uses for OpenPGP-compatible encryption, consult any (or all!) of the following guides:

* [The Electronic Frontier Foundation's Surveillance Self-Defense guide to PGP](https://ssd.eff.org/en/module/introduction-public-key-cryptography-and-pgp)
* [RiseUp.net's OpenPGP best practices guide](https://help.riseup.net/en/gpg-best-practices)
* [OpenPGP.org](https://www.openpgp.org/)

The S/MIME-encrypted emails can be decrypted by any S/MIME-compatible mail client. These include [Apple's Mail on macOS](http://siber-sonic.com/mac/MailSMIME/) and [iOS for iPhone and iPad](https://support.apple.com/en-au/HT202345), [Microsoft Outlook](https://support.office.com/en-us/article/Encrypt-messages-by-using-S-MIME-in-Outlook-Web-App-2E57E4BD-4CC2-4531-9A39-426E7C873E26), [Claws Mail for GNU/Linux](http://www.claws-mail.org/faq/index.php/S/MIME_howto), and more.

For developers, WP PGP Encrypted Emails provides [an easy to use API to both OpenPGP](https://github.com/fabacab/wp-pgp-encrypted-emails/blob/develop/README.markdown#openpgp-api) and [S/MIME](https://github.com/fabacab/wp-pgp-encrypted-emails/blob/develop/README.markdown#smime-api) encryption, decryption, and integrity validation operations through the familiar [WordPress plugin API](https://codex.wordpress.org/Plugin_API) so you can use this plugin's simple filter hooks to build custom OpenPGP- or S/MIME-based encryption functionality into your own plugins and themes.

**Security Disclaimer**

Security is a process, not a product. Using WP PGP Encrypted Emails does not guarantee that your site's outgoing messages are invulnerable to every attacker, in every possible scenario, at all times. No single security measure, in isolation, can do that.

Do not rely solely on this plugin for the security or privacy of your webserver. See the [Frequently Asked Questions](https://wordpress.org/plugins/wp-pgp-encrypted-emails/faq/) for more security advice and for more information about the rationale for this plugin.

== Installation ==

WP PGP Encrypted Emails can be installed automatically from the WordPress plugin repository by searching for "PGP Encrypted Emails" in the "Add new plugin" screen of your WordPress admin site and clicking the "Install now" button.

Minimum requirements:

* PHP version 5.4 or later.
* S/MIME support requires the [OpenSSL PHP extension](https://secure.php.net/manual/book.openssl.php). (This is almost certainly already installed for you.)

The plugin will automatically de-activate itself, or automatically disable certain features, if these requirements are not met. If you do not see a given feature in the user interface, ensure your server (and your web hosting provider) meet the above requirements!

WP PGP Encrypted Emails can also be installed manually by following these instructions:

1. [Download the latest plugin code](https://downloads.wordpress.org/plugin/wp-pgp-encrypted-emails.zip) from the WordPress plugin repository.
1. Upload the unzipped `wp-pgp-encrypted-emails` folder to the `/wp-content/plugins/` directory of your WordPress installation.
1. Activate the plugin through the "Plugins" menu in WordPress.

Once activated, each user who wants to receive encrypted emails must add their OpenPGP public key or S/MIME public certificate to their profile, and optionally choose the type of encryption they prefer messages addressed to them will use.

See the [screenshots](https://wordpress.org/plugins/wp-pgp-encrypted-emails/screenshots/) for a brief walkthrough of how to configure WP PGP Encrypted Emails after it is installed.

If a user does not have an OpenPGP public key already, they need to use an OpenPGP-compatible client to generate one themselves. ([Learn more about OpenPGP-compatible clients](https://wordpress.org/plugins/wp-pgp-encrypted-emails/faq/).) Users will need to have the private key corresponding to the public key saved in their WordPress profile in order to be able to decrypt the email they receive. To learn more about generating keys and decrypting email, consult one (or more) of the following guides:

* [The Electronic Frontier Foundation's Surveillance Self-Defense guide to PGP](https://ssd.eff.org/en/module/introduction-public-key-cryptography-and-pgp)
* [RiseUp.net's OpenPGP best practices guide](https://help.riseup.net/en/gpg-best-practices)

I have also found the following articles useful, but can not personally vouch for their accuracy:

* [Jerzy Gangi's "Best PGP Tutorial for Mac OS X, ever"](http://notes.jerzygangi.com/the-best-pgp-tutorial-for-mac-os-x-ever/)
* [DeepDotWeb's Basic Guide to PGP on Linux](https://web.archive.org/web/20190503073351/https://www.deepdotweb.com/2015/02/17/basic-guide-pgp-linux/)
* [BitCoin Not Bombs: Beginner's Guide to PGP](http://www.bitcoinnotbombs.com/beginners-guide-to-pgp/)

If you found a good guide to using PGP/GPG that I haven't listed here, please share it in [the WP PGP Encrypted Emails plugin support forum](https://wordpress.org/support/plugin/wp-pgp-encrypted-emails#postform).

Similarly, if a user doesn't already have one, they will need to obtain an S/MIME certificate from a Certificate Authority (such as a public CA or their employer), or generate a self-signed one themselves. [Learn more about getting an S/MIME certificate](http://kb.mozillazine.org/Getting_an_SMIME_certificate).

To view a list of known issues with this plugin or to report a bug, please use [the project's issue tracker](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/).

== Frequently Asked Questions==

= What is an OpenPGP-compatible client and where can I get one? =

An OpenPGP-compatible client is simply an app that can read, write, and verify messages encrypted or signed using PGP technology. There are great, free apps for every major platform, including Windows, Mac, Linux, Android, iPhones, iPads, and more. Which app you choose depends largely on which device you already have, and then a bit about your personal tastes.

Since there are so many OpenPGP-compatible apps to choose from, I recommend sticking to the [ones listed on the PRISM-Break.org website](https://prism-break.org/en/protocols/gpg/). (Note that PRISM-Break calls it "GPG" instead of "PGP," but the two terms are generally synonymous.) Once you choose an OpenPGP-compatible app for your platform, consider seeking out its help and support documentation to get started using it, or check out some of the generic PGP/GPG guides listed at the end of [this plugin's Installation page](https://wordpress.org/plugins/wp-pgp-encrypted-emails/installation/).

= I can't decrypt messages addressed to my admin email address! =

If you have registered a WordPress user account with the same email address as your site's admin email address (in the Settings → General screen), then WP PGP Encrypted Emails will first check for a public key or certificate in the administrative Email Encryption settings (Settings → Email Encryption) before looking at your user's profile settings. If an encryption key or certificate exists in the administrative settings, that key will be used instead of the key or certificate in the user's profile. To resolve this issue, either ensure that you enter encryption keys in only one location (the administrative screen or the user's profile), or ensure these keys are the same.

If you still cannot decrypt messages, make absolutely certain you have the matching private key or certificate corresponding to the public key or certificate that was used to encrypt the message. Unfortunately, it is highly infeasible that anyone on Earth will be able to decrypt messages encrypted to a public key or certificate that you do not have the associated private key for. That is, of course, the whole point of this software.

= How do I read an encrypted comment? =

If you have received a "Private" comment, you will need to use an OpenPGP-compatible PGP client to decrypt and read it. There are many free apps that do this. Which one you choose depends on what kind of computer you are already using. If you use Windows, I suggest installing and using [GPG4Win](https://www.gpg4win.org/) since it provides the most features. For Mac OS X users, I suggest [MacGPG](http://gpgtools.org/) for the same reason, and Linux users should check their distro's package repository for compatible options. (For Ubuntu users, the [Seahorse-Nautilus](http://packages.ubuntu.com/precise/gnome/seahorse-nautilus) plugin is popular.)

I might also add support for an in-browser client based on [OpenPGP.js](http://openpgpjs.org/) at some point, but for now you will still need an external program to read encrypted comments. Please consider [donating](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=TJLPJYXHSRBEE&lc=US&item_name=WP%20PGP%20Encrypted%20Emails&item_number=wp-pgp-encrypted-emails&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted) to help resource me work on this if that is a feature you'd like to see.

= Why are emails from [other-plugin-here] not being encrypted? =

Make sure the emails the other plugin sends are being addressed to an email account that WordPress knows about and that WordPress knows which OpenPGP public key or S/MIME certificate to use when encrypting email destined for that address.

More specifically, this means the `TO:` field of the outgoing email needs to match either your WordPress's "admin email" address or the email address of one of your WordPress user accounts, and you need to provide the OpenPGP public key or S/MIME public certificate you want WordPress to use when encrypting the message and sending email to that address. In many contact form plugins, you can supply an arbitrary email address to send those emails to, but if that email address is not the address of a user on your site, WP PGP Encrypted Emails won't know which OpenPGP public key or S/MIME public certificate to use for encryption.

As a workaround, simply create an unprivileged ("Subscriber" [role](https://codex.wordpress.org/Roles_and_Capabilities)) new WordPress user account with that email address and enter the OpenPGP public key or S/MIME certificate in that user's profile. (Either accept the automatically generated password, or supply a new very strong passphrase, since you will not need to remember it because you will never need to log in with that user account.)

= Why are my emails appearing strangely in my email client? =

Issues with character sets, accented characters, different human languages, or content types not appearing correctly are almost always the result of a misconfiguration in the email-sending plugin you are using. Many contact form plugins, for example, allow you to supply custom email headers. WP PGP Encrypted Emails takes great care not to corrupt the email message sent by the underlying plugin that generated the email in the first place. However, this also means that if you do not set up your contact form or email-sending plugin correctly, this plugin won't fix the error.

Most often, this is simply a matter of setting the correct Content-Type header in your contact form or email-sending plugin's settings.

= Is this plugin *really* secure? =

Against the NSA? No, probably not. Against a nosy co-worker? Yes, probably.

The "realness" of security cannot "really" be measured in abstract, imprecise terms, but rather only based on what real threats you are likely to face and what risks you are vulnerable to if those threats materialize in reality. You have a much better sense of the answers to these things than I do for your situation, because I am not you. Security professionals call this process "threat modeling," and if you are "really" concerned for your security (I encourage you to be!) then learning how to conduct a threat assessment for yourself is a good idea. [Learn more about threat modeling from the EFF's Surveillance Self-Defense Guide](https://ssd.eff.org/en/module/introduction-threat-modeling).

= If this plugin isn't secure against the NSA, what good is it? =

TL;DR: Don't let perfect be the enemy of good.

First of all, not everyone's security needs are the same. (See "threat modeling," discussed in the previous question.)

* Against an opportunistic attacker, your security measures merely need to be better than your neighbor's in order to be sufficient to deter attacks. This is "good enough" security for most users of WordPress, especially on shared hosting accounts (which are generally closer to the unsafe side of the security spectrum no matter what plugins you install anyway).
* Against a well-resourced, determined adversary who has specifically singled you out, however, what matters is that your ability to secure yourself exceeds your adversary's ability to compromise the specific security precautions you've put in place. Your relative security as compared with your neighbor's doesn't matter. In this case, it is better to do anything and everything you reasonably can do for your protection, even if no specific security measure will be enough on its own. This is known as "[defense in depth](https://en.wikipedia.org/wiki/Defense_in_depth_%28computing%29)" and is analogous to the way a medival castle had a moat that surrounded an outer wall which itself surrounded an inner wall protecting a keep. These concentric rings of security provide redundancy and serve to slow an attacker's intrusion. This plugin can be considered *one* small part of a larger defense-in-depth security approach for your website.

Read [Bruce Schneier's "Lessons from the Sony Hack"](https://www.schneier.com/blog/archives/2014/12/lessons_from_th_4.html) for a brief, real-life case study in understanding this important nuance between opportunistic and focused attackers.

Further, security is largely a matter of operational practice, not theoretics. If you never use PGP/GPG because the only tools you have access to are not perfect, then you will not have the experience you need to know how to use PGP/GPG when you actually get access to it, because you never even practiced using it. By way of analogy, if you want to learn swordfighting but all you have is sticks you picked up in the forest, you are better off picking up those sticks and practicing with them than waiting and not practicing at all until you get your hands on steel swords.

= Can I use a "strong" key for my user account? =

Yes. You can use any OpenPGP public key you generate from any OpenPGP-compatible client.

= How strong is the signing key the plugin generates? =

When generating an OpenPGP signing keypair for your WordPress site, this plugin will create a 2,048-bit RSA OpenPGP keypair. This is considered "okay" (but not "great") by 2018 standards. Unfortunately, many hosts will not allow the plugin to create a stronger keypair because of the computation required. Then again, this key is used only for signing, not encryption. Your own OpenPGP public key is always used for encryption, and you are of course encouraged to make that key as strong as you want.

If you want to use a stronger signing keypair, you can generate one yourself (offline), though you will need to load the key into your WordPress database yourself to use it with this plugin. I consider this extra step "paranoid," but you are of course welcome to be as careful as you feel is appropriate. :)

== Screenshots ==

1. Paste the plain text version of your OpenPGP public key into the "PGP Public Key" field in your profile, then click "Save changes" at the bottom of the page. (There is a similar field for the WordPress admin email in the General Settings screen accessible to Administrator users.)

2. If the plugin detects a problem with your OpenPGP public key, you will get a notice like the one shown here.

3. Authors who add an OpenPGP public key to their profile also let readers leave semi-private comments on their posts. These are comments that are automatically encrypted to the author's public key upon submission. Commenters who want to send a "Private" comment simply write their comment normally and ensure the encryption checkbox is enabled when they submit their comment.

4. Administrators can generate an OpenPGP signing keypair with which to automatically sign outgoing emails. This helps recipients verify that email they receive actually came from your website. Admins can regenerate the keypair automatically by clicking the "Regenerate keypair" button, or they can manually paste an ASCII-armored keypair for the site to use. For security, the private key part of the site's signing key will only be transmitted over a secure (HTTPS) connection, so you will see a prompt to switch to a secure connection if you try to view it insecurely. You can still (re)generate a keypair, including the private key part, over an insecure connection because the key is generated on the server itself.

== Change log ==

= 0.8.0 =
* Maintenance: Drop support for PHP versions earlier than 7.4, add experimental support for PHP 8.x.

= 0.7.6 =
* Maintenance: Update dependencies.
    * `phpseclib` is updated to version 2.0.31 and addresses a moderate severity security vulnerability.

= 0.7.5 =
* Maintenance: Update dependencies. Note also that this version officially drops support for PHP versions earlier than the [current WordPress recommendations](https://wordpress.org/about/requirements/), which at the time of this writing is PHP v7.4. If you are still running WordPress in a "legacy" environment (using PHP 5.x), you must update or push your hosting provider to update your version of PHP to 7.4 or greater to continue using this plugin.

= 0.7.4 =
* Security: Always use the AES-256 cipher in CBC mode when encrypting S/MIME emails. This change drops support for PHP versions less than 5.4.
* Security: Improved shredding of temporary files needed for S/MIME encryption with 3-pass overwrite and explicit filesystem write buffer flushing.
* Enhancement: Improve S/MIME compatibility with some email clients, notably Roundcube. Props @githubuserx.
* [Bugfix](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/18): Conflict where admin email without encryption keys matching user email no longer results in unencrypted email being sent.
* Minor code cleanup and documentation improvements.

= 0.7.3 =
* Bugfix: Messages with `Content-Type: text/html` headers that were also S/MIME encrypted now render properly. Props @githubuserx.
* Bugfix: Ensure MIME subtypes in `Content-Type` mail headers are retained.
* [Bugfix](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/33): Do not enqueue admin-area stylesheet on site front-end.

= 0.7.2 =
* [Bugfix](https://github.com/fabacab/wp-pgp-encrypted-emails/pull/29): Fixes a problem where S/MIME email sending fails due to a web hoster restriction.

= 0.7.1 =
* [Enhancement](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/28): Offer a simple "Send me a test email" button to let inexperienced users easily test their encryption setup.

= 0.7 =
* Feature: WooCommerce integration. Customers can add their own OpenPGP keys or S/MIME certificates on their "My Account" front-end supplied by WooCommerce. By default, emails sent to Customers are *not* signed with the site's PGP signing key, though individual customers can opt-in to receive either encrypted and signed or just signed emails as they wish.
* Developer: Theme authors can override the plugin's default WooCommerce integration file by adding a `woocommerce-functions.php` file to their theme. Please only do this if you know what you are doing.
* Update OpenPGP-PHP libraries to current released version.

= 0.6.3 =

* [Bugfix](https://wordpress.org/support/topic/accept-also-smime-keys/#post-9171196): Fix compatiblity with third-party contact form plugins (namely Contact Form 7).
* [Bugfix](https://wordpress.org/support/topic/delete-plugin-not-working/): Fix issue with uninstallation.

= 0.6.2 =

* Feature: New S/MIME API filter, `smime_pem_to_der`.
    * This supports certain applications that need certificate data in DER format.

= 0.6.1 =

* Bugfix: Fix comment filter call.

= 0.6.0 =

* [Feature](https://wordpress.org/support/topic/accept-also-smime-keys/): S/MIME support! :)
    * Three new API filter hooks are provided to offer S/MIME encryption. These are `smime_certificate`, `smime_certificate_pem_encode` and `smime_encrypt`. See [S/MIME API](https://github.com/fabacab/wp-pgp-encrypted-emails/#smime-api) for details.

= 0.5.0 =

* [Feature](https://wordpress.org/support/topic/can-i-disable-signing-of-messages-to-unknown-users/): Configure whether email destined for addresses that are not associated with user accounts are automatically PGP-signed.
* Feature: A "delete PGP signing keypair on uninstall" option has been added. When enabled and the plugin is uninstalled, the site's PGP signing keypair is deleted from the WordPress database.
* Minor bugfixes.

= 0.4.4 =

* [Bugfix](https://wordpress.org/support/topic/how-to-revoke-keys-generated-with-this-plugin?replies=4): Generate signing key that can be used to create a revocation certificate.

= 0.4.3 =

* Site signing key is generated with correct [OpenPGP key flags](https://tools.ietf.org/html/rfc4880#section-5.2.3.21) (shown as `S` for signing and `C` for certification in [GnuPG](https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html#GPG-Configuration-Options)).
* Update `openpgp-php` library and dependencies.

= 0.4.2 =

* [Bugfix](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/10): Improve compatibility with some third-party plugins.

= 0.4.1 =

* [Bugfix](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/8): Plugins that call `wp_mail()` with an array no longer cause PHP warnings.
* [Bugfix](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/7): Fix syntax error when running on PHP 5.3 or earlier.

= 0.4.0 =

* [Feature](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/1): Admins can now generate a PGP signing keypair for the blog itself. If a signing keypair exists, outgoing emails will be automatically signed.
    * This keypair is intended *only* for signing outgoing emails from WordPress itself. It is *not* intended to be used for any other purpose. *Do not* use this keypair for emails you send from your own mail client. *Do not* use this keypair as your personal PGP key. *Do not* export this key for use in any other system. This keypair should be treated as a low-trust, single-purpose keypair reserved exclusively for your website itself.
    * After adding a PGP signing keypair, users can download the site's public key part from their profile pages.
    * Theme authors can always link to a site's PGP signing public key with the following code: `print admin_url('admin-ajax.php?action=download_pgp_signing_public_key')`
* Developer: New filter hooks. These are documented on the [Other Notes](https://wordpress.org/plugins/wp-pgp-encrypted-emails/other_notes/) page.
    * `openpgp_enarmor` filter for ASCII-armoring arbitrary OpenPGP data.
    * `openpgp_sign` filter for (clear)signing an arbitrary message.

= 0.3.0 =

* [Feature](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/6): Authors with a PGP public key set in their profile can now receive "private" comments. Readers write their comment as normal, and can then enable the "Private" checkbox next to the comment submit button. This will automatically encrypt the comment to the post author's PGP public key and saves the comment in the WordPress database as an ASCII-armored string.
    * This feature is *not* secure against eavesdropping, other network attackers, or malicious web host. It does *not* prevent server administrators from reading the contents of your comment. Rather, it prevents *other readers* or unprivileged users of the blog from reading your comment after it has been sent to the author. This is useful if, for instance, you want to communicate semi-privately with the author in an otherwise public forum (the comment thread) but do not know the author's email address, perhaps because the author themselves wish to remain pseudonymous (and thus do not provide a valid email address associated with their PGP key).

= 0.2.0 =

* [Developer](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/5): Added two new filters, `openpgp_key` and `openpgp_encrypt` so plugin developers and theme authors can encrypt arbitrary data, too.

= 0.1.2 =

* [Security](https://github.com/fabacab/wp-pgp-encrypted-emails/issues/3): Switch PGP library to [OpenPGP-PGP](https://github.com/singpolyma/openpgp-php).

= 0.1.1 =

* Bugfix: Fix `Fatal error` in cases where the public key is set to `false`.

= 0.1 =

* Initial release.

== Upgrade Notice ==

= 0.7.4 =
This version requires PHP 5.4 or later, improves the security of S/MIME email, and fixes a minor bug affecting some admin users.

= 0.7.3 =
Fixes numerous issues with `Content-Type` mail header handling, notably fixing S/MIME-encrypted HTML email sending.

== Other notes ==

If you like this plugin, **please consider [making a donation](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=TJLPJYXHSRBEE&lc=US&item_name=WP%20PGP%20Encrypted%20Emails&item_number=wp-pgp-encrypted-emails&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted) for your use of the plugin** or, better yet, contributing directly to [my Cyberbusking fund](http://Cyberbusking.org/). Your support is appreciated!

= Themeing =

Theme authors can use the following code snippets to integrate a WordPress theme with this plugin.

* To link to a site's OpenPGP signing public key: `<?php print admin_url( 'admin-ajax.php?action=download_pgp_signing_public_key' ); ?>`

= Plugin hooks =

This plugin offers additional functionality intended for other plugin developers or theme authors to make use of. This functionality is documented here.

== Filters ==

= `wp_user_encryption_method` =

Gets the user's preferred encryption method (either `pgp` or `smime`), if they have provided both an OpenPGP public key and an S/MIME certificate.

* Optional arguments:
    * `WP_User` `$user` - The WordPress user object. Defaults to the current user.

= `wp_openpgp_user_key` =

Gets the user's saved OpenPGP public key from their WordPress profile data, immediately usable in other `openpgp_*` filters.

* Optional arguments:
    * `WP_User` `$user` - The WordPress user object. Defaults to the current user.

= `openpgp_enarmor` =

Gets an ASCII-armored representation of an OpenPGP data structure (like a key, or an encrypted message).

* Required parameters:
    * `string` `$data` - The data to be armored.
* Optional parameters:
    * `string` `$marker` - The marker of the block (the text that follows `-----BEGIN`). Defaults to `MESSAGE`, but you should set this to a more appropriate value. If you are armoring a PGP public key, for instance, set this to `PGP PUBLIC KEY BLOCK`.
    * `string[]` `$headers` - An array of strings to apply as headers to the ASCII-armored block, usually used to insert comments or identify the OpenPGP client used. Defaults to `array()` (no headers).

Example: ASCII-armor a binary public key.

    $ascii_key = apply_filters('openpgp_enarmor', $public_key, 'PGP PUBLIC KEY BLOCK');

= `openpgp_key` =

Gets a binary OpenPGP public key for use in later PGP operations from an ASCII-armored representation of that key.

* Required parameters:
    * `string` `$key` - The ASCII-armored PGP public key block.

Example: Get a key saved as an ASCII string in the WordPress database option `my_plugin_pgp_public_key`.

    $key = apply_filters('openpgp_key', get_option('my_plugin_pgp_public_key'));

= `openpgp_sign` =

[Clearsigns](https://www.gnupg.org/gph/en/manual/x135.html#AEN152) a message using a given private key.

* Required parameters:
    * `string` `$data` - The message data to sign.
    * `OpenPGP_SecretKeyPacket` `$signing_key` - The signing key to use, obtained by passing the ASCII-armored private key through the `openpgp_key` filter.

Example: Sign a short string.

    $message = 'This is a message to sign.';
    $signing_key = apply_filters('openpgp_key', $ascii_key);
    $signed_message = apply_filters('openpgp_sign', $message, $signing_key);
    // $signed_message is now a clearsigned message

= `openpgp_encrypt` =

Encrypts data to one or more PGP public keys or passphrases.

* Required arguments:
    * `string` `$data` - Data to encrypt.
    * `array|string` `$keys` - Passphrases or keys to use to encrypt the data.

Example: Encrypt the content of a blog post.

    // First, get the PGP public key(s) of the recipient(s)
    $ascii_key = '-----BEGIN PGP PUBLIC KEY BLOCK-----
    [...snipped for length...]
    -----END PGP PUBLIC KEY BLOCK-----';
    $encryption_key = apply_filters('openpgp_key', $ascii_key);
    $encrypted_post = apply_filters('openpgp_encrypt', $post->post_content, $encryption_key);
    // Now you can safely send or display $encrypted_post anywhere you like and only
    // those who control the corresponding private key(s) can decrypt it.

= `openpgp_sign` =

Signs a message (arbitrary data) with the given private key.

Note that if your plugin uses the built-in WordPress core `wp_mail()` function and this plugin is active, your plugin's outgoing emails are already automatically signed so you do not need to do anything. This filter is intended for use by plugin developers who want to create custom, trusted communiques between WordPress and some other system.

* Required arguments:
    * `string` `$data` - The data to sign.
* Optional arguments:
    * `OpenPGP_SecretKeyPacket` `$privatekey` - The private key used for signing the message. The default is to use the private key automatically generated during plugin activation. The automatically generated keypair is intended to be a low-trust, single-purpose keypair for your website itself, so you probably do not need or want to use this argument yourself.

Example: Send a signed, encrypted JSON payload to a remote, insecure server.

    $comment_data = get_comment(2); // get a WP_Comment object with comment ID 2
    // Create JSON payload
    $json = array('success' => true, 'action' => 'new_comment', 'data' => $comment_data);
    $url = 'http://insecure.example.com/';
    $response = wp_safe_remote_post($url, array(
    ));

= `openpgp_sign_and_encrypt` =

A convenience filter that applies `openpgp_sign` and then `openpgp_encrypt` to the result.

* Required arguments:
    * `string` `$data` - The data to sign and encrypt.
    * `string` `$signing_key` - The signing key to use.
    * `array|string` `$recipient_keys_and_passphrases` - Public key(s) of the recipient(s), or passphrases to encrypt to.

= `wp_openpgp_user_key` =

Gets the user's saved S/MIME public certificate from their WordPress profile data, immediately usable in other `smime_*` filters.

* Optional arguments:
    * `WP_User` `$user` - The WordPress user object. Defaults to the current user.

= `smime_certificate` =

Gets a PHP resource handle to an X.509 Certificate.

* Required arguments:
    * `mixed` `$cert` - The certificate, either as a string to a file, or raw PEM-encoded certificate data.

= `smime_certificate_pem_encode` =

Encodes ("exports") a given X.509 certificate as PEM format.

* Required arguments:
    * `resource` `$cert`

= `smime_encrypt` =

Encrypts a message as an S/MIME email given a public certificate.

* Required arguments:
    * `string` `$message` - The message contents to encrypt.
    * `string|string[]` `$headers` - The message headers for the encrypted part.
    * `resource|array` `$certificates` - The recipient's certificate, or an array of recipient certificates.

This filter returns an array with two keys, `headers` and `message`, wherein the message is encrypted.

Example: send an encrypted email via `wp_mail()`. (You do not need to do this if the recipient is registered as your site's user, because this plugin does that automatically. Only do this if you need to send S/MIME encrypted email to an address not stored in WordPress's own database.)

    $cert = apply_filters( 'smime_certificate', get_option( 'my_plugin_smime_certificate' ) );
    $body = 'This is a test email message body.';
    $head = array(
        'From' => get_option( 'admin_email' ),
    );
    $smime_data = apply_filters( 'smime_encrypt', $body, $head, $cert );
    if ( $smime_data ) {
        wp_mail(
            'recipient@example.com',
            'Test message.',
            $smime_data['message'], // message is sent encrypted
            $smime_data['headers']
        );
    }