# Bazaar merge directive format 2 (Bazaar 0.90) # revision_id: davazp@gmail.com-20080815003415-y7623vov97v042wn # target_branch: http://bzr.savannah.gnu.org/r/pdf/libgnupdf/branches\ # /trunk/ # testament_sha1: fb3ed052b9a0000589a203833d8637f0845143ae # timestamp: 2008-08-15 02:37:52 +0200 # base_revision_id: jemarch@gnu.org-20080806214528-oqqna5c4sndhfl8n # # Begin patch === modified file 'ChangeLog' --- ChangeLog 2008-08-06 21:45:28 +0000 +++ ChangeLog 2008-08-15 00:34:15 +0000 @@ -1,3 +1,11 @@ +2008-08-15 David Vazquez + + * doc/gnupdf.texi (Encryption): New section. + (Initializating the module): New subsection. + (Encryption and decryption): New subsection. + (Creating and destroying Ciphers): New subsection. + (Utils functions): New subsection. + 2008-08-06 Jose E. Marchesi * 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-15 00:34:15 +0000 @@ -86,6 +86,7 @@ * Encoded Text:: * Time Management:: * The Filesystem Module:: +* Encryption:: @end menu @node Base Layer Overview @@ -7850,6 +7851,309 @@ @end table @end deftypefun + + +@node Encryption +@section Encryption + +This section describes related to encryption functions. + +@menu +* Initializating the module:: +* Creating and destroying Ciphers:: +* Encryption and decryption:: +* Utils functions:: +@end menu + +@node Initializating the module +@subsection Initializating the module + +The encryption module must be initialized when Libgnupdf library was +loaded It is *NOT* safe-thread. + +@deftypefun pdf_status_t pdf_crypt_init (void) + +Initialize the encryption module. + +@table @strong +@item Parameters +None. +@item Returns +A PDF status value: +@table @code +@item PDF_OK +Operation successful +@item PDF_ERROR +A error ocurred. +@end table +@item Usage example +@example +xxx +@end example +@end table +@end deftypefun + +@node Creating and destroying Ciphers +@subsection Creating and destroying Ciphers + +@deftp {Data Type} {pdf_crypt_algo_e} +Enumeration of encryption algorithms provided. + +@table @code +@item PDF_CRYPT_CIPHER_ALGO_AESV2 +Use AES algorithm with a key of 128 bits to encrypt the data. +@item PDF_CRYPT_CIPHER_ALGO_V2 +Use ARC4 algorithm. +@end table +@end deftp + +@deftp {Data Type} {pdf_crypt_cipher_t} +A cipher. It contains data which is required between several calls to +functions. +@end deftp + +@deftypefun pdf_status_t pdf_crypt_cipher_new (pdf_crypt_algo_t @var{algorithm}, pdf_crypt_cipher_t *@var{cipher}) + +Create a new cipher. + +@table @strong +@item Parameters +@table @var +@item algorithm +The algorithm the cipher will use in order to encrypt or decrypt +data. +@item cipher +A pointer to @code{pdf_crypt_cipher_t} variable where it will put the cipher. +@end table +@item Returns +A PDF status value: +@table @code +@item PDF_OK +Operation successful +@item PDF_ERROR +A error ocurred when trying to create the cipher. +@end table +@item Usage example +@example +xxx +@end example +@end table +@end deftypefun + + +@deftypefun pdf_status_t pdf_crypt_cipher_destroy (pdf_crypt_cipher_t @var{cipher}) + +Destroy a cipher. + +@table @strong +@item Parameters +@table @var +@item cipher +The cipher you want destroy. It must have been created with +@code{pdf_crypt_cipher_new} functions previously. +@end table +@item Returns +@table @code +A PDF status value: +@item PDF_OK +Operation successful +@item PDF_ERROR +A error ocurred when trying to destroy the cipher. +@end table +@item Usage example +@example +xxx +@end example +@end table +@end deftypefun + + +@node Encryption and decryption +@subsection Encryption and decryption + +@deftypefun pdf_status_t pdf_crypt_cipher_setkey (pdf_crypt_cipher_t @var{cipher}, pdf_char_t *@var{key}, pdf_size_t @var{size}) + +Set the key which will be used to encrypt and decrypt data. + +@table @strong +@item Parameters +@table @var +@item cipher +A cipher created previously. +@item key +A pointer to memory where the key is stored. +@item size +The length of the key in bytes. Note that some algorithms could require +a fixed length of key. +@end table +@item Returns +A PDF status value: +@table @code +@item PDF_OK +Operation successful +@item PDF_EBADDATA +Invalid argument. The @var{size} parameter is not supported by the +cipher. +@item PDF_ERROR +A error ocurred while trying to set the key. +@end table +@end table +@end deftypefun + +@deftypefun pdf_size_t pdf_crypt_cipher_encrypt_size (pdf_crypt_cipher_t @var{cipher}, pdf_char_t *@var{in}, pdf_size_t @var{in_size}) + +Compute the size for the output buffer in +@code{pdf_crypt_cipher_encrypt} function for the given parameters. + +@table @strong +@item Parameters +@table @var +@item cipher +A cipher. +@item in +A pointer to the buffer which will be encrypted. +@item in_size +The length of the buffer in bytes. +@end table +@item Returns +The size of a valid output buffer in @code{pdf_crypt_cipher_encrypt} +function for this parameters. +@end table +@end deftypefun + +@deftypefun pdf_status_t pdf_crypt_cipher_decrypt_size (pdf_crypt_cipher_t @var{cipher}, pdf_char_t *@var{in}, pdf_size_t @var{in_size}) + +Compute the size for the output buffer in +@code{pdf_crypt_cipher_decrypt} function for the given parameters. + +@table @strong +@item Parameters +@table @var +@item cipher +A cipher. +@item in +A pointer to the buffer which will be decrypted. +@item in_size +The length of the buffer in bytes. +@end table +@item Returns +The size of a valid output buffer in @code{pdf_crypt_cipher_encrypt} +function for this parameters. +@end table +@end deftypefun + + +@deftypefun pdf_status_t pdf_crypt_cipher_encrypt (pdf_crypt_cipher_t @var{cipher}, pdf_char_t *@var{out}, pdf_size_t @var{out_size}, pdf_char_t *@var{in}, pdf_size_t @var{in_size}) + +Encrypt a buffer. The ciphered text will be put in @var{out}. + +@table @strong +@item Parameters +@table @var +@item cipher +A cipher. +@item out +A pointer to the output buffer. +@item out_size +Size of the output buffer in bytes. The function will fail if it is not +too large to contain the output. +@item in +A pointer to input buffer. +@item in_size +The length of the input buffer in bytes. +@end table +@item Returns +A PDF status value: +@table @code +@item PDF_OK +Operation successful +@item PDF_EBADDATA +Invalid argument. The @var{out} buffer is not too large to contain the +ciphered text. +@item PDF_ERROR +A error ocurred. +@end table +@item Usage example +@example +xxx +@end example +@end table +@end deftypefun + + +@deftypefun pdf_status_t pdf_crypt_cipher_decrypt (pdf_crypt_cipher_t @var{cipher}, pdf_char_t *@var{out}, pdf_size_t @var{out_size}, pdf_char_t *@var{in}, pdf_size_t @var{in_size}) + +Decrypt a buffer. The plain text will be put in @var{out}. + +@table @strong +@item Parameters +@table @var +@item cipher +A cipher. +@item out +A pointer to the output buffer. +@item out_size +Size of the output buffer in bytes. The function will fail if it is not +too large to contain the output. +@item in +A pointer to input buffer. +@item in_size +The length of the input buffer in bytes. +@end table +@item Returns +A PDF status value: +@table @code +@item PDF_OK +Operation successful +@item PDF_EBADDATA +Invalid argument. The @var{out} buffer is not too large to contain the plain text. +@item PDF_ERROR +A error ocurred. +@end table +@item Usage example +@example +xxx +@end example +@end table +@end deftypefun + +@node Utils functions +@subsection Utils functions + +@deftypefun pdf_status_t pdf_crypt_md_md5 (pdf_char_t *@var{out}, pdf_size_t @var{out_size}, pdf_char_t *@var{in}, pdf_size_t @var{in_size}) + +Compute the message-digest md5 function of a buffer in memory. + +@table @strong +@item Parameters +@table @var +@item out +A pointer to output buffer. +@item out_size +The size of output buffer in bytes. This parameter is provided in order +to avoid a possible overflow. The size must be 16 bytes. +@item in +A pointer to the input buffer which md5 will compute on. +@item in_size +Size of the input buffer in bytes. +@end table +@item Returns +A PDF status value: +@table @code +@item PDF_OK +Operation successful +@item PDF_EBADDATA +Bad parameter. The size of the output buffer is not too large. +@end table +@item Usage example +@example +xxx +@end example +@end table +@end deftypefun + + + @node Object Layer @chapter Object Layer # Begin bundle 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