Bug#402814: cyrus-imapd-2.2: Inadequate documentation of 'sasl_minimum_layer'

[Sven Mueller]

Henrique de Moraes Holschuh wrote on 14/12/2006 02:51:
> On Wed, 13 Dec 2006, Michael Richters wrote:
> 
>>FYI: the string "sasl_minimum_layer" appears in the cyrus-imapd-2.2
>>source package, but not in the cyrus-sasl2 package:
> 
> 
> Strip the sasl_ prefix when grepping SASL code and docs.
> 
> That said, there are two possibilities for sasl_minimum_layer:
> 
> 1. Cyrus imap does its own processing on top of whatever SASL already does.
> 
> 2. It is in fact implemented by cyrus imap.
> 
> 
> If it is (2), we document it. If it is (1), we document it in a case by case
> basis.
> 
> There is also a (3): if I am wrong and cyrus now knows a set of SASL options
> and doesn't pass them blindly to SASL anymore, then we document them all.
> 
> I don't have the time to find out which is the case here, though. At least
> not right now.  It could be just that cyrus imap tries to change the default
> sasl minimum layer, which I find likely.
> 
> 
>>I don't think it's reasonable to expect someone to grep through the
>>source in order to determine that "sasl_minimum_layer" in one package
>>translates to "min_ssf" in another.  Not to mention the fact that this
>>information still doesn't lead me to an answer to my original
>>question.
> 
> 
> It should not translate to min_ssf at all, unless SASL is renaming options,
> in which case whomever is doing the translation needs to document it (either
> cyrus imap or sasl).
> 
> But no, it is not reasonable to have to grep code to find this information.
> SASL should document all their options easily, and in a manpage.  Feel free
> to file a bug against libsasl2 requesting that.
> 
> We are already agreeing that cyrus should also document those that are its
> responsability, btw.  I just don't know which ones are at this point, as I
> don't have the time to go code-hunting on cyrus right now.
> 
> I hope one of the other maintainers can do it soon.

Regarding the Documentation:

sasl_minimum_layer really translates into min_ssf in libsasl2,
sasl_maximum_layer into max_ssf of the same structure. What they do is
documented in: /usr/share/doc/libsasl2/programming.html

Actually, the documentation available in cyrus-imapd is almost all there
is to know:
a layer of 0 doesn't ensure anything
a layer of 1 provides integrity protection
any higher level ensures some sort of encryption. The example given in
sasl documentation is 56-bit DES encryption providing an SSF (security
strength factor) of 56.

Perhaps someone else can put this in more documentation-like words and
add it to our manpages, READMEs or so.

regards,
Sven
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 188 bytes
Desc: OpenPGP digital signature
Url : http://lists.alioth.debian.org/pipermail/pkg-cyrus-imapd-debian-devel/attachments/20061214/626f6e0d/signature.pgp