Re: [office-comment] Insufficient documentation on ODF encryption.

[Peter Dolding <oiaohm@gmail.com>]

> I am attempting to implement ODF encryption (ODF 1.1 paragraph 17.3) and I
> am failing miserably. My goal was to purely use information within the ODF
> specification and not use any extra materials like the Open Office source
> code. My goal of implementing this feature of ODF is made difficult with the
> lack of useful information in the ODF specification itself. In total there
> is ½ an A4 worth of text on encryption of documents, which IMHO is a vital
> feature and deserves much more attention. I find the text hard to read,
> lacking important information and generally not useful for building
> software. In short, here are my main issues with this part of the ODF
> specification.
>
> -          The text immediately jumps into implementation steps, without
> explaining anything about the goals, process or general background of
> encryption of ODF documents. For instance, is the entire ZIP encrypted, or
> the entries within the ZIP?
>
> -          There are no references to other important areas of the
> specification, which would facilitate improved navigation. This makes it
> even harder to find relevant areas of ODF to look at.
>
> -          There is no mention of decryption of a document.
>
> -          The steps do not show any sample data which could be used to
> validate my code without needing to fall back on existing implementations
> (which might be equally wrong as my code)
>
> -          The author of the Blowfish encryption algorithm indicates that he
> is amazed that it is even used. It might not be allowed to use the algorithm
> for FIPS compliancy (I’m no expert on that though).
>
> -          The encoding of the password is not mentioned, which is vital
> information to be able to implement this feature.
>
> -          The exact process of salting the password hash is defined as
> ‘used together’, which is totally useless from an implementation standpoint.
>
>
>
> Since my government is demanding usage of this file format, I have interest
> in seeing it improve much beyond where it is right now. Even the source code
> of Open Office would result in more useful documentation, which IMHO should
> never be the case for a specification of this importance.
>

Lot of how this works is in the draft 1.2 specification.   At the time
1.1 was drafted there was a lot of other thing going on unifying other
parts.  So this section got left up in the air.  Of course it would
pay to get the draft and read over and make sure it complete.  Many
eyes of course.

> I hope you will appreciate this feedback and take appropriate action to make
> ODF a more useful standard, and not the essay that I am reading right now.
> People actually need to use this to implement applications, and to be
> honest, I do not think this is actually possible. Please don’t take this the
> wrong way, but the Open XML specification would be a great sample on how the
> general structure of the ODF specification should look like. Much more text,
> samples, and anchor / hyperlinks.
>
I do not mean to be mean here.   More text does not make a document
any more valid.  When it comes to standards larger is worse.

Part of the problem on OpenXML is that some of the examples and
documentation don't match.

A standard should be self contained.  ODF is not in places yet.   A
standard should not depend on hyper-linking out to explain things.  A
standard should not ever have information entered twice.  Ie once as
description once as sample is twice.

OpenXML is what a crap written standard looks like.  If you want
samples you want a reference implementation of standard.  If you want
programming guide for standard ask for that.

Nice standards have at least 3 documents.
1) The Standard.  Yep boring and short.  Less duplication less risk of
confusion more black and white.  It has to be this not ok doc says
this and sample shows this so what one should I do.
2) Reference implementation.  What is well commented source that is
build following the standard exactly.  If standard said jump of a
cliff it should.
3) Programmers Guide.  Programmers Guide includes overview of all know
existing implementations and there bugs and how to cope with them as
well as longer and more descriptive wording of the standard. Remember
the standard has no room for anything that is not exactly required to
explain how the standard should work.  Programmers guides fill that
gap.

Reference implementations and program guides can duplicate up for
different programming languages and platforms.  The advantage of not
having them in the standard is correcting them does not require
resubmitting the standard.   So they are more maintainable independent
to standard.

OpenXML writers mixed up the difference between writing a standard
document and a reference implementation and programming guide
generating a stack of confusion to anyone implementing that standard
including MS themselves.   Not having the clean 3 parts makes OpenXML
as an standard a bugger to maintain.  It explains to me why over the
years MS has had so many incompatibility between OS versions.  They
have no clue how to write a standard document.

Read the RFC standards for TCP and the like they are not programming
guides or reference implementations.  Short to the point documents.
Most coders would not make a TCP stack from the RFC doc instead use
reference implementations and programmer guides and check operation
against what is written in the standard doc.

Peter Dolding