Merge pull request #29 from lealem47/clu

Updating wolfCLU docs

Author: JacobBarthelmeh

wolfCLU/create-pdf.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+pandoc -s header.txt src/Intro.md src/build.md src/command_list.md src/bench.md src/ca.md src/crl.md src/dsaparam.md src/dhparam.md src/dgst.md src/ecparam.md src/enc.md src/genkey.md src/hash.md src/md5.md src/sha.md src/pkcs12.md src/pkey.md src/rand.md src/req.md src/rsa.md src/s_client.md src/verify.md src/x509.md --toc -o wolfCLU_Manual.pdf

wolfCLU/src/build.md

@@ -1,4 +1,6 @@
 ## Building wolfCLU
+
+### Building on *NIX
 To build wolfCLU first build wolfSSL with the --enable-wolfclu flag. An example of this would be:
 
 ```
@@ -26,4 +28,38 @@ cd wolfclu
 ./configure --with-wolfssl=/path/to/wolfssl/install
 make
 sudo make install
-``` 
+```
+
+Run `make check` to run unit tests.
+
+## Building on Windows
+
+wolfCLU can also be built with its Visual Studios solution, wolfclu.sln. The solution provides both Debug and Release builds of Dynamic 32- or 64-bit libraries. The file `user_settings.h` should be used in the wolfSSL build to configure it.
+
+The file `wolfclu\ide\winvs\user_settings.h` contains the settings used to configure wolfSSL with the appropriate settings. This file must be copied from the directory `wolfclu\ide\winvs` to `wolfssl\IDE\WIN`. You can then build wolfSSL with support for wolfCLU. 
+
+Before building wolfCLU, Make sure you have the same architecture (Win32 or x64) selected as used in wolfSSL.
+
+This project assumes that the wolfSSH and wolfSSL source directories
+are installed side-by-side and do not have the version number in their
+names:
+```
+    Projects\
+        wolfclu\
+        wolfssl\
+```
+
+Building wolfCLU a release configuration will generate `wolfssl.exe` in the 
+`Release\Win32` or `Release\x64` directory. 
+
+#### Running Unit Tests
+
+To run the shell-script unit tests, you will need either the `sh` or `bash`
+commands, both of which come with a Git installation on Windows (although you
+may have to add them to the PATH). 
+
+1. Copy the `wolfssl.exe` to the root directory of wolfclu.
+2. Modify the `run` function (as well as `run_fail`, if present) of the desired 
+unit test to run `./wolfssl.exe $1` instead of `./wolfssl $1`.
+3. In your terminal, run `sh <desired_unit_test>` from the root directory. For 
+instance, to run the hash unit tests, run `sh tests\hash\hash-test.sh`.

wolfCLU/src/ca.md

@@ -0,0 +1,21 @@
+### CA Command
+Used for signing Certificates. Can handle some basic config file parsing.
+
+Available arguments are:    
+
+- [-in] input CSR file
+- [-out] file to write to
+- [-keyfile] file to read private key from
+- [-cert] file to read CA from
+- [-extensions] section in config file to parse extensions from
+- [-md] type of hash to use i.e sha, sha256, ...
+- [-inform] PEM/DER type of CSR input
+- [-config] file to parse for configuration
+- [-days] number of days should be valid for
+- [-selfsign] sign with key associated with input cert
+
+Example:
+
+```
+wolfssl ca -config ca.conf -in test.csr -out test.pem -md sha256 -selfsign -keyfile ./key
+```

wolfCLU/src/command_list.md

@@ -1,6 +1,8 @@
 ## List Of Commands:
 - bench
+- ca
 - crl
+- dsaparam
 - dgst
 - ecparam
 - enc
@@ -15,3 +17,7 @@
 - s_client
 - verify
 - x509
+- dhparam
+- sha256
+- sha384
+- sha512

wolfCLU/src/dgst.md

@@ -9,12 +9,26 @@ Hash algos supported:
 - [-sha384]
 - [-sha512]
 
+**Sign**
+
+Parameters:     
+
+- [-sign] key used to create signature
+- [-out] file to write signature to
+
+Example:
+```
+wolfssl dgst -sign keyPrivate.pem -out test.sig testfile
+```
+
+**Verify**
+
 Parameters:     
 
-- [-signature] file containing the signature
 - [-verify] key used to verify the signature
+- [-signature] file containing the signature
 
 Example:
 ```
