def sync_private_key(contacts_encryption_encoded):
    '''
        Sync a key pair, and its associated records, for an email address within our domain.

        >>> sync_private_key(None)
        False
    '''

    result_ok = False
    if contacts_encryption_encoded is not None:
        try:
            contacts_encryption = pickle.loads(contacts_encryption_encoded)
            email = contacts_encryption.contact.email
            try:
                sync_db_key_class = SyncPrivateKey(contacts_encryption)
                if sync_db_key_class:
                    result_ok = sync_db_key_class.configure()
                else:
                    result_ok = False
            except Exception as exception:
                record_exception()
                log_message('EXCEPTION - see syr.exception.log for details')
                result_ok = False
        except Exception as exception:
            record_exception()
            log_message('EXCEPTION - see syr.exception.log for details')
            result_ok = False

    return result_ok

    def public_key_exists(self, user_id):
        '''
            Returns whether there is a public key for the user. It ignores
            whether the public key has expired or not.

            >>> from goodcrypto.oce.key.key_factory import KeyFactory
            >>> plugin = KeyFactory.get_crypto(gpg_key_constants.NAME)
            >>> plugin.set_home_dir(plugin.GPG_HOME_DIR)
            True
            >>> plugin.public_key_exists('[email protected]')
            True
            >>> plugin.public_key_exists('Ed <[email protected]>')
            True
        '''

        key_exists = False

        if user_id is None:
            key_exists = False
            self.log_message('missing user id ({})'.format(user_id))

        else:
            try:
                email = get_email(user_id)
                args = [gpg_constants.LIST_PUBLIC_KEYS, self.get_user_id_spec(email)]
                result_code, gpg_output, gpg_error= self.gpg_command(args)
                key_exists = result_code == gpg_constants.GOOD_RESULT

                self.log_message('found public key for {}: {}'.format(user_id, key_exists))
            except Exception:
                record_exception()
                self.log_message('EXCEPTION - see syr.exception.log for details')

        return key_exists

def get_passcode(email, encryption_name):
    '''
        Get the passcode for the encryption program for the contact.
        The email can be an RFC address or just the email address.

        >>> len(get_passcode('[email protected]', 'GPG')) > 0
        True
        >>> get_passcode('[email protected]', 'TestBC') is None
        True
    '''

    passcode = None

    try:
        if email_in_domain(email):
            address = get_email(email)
            user_key = get(address, encryption_name)
            if user_key:
                passcode = user_key.passcode
                if passcode and len(passcode) > 0:
                    log_message("private {} key configured for {}".format(encryption_name, email))
                else:
                    log_message('{} does not have a {} private key configured'.format(email, encryption_name))
            else:
                log_message('{} does not have a matching contact'.format(email))
        else:
            log_message('{} not part of managed domain so no private user key'.format(email))
    except Exception:
        record_exception()
        log_message('EXCEPTION - see syr.exception.log for details')

    return passcode

def get_from_metadata_user_details(email, encryption_name):
    '''
        Get the metadata address and key for the encryption program.

        >>> get_from_metadata_user_details(None, None)
        (False, None, None)
    '''

    metadata_address = passcode = None
    ok = False

    try:
        ok, metadata_address, fingerprint = get_metadata_user_details(email, encryption_name)
        if ok:
            passcode = user_keys.get_passcode(metadata_address, encryption_name)
            if passcode is None:
                ok = False
                log_message('no user key for {}'.format(metadata_address))
            else:
                ok = True
                log_message('ready to protect metadata using {}'.format(encryption_name))

        elif fingerprint is None:
            log_message('adding {}'.format(encryption_name, email))
            contacts.add(email, encryption_name, source=MESSAGE_HEADER)
    except:
        ok = False
        record_exception()
        log_message('EXCEPTION - see syr.exception.log for details')

    if not ok:
        metadata_address = passcode = None

    return ok, metadata_address, passcode

