Mercurial > public > m209
view docs/procedure.rst @ 70:753974fc7619
Minor tweaks to install instructions. Added a note on how to run the tests.
author | Brian Neal <bgneal@gmail.com> |
---|---|
date | Sun, 21 Jul 2013 14:30:12 -0500 |
parents | 30aa114bb746 |
children | 854c5d361011 |
line wrap: on
line source
StdProcedure Class ================== The ``StdProcedure`` class encapsulates the encrypting and decrypting procedures outlined in :ref:`references-label`. In particular, see references [5] and [7]. This class takes care of the high level details of inserted various message indicators into an encrypted message, and stripping them off during decrypt. These message indicators tell the recipient what key list and initial key wheel settings to use when configuring their M-209 for decrypt. .. class:: m209.procedure.StdProcedure([m_209=None[, key_list=None]]) :param m_209: an instance of a :class:`~m209.converter.M209` can optionally be provided to the procedure object. If ``None`` the procedure object will create one for internal use. :param key_list: an instance of a :class:`~m209.keylist.KeyList` can be provided if known ahead of time. Before an encrypt or decrypt operation can be performed, a key list must be provided. This can be done after object creation via :meth:`set_key_list`. Note that the ``letter_check`` attribute of the :class:`~m209.keylist.KeyList` is not accessed by the procedure object, and can be ``None`` if not known. Before an :meth:`encrypt` operation can be performed, a valid key list must be installed, either during procedure object construction, or by the :meth:`set_key_list` method. Decrypt operations are performed in a 3-step process. #. First, a call to the :meth:`set_decrypt_message` method passes the message to be decrypted to the procedure and establishes the parameters to be used for the actual :meth:`decrypt` operation. These decrypt parameters are returned to the caller. #. The caller can examine the decrypt parameters to determine which key list must be installed before a successful :meth:`decrypt` operation can be carried out. The caller may call :meth:`get_key_list` to examine the currently installed key list. It is up to the caller to obtain the required key list and install it with :meth:`set_key_list`, if necessary. This is done by ensuring the installed key list indicator matches the ``key_list_ind`` field of the decrypt parameters. #. Finally :meth:`decrypt` can be called. If the procedure does not have the key list necessary to decrypt the message, a ``ProcedureError`` is raised. ``StdProcedure`` objects have the following methods: .. method:: get_key_list() :returns: the currently installed :class:`~m209.keylist.KeyList` object or ``None`` if one has not been set .. method:: set_key_list(key_list) Establishes the :class:`~m209.keylist.KeyList` to be used for future :meth:`encrypt` and :meth:`decrypt` operations :param key_list: the new :class:`~m209.keylist.KeyList` to use .. method:: encrypt(plaintext[, spaces=True[, ext_msg_ind=None[, sys_ind=None]]]) :noindex: Encrypts a plaintext message using the installed :class:`~m209.keylist.KeyList` and by following the standard procedure. The encrypted text with the required message indicators are returned as a string. :param plaintext: the input string to be encrypted :param spaces: if ``True``, space characters in the input plaintext are allowed and will be replaced with ``Z`` characters before encrypting :param ext_msg_ind: this is the external message indicator, which, if supplied, must be a valid 6-letter string of key wheel settings. If not supplied, one will be generated randomly. :param sys_ind: this is the system indicator, which must be a string of length 1 in the range ``A`` - ``Z``, inclusive. If ``None``, one is chosen at random. :returns: the encrypted text with the required message indicators :raises ProcedureError: if the procedure does not have a :class:`~m209.keylist.KeyList` or the input indicators are invalid .. method:: set_decrypt_message(msg) Prepare to decrypt the supplied message. :param msg: the messsage to decrypt. The message can be grouped into 5-letter groups separated by spaces or accepted without spaces. :returns: a ``DecryptParams`` named tuple to the caller (see below) The ``DecryptParams`` named tuple has the following attributes: * ``sys_ind`` - the system indicator * ``ext_msg_ind`` - the external message indicator * ``key_list_ind`` - the key list indicator * ``ciphertext`` - the cipher text with all indicators removed The caller should ensure the procedure instance has the required :class:`~m209.keylist.KeyList` before calling :meth:`decrypt`. The ``key_list_ind`` attribute of the returned ``DecryptParams`` named tuple identifies the key list that should be installed with :meth:`set_key_list`. .. method:: decrypt() :noindex: Decrypt the message set in a previous :meth:`set_decrypt_message` call. The resulting plaintext is returned as a string. :returns: the decrypted plaintext as a string :raises ProcedureError: if the procedure instance has not been previously configured with the required :class:`~m209.keylist.KeyList` via :meth:`set_key_list` Here is a simple interactive example of performing an encrypt operation. Here we choose a random key list from our key list file, and use random indicators: >>> from m209.keylist.config import read_key_list >>> from m209.procedure import StdProcedure >>> >>> key_list = read_key_list('m209keys.cfg') >>> proc = StdProcedure(key_list=key_list) >>> ct = proc.encrypt('ORDER THE PIZZA AT TWELVE HUNDRED HOURS') >>> ct 'YYGBM ENNHT VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX YYGBM ENNHT' >>> The first and last two groups of this message contain the indicators. Here we can see the system indicator was ``Y``, the external message indicator is ``GBMENN``, and the key list indicator is ``HT``. An example session for decrypting the above message might look like: >>> proc = StdProcedure() >>> ct = 'YYGBM ENNHT VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX YYGBM ENNHT' >>> params = proc.set_decrypt_message(ct) >>> params DecryptParams(sys_ind='Y', ext_msg_ind='GBMENN', key_list_ind='HT', ciphertext='VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX') >>> key_list = read_key_list('m209keys.cfg', params.key_list_ind) >>> proc.set_key_list(key_list) >>> pt = proc.decrypt() >>> pt 'ORDER THE PI A AT TWELVE HUNDRED HOURS ' >>>