> I think that this is a good time to write down the API in the
> reference manual. Would you like to prepare the draft taking into
> account the comments made in this mailing list about the issue?
I would like it :). So I have already written down the draft.
Thanks :) Some comments about the patch follows.
[EMAIL PROTECTED] Initializating the module
[EMAIL PROTECTED] Initializating the module
+
+The encryption module must be initialized when Libgnupdf library was
+loaded It is *NOT* safe-thread.
What kind of global data will be maintained by the module? All the
information related with the ciphers will be stored in the per-cipher
data structure, isnt it?
[EMAIL PROTECTED] {Data Type} {pdf_crypt_algo_t}
+Enumeration of encryption algorithms provided.
[EMAIL PROTECTED] deftp
Note that we are using the convention of naming the enumeration data
types as 'enum pdf_XXX_e'. Also, we use to include the complete data
type name in the @deftp entry, as:
@deftp {Data Type} {enum pdf_crypt_algo_e}
...
@end deftp
[EMAIL PROTECTED] {Data Type} {pdf_crypt_t}
+A cipher. It contains data which is required between several calls to
+functions.
[EMAIL PROTECTED] deftp
The crypt module will implement several abstractions, one of which is
the 'cipher'. I would suggest to use a more explicit data type such as
'pdf_crypt_cipher_t' for ciphers.
Also, the functions operating in ciphers should be named after
'pdf_crypt_cipher_xxx'.
[EMAIL PROTECTED] pdf_status_t pdf_crypt_new (pdf_crypt_algo_t @var{algorithm},
pdf_crypt_t @var{*cipher})
Please use '[EMAIL PROTECTED]' instead of '@var{*cipher}'
+The algorithm the cipher will use in order to encrypt or decrypt
+data. Possible values are:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] PDF_CRYPT_IDENTITY
[EMAIL PROTECTED] PDF_CRYPT_AESV2
[EMAIL PROTECTED] PDF_CRYPT_V2
Please document the possible values of the enumeration data type in
the appropriate @deftp entry.
[EMAIL PROTECTED] Encryption and decryption
[EMAIL PROTECTED] Encryption and decryption
+
[EMAIL PROTECTED] pdf_status_t pdf_crypt_setkey (pdf_crypt_t @var{cipher},
pdf_char_t @var{*key}, pdf_size_t @var{length})
+
+Set the key which will be used to encrypt and decrypt data. This
+function should be called each time @code{pdf_crypt_encrypt} or
[EMAIL PROTECTED] are called.
Is that restriction really needed?
[EMAIL PROTECTED] length
+The length of the key in bytes. Note that some algorithms could require
+a fixed length of key.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] Returns
+A PDF status value:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] PDF_OK
[EMAIL PROTECTED] PDF_ERROR
[EMAIL PROTECTED] table
[EMAIL PROTECTED] table
[EMAIL PROTECTED] deftypefun
Since you can pass invalid parameters to this function
(pdf_crypt_cipher_setkey) would be good to have more detailed return
status values, such as PDF_EBADDATA for an invalid key (wrong key
length, etc).
Dont hesitate to define new values for pdf_status_t as needed.
[EMAIL PROTECTED] pdf_status_t pdf_crypt_encrypt (pdf_crypt_t @var{cipher},
pdf_char_t @var{*out}, pdf_size_t @var{outsize}, pdf_char_t @var{*in},
pdf_size_t @var{length})
+
+Encrypt a buffer. The ciphered text will be put in @var{out}.
+
[EMAIL PROTECTED] deftypefun
Please include information about parameters, return value, etc in
every @deftypefun entry.
Also note that if you call the first size parameter 'in_size' then
would be reasonable to do the same with 'out_size' ('length' name
may be confusing).
BTW, how do we know the size of the de/ciphered text? As far as I
understand it the *_crypt_size functions provides information about
the minimum buffer space required to hold the de/ciphered text, but
not the exact number of bytes.
[EMAIL PROTECTED] Usage example
[EMAIL PROTECTED] Usage example
We are including "Usage example" entries for every function documented
in the reference manual (into the @deftypefun block).
If you want to provide additional examples involving several functions
or non-simple examples then it is ok to include a subsection like
"Examples of use".