def get_metadata_address(email=None, domain=None):
    '''
        Get the metadata email address for this user's email address or domain.

        >>> metadata_address = get_metadata_address(None)
        >>> metadata_address is None
        True
    '''

    metadata_address = None

    if email is not None:
        try:
            domain = parse_domain(email)
        except:
            record_exception()
            log_message('EXCEPTION - see syr.exception.log for details')

    if domain is None or len(domain.strip()) <= 0:
        log_message('unable to get metadata address without a domain')
    else:
        try:
            metadata_address = '{} domain key (system use only) <{}@{}>'.format(domain, get_domain_user(), domain)
        except:
            record_exception()
            log_message('EXCEPTION - see syr.exception.log for details')

    return metadata_address

    def update_accepted_crypto(self, email, encryption_software_list):
        ''' Update the list of encryption software accepted by user.
        '''

        if email is None:
            self.log_message("email not defined so no need to update accepted crypto")
        elif encryption_software_list is None or len(encryption_software_list) <= 0:
            self.log_message('no encryption programs defined for {}'.format(email))
        else:
            contact = contacts.get(email)
            if contact is None:
                # if the contact doesn't exist, then add them with the first encryption program
                encryption_program = encryption_software_list[0]
                contact = contacts.add(email, encryption_program, source=MESSAGE_HEADER)
                self.log_message("added {} to contacts".format(email))

            # associate each encryption program in the list with this contact
            for encryption_program in encryption_software_list:
                try:
                    contacts_crypto = contacts.get_contacts_crypto(email, encryption_program)
                    if contacts_crypto is None:
                        encryption_software = crypto_software.get(encryption_program)
                        if encryption_software is None:
                            self.log_message('{} encryption software unknown'.format(encryption_program))
                            self.log_message(
                              'unable to add contacts crypt for {} using {} encryption software unknown'.format(email, encryption_program))
                        else:
                            contacts_crypto = contacts.add_contacts_crypto(
                               contact=contact, encryption_software=encryption_software, source=MESSAGE_HEADER)
                except Exception:
                    record_exception()
                    self.log_message('EXCEPTION - see syr.exception.log for details')

def import_keyserver_tab(request):
    ''' Get the details about importing a key from a keyserver.'''

    response = None
    form_template = 'mail/import_key_from_keyserver.html'
    if request.method == 'POST':
        try:
            form = ImportKeyFromKeyserverForm(request.POST)
            if form.is_valid():
                response = import_key_from_keyserver(request, form)
            else:
                params = {'form_from_server': form}
                response = render_to_response(
                    form_template, params, context_instance=RequestContext(request))
        except Exception:
            record_exception()
            log_message('EXCEPTION - see syr.exception.log for details')

        if response is None:
            log_message('post: {}'.format(request.POST))

    if response is None:
        form_from_server = ImportKeyFromKeyserverForm()
        params = {'form_from_server': form_from_server}
        response = render_to_response(
            form_template, params, context_instance=RequestContext(request))

    return response

def get_user_id_matching_email(address, user_ids):
    '''
        Gets the matching user ID based on email address.

        An address is a internet address. It may be just an email address,
        or include a readable name, such as "Jane Saladin <[email protected]>".
        User ids are typically fingerprints from encryption software.

        A user id may be an internet address, or may be an arbitrary string.
        An address matches iff a user id is a valid internet address and the
        email part of the internet address matches. User ids which are not
        internet addresses will not match. The match is case-insensitive.

        >>> from goodcrypto.oce.test_constants import EDWARD_LOCAL_USER, EDWARD_LOCAL_USER_ADDR, JOSEPH_REMOTE_USER, GLENN_REMOTE_USER
        >>> test_addresses = [EDWARD_LOCAL_USER, JOSEPH_REMOTE_USER, GLENN_REMOTE_USER]
        >>> get_user_id_matching_email(EDWARD_LOCAL_USER, test_addresses) == EDWARD_LOCAL_USER_ADDR
        True
    '''

    matching_id = None

    try:
        for user_id in user_ids:
            email = get_email(user_id)
            if emails_equal(address, email):
                matching_id = email
                if DEBUGGING: log_message("{} matches {}".format(address, matching_id))
                break
    except Exception:
        record_exception()
        log_message('EXCEPTION - see syr.exception.log for details')

    return matching_id

def send_message(sender, recipient, message):
    '''
        Send a message.

        The message can be a Message in string format or a "email.Message" class.
    '''

    if TESTS_RUNNING:
        log_message('not sending message when tests running')
        result_ok = True
    else:
        try:
            log_message('starting to send message')
            if USE_SMTP_PROXY:
                result_ok, msg = send_mime_message(sender, recipient, message, use_smtp_proxy=USE_SMTP_PROXY,
                  mta_address=mail_server_address(), mta_port=mta_listen_port())
            else:
                result_ok, msg = send_mime_message(sender, recipient, message)

            if DEBUGGING:
                if result_ok:
                    log_message('=================')
                    log_message(msg)
                    log_message('=================')
            log_message('finished sending message: {}'.format(result_ok))
        except Exception as exception:
            result_ok = False
            log_message('error while sending message')
            log_message('EXCEPTION - see syr.exception.log for details')
            record_exception()

    return result_ok

