mirror of
https://github.com/gregtwallace/apc-p15-tool.git
synced 2025-01-22 16:14:09 +00:00
40eca754e0
* apcssh: add descriptive error when required file(s) not passed * create: dont create key+cert file when key isn't supported by NMC2 * config: fix usage messages re: key types * p15 files: dont generate key+cert when it isn't needed (aka NMC2 doesn't support key) * pkcs15: pre-calculate envelope when making the p15 struct * pkcs15: omit key ID 8 & 9 from EC keys * pkcs15: update key decode logic * pkcs15: add key type value for easy determination of compatibility * pkcs15: add ec key support * pkcs15: separate functions for key and key+cert p15 files * update README see: https://github.com/gregtwallace/apc-p15-tool/issues/6
177 lines
7.1 KiB
Markdown
177 lines
7.1 KiB
Markdown
# APC P15 Tool
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
### Key Types and Sizes
|
|
|
|
NMC2:
|
|
- RSA 1,024, 2,048, 3,072* bit lengths.
|
|
|
|
NMC3:
|
|
- RSA 1,024, 2,048, 3,072, and 4,092 bit lengths.
|
|
- ECDSA curves P-256, P-384, and P-521.
|
|
|
|
* 3,072 bit length is not officially supported by my NMC2, but appears to work
|
|
fine.
|
|
|
|
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.
|
|
|
|
### General Troubleshooting
|
|
|
|
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.1.2 and Boot Monitor
|
|
v1.0.9.
|
|
|
|
If you have trouble, your first step should be to update your NMC's firmware.
|
|
Many issues with this tool will be resolved simply by updating to the newest
|
|
firmware.
|
|
|
|
If you have a problem after that, 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
|
|
using the `--insecurecipher` flag. If this works, you should upgrade your
|
|
NMC to a newer firmware which includes secure ciphers. You should NOT automate
|
|
your environment using this flag as SSH over these ciphers is broken and
|
|
exploitable. If this also does not work, please run `ssh -vv myups.example.com`
|
|
and include the `peer server KEXINIT proposal` in your issue. For example:
|
|
|
|
```
|
|
debug2: peer server KEXINIT proposal
|
|
debug2: KEX algorithms: diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,ecdh-sha2-nistp256
|
|
debug2: host key algorithms: ssh-rsa
|
|
debug2: ciphers ctos: aes256-ctr,aes128-ctr,aes256-cbc,aes128-cbc
|
|
debug2: ciphers stoc: aes256-ctr,aes128-ctr,aes256-cbc,aes128-cbc
|
|
debug2: MACs ctos: hmac-sha2-256,hmac-sha1
|
|
debug2: MACs stoc: hmac-sha2-256,hmac-sha1
|
|
debug2: compression ctos: none
|
|
debug2: compression stoc: none
|
|
debug2: languages ctos:
|
|
debug2: languages stoc:
|
|
```
|
|
|
|
## Usage
|
|
|
|
Currently the tool contains two commands: create and install. The tool
|
|
can be run with the --help flag to see options.
|
|
|
|
i.e. `./apc-p15-tool --help`
|
|
|
|
Help can also be run on a subcommand to see the options for that
|
|
subcommand.
|
|
|
|
e.g. `./apc-p15-tool install --help`
|
|
|
|
### Create
|
|
|
|
Create creates an apc p15 file from given key and cert pem files or
|
|
content.
|
|
|
|
e.g. `./apc-p15-tool create --keyfile ./apckey.pem --certfile ./apccert.pem`
|
|
|
|
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 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`
|
|
|
|
## Note About Install Automation
|
|
|
|
The application supports passing all args instead as environment
|
|
variables by prefixing the flag name with `APC_P15_TOOL`.
|
|
|
|
e.g. `APC_P15_TOOL_KEYPEM`
|
|
|
|
Additionally, there is a second binary built with just the install
|
|
command so the subcommand is not needed.
|
|
|
|
There are mutually exclusive flags that allow specifying the pem
|
|
as either filenames or directly as strings. The strings are useful
|
|
for passing the pem content from another application without having
|
|
to save the pem files to disk.
|
|
|
|
Putting all of this together, you can combine the install binary with
|
|
a tool like Cert Warden (https://www.certwarden.com/) to call the
|
|
install binary, with environment variables, to directly upload new
|
|
certificates as they're issued by Cert Warden, without having to write a
|
|
separate script.
|
|
|
|
|
|
|
|
## Thanks
|
|
|
|
Special thanks to the following people and resources which helped me
|
|
deduce how all of this works:
|
|
|
|
https://github.com/dnlmengs/pemtrans
|
|
|
|
https://github.com/freddy36/apc_tools
|
|
|
|
http://lapo.it/asn1js/
|