Re: [pdf-devel] Encryption module page draft

[David Vazquez]

address@hidden 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: address@hidden
# target_branch: file:///home/davazp/projects/gnupdf/
# testament_sha1: f30baf421c90aad1347c975cb84f17f9a0d089ff
# timestamp: 2008-08-09 05:29:30 +0200
# base_revision_id: address@hidden
# 
# 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  <address@hidden>
+
+       * 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  <address@hidden>
 
        *  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
 
+
+
+
address@hidden Encryption
address@hidden Encryption
+
+This section describes related to encryption functions.
+
address@hidden
+* Initializating the module::   
+* Creating and destroying Ciphers::  
+* Encryption and decryption::   
+* Utils functions::  
+* Usage example::           
address@hidden menu
+
address@hidden Initializating the module
address@hidden Initializating the module
+
+The encryption module must be initialized when Libgnupdf library was
+loaded It is *NOT* safe-thread.
+
address@hidden pdf_status_t pdf_crypt_init (void)
+
+Initialize the encryption module.
+
address@hidden @strong
address@hidden Parameters
+None.
address@hidden Returns
+A PDF status value:
address@hidden @code
address@hidden PDF_OK
+The module was initialized successfully.
address@hidden PDF_ERROR
+A error ocurred.
address@hidden table
address@hidden table
address@hidden deftypefun
+
address@hidden Creating and destroying Ciphers
address@hidden Creating and destroying Ciphers
+
address@hidden {Data Type} {pdf_crypt_algo_t}
+Enumeration of encryption algorithms provided.
address@hidden deftp
+
address@hidden {Data Type} {pdf_crypt_t}
+A cipher. It contains data which is required between several calls to
+functions.
address@hidden deftp
+
address@hidden pdf_status_t pdf_crypt_new (pdf_crypt_algo_t @var{algorithm}, 
pdf_crypt_t @var{*cipher})
+
+Create a new cipher.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden algorithm
+The algorithm the cipher will use in order to encrypt or decrypt
+data. Possible values are:
address@hidden @code
address@hidden PDF_CRYPT_IDENTITY
address@hidden PDF_CRYPT_AESV2
address@hidden PDF_CRYPT_V2
address@hidden table
address@hidden cipher
+A pointer to @code{pdf_crypt_t} variable where it will put the cipher.
address@hidden table
address@hidden Returns
+A PDF status value:
address@hidden @code
address@hidden PDF_OK
+The cipher was created sucessfully.
address@hidden PDF_ERROR
+A error ocurred when trying create the cipher.
address@hidden table
address@hidden table
address@hidden deftypefun
+
+
address@hidden pdf_status_t pdf_crypt_destroy (pdf_crypt_t @var{cipher})
+
+Destroy a cipher.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden cipher
+The cipher you want destroy. It must have been created with
address@hidden functions previosly.
address@hidden table
address@hidden Returns
address@hidden @code
+A PDF status value:
address@hidden PDF_OK
+The cipher was destroyed sucessfully.
address@hidden PDF_ERROR
+A error ocurred when trying destroy the cipher.
address@hidden table
address@hidden table
address@hidden deftypefun
+
+
address@hidden Encryption and decryption
address@hidden Encryption and decryption
+
address@hidden 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
address@hidden are called.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden cipher
+A cipher created previously.
address@hidden key
+A pointer to memory where the key is stored.
address@hidden length
+The length of the key in bytes. Note that some algorithms could require
+a fixed length of key.
address@hidden table
address@hidden Returns
+A PDF status value:
address@hidden @code
address@hidden PDF_OK
address@hidden PDF_ERROR
address@hidden table
address@hidden table
address@hidden deftypefun
+
address@hidden pdf_size_t pdf_crypt_encrypt_size (pdf_crypt_t @var{cipher}, 
pdf_char_t  @var{*in}, pdf_size_t  @var{length})
address@hidden deftypefun
+
address@hidden 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
address@hidden and @code{pdf_crypt_decrypt} functions
+respectively for the given parameters.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden cipher
+A cipher.
address@hidden in
+A pointer to the buffer which will be encrypt.
address@hidden length
+The length of the buffer in bytes.
address@hidden table
address@hidden Returns
+The size of a valid output buffer in @code{pdf_crypt_encrypt} function for 
this parameters.
address@hidden table
address@hidden deftypefun
+
+
address@hidden 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}.
+
address@hidden deftypefun
+
address@hidden 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}.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden cipher
+A cipher.
address@hidden out
+A pointer to the output buffer.
address@hidden outsize
+Size of the output buffer in bytes. The function will rails if it is not
+too large to contain the output.
address@hidden in
+A pointer to input buffer.
address@hidden length
+The length of the input buffer in bytes.
address@hidden table
address@hidden Returns
+A PDF status value:
address@hidden @code
address@hidden PDF_OK
address@hidden PDF_ERROR
address@hidden table
address@hidden table
address@hidden deftypefun
+
address@hidden Utils functions
address@hidden Utils functions
+
address@hidden 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.
+
address@hidden @strong
address@hidden Parameters
address@hidden @var
address@hidden out
+A pointer to output buffer.
address@hidden 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.
address@hidden in
+A pointer to the input buffer which md5 will compute on.
address@hidden length
+Size of the input buffer in bytes.
address@hidden table
address@hidden Returns
+A PDF status value:
address@hidden @code
address@hidden PDF_OK
address@hidden PDF_ERROR
address@hidden table
address@hidden table
address@hidden deftypefun
+
address@hidden Usage example
address@hidden Usage example
+
+Assuming that:
address@hidden @code
address@hidden @var{buffer} contains the data you want encrypt
address@hidden @var{size} the length of the buffer:
address@hidden table
+
address@hidden
+xxx
address@hidden example
+
+
 @node Object Layer
 @chapter Object Layer
 

# Begin bundle
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
yNQ=


--