Writing documentation

Design.md

@@ -10,4 +10,6 @@ secure, unpack and reconcile the restored/cloned documents.
 
 ## Technology
 
-PeterDocs is written as a PowerShell module and uses a 7ZIP and AWS modules.
+PeterDocs is written as a PowerShell module and uses the 7ZIP and AWS modules.
+
+The AWS module is only used if you are transferring to AWS S3 bucket or compatible destination.

Encryption.md

@@ -0,0 +1,82 @@
+# Encryption
+
+One of the three primary objectives for the PeterDocs design is to
+protect the data being transferred.  This objective is met by
+using 7ZIP archive encryption including file names.
+
+If the 7ZIP file were to be viewed without the password, the file names
+and folders would be illegible.  Therefore content metadata leakage is
+addressed.
+
+There are two options for encryption:
+
+1. Using a complex symmetric key
+2. Using an asymmetric key as that provided by the Microsoft ```certmgr```
+
+## SecretKey
+
+The PeterDocs parameter labelled ```SecretKey``` is used for symmetric key
+encryption.  The secret (or password) needs to be complex and at least
+10 characters long.
+
+The complex secret needs to contain lower case letter, upper case letter,
+numeric digit and special symbol.
+
+The secret is used directly on the 7ZIP compresison and you can use the
+secret to decrypt the archive file and check its contents.
+
+Make a note of the secret as you will need it to decrypt the contents.
+
+If you are transferring the archive to another person please send the
+secret to your recipient via an alternate channel to that of the archive
+file itself.
+
+## RecipientKey
+
+The PeterDocs parameter labelled ```RecipientKey``` is used for asymmetric
+keys provided by the Microsft Certificate Manager for encrypting content.
+
+This is the most secure method for transfer as it is secured with the
+certficates.  Using certificates requires:
+
+1. your recipient to send you their public certificate
+2. you to load the public certificate into your Windows Certificate Manager
+3. you to specify the key name as the value for  the ```RecipientKey```
+
+Once the archive is encrypted you will not be able to decrypt and view
+its contents.  Only the recipient with the private key can decrypt the
+contents.
+
+The recipient will need to receive the archive file plus the ```.key```
+file generated by PeterDocs.  Both files must be accessible to the
+recipient for decryptingg the contents.
+
+### Internal process
+
+Internally the PeterDocs process generates a long random password which
+is saved into the ```.key``` file which is encrypted using the recipients
+public key.
+
+The reason for doing this process is because there are technical limitations
+in encrypting large files using the certficate public keys.  The maximum
+size is around 60MB when using public keys.
+
+### Generating your Certificate
+
+You as a recipient can generate your own key by using Microsoft Certificate
+Manager or executing the below PowerShell command.
+
+```powershell
+    New-SelfSignedCertificate -Subject "CN=PeterDocs" -FriendlyName "PeterDocs"  -KeyDescription "Encryption key for PeterDocs data encipherment" -CertStoreLocation "Cert:\CurrentUser\My" -KeyUsage KeyEncipherment,DataEncipherment, KeyAgreement -Type DocumentEncryptionCert
+```
+
+To list your current certficates use the below PowerShell command.
+
+```powershell
+   Get-Childitem -Path "Cert:\CurrentUser\My" -DocumentEncryptionCert     
+```
+
+### Exporting your Certificate
+
+You will need to export your public key and send it to the person who will generate the archive
+file for you.  That person with your public key will need to import your public key.

README.md

@@ -2,13 +2,14 @@
 
 ## Summary
 
-PeterDocs is for Protecting, Transfering and Reconciling documents on remote computer
+PeterDocs is for [Protecting](Encryption.md), [Transferring](SendArchive.md) and [Reconciling](Reconcile.md) documents
-where the computers are isolated or on different networks.
+on a remote computer where the computers are isolated or on different networks.
 
-The process uses a Windows PowerShell script and both the source and target computers
+The process uses a Windows PowerShell module and script.  Both the source and target computers
-that execute the code are required to be installed with Windows PowerShell.
+that execute the code are required to have Windows PowerShell installed.
 
-transfer the file to your target, where the content are unpacked using the decryption
+Use the script to create an encrypted archive of the source folder and its contents, then
+transfer the archive file to your target, where the content are unpacked using the decryption
 key. After archive contents are restored you can execute the reconcile function
 to veriy that the contents are transferred, unaltered.
 
@@ -30,15 +31,17 @@ JAM Software FileList.
 
 ## Background
 
-The script was born out a necessity to transfer a large volume of photographs
+The script was born out of necessity to transfer a large volume of photographs
-from a media server to cloud backup.
+from a media server to cloud storage.  Commonly photographs are stored in many
+folders and can be large in number and size because of the increased
+resolution of digital cameras.
 
 ## Usage
 
 Packages source folder contents into a 7ZIP file, adding a reconciliation
 file to the 7ZIP file and then encrypting the contents.  Send
 
-* this script
+* this script or instructions on where to get the script
 * the 7ZIP package file
 * plus optional Secret File ( if using Recipient Key ) to the target or recipient.
 
@@ -72,10 +75,8 @@ A log file is produced on execution.  Repeated executions on the same day
 will add text content to the same log file.  The default log name takes the form:
 "PETERDOCS_yyyy-MM-dd.log"
 
-You will need to have installed the 7Zip4Powershell PowerShell cmdlet
+You will need to install the PeterDocs module from the PowerShell gallery or
-before using the pack or unpack actions.  You can install the cmdlet
+via local file NuGet package file if Internet access is limited.
-by executing
-.\ptrDocs.ps1 -Action install -Path ".\"
 
 ## Further Reading