Mercurial > public > m209

comparison docs/procedure.rst @ 68:30aa114bb746

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added docs for StdProcedure and exceptions.
author Brian Neal <bgneal@gmail.com>
date Sun, 21 Jul 2013 14:03:55 -0500
parents
children 854c5d361011
comparison
equal deleted inserted replaced
67:a2647b9fe107 68:30aa114bb746
1 StdProcedure Class
2 ==================
3
4 The ``StdProcedure`` class encapsulates the encrypting and decrypting
5 procedures outlined in :ref:`references-label`. In particular, see
6 references [5] and [7]. This class takes care of the high level details of
7 inserted various message indicators into an encrypted message, and stripping
8 them off during decrypt. These message indicators tell the recipient what key
9 list and initial key wheel settings to use when configuring their M-209 for
10 decrypt.
11
12 .. class:: m209.procedure.StdProcedure([m_209=None[, key_list=None]])
13
14 :param m_209: an instance of a :class:`~m209.converter.M209` can optionally be
15 provided to the procedure object. If ``None`` the procedure object
16 will create one for internal use.
17 :param key_list: an instance of a :class:`~m209.keylist.KeyList` can be
18 provided if known ahead of time. Before an encrypt or decrypt operation
19 can be performed, a key list must be provided. This can be done after
20 object creation via :meth:`set_key_list`. Note that the ``letter_check``
21 attribute of the :class:`~m209.keylist.KeyList` is not accessed by the
22 procedure object, and can be ``None`` if not known.
23
24 Before an :meth:`encrypt` operation can be performed, a valid key list must be
25 installed, either during procedure object construction, or by the
26 :meth:`set_key_list` method.
27
28 Decrypt operations are performed in a 3-step process.
29
30 #. First, a call to the :meth:`set_decrypt_message` method passes the message
31 to be decrypted to the procedure and establishes the parameters to be used
32 for the actual :meth:`decrypt` operation. These decrypt parameters are
33 returned to the caller.
34
35 #. The caller can examine the decrypt parameters to determine which key list
36 must be installed before a successful :meth:`decrypt` operation can be
37 carried out. The caller may call :meth:`get_key_list` to examine the
38 currently installed key list. It is up to the caller to obtain the required
39 key list and install it with :meth:`set_key_list`, if necessary. This is
40 done by ensuring the installed key list indicator matches the
41 ``key_list_ind`` field of the decrypt parameters.
42
43 #. Finally :meth:`decrypt` can be called. If the procedure does not have the
44 key list necessary to decrypt the message, a ``ProcedureError`` is
45 raised.
46
47 ``StdProcedure`` objects have the following methods:
48
49 .. method:: get_key_list()
50
51 :returns: the currently installed :class:`~m209.keylist.KeyList` object
52 or ``None`` if one has not been set
53
54 .. method:: set_key_list(key_list)
55
56 Establishes the :class:`~m209.keylist.KeyList` to be used for future
57 :meth:`encrypt` and :meth:`decrypt` operations
58
59 :param key_list: the new :class:`~m209.keylist.KeyList` to use
60
61 .. method:: encrypt(plaintext[, spaces=True[, ext_msg_ind=None[, sys_ind=None]]])
62 :noindex:
63
64 Encrypts a plaintext message using the installed
65 :class:`~m209.keylist.KeyList` and by following the standard procedure.
66 The encrypted text with the required message indicators are returned as
67 a string.
68
69 :param plaintext: the input string to be encrypted
70 :param spaces: if ``True``, space characters in the input plaintext are
71 allowed and will be replaced with ``Z`` characters before encrypting
72 :param ext_msg_ind: this is the external message indicator, which, if
73 supplied, must be a valid 6-letter string of key wheel settings. If not
74 supplied, one will be generated randomly.
75 :param sys_ind: this is the system indicator, which must be a string of length
76 1 in the range ``A`` - ``Z``, inclusive. If ``None``, one is chosen at random.
77 :returns: the encrypted text with the required message indicators
78 :raises ProcedureError: if the procedure does not have
79 a :class:`~m209.keylist.KeyList` or the input indicators are invalid
80
81 .. method:: set_decrypt_message(msg)
82
83 Prepare to decrypt the supplied message.
84
85 :param msg: the messsage to decrypt. The message can be grouped into
86 5-letter groups separated by spaces or accepted without spaces.
87 :returns: a ``DecryptParams`` named tuple to the caller (see below)
88
89 The ``DecryptParams`` named tuple has the following attributes:
90
91 * ``sys_ind`` - the system indicator
92 * ``ext_msg_ind`` - the external message indicator
93 * ``key_list_ind`` - the key list indicator
94 * ``ciphertext`` - the cipher text with all indicators removed
95
96 The caller should ensure the procedure instance has the required
97 :class:`~m209.keylist.KeyList` before calling :meth:`decrypt`. The
98 ``key_list_ind`` attribute of the returned ``DecryptParams`` named tuple
99 identifies the key list that should be installed with
100 :meth:`set_key_list`.
101
102 .. method:: decrypt()
103 :noindex:
104
105 Decrypt the message set in a previous :meth:`set_decrypt_message` call. The
106 resulting plaintext is returned as a string.
107
108 :returns: the decrypted plaintext as a string
109 :raises ProcedureError: if the procedure instance has not been
110 previously configured with the required :class:`~m209.keylist.KeyList`
111 via :meth:`set_key_list`
112
113 Here is a simple interactive example of performing an encrypt operation. Here
114 we choose a random key list from our key list file, and use random indicators:
115
116 >>> from m209.keylist.config import read_key_list
117 >>> from m209.procedure import StdProcedure
118 >>>
119 >>> key_list = read_key_list('m209keys.cfg')
120 >>> proc = StdProcedure(key_list=key_list)
121 >>> ct = proc.encrypt('ORDER THE PIZZA AT TWELVE HUNDRED HOURS')
122 >>> ct
123 'YYGBM ENNHT VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX YYGBM ENNHT'
124 >>>
125
126 The first and last two groups of this message contain the indicators. Here we
127 can see the system indicator was ``Y``, the external message indicator is
128 ``GBMENN``, and the key list indicator is ``HT``.
129
130 An example session for decrypting the above message might look like:
131
132 >>> proc = StdProcedure()
133 >>> ct = 'YYGBM ENNHT VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX YYGBM ENNHT'
134 >>> params = proc.set_decrypt_message(ct)
135 >>> params
136 DecryptParams(sys_ind='Y', ext_msg_ind='GBMENN', key_list_ind='HT', ciphertext='VBMTJ PEEFV JWLUU PAFTS VOHEA QEPEQ OKVUA XDAUX')
137 >>> key_list = read_key_list('m209keys.cfg', params.key_list_ind)
138 >>> proc.set_key_list(key_list)
139 >>> pt = proc.decrypt()
140 >>> pt
141 'ORDER THE PI A AT TWELVE HUNDRED HOURS '
142 >>>
143