mirror of
https://github.com/gregtwallace/apc-p15-tool.git
synced 2025-08-06 20:37:48 +00:00
236 lines
9.6 KiB
Markdown
236 lines
9.6 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.
|
|
|
|
### Key Types and Sizes
|
|
|
|
Ensure you select an appropriate key!
|
|
|
|
NMC2 is extremely picky about the key type and size it supports. NMC3 is a bit
|
|
more flexible. Beware, some ACME clients will generate an ECDSA key by default
|
|
which is NOT supported by NMC2.
|
|
|
|
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.
|
|
|
|
\* The additional key types supported by NMC3 require newer firmware on the
|
|
device. I am unsure what the version cutoff is, but you can check support
|
|
by connecting to the UPS via SSH and typing `ssl`. If `Command Not Found`
|
|
is returned, the firmware is too old and only the key types listed under
|
|
NMC2 will work.
|
|
|
|
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.
|
|
|
|
### 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.
|
|
|
|
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.
|
|
|
|
Generally, if there is a compatibility issue, there is a good chance you will
|
|
not see an error. Rather, the NMC will silently fail and you'll only know
|
|
something went wrong because the NMC's certificate didn't update, or it regenerated
|
|
a self-signed certificate that you'll see upon your next connection attempt.
|
|
I've tried to add some `WARNING` messages to the tool to indicate what might
|
|
be going wrong, but the list is definitely not exhaustive.
|
|
|
|
### Troubleshooting
|
|
|
|
Suggested troubleshooting steps:
|
|
- Review the `Key Types and Sizes` and `Compatibility Notice` sections of this
|
|
README.
|
|
- Update your NMC's firmware to the latest version.
|
|
- Read this tool's output, look specifically for any `WARNING` messages and
|
|
adjust your certificate accordingly.
|
|
- Test using an RSA 2048 bit key to obtain a certificate from Let's Encrypt.
|
|
Their certificates are known to work with NMC.
|
|
- Use the official NMC Security Wizard to verify you can create a working
|
|
certificate and load it into your NMC. If the official tool does not work
|
|
switching to this tool won't help.
|
|
|
|
If you have tried all of these steps and are still experiencing a problem,
|
|
you may open an Issue on GitHub.
|
|
|
|
Include:
|
|
- The full command you are running that is causing the problem.
|
|
- The full log of this tool's output when you run the command. Append the
|
|
`--debug` flag to your command to get the debug output.
|
|
|
|
Keep in mind, I am one person with one specific hardware setup. I may not
|
|
be able to help you.
|
|
|
|
#### NMC3 Install `ssh: parse error in message type 53` Error
|
|
|
|
Configuring a `System Message` on an NMC3 breaks the install function. I do
|
|
not have an NMC3 and after doing some code review it is highly unlikely I'll
|
|
be able to fix this. Don't use a `System Message` if the install feature is
|
|
important to you.
|
|
|
|
see: https://github.com/gregtwallace/apc-p15-tool/issues/14
|
|
|
|
#### Install `ssh: handshake failed` Error
|
|
|
|
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 --hostname myapc.example.com --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.
|
|
|
|
|
|
|
|
## Building
|
|
|
|
Python3, Go, and git all must be installed to run the build script.
|
|
|
|
Once the dependencies are installed, clone this repo and run
|
|
`python build_release.py`. If you only want to build for certain OS or
|
|
ARCH targets, edit the `targets` array in the `build_release.py` file
|
|
before running it.
|
|
|
|
## Links
|
|
|
|
@Owl-Tec's write up using this tool with ACDS:
|
|
https://owltec.ca/Windows+Server/Deploying+An+Internal+HTTPS+Certificate+for+a+UPS+APC+with+ADCS+(Active+Directory+Certificate+Services)+with+APC+P15+Tool
|
|
|
|
## 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/
|