OpenSSL Command-Line HOWTO
Paul Heinlein
First published on June 13, 2004
Last updated on May 3, 2024
Contents
Introduction
Theopenssl command-line binary that ships with theOpenSSL libraries can perform a wide range ofcryptographic operations. It can come in handy in scripts or foraccomplishing one-time command-line tasks.
Documentation for using theopenssl application is somewhat scattered,however, so this article aims to provide some practical examples of itsuse. I assume that you’ve already got a functional OpenSSL installationand that theopenssl binary is in your shell’s PATH.
Just to be clear, this article is strictly practical; it does notconcern cryptographic theory and concepts. If you don’t know what an MD5sum is, this article won’t enlighten you one bit—but if all you need toknow is how to useopenssl to generate a file sum,you’re inluck.
The nature of this article is that I’ll be adding new examplesincrementally. Check back at a later date if I haven’t gotten to theinformation you need.
How do I find out what OpenSSL version I’m running?
Use theversion option.
$ openssl versionOpenSSL 1.0.1e-fips 11 Feb 2013You can get much more information with theversion -a option.
$ openssl version -aOpenSSL 1.0.1e-fips 11 Feb 2013built on: Thu Jul 23 19:06:35 UTC 2015platform: linux-x86_64options: bn(64,64) md2(int) rc4(16x,int) des(idx,cisc,16,int) idea(int) blowfish(idx)compiler: gcc -fPIC -DOPENSSL_PIC -DZLIB -DOPENSSL_THREADS -D_REENTRANT-DDSO_DLFCN -DHAVE_DLFCN_H -DKRB5_MIT -m64 -DL_ENDIAN -DTERMIO-Wall -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions-fstack-protector --param=ssp-buffer-size=4 -m64 -mtune=generic-Wa,--noexecstack -DPURIFY -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT-DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM-DSHA512_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM-DWHIRLPOOL_ASM -DGHASH_ASMOPENSSLDIR: "/etc/pki/tls"engines: rdrand dynamicHow do I get a list of the available commands?
There are three built-in options for getting lists of availablecommands, but none of them provide what I consider useful output. Thebest thing to do is provide an invalid command (help or-h will donicely) to get a readable answer.
$ openssl helpopenssl:Error: 'help' is an invalid command.Standard commandsasn1parse ca ciphers cmscrl crl2pkcs7 dgst dhdhparam dsa dsaparam ececparam enc engine errstrgendh gendsa genpkey genrsanseq ocsp passwd pkcs12pkcs7 pkcs8 pkey pkeyparampkeyutl prime rand reqrsa rsautl s_client s_servers_time sess_id smime speedspkac ts verify versionx509Message Digest commands (see the `dgst' command for more details)md2 md4 md5 rmd160sha sha1Cipher commands (see the `enc' command for more details)aes-128-cbc aes-128-ecb aes-192-cbc aes-192-ecbaes-256-cbc aes-256-ecb base64 bfbf-cbc bf-cfb bf-ecb bf-ofbcamellia-128-cbc camellia-128-ecb camellia-192-cbc camellia-192-ecbcamellia-256-cbc camellia-256-ecb cast cast-cbccast5-cbc cast5-cfb cast5-ecb cast5-ofbdes des-cbc des-cfb des-ecbdes-ede des-ede-cbc des-ede-cfb des-ede-ofbdes-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofbdes-ofb des3 desx ideaidea-cbc idea-cfb idea-ecb idea-ofbrc2 rc2-40-cbc rc2-64-cbc rc2-cbcrc2-cfb rc2-ecb rc2-ofb rc4rc4-40 seed seed-cbc seed-cfbseed-ecb seed-ofb zlibWhat the shell calls “Standard commands” are the main top-level options.
You can use the same trick with any of the subcommands.
$ openssl dgst -hunknown option '-h'options are-c to output the digest with separating colons-r to output the digest in coreutils format-d to output debug info-hex output as hex dump-binary output in binary form-sign file sign digest using private key in file-verify file verify a signature using public key in file-prverify file verify a signature using private key in file-keyform arg key file format (PEM or ENGINE)-out filename output to filename rather than stdout-signature file signature to verify-sigopt nm:v signature parameter-hmac key create hashed MAC with key-mac algorithm create MAC (not neccessarily HMAC)-macopt nm:v MAC algorithm parameters or key-engine e use engine e, possibly a hardware device.-md4 to use the md4 message digest algorithm-md5 to use the md5 message digest algorithm-ripemd160 to use the ripemd160 message digest algorithm-sha to use the sha message digest algorithm-sha1 to use the sha1 message digest algorithm-sha224 to use the sha224 message digest algorithm-sha256 to use the sha256 message digest algorithm-sha384 to use the sha384 message digest algorithm-sha512 to use the sha512 message digest algorithm-whirlpool to use the whirlpool message digest algorithmIn more boring fashion, you can consult theOpenSSL man pages.
How do I get a list of available ciphers?
Use theciphers option. Theciphers(1) man page isquite helpful.
# list all available ciphersopenssl ciphers -v# list only TLSv1 ciphersopenssl ciphers -v -tls1# list only high encryption ciphers (keys larger than 128 bits)openssl ciphers -v'HIGH'# list only high encryption ciphers using the AES algorithmopenssl ciphers -v'AES+HIGH'Benchmarking
How do I benchmark my system’s performance?
The OpenSSL developers have built a benchmarking suite directly into theopenssl binary. It’s accessible via thespeed option. It tests howmany operations it can perform in a given time, rather than how long ittakes to perform a given number of operations. This strikes me as quitesane, because the benchmarks don’t take significantly longer to run on aslow system than on a fast one.
To run a catchall benchmark, run it without any further options.
openssl speedThere are two sets of results. The first reports how many bytes persecond can be processed for each algorithm, the second the times neededfor sign/verify cycles. Here are the results on an 2.70GHz Intel Xeon E5.
The 'numbers' are in 1000s of bytes per second processed.type 16 bytes 64 bytes 256 bytes 1024 bytes 8192 bytesmd2 2540.48k 5184.66k 6989.57k 7651.67k 7872.51kmdc2 0.00 0.00 0.00 0.00 0.00md4 83248.41k 261068.18k 624212.82k 940529.32k 1128846.68kmd5 62411.57k 184768.36k 408835.75k 586930.52k 678061.98khmac(md5) 48713.62k 148265.56k 359626.67k 563050.68k 670255.79ksha1 68829.72k 195087.40k 431001.51k 623344.42k 729505.79krmd160 38598.59k 96226.86k 183336.45k 235962.71k 257526.44krc4 480093.57k 678565.35k 783765.42k 818297.51k 838205.99kdes cbc 69500.17k 71184.75k 71491.50k 71641.77k 72010.15kdes ede3 26433.63k 26717.01k 26772.99k 26788.18k 26907.57kidea cbc 95690.28k 99334.17k 100835.40k 100787.54k 100900.86kseed cbc 76871.40k 77238.46k 77736.50k 77452.97k 77545.47krc2 cbc 48984.63k 49589.03k 50188.07k 50103.98k 50066.77krc5-32/12 cbc 0.00 0.00 0.00 0.00 0.00blowfish cbc 122583.30k 129550.92k 130876.67k 131111.94k 131394.22kcast cbc 109471.38k 114523.31k 115934.46k 116200.45k 116331.86kaes-128 cbc 128352.23k 138604.76k 141173.42k 142832.25k 142682.79kaes-192 cbc 107703.93k 114456.79k 117716.65k 118847.36k 118784.00kaes-256 cbc 93374.87k 99521.51k 101198.51k 101382.49k 101635.41kcamellia-128 cbc 99270.57k 150412.42k 170346.33k 176311.91k 177913.86kcamellia-192 cbc 85896.60k 117356.52k 128556.97k 132759.72k 133425.83kcamellia-256 cbc 87351.27k 117695.15k 128972.03k 132130.47k 133455.87ksha256 52372.61k 117766.12k 204825.69k 249974.10k 270914.90ksha512 41278.19k 165820.37k 258298.69k 365981.70k 419864.58kwhirlpool 24803.02k 53047.07k 87593.90k 104570.54k 111159.98kaes-128 ige 128441.31k 132981.88k 133269.08k 133738.15k 133966.51kaes-192 ige 107831.37k 111507.07k 111800.66k 112156.67k 112219.48kaes-256 ige 94382.07k 96351.17k 96750.68k 96958.46k 97446.44kghash 888644.92k 1452788.80k 1696788.74k 1763055.96k 1799086.49k sign verify sign/s verify/srsa 512 bits 0.000049s 0.000004s 20547.1 248266.2rsa 1024 bits 0.000194s 0.000011s 5146.0 90735.4rsa 2048 bits 0.001194s 0.000037s 837.3 27277.1rsa 4096 bits 0.008560s 0.000137s 116.8 7324.5 sign verify sign/s verify/sdsa 512 bits 0.000048s 0.000046s 20667.7 21701.8dsa 1024 bits 0.000113s 0.000126s 8831.9 7951.8dsa 2048 bits 0.000362s 0.000430s 2762.0 2322.9 sign verify sign/s verify/s 256 bit ecdsa (nistp256) 0.0001s 0.0004s 9856.1 2524.4 384 bit ecdsa (nistp384) 0.0002s 0.0008s 5103.6 1191.7 521 bit ecdsa (nistp521) 0.0004s 0.0018s 2679.0 550.3 op op/s 256 bit ecdh (nistp256) 0.0003s 3063.8 384 bit ecdh (nistp384) 0.0007s 1447.3 521 bit ecdh (nistp521) 0.0015s 666.2You can run any of the algorithm-specific subtests directly.
# test rsa speedsopenssl speed rsa# do the same test on a two-way SMP systemopenssl speed rsa -multi2How do I benchmark remote connections?
Thes_time option lets you test connection performance. The mostsimple invocation will run for 30 seconds, use any cipher, and use SSLhandshaking to determine number of connections per second, using bothnew and reused sessions:
openssl s_time -connect remote.host:443Beyond that most simple invocation,s_time gives you a wide variety oftesting options.
# retrieve remote test.html page using only new sessionsopenssl s_time -connect remote.host:443 -www /test.html -new# similar, using only SSL v3 and high encryption (see# ciphers(1) man page for cipher strings)openssl s_time\ -connect remote.host:443 -www /test.html -new\ -ssl3 -cipher HIGH# compare relative performance of various ciphers in# 10-second testsIFS=":"for c in$(openssl ciphers -ssl3 RSA);doecho$c openssl s_time -connect remote.host:443\ -www / -new -time10 -cipher$c 2>&1|\ grep bytesechodoneIf you don’t have an SSL-enabled web server available for your use, youcan emulate one using thes_server option.
# on one host, set up the server (using default port 4433)openssl s_server -cert mycert.pem -www# on second host (or even the same one), run s_timeopenssl s_time -connect myhost:4433 -www / -new -ssl3Certificates
How do I generate a self-signed certificate?
You’ll first need to decide whether or not you want to encrypt your key.Doing so means that the key is protected by a passphrase.
On the plus side, adding a passphrase to a key makes it more secure, sothe key is less likely to be useful to someone who steals it. Thedownside, however, is that you’ll have to either store the passphrase ina file or type it manually every time you want to start your web or ldapserver.
It violates my normally paranoid nature to say it, but I preferunencrypted keys, so I don’t have to manually type a passphrase eachtime a secure daemon is started. (It’s not terribly difficulttodecrypt your key if you later tire of typing apassphrase.)
This example will produce a file calledmycert.pem which will containboth the private key and the public certificate based on it. Thecertificate will be valid for 365 days, and the key (thanks to the-nodes option) is unencrypted.
openssl req\ -x509 -nodes -days365 -sha256\ -newkey rsa:2048 -keyout mycert.pem -out mycert.pemUsing this command-line invocation, you’ll have to answer a lot ofquestions: Country Name, State, City, and so on. The tricky question is“Common Name.” You’ll want to answer with thehostname or CNAME bywhich people will address the server. This is very important. If yourweb server’s real hostname is mybox.mydomain.com but people will beusingwww.mydomain.com to address the box, then use the latter name toanswer the “Common Name” question.
Once you’re comfortable with the answers you provide to those questions,you can script the whole thing by adding the-subj option. I’veincluded some information about location into the example that follows,but the only thing you really need to include for the certificate to beuseful is the hostname (CN).
openssl req\ -x509 -nodes -days365 -sha256\ -subj'/C=US/ST=Oregon/L=Portland/CN=www.madboa.com'\ -newkey rsa:2048 -keyout mycert.pem -out mycert.pemHow do I generate a certificate request for VeriSign?
Applying for a certificate signed by a recognized certificate authoritylike VeriSign is a complex bureaucratic process. You’ve got to performall the requisite paperwork before creating a certificate request.
As in the recipe forcreating a self-signed certificate,you’ll have to decide whether or not you want a passphrase on yourprivate key. The recipe below assumes you don’t. You’ll end up with twofiles: a new private key calledmykey.pem and a certificate requestcalledmyreq.pem.
openssl req\ -new -sha256 -newkey rsa:2048 -nodes\ -keyout mykey.pem -out myreq.pemIf you’ve alreadygot a key and would like to use it forgenerating the request, the syntax is a bit simpler.
openssl req -new -key mykey.pem -out myreq.pemSimilarly, you can also provide subject information on the command line.
openssl req\ -new -sha256 -newkey rsa:2048 -nodes\ -subj'/CN=www.mydom.com/O=My Dom, Inc./C=US/ST=Oregon/L=Portland'\ -keyout mykey.pem -out myreq.pemWhen dealing with an institution like VeriSign, you need to take specialcare to make sure that the information you provide during the creationof the certificate request isexactly correct. I know from personalexperience that even a difference as trivial as substituting “and” for“&” in the Organization Name will stall the process.
If you’d like, you can double check the signature and informationprovided in the certificate request.
# verify signatureopenssl req -in myreq.pem -noout -verify -key mykey.pem# check infoopenssl req -in myreq.pem -noout -textSave the key file in a secure location. You’ll need it in order to usethe certificate VeriSign sends you. The certificate request willtypically be pasted into VeriSign’s online application form.
How do I test a new certificate?
Thes_server option provides a simple but effective testing method.The example below assumes you’ve combined your key and certificate intoone file calledmycert.pem.
First, launch the test server on the machine on which the certificatewill be used. By default, the server will listen on port 4433; you canalter that using the-accept option.
openssl s_server -cert mycert.pem -wwwIf the server launches without complaint, then chances are good that thecertificate is ready for production use.
You can also point your web browser at the test server,e.g.,https://yourserver:4433/. Don’t forget to specify the “https”protocol; plain-old “http” won’t work. You should see a page listing thevarious ciphers available and some statistics about your connection.Most modern browsers allow you to examine the certificate as well.
How do I retrieve a remote certificate?
If you combineopenssl andsed, you can retrieve remote certificatesvia a shell one-liner or a simple script.
#!/bin/sh## usage: retrieve-cert.sh remote.host.name [port]#REMHOST=$1REMPORT=${2:-443}echo|\openssl s_client -connect${REMHOST}:${REMPORT} 2>&1|\sed -ne'/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'You can, in turn, pipe that information back toopenssl to do thingslike check the dates on all your active certificates.
#!/bin/sh#for CERT in\ www.yourdomain.com:443\ ldap.yourdomain.com:636\ imap.yourdomain.com:993doecho|\ openssl s_client -connect${CERT} 2>/dev/null|\ sed -ne'/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'|\ openssl x509 -noout -subject -datesdoneHow do I extract information from a certificate?
An SSL certificate contains a wide range of information: issuer, validdates, subject, and some hardcore crypto stuff. Thex509 subcommand isthe entry point for retrieving this information. The examples below allassume that the certificate you want to examine is stored in a filenamedcert.pem.
Using the-text option will give you the full breadth of information.
openssl x509 -text -in cert.pemOther options will provide more targeted sets of data.
# who issued the cert?openssl x509 -noout -in cert.pem -issuer# to whom was it issued?openssl x509 -noout -in cert.pem -subject# for what dates is it valid?openssl x509 -noout -in cert.pem -dates# the above, all at onceopenssl x509 -noout -in cert.pem -issuer -subject -dates# what is its hash value?openssl x509 -noout -in cert.pem -hash# what is its MD5 fingerprint?openssl x509 -noout -in cert.pem -fingerprintHow do I export or import a PKCS#12 certificate?
PKCS#12 files can be imported and exported by a number of applications,including Microsoft IIS. They are often associated with the fileextensions.pfx and.p12.
To create a PKCS#12 certificate, you’ll need a private key and acertificate. During the conversion process, you’ll be given anopportunity to put an “Export Password” (which can be empty, if youchoose) on the certificate.
# create a file containing key and self-signed certificateopenssl req\ -x509 -sha256 -nodes -days365\ -newkey rsa:2048 -keyout mycert.pem -out mycert.pem# export mycert.pem as PKCS#12 file, mycert.pfxopenssl pkcs12 -export\ -out mycert.pfx -in mycert.pem\ -name"My Certificate"If someone sends you a PKCS#12 and any passwords needed to work withit, you can export it into standard PEM format.
# export certificate and passphrase-less keyopenssl pkcs12 -in mycert.pfx -out mycert.pem -nodes# same as above, but you’ll be prompted for a passphrase for# the private keyopenssl pkcs12 -in mycert.pfx -out mycert.pemWeb-based consoles for certificate authorities will often compelyou to encrypt keys prior to downloading a requested certificate.At the same time, you might not want to install a PKCS#12 filewith an encrypted key on a given server. Also you might need tochange the “alias” or “name” of a key-certificate pair within theinstalled file.
Here’s a simple pipe that decrypts the key in a downloaded PFX fileand changes the name/alias of the certificate and writes them allto a new PFX/P12 file. The first part of the pipe operation willprompt you to provide the password you set on the downloaded file.
# in this example, the key in the .pfx file is encrypted, while the# key in the resulting .p12 file is notopenssl pkcs12 -nodes -in webhost.my.com.pfx|\openssl pkcs12 -out webhost.my.com.p12 -export -name"ApacheTomcat"Certificate Verification
Applications linked against the OpenSSL libraries can verifycertificates signed by a recognized certificate authority (CA).
How do I verify a certificate?
Use theverify option to verify certificates.
openssl verify cert.pemIf your local OpenSSL installation recognizes the certificate or itssigning authority and everything else (dates, signing chain, etc.)checks out, you’ll get a simple OK message.
$ openssl verify remote.site.pemremote.site.pem: OKIf anything is amiss, you’ll see some error messages with shortdescriptions of the problem,e.g.,
error 10 at 0 depth lookup:certificate has expired. Certificatesare typically issued for a limited period of time—usually just oneyear—andopensslwill complain if a certificate has expired.error 18 at 0 depth lookup:self signed certificate. Unless youmake an exception, OpenSSL won’t verify aself-signed certificate.
What certificate authorities does OpenSSL recognize?
When OpenSSL was built for your system, it was configured with a“Directory for OpenSSL files.” (That’s the--openssldir option passedto the configure script, for you hands-on types.) This is the directorythat typically holds information about certificate authorities yoursystem trusts.
The default location for this directory is/usr/local/ssl, but mostvendors put it elsewhere,e.g.,/usr/share/ssl (Red Hat/Fedora),/etc/ssl (Gentoo),/usr/lib/ssl (Debian), or/System/Library/OpenSSL (Macintosh OS X).
Use theversion option to identify which directory (labeledOPENSSLDIR) your installation uses.
openssl version -dWithin that directory and a subdirectory calledcerts, you’re likelyto find one or more of three different kinds of files.
A large file called
cert.pem, an omnibus collection of manycertificates from recognized certificate authorities like VeriSignand Thawte.Some small files in the
certssubdirectory named with a.pemfile extension, each of which contains a certificate from a singleCA.Some symlinks in the
certssubdirectory with obscure filenameslike052eae11.0. There is typically one of these links for each.pemfile.The first part of obscure filename is actually a hash value based onthe certificate within the
.pemfile to which it points. The fileextension is just an iterator, since it’s theoretically possiblethat multiple certificates can generate identical hashes.On my Gentoo system, for example, there’s a symlink named
f73e89fd.0that points to a file namedvsignss.pem. Sure enough,the certificate in that file generates a hash the equates to thename of the symlink:
$ openssl x509 -noout -hash -in vsignss.pemf73e89fdWhen an application encounters a remote certificate, it will typicallycheck to see if the cert can be found incert.pem or, if not, in afile named after the certificate’s hash value. If found, the certificateis considered verified.
It’s interesting to note that some applications, like Sendmail, allowyou to specify at runtime the location of the certificates you trust,while others, like Pine, do not.
How do I get OpenSSL to recognize/verify a certificate?
Put the file that contains the certificate you’d like to trust into thecerts directory discussedabove. Then create thehash-based symlink. Here’s a little script that’ll do just that.
#!/bin/sh## usage: certlink.sh filename [filename ...]for CERTFILE in$*;do# make sure file exists and is a valid certtest -f"$CERTFILE"||continueHASH=$(openssl x509 -noout -hash -in"$CERTFILE")test -n"$HASH"||continue# use lowest available iterator for symlinkfor ITER in012345678 9;dotest -f"${HASH}.${ITER}"&&continue ln -s"$CERTFILE""${HASH}.${ITER}"test -L"${HASH}.${ITER}"&&breakdonedoneCommand-line clients and servers
Thes_client ands_server options provide a way to launchSSL-enabled command-line clients and servers. There are other examplesof their use scattered around this document, but this section isdedicated solely to them.
In this section, I assume you are familiar with the specific protocolsat issue: SMTP, HTTP, etc. Explaining them is out of the scope of thisarticle.
How do I connect to a secure SMTP server?
You can test, or even use, an SSL-enabled SMTP server from the commandline using thes_client option.
Secure SMTP servers offer secure connections on up to three ports: 25(TLS), 465 (SSL), and 587 (TLS). Some time around the 0.9.7 release, theopenssl binary was given the ability to use STARTTLS when talking toSMTP servers.
# port 25/TLS; use same syntax for port 587openssl s_client -connect remote.host:25 -starttls smtp# port 465/SSLopenssl s_client -connect remote.host:465RFC821 suggests (although itfalls short of explicitly specifying) the two characters “<CRLF>” asline-terminator. Most mail agents do not care about this and accepteither “<LF>” or “<CRLF>” as line-terminators, but Qmail does not.If you want to comply to the letter with RFC821 and/or communicate withQmail, use also the-crlf option:
openssl s_client -connect remote.host:25 -crlf -starttls smtpHow do I connect to a web server using SNI?
The shortage of IPv4 addresses prompted the development of the HTTP 1.1standard so a single IP address could host multiple name-based virtualservers.
Later, that same shortage of addresses led to the development oftheServer NameIndication(SNI) extension of the TLS protocol. When using SNI, the clientsends the hostname it wants to contact during the TLS negotiation.An SNI-enabled server is then able to offer the certificate withthe matching hostname for the client to verify.
SNI is enabled inopenssl by specifying the-servername option.
openssl s_client -connect www.massivehost.com:443 -servername www.myhost.comHow do I connect to a secure [whatever] server?
Connecting to a different type of SSL-enabled server is essentially thesame operation as outlined above. As of the date of this writing,openssl only supports command-line TLS with SMTP servers, so you haveto use straightforward SSL connections with any other protocol.
# https: HTTP over SSLopenssl s_client -connect remote.host:443# ldaps: LDAP over SSLopenssl s_client -connect remote.host:636# imaps: IMAP over SSLopenssl s_client -connect remote.host:993# pop3s: POP-3 over SSLopenssl s_client -connect remote.host:995How do I set up an SSL server from the command line?
Thes_server option allows you to set up an SSL-enabled server fromthe command line, but it’s I wouldn’t recommend using it for anythingother than testing or debugging. If you need a production-qualitywrapper around an otherwise insecure server, check outStunnel instead.
Thes_server option works best when you have a certificate; it’sfairly limited without one.
# the -www option will sent back an HTML-formatted status page# to any HTTP clients that request a pageopenssl s_server -cert mycert.pem -www# the -WWW option "emulates a simple web server. Pages will be# resolved relative to the current directory." This example# is listening on the https port, rather than the default# port 4433openssl s_server -accept443 -cert mycert.pem -WWWDigests
Generating digests with thedgst option is one of the morestraightforward tasks you can accomplish with theopenssl binary.Producing digests is done so often, as a matter of fact, that you canfind special-use binaries for doing the same thing.
How do I create an MD5 or SHA1 digest of a file?
Digests are created using thedgst option. I’ve seen severalsystems on which the OpenSSLdgst(1) manpage does not accurately report the digest functions available viathe localopenssl binary. I suggest runningopenssl dgst -h tosee which digests are actually available.
# MD5 digestopenssl dgst -md5 filename# SHA1 digestopenssl dgst -sha1 filename# SHA256 digestopenssl dgst -sha256 filenameThe MD5 digests are identical to those created with the widely availablemd5sum command, though the output formats differ.
$ openssl dgst -md5 foo-2.23.tar.gzMD5(foo-2.23.tar.gz)= 81eda7985e99d28acd6d286aa0e13e07$ md5sum foo-2.23.tar.gz81eda7985e99d28acd6d286aa0e13e07 foo-2.23.tar.gzThe same is true for SHA1 digests and the output of thesha1sumapplication.
$ openssl dgst -sha1 foo-2.23.tar.gzSHA1(foo-2.23.tar.gz)= e4eabc78894e2c204d788521812497e021f45c08$ sha1sum foo-2.23.tar.gze4eabc78894e2c204d788521812497e021f45c08 foo-2.23.tar.gzHow do I sign a digest?
If you want to ensure that the digest you create doesn’t get modifiedwithout your permission, you can sign it using yourprivatekey. The following example assumes that you want to sign theSHA256 sum of a file calledfoo-1.23.tar.gz.
# signed digest will be foo-1.23.tar.gz.sha1openssl dgst -sha256\ -sign mykey.pem -out foo-1.23.tar.gz.sha1\ foo-1.23.tar.gzHow do I verify a signed digest?
To verify a signed digest you’ll need the file from which the digest wasderived, the signed digest, and the signer’spublickey.
# to verify foo-1.23.tar.gz using foo-1.23.tar.gz.sha1# and pubkey.pemopenssl dgst -sha256\ -verify pubkey.pem\ -signature foo-1.23.tar.gz.sha1\ foo-1.23.tar.gzHow do I create an Apache digest password entry?
Apache’s HTTP digest authentication feature requires a special passwordformat. Apache ships with thehtdigest utility, but it will only writeto a file, not to standard output. When working with remote users, it’ssometimes nice for them to be able to generate a password hash on amachine they trust and then mail it for inclusion in your local passworddatabase.
The format of the password database is relatively simple: acolon-separated list of the username, authorization realm (specified bythe Apache AuthName directive), and an MD5 digest of those two items andthe password. Below is a script that duplicates the output ofhtdigest, except that the output is written to standard output. Ittakes advantage of thedgst option’s ability to read from standardinput.
#!/bin/bashecho"Create an Apache-friendly Digest Password Entry"echo"-----------------------------------------------"# get user input, disabling tty echoing for passwordread -p"Enter username: " UNAMEread -p"Enter Apache AuthName: " AUTHNAMEread -s -p"Enter password: " PWORD;echoprintf"\n%s:%s:%s\n"\"$UNAME"\"$AUTHNAME"\$(printf"${UNAME}:${AUTHNAME}:${PWORD}"| openssl dgst -md5)What other kinds of digests are available?
Use the built-inlist-message-digest-commands option to get a list ofthe digest types available to your local OpenSSL installation.
openssl list-message-digest-commandsLike the list in the dgst(1) man page, this list may be outdated.Let the buyer beware!
Encryption/Decryption
How do I base64-encode something?
Use theenc -base64 option.
# send encoded contents of file.txt to stdoutopenssl enc -base64 -in file.txt# same, but write contents to file.txt.encopenssl enc -base64 -in file.txt -out file.txt.encIt’s also possible to do a quick command-line encoding of a stringvalue:
$ echo "encode me" | openssl enc -base64ZW5jb2RlIG1lCg==Note thatecho will silently attach a newline character to yourstring. Consider using its-n option if you want to avoid thatsituation, which could be important if you’re trying to encode apassword or authentication string.
$ echo -n "encode me" | openssl enc -base64ZW5jb2RlIG1lUse the-d (decode) option to reverse the process.
$ echo "ZW5jb2RlIG1lCg==" | openssl enc -base64 -dencode meHow do I simply encrypt a file?
Simple file encryption is probably better done using atool likeGPG. Still, you may have occasion to want toencrypt a file without having to build or use a key/certificatestructure. All you want to have to remember is a password. It can nearlybe that simple—if you can also remember the cipher you employed forencryption.
To choose a cipher, consult theenc(1) manpage. More simply (andperhaps more accurately), you can askopenssl for a list in one of twoways.
# see the list under the 'Cipher commands' headingopenssl -h# or get a long list, one cipher per lineopenssl list-cipher-commandsAfter you choose a cipher, you’ll also have to decide if you want tobase64-encode the data. Doing so will mean the encrypted data can be,say, pasted into an email message. Otherwise, the output will be abinary file.
# encrypt file.txt to file.enc using 256-bit AES in CBC modeopenssl enc -aes-256-cbc -salt -in file.txt -out file.enc# the same, only the output is base64 encoded for, e.g., e-mailopenssl enc -aes-256-cbc -a -salt -in file.txt -out file.encTo decryptfile.enc you or the file’s recipient will need to rememberthe cipher and the passphrase.
# decrypt binary file.encopenssl enc -d -aes-256-cbc -in file.enc# decrypt base64-encoded versionopenssl enc -d -aes-256-cbc -a -in file.encIf you’d like to avoid typing a passphrase every time you encrypt ordecrypt a file, the openssl(1) man page provides the details under theheading “PASS PHRASE ARGUMENTS.” The format of the password argument isfairly simple.
# provide password on command lineopenssl enc -aes-256-cbc -salt -in file.txt\ -out file.enc -pass pass:mySillyPassword# provide password in a fileopenssl enc -aes-256-cbc -salt -in file.txt\ -out file.enc -pass file:/path/to/secret/password.txtErrors
How do I interpret SSL error messages?
Poking through your system logs, you see some error messages that areevidently related to OpenSSL or crypto:
sshd[31784]: error: RSA_public_decrypt failed: error:0407006A:lib(4):func(112):reason(106)sshd[770]: error: RSA_public_decrypt failed: error:0407006A:lib(4):func(112):reason(106)The first step to figure out what’s going wrong is to use theerrstroption to intrepret the error code. The code number is found between“error:” and “:lib”. In this case, it’s 0407006A.
$ openssl errstr 0407006Aerror:0407006A:rsa routines:RSA_padding_check_PKCS1_type_1:block type is not 01If you’ve got a full OpenSSL installation, including all the developmentdocumentation, you can start your investigation there. In this example,the RSA_padding_add_PKCS1_type_1(3) man page will inform you thatPKCS #1 involves block methods for signatures. After that, of course,you’d need to pore through your application’s source code to identifywhen it would expect be receiving those sorts of packets.
Keys
How do I generate an RSA key?
Use thegenrsa option.
# default 1024-bit key, sent to standard outputopenssl genrsa# 2048-bit key, saved to file named mykey.pemopenssl genrsa -out mykey.pem2048# same as above, but encrypted with a passphraseopenssl genrsa -des3 -out mykey.pem2048How do I generate a public RSA key?
Use thersa option to produce a public version of your private RSAkey.
openssl rsa -in mykey.pem -puboutHow do I generate a DSA key?
Building DSA keys requires a parameter file, and DSA verify operationsare slower than their RSA counterparts, so they aren’t as widely used asRSA keys.
If you’re only going to build a single DSA key, you can do so in justone step using thedsaparam subcommand.
# key will be called dsakey.pemopenssl dsaparam -noout -out dsakey.pem -genkey1024If, on the other hand, you’ll be creating several DSA keys, you’llprobably want to build a shared parameter file before generating thekeys. It can take a while to build the parameters, but once built, keygeneration is done quickly.
# create parameters in dsaparam.pemopenssl dsaparam -out dsaparam.pem1024# create first keyopenssl gendsa -out key1.pem dsaparam.pem# and second ...openssl gendsa -out key2.pem dsaparam.pemHow do I create an elliptic curve key?
Routines for working withelliptic curvecryptography were added to OpenSSL in version0.9.8. Generating an EC key involves theecparam option.
openssl ecparam -out key.pem -name prime256v1 -genkey# openssl can provide full list of EC parameter names suitable for# passing to the -name option above:openssl ecparam -list_curvesHow do I remove a passphrase from a key?
Perhaps you’ve grown tired of typing your passphrase every time yoursecure daemon starts. You can decrypt your key, removing the passphraserequirement, using thersa ordsa option, depending on the signaturealgorithm you chose when creating your private key.
If you created an RSA key and it is stored in a standalone file calledkey.pem, then here’s how to output a decrypted version of the same keyto a file callednewkey.pem.
# you'll be prompted for your passphrase one last timeopenssl rsa -in key.pem -out newkey.pemOften, you’ll have your private key and public certificate stored in thesame file. If they are stored in a file calledmycert.pem, you canconstruct a decrypted version callednewcert.pem in two steps.
# you'll need to type your passphrase once moreopenssl rsa -in mycert.pem -out newcert.pemopenssl x509 -in mycert.pem >>newcert.pemPassword hashes
Using thepasswd option, you can generate password hashes thatinteroperate with traditional/etc/passwd files, newer-style/etc/shadow files, and Apache password files.
How do I generate a crypt-style password hash?
You can generate a new hash quite simply:
$ openssl passwd MySecret8E4vqBR4UOYF.If you know an existing password’s “salt,” you can duplicate the hash.
$ openssl passwd -salt 8E MySecret8E4vqBR4UOYF.How do I generate a shadow-style password hash?
Newer Unix systems use a more secure MD5-based hashing mechanism thatuses an eight-character salt (as compared to the two-character salt intraditional crypt()-style hashes). Generating them is stillstraightforward using the-1 option:
$ openssl passwd -1 MySecret$1$sXiKzkus$haDZ9JpVrRHBznY5OxB82.The salt in this format consists of the eight characters between thesecond and third dollar signs, in this casesXiKzkus. So you can alsoduplicate a hash with a known salt and password.
$ openssl passwd -1 -salt sXiKzkus MySecret$1$sXiKzkus$haDZ9JpVrRHBznY5OxB82.Prime numbers
Current cryptographic techniques rely heavily on the generation andtesting of prime numbers, so it’s no surprise that the OpenSSL librariescontain several routines dealing with primes. Beginning with version0.9.7e (or so), theprime option was added to the openssl binary.
How do I test whether a number is prime?
Pass the number to theprime option. Note that the number returned byopenssl will be in hex, not decimal, format.
$ openssl prime 1190547592454607531A6F7AC39A53511 is not primeYou can also pass hex numbers directly.
$ openssl prime -hex 2f2F is primeHow do I generate a set of prime numbers?
Starting with OpenSSL version 1.0.0, the openssl binary can generateprime numbers of a specified length:
$ openssl prime -generate -bits 6416148891040401035823$ openssl prime -generate -bits 64 -hexE207F23B9AE52181If you’re using a version of OpenSSL older than 1.0.0, you’ll have topass a bunch of numbers to openssl and see what sticks. Thesequtility is useful in this capacity.
# define start and ending pointsAQUO=10000ADQUEM=10100for N in$(seq$AQUO$ADQUEM);do# use bc to convert hex to decimal openssl prime$N| awk'/is prime/ {print "ibase=16;"$1}'| bcdoneRandom data
How do I generate random data?
Use therand option to generate binary or base64-encoded data.
# write 128 random bytes of base64-encoded data to stdoutopenssl rand -base64128# write 1024 bytes of binary random data to a fileopenssl rand -out random-data.bin1024# seed openssl with semi-random bytes from browser cachecd$(find ~/.mozilla/firefox -type d -name Cache)openssl rand -rand$(find . -type f -printf'%f:') -base641024On a Unix box with a/dev/urandom device and a copy of GNUhead, ora recent version of BSDhead, you can achieve a similar effect, oftenwith better entropy:
# get 32 bytes from /dev/urandom and base64 encode themhead -c32 /dev/urandom| openssl enc -base64You can get a wider variety of characters than what’s offered usingBase64 encoding by usingstrings:
# get 32 bytes from /dev/random, grab printable characters, and# strip whitespace. using echo and the shell's command substitution# will nicely strip out newlines.echo$(head -c32 /dev/random| strings -1)| sed's/[[:space:]]//g'Make sure you know the trade-offs between therandom andurandomdevices before relying on them for truly critical entropy. Consult therandom(4) man page on Linux and BSD systems, or random(7D) on Solaris,for further information.
S/MIME
S/MIME is astandard for sending and receiving secure MIME data, especially ine-mail messages. Automated S/MIME capabilities have been added to quitea few e-mail clients, thoughopenssl can provide command-line S/MIMEservices using thesmime option.
Note that the documentation in thesmime(1) man pageincludes a number of good examples.
How do I verify a signed S/MIME message?
It’s pretty easy to verify a signed message. Use your mail client tosave the signed message to a file. In this example, I assume that thefile is namedmsg.txt.
openssl smime -verify -in msg.txtIf the sender’s certificate is signed by a certificate authority trustedby your OpenSSL infrastructure, you’ll see some mail headers, a copy ofthe message, and a concluding line that saysVerification successful.
If the messages has been modified by an unauthorized party, the outputwill conclude with a failure message indicating that the digest and/orthe signature doesn’t match what you received:
Verification failure23016:error:21071065:PKCS7 routines:PKCS7_signatureVerify:digestfailure:pk7_doit.c:804:23016:error:21075069:PKCS7 routines:PKCS7_verify:signaturefailure:pk7_smime.c:265:Likewise, if the sender’s certificate isn’t recognized by your OpenSSLinfrastructure, you’ll get a similar error:
Verification failure9544:error:21075075:PKCS7 routines:PKCS7_verify:certificate verifyerror:pk7_smime.c:222:Verify error:self signed certificateMost e-mail clients send a copy of the public certificate in thesignature attached to the message. From the command line, you can viewthe certificate data yourself. You’ll use thesmime -pk7out option topipe a copy of the PKCS#7 certificate back into thepkcs7 option.It’s oddly cumbersome but it works.
openssl smime -pk7out -in msg.txt|\openssl pkcs7 -text -noout -print_certsIf you’d like to extract a copy of your correspondent’s certificate forlong-term use, use just the first part of that pipe.
openssl smime -pk7out -in msg.txt -out her-cert.pemAt that point, you can eitherintegrate it into your OpenSSLinfrastructure or you can save it off somewhere forspecial use.
openssl smime -verify -in msg.txt -CAfile /path/to/her-cert.pemHow do I encrypt a S/MIME message?
Let’s say that someone sends you her public certificate and asks thatyou encrypt some message to her. You’ve saved her certificate asher-cert.pem. You’ve saved your reply asmy-message.txt.
To get the default—though fairly weak—RC2-40 encryption, you just tellopenssl where the message and the certificate are located.
openssl smime her-cert.pem -encrypt -in my-message.txtIf you’re pretty sure your remote correspondent has a robust SSLtoolkit, you can specify a stronger encryption algorithm like tripleDES:
openssl smime her-cert.pem -encrypt -des3 -in my-message.txtBy default, the encrypted message, including the mail headers, is sentto standard output. Use the-out option or your shell to redirect itto a file. Or, much trickier, pipe the output directly tosendmail.
openssl smime her-cert.pem\ -encrypt\ -des3\ -in my-message.txt\ -from'Your Fullname <you@youraddress.com>'\ -to'Her Fullname <her@heraddress.com>'\ -subject'My encrypted reply'|\sendmail her@heraddress.comHow do I sign a S/MIME message?
If you don’t need to encrypt the entire message, but you do want to signit so that your recipient can be assured of the message’s integrity, therecipe is similar to that forencryption. The maindifference is that you need to have your own key and certificate, sinceyou can’t sign anything with the recipient’s cert.
openssl smime\ -sign\ -signer /path/to/your-cert.pem\ -in my-message.txt\ -from'Your Fullname <you@youraddress.com>'\ -to'Her Fullname <her@heraddress.com>'\ -subject'My signed reply'|\sendmail her@heraddress.comFor further reading
Though it takes time to read them all and figure out how they relate toone another, the OpenSSL man pages are the best place to start:asn1parse(1),ca(1),ciphers(1),config(5),crl(1),crl2pkcs7(1),dgst(1),dhparam(1),dsa(1),dsaparam(1),ec(1),ecparam(1),enc(1),errstr(1),gendsa(1),genpkey(1),genrsa(1),nseq(1),ocsp(1),openssl(1),passwd(1),pkcs12(1),pkcs7(1),pkcs8(1),pkey(1),pkeyparam(1),pkeyutl(1),rand(1),req(1),rsa(1),rsautl(1),s_client(1),s_server(1),s_time(1),sess_id(1),smime(1),speed(1),spkac(1),ts(1),tsget(1),verify(1),version(1),x509(1),x509v3_config(5).
Comments welcome
This document has been online for well over a decade. Much of itsdevelopment is due to my own curiosity, but several key improvementshave come via unsolicited suggestions from readers. So let me sayexplicitly that comments and suggestions about this document areappreciated and can be addressed to the author atheinlein@madboa.com.