Using ecstool - rallytac/pub GitHub Wiki
The Engage Certificate Storage Tool, or ecstool is a command-line utility that allows you to manage certificate stores. The utility is available for Windows, Linux, and Mac OSX platforms and is designed with administrative personnel in mind. As such, it is a no-frills application that allow admins to quickly and easily modify and query certificate stores without the need for complex graphical user interfaces.
To run ecstool, simply invoke the application with required parameters. These parameters define the operation to be carried out. For example, to show quick help:
$ ecstool --help
usage: ecstool <file_name> [--pass:<passwordHexString>] [--tags:<tags>] [--quiet] <operation> ...
Operations:
create
list
descriptor
pem <id>
add <id> <certificate_pem_file> [<private_key_pem_file>]
addp12 <id> <p12_or_pfx_file> [p12_export_password]
import <id> <srcId> <srcFile> [srcPasswordHexString]
del <id>
show <id>
tagset <id>As you can see from the help provided, the first parameter must always be the name of the certificate store file. The "--pass" parameter is an optional binary password represented as a string of hex digits. For example, assuming our certificate store is named "test.certstore" and the password is "ABC" (which is represented in hex as "404142"), and we want to list the contents using the "list" operation; our command-line would be:
$ ecstool test.certstore --pass:404142 listIf the certificate store is not password protected, our command-line would simply be:
$ ecstool test.certstore listThe "--tags" parameter is also an option element which used to associated an arbitrary string of tags with an element when it being added or updated.
As described in the example above, the "list" operation lists the contents of the store, showing the ID of each element and whether that element contains just a certificate or a certificate and associated private key. This command does not show details of each certificate, just essentially a directory listing of the contents.
$ ecstool test.certstore listAdding a certificate private keys is performed using the "add" operation. You can add just a certificate or a certificate and the private key for that certificate.
For this operation, the name of the file containing the PEM representation of the certificate must be provided as the first parameter following the "add" operation. If there is a private key to be added as part of the operation, the name of the file containing the PEM representation must be provided following the name of the certificate PEM file. (You cannot add just a private key - it must always be accompanied by a certificate.)
You can also add one or more tags to the certificate during the add operation. While these tags may be used for your own purposes, some tags are recognized by Engage Engines and Rallypoints to designate whether the certificate has a "defaulting" operation.
Note that adding an element with an ID that already exists will overwrite the existing element (including the certificate and private key). In other words, "add" effectively means "addOrUpdate".
For example, assuming we are adding just a certificate which we will identify as "rtsFactoryDefaultForClient", our command-line looks as follows (assuming the certificate PEM resides in "rtsFactoryDefaultEngage.pem"):
$ ecstool test.certstore add rtsFactoryDefaultForClient rtsFactoryDefaultEngage.pem
added/updated certificate for rtsFactoryDefaultForClientListing the certificate store would look as follows (notice "(CERTIFICATE ONLY"):
$ ecstool test.certstore list
id................: {c9d197ad-f7c8-4958-a0cd-816d31e8524d}
fileName..........: test.certstore
version...........: 1
1 CERTIFICATES
rtsFactoryDefaultForClient (CERTIFICATE ONLY) []Note the
id({c9d197ad-f7c8-4958-a0cd-816d31e8524d}) shown in the listing. This is a unique identifier generated when the store is first created. Subsequent modifications to the store will retain this identifier.
Now let's say we have a private key that goes along with the certificate, and its PEM resides in "rtsFactoryDefaultEngage.key", our command-line looks as follows:
$ ecstool test.certstore add rtsFactoryDefaultForClient rtsFactoryDefaultEngage.pem rtsFactoryDefaultEngage.key
added/updated certificate for rtsFactoryDefaultForClientListing the certificate store contents would now look as follows (notice "(CERTIFICATE + PRIVATE KEY"):
$ ecstool test.certstore list
id................: {c9d197ad-f7c8-4958-a0cd-816d31e8524d}
fileName..........: test.certstore
version...........: 1
1 CERTIFICATES
rtsFactoryDefaultForClient (CERTIFICATE + PRIVATE KEY) []To add another certificate, simply repeat the command line with a different identifier and different certificate and private key files. For example, let's add the RTS CA certificate. We don't have the private key for this certificate, so we'll just add the certificate.
$ ecstool test.certstore add rtsCertificateAuthority rtsCA.pem
added/updated certificate for rtsCertificateAuthorityIf we list our contents, now, we see the new entity:
$ ecstool test.certstore list
id................: {c9d197ad-f7c8-4958-a0cd-816d31e8524d}
fileName..........: test.certstore
version...........: 1
2 CERTIFICATES
rtsFactoryDefaultForClient (CERTIFICATE + PRIVATE KEY) []
rtsCertificateAuthority (CERTIFICATE ONLY) []You can also add elements to the certificate store from a PKCS12 file archive. Such archives typically have the extension ".p12" or ".pfx" and may contain multiple certificates and/or private keys. These archives are also usually password proected with what's known as the "export password" assigned by the creator of the archive.
Note the following caveats, though:
Only the first certificate element in the archive will be imported.
If the first certificate does not have a private key associated with it; only the certificate will be imported.
You cannot import only a private key. In order to import the private key from the archive, it must have a corresponding certificate.
Let's say that instead of the "rtsFactoryDefaultForClient" certificate and it's private key being in two seperate files as in the earlier example; they were rather in a PKCS12 file named "rtsFactoryDefaultForClient.p12" which has an export password of "12345". To import, your command-line would look as follows (using the "addp12" operation):
$ ecstool test.certstore addp12 rtsFactoryDefaultForClient rtsFactoryDefaultEngage.p12 12345
added/updated certificate for rtsFactoryDefaultForClientDeleting an element is performed with the "del" operation, specifying the identifier to be removed. For example, to remove the CA certificate we added earlier:
$ ecstool test.certstore del rtsCertificateAuthority
removed certificate and key for rtsCertificateAuthorityFor a description of a certificate, use the "show" operation. For example:
$ ecstool test.certstore show rtsFactoryDefaultForClient
2020:03:03 20:40:36.814 [0x1021d85c0- ] I/CertStore: Loading 'test.certstore'
id...............: [rtsFactoryDefaultForClient]
subject..........: [/C=US/ST=Washington/L=Seattle/O=Rally Tactical Systems, Inc./OU=(c) 2019 Rally Tactical Systems, Inc. - For authorized use only/CN=Engage Factory Default Certificate/emailAddress=[email protected]]
issuer...........: [/C=US/ST=Washington/L=Seattle/O=Rally Tactical Systems, Inc./OU=(c) 2019 Rally Tactical Systems, Inc. - For authorized use only/CN=Rally Tactical Systems Root CA 1/emailAddress=[email protected]]
selfSigned.......: [0]
version..........: [1]
notBefore........: [Sep 7 01:53:06 2019 GMT]
notAfter.........: [Sep 4 01:53:06 2029 GMT]There are times when applications such as scripts and other tools need to process the certstore and its contents and therefore need a formalized strcuture in which to view details. To accomplish this, ecstool has the "descriptor" operation which outputs information about the certstore in JSON format. For example:
$ ecstool rallypointd.certstore descriptor
{"certificates":[{"certificatePem":"-----BEGIN CERTIFICATE-----\nMIIDYzCCAsUCCQCv5htRvPUEMTAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy\nNjIzMzk0NloXDTI5MDgyMzIzMzk0NlowgfUxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\nDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx\nKTAnBgNVBAMMIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMgUm9vdCBDQSAxMSMwIQYJ\nKoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjOPQIBBgUr\ngQQAIwOBhgAEAFq4pJf5N9/jike4V/go5seUVksUwkzkvT8EgFzVuqbJq8RgspHi\nucZNqgOPk4u5jIv2L8slsBf+4CzywG9fy2kmAK2TObjzXRdcyjP5Z68D43UvGS5X\n5nGoHh+vsoNrThLlf+b5dP/Y6wdEPv5a3LBHRuJAspjg6KBTYXz24NsNzitwMAoG\nCCqGSM49BAMCA4GLADCBhwJCAT+UvorzWqLn7lN5tjCjnHZWZpntWS+8Evj7Vkn6\ncXhov2EmYWOTvU/l2Fx7RBR9Qndj4Aiv+FMGVgXKBlxZGP3bAkE4ZmS+yTbHMtGn\nAQzDVYaZOZtZLlBvekiCqO9nyeLPwEE3yFxwj3iMLmHEQka/g3xi4AjLpdK6Pzdy\nmh/JGZAhEw==\n-----END CERTIFICATE-----\n","hasPrivateKey":false,"id":"rtsCA","tags":"-cadefault"},{"certificatePem":"-----BEGIN CERTIFICATE-----\nMIIDaTCCAssCCQCty2HImU4h3zAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy\nNjIzNDEwOFoXDTI5MDgyMzIzNDEwOFowgfsxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\nDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx\nLzAtBgNVBAMMJlJhbGx5cG9pbnQgRmFjdG9yeSBEZWZhdWx0IENlcnRpZmljYXRl\nMSMwIQYJKoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjO\nPQIBBgUrgQQAIwOBhgAEAZrUogUPPxekgufX56wkzFUtkZ8i4J+Rv1F4k5ZZBBEf\nrxcFjF7QjswZ7RxnBT6irwYmAwIBXHYMMw8o38tLjYNxARTA6woT5nIvj+d5sUhK\ngie3quLASWFJx00bR8PUliDHU8FNzkp98X6T+vBcxF7Vc8bCiF+ZjlnX8+MPqIYu\nchjcMAoGCCqGSM49BAMCA4GLADCBhwJBM+YCXS+Ne4E10HaXAQRxGOQW8+MSzHYc\niUsKF2rNcqe113WU8l4M1MSMRpn/osOuZGQEFNvqFlPZreMwMzI+5BACQgFdS5uM\nRE7FN5LpZ7A9gN9WRu1ODuYeRiQv3BG+FZCRLJ4Q4v2H+hm8WR9welKeNbRixxmD\nPBTBlVE/qylDBDZapw==\n-----END CERTIFICATE-----\n","hasPrivateKey":true,"id":"rtsFactoryDefaultRpSrv","tags":"-rpdefault"},{"certificatePem":"-----BEGIN CERTIFICATE-----\nMIIDiTCCAusCCQCty2HImU4h4jAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMCAXDTIzMDIw\nNTIwMzQwNVoYDzIwNTAwNjIyMjAzNDA1WjCBkTELMAkGA1UEBhMCVVMxEzARBgNV\nBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxIzAhBgNVBAoMGlJhbGx5\nIFRhY3RpY2FsIFN5c3RlbXMgSW5jMRQwEgYDVQQLDAtEZXZlbG9wbWVudDEgMB4G\nA1UEAwwXUlRTIFdlYnNvY2tldCBSUCBTZXJ2ZXIwggEiMA0GCSqGSIb3DQEBAQUA\nA4IBDwAwggEKAoIBAQDKMSayiOLVlFsQFBYL3n4+bWkVGFyfX0vAreBxB7LTxOBd\nUMHamPvIH9gSE0jlURlIJ2VFgRB1SwLwf4VbFBb1L49pMpnQLjDMksPXghkh9U6j\ndyxrvha4VnNYjjcYCC6KXCoK0IrbVrvxoCR9GaYh5A+6xjj/uONUYd142ngdE+RF\nyNTLvKmqSzCtOYVu1NehBbyOAcHv3kSJ9Dgh33ZBXPDurQfEKZlvcgTDawMfDUWg\nbwGYP4kG2tPrfgmMxydVc1wwXCMa7merxFee8wpgcwlW3RLCiBFPI+2V3vK+To9v\nXyE2V1BwBMsIYD+AwSayn+j4SALwJkZQWEghLMhLAgMBAAEwCgYIKoZIzj0EAwID\ngYsAMIGHAkIAoLNP2CZUckv9Rn+1GKCfXKFL5ynIENh2vYhf0xTb1afuAjwT9Hba\nckqw6GzbIHHGL/+xetb+PfEYw3RqkL6+q/8CQRC8Q0mCBU++7ozb6XkkI7d1ogtY\nq7HkCSsKBk6oNrO+b35PFjHIWMzkhlhUSHF1OuFs+In5eUPme+aRU485cJEh\n-----END CERTIFICATE-----\n","hasPrivateKey":true,"id":"rtsFactoryDefaultRpSrvWs","tags":"-rpwsdefault"}],"fileName":"rallypointd.certstore","flags":0,"id":"{9b8e8646-b2c1-4ee0-8abc-e667e7f4a770}","version":1}
builder@RTSs-Mac-mini devgru % ./ecstool --quiet rallypointd.certstore descriptor rtsCA
{"certificates":[{"certificatePem":"-----BEGIN CERTIFICATE-----\nMIIDYzCCAsUCCQCv5htRvPUEMTAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy\nNjIzMzk0NloXDTI5MDgyMzIzMzk0NlowgfUxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\nDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx\nKTAnBgNVBAMMIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMgUm9vdCBDQSAxMSMwIQYJ\nKoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjOPQIBBgUr\ngQQAIwOBhgAEAFq4pJf5N9/jike4V/go5seUVksUwkzkvT8EgFzVuqbJq8RgspHi\nucZNqgOPk4u5jIv2L8slsBf+4CzywG9fy2kmAK2TObjzXRdcyjP5Z68D43UvGS5X\n5nGoHh+vsoNrThLlf+b5dP/Y6wdEPv5a3LBHRuJAspjg6KBTYXz24NsNzitwMAoG\nCCqGSM49BAMCA4GLADCBhwJCAT+UvorzWqLn7lN5tjCjnHZWZpntWS+8Evj7Vkn6\ncXhov2EmYWOTvU/l2Fx7RBR9Qndj4Aiv+FMGVgXKBlxZGP3bAkE4ZmS+yTbHMtGn\nAQzDVYaZOZtZLlBvekiCqO9nyeLPwEE3yFxwj3iMLmHEQka/g3xi4AjLpdK6Pzdy\nmh/JGZAhEw==\n-----END CERTIFICATE-----\n","hasPrivateKey":false,"id":"rtsCA","tags":"-cadefault"},{"certificatePem":"-----BEGIN CERTIFICATE-----\nMIIDaTCCAssCCQCty2HImU4h3zAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy\nNjIzNDEwOFoXDTI5MDgyMzIzNDEwOFowgfsxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\nDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx\nLzAtBgNVBAMMJlJhbGx5cG9pbnQgRmFjdG9yeSBEZWZhdWx0IENlcnRpZmljYXRl\nMSMwIQYJKoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjO\nPQIBBgUrgQQAIwOBhgAEAZrUogUPPxekgufX56wkzFUtkZ8i4J+Rv1F4k5ZZBBEf\nrxcFjF7QjswZ7RxnBT6irwYmAwIBXHYMMw8o38tLjYNxARTA6woT5nIvj+d5sUhK\ngie3quLASWFJx00bR8PUliDHU8FNzkp98X6T+vBcxF7Vc8bCiF+ZjlnX8+MPqIYu\nchjcMAoGCCqGSM49BAMCA4GLADCBhwJBM+YCXS+Ne4E10HaXAQRxGOQW8+MSzHYc\niUsKF2rNcqe113WU8l4M1MSMRpn/osOuZGQEFNvqFlPZreMwMzI+5BACQgFdS5uM\nRE7FN5LpZ7A9gN9WRu1ODuYeRiQv3BG+FZCRLJ4Q4v2H+hm8WR9welKeNbRixxmD\nPBTBlVE/qylDBDZapw==\n-----END CERTIFICATE-----\n","hasPrivateKey":true,"id":"rtsFactoryDefaultRpSrv","tags":"-rpdefault"},{"certificatePem":"-----BEGIN CERTIFICATE-----\nMIIDiTCCAusCCQCty2HImU4h4jAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMCAXDTIzMDIw\nNTIwMzQwNVoYDzIwNTAwNjIyMjAzNDA1WjCBkTELMAkGA1UEBhMCVVMxEzARBgNV\nBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxIzAhBgNVBAoMGlJhbGx5\nIFRhY3RpY2FsIFN5c3RlbXMgSW5jMRQwEgYDVQQLDAtEZXZlbG9wbWVudDEgMB4G\nA1UEAwwXUlRTIFdlYnNvY2tldCBSUCBTZXJ2ZXIwggEiMA0GCSqGSIb3DQEBAQUA\nA4IBDwAwggEKAoIBAQDKMSayiOLVlFsQFBYL3n4+bWkVGFyfX0vAreBxB7LTxOBd\nUMHamPvIH9gSE0jlURlIJ2VFgRB1SwLwf4VbFBb1L49pMpnQLjDMksPXghkh9U6j\ndyxrvha4VnNYjjcYCC6KXCoK0IrbVrvxoCR9GaYh5A+6xjj/uONUYd142ngdE+RF\nyNTLvKmqSzCtOYVu1NehBbyOAcHv3kSJ9Dgh33ZBXPDurQfEKZlvcgTDawMfDUWg\nbwGYP4kG2tPrfgmMxydVc1wwXCMa7merxFee8wpgcwlW3RLCiBFPI+2V3vK+To9v\nXyE2V1BwBMsIYD+AwSayn+j4SALwJkZQWEghLMhLAgMBAAEwCgYIKoZIzj0EAwID\ngYsAMIGHAkIAoLNP2CZUckv9Rn+1GKCfXKFL5ynIENh2vYhf0xTb1afuAjwT9Hba\nckqw6GzbIHHGL/+xetb+PfEYw3RqkL6+q/8CQRC8Q0mCBU++7ozb6XkkI7d1ogtY\nq7HkCSsKBk6oNrO+b35PFjHIWMzkhlhUSHF1OuFs+In5eUPme+aRU485cJEh\n-----END CERTIFICATE-----\n","hasPrivateKey":true,"id":"rtsFactoryDefaultRpSrvWs","tags":"-rpwsdefault"}],"fileName":"rallypointd.certstore","flags":0,"id":"{9b8e8646-b2c1-4ee0-8abc-e667e7f4a770}","version":1}Given that this output is JSON, it can be further processed by a tool such as jq to make it more readble. For example:
$ ecstool --quiet rallypointd.certstore descriptor | jq .
{
"certificates": [
{
"certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDYzCCAsUCCQCv5htRvPUEMTAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy\nNjIzMzk0NloXDTI5MDgyMzIzMzk0NlowgfUxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\nDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx\nKTAnBgNVBAMMIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMgUm9vdCBDQSAxMSMwIQYJ\nKoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjOPQIBBgUr\ngQQAIwOBhgAEAFq4pJf5N9/jike4V/go5seUVksUwkzkvT8EgFzVuqbJq8RgspHi\nucZNqgOPk4u5jIv2L8slsBf+4CzywG9fy2kmAK2TObjzXRdcyjP5Z68D43UvGS5X\n5nGoHh+vsoNrThLlf+b5dP/Y6wdEPv5a3LBHRuJAspjg6KBTYXz24NsNzitwMAoG\nCCqGSM49BAMCA4GLADCBhwJCAT+UvorzWqLn7lN5tjCjnHZWZpntWS+8Evj7Vkn6\ncXhov2EmYWOTvU/l2Fx7RBR9Qndj4Aiv+FMGVgXKBlxZGP3bAkE4ZmS+yTbHMtGn\nAQzDVYaZOZtZLlBvekiCqO9nyeLPwEE3yFxwj3iMLmHEQka/g3xi4AjLpdK6Pzdy\nmh/JGZAhEw==\n-----END CERTIFICATE-----\n",
"hasPrivateKey": false,
"id": "rtsCA",
"tags": "-cadefault"
},
{
"certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDaTCCAssCCQCty2HImU4h3zAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy\nNjIzNDEwOFoXDTI5MDgyMzIzNDEwOFowgfsxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\nDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU\nYWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx\nLzAtBgNVBAMMJlJhbGx5cG9pbnQgRmFjdG9yeSBEZWZhdWx0IENlcnRpZmljYXRl\nMSMwIQYJKoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjO\nPQIBBgUrgQQAIwOBhgAEAZrUogUPPxekgufX56wkzFUtkZ8i4J+Rv1F4k5ZZBBEf\nrxcFjF7QjswZ7RxnBT6irwYmAwIBXHYMMw8o38tLjYNxARTA6woT5nIvj+d5sUhK\ngie3quLASWFJx00bR8PUliDHU8FNzkp98X6T+vBcxF7Vc8bCiF+ZjlnX8+MPqIYu\nchjcMAoGCCqGSM49BAMCA4GLADCBhwJBM+YCXS+Ne4E10HaXAQRxGOQW8+MSzHYc\niUsKF2rNcqe113WU8l4M1MSMRpn/osOuZGQEFNvqFlPZreMwMzI+5BACQgFdS5uM\nRE7FN5LpZ7A9gN9WRu1ODuYeRiQv3BG+FZCRLJ4Q4v2H+hm8WR9welKeNbRixxmD\nPBTBlVE/qylDBDZapw==\n-----END CERTIFICATE-----\n",
"hasPrivateKey": true,
"id": "rtsFactoryDefaultRpSrv",
"tags": "-rpdefault"
},
{
"certificatePem": "-----BEGIN CERTIFICATE-----\nMIIDiTCCAusCCQCty2HImU4h4jAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx\nEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM\nHFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5\nIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1\nc2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB\nIDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMCAXDTIzMDIw\nNTIwMzQwNVoYDzIwNTAwNjIyMjAzNDA1WjCBkTELMAkGA1UEBhMCVVMxEzARBgNV\nBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxIzAhBgNVBAoMGlJhbGx5\nIFRhY3RpY2FsIFN5c3RlbXMgSW5jMRQwEgYDVQQLDAtEZXZlbG9wbWVudDEgMB4G\nA1UEAwwXUlRTIFdlYnNvY2tldCBSUCBTZXJ2ZXIwggEiMA0GCSqGSIb3DQEBAQUA\nA4IBDwAwggEKAoIBAQDKMSayiOLVlFsQFBYL3n4+bWkVGFyfX0vAreBxB7LTxOBd\nUMHamPvIH9gSE0jlURlIJ2VFgRB1SwLwf4VbFBb1L49pMpnQLjDMksPXghkh9U6j\ndyxrvha4VnNYjjcYCC6KXCoK0IrbVrvxoCR9GaYh5A+6xjj/uONUYd142ngdE+RF\nyNTLvKmqSzCtOYVu1NehBbyOAcHv3kSJ9Dgh33ZBXPDurQfEKZlvcgTDawMfDUWg\nbwGYP4kG2tPrfgmMxydVc1wwXCMa7merxFee8wpgcwlW3RLCiBFPI+2V3vK+To9v\nXyE2V1BwBMsIYD+AwSayn+j4SALwJkZQWEghLMhLAgMBAAEwCgYIKoZIzj0EAwID\ngYsAMIGHAkIAoLNP2CZUckv9Rn+1GKCfXKFL5ynIENh2vYhf0xTb1afuAjwT9Hba\nckqw6GzbIHHGL/+xetb+PfEYw3RqkL6+q/8CQRC8Q0mCBU++7ozb6XkkI7d1ogtY\nq7HkCSsKBk6oNrO+b35PFjHIWMzkhlhUSHF1OuFs+In5eUPme+aRU485cJEh\n-----END CERTIFICATE-----\n",
"hasPrivateKey": true,
"id": "rtsFactoryDefaultRpSrvWs",
"tags": "-rpwsdefault"
}
],
"fileName": "rallypointd.certstore",
"flags": 0,
"id": "{9b8e8646-b2c1-4ee0-8abc-e667e7f4a770}",
"version": 1
}This JSON can then be processed and pulled apart as needed by downstream software - such as jq in this case.
Now, there are also instances where you simply want to raw content of a particular format for further analysis of that certificate - say by a certificate viewer. Here we use the pem operator to tell ecstool to output the certificate element in PEM format. For example, to view the PEM content of the rtsCA certificate in rallypointd.certstore we'd do the following:
$ ecstool --quiet rallypointd.certstore pem rtsCA
-----BEGIN CERTIFICATE-----
MIIDYzCCAsUCCQCv5htRvPUEMTAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx
EzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM
HFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5
IFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1
c2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB
IDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy
NjIzMzk0NloXDTI5MDgyMzIzMzk0NlowgfUxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
DApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU
YWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU
YWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx
KTAnBgNVBAMMIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMgUm9vdCBDQSAxMSMwIQYJ
KoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjOPQIBBgUr
gQQAIwOBhgAEAFq4pJf5N9/jike4V/go5seUVksUwkzkvT8EgFzVuqbJq8RgspHi
ucZNqgOPk4u5jIv2L8slsBf+4CzywG9fy2kmAK2TObjzXRdcyjP5Z68D43UvGS5X
5nGoHh+vsoNrThLlf+b5dP/Y6wdEPv5a3LBHRuJAspjg6KBTYXz24NsNzitwMAoG
CCqGSM49BAMCA4GLADCBhwJCAT+UvorzWqLn7lN5tjCjnHZWZpntWS+8Evj7Vkn6
cXhov2EmYWOTvU/l2Fx7RBR9Qndj4Aiv+FMGVgXKBlxZGP3bAkE4ZmS+yTbHMtGn
AQzDVYaZOZtZLlBvekiCqO9nyeLPwEE3yFxwj3iMLmHEQka/g3xi4AjLpdK6Pzdy
mh/JGZAhEw==
-----END CERTIFICATE-----If you want to view the resulting PEM, the output can be piped in the openssl utility or other viewer of your choice. For example:
$ ./ecstool --quiet rallypointd.certstore pem rtsCA | openssl x509 -text
Certificate:
Data:
Version: 1 (0x0)
Serial Number:
af:e6:1b:51:bc:f5:04:31
Signature Algorithm: ecdsa-with-SHA256
Issuer: C=US, ST=Washington, L=Seattle, O=Rally Tactical Systems, Inc., OU=(c) 2019 Rally Tactical Systems, Inc. - For authorized use only, CN=Rally Tactical Systems Root CA 1, [email protected]
Validity
Not Before: Aug 26 23:39:46 2019 GMT
Not After : Aug 23 23:39:46 2029 GMT
Subject: C=US, ST=Washington, L=Seattle, O=Rally Tactical Systems, Inc., OU=(c) 2019 Rally Tactical Systems, Inc. - For authorized use only, CN=Rally Tactical Systems Root CA 1, [email protected]
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey
Public-Key: (521 bit)
pub:
04:00:5a:b8:a4:97:f9:37:df:e3:8a:47:b8:57:f8:
28:e6:c7:94:56:4b:14:c2:4c:e4:bd:3f:04:80:5c:
d5:ba:a6:c9:ab:c4:60:b2:91:e2:b9:c6:4d:aa:03:
8f:93:8b:b9:8c:8b:f6:2f:cb:25:b0:17:fe:e0:2c:
f2:c0:6f:5f:cb:69:26:00:ad:93:39:b8:f3:5d:17:
5c:ca:33:f9:67:af:03:e3:75:2f:19:2e:57:e6:71:
a8:1e:1f:af:b2:83:6b:4e:12:e5:7f:e6:f9:74:ff:
d8:eb:07:44:3e:fe:5a:dc:b0:47:46:e2:40:b2:98:
e0:e8:a0:53:61:7c:f6:e0:db:0d:ce:2b:70
ASN1 OID: secp521r1
NIST CURVE: P-521
Signature Algorithm: ecdsa-with-SHA256
Signature Value:
30:81:87:02:42:01:3f:94:be:8a:f3:5a:a2:e7:ee:53:79:b6:
30:a3:9c:76:56:66:99:ed:59:2f:bc:12:f8:fb:56:49:fa:71:
78:68:bf:61:26:61:63:93:bd:4f:e5:d8:5c:7b:44:14:7d:42:
77:63:e0:08:af:f8:53:06:56:05:ca:06:5c:59:18:fd:db:02:
41:38:66:64:be:c9:36:c7:32:d1:a7:01:0c:c3:55:86:99:39:
9b:59:2e:50:6f:7a:48:82:a8:ef:67:c9:e2:cf:c0:41:37:c8:
5c:70:8f:78:8c:2e:61:c4:42:46:bf:83:7c:62:e0:08:cb:a5:
d2:ba:3f:37:72:9a:1f:c9:19:90:21:13
-----BEGIN CERTIFICATE-----
MIIDYzCCAsUCCQCv5htRvPUEMTAKBggqhkjOPQQDAjCB9TELMAkGA1UEBhMCVVMx
EzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUxJTAjBgNVBAoM
HFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4xSDBGBgNVBAsMPyhjKSAyMDE5
IFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMsIEluYy4gLSBGb3IgYXV0aG9yaXplZCB1
c2Ugb25seTEpMCcGA1UEAwwgUmFsbHkgVGFjdGljYWwgU3lzdGVtcyBSb290IENB
IDExIzAhBgkqhkiG9w0BCQEWFHN1cHBvcnRAcmFsbHl0YWMuY29tMB4XDTE5MDgy
NjIzMzk0NloXDTI5MDgyMzIzMzk0NlowgfUxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
DApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMSUwIwYDVQQKDBxSYWxseSBU
YWN0aWNhbCBTeXN0ZW1zLCBJbmMuMUgwRgYDVQQLDD8oYykgMjAxOSBSYWxseSBU
YWN0aWNhbCBTeXN0ZW1zLCBJbmMuIC0gRm9yIGF1dGhvcml6ZWQgdXNlIG9ubHkx
KTAnBgNVBAMMIFJhbGx5IFRhY3RpY2FsIFN5c3RlbXMgUm9vdCBDQSAxMSMwIQYJ
KoZIhvcNAQkBFhRzdXBwb3J0QHJhbGx5dGFjLmNvbTCBmzAQBgcqhkjOPQIBBgUr
gQQAIwOBhgAEAFq4pJf5N9/jike4V/go5seUVksUwkzkvT8EgFzVuqbJq8RgspHi
ucZNqgOPk4u5jIv2L8slsBf+4CzywG9fy2kmAK2TObjzXRdcyjP5Z68D43UvGS5X
5nGoHh+vsoNrThLlf+b5dP/Y6wdEPv5a3LBHRuJAspjg6KBTYXz24NsNzitwMAoG
CCqGSM49BAMCA4GLADCBhwJCAT+UvorzWqLn7lN5tjCjnHZWZpntWS+8Evj7Vkn6
cXhov2EmYWOTvU/l2Fx7RBR9Qndj4Aiv+FMGVgXKBlxZGP3bAkE4ZmS+yTbHMtGn
AQzDVYaZOZtZLlBvekiCqO9nyeLPwEE3yFxwj3iMLmHEQka/g3xi4AjLpdK6Pzdy
mh/JGZAhEw==
-----END CERTIFICATE-----Using the elements in the certificate store is a function of the application using the Engage Engine and the appropriate JSON configuration. As a quick example, though; to use the certificate store we managed with the above examples, the application would call the "engageOpenCertStore" API for the "test.certstore" and then have JSON elements refer to the IDs created - such as:
.
.
"security":{
"certificate" : {
"certificate":"@certstore://rtsFactoryDefaultForClient",
"key":"@certstore://rtsFactoryDefaultForClient"
}
}
.
.Please refer to the Engage Security wiki article for more detailed information.
As discussed in the Engage Security wiki article, Engage Engines and Rallypoints can use tagged certificate elements to automatically import certificates and keys from the active certificate store if security-related JSON configuration elements are left blank.
Tags are simply a string of characters that are associated with a certificate element in the store. These tags are associated (or cleared) during add/update operations by using the "--tags:" command-line parameter.
For example, as per the example above showing how to add a certificate, tagging it is as simple as including "--tags:" on the command-line. In this case we'll tag rtsFactoryDefaultForClient as the default Engine certificate.
$ ecstool test.certstore --tags:-enginedefault add rtsFactoryDefaultForClient rtsFactoryDefaultEngage.pem rtsFactoryDefaultEngage.keyListing the certificate store would look as follows (notice the [-enginedefault] tag):
$ ecstool test.certstore list
id................: {c9d197ad-f7c8-4958-a0cd-816d31e8524d}
fileName..........: test.certstore
version...........: 1
2 CERTIFICATES
rtsFactoryDefaultForClient (CERTIFICATE + PRIVATE KEY) [-enginedefault]
rtsCertificateAuthority (CERTIFICATE ONLY) []You can also just set (or unset) the tags in the certificate store using the "tagset" operation. This will not modify the certificate contents, just the tags associated with it.
$ ecstool test.certstore --tags:-cadefault tagset rtsCertificateAuthorityListing the contents now show the following:
id................: {c9d197ad-f7c8-4958-a0cd-816d31e8524d}
fileName..........: test.certstore
version...........: 1
2 CERTIFICATES
rtsFactoryDefaultForClient (CERTIFICATE + PRIVATE KEY) [-enginedefault]
rtsCertificateAuthority (CERTIFICATE ONLY) [-cadefault]There are current 2 tags recognized by Engage Engines:
| Name | Description |
|---|---|
-enginedefault |
The default certificate used for general X.509 operations. |
-cadefault |
The default Certificate Authority certificate. |
On a Rallypoint, the same logic applies but with a slightly different name for the default certificate:
| Name | Description |
|---|---|
-rpdefault |
The default certificate used for general X.509 operations. |
-cadefault |
The default Certificate Authority certificate. |