def delete_user(email):
    '''
        Delete a django user.

        >>> delete_user(None)
        False
    '''

    ok = False
    if email is None:
        ok = False
        log_message('email not defined')
    else:
        try:
            user = User.objects.get(username=email)
        except:
            user = None
            record_exception()
            log_message('EXCEPTION - see syr.exception.log for details')

        if user:
            user.delete()
            ok = True
        else:
            ok = False

    return ok

def get_admin_email():
    '''
        Get the admin's email.

        >>> email = get_admin_email()
        >>> email is not None
        True
        >>> email.endswith(get_domain())
        True
    '''

    admin_email = None
    try:
        users = User.objects.filter(is_superuser=True)
        if users is not None and len(users) > 0:
            for user in users:
                email = user.email
                if email is not None and len(email.strip()) > 0:
                    admin_email = email
                    break
                else:
                    username = user.username
                    email = get_email(user.username)
                    if email is not None and len(email.strip()) > 0:
                        admin_email = email
                        break
    except:
        record_exception()
        log_message('EXCEPTION - see syr.exception.log for details')

    if admin_email is None:
        admin_email = '[email protected]{}'.format(get_domain())

    return admin_email

def login_user(request, user, password):
    '''
        Login a django user.

        >>> error_message = login_user(None, None, None)
        >>> error_message == 'Unable to login user without a request and user.'
        True
    '''

    error_message = None
    if request is None or user is None:
        error_message = i18n("Unable to login user without a request and user.")
        log_message(error_message)
    else:
        if user.is_active:
            try:
                username = user.username
                # you must authenticate before logging a user in
                user = authenticate(username=username, password=password)
                login(request, user)
            except:
                error_message = i18n('Unexpected error while logging in {username}.'.format(
                   username=user.username))
                log_message(error_message)
                record_exception()
                log_message('EXCEPTION - see syr.exception.log for details')
        else:
            error_message = i18n("User is not active so unable to login.")
            log_message(error_message)

    return error_message

    def _log_exception(self, msg):
        '''
            Log the message to the local and Exception logs.
        '''

        self._log_message(msg)
        record_exception(message=msg)

def config_database_and_user(email, crypto_name, passcode):
    '''
        Configure the fingerprint for the user key.

        >>> from goodcrypto.oce.test_constants import CHELSEA_PASSPHRASE, CHELSEA_LOCAL_USER_ADDR
        >>> email = CHELSEA_LOCAL_USER_ADDR
        >>> crypto_name = 'GPG'
        >>> passcode = CHELSEA_PASSPHRASE
        >>> try:
        ...     config_database_and_user(email, crypto_name, passcode)
        ...     fail()
        ... except:
        ...     pass
    '''
    result_ok = timed_out = need_fingerprint = False

    log_message('adding associated user key record for {}'.format(email))
    try:
        user_key = user_keys.add(email, crypto_name, passcode=passcode)
    except Exception as e:
        user_key = None
        log_message(e)
        record_exception()

    if user_key is None:
        result_ok = False
        log_message('unable to add user key record for {}'.format(email))
    else:
        result_ok = True

    def decrypt_and_send_message(self, inner_crypto_message):
        ''' Decrypt and send a message. '''

        result_ok = False
        sender = recipient = message = decrypted_crypto_message = None
        try:
            decrypt = Decrypt(inner_crypto_message)
            decrypted_crypto_message = decrypt.process_message()

            sender = decrypted_crypto_message.smtp_sender()
            recipient = decrypted_crypto_message.smtp_recipient()
            message = decrypted_crypto_message.get_email_message().get_message().as_string()
            self.log_message('message to {} decrypted: {}'.format(
               recipient, decrypted_crypto_message.is_crypted()))

            if send_message(sender, recipient, message):
                result_ok = True
                self.log_message('sent message to {}'.format(recipient))
                if self.DEBUGGING: self.log_message('DEBUG: message:\n{}'.format(message))
            else:
                result_ok = False
        except AttributeError as attribute_error:
            result_ok = False
            self.log_message(attribute_error)
        except:
            result_ok = False
            record_exception()
            self.log_message('EXCEPTION - see syr.exception.log for details')

        if not result_ok:
            report_message_undeliverable(message, sender)
            self.log_message('reported message undeliverable')

        # we're returning the decrypted message to allow tests to verify everything went smoothly
        return result_ok, decrypted_crypto_message

