diff --git a/README.md b/README.md index fb1cae5..b41e8f3 100644 --- a/README.md +++ b/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 -proprietary tools (such as cryptlib). + +APC P15 Tool is a completely open source application designed to make +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 -aka `NMC Security Wizard CLI Utility`. The files it generates should be -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. +Both NMC2 and NMC3 devices should be fully supported. However, I have one +NMC2 device in a home lab and have no way to guarantee success in all cases. -The install functionality is a custom creation of mine so it may or may not -work depending on your exact setup. My setup (and therefore the testing -setup) is: +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. + +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 -directly loaded on to an APC NMC2 (Network Management Card 2). +The command creates and outputs ./apctool.p15 and ./apctool.key.p15 by +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 -to disk. It instead uploads the p15 file directly to the specified -remote host, via scp. +Install generates the necessary p15 file(s) but does NOT save them to +disk. It instead installs the files directly on the NMC. Logic +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`