[EMAIL PROTECTED] writes:
> Hello David.
>
> I have written a draft of encryption module wiki
> page[1]. Operations must be described yet.
>
> Many thanks. Reading the architecture page it is clear what is going
> to be implemented.
>
> 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?
>
Hello jemarch.
I would like it :). So I have already written down the draft. I
include the patch here.
# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: [EMAIL PROTECTED]
# target_branch: file:///home/davazp/projects/gnupdf/
# testament_sha1: f30baf421c90aad1347c975cb84f17f9a0d089ff
# timestamp: 2008-08-09 05:29:30 +0200
# base_revision_id: [EMAIL PROTECTED]
#
# Begin patch
=== modified file 'ChangeLog'
--- ChangeLog 2008-08-06 21:45:28 +0000
+++ ChangeLog 2008-08-09 03:27:32 +0000
@@ -1,3 +1,9 @@
+2008-08-09 David Vazquez <[EMAIL PROTECTED]>
+
+ * doc/gnupdf.texi (Encryption, Initializating the module)
+ (Creating and destroying Ciphers, Encryption and decryption)
+ (Utils functions, Usage example): New sections.
+
2008-08-06 Jose E. Marchesi <[EMAIL PROTECTED]>
* Patch by Hans Hohenfeld changing the interface of
=== modified file 'doc/gnupdf.texi'
--- doc/gnupdf.texi 2008-08-06 21:45:28 +0000
+++ doc/gnupdf.texi 2008-08-09 03:27:32 +0000
@@ -86,6 +86,7 @@
* Encoded Text::
* Time Management::
* The Filesystem Module::
+* Encryption::
@end menu
@node Base Layer Overview
@@ -7850,6 +7851,242 @@
@end table
@end deftypefun
+
+
+
[EMAIL PROTECTED] Encryption
[EMAIL PROTECTED] Encryption
+
+This section describes related to encryption functions.
+
[EMAIL PROTECTED]
+* Initializating the module::
+* Creating and destroying Ciphers::
+* Encryption and decryption::
+* Utils functions::
+* Usage example::
[EMAIL PROTECTED] menu
+
[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.
+
[EMAIL PROTECTED] pdf_status_t pdf_crypt_init (void)
+
+Initialize the encryption module.
+
[EMAIL PROTECTED] @strong
[EMAIL PROTECTED] Parameters
+None.
[EMAIL PROTECTED] Returns
+A PDF status value:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] PDF_OK
+The module was initialized successfully.
[EMAIL PROTECTED] PDF_ERROR
+A error ocurred.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] table
[EMAIL PROTECTED] deftypefun
+
[EMAIL PROTECTED] Creating and destroying Ciphers
[EMAIL PROTECTED] Creating and destroying Ciphers
+
[EMAIL PROTECTED] {Data Type} {pdf_crypt_algo_t}
+Enumeration of encryption algorithms provided.
[EMAIL PROTECTED] deftp
+
[EMAIL PROTECTED] {Data Type} {pdf_crypt_t}
+A cipher. It contains data which is required between several calls to
+functions.
[EMAIL PROTECTED] deftp
+
[EMAIL PROTECTED] pdf_status_t pdf_crypt_new (pdf_crypt_algo_t @var{algorithm}, pdf_crypt_t @var{*cipher})
+
+Create a new cipher.
+
[EMAIL PROTECTED] @strong
[EMAIL PROTECTED] Parameters
[EMAIL PROTECTED] @var
[EMAIL PROTECTED] algorithm
+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
[EMAIL PROTECTED] table
[EMAIL PROTECTED] cipher
+A pointer to @code{pdf_crypt_t} variable where it will put the cipher.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] Returns
+A PDF status value:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] PDF_OK
+The cipher was created sucessfully.
[EMAIL PROTECTED] PDF_ERROR
+A error ocurred when trying create the cipher.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] table
[EMAIL PROTECTED] deftypefun
+
+
[EMAIL PROTECTED] pdf_status_t pdf_crypt_destroy (pdf_crypt_t @var{cipher})
+
+Destroy a cipher.
+
[EMAIL PROTECTED] @strong
[EMAIL PROTECTED] Parameters
[EMAIL PROTECTED] @var
[EMAIL PROTECTED] cipher
+The cipher you want destroy. It must have been created with
[EMAIL PROTECTED] functions previosly.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] Returns
[EMAIL PROTECTED] @code
+A PDF status value:
[EMAIL PROTECTED] PDF_OK
+The cipher was destroyed sucessfully.
[EMAIL PROTECTED] PDF_ERROR
+A error ocurred when trying destroy the cipher.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] table
[EMAIL PROTECTED] deftypefun
+
+
[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.
+
[EMAIL PROTECTED] @strong
[EMAIL PROTECTED] Parameters
[EMAIL PROTECTED] @var
[EMAIL PROTECTED] cipher
+A cipher created previously.
[EMAIL PROTECTED] key
+A pointer to memory where the key is stored.
[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
+
[EMAIL PROTECTED] pdf_size_t pdf_crypt_encrypt_size (pdf_crypt_t @var{cipher}, pdf_char_t @var{*in}, pdf_size_t @var{length})
[EMAIL PROTECTED] deftypefun
+
[EMAIL PROTECTED] pdf_status_t pdf_crypt_decrypt_size (pdf_crypt_t @var{cipher}, pdf_char_t @var{*in}, pdf_size_t @var{length})
+
+Compute the lesser valid size for the output buffer in
[EMAIL PROTECTED] and @code{pdf_crypt_decrypt} functions
+respectively for the given parameters.
+
[EMAIL PROTECTED] @strong
[EMAIL PROTECTED] Parameters
[EMAIL PROTECTED] @var
[EMAIL PROTECTED] cipher
+A cipher.
[EMAIL PROTECTED] in
+A pointer to the buffer which will be encrypt.
[EMAIL PROTECTED] length
+The length of the buffer in bytes.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] Returns
+The size of a valid output buffer in @code{pdf_crypt_encrypt} function for this parameters.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] deftypefun
+
+
[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
+
[EMAIL PROTECTED] pdf_status_t pdf_crypt_decrypt (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})
+
+Decrypt a buffer. The plain text will be put in @var{out}.
+
[EMAIL PROTECTED] @strong
[EMAIL PROTECTED] Parameters
[EMAIL PROTECTED] @var
[EMAIL PROTECTED] cipher
+A cipher.
[EMAIL PROTECTED] out
+A pointer to the output buffer.
[EMAIL PROTECTED] outsize
+Size of the output buffer in bytes. The function will rails if it is not
+too large to contain the output.
[EMAIL PROTECTED] in
+A pointer to input buffer.
[EMAIL PROTECTED] length
+The length of the input buffer in bytes.
[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
+
[EMAIL PROTECTED] Utils functions
[EMAIL PROTECTED] Utils functions
+
[EMAIL PROTECTED] pdf_status_t pdf_crypt_md5 (pdf_char_t @var{*out}, pdf_size_t @var{outsize}, pdf_char_t @var{*in}, pdf_size_t @var{length})
+
+Compute the message-digest md5 function of a buffer in memory.
+
[EMAIL PROTECTED] @strong
[EMAIL PROTECTED] Parameters
[EMAIL PROTECTED] @var
[EMAIL PROTECTED] out
+A pointer to output buffer.
[EMAIL PROTECTED] outsize
+The size of output buffer in bytes. This parameter is provided in order
+to avoid a possible overflow. It must be at least 16 bytes.
[EMAIL PROTECTED] in
+A pointer to the input buffer which md5 will compute on.
[EMAIL PROTECTED] length
+Size of the input buffer in bytes.
[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
+
[EMAIL PROTECTED] Usage example
[EMAIL PROTECTED] Usage example
+
+Assuming that:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] @var{buffer} contains the data you want encrypt
[EMAIL PROTECTED] @var{size} the length of the buffer:
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED]
+xxx
[EMAIL PROTECTED] example
+
+
@node Object Layer
@chapter Object Layer
# Begin bundle
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
yNQ=
--
