[Classpathx-crypto] todo

[Raif S. Naffah]

hi there everybody,

after so many weeks, we're finally here :-)  thanks to Nic Ferrier for his 
hospitality, and for doing everything needed to make it happen.


i've already checked in the initial copy of the project.  it compiles --of 
course ;-) -- and have added a new tree structure (source/test) that 
includes junit tests.  few notes before i go further:

* the name src/ has been changed to source/ to align with the customs of 
the umbrella project; ie. classpathx.  i've changed the references in the 
build.xml file to use a symbolic name ${src.dir} so it's easier if in the 
future the source directory naming changes.

* the names under test/ mirror that under gnu/crypto/ .  in other words, 
package gnu.crypto.foo will have its test classes in test/foo.  from 
experience this proves to be easy when (a) compiling, jarring the main 
deliverables, and (b) separating the 'main' code from its 'test' counterpart.

some people argue that this separation disallows testing package private 
methods.  true; but (a) junit is not made for that, and (b) if an internal 
function is wrong then it will impact the result of a visible/public 
one.  write enough test cases to ensure the fullfilment of the contract for 
the visible one and the weaknesses/bugs of the internal ones will 
appear  --at least that's what i do.

if somebody has other opinions/experience, pls share them.


things left to do/solve before a first public release:

1. fix the links in the Javadoc for the reference documentation of the 
implemented algorithms.  i was referencing a .zip file but when i checked 
in the project i only checked in the .pdf and .txt files that are included 
in those archives.  i also moved the JavaStyle and AntStyle documents to 
the docs/ folder.

2. fix in the build.xml, in the docs section, the reference to the project 
home page --i still have to find that out from Nic before this can be done.

3. write an index.html page that will act as the root of all the project's 
documentation.  this should mirror the README at the project's root.

4. debugging: the code still contains in-line debugging statements that can 
be turned on/off.  it uses conditional compilation, so it's only useful for 
"programmers" and it requires re-compilation before the debugging output 
can occur.  i dont like it as part of a released code.  yes it's useful and 
necessary while you're getting the implementation to do what it's supposed 
to do, but for release it's ugly and confusing.  i would like to remove it 
unless somebody can convince me otherwise.

5. code correctness: each algorithm is published with its test vectors.  an 
implementation is deemed correct if it generates equivalent test vectors to 
those published by the designer of the algorithm.  the junit tests attempt 
to test the implementations against a very small subset of those test 
vectors.  is that enough?  i should note that the tools under 
gnu.crypto.tools do generate the test vectors (at least for the 
gnu.crypto.cipher package) in NESSIE and (almost) NIST forms.  yet the 
verification of the result is not straightforward:

* either the gnu.crypto.tool tools generate a more or less exact match of 
the published test vectors and then a diff tool is run over these two files 
to detect eventual differences, or
* we write a new tool that would read a published test vector file and try 
to generated the same from the implementation and compare the results 
--something that would automate the process of verifying an implementation 
basically.

6. deliverables: what should our deliverables consist of? separate archives 
for source, binaries, documentation? combine the lot? should we include the 
designers' reference documentation? their test vectors?  have a look at the 
sizes of these files before giving an answer please.

7. versioning: what type of versioning should we use?


things to do later:

this is still an open issue, and i would leave that for everybody to 
suggest what they can do relative to the time they can spend working on 
this project.


cheers;
rsn