Generating Certificates with OpenSSL

From NIEF Wiki
Jump to navigation Jump to search

This page explains how to use the open source openssl program to generate GFIPM/NIEF compliant self signed X509 certificates for use within SAML transactions.

Basic Generation

To generate a self-signed certificate that conforms to the NIEF Certificate Policy use the following command:

 $ openssl req -x509 -sha256 -nodes -days 1826 -newkey rsa:2048 -keyout NEW_SERVER_KEY.key -out NEW_SERVER_CERT.crt

The above insures that the RSA key is 2048 bits and that the certificate is signed with SHA-256, the defaults for these two settings is insufficient to meet the requirements of the NIEF Certificate Policy.

Prompted Information

You will be prompted for a set of information that should be properly filled out for your organization. This data is published in the x509 certificate. An example of openssl prompting a user to fill out this information follows:

 writing new private key to 'NEW_SERVER_KEY.key'
 -----
 You are about to be asked to enter information that will be incorporated
 into your certificate request.
 What you are about to enter is what is called a Distinguished Name or a DN.
 There are quite a few fields but you can leave some blank
 For some fields there will be a default value,
 If you enter '.', the field will be left blank.
 -----
 Country Name (2 letter code) [GB]:US
 State or Province Name (full name) [Berkshire]:GA
 Locality Name (eg, city) [Newbury]:Atlanta
 Organization Name (eg, company) [My Company Ltd]:CISAnet
 Organizational Unit Name (eg, section) []:Identity Provider
 Common Name (eg, your name or your server's hostname) []:idp.cisanet.net
 Email Address []:support@cisanet.net

Finally, while GFIPM and NIEF have not formally adopted a requirement that all signing certificates and encryption certificates be different, this is a requirement of the Federal PKI and as such is highly recommended (and may become a GFIPM and/or NIEF requirement in the future). As such it is requested that all IDPs and SPs submit two separate certificates with their federation metadata.

Certificate Options

It is possible to use more sophisticated certificate options to constrain a certificate's use to signing or encryption. To use these options with openssl here are two sample ssl configuration files:

 [ req ]
 default_bits            = 2048
 default_md              = sha256
 prompt                  = yes
 x509_extensions         = v3_req
 distinguished_name      = default_name
 [ default_name ]
 0.organizationName      = Organization Name (company)
 organizationalUnitName  = Organizational Unit Name (department, division)
 emailAddress            = Email Address
 localityName            = Locality Name (city, district)
 stateOrProvinceName     = State or Province Name (full name)
 countryName             = Country Name (2 letter code)
 commonName              = Common Name (hostname, IP, or your name)
 [ v3_req ]
 basicConstraints        = CA:FALSE
 keyUsage                = keyEncipherment, dataEncipherment

The above example is for a certificate used for encryption. While this next example is for a signing certificate:

 [ req ]
 default_bits            = 2048
 default_md              = sha256
 prompt                  = yes
 x509_extensions         = v3_req
 distinguished_name      = default_name
 [ default_name ]
 0.organizationName      = Organization Name (company)
 organizationalUnitName  = Organizational Unit Name (department, division)
 emailAddress            = Email Address
 localityName            = Locality Name (city, district)
 stateOrProvinceName     = State or Province Name (full name)
 countryName             = Country Name (2 letter code)
 commonName              = Common Name (hostname, IP, or your name)
 [ v3_req ]
 basicConstraints        = CA:FALSE
 keyUsage                = digitalSignature, nonRepudiation, keyCertSign

Finally, if you are using these more advanced openssl options, you must specify the configuration file in the parameters of the command executed:

 $ openssl req -x509 -sha256 -nodes -days 1826 -newkey rsa:2048 -config YOUR_SSL_CONFIG_FILE.cnf -keyout NEW_SERVER_KEY.key -out NEW_SERVER_CERT.crt

Creating PKCS

If you need to create PKCS file from the cert/key pair you can use this command:

 openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

Certs for use with HTTPS

If you need to create a key and certificate for use with https, then you will not be using a self-signed certificate, you will need to generate a key and a certificate signing request.

To generate the key and signing request, use this command:

 openssl req -nodes -sha256 -newkey rsa:2048 -keyout myserver.key -out server.csr

After doing the above you will be prompted for details:

 What you are about to enter is what is called a Distinguished Name or a DN.
 There are quite a few fields but you can leave some blank
 For some fields there will be a default value,
 If you enter '.', the field will be left blank.
 -----
 Country Name (2 letter code) [AU]:US
 State or Province Name (full name) [Some-State]:Georgia
 Locality Name (eg, city) []:Atlanta
 Organization Name (eg, company) [Internet Widgits Pty Ltd]:Georgia Tech
 Organizational Unit Name (eg, section) []:GTRI-IEAD
 Common Name (e.g. server FQDN or YOUR name) []:this-must-match-your-url.tld
 Email Address []:help@gfipm.net

The bolded line above is critical (Common Name). If you do not populate that line with the domain name of your https server, users will be prompted with confusing security alerts by browsers. Make sure you get that name exactly right. You may also specify *.[your-domain] for a wildcard certificate.