Initial checkin of bmo/4.0 extensions. Still todo: port changes to core Bugzilla code

10 files changed, 630 insertions, 0 deletions

diff --git a/extensions/SecureMail/Config.pm b/extensions/SecureMail/Config.pm
new file mode 100644
index 000000000..436b4753d
--- /dev/null
+++ b/extensions/SecureMail/Config.pm
@@ -0,0 +1,41 @@
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla SecureMail Extension
+#
+# The Initial Developer of the Original Code is Mozilla.
+# Portions created by Mozilla are Copyright (C) 2008 Mozilla Corporation.
+# All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+#                 Gervase Markham <gerv@gerv.net>
+
+package Bugzilla::Extension::SecureMail;
+use strict;
+use constant NAME => 'SecureMail';
+
+use constant REQUIRED_MODULES => [
+    {
+        package => 'Crypt-OpenPGP',
+        module  => 'Crypt::OpenPGP',
+        # 1.02 added the ability for new() to take KeyRing objects for the
+        # PubRing argument.
+        version => '1.02',
+    },
+    {
+        package => 'Crypt-SMIME',
+        module  => 'Crypt::SMIME',
+        version => 0,
+    },
+];
+
+__PACKAGE__->NAME;
diff --git a/extensions/SecureMail/Extension.pm b/extensions/SecureMail/Extension.pm
new file mode 100644
index 000000000..ca5516c0a
--- /dev/null
+++ b/extensions/SecureMail/Extension.pm
@@ -0,0 +1,326 @@
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla SecureMail Extension
+#
+# The Initial Developer of the Original Code is the Mozilla Foundation.
+# Portions created by Mozilla are Copyright (C) 2008 Mozilla Foundation.
+# All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+#                 Gervase Markham <gerv@gerv.net>
+
+package Bugzilla::Extension::SecureMail;
+use strict;
+use base qw(Bugzilla::Extension);
+
+use Bugzilla::Group;
+use Bugzilla::Object;
+use Bugzilla::User;
+use Bugzilla::Util qw(correct_urlbase trim trick_taint);
+use Bugzilla::Error;
+use Crypt::OpenPGP::KeyRing;
+use Crypt::OpenPGP;
+use Crypt::SMIME;
+
+our $VERSION = '0.4';
+
+##############################################################################
+# Creating new columns
+#
+# secure_mail boolean in the 'groups' table - whether to send secure mail
+# public_key text in the 'profiles' table - stores public key
+##############################################################################
+sub install_update_db {
+    my ($self, $args) = @_;
+    
+    my $dbh = Bugzilla->dbh;
+    $dbh->bz_add_column('groups', 'secure_mail', 
+                        {TYPE => 'BOOLEAN', NOTNULL => 1, DEFAULT => 0});
+    $dbh->bz_add_column('profiles', 'public_key', { TYPE => 'LONGTEXT' });
+}
+
+##############################################################################
+# Maintaining new columns
+##############################################################################
+# Make sure generic functions know about the additional fields in the user
+# and group objects.
+sub object_columns {
+    my ($self, $args) = @_;
+    my $class = $args->{'class'};
+    my $columns = $args->{'columns'};
+    
+    if ($class->isa('Bugzilla::Group')) {
+        push(@$columns, 'secure_mail');
+    }
+    elsif ($class->isa('Bugzilla::User')) {
+        push(@$columns, 'public_key');
+    }
+}
+
+# Plug appropriate validators so we can check the validity of the two 
+# fields created by this extension, when new values are submitted.
+sub object_validators {
+    my ($self, $args) = @_;
+    my %args = %{ $args };
+    my ($invocant, $validators) = @args{qw(class validators)};
+    
+    if ($invocant->isa('Bugzilla::Group')) {
+        $validators->{'secure_mail'} = \&Bugzilla::Object::check_boolean;
+    }
+    elsif ($invocant->isa('Bugzilla::User')) {
+        $validators->{'public_key'} = sub {
+            my ($self, $value) = @_;
+            $value = trim($value) || '';
+            
+            return $value if $value eq '';
+            
+            if ($value =~ /PUBLIC KEY/) {
+                # PGP keys must be ASCII-armoured.
+                my $ring = new Crypt::OpenPGP::KeyRing(Data => $value);
+                $ring->read if $ring;
+                if (!defined $ring || !scalar $ring->blocks) {
+                    ThrowUserError('securemail_invalid_key');
+                }
+            }
+            elsif ($value =~ /BEGIN CERTIFICATE/) {
+                # S/MIME Keys must be in PEM format (Base64-encoded X.509)
+                #
+                # Crypt::SMIME seems not to like tainted values - it claims
+                # they aren't scalars!
+                trick_taint($value);
+
+                my $smime = Crypt::SMIME->new();
+                
+                eval {
+                    $smime->setPublicKey([$value]);
+                };                
+                if ($@) {
+                    ThrowUserError('securemail_invalid_key');
+                }
+            }
+            else {
+                ThrowUserError('securemail_invalid_key');
+            }
+            
+            return $value;
+        };
+    }
+}
+
+# When creating a 'group' object, set up the secure_mail field appropriately.
+sub object_before_create {
+    my ($self, $args) = @_;
+    my $class = $args->{'class'};
+    my $params = $args->{'params'};
+
+    if ($class->isa('Bugzilla::Group')) {
+        $params->{secure_mail} = Bugzilla->cgi->param('secure_mail');
+    }
+}
+
+# On update, make sure the updating process knows about our new columns.
+sub object_update_columns {
+    my ($self, $args) = @_;
+    my $object  = $args->{'object'};
+    my $columns = $args->{'columns'};
+    
+    if ($object->isa('Bugzilla::Group')) {
+        # This seems like a convenient moment to extract this value...
+        $object->set('secure_mail', Bugzilla->cgi->param('secure_mail'));
+        
+        push(@$columns, 'secure_mail');
+    }
+    elsif ($object->isa('Bugzilla::User')) {
+        push(@$columns, 'public_key');
+    }
+}
+
+# Handle the setting and changing of the public key.
+sub user_preferences {
+    my ($self, $args) = @_;
+    my $tab     = $args->{'current_tab'};
+    my $save    = $args->{'save_changes'};
+    my $handled = $args->{'handled'};
+    my $vars    = $args->{'vars'};
+    
+    return unless $tab eq 'securemail';
+
+    # Create a new user object so we don't mess with the main one, as we
+    # don't know where it's been...
+    my $user = new Bugzilla::User(Bugzilla->user->id);
+    
+    if ($save) {
+        my $public_key = Bugzilla->input_params->{'public_key'};
+        $user->set('public_key', $public_key);
+        $user->update();
+    }
+    
+    $vars->{'public_key'} = $user->{'public_key'};
+
+    # Set the 'handled' scalar reference to true so that the caller
+    # knows the panel name is valid and that an extension took care of it.
+    $$handled = 1;
+}
+
+##############################################################################
+# Encrypting the email
+##############################################################################
+sub mailer_before_send {
+    my ($self, $args) = @_;
+
+    my $email = $args->{'email'};
+    
+    # Decide whether to make secure.
+    # This is a bit of a hack; it would be nice if it were more clear 
+    # what sort a particular email is.
+    my $is_bugmail      = $email->header('X-Bugzilla-Status');
+    my $is_passwordmail = !$is_bugmail && ($email->body =~ /cfmpw.*cxlpw/s);
+    
+    if ($is_bugmail || $is_passwordmail) {
+        # Convert the email's To address into a User object
+        my $login = $email->header('To');        
+        my $emailsuffix = Bugzilla->params->{'emailsuffix'};
+        $login =~ s/$emailsuffix$//;
+        my $user = new Bugzilla::User({ name => $login });
+        
+        # Default to secure. (Of course, this means if this extension has a 
+        # bug, lots of people are going to get bugmail falsely claiming their 
+        # bugs are secure and they need to add a key...)
+        my $make_secure = 1;
+        
+        if ($is_bugmail) {
+            # This is also a bit of a hack, but there's no header with the 
+            # bug ID in. So we take the first number in the subject.
+            my ($bug_id) = ($email->header('Subject') =~ /^[^\d]+(\d+)/);
+            my $bug = new Bugzilla::Bug($bug_id);
+            if ($bug && !grep($_->{secure_mail}, @{ $bug->groups_in })) {
+                $make_secure = 0;
+            }
+        }
+        elsif ($is_passwordmail) {
+            # Mail is made unsecure only if the user does not have a public
+            # key and is not in any security groups. So specifying a public
+            # key OR being in a security group means the mail is kept secure
+            # (but, as noted above, the check is the other way around because
+            # we default to secure).
+            if ($user && 
+                !$user->{'public_key'} &&
+                !grep($_->{secure_mail}, @{ $user->groups })) 
+            {
+                $make_secure = 0;
+            }      
+        }
+        
+        # If finding the user fails for some reason, but we determine we 
+        # should be encrypting, we want to make the mail safe. An empty key 
+        # does that.
+        my $public_key = $user ? $user->{'public_key'} : '';
+    
+        if ($make_secure) {
+            _make_secure($email, $public_key, $is_bugmail);
+        }
+    }
+}
+
+sub _make_secure {
+    my ($email, $key, $is_bugmail) = @_;
+
+    my $bug_id = undef;
+    my $subject = $email->header('Subject');
+
+    # We only change the subject if it's a bugmail; password mails don't have
+    # confidential information in the subject.
+    if ($is_bugmail) {            
+        $subject =~ /^[^\d]+(\d+)/;
+        $bug_id = $1;
+        
+        my $new_subject = $subject;
+        # This is designed to still work if the admin changes the word
+        # 'bug' to something else. However, it could break if they change
+        # the format of the subject line in another way.
+        $new_subject =~ s/($bug_id\])\s+(.*)$/$1 (Secure bug updated)/;
+        $email->header_set('Subject', $new_subject);
+    }
+
+    if ($key && $key =~ /PUBLIC KEY/) {
+        ##################
+        # PGP Encryption #
+        ##################
+        my $body = $email->body;
+        if ($is_bugmail) {
+            # Subject gets placed in the body so it can still be read
+            $body = "Subject: $subject\n\n" . $body;
+        }
+        
+        my $pubring = new Crypt::OpenPGP::KeyRing(Data => $key);
+        my $pgp = new Crypt::OpenPGP(PubRing => $pubring);
+        
+        # "@" matches every key in the public key ring, which is fine, 
+        # because there's only one key in our keyring.
+        #
+        # We use the CAST5 cipher because the Rijndael (AES) module doesn't
+        # like us for some reason I don't have time to debug fully.
+        # ("key must be an untainted string scalar")
+        my $encrypted = $pgp->encrypt(Data       => $body, 
+                                      Recipients => "@", 
+                                      Cipher     => 'CAST5',
+                                      Armour     => 1);
+        if (defined $encrypted) {
+            $email->body_set($encrypted);
+        }
+        else {
+            $email->body_set('Error during Encryption: ' . $pgp->errstr);
+        }
+    }
+    elsif ($key && $key =~ /BEGIN CERTIFICATE/) {
+        #####################
+        # S/MIME Encryption #
+        #####################
+        my $smime = Crypt::SMIME->new();
+        my $encrypted;
+        
+        eval {
+            $smime->setPublicKey([$key]);                
+            $encrypted = $smime->encrypt($email->as_string());
+        };
+        
+        if (!$@) {      
+            # We can't replace the Email::MIME object, so we have to swap
+            # out its component parts.
+            my $enc_obj = new Email::MIME($encrypted);
+            $email->header_obj_set($enc_obj->header_obj());
+            $email->body_set($enc_obj->body());
+        }
+        else {
+            $email->body_set('Error during Encryption: ' . $@);
+        }
+    }
+    else {
+        # No encryption key provided; send a generic, safe email.
+        my $template = Bugzilla->template;
+        my $message;
+        my $vars = {
+          'urlbase'    => correct_urlbase(),
+          'bug_id'     => $bug_id,
+          'maintainer' => Bugzilla->params->{'maintainer'}
+        };
+        
+        $template->process('account/email/encryption-required.txt.tmpl',
+                           $vars, \$message)
+          || ThrowTemplateError($template->error());
+        
+        $email->body_set($message);
+    }
+}
+
+__PACKAGE__->NAME;
diff --git a/extensions/SecureMail/README b/extensions/SecureMail/README
new file mode 100644
index 000000000..ac3484291
--- /dev/null
+++ b/extensions/SecureMail/README
@@ -0,0 +1,8 @@
+This extension should be placed in a directory called "SecureMail" in the
+Bugzilla extensions/ directory. After installing it, remove the file
+"disabled" (if present) and then run checksetup.pl.
+
+Instructions for user key formats:
+
+S/MIME Keys must be in PEM format - i.e. Base64-encoded text, with BEGIN CERTIFICATE
+PGP keys must be ASCII-armoured - i.e. text, with BEGIN PGP PUBLIC KEY.
diff --git a/extensions/SecureMail/template/en/default/account/email/encryption-required.txt.tmpl b/extensions/SecureMail/template/en/default/account/email/encryption-required.txt.tmpl
new file mode 100644
index 000000000..7341992c8
--- /dev/null
+++ b/extensions/SecureMail/template/en/default/account/email/encryption-required.txt.tmpl
@@ -0,0 +1,15 @@
+This email would have contained sensitive information, and you have not set 
+a PGP/GPG key or SMIME certificate in the "Secure Mail" section of your user 
+preferences.
+
+[% IF bug_id %]
+In order to receive the full text of similar mails in the future, please 
+go to: 
+[%+ urlbase %]userprefs.cgi?tab=securemail 
+and provide a key or certificate.
+
+You can see this bug's current state at: 
+[%+ urlbase %]show_bug.cgi?id=[% bug_id %]
+[% ELSE %]
+You will have to contact [% maintainer %] to reset your password.
+[% END %]
diff --git a/extensions/SecureMail/template/en/default/account/prefs/securemail.html.tmpl b/extensions/SecureMail/template/en/default/account/prefs/securemail.html.tmpl
new file mode 100644
index 000000000..2b643c961
--- /dev/null
+++ b/extensions/SecureMail/template/en/default/account/prefs/securemail.html.tmpl
@@ -0,0 +1,34 @@
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # The Initial Developer of the Original Code is the Mozilla Corporation.
+  # Portions created by the Initial Developer are Copyright (C) 2008 the 
+  # Initial Developer. All Rights Reserved.
+  #
+  # Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+  #%]
+
+<p>Some [% terms.bugs %] in this [% terms.Bugzilla %] are in groups the administrator has 
+deemed 'secure'. This means emails containing information about those [% terms.bugs %] 
+will only be sent encrypted. Enter your PGP/GPG public key or 
+SMIME certificate here to receive full update emails for such [% terms.bugs %].</p>
+
+<p>If you are a member of a secure group, or if you enter a key here, your password reset email 
+will also be sent to you encrypted. If you are a member of a secure group and do not enter a key, 
+you will not be able to reset your password without the assistance of an administrator.</p>
+
+<p><a href="page.cgi?id=securemail/help.html">More help is available</a>.</p>
+
+[% Hook.process('moreinfo') %]
+
+<textarea id="public_key" name="public_key" cols="72" rows="12">
+  [%- public_key FILTER html %]</textarea>
diff --git a/extensions/SecureMail/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl b/extensions/SecureMail/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl
new file mode 100644
index 000000000..70a40e592
--- /dev/null
+++ b/extensions/SecureMail/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl
@@ -0,0 +1,28 @@
+[%# -*- Mode: perl; indent-tabs-mode: nil -*-
+  #
+  # The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla SecureMail Extension
+  #
+  # The Initial Developer of the Original Code is Mozilla.
+  # Portions created by Mozilla are Copyright (C) 2008 Mozilla Corporation.
+  # All Rights Reserved.
+  #
+  # Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+  #                 Gervase Markham <gerv@gerv.net> 
+  #%]
+
+[% tabs = tabs.import([{
+    name => "securemail",
+    label => "Secure Mail",
+    link => "userprefs.cgi?tab=securemail",
+    saveable => 1
+    }]) %]
diff --git a/extensions/SecureMail/template/en/default/hook/admin/groups/create-field.html.tmpl b/extensions/SecureMail/template/en/default/hook/admin/groups/create-field.html.tmpl
new file mode 100644
index 000000000..27c644d02
--- /dev/null
+++ b/extensions/SecureMail/template/en/default/hook/admin/groups/create-field.html.tmpl
@@ -0,0 +1,25 @@
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # The Initial Developer of the Original Code is the Mozilla Corporation.
+  # Portions created by the Initial Developer are Copyright (C) 2008 the 
+  # Initial Developer. All Rights Reserved.
+  #
+  # Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+  #%]
+<tr>
+  <th>Secure Bugmail:</th>
+  <td colspan="3">
+    <input type="checkbox" id="secure_mail" name="secure_mail"
+            [% ' checked="checked"' IF group.secure_mail %]>
+  </td>  
+</tr>  
diff --git a/extensions/SecureMail/template/en/default/hook/admin/groups/edit-field.html.tmpl b/extensions/SecureMail/template/en/default/hook/admin/groups/edit-field.html.tmpl
new file mode 100644
index 000000000..81436a46c
--- /dev/null
+++ b/extensions/SecureMail/template/en/default/hook/admin/groups/edit-field.html.tmpl
@@ -0,0 +1,27 @@
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # The Initial Developer of the Original Code is the Mozilla Corporation.
+  # Portions created by the Initial Developer are Copyright (C) 2008 the 
+  # Initial Developer. All Rights Reserved.
+  #
+  # Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+  #%]
+[% IF group.is_bug_group %]
+  <tr>
+    <th>Secure Bugmail:</th>
+    <td>
+      <input type="checkbox" id="secure_mail" name="secure_mail"
+              [% ' checked="checked"' IF group.secure_mail %]>
+    </td>  
+  </tr>
+[% END %]
diff --git a/extensions/SecureMail/template/en/default/hook/global/user-error-errors.html.tmpl b/extensions/SecureMail/template/en/default/hook/global/user-error-errors.html.tmpl
new file mode 100644
index 000000000..f48a5389f
--- /dev/null
+++ b/extensions/SecureMail/template/en/default/hook/global/user-error-errors.html.tmpl
@@ -0,0 +1,27 @@
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # The Initial Developer of the Original Code is the Mozilla Corporation.
+  # Portions created by the Initial Developer are Copyright (C) 2008 the 
+  # Initial Developer. All Rights Reserved.
+  #
+  # Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+  #%]
+
+[% IF error == "securemail_invalid_key" %]
+   [% title = "Invalid Public Key" %]
+   We were unable to read the public key that you entered. Make sure
+   that you are entering either an ASCII-armored PGP/GPG public key, 
+   including the "BEGIN PGP PUBLIC KEY BLOCK" and "END PGP PUBLIC KEY BLOCK" 
+   lines, or a PEM format (Base64-encoded X.509) S/MIME key, including the
+   BEGIN CERTIFICATE and END CERTIFICATE lines.
+[% END %]
\ No newline at end of file
diff --git a/extensions/SecureMail/template/en/default/pages/securemail/help.html.tmpl b/extensions/SecureMail/template/en/default/pages/securemail/help.html.tmpl
new file mode 100644
index 000000000..4e1a5c577
--- /dev/null
+++ b/extensions/SecureMail/template/en/default/pages/securemail/help.html.tmpl
@@ -0,0 +1,99 @@
+[%#
+  # The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla SecureMail Extension.
+  #
+  # The Initial Developer of the Original Code is the Mozilla Foundation.
+  # Portions created by Mozilla are Copyright (C) 2008 Mozilla Foundation.
+  # All Rights Reserved.
+  #
+  # Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+  #                 Gervase Markham <gerv@gerv.net>
+  # Dave Lawrence <dkl@mozilla.com>
+  #%]
+
+[% PROCESS global/header.html.tmpl
+  title = "SecureMail Help"
+%]
+
+[% terms.Bugzilla %] considers certain groups as "secure". If a [% terms.bug %] is in one of those groups, [% terms.Bugzilla %] 
+will not send unencrypted email about it. To receive encrypted email rather than just a "something changed" placeholder, you must provide either 
+a S/MIME or a GPG/PGP key on the <a href="[% urlbase FILTER none %]userprefs.cgi?tab=securemail">SecureMail preferences tab</a>.<br>
+<br>
+In addition, if you have uploaded a S/MIME or GPG/PGP key using the <a href="[% urlbase FILTER none %]userprefs.cgi?tab=securemail">
+SecureMail preferences tab</a>, if you request your password to be reset, [% terms.Bugzilla %] will send the reset email encrypted and you will
+be required to decrypt it to view the reset instructions.
+
+<h2>S/MIME</h2>
+
+<b>S/MIME Keys must be in PEM format - i.e. Base64-encoded text, with the first line containing BEGIN CERTIFICATE.</b></p>
+
+<p>
+S/MIME certificates can be obtained from a number of providers. You can get a free one from <a href="https://www.startssl.com/?app=12">StartCom</a>. 
+Once you have it, <a href="https://www.startssl.com/?app=25#52">export it from your browser as a .p12 file and import it into your mail client</a>. 
+You'll need to provide a password when you export - pick a strong one, and then back up the .p12 file somewhere safe.</p>
+
+<p>
+Then, you need to convert it to a .pem file. If you have OpenSSL installed, one way is as follows:</p>
+
+<p>
+<code>openssl pkcs12 -in certificate.p12 -out certificate.pem -nodes</code></p>
+
+<p>
+Open the .pem file in a text editor. You can recognise the public key because it starts "BEGIN CERTIFICATE" and ends "END CERTIFICATE" and 
+has an appropriate friendly name (e.g. "StartCom Free Certificate Member's StartCom Ltd. ID"). It is <b>not</b> the section beginning 
+"BEGIN RSA PRIVATE KEY", and it is not any of the intermediate certificates or root certificates.</p>
+
+<p>
+<b>Note: the .pem file has your private key in plaintext. Delete it once you have copied the public key out of it!</b></p>
+
+<h2>PGP</h2>
+
+<b>PGP keys must be ASCII-armoured - i.e. text, with the first line containing BEGIN PGP PUBLIC KEY.</b></p>
+
+<p>
+If you already have your own PGP key in a keyring, skip straight to step 3. Otherwise:</p>
+
+<ol>
+
+<li>Install the GPG suite of utilities for your operating system, either using your package manager or downloaded from <a href="http://www.gnupg.org/download/index.en.html">gnupg.org</a>.</p>
+
+<li><p>Generate a private key.</p>
+
+<p><code>gpg --gen-key</code></p>
+
+<p>
+You’ll have to answer several questions:</p>
+
+<p>
+<ul>
+  <li>What kind and size of key you want; the defaults are probably good enough.</li>
+  <li>How long the key should be valid; you can safely choose a non-expiring key.</li>
+  <li>Your real name and e-mail address; these are necessary for identifying your key in a larger set of keys.</li>
+  <li>A comment for your key; the comment can be empty.</li>
+  <li>A passphrase. Whatever you do, don’t forget it! Your key, and all your encrypted files, will be useless if you do.</li>
+</ul>
+
+<li><p>Generate an ASCII version of your public key.</p>
+
+<p><code>gpg --armor --output pubkey.txt --export 'Your Name'</code></p>
+
+<p>Paste the contents of pubkey.txt into the SecureMail text field in [% terms.Bugzilla %]. 
+
+<li>Configure your email client to use your associated private key to decrypt the encrypted emails. For Thunderbird, you need the <a href="https://addons.mozilla.org/en-us/thunderbird/addon/enigmail/">Enigmail</a> extension.</p>
+</ol>
+
+<p>
+Further reading: <a href="http://www.madboa.com/geek/gpg-quickstart">GPG Quickstart</a>.
+
+[% PROCESS global/footer.html.tmpl %]
+
+