generate and manage x509 certificates and private keys
Iron is a commandline utility to create a CA and certificates for services that need to share data over a secure channel with client authentication. It enforces convention over configuration to allow a full family of services sharing the same framework.
Get the software
Install deb package
issue the command:
sudo dpkg -i ./iron-1.0.0.deb
Install rpm package
you can install with the following command:
sudo rpm -i ./iron-1.0-3.noarch.rpm
Use the software
Iron comes with a minimal inline help:
$ iron Usage: iron <command> [<args>] Some useful iron commands are: ca manage CA certificate create certificates client manage CSR for certificates creation commands List all iron commands debug manage CA service manage service/server certificate creation See 'iron help <command>' for information on a specific command.
Generate a CA
A Certification Authority is the root certificate that we use in order to work with certificates and validate the claims made by all the other certificates. The way to generate such CA is documented next. But you can still access a simple command synopsis by typing:
$ iron ca Usage: iron ca <create|setup|delete>
For the actual use, see below:
$ iron ca setup Edit values in $HOME/.iron/default-ca.env $ cat $HOME/.iron/default-ca.env CAPATH=$HOME/.iron/CA CA_CONFIG_FILE=$HOME/.iron/CA/conf/openssl-ca.conf
But let’s explore/adapt such configuration:
$ cat $HOME/.iron/CA/conf/openssl-ca.conf RANDFILE = ::HOME/.rnd [ req ] default_bits = 1024 default_keyfile = keyfile.pem distinguished_name = req_distinguished_name attributes = req_attributes prompt = no #output_password = somerandompass default_days =3650 [ req_distinguished_name ] C = SE ST = YourCountry L = Yourcity O = data.kevwe.se OU = data.kevwe.se CN = data.kevwe.se emailAddress = firstname.lastname@example.org [ req_attributes ] challengePassword = somechallenge
And now proceed with the actual CA creation:
$ iron ca create Generating RSA private key, 2048 bit long modulus ................................................................................+++++ ........................+++++ e is 65537 (0x010001) Signature ok subject=C = SE, ST = YourCountry, L = Yourcity, O = data.kevwe.se, OU = data.kevwe.se, CN = data.kevwe.se, emailAddress = email@example.com Getting Private key
the generated CA and the relative secret key reside here:
$HOME/.iron/CA/ca.key $HOME/.iron/CA/ca.crt $HOME/.iron/CA/ca.csr
Generate certificates for a service
A first look at the command syntax:
$ iron service Usage: $iron service <setup|create|delete> <service>
And now let’s go ahead and generare the certificate for the service:
$ iron service setup x.kevwe.se Edit values in $HOME/.iron/service-x.kevwe.se.env cat /home/test/.iron/service-x.kevwe.se.env CERTPATH=$HOME/.iron/x.kevwe.se/certs CAPATH=$HOME/.iron/CA SERVER_CONFIG_FILE=$HOME/.iron/x.kevwe.se/conf/openssl-server.conf
Adjust the setup in that file, according to your needs:
$ cat $HOME/.iron/x.kevwe.se/conf/openssl-server.conf RANDFILE = ::HOME/.rnd [ req ] default_bits = 1024 default_keyfile = keyfile.pem distinguished_name = req_distinguished_name attributes = req_attributes prompt = no [ req_distinguished_name ] C = SE ST = YourCountry L = YourCity O = x.kevwe.se OU = x.kevwe.se CN = x.kevwe.se emailAddress = firstname.lastname@example.org [ req_attributes ] challengePassword = chpassswwwwsd
If you want to explore the command syntax, just type:
$ iron service Usage: $iron service <setup|create|delete> <service>
But let’s finally generate the certificate for the service/server that we are planning to expose as an endpoint.
$ iron service create x.kevwe.se Generating RSA private key, 2048 bit long modulus .+++++ .........................................+++++ e is 65537 (0x010001) Signature ok subject=C = SE, ST = YourCountry, L = Yourcity, O = x.kevwe.se, OU = x.kevwe.se, CN = x.kevwe.se, emailAddress = email@example.com Getting Private key
Take a look at what was generated:
$HOME/.iron/x.kevwe.se/certs/server.csr $HOME/.iron/x.kevwe.se/certs/server.crt $HOME/.iron/x.kevwe.se/certs/server.key
those files contain:
- server.csr : the Signing Request, useful for future certificate renewals
- server.crt : the service certificate
- server.key : the private key. DO NOT SHARE this should be possibly kept secret and encrypted with a password.
Let’s get now to the most useful and usually most tricky part of our application: the generation of client certificates.
What we are assuming now is that we have exposed some service (x.kevwe.se) that is published and is secured by a server certificate. Like in common HTTPS transactions, most of the time we just want to encrypt the traffic towards the server. The use case that we’re after now is when we want the server to only encrypt the traffic towards a specific client. Put in other words: if you don’t have a client certificate, you’re not going to be able to connect to the service. This way you achieve a data exchange that is both encrypted and authorized towards certain clients, to which dedicated client certificates will be distributed.
Usually you will want to generate a private key and a CSR on the client system, send it to the server, that will make a certificate out of it. The server will sign the CSR and will provide the actual certificate, possibly encrypted to the client.
The client will keep the key secret for itself and will eventually use it for updates or other purposes if desired.
Iron package can be installed on both server and client, it provides the necessary in both cases, it is the same install. It is just that on the server you will use:
$ iron certificate Usage: $iron certificate <sign> <service> <CSR-file> $iron certificate <create> <service> <client-id> $iron certificate <remotesign> <service><client-id>
on the client you will use:
$ iron client Usage: iron client <setup|csr|delete|export> <service> <client-id>
Before proceeding, of course on the client you won’t have the key of the CA, as on the CA/server machine you’ll not have the client key. It is fine like this.
I would add that iron will allow you also to generate client key and certificates on the server, but in a typical workflow that’s not the right thing, because you defy the purpose of public key cryptography that is: separating the secrets.
No matter what, if you still have some particular use case for being able to generate both client and server certificates on the same machine (some testing maybe?) you still can and Iron will not stop you. You take your full responsibility for that.
iron client setup x.kevwe.se client-zero Edit values in $HOME/.iron/x.kevwe.se/client-client-zero.env
Let’s adapt this configuration accordingly:
cat $HOME/.iron/x.kevwe.se/client-client-zero.env CLIENT_CONFIG_DIR=$HOME/.iron/x.kevwe.se/conf CLIENT_CERTPATH=$HOME/.iron/x.kevwe.se/certs CLIENT_CONFIG_FILE=$HOME/.iron/x.kevwe.se/conf/client-client-zero.conf CAPATH=$HOME/.iron/x.kevwe.se/CA
With that configuration in place, we are now able to generate the CSR:
iron client csr x.kevwe.se client-zero Generating RSA private key, 1024 bit long modulus ..+++++ .+++++ e is 65537 (0x010001)
Here you will have stored a copy of the CSR:
The client will have to send somehow to the server the CSR, and the server/CA server will use to create the certificate to give back to the client, like this:
iron certificate sign x.kevwe.se /tmp/client-zero.csr Signature ok subject=C = SE, ST = YourCountry, L = Yourcity, O = x.kevwe.se, OU = x.kevwe.se, CN = client-zero, emailAddress = client-zero Getting CA Private Key
Assuming that he has a copy of the client CSR saved on the path:
This command has generated the client certificate, that should be now redistributed to the client on a secure protocol.
If the server can, for example, reach the client over ssh, i.e.: if you are either on a local network or you have a VPN between the nodes, Iron is still able to sign the remote CSR and generate the certificate with the following command:
$iron certificate remotesign x.kevwe.se $CLIENT_USER $REMOTE_MACHINE $REMOTE_CSR_FILENAME
Provided that you know the following:
- $CLIENT_USER : the user on the client machine
- $REMOTE_MACHINE : the client host
- $REMOTE_CSR_FILENAME : the remote path of the CSR on the client host
COMMUNITY EDITION Here you can download a preview of the software, and you have to consider it as a Beta unlicensed version to be used for evaluation. you might considering buying support, for which you are encouraged to reach out.