-wolfssl dgst -signature test.sig -verify key.pem test
-```
+wolfssl dgst -verify keyPublic.pem -signature test.sig testfile
+```

wolfCLU/src/dhparam.md

@@ -0,0 +1,16 @@
+### DHPARAM Command
+
+Used for creating Diffie Hellman params and keys.
+
+Available arguments are:    
+
+- [-genkey] create new DH key
+- [-in] file to read params from to create a key
+- [-out] file to output to (default stdout)
+- [-check] check if generated parameters are valid
+- [-noout] do not print out the params
+
+Example: 
+
+```
+wolfssl dhparam -check -out dh.params 1024

wolfCLU/src/dsaparam.md

@@ -0,0 +1,17 @@
+### DSAPARAM Command
+
+Used for creating DSA params and keys. Make sure wolfSSL is compiled with `--enable-dsa`.
+
+Available arguments are:    
+
+- [-genkey] create new DSA key
+- [-in] file to read params from to create a key
+- [-out] file to output to (default stdout)
+- [-noout] do not print out the params
+
+Example: 
+
+```
+wolfssl dsaparam -out dsa.params 1024
+wolfssl dsaparam -in dsa.params -genkey
+```

wolfCLU/src/genkey.md

@@ -1,17 +1,18 @@
 ### GENKEY Command
-Used to generate RSA, ECC, and ED25519 keys. If using "-output KEY" a private key is created having .priv appended to -out argument and a public key is created with .pub appended to the -out argument. If generating ED25519 keys compile wolfSSL with --enable-ed25519.
+Used to generate RSA, ECC, ED25519 and DSA keys. If using "-output KEY" a private key is created having .priv appended to -out argument and a public key is created with .pub appended to the -out argument. If generating ED25519 keys compile wolfSSL with --enable-ed25519.
 
 Available arguments are:    
 
 - [-out] file to write to
 - [rsa | ecc | ed25519] key type to generate
 - [-inkey] input file for key
 - [-size] size of key to generate
-- [-outform] output form, either DER or PEM
+- [-outform] output form, either DER or PEM (defaults to DER)
+- [-output] key to generate, either PUB, PRIV or KEYPAIR (defaults to KEYPAIR) 
 - [-exponent] RSA exponent size
 
 Example:
 
 ```
-wolfssl genkey rsa -size 2048 -out mykey -outform pem  -output KEY
-```
+wolfssl genkey rsa -size 2048 -out mykey -outform pem  -output KEYPAIR
+```

wolfCLU/src/pkey.md

@@ -2,12 +2,12 @@
 Used for dealing with generic key operations. Prints the key read in to stdout.
 
 - [-in] file input for key
-- [-inform] pem or der input format
+- [-inform] pem or der input format (defaults to pem)
 - [-pubout] only print out the public key
-
+- [-pubin] expect to public key as input
 
 Example:
 
 ```
 ./wolfssl pkey -in ./certs/server-key.pem -inform pem -pubout
-```
+```

wolfCLU/src/req.md

@@ -6,8 +6,8 @@ Available arguments are:
 - [-in] input file to read from
 - [-out] file to write to (default stdout)
 - [-key] public key to put into certificate request
-- [-inform] der or pem format for '-in'
-- [-outform] der or pem format for '-out'
+- [-inform] der or pem format for '-in' (defaults to pem) 
+- [-outform] der or pem format for '-out' (defaults to pem)
 - [-config] file to parse for certificate configuration
 - [-days] number of days should be valid for
 - [-x509] generate self signed certificate
@@ -18,4 +18,4 @@ Example:
 wolfssl ecparam -genkey -out ecc.key -name secp384r1
 wolfssl req -new -x509 -days 3650 -config selfsigned.conf -key ecc.key -out ecc.cert \
 -outform der -sha256
-```
+```