Update of /project/crypticl/cvsroot/crypticl/doc In directory clnet:/tmp/cvs-serv2674

Modified Files: USERGUIDE README Log Message: Fixed width (78 visible chars) paragraphs with fill-region to make cvs diff easier.

--- /project/crypticl/cvsroot/crypticl/doc/USERGUIDE 2005/10/01 18:47:20 1.3 +++ /project/crypticl/cvsroot/crypticl/doc/USERGUIDE 2007/01/20 15:35:00 1.4 @@ -1,40 +1,52 @@ -;;;;-*-text-*- -;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; CRYPTICL - USER GUIDE -;; -;; *** WORK IN PROGRESS *** -;; -;;;;;;;;;;;;;;;;;;;;;;;;;;; +======================== += += CRYPTICL - USER GUIDE += +======================== +

CONTENTS ======== --Introduction --Hash functions --Symmetric key encryption --Digital signatures + +-INTRODUCTION +-HASH FUNCTIONS +-SYMMETRIC KEY ENCRYPTION +-DIGITAL SIGNATURES +-DIFFIE-HELLMAN

INTRODUCTION ============ -This user guide focus on examples showing typical tasks. The unit tests for each algorithm is a further source of examples. To test the examples yourself load crypticl and then change into the package with in-package: + +This is a short introduction and user guide for the Crypticl cryptography +library written in and for Common Lisp. + +This user guide focus on examples showing typical tasks. The unit tests for +each algorithm is a further source of examples. To test the examples yourself +load crypticl and then change into the package with in-package:

cl-user(2):(load "C:\crypticl\src\load.lisp") ... cl-user(3): (in-package crypticl) #<The crypticl package>

-The examples use two utility functions, hex and hexo, to simplify the output. hex takes an octet vector (byte vector) and returns a string representation in hex. hexo is the reverse, it takes a hex string and returns the octect vector equivalent. Both functions are part of the library. +The examples use two utility functions, hex and hexo, to simplify the +output. hex takes an octet vector (byte vector) and returns a string +representation in hex. hexo is the reverse, it takes a hex string and returns +the octect vector equivalent. Both functions are part of the library.

HASH FUNCTIONS ============== + Create a SHA-1 object:

-crypticl(4): (setf obj (new-instance 'SHA1)) +crypticl(4): (setf obj (new-instance 'SHA-1)) #<SHA1 @ #x211285fa>

-The new-instance function is a factory method used to generate instances of all the algorithms. An md5 object can for example be created with (new-instance 'MD5). +The new-instance function is a factory method used to generate instances of +all the algorithms. A SHA-256 object can for example be created with +(new-instance 'SHA-256).

Compute SHA-1 hash of a byte vector:

@@ -55,10 +67,18 @@ crypticl(14): (hex (hash obj)) "a9993e364706816aba3e25717850c26c9cd0d89d"

-Implementation note: -There is a semantic difference between calling hash on a hash object with no data and calling hash on an empty byte vector. Calling hash on an empty object is more likely to be a user error and hence returns nil. Calling hash on an empty byte vector on the other hand, may simply mean that we got very short input and hence returns the initial state of the SHA-1 algorithm (which is a valid 160 bits byte vector). - -The object oriented interface introduced above is built on top of low level function primitives for each algorithm. Sometimes it's easier to work directly with them. To get the SHA1 hash of a stream (typically a file) use sha1-on-octet-stream: +Implementation note: +There is a semantic difference between calling hash on a +hash object with no data and calling hash on an empty byte vector. Calling +hash on an empty object is more likely to be a user error and hence returns +nil. Calling hash on an empty byte vector on the other hand, may simply mean +that we got very short input and hence returns the initial state of the SHA-1 +algorithm (which is a valid 160 bits byte vector). + +The object oriented interface introduced above is built on top of low level +function primitives for each algorithm. Sometimes it's easier to work directly +with them. To get the SHA1 hash of a stream (typically a file) use +sha1-on-octet-stream:

crypticl(31): (with-open-file (s "rsa.lisp") (hex (sha1-on-octet-stream s))) @@ -68,13 +88,19 @@

SYMMETRIC KEY ENCRYPTION ======================== -The Cipher class provides common functionality for symmetric and asymmetric algorithms used for encryption. Subclasses of the Cipher class must support the following methods:

-init-encrypt: Initializes the Cipher object for encryption. Arguments may include the key and mode to use. +The Cipher class provides common functionality for symmetric and asymmetric +algorithms used for encryption. Subclasses of the Cipher class must support +the following methods: + +init-encrypt: Initializes the Cipher object for encryption. Arguments may +include the key and mode to use.

-init-decrypt: Initializes the Cipher object for decryption. Arguments may include the key and mode to use. +init-decrypt: Initializes the Cipher object for decryption. Arguments may +include the key and mode to use.

-update: Updates the state of the Cipher object. This means adding encrypted data for decryption or cleartext for encryption. +update: Updates the state of the Cipher object. This means adding encrypted +data for decryption or cleartext for encryption.

encrypt: Applies padding and encrypts any leftover data.

@@ -95,7 +121,8 @@ -> Signature -> DSA

-To use a symmetric encryption scheme like IDEA or AES, start by getting an instance of the algorithm: +To use a symmetric encryption scheme like IDEA or AES, start by getting an +instance of the algorithm:

