readme: update general info about tool and compatibility

README.md

@@ -1,25 +1,78 @@
 # APC P15 Tool
-A tool to create APC p15 formatted certificates from pem files, without
+
-having to use APC's closed-source tool, APC generated keys, or other 
+APC P15 Tool is a completely open source application designed to make 
-proprietary tools (such as cryptlib).
+creating and installing SSL certificates on APC (Schneider Electric) 
+Network Management Cards (2 & 3) simple and easy to do. It is also 
+designed to simplify automation of the certificate management lifecycle.
+
+## Background
+
+When APC created the NMC2 (Network Management Card 2), they chose to use 
+the p15 file format for their SSL keys and certificates, which is a 
+relatively obscure file format. In addition to this, they designed the
+device to require an APC specific header be prepended to the p15 file
+or the file would be rejected by the device. Accordingly, they created 
+a proprietary tool (the `NMC Security Wizard CLI Utility`) to generate
+the required format.
+
+Unfortunately, the proprietary tool has a number of shortcomings:
+- It can be difficult to find the right version to use. APC has released
+  a number of versions (in both a CLI and GUI form). Not all of the
+  versions worked correctly (or at all).
+- User provided private keys are not supported. Private keys must be 
+  generated by the proprietary tool and are only outputted in the p15 
+  format. APC's proprietary tool is closed source and as such there is 
+  no way to audit the key generation process.
+- Since the generated keys are in the p15 format, they can't be loaded
+  easily into other management tools (such as Cert Warden
+  https://www.certwarden.com/), nor can CSRs be generated easily 
+  outside of the proprietary tool. The proprietary tool is generally
+  required to generate the CSR.
+- The CSR generation function in the proprietary tool is fairly rigid,
+  making customization (e.g., multiple DNS names) difficult, if not 
+  impossible.
+- After the user generates a key, generates a CSR, sends that CSR to 
+  their CA, and receives a certificate back, they're still not done.
+  The tool must be used again to generate the final p15 file for the
+  NMC.
+- To install the final file on the NMC, the user must use an SCP
+  program such as `pscp` to install the file, or the NMC's web UI.
+
+Due to all of this, others have tried to recreate the proprietary
+functionality. The only implementations I have found rely on a closed
+source library called `cryptlib`. This library has evolved over time
+and more recent versions do not work for the NMC (it appears at some
+point cryptlib switched from 3DES to AES and NMC does not support
+AES within the p15 file). It was also near impossible to find an old
+enough version of cryptlib that would work. Even if one gets this 
+working, it does not resolve the obscurity of a closed source 
+implementation and would continue to be subject to potential future
+breakage as the cryptlib library continues to evolve.
+
+This project aims to solve all of these problems by accepting the most
+common key and cert file format (PEM) and by being 100% open source
+and licensed under the GPL-3.0 license.
 
 ## Compatibility Notice
 
-This tool's create functionality is modeled from the APC NMCSecurityWizardCLI 
+Both NMC2 and NMC3 devices should be fully supported. However, I have one
-aka `NMC Security Wizard CLI Utility`. The files it generates should be 
+NMC2 device in a home lab and have no way to guarantee success in all cases.
-comaptible with any UPS that accepts p15 files from that tool. Only RSA 1,024
-and 2,048 bit keys are accepted. 1,024 bit RSA is no longer considered 
-completely secure; avoid keys of this size if possible. Most (all?) public 
-ACME services won't accept keys of this size anyway.
 
-The install functionality is a custom creation of mine so it may or may not 
+Only RSA 1,024 and 2,048 bit keys are accepted. 1,024 bit RSA is no longer 
-work depending on your exact setup. My setup (and therefore the testing 
+considered completely secure; avoid keys of this size if possible. Most 
-setup) is:
+(all?) public ACME services won't accept keys of this size anyway.
+
+Even though later versions of the NMC3 firmware supports RSA 4,096 and 
+ECDSA keys, this tool does not. These options were not available in APC's
+proprietary tool, and as such I have no way to generate files to reverse 
+engineer.
+
+My setup (and therefore the testing setup) is:
 - APC Smart-UPS 1500VA RM 2U SUA1500RM2U (Firmware Revision 667.18.D)
 - AP9631 NMC2 Hardware Revision 05 running AOS v7.0.4 and Boot Monitor 
   v1.0.9.
 
-If you have problems you can post the log in an issue and I can try to fix it
+If you have problems, please post the log in an issue and I can try to fix it
 but it may be difficult without your particular hardware to test with.
 
 In particular, if you are experiencing `ssh: handshake failed:` first try
@@ -62,14 +115,16 @@ content.
 
 e.g. `./apc-p15-tool create --keyfile ./apckey.pem --certfile ./apccert.pem`
 
-The command outputs ./apctool.p15 by default. This file can be 
+The command creates and outputs ./apctool.p15 and ./apctool.key.p15 by
-directly loaded on to an APC NMC2 (Network Management Card 2).
+default. These files are equivelant to the key and final p15 files
+generated by APC's proprietary tool.
 
 ### Install
 
-Install works similarly to create except it doesn't save the p15 file 
+Install generates the necessary p15 file(s) but does NOT save them to
-to disk. It instead uploads the p15 file directly to the specified 
+disk. It instead installs the files directly on the NMC. Logic
-remote host, via scp.
+automatically deduces if the device is an NMC2 or NMC3 and performs
+the appropriate installation steps.
 
 e.g. `./apc-p15-tool install --keyfile ./apckey.pem --certfile ./apccert.pem --apchost myapc.example.com:22 --username apc --password someSecret --fingerprint 123abc`