def bounce_message(original_message, user, subject, error_message):
    '''
        Bounce a message that a local user.

        Test extreme case
        >>> bounce_message(None, None, None, None)
        False
    '''

    notified_user = False

    try:
        log_message(error_message)

        if user is None:
            log_message('unable to bounce message without a user email address')
        elif email_in_domain(user):
            message = '{}\n\n===================\n{}'.format(
              error_message, original_message)
            notified_user = notify_user(user, subject, message)
            log_message('sent note to {} about error.'.format(user))
        else:
            log_message('unable to send note to {} about error.'.format(user))
    except:
        record_exception()
        log_message('EXCEPTION - see syr.exception.log for details')

    return notified_user

    def _key_matches(self, encryption_name, old_fingerprint, id_fingerprint_pairs):
        '''
            Does the new key's fingerprint match the old fingerprint? (internal use only)
        '''

        matches = error = False

        if encryption_name is None:
            error = True
            self.log_message('unable to compare fingerprints because basic data is missing')
        else:
            try:
                if id_fingerprint_pairs is None or old_fingerprint is None:
                    error = True
                    self.log_message('missing fingerprint for comparison')
                    self.log_message('old fingerprint: {}'.format(old_fingerprint))
                    self.log_message('id fingerprint pairs: {}'.format(id_fingerprint_pairs))
                else:
                    fingerprints = []
                    for (__, fingerprint) in id_fingerprint_pairs:
                        fingerprints.append(fingerprint.replace(' ', ''))
                    matches = old_fingerprint.replace(' ', '') in fingerprints
            except:
                error = True
                matches = False
                record_exception()
                self.log_message('EXCEPTION - see syr.exception.log for details')

        return matches, error

def drop_message(original_message, recipient, subject, error_message):
    '''
        Drop a message that we shouldn't process from a remote user.

        Test extreme case
        >>> drop_message(None, None, None, None)
        False
    '''

    notified_user = False

    try:
        log_message(error_message)

        if recipient is None:
            log_message('unable to notify recipient about dropped message')
        elif email_in_domain(recipient):
            message = '{}\n\n===================\n{}'.format(
              error_message, original_message)
            notified_user = notify_user(recipient, subject, message)
            log_message('sent note to {} about error.'.format(recipient))
        else:
            log_message('unable to send note to {} about error.'.format(recipient))
    except:
        record_exception()
        log_message('EXCEPTION - see syr.exception.log for details')

    return notified_user

    def update_contact(contact, crypto_name, fingerprint):
        fingerprint_ok = True
        try:
            if (user_name is not None and
                (contact.user_name is None or len(contact.user_name.strip()) <= 0)):
                contact.user_name = user_name.strip()
                contact.save()
                log_message('updated user name')
            else:
                log_message('user name: {}'.format(user_name))
                log_message('contact user name: {}'.format(contact.user_name))
            if possible_fingerprint is not None and len(possible_fingerprint.strip()) > 0:
                if strip_fingerprint(possible_fingerprint).lower() == strip_fingerprint(fingerprint).lower():
                    contacts_crypto = contacts.get_contacts_crypto(user_id, plugin.get_name())
                    contacts_crypto.verified = True
                    contacts_crypto.save()
                    log_message('verified fingerprint')
                else:
                    fingerprint_ok = False
                    log_message('possible fingerprint: {}'.format(strip_fingerprint(possible_fingerprint).lower()))
                    log_message('imported fingerprint: {}'.format(strip_fingerprint(fingerprint).lower()))
        except:
            record_exception()
            log_message('EXCEPTION - see syr.exception.log for details')

        return  fingerprint_ok

    def is_available(self):
        '''
            Determine if the crypto app is installed.

            >>> plugin = GPGPlugin()
            >>> plugin.is_available()
            True
        '''

        installed = False
        try:
            #  if we can get the version, then the app's installed
            version = self.get_crypto_version()
            if version != None:
                if len(version.strip()) > 0:
                    installed = True

                    # make sure the home directory is defined and exists
                    self.get_home_dir()
                else:
                    self.log_message('unable to get version while trying to verify gpg installed.')

        except Exception:
            self.log_message("unable to get version so assume not installed")
            self.log_message('EXCEPTION - see syr.exception.log for details')
            record_exception()

        self.log_message("GPG's back end app is installed: {}".format(installed))

        return installed