crypticl(37): (setf obj (new-instance 'AES)) #<AES @ #x20d98f5a> @@ -114,7 +141,9 @@ crypticl(48): (hex (encrypt obj #(1 2 3))) "b92a901ceb2d6da3f74cfafcc8bc4064"

-Note that although the input is only a 3 byte vector the output is a 16 byte long vector because of padding. To decrypt, initialize the object for decryption with the same key used for encryption and call decrypt: +Note that although the input is only a 3 byte vector the output is a 16 byte +long vector because of padding. To decrypt, initialize the object for +decryption with the same key used for encryption and call decrypt:

crypticl(49): (init-decrypt obj aeskey)

@@ -122,7 +151,8 @@ #(1 2 3)

-The next example is more advanced and sets both the iv and mode before doing encryption and decryption in several steps using the update function. +The next example is more advanced and sets both the iv and mode before doing +encryption and decryption in several steps using the update function.

crypticl(126): (setf obj (new-instance 'AES)) @@ -130,7 +160,14 @@ crypticl(129): (init-encrypt obj aeskey :mode 'cbc :iv #16(0)) 0

-The CBC mode is the default mode and the only safe mode implemented. The default iv is #16(0). In the following we encrypt the input stream a bit at a time, a typical thing to do for large files or network streams. Each call to update returns the cryptotext for the section of cleartext given as input, minus possibly a residue modulo the block size. The encryption (or decryption) must be closed with a call to encrypt(decrypt). This call will empty any buffered cleartext from previous calls to update, add padding and return the last of the cryptotext. +The CBC mode is the default mode and the only safe mode implemented. The +default iv is #16(0). In the following we encrypt the input stream a bit at a +time, a typical thing to do for large files or network streams. Each call to +update returns the cryptotext for the section of cleartext given as input, +minus possibly a residue modulo the block size. The encryption (or decryption) +must be closed with a call to encrypt(decrypt). This call will empty any +buffered cleartext from previous calls to update, add padding and return the +last of the cryptotext.

crypticl(131): (init-encrypt obj aeskey :mode 'cbc :iv #16(0)) 0 @@ -139,7 +176,8 @@ crypticl(135): (hex (update obj #7(2))) ""

-NOte how this call didn't return any cryptotext because update didn't add enough cleartext to fill a whole block of cryptotext. +Note how this call didn't return any cryptotext because update didn't add +enough cleartext to fill a whole block of cryptotext.

crypticl(136): (hex (encrypt obj)) "e32e05ea9f3d9c40c12431c3ef77afbb" @@ -152,9 +190,12 @@

-Digital signatures +DIGITAL SIGNATURES ================== -We create a DSA object and generate a keypair. We see that the keypair object contain a private key for signing data and a public key for verifying signatures. + +We create a DSA object and generate a keypair. We see that the keypair object +contain a private key for signing data and a public key for verifying +signatures.

crypticl(148): (setf obj (new-instance 'DSA)) #<DSA @ #x215d9faa> @@ -173,20 +214,27 @@ crypticl(155): (init-sign obj (private dsakey)) ...

-Sign the data. The sign function returns the signature as a list of two numbers: +Sign the data. The sign function returns the signature as a list of two +numbers: + crypticl(156): (setf signature (sign obj #16(1))) (610205237490270933520572927751741211804151194981 814606745356376522186211750303275432244290651385)

-We can verify a singature by initializing the DSA object with the public key and give the data and the signature as input too verify: +We can verify a singature by initializing the DSA object with the public key +and give the data and the signature as input too verify:

crypticl(158): (verify obj signature #16(1)) t

-Diffie-Hellman +DIFFIE-HELLMAN ============== -The following functions illustrates the Diffie-Hellman interface. The result will be list with two secrets which should be equal. Each of the two Diffie-Hellman objects dh1 and dh2 represents the two endpoints in a secure exchange of a common secret. + +The following functions illustrates the Diffie-Hellman interface. The result +will be list with two secrets which should be equal. Each of the two +Diffie-Hellman objects dh1 and dh2 represents the two endpoints in a secure +exchange of a common secret.

(defun test-dh () (let (half-secret-1 --- /project/crypticl/cvsroot/crypticl/doc/README 2007/01/17 22:00:57 1.7 +++ /project/crypticl/cvsroot/crypticl/doc/README 2007/01/20 15:35:00 1.8 @@ -1,4 +1,5 @@ INTRODUCTION +============

Crypticl is a library of cryptographic functions written in Common Lisp. The goal is to provide flexible, high level cryptographic abstractions on top of @@ -9,10 +10,16 @@ implement all available cryptographic algorithms. Hence AES is included and DES is not.

+ WEBSITE +======= + http://common-lisp.net/project/crypticl/

+ INSTALL +======= + The library can be loaded by loading the file "load.lisp". This file will load the library and run unit tests.

@@ -22,26 +29,44 @@ contain some Allegro specific functions, but the bulk of the code is portable to all Common Lisp implementations.

+ DOCUMENTATION +============= + See the user guide in the file USERGUIDE.

+ DEVELOPERS +========== + Document changes in the ChangeLog in addition to writing commit messages. Before commiting, check that the library loads correctly into a fresh top level (use (delete-package 'crypticl) and reload) and verify that the unit tests are successful. Tag with V_<major>_<minor>_<num>, like V_0_1_0, V_0_1_1, etc.

+ TODO +==== + The file TODO is meant as a supplement to the various TODO comments in the source.

+ CHANGELOG +========= + See the file ChangeLog for the project change log.

+ CREDITS +======= + Tage Stabell-Kulø Frode V. Fjeld

+ AUTHOR +====== + Taale Skogan \ No newline at end of file