# OpenSSL Command help This file shows the OpenSSL operations you are most likely to use. It is in no way a complete guide. ## Complexity OpenSSL is a very versatile and complex application. If you just want to create certificates for yourself or your organization, check out mobile-ca ([Binary](https://github.com/AyrA/mobile-ca/releases), [Source](https://github.com/AyrA/mobile-ca)), a portable, free and open source application to manage a tiny CA with certificates and keys. ## General info - OpenSSL usually works with certificates and keys in ASCII format which means you can open them in a text editor if you wish to inspect them. - P12 and PFX files are interchangeable in all commands that want such a file as input/output. - This guide works for Windows and Linux. ## Private key issues private keys can be a bit fiddly to work with ### Password protection If you want full unattended startup of your SSL secured services do not encrypt the private key. Encrypting the private key requires you to enter the password during each start of said services. You can encrypt the key if you are allowed to specify the password in the config file or as command line argument. Make sure said config file is protected well. Encrypted keys are useless if the password is obtainable. ### Key not accepted If the private key is not accepted, SSL negotiation fails or your service won't start after installing the certificate, open the private key file and look at the header and footer. The header will be `-----BEGIN RSA PRIVATE KEY-----` and the footer `-----END RSA PRIVATE KEY-----` with `RSA` not necessarily being present. Some services want the word `RSA` present and some do not. Try to add/remove it and then test again. - Always restart the service to be sure the new key is used. - Always add/remove it on header **and** footer. ## PFX PFX files are used on windows and are the standard way to combine keys and certificate. You usually need PFX keys if you run windows specific software, for example the IIS web server. They either have the extension `.pfx` or `.p12` Application that depend on OpenSSL usually use the PEM key format. ### Export private key from existing pfx file Export the key unencrypted: openssl pkcs12 -in yourP12File.pfx -nocerts -nodes -out privateKey.pem Export the key encrypted: openssl pkcs12 -in yourP12File.pfx -nocerts -out privateKey.pem Both commands will ask you for the private key password. The second command will also ask for the password to encrypt the exported key again. Both passwords can be identical if you wish. ### Create pfx file from existing keys To add intermediate certificates, just chain them into a single file with your certificate on the top and the chain following in proper ordering. Adding the Root CA is usually not required and is frowned upon, simply because clients ignore the root certificate which makes it unneeded payload during the SSL handshake. It will not generate SSL errors if it is included though. To build the chain: cat your.cer intermediate.cer root.cer > bundle.cer On Windows, use `type` instead of `cat`. Depending on your CA, you might have multiple intermediate certificates. To combine the chain with a private key into a pfx file, do this: openssl pkcs12 -export -in bundle.cer -inkey privateKey.pem -out bundle.pfx You will be required to enter a password. Some applications will not read PFX files with an empty password. **Note**: Including other certificates is not required for a working PFX but it is recommended if you use the PFX in a service like Microsoft IIS. If you don't supply the intermediate certificate the client has to check his certificate store and if it is missing (even if the root is present and valid) you will get an SSL error. To create a pfx for legacy Windows systems (Windows 7 or older, Server 2008 R2 or older) add the following arguments after the "-export" argument: -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -nomac ### Export public certificate from pfx file Requires the PFX file password. Software that uses OpenSSL wants the public key in this X.509 format. It contains the public key plus the information about the certificate itself: openssl pkcs12 -in yourP12File.pfx -clcerts -nokeys -out publicCert.pem ### Export public key from pfx file Requires the PFX file password. This exports only the public key from a pfx file, not the certificate information. You need this if you want to encrypt something with a certificate or verify a file signature: openssl pkcs12 -in yourP12File.pfx -clcerts -nokeys | openssl x509 -pubkey -noout > publicKey.pem ## Private Key Encryption ### Encrypt existing private key This will encrypt an existing key using 3DES. Check the "Create Private Key" chapter further below for other algorithms. Most applications, that demand an encrypted key, want it this way: openssl rsa -des3 -in your.key -out your.encrypted.key Don't forget to securely delete the unencrypted version if it is no longer needed. **NOTE**: This method can also be used to directly convert an encrypted key into another encrypted format. You don't need to decrypt it first. ### Decrypt existing private key This will decrypt a private key, which allows applications to start without a key password. openssl rsa -nodes -in your.key -out your.encrypted.key ## Extracting Public Keys You can extract public keys from any certificate or from a private key. ### Export public key from public certificate part This works for any public certificate: openssl x509 -pubkey -noout > publicKey.pem < public.cer ### Export public key from private key If you ever lose the public key, this can recreate it: openssl rsa -in privateKey.pem -pubout **Note:** "Recreate" is wrong in this context, you will get the proper public key with this command though. Reason for this is that the private key contains all the information needed to create the public key, which is the reason why it is bigger. You **will not** be able to get the certificate from it, just the public key needed for encryption and signature verification. ## Convert key formats Keys can be in ASCII or binary form. Sometimes applications only accept one form. If in doubt, go with ASCII (PEM). ### Public Keys If you need to convert a key or certificate from one type to another: openssl x509 -in input.crt -inform PEM -out output.crt -outform DER ### Private Keys For key conversion, use `rsa` instead of `x509`: openssl rsa -in input.key -inform PEM -out output.key -outform DER ### Bidirectional Conversion You can freely transform from DER to PEM and vice versa. - **PEM**: ASCII encoded (readable in text editor). Used by Linux services. - **DER**: Binary encoded. Used by Windows services that don't want a PFX. **Note**: Applications that are designed to run on both platforns (Windows and Linux) usually want PEM format. ## Creating Keys and certificates OpenSSL can be used to create a wide variety of keys ### Create custom DH params openssl dhparam -out dh.pem 2048 You can replace `2048` with `1024` if you use old software or with `4096` for extra security. With higher numbers, this process runs longer. 4096 took about half an hour on a decent machine. The process is entirely luck based and running this command multiple times will yield different results each time. You might get lucky and calculate the correct values within seconds. If you plan on doing this often I recommend setting up some sort of automated processing, where a directory is constantly filled with up to 10 files (or more if you need more). If you want to deploy a custom dhparam file, this should be individual to each installation. Custom DH params prevent certain attacks on some secured connections. Only the server needs custom DH feature support. ### Create private key Creates an unencrypted private key: openssl genrsa -out private.key 4096 To add encryption, supply one of these arguments between the file name and key size: `-des`, `-des3`, `-idea`, `-aes128`, `-aes192`, `-aes256` Please note that some applications only support `-des3` mode. Check the "Encrypt Private key" chapter above to encrypt the private key in another format if needed. The key can be used to derive a public key from it (described in a previous chapter). You can use the public and private keys as-is for encryption and signing. ### Create new (self-signed) certificate for server authentication You are asked for various information during the `openssl req` command, including the domain which the certificate is to be used for. Most of the questions will have a default in square brackets that is used if you don't provide a value: openssl genrsa -out private.key 4096 openssl req -new -key private.key -out request.csr openssl x509 -req -days 3650 -in request.csr -signkey private.key -out public.crt **Note**: Nobody will trust this certificate. To become trusted, it has to be installed in the trusted root certificate store. ### Request a certificate from a 3rd party This is identical to the "Create new certificate" chapter above but you do not perform the 3rd step (the CA does). The csr file is what you will be asked to either upload or paste into a text box. Depending on the validation type some fields might be required, some will be ignored and some replaced by the CA. If approved you will get the public certificate as answer. **Never ever provide the private key**. A proper CA will not need the private key at all. Some CAs have an online key generator for it which I personally recommend against using. #### Private key and request file. When you renew an expiring certificate you need those two so **don't delete them**. You sometimes need to go through the entire validation again if you lose the private key and sometimes the CSR.