OpenSSLWiki - User contributions [en]

Talk:Command Line Utilities

2020-09-15T16:16:29Z

Jflopezfernandez: /* Pretty significant rewrite */

== Pretty significant rewrite ==

I noticed a lot of the information on the page was essentially a print out of the program help menu, so I thought it would be more beneficial to provide a basic introduction to the command-line utilities in tutorial form, with links to the official documentation. It isn't finished, as there are a lot of topics I didn't cover (certificates being a significant topic I did not cover), but because of the magnitude of the changes, I thought it best to stop here and get feedback on the changes. I'm brand-new to the project and I'm excited contribute in a meaningful way, so please if there is any wrong information, the style is off, etc., please do pass that along.

This rewrite is essentially a reformatting of the previous version, with a lot of additional explanations from the perldocs. The bulk of the changes come from the removing of the old code samples, which were essentially just the helps menus, and the addition of code examples which again come primarily from the perldocs. There's also a table with all of the standard commands which link to their respective manpage on the main openssl site. I thought this was better because now we only have to update one set of documentation, which itself is automatically generated from the pod files.

--[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 03:35, 30 July 2019 (UTC)

: This new style page looks great!! Please continue with it.
: A point to note about the ec key generation stuff. It is not necessary to first create an ec params file. It is simpler just to generate the key directly using genpkey and passing the pkeyopt "ec_paramgen_curve". See the man page for further details.
: --[[User:Matt|Matt]] ([[User talk:Matt|talk]]) 08:27, 30 July 2019 (UTC)

:: Awesome, I'll go ahead and add that in, thanks for the heads up. I'm glad you like the change; I was pretty nervous about it since it was a pretty big change and I'm still brand-new.
:: --[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 15:27, 30 July 2019 (UTC)

::: During this rewrite a comment about base64 usage 64 characters per line limit and -A usage was lost
::: i found it while rereading one old answer i did on stack overflow see https://askubuntu.com/questions/178521/how-can-i-decode-a-base64-string-from-the-command-line reference )
::: --[[User:Philippe lhardy|Philippe lhardy]] ([[User talk:Philippe lhardy|talk]]) 15:43, 14 June 2020 (UTC)

:::: Hi, Philippe, sorry about that; I've gone ahead and re-added the information. Can't believe I missed that, but thanks for letting me know.
:::: --[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 16:16, 15 September 2020 (UTC)

Command Line Utilities

2020-09-15T16:14:58Z

Jflopezfernandez: Re-added information about the limitations of base64 encoding, as discussed in the talk page.

The '''openssl''' program provides a rich variety of commands, each of which often has a wealth of options and arguments. Many commands use an external configuration file for some or all of their arguments and have a <code>-config</code> option to specify that file. The environment variable [[OPENSSL_CONF]] can be used to specify the location of the configuration file. If the environment variable is not specified, a default file is created in the default certificate storage area called '''openssl.cnf'''. The settings in this default configuration file depend on the flags set when the version of OpenSSL being used was built.

This article is an overview of the available tools provided by openssl. For all of the details on usage and implementation, you can find the [https://www.openssl.org/docs/manmaster/ manpages] which are automatically generated from the source code at the [https://www.openssl.org/ official OpenSSL project home]. Likewise, the source code itself may be found on the [https://www.openssl.org/source/ OpenSSL project home page], as well as on the [https://github.com/openssl/openssl OpenSSL Github]. The main OpenSSL site also includes an [https://www.openssl.org/docs/manmaster/man1/openssl.html overview of the command-line utilities], as well as links to all of their respective documentation.

=Getting Started=

The entry point for the OpenSSL library is the '''openssl''' binary, usually <tt>/usr/bin/openssl</tt> on Linux. The general syntax for calling openssl is as follows:

$ openssl command [ command_options ] [ command_arguments ]

Alternatively, you can call openssl without arguments to enter the interactive mode prompt. You may then enter commands directly, exiting with either a <code>quit</code> command or by issuing a termination signal with either <tt>Ctrl+C</tt> or <tt>Ctrl+D</tt>. The following is a sample interactive session in which the user invokes the [[prime]] command twice before using the <tt>quit</tt> command to terminate the session.

OpenSSL> prime -generate -bits 24
13467269
OpenSSL> prime -generate -bits 24
16651079
OpenSSL> quit

=Basic Tasks=

This section is a brief tutorial on performing the most basic tasks using OpenSSL. For a detailed explanation of the rationale behind the syntax and semantics of the commands shown here, see the section on [[#Commands|Commands]].

==Getting Help==

As mentioned previously, the general syntax of a command is <code>openssl command [ command_options ] [ command_arguments ]</code>. The help command is no different, but it does have its idiosyncrasies. To view the top-level help menu, you can call openssl as follows.

$ openssl help

This query will print all of the available commands, like so:

Standard commands
asn1parse ca ciphers cms
crl crl2pkcs7 dgst dhparam
dsa dsaparam ec ecparam
...

Note the above output was truncated, so only the first four lines of output are shown.

A help menu for each command may be requested in two different ways. First, the same command used above may be repeated, followed by the name of the command to print help for.

$ openssl help genpkey

The program will then display the valid options for the given command.

$ openssl help genpkey
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

The second way of requesting the help menu for a particular command is by using the first option in the output shown above, namely <code>openssl command -help</code>. Both commands will yield the same output; the help menu displayed will be exactly the same.

$ openssl genpkey -help
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

For additional information on the usage of a particular command, the project [https://www.openssl.org/docs/manpages.html manpages] are a great source of information. Another excellent source of information is the project perldocs. [https://perldoc.perl.org/5.30.0/perldoc.html perldoc] is a utility included with most if not all [https://www.perl.org/ Perl] distributions, and it's capable of displaying documentation information in a variety of formats, one of which is as manpages. Not surprisingly, the project documentation is generated from the pod files located in the <tt>doc</tt> directory of the source code.

==Getting Library Version Information==

$ openssl version
OpenSSL 1.1.1c 28 May 2019

As mentioned above, the <tt>version</tt> command's help menu may be queried for additional options like so:

$ openssl version -help
Usage: version [options]
Valid options are:
-help Display this summary
-a Show all data
-b Show build date
-d Show configuration directory
-e Show engines directory
-f Show compiler flags used
-o Show some internal datatype options
-p Show target build platform
-r Show random seeding options
-v Show library version

Using the <tt>-a</tt> option to show all version information yields the following output on my current machine:

$ openssl version -a
OpenSSL 1.1.1c 28 May 2019
built on: Tue May 28 16:23:39 2019 UTC
platform: linux-x86_64
options: bn(64,64) rc4(16x,int) des(int) idea(int) blowfish(ptr)
compiler: gcc -fPIC -pthread -m64 -Wa,--noexecstack -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wa,--noexecstack -D_FORTIFY_SOURCE=2 -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now -DOPENSSL_USE_NODELETE -DL_ENDIAN -DOPENSSL_PIC -DOPENSSL_CPUID_OBJ -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT -DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DKECCAK1600_ASM -DRC4_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM -DGHASH_ASM -DECP_NISTZ256_ASM -DX25519_ASM -DPOLY1305_ASM -DNDEBUG -D_FORTIFY_SOURCE=2
OPENSSLDIR: "/etc/ssl"
ENGINESDIR: "/usr/lib/engines-1.1"
Seeding source: os-specific

==Generating an RSA Private Key==

Generating a private key can be done in a variety of different ways depending on the type of key, algorithm, bits, and other options your specific use case may require. In this example, we are generating a private key using RSA and a key size of 2048 bits.

$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

To generate a password protected private key, the previous command may be slightly amended as follows:

$ openssl genpkey -aes256 -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

The addition of the <tt>-aes256</tt> option specifies the cipher to use to encrypt the private key file. For a list of available ciphers in the library, you can run the following command:

$ openssl list -cipher-algorithms

With your private key in hand, you can use the following command to see the key's details, such as its modulus and its constituent primes. Remember to change the name of the input file to the file name of your private key.

$ openssl pkey -in private-key.pem -text

The above command yields the following output in my specific case. Your output will differ but should be structurally similar.

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDZD6IMLRFk4CaF
w0rhRienwuE5EZ6xFE8e3C5TVi1+d9Enhi38RgkwD7UlWxPE6AWhp5T3kfrFWdak
1lZFVPp7/btOKLjKUru15nLoA4AKYtz9W9PhsM0dyzLc6FQ6K4ReQam5pHCqI2zF
82MwE+eIAduvuqyoQLKiI608EArWZqDtMUpBJzv0UVEYvRdnMWpCwfzpI+hPJywV
CcTlNCT/ctGgBKyIx+dDuZ7bR9MNmSW7GreJEbTH+R13xT3dd/JCka1+LYCl4h0q
oWhFPhOkvQzmmSzUmZlAlTDQLv2eAdJIrQcsnKZ3SsIOCC/3IpqwSzpid38Ill4O
xH6XIrVFAgMBAAECggEBAJ2MC0JrM8TULSHJrf/0u7O4b2DMuTIuW386sSUr17mD
nfviGF6TNvf7bq++e4rgHbZHvIg1HJ9Bpdne+J86HtUARYNlazru8fAFZEGiyLzB
JUV/8TpO6ZJGepR8zSWrkFgZsOddw6i6LalADy5GRDcjoiDajZdR3lZxLrv5qOQU
I1vKTf4Zs2Tl3gnaJ/Il1gBHIQ9W9xUH8jPBIwj51iXwCh8H0BiDPvFkU7cHIFCP
sJhGsGp6OS3uSwwQuSE+NqbuPfVilysCcwgZduknyio0QO1YfMBL6+XoKE/bFHsn
N+FzzczQg9sWyiwVR+3EeI9kp4JSElNh2nqG96i4QAECgYEA76OLUGrShHb4saoP
aYnBAKLEdWj5K483JdY6BSbdd5RkDbJG8ExmcbfTas/BGdKc4iVCkxV3ysxKnX18
PfxATHDLL8NMa+gGgZY5oTKUsrXEpS132HhCJ9T9LoesQjRb4kOZH8POVqm6O4Xf
lCt0y1+M1eQHI1NPO9CmPBgouEUCgYEA5+F4SS8RMyYRkU/kx195fwh0hhaOElzr
E8mZou3NFL/XT6/9t+2+7sMTuiQCP9zIa6s+/rrXdjWtrTcDp4WlDITas0UUgZhv
YVBQBF4vhHxIVwJxnT9Gwi4XM1JlFmVHofWD71P6DRe7jSWRS3CujP3AE9vmpWMx
tE1D9qLiWQECgYB445LzFYBvrKjWz4iI4CJKFNJwvGz+iXfzkXehg7KzkVtMAYSB
0rjXYzm3J2ktgq778nn8Qxc0agy2GEil6GvzY+9MgAQ8Z0do9gTKif6zjLjP7vkH
bdtJxsuWPoEqwMkdgqZrfNbJp0O4pVddovJ/agtdF3R2YJ+W+DH0HOfl1QKBgFnM
c2zEEYEhaQRBUHP1gXO0rouPCI4L9e2/0QPL2/QBJzzxBuzH4X1NhsI7V7OrqOIp
e0fiy7Y3q369I2ko1HY4rQln4z0c72VcWOCYKQbBqrInfCBNdPWWK93wNr2pk0gh
cGqqtteDLVrIBbCVfsOTMWN/cZ7y/zi4A23sPoQBAoGAEPzcIjOyoB97Pzd7iNim
Gin8RkwXIiFGSHo8vAh74CKBNokThM50OUNm5T2eJ4huzPpowQ+ID1mB5EjEai9n
JY9ll3cUpawiIIW/6uGTHyXfvZWNtqEYXrVJ6fcDaKcW4y3cplNj/SJaBW8HXsW7
YGHW3zHsgy7EOAOzPwlm9oE=
-----END PRIVATE KEY-----
RSA Private-Key: (2048 bit, 2 primes)
modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
publicExponent: 65537 (0x10001)
privateExponent:
00:9d:8c:0b:42:6b:33:c4:d4:2d:21:c9:ad:ff:f4:
bb:b3:b8:6f:60:cc:b9:32:2e:5b:7f:3a:b1:25:2b:
d7:b9:83:9d:fb:e2:18:5e:93:36:f7:fb:6e:af:be:
7b:8a:e0:1d:b6:47:bc:88:35:1c:9f:41:a5:d9:de:
f8:9f:3a:1e:d5:00:45:83:65:6b:3a:ee:f1:f0:05:
64:41:a2:c8:bc:c1:25:45:7f:f1:3a:4e:e9:92:46:
7a:94:7c:cd:25:ab:90:58:19:b0:e7:5d:c3:a8:ba:
2d:a9:40:0f:2e:46:44:37:23:a2:20:da:8d:97:51:
de:56:71:2e:bb:f9:a8:e4:14:23:5b:ca:4d:fe:19:
b3:64:e5:de:09:da:27:f2:25:d6:00:47:21:0f:56:
f7:15:07:f2:33:c1:23:08:f9:d6:25:f0:0a:1f:07:
d0:18:83:3e:f1:64:53:b7:07:20:50:8f:b0:98:46:
b0:6a:7a:39:2d:ee:4b:0c:10:b9:21:3e:36:a6:ee:
3d:f5:62:97:2b:02:73:08:19:76:e9:27:ca:2a:34:
40:ed:58:7c:c0:4b:eb:e5:e8:28:4f:db:14:7b:27:
37:e1:73:cd:cc:d0:83:db:16:ca:2c:15:47:ed:c4:
78:8f:64:a7:82:52:12:53:61:da:7a:86:f7:a8:b8:
40:01
prime1:
00:ef:a3:8b:50:6a:d2:84:76:f8:b1:aa:0f:69:89:
c1:00:a2:c4:75:68:f9:2b:8f:37:25:d6:3a:05:26:
dd:77:94:64:0d:b2:46:f0:4c:66:71:b7:d3:6a:cf:
c1:19:d2:9c:e2:25:42:93:15:77:ca:cc:4a:9d:7d:
7c:3d:fc:40:4c:70:cb:2f:c3:4c:6b:e8:06:81:96:
39:a1:32:94:b2:b5:c4:a5:2d:77:d8:78:42:27:d4:
fd:2e:87:ac:42:34:5b:e2:43:99:1f:c3:ce:56:a9:
ba:3b:85:df:94:2b:74:cb:5f:8c:d5:e4:07:23:53:
4f:3b:d0:a6:3c:18:28:b8:45
prime2:
00:e7:e1:78:49:2f:11:33:26:11:91:4f:e4:c7:5f:
79:7f:08:74:86:16:8e:12:5c:eb:13:c9:99:a2:ed:
cd:14:bf:d7:4f:af:fd:b7:ed:be:ee:c3:13:ba:24:
02:3f:dc:c8:6b:ab:3e:fe:ba:d7:76:35:ad:ad:37:
03:a7:85:a5:0c:84:da:b3:45:14:81:98:6f:61:50:
50:04:5e:2f:84:7c:48:57:02:71:9d:3f:46:c2:2e:
17:33:52:65:16:65:47:a1:f5:83:ef:53:fa:0d:17:
bb:8d:25:91:4b:70:ae:8c:fd:c0:13:db:e6:a5:63:
31:b4:4d:43:f6:a2:e2:59:01
exponent1:
78:e3:92:f3:15:80:6f:ac:a8:d6:cf:88:88:e0:22:
4a:14:d2:70:bc:6c:fe:89:77:f3:91:77:a1:83:b2:
b3:91:5b:4c:01:84:81:d2:b8:d7:63:39:b7:27:69:
2d:82:ae:fb:f2:79:fc:43:17:34:6a:0c:b6:18:48:
a5:e8:6b:f3:63:ef:4c:80:04:3c:67:47:68:f6:04:
ca:89:fe:b3:8c:b8:cf:ee:f9:07:6d:db:49:c6:cb:
96:3e:81:2a:c0:c9:1d:82:a6:6b:7c:d6:c9:a7:43:
b8:a5:57:5d:a2:f2:7f:6a:0b:5d:17:74:76:60:9f:
96:f8:31:f4:1c:e7:e5:d5
exponent2:
59:cc:73:6c:c4:11:81:21:69:04:41:50:73:f5:81:
73:b4:ae:8b:8f:08:8e:0b:f5:ed:bf:d1:03:cb:db:
f4:01:27:3c:f1:06:ec:c7:e1:7d:4d:86:c2:3b:57:
b3:ab:a8:e2:29:7b:47:e2:cb:b6:37:ab:7e:bd:23:
69:28:d4:76:38:ad:09:67:e3:3d:1c:ef:65:5c:58:
e0:98:29:06:c1:aa:b2:27:7c:20:4d:74:f5:96:2b:
dd:f0:36:bd:a9:93:48:21:70:6a:aa:b6:d7:83:2d:
5a:c8:05:b0:95:7e:c3:93:31:63:7f:71:9e:f2:ff:
38:b8:03:6d:ec:3e:84:01
coefficient:
10:fc:dc:22:33:b2:a0:1f:7b:3f:37:7b:88:d8:a6:
1a:29:fc:46:4c:17:22:21:46:48:7a:3c:bc:08:7b:
e0:22:81:36:89:13:84:ce:74:39:43:66:e5:3d:9e:
27:88:6e:cc:fa:68:c1:0f:88:0f:59:81:e4:48:c4:
6a:2f:67:25:8f:65:97:77:14:a5:ac:22:20:85:bf:
ea:e1:93:1f:25:df:bd:95:8d:b6:a1:18:5e:b5:49:
e9:f7:03:68:a7:16:e3:2d:dc:a6:53:63:fd:22:5a:
05:6f:07:5e:c5:bb:60:61:d6:df:31:ec:83:2e:c4:
38:03:b3:3f:09:66:f6:81

Keep in mind the above key was generated solely for pedagogical purposes; never give anyone access to your private keys.

==Generating a Public Key==

Having previously generated your private key, you may generate the corresponding public key using the following command.

$ openssl pkey -in private-key.pem -out public-key.pem -pubout

You may once again view the key details, using a slightly different command this time.

$ openssl pkey -in public-key.pem -pubin -text

The output for the public key will be shorter, as it carries much less information, and it will look something like this.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2Q+iDC0RZOAmhcNK4UYn
p8LhORGesRRPHtwuU1YtfnfRJ4Yt/EYJMA+1JVsTxOgFoaeU95H6xVnWpNZWRVT6
e/27Tii4ylK7teZy6AOACmLc/VvT4bDNHcsy3OhUOiuEXkGpuaRwqiNsxfNjMBPn
iAHbr7qsqECyoiOtPBAK1mag7TFKQSc79FFRGL0XZzFqQsH86SPoTycsFQnE5TQk
/3LRoASsiMfnQ7me20fTDZkluxq3iRG0x/kdd8U93XfyQpGtfi2ApeIdKqFoRT4T
pL0M5pks1JmZQJUw0C79ngHSSK0HLJymd0rCDggv9yKasEs6Ynd/CJZeDsR+lyK1
RQIDAQAB
-----END PUBLIC KEY-----
RSA Public-Key: (2048 bit)
Modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
Exponent: 65537 (0x10001)

For more information on generating keys, see the source code documentation, located in the <tt>doc/HOWTO/keys.txt</tt> file.

==Generating Keys Based on Elliptic Curves==

There are essentially two steps to generating a key:

# Generate the parameters for the specific curve you are using
# Use those parameters to generate the key

To see the list of curves instrinsically supported by openssl, you can use the <tt>-list_curves</t> option when calling the <tt>ecparam</tt> command.

$ openssl ecparam -list_curves
secp112r1 : SECG/WTLS curve over a 112 bit prime field
secp112r2 : SECG curve over a 112 bit prime field
secp128r1 : SECG curve over a 128 bit prime field
secp128r2 : SECG curve over a 128 bit prime field
secp160k1 : SECG curve over a 160 bit prime field
...

For this example I will use the <tt>prime256v1</tt> curve, which is an <tt>X9.62/SECG</tt> curve over a 256 bit prime field.

===Generating the Curve Parameters===

Having selected our curve, we now call <tt>ecparam</tt> to generate our parameters file.

$ openssl ecparam -name prime256v1 -out prime256v1.pem

====Printing Parameters to Standard Out====

You can print the generated curve parameters to the terminal output with the following command:

$ openssl ecparam -in prime256v1.pem -noout -text
ASN1 OID: prime256v1
NIST CURVE: P-256

====Printing Parameters as C Code====

Analogously, you may also output the generated curve parameters as C code. The parameters can then be loaded by calling the <tt>get_ec_group_XXX()</tt> function. To print the C code to the current terminal's output, the following command may be used:

$ openssl ecparam -in prime256v1.pem -noout -C

And here are the first few lines of the corresponding output:

EC_GROUP *get_ec_group_256(void)
{
static unsigned char ec_p_256[] = {
0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
...

===Generating the Key===

With the curve parameters in hand, we are now free to generate the key. Just as with the [#Generating an RSA Private Key|RSA] example above, we may optionally specify a cipher algorithm with which to encrypt the private key. The call to generate the key using the elliptic curve parameters generated in the example above looks like this:

$ openssl genpkey -aes256 -paramfile prime256v1.pem -out private-key.pem
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

===Putting it All Together===

The process of generation a curve based on elliptic-curves can be streamlined by calling the <tt>genpkey</tt> command directly and specifying both the algorithm and the name of the curve to use for parameter generation. In it's simplest form, the command to generate a key based on the same curve as in the example above looks like this:

$ openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256

This command will result in the generated key being printed to the terminal's output.

$ openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256

-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgqqYoJGowXJ5/GTkB
SRLnBMNWLoQ2RM/QxrY+bfDDGRahRANCAASPY4eTANkwIIAWhh32eoFl2YFLJSWy
bdITdZ82O5JDpDijmGmJ2hepe5afek9WVqxMPYjmbTwMPO3xMGbqUiJD
-----END PRIVATE KEY-----

Remember that you can specify a cipher algorithm to encrypt the key with, which something you may or may not want to do, depending on your specific use case. Here is a slightly more complete example showing a key generated with a password and written to a specific output file.

$ openssl genpkey -aes256 -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

Just as with the previous example, you can use the <tt>pkey</tt> command to inspect your newly-generated key.

$ openssl pkey -in private-key.pem -text
Enter pass phrase for private-key.pem:
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgEO7CxgTwi0hsjdbp
sXWuU2x2flLthxqXabYDOqOZCvuhRANCAAQVTLkeCBJdvMnqwZKYJxrPvTTuanrD
NkyAPQCARKsQ7bVrP6ky/5uAcAvjuZB0xKCcSp7roXLWRzD/y/ik8P5R
-----END PRIVATE KEY-----
Private-Key: (256 bit)
priv:
10:ee:c2:c6:04:f0:8b:48:6c:8d:d6:e9:b1:75:ae:
53:6c:76:7e:52:ed:87:1a:97:69:b6:03:3a:a3:99:
0a:fb
pub:
04:15:4c:b9:1e:08:12:5d:bc:c9:ea:c1:92:98:27:
1a:cf:bd:34:ee:6a:7a:c3:36:4c:80:3d:00:80:44:
ab:10:ed:b5:6b:3f:a9:32:ff:9b:80:70:0b:e3:b9:
90:74:c4:a0:9c:4a:9e:eb:a1:72:d6:47:30:ff:cb:
f8:a4:f0:fe:51
ASN1 OID: prime256v1
NIST CURVE: P-256

For more details on elliptic curve cryptography or key generation, check out the [https://www.openssl.org/docs/manpages.html manpages].

==Base64 Encoding Strings==

For simple string encoding, you can use "here string" syntax with the [[Base64 Encoding|base64]] command as below. Intuitively, the <tt>-e</tt> flag specifies the action to be encoding.

$ openssl base64 -e <<< 'Welcome to openssl wiki'
V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK

Similarly, the base64 command's <tt>-d</tt> flag may be used to indicate decoding mode.

$ openssl base64 -d <<< 'V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK'
Welcome to openssl wiki

'''''Note:''''' base64 line length is limited to 76 characters by default in openssl (and generated with 64 characters per line).

openssl base64 -e <<< 'Welcome to openssl wiki with a very long line that splits...'
V2VsY29tZSB0byBvcGVuc3NsIHdpa2kgd2l0aCBhIHZlcnkgbG9uZyBsaW5lIHRo
YXQgc3BsaXRzLi4uCg==
openssl base64 -d <<< 'V2VsY29tZSB0byBvcGVuc3NsIHdpa2kgd2l0aCBhIHZlcnkgbG9uZyBsaW5lIHRoYXQgc3BsaXRzLi4uCg=='

=> NOTHING!

To be able to decode a base64 line without line feeds that exceeds the default 76 character length restriction use the <code>-A</code> option.

openssl base64 -d -A <<< 'V2VsY29tZSB0byBvcGVuc3NsIHdpa2kgd2l0aCBhIHZlcnkgbG9uZyBsaW5lIHRoYXQgc3BsaXRzLi4uCg=='
Welcome to openssl wiki with a very long line that splits...

It is recommended to actually split base64 strings into multiple lines of 64 characters, however, since the <code>-A</code> option is buggy, particularly with its handling of long files.

==Generating a File Hash==

One of the most basic uses of the [[dgst]] command (short for digest) is viewing the hash of a given file. To do this, simply invoke the command with the specified digest algorithm to use. For this example, I will be hashing an arbitrary file on my system using the [[MD5]], [[SHA1]], and [[SHA384]] algorithms.

$ openssl dgst -md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl dgst -sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl dgst -sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

For a list of the available digest algorithms, you can use the following command.

$ openssl list -digest-algorithms
RSA-MD4 => MD4
RSA-MD5 => MD5
RSA-MDC2 => MDC2
RSA-RIPEMD160 => RIPEMD160
RSA-SHA1 => SHA1
RSA-SHA1-2 => RSA-SHA1
...

You can also use a similar command to see the available [[Digest Commands|digest commands]]:

$ openssl list -digest-commands
blake2b512 blake2s256 gost md4
md5 mdc2 rmd160 sha1
sha224 sha256 sha3-224 sha3-256
sha3-384 sha3-512 sha384 sha512
sha512-224 sha512-256 shake128 shake256
sm3

Below are three sample invocations of the [[md5]], [[sha1]], and [[sha384]] digest commands using the same file as the [[dgst]] command invocation above.

$ openssl md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

==File Encryption and Decryption==

The following example demonstrates a simple file encryption and decryption using the [[enc]] command. The first argument is the cipher algorithm to use for encrypting the file. For this example I carefully selected the [[AES-256]] algorithm in [[CBC Mode]] by looking up the available ciphers and picking out the first one I saw. To see the list of available ciphers, you can use the following command.

$ openssl enc -ciphers
Supported ciphers:
-aes-128-cbc -aes-128-cfb -aes-128-cfb1
-aes-128-cfb8 -aes-128-ctr -aes-128-ecb
-aes-128-ofb -aes-192-cbc -aes-192-cfb
-aes-192-cfb1 -aes-192-cfb8 -aes-192-ctr
...

You can also use the following command:

$ openssl list -cipher-algorithms
AES-128-CBC
AES-128-CBC-HMAC-SHA1
AES-128-CBC-HMAC-SHA256
id-aes128-CCM
AES-128-CFB
AES-128-CFB1
AES-128-CFB8
AES-128-CTR
...

Having selected an encryption algorithm, you must then specify whether the action you are taking is either encryption or decryption via the <tt>-e</tt> or <tt>-d</tt> flags, respectively. The <tt>-iter</tt> flag specifies the number of iterations on the password used for deriving the encryption key. A higher iteration count increases the time required to brute-force the resulting file. Using this option implies enabling use of the [[Password-Based Key Derivation Function 2]], usually set using the <tt>-pbkdf2</tt> flag. We then use the <tt>-salt</tt> flag to enable the use of a randomly generated salt in the key-derivation function.

Putting it all together, you can see the command to encrypt a file and the corresponding output below. Note that the passwords entered by the user are blank, just as they would usually be in a terminal session.

$ openssl enc -aes-256-cbc -e -iter 1000 -salt -in primes.dat -out primes.enc
enter aes-256-cbc encryption password:
Verifying - enter aes-256-cbc encryption password:

The analogous decryption command is as follows:

$ openssl enc -aes-256-cbc -d -iter 1000 -in primes.enc -out primes.dec
enter aes-256-cbc decryption password:

=Commands=

There are three different kinds of commands. These are [[Standard commands|standard commands]], [[Cipher commands|cipher commands]], and [[Digest comands|digest commands]]. Calling the OpenSSL top-level <tt>help</tt> command with no arguments will result in openssl printing all available commands by group, sorted alphabetically.

==Standard Commands==

{| class="wikitable" style="margin:auto; text-align: center; width: 65%;"
|+ Overview of OpenSSL's command line utilities
! style="width: 25%; padding: 4px;" | Command
! style="width: 75%; padding: 4px;" | Description
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/asn1parse.html asn1parse]
|style="padding: 4px;" | Parse an ASN.1 sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ca.html ca]
|style="padding: 4px;" | Certificate Authority (CA) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ciphers.html ciphers]
|style="padding: 4px;" | Cipher Suite Description Determination.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/cms.html cms]
|style="padding: 4px;" | CMS (Cryptographic Message Syntax) utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl.html crl]
|style="padding: 4px;" | Certificate Revocation List (CRL) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl2pkcs7.html crl2pkcs7]
|style="padding: 4px;" | CRL to PKCS#7 Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dgst.html dgst]
|style="padding: 4px;" | Message Digest calculation. MAC calculations are superseded by mac(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dhparam.html dhparam]
|style="padding: 4px;" | Generation and Management of Diffie-Hellman Parameters. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsa.html dsa]
|style="padding: 4px;" | DSA Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsaparam.html dsaparam]
|style="padding: 4px;" | DSA Parameter Generation and Management. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ec.html ec]
|style="padding: 4px;" | EC (Elliptic curve) key processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ecparam.html ecparam]
|style="padding: 4px;" | EC parameter manipulation and generation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/enc.html enc]
|style="padding: 4px;" | Encoding with Ciphers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/engine.html engine]
|style="padding: 4px;" | Engine (loadable module) information and manipulation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/errstr.html errstr]
|style="padding: 4px;" | Error Number to Error String Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/gendsa.html gendsa]
|style="padding: 4px;" | Generation of DSA Private Key from Parameters. Superseded by genpkey(1) and pkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genpkey.html genpkey]
|style="padding: 4px;" | Generation of Private Key or Parameters.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genrsa.html genrsa]
|style="padding: 4px;" | Generation of RSA Private Key. Superseded by genpkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/info.html info]
|style="padding: 4px;" | Display diverse information built into the OpenSSL libraries.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/kdf.html kdf]
|style="padding: 4px;" | Key Derivation Functions.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/mac.html mac]
|style="padding: 4px;" | Message Authentication Code Calculation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/nseq.html nseq]
|style="padding: 4px;" | Create or examine a Netscape certificate sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ocsp.html ocsp]
|style="padding: 4px;" | Online Certificate Status Protocol utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/passwd.html passwd]
|style="padding: 4px;" | Generation of hashed passwords.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs12.html pkcs12]
|style="padding: 4px;" | PKCS#12 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs7.html pkcs7]
|style="padding: 4px;" | PKCS#7 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs8.html pkcs8]
|style="padding: 4px;" | PKCS#8 format private key conversion tool.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkey.html pkey]
|style="padding: 4px;" | Public and private key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyparam.html pkeyparam]
|style="padding: 4px;" | Public key algorithm parameter management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyutl.html pkeyutl]
|style="padding: 4px;" | Public key algorithm cryptographic operation utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/prime.html prime]
|style="padding: 4px;" | Compute prime numbers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rand.html rand]
|style="padding: 4px;" | Generate pseudo-random bytes.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rehash.html rehash]
|style="padding: 4px;" | Create symbolic links to certificate and CRL files named by the hash values.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/req.html req]
|style="padding: 4px;" | PKCS#10 X.509 Certificate Signing Request (CSR) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsa.html rsa]
|style="padding: 4px;" | RSA key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsautl.html rsautl]
|style="padding: 4px;" | RSA utility for signing, verification, encryption, and decryption. Superseded by pkeyutl(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_client.html s_client]
|style="padding: 4px;" | This implements a generic SSL/TLS client which can establish a transparent connection to a remote server speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_server.html s_server]
|style="padding: 4px;" | This implements a generic SSL/TLS server which accepts connections from remote clients speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_time.html s_time]
|style="padding: 4px;" | SSL Connection Timer.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/sess_id.html sess_id]
|style="padding: 4px;" | SSL Session Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/smime.html smime]
|style="padding: 4px;" | S/MIME mail processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/speed.html speed]
|style="padding: 4px;" | Algorithm Speed Measurement.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/spkac.html spkac]
|style="padding: 4px;" | SPKAC printing and generating utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/srp.html srp]
|style="padding: 4px;" | Maintain SRP password file.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/storeutl.html storeutl]
|style="padding: 4px;" | Utility to list and display certificates, keys, CRLs, etc.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ts.html ts]
|style="padding: 4px;" | Time Stamping Authority tool (client/server).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/verify.html verify]
|style="padding: 4px;" | X.509 Certificate Verification.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/version.html version]
|style="padding: 4px;" | OpenSSL Version Information.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/x509.html x509]
|style="padding: 4px;" | X.509 Certificate Data Management.
|}

= Further reading =

* Paul Heinlein. [https://www.madboa.com/geek/openssl/ "OpenSSL Command-Line HOWTO"]. Has many quick cookbook-style recipes for doing common tasks using the "oppenssl" command-line application.

[[Category:Examples]]
[[Category:Shell level]]

User talk:Jflopezfernandez

2019-08-26T10:27:16Z

Jflopezfernandez: Created user talk page

Hi! Feel free to reach out to me if I make a mistake, I'm always looking to learn :)

Talk:Main Page

2019-08-25T18:03:34Z

Jflopezfernandez: Replying to thread

Content Outline

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
</TR>
</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* OpenSSL Manual Pages
::* [[Manual:Openssl(1)]], [[Manual:Ssl(3)]], [[Manual:Crypto(3)]], [[Documentation Index]]
:: If you wish to edit any of the Manual page content please refer to the [[Guidelines for Manual Page Authors]] page.
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* EVP
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* Low Level APIs
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [[FIPS 140-2]]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]

== Miscellanous ==
For the material that doesn't seem to fit anywhere else
:* New topics pending categorization (not yet linked elsewhere)
:* Incomplete or contentious pages under discussion

----
I like it - it brings the interesting content right up front. It probably needs to have some top and tail text to describe what this wiki is for, and how to contribute. I added a link to the Elliptic Curve Cryptography page above
--[[User:Matt|Matt]] 15:02, 30 May 2013 (UTC)

== Proposed Change: Quick Links ==

I'm proposing a change of the quick links section to use the wikitable syntax. This is the current version, but I can modify the styling as required, like changing the background and removing the border to look as if we just moved the old table to the center, if anyone prefers that.

{| class="wikitable" style="margin-left: auto; margin-right: auto; text-align: center;"
| style="width: 200px; | [[OpenSSL Overview]] || style="width: 200px;" | [[Compilation and Installation]] || style="width: 200px;" | [[Internals]] || style="width: 200px;" | [[Mailing Lists]]
|-
| [[libcrypto API]] || [[libssl API]] || [[Examples]] || [[Documentation Index|Index of all API functions]]
|-
| [[License]] || [[Command Line Utilities]] || [[Related Links]] || [[Binaries]]
|-
| [[SSL and TLS Protocols]] || [[1.1 API Changes]] || [[FIPS modules]] || [[TLS1.3]]
|}

The main benefit in my opinion is the code. This is the code for the table:

<pre>
{| class="wikitable" style="margin-left: auto; margin-right: auto; text-align: center;"
| style="width: 200px; | [[OpenSSL Overview]] || style="width: 200px;" | [[Compilation and Installation]] || style="width: 200px;" | [[Internals]] || style="width: 200px;" | [[Mailing Lists]]
|-
| [[libcrypto API]] || [[libssl API]] || [[Examples]] || [[Documentation Index|Index of all API functions]]
|-
| [[License]] || [[Command Line Utilities]] || [[Related Links]] || [[Binaries]]
|-
| [[SSL and TLS Protocols]] || [[1.1 API Changes]] || [[FIPS modules]] || [[TLS1.3]]
|}
</pre>

The previous table's code used image files to manipulate the alignment, and I think it makes adding or removing links a lot harder than it needs to be.

<pre>
<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Mailing Lists]] </TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Binaries]]</TD>
</TR>
<TR>
<TD>[[SSL and TLS Protocols]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[FIPS modules]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[TLS1.3]]</TD>
</TR>
</TABLE>
</pre>

Let me know what you think; I appreciate any and all feedback.

-- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 19:52, 9 August 2019 (UTC)

: Wow - yeah. That looks great to me.
: --[[User:Matt|Matt]] ([[User talk:Matt|talk]]) 22:33, 9 August 2019 (UTC)

:: Do you think it's okay to make the change? There haven't been any objections,
:: but I'm not sure what the procedure is for making changes like this. I think
:: it's substantial enough to merit some kind of review process since it's the
:: main page, but like I said, I don't really know.
::
:: -- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 18:03, 25 August 2019 (UTC)

Talk:Main Page

2019-08-09T19:52:24Z

Jflopezfernandez: /* Proposed Change: Quick Links */ new section

Basic rules

2019-08-09T19:38:03Z

Jflopezfernandez: Modified the headings so the organization was a little clearer, and removed one of the misuse sections, as there were two identical ones

= Basic Rules =

== Access and Privileges ==

=== Eligibility ===
We do not want to exclude anyone from participation and so will impose the minimal restrictions consistent with the basic integrity of the site. For the beginning at least edit privileges will be given to any registered account. If necessary then later when we have a pool of sysops manual intervention may be required for edit privileges.

=== Misuse ===
If your account is used for spam or vandalism it may be deleted without warning. If that account was compromised without your knowledge or consent then contact us and we'll figure out how to restore your access.

== Content ==

=== Copyrights ===
Only content in the public domain or under the OpenSSL license should be added to this wiki. We don't have the expertise or means to properly research copyright issues and so will probably be forced to remove any content if complaints of copyright infringement are received.

=== Disclaimers ===
If any OpenSSL team member reports any content as factually incorrect, and does not immediately correct it, that content may be edited to include a disclaimer noting the presence of uncorrected errors.

=== Commercial Products ===

OpenSSL does not endorse any specific commercial products or services. Reference to such products and services is permissible when restricted to factually verifiable information appropriate in the current context, but such references should be accompanied by a link to the [[Commercial Product Disclaimer]] page.

[[Category:Wiki Usage]]

Versioning

2019-08-09T19:15:11Z

Jflopezfernandez: Added link to the command-line utilities overview page

[[Category:Versioning]]
OpenSSL version numbers are formatted as n1.n2.n3x, where n1-3 are numbers and x, if present, is one or more letters. These can change depending on the release type:

- '''Major releases''' that change one/both of the first two digits, which can break compatibility with previous versions

- '''Minor releases''' that change the last digit, e.g. 1.1.0 vs. 1.1.1, can and are likely to contain new features, but in a way that does not break binary compatibility. This means that an application compiled and dynamically linked with 1.1.0 does not need to be recompiled when the shared library is updated to 1.1.1. It should be noted that some features are transparent to the application such as the maximum negotiated TLS version and cipher suites, performance improvements and so on. There is no need to recompile applications to benefit from these features.

- '''Letter releases''', such as 1.0.2a, exclusively contain bug and security fixes and no new features.

The full release strategy for OpenSSL is available [https://www.openssl.org/policies/releasestrat.html here]

== Finding the current version ==

The [[Command Line Utilities|command line tool]] [https://www.openssl.org/docs/manmaster/apps/version.html version] can be used to determine the installed OpenSSL version.

Header file [https://github.com/openssl/openssl/blob/master/include/openssl/opensslv.h opensslv.h] also contains information about the version number.

Cryptogams SHA

2019-08-09T19:11:36Z

Jflopezfernandez: Fixed typo

[http://www.openssl.org/~appro/cryptogams/ Cryptogams] is Andy Polyakov's project used to develop high speed cryptographic primitives and share them with other developers. This wiki article will show you how to use Cryptogams ARMv4 SHA-1 implementation. According to the head notes the ARMv4 implementation runs around 6.5 cycles per byte (cpb). Typical C/C++ implementations run around 10 to 20 cpb and Andy's routines should outperform all of them.

Andy's Cryptogam implementations are provided by OpenSSL, but they are also available stand alone under a BSD license. The BSD style license is permissive and allows developers to use Andy's high speed cryptography without an OpenSSL dependency or licensing terms.

There are 6 steps to the process. The first step obtains the sources. The second step creates an ASM source file. The third step compiles and assembles the source file into an object file. The fourth steps determines the API. The fifth step creates a C header file. The final step integrates the object file into a program. Once you create the files <tt>sha1-armv4.h</tt> and <tt>sha1-armv4.S</tt> you can use <tt>sed</tt> to restore symbols back to their Cryptogams name with <tt>sed -i 's|OPENSSL|CRYPTOGAMS|g' sha1-armv4.h sha1-armv4.S</tt>.

A few cautions before you begin. First, you are going to examine undocumented features of the OpenSSL library to learn how to work with the Cryptogam's sources. The Cryptogam sources are stable but things could change over time. Second, the ARMv4 implementation hashes full SHA blocks. You are responsible for things like padding and side channel counter-measures.

If you experience ''"unexpected reloc type 0x03"'' when building a shared object then see [https://sourceware.org/ml/binutils/2019-05/msg00287.html What does unexpected reloc type 0x03 mean?] on the Binutils mailing list.

==Obtain Source Files==

There are two source files you need for Cryptogams SHA. The first is [https://github.com/openssl/openssl/blob/master/crypto/perlasm/arm-xlate.pl <tt>arm-xlate.pl</tt>] and the second is [https://github.com/openssl/openssl/blob/master/crypto/sha/asm/sha1-armv4-large.pl <tt>sha1-armv4.pl</tt>]. They are available in the OpenSSL sources. The following commands fetch OpenSSL and then peels off the two Cryptogams files of interest.

<pre># Clone OpenSSL for the latest Cryptogams sources
git clone https://github.com/openssl/openssl.git

mkdir cryptogams/

cp ./openssl/crypto/perlasm/arm-xlate.pl ./cryptogams/
cp ./openssl/crypto/sha/asm/sha1-armv4-large.pl ./cryptogams/
cp ./openssl/crypto/arm_arch.h cryptogams/

cd cryptogams/</pre>

==Create ASM File==

The second step is to run <tt>sha1-armv4-large.pl</tt> to produce an assembly language source file that can be consumed by GCC. <tt>sha1-armv4-large.pl</tt> internally calls <tt>arm-xlate.pl</tt>. <tt>linux32</tt> is the flavor used by the translate program. <tt>sha1-armv4.S</tt> is the output filename. In the command below note the <tt>*.S</tt> file extension, which is a capitol '''''S'''''. Do not use a lowercase '''''s''''' because GCC must drive the compile and assemble step.

<pre>perl sha1-armv4-large.pl linux32 sha1-armv4.S</pre>

GCC is needed to drive the process because there are C macros in the source file. Some Cryptogam source files have this requirement, while some others do not. <tt>sha1-armv4</tt> happens to have the requirement.

<pre>$ cat sha1-armv4.S
@ Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
...

#ifndef __KERNEL__
# include "arm_arch.h"
#else
# define __ARM_ARCH__ __LINUX_ARM_ARCH__
#endif
...</pre>

At this point there is an ASM file but it needs two small fixups. First, <tt>arm_arch.h</tt> is an OpenSSL source file so the dependency must be removed. Second, GCC defines <tt>__ARM_ARCH</tt> instead of <tt>__ARM_ARCH__</tt> so a <tt>sed</tt> is needed.

To fixup the source files execute the following two commands:

<pre># Remove OpenSSL include
sed -i 's/# include "arm_arch.h"//g' sha1-armv4.S

# Fix GCC defines
sed -i 's/__ARM_ARCH__/__ARM_ARCH/g' sha1-armv4.S</pre>

Alternately, instead of the two <tt>sed's</tt>, you can open <tt>arm_arch.h</tt>, copy the defines and paste them directly into <tt>sha1-armv4.S</tt>. Take care when using <tt>arm_arch.h</tt> as it carries the OpenSSL license.

After the two fixups <tt>sha1-armv4.S</tt> is ready to be compiled by GCC.

==Compile Source File==

The source file is ready to be compiled and assembled. At this point there are two choices. First, you can use ARMv5t or higher which includes Thumb instructions. The following compiles the source file with ARMv5t.

<pre>$ gcc -march=armv5t -c sha1-armv4.S</pre>

The second choice uses ARMv4 and avoids Thumb instructions. If you want to avoid Thumb then add <tt>-marm</tt> to you compile command.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S</pre>

Using ARMv5t as an example you now have an object file with the following symbols. Symbols with a capitol '''''T''''' are public and exported. Symbols with a lower '''''t''''' are private and should not be used.

<pre>$ gcc -march=armv4 -marm -c sha1-armv4.S
$ nm sha1-armv4.o
00000000 T sha1_block_data_order</pre>

And you can inspect the generated code with <tt>objdump</tt>.

<pre>$ objdump --disassemble sha1-armv4.o
sha1-armv4.o: file format elf32-littlearm

Disassembly of section .text:

00000000 <sha1_block_data_order>:
0: e92d5ff0 push {r4, r5, r6, r7, r8, r9, sl, fp, ip, lr}
4: e0812302 add r2, r1, r2, lsl #6
8: e89000f8 ldm r0, {r3, r4, r5, r6, r7}
c: e59f858c ldr r8, [pc, #1420] ; 5a0 <sha1_block_data_order+0x5a0>
10: e1a0e00d mov lr, sp
14: e24dd03c sub sp, sp, #60 ; 0x3c
18: e1a05f65 ror r5, r5, #30
1c: e1a06f66 ror r6, r6, #30

...</pre>

==Determine API==

The next step is determine the API so you can call it from a C program. Unfortunately the API is not documented and you have to dig around the OpenSSL sources. Fortunately there is one function of interest called <tt>sha1_block_data_order</tt>.

A quick <tt>grep</tt> of OpenSSL sources reveals the following for <tt>sha1_block_data_order</tt>.

<pre>openssl$ grep -nIR sha1_block_data_order | grep '\.c'
crypto/evp/e_sha_cbc_hmac_sha1.c:95: void sha1_block_data_order(void *c, const void *p, size_t len);
crypto/evp/e_sha_cbc_hmac_sha1.c:115: sha1_block_data_order(c, ptr, len / SHA_CBLOCK);
crypto/evp/e_sha_cbc_hmac_sha1.c:615: sha1_block_data_order(&key->md, data, 1);
crypto/evp/e_sha_cbc_hmac_sha1.c:631: sha1_block_data_order(&key->md, data, 1);
...
</pre>

We need several more symbols, and and they are <tt>OPENSSL_armcap_P</tt>, <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

<pre>$ grep -nIR OPENSSL_armcap_P
...
crypto/armcap.c:20:unsigned int OPENSSL_armcap_P = 0;</pre>

Lather, rinse, repeat for <tt>ARMV7_NEON</tt> and <tt>ARMV8_SHA1</tt>.

==Create C Header==

The fifth step creates a C header file based on information from [[#Determine_API|Determine API]]. The header file is needed for two reasons. First, it removes the OpenSSL dependency from your project. Second, it avoids OpenSSL licensing violations.

Below is the C Header file you can use. While it is not obvious, the <tt>len</tt> parameter from [[#Determine_API|Determine API]] is a block count, not a byte count.

<pre>/* Header file for use with Cryptogam's ARMv4 SHA1. */
/* Also see http://www.openssl.org/~appro/cryptogams/ */
/* https://wiki.openssl.org/index.php/Cryptogams_SHA. */

#ifndef CRYPTOGAMS_SHA1_ARMV4_H
#define CRYPTOGAMS_SHA1_ARMV4_H

#ifdef __cplusplus
extern "C" {
#endif

extern unsigned int OPENSSL_armcap_P;
void sha1_block_data_order(void *state, const void *data, size_t blocks);

/* Auxval caps */
#ifndef HWCAP_NEON
# define HWCAP_NEON (1 << 12)
#endif
#ifndef HWCAP_SHA1
# define HWCAP_SHA1 (1 << 5)
#endif

/* OpenSSL caps */
#define ARMV7_NEON (1<<0)
#define ARMV8_SHA1 (1<<3)

#ifdef __cplusplus
}
#endif

#endif /* CRYPTOGAMS_SHA1_ARMV4_H */</pre>

==Test Program==

The final step is to test the integration of Cryptogam's SHA with your program.

<pre>$ gcc -std=c99 sha1-armv4-test.c ./sha1-armv4.o -o sha1-armv4-test.exe
$ ./sha1-armv4-test.exe
SHA1 hash of empty message: DA39A3EE5E6B4B0D...
Success!</pre>

And the test program is shown below.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

/* empty message with padding */
uint8_t message[64];
memset(message, 0x00, sizeof(message));
message[0] = 0x80;

/* initial state */
uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

sha1_block_data_order(state, message, 1);

const uint8_t b1 = (uint8_t)(state[0] >> 24);
const uint8_t b2 = (uint8_t)(state[0] >> 16);
const uint8_t b3 = (uint8_t)(state[0] >> 8);
const uint8_t b4 = (uint8_t)(state[0] >> 0);
const uint8_t b5 = (uint8_t)(state[1] >> 24);
const uint8_t b6 = (uint8_t)(state[1] >> 16);
const uint8_t b7 = (uint8_t)(state[1] >> 8);
const uint8_t b8 = (uint8_t)(state[1] >> 0);

/* DA39A3EE5E6B4B0D... */
printf("SHA1 hash of empty message: ");
printf("%02X%02X%02X%02X%02X%02X%02X%02X...\n",
b1, b2, b3, b4, b5, b6, b7, b8);

int success = ((b1 == 0xDA) && (b2 == 0x39) && (b3 == 0xA3) && (b4 == 0xEE) &&
(b5 == 0x5E) && (b6 == 0x6B) && (b7 == 0x4B) && (b8 == 0x0D));

if (success)
printf("Success!\n");
else
printf("Failure!\n");

return (success != 0 ? 0 : 1);
}</pre>

==Symbol Names==

The article used the same names as they appeared in the Cryptogams source code. For example, <tt>sha1_block_data_order</tt> is the names of function in the source code, and they will show up in the object file and when compiled and in the library when linked.

It is possible the function and date names will collide if you also link to OpenSSL, either directly or indirectly. If you plan on using Cryptogams code in a shared object then you should rename all symbols to avoid collisions. To rename symbols for SHA-1 you should rename <tt>sha1_block_data_order</tt> and <tt>OPENSSL_armcap_P</tt>. Assuming you are using <tt>MYLIB</tt> as a prefix the following <tt>sed</tt> should do the job.

<pre>sed -i 's/OPENSSL/MYLIB/g' sha1_armv4.h sha1_armv4.S
sed -i 's/sha1_block_data_order/MYLIB_sha1_block_data_order/g' sha1_armv4.h sha1_armv4.S</pre>

You can verify public symbols were renamed with <tt>nm aes-armv4.o</tt>. Generally speaking, all symbols with capitol letters like <tt>T</tt> (public function), <tt>B</tt> (uninitialized data), <tt>C</tt> (common data), <tt>D</tt> (initialized data), and <tt>R</tt> (read-only data) should be renamed.

==Benchmarks==

You can perform a rough benchmark using the code shown below. Prior to executing the benchmark program you should move the CPU from <tt>on-demand</tt> or <tt>powersave</tt> to <tt>performance</tt> mode.

<pre>#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <time.h>
#include <unistd.h>
#include <string.h>
#include <sys/auxv.h>
#include "sha1-armv4.h"

/* processor caps */
unsigned int OPENSSL_armcap_P = 0;

int main(int argc, char* argv[])
{
/* set processor caps */
if (getauxval(AT_HWCAP) & HWCAP_NEON)
OPENSSL_armcap_P |= ARMV7_NEON;
if (getauxval(AT_HWCAP) & HWCAP_SHA1)
OPENSSL_armcap_P |= ARMV8_SHA1;

const unsigned int STEPS = 128;
uint8_t* buf = (uint8_t*)malloc(STEPS*64+64);
memset(buf, 0x00, 16);

double elapsed = 0.0;
size_t total = 0;

struct timespec start, end;
clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start);

uint32_t state[5] = {0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0};

do
{
size_t idx = 0;
for (unsigned int i=0; i<STEPS; ++i)
sha1_block_data_order(state, buf, idx+1);
total += 64*STEPS;

clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end);
elapsed = (end.tv_sec-start.tv_sec);
}
while (elapsed < 3 /* seconds */);

/* Increase precision of elapsed time */
elapsed = ((double)end.tv_sec-start.tv_sec) +
((double)end.tv_nsec-start.tv_nsec) / 1000 / 1000 / 1000;

/* CPU freq of 1 GHz */
const double cpuFreq = 1000.0*1000*1000;

const double bytes = total;
const double ghz = cpuFreq / 1000 / 1000 / 1000;
const double mbs = bytes / elapsed / 1024 / 1024;
const double cpb = elapsed * cpuFreq / bytes;

printf("%.0f bytes\n", bytes);
printf("%.02f mbs\n", mbs);
printf("%.02f cpb\n", cpb);

free(buf);

return 0;
}</pre>

The results below are from a [https://www.amazon.com/gp/product/B07D4L7GXZ Libre Computer Tritium H3] with a Cortex-A7 Sun7i SoC running at 1 GHz. A C/C++ SHA implementation runs about 22 cpb on the dev-board. Notice <tt>sha1-armv4.S</tt> was compiled with <tt>-march=armv7</tt>.

<pre>$ gcc -std=c99 -march=armv7 -c sha1-armv4.S -o sha1-armv7.o
$ gcc -O3 -std=c99 sha1-armv7-test.c sha1-armv7.o -o sha1-armv7-test.exe
$ ./sha1-armv7-test.exe
180994048 bytes
57.59 mbs
16.56 cpb</pre>

== iOS Builds ==

<tt>sha1-armv4</tt> can be configured for iOS. Simply use <tt>ios32</tt> or <tt>ios64</tt> instead of <tt>linux32</tt> as shown below.

<pre>$ perl sha1-armv4-large.pl ios32 sha1-armv4.S
$ clang -arch armv7 sha1-armv4.S -c</pre>

And then:

<pre>$ nm sha1-armv4.o
000012d0 s OPENSSL_armcap_P
00000004 C _OPENSSL_armcap_P
00000000 T _sha1_block_data_order
00001100 t sha1_block_data_order_armv8
00000560 t sha1_block_data_order_neon

$ otool -tV sha1-armv4.o
sha1-armv4.o:
(__TEXT,__text) section
_sha1_block_data_order:
00000000 f8dfc4ec ldr.w r12, [pc, #0x4ec]
00000004 f2af0308 subw r3, pc, #0x8
00000008 f853c00c ldr.w r12, [r3, r12]
0000000c f8dcc000 ldr.w r12, [r12]
00000010 f01c0f08 tst.w r12, #0x8
00000014 f0418074 bne.w sha1_block_data_order_armv8
00000018 f01c0f01 tst.w r12, #0x1
0000001c f04082a0 bne.w sha1_block_data_order_neon
00000020 e92d5ff0 push.w {r4, r5, r6, r7, r8, r9, r10, r11, r12, lr}
...</pre>
[[Category:Cryptogams]]

Talk:FIPS mode()

2019-08-09T19:06:17Z

Jflopezfernandez:

Feel free to edit the notice, especially in case anyone thinks it's too intense. I figured users should be immediately told if the functionality they're expecting but aren't getting isn't because of an error they on their end.

-- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 16:05, 9 August 2019 (UTC)

: I removed the notice and made some changes per Matt's request. The thread at the [[Talk:FIPS Mode|FIPS mode talk page]] has all of the details.
:
: -- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 19:06, 9 August 2019 (UTC)

Talk:FIPS Mode

2019-08-09T19:05:10Z

Jflopezfernandez:

The <tt>FIPS Mode</tt> link on the home page was broken, so I added a redirect as a stopgap, but I think it would be better to use this page to explain what FIPS mode is, and then include a link to the <tt>FIPS_mode()</tt> page.

-- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 15:31, 9 August 2019 (UTC)

Yes, I agree. And actually the FIPS_mode() page that you have redirected to would be better off as a man page in the source repo rather than as a wiki page. Of course in 1.1.1 this function doesn't do anything at all (although it exists). In 3.0 it will do something again, but that code needs to be implemented.

--[[User:Matt|Matt]] ([[User talk:Matt|talk]]) 15:36, 9 August 2019 (UTC)

: That's good to know, I actually didn't know that. I'll make a note of that on the <tt>FIPS_mode()</tt> page, as there's currently no indication it doesn't do anything right now.
:
: -- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 15:53, 9 August 2019 (UTC)

: Just to clarify my earlier comment. It does do something in 1.0.2 too. 1.0.2 is a FIPS capable release, 1.1.1 is not FIPS capable, 3.0 will be FIPS capable again. Confused yet? :-)
: --[[User:Matt|Matt]] ([[User talk:Matt|talk]]) 16:07, 9 August 2019 (UTC)

:: Oh, wow, now I really am confused. Can you take a look at the [[FIPS_mode()]] page? I added a notice based on the first thing you told me, but now I'm not sure it's right, and I don't want others to share in my current state of confusion haha.
::
:: -- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 16:20, 9 August 2019 (UTC)

::: No, it's not quite right. I'd remove the notice and add something in the body of the text saying that OpenSSL 1.1.0 and 1.1.1 are not FIPS capable and therefore this function always returns 0 in those releases
::: --[[User:Matt|Matt]] ([[User talk:Matt|talk]]) 16:24, 9 August 2019 (UTC)

:::: Okay, I just finished making the changes. Could I bother you again to take a look and let me know what you think? Thanks for the feedback.
:::: -- [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 19:05, 9 August 2019 (UTC)

FIPS mode()

2019-08-09T19:03:30Z

Jflopezfernandez: Removed the previously added notice and updated the page as per Matt's suggestions on the FIPS mode talk page.

The '''FIPS_mode()''' function is used to determine the current [[FIPS]] [[FIPS 140-2|140-2]] mode of operation by a program utilizing the services of the validated library. The library must have been built with the [[FIPS Object Module]], and the FIPS Object Module must have been acquired, built, and installed in accordance with the [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.16.pdf security policy].

The return value is either <tt>0</tt> to indicate that the FIPS mode of operation is not enabled, or the value used for the <tt>ONOFF</tt> parameter passed to an earlier successful call to <tt>FIPS_mode_set()</tt>. Effectively, any non-zero value indicates FIPS mode. Values other than <tt>1</tt> may have additional significance, such as designating an additional restriction to [[Suite B]] algorithms.

The only current [[FIPS]]-capable release of OpenSSL is version 1.0.2. Calling the function from an application linked to OpenSSL versions <tt>1.1.0</tt> or <tt>1.1.1</tt> will always return <tt>0</tt>, indicating non-FIPS mode, with an error code of <tt>CRYPTO_R_FIPS_MODE_NOT_SUPPORTED (0x0f06d065)</tt>.

= History =
FIPS support was introduced in version 0.9.7 of [https://www.openssl.org/ OpenSSL].

= Example =
To call the function, the OpenSSL <tt>crypto</tt> header must be included.

#include <openssl/crypto.h>

The function itself takes no parameters, and returns an integer indicating the mode of operation as described above.

int FIPS_MODE(void);

In the following example, the program tests the return value of the <tt>FIPS_mode()</tt> function call, exiting with an error if the library being linked to is not FIPS-capable. The return value of the function is saved because the return code may carry additional information, in addition to FIPS-capability (see above).

int fips_compatible_build = -1;

if ((fips_compatible_build = FIPS_mode()) == 0) {
fprintf(stderr, "The current version of OpenSSL is not FIPS-capable.\n");
exit(EXIT_FAILURE);
}

// ...

= See Also =
* FIPS_mode_set(3)
* FIPS_selftest(3)

= Notes =
<tt>FIPS_mode()</tt> was formerly included with <openssl/fips.h>.

= External Links =
* Information regarding the [https://www.openssl.org/docs/fips.html OpenSSL FIPS 140-2 validation] at the [https://www.openssl.org/ OpenSSL] project.
* [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.16.pdf OpenSSL Security Policy]

[[Category:FIPS 140-2]]
[[Category:Crypto API]]
[[Category:C level]]

Talk:FIPS Mode

2019-08-09T16:20:27Z

Jflopezfernandez:

Talk:FIPS mode()

2019-08-09T16:05:50Z

Jflopezfernandez: Created page with "Feel free to edit the notice, especially in case anyone thinks it's too intense. I figured users should be immediately told if the functionality they're expecting but aren't g..."

FIPS mode()

2019-08-09T16:03:45Z

Jflopezfernandez: Added a notice indicating the version in the current release has no functionality

{| class="wikitable" style="margin-left: auto; margin-right: auto; margin-top: 36px; margin-bottom: 36px; text-align: center; background-color: #FF8787; border: 1px solid #FA0000;"
| style="font-size: 16px; font-weight: bold; border: none; padding: 8px;" | Not Currently Implemented
|-
| style="border: none; padding-left: 16px; padding-right: 16px; padding-bottom: 8px;" | This function as currently implemented does nothing. It is part of the currently-planned 3.0.0 release, but has not yet been written.
|}

----
'''NAME'''

FIPS_mode - retrieve the current FIPS 140-2 mode of operation

----
'''SYNOPSIS'''

#include <openssl/crypto.h>

int FIPS_mode(void);

----
'''DESCRIPTION'''

FIPS_mode() is used to determine the FIPS mode of operation by a program utilizing the services of the validated library. The library must have been built with the FIPS Object Module, and the FIPS Object Module must have been acquired, built, and installed in accordance with the Security Policy.

The return value is either 0 to indicate that the FIPS mode of operation is not enabled, or the value used for the ONOFF parameter passed to an earlier successful call to FIPS_mode_set(). Effectively any non-zero value indicates FIPS mode; values other than 1 may have additional significance such as designating an additional restriction to Suite B algorithms.

If the library was built without support of the FIPS Object Module, then the function will return 0 with an error code of CRYPTO_R_FIPS_MODE_NOT_SUPPORTED (0x0f06d065).

----
'''RETURN VALUES'''

A return code of non-zero indicates FIPS mode, 0 indicates non-FIPS mode. When called from a version of OpenSSL that is not "FIPS capable" (capable of utilizing an embedded FIPS Object Module), then FIPS_mode() will always return 0.

----
'''SEE ALSO'''

FIPS_mode_set(3), FIPS_selftest(3)

----
'''NOTES'''

FIPS_mode() was formerly included with <openssl/fips.h>.

----
'''HISTORY'''

FIPS support was introduced in version 0.9.7 of OpenSSL.

[[Category:FIPS 140-2]]
[[Category:Crypto API]]
[[Category:C level]]

Talk:FIPS Mode

2019-08-09T15:53:51Z

Jflopezfernandez:

Base64

2019-08-09T15:34:33Z

Jflopezfernandez: Added page to the Examples and C level categories

Encode binary information 8 bits into ASCII.

This is PEM base encode, it exists other base64 encoding scheme like this used by crypt.

== Algorithm ==

3 x 8 bits binary are concatenated to form a 24bits word that is split in 4 x 6bits each being translating into an ascii value using a character ordered in following list :

<pre>
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0000000000111111111122222222223333333333444444444455555555556666
0123456789012345678901234567890123456789012345678901234567890123
</pre>

[what makes 26 * 2 + 10 + 2 = 64 values]

Since it encodes by group of 3 bytes, when last group of 3 bytes miss one byte then = is used, when it miss 2 bytes then == is used for padding.

== Openssl command ==

base64 or -enc base64 can be used to decode lines see [[Command_Line_Utilities]]

== EVP API ==

crypto/evp/encode.c
crypto/evp/bio_b64.C

If you need to encode a block of data, use the '''<tt>EVP_EncodeBlock</tt>''' function, example:
<pre>
unsigned char sourceData[16] = {0x30,0x82,0x07,0x39,0x30,0x82,0x05,0x21,0xA0,0x03,0x02,0x01,0x02,0x02,0x04,0x00};
char encodedData[100];
EVP_EncodeBlock((unsigned char *)encodedData, sourceData, 16);
printf(encodedData);
</pre>

=== WARNINGS ===

=== other unsupported base64 scheme ===

Warning crypt() password encryption function uses another base64 scheme which is not the openssl base64 one. :

<pre>
./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0000000000111111111122222222223333333333444444444455555555556666
0123456789012345678901234567890123456789012345678901234567890123
</pre>

=== base64 uses PEM 80 characters per line ===

Base64 itself does not impose a line split, but openssl uses it in PEM context hence enforce that base64 content is splitted by lines with a maximum of 80 characters.

With C code it is possible to ask to disregard lines breaks : BIO_set_flags(d,BIO_FLAGS_BASE64_NO_NL);

[[Category:Encoding]]
[[Category:Examples]]
[[Category:C level]]

Talk:FIPS Mode

2019-08-09T15:31:34Z

Jflopezfernandez: Created page with "The <tt>FIPS Mode</tt> link on the home page was broken, so I added a redirect as a stopgap, but I think it would be better to use this page to explain what FIPS mode is, and..."

FIPS Mode

2019-08-09T15:26:48Z

Jflopezfernandez: Created as a redirect to the FIPS_mode(), as it did not currently exist

#REDIRECT [[FIPS_mode()]]

Template:Broken Link

2019-08-06T05:56:01Z

Jflopezfernandez: Modified so that the template itself is not included in the category of all pages with a broken link

[[:Category:Broken Links|[Broken Link]]]

<noinclude>
==Overview==
The purpose of this template is to group all of the outstanding broken links in the wiki into the [[:Category:Broken Links|broken links]] category.
</noinclude>

<includeonly>
[[Category:Broken Links]]
</includeonly>

Command Line Utilities

2019-07-30T21:11:58Z

Jflopezfernandez: Added section on 1-step ecc key generation, as per Matt's suggestion on the discussion page

The '''openssl''' program provides a rich variety of commands, each of which often has a wealth of options and arguments. Many commands use an external configuration file for some or all of their arguments and have a <code>-config</code> option to specify that file. The environment variable [[OPENSSL_CONF]] can be used to specify the location of the configuration file. If the environment variable is not specified, a default file is created in the default certificate storage area called '''openssl.cnf'''. The settings in this default configuration file depend on the flags set when the version of OpenSSL being used was built.

This article is an overview of the available tools provided by openssl. For all of the details on usage and implementation, you can find the [https://www.openssl.org/docs/manmaster/ manpages] which are automatically generated from the source code at the [https://www.openssl.org/ official OpenSSL project home]. Likewise, the source code itself may be found on the [https://www.openssl.org/source/ OpenSSL project home page], as well as on the [https://github.com/openssl/openssl OpenSSL Github]. The main OpenSSL site also includes an [https://www.openssl.org/docs/manmaster/man1/openssl.html overview of the command-line utilities], as well as links to all of their respective documentation.

=Getting Started=

The entry point for the OpenSSL library is the '''openssl''' binary, usually <tt>/usr/bin/openssl</tt> on Linux. The general syntax for calling openssl is as follows:

$ openssl command [ command_options ] [ command_arguments ]

Alternatively, you can call openssl without arguments to enter the interactive mode prompt. You may then enter commands directly, exiting with either a <code>quit</code> command or by issuing a termination signal with either <tt>Ctrl+C</tt> or <tt>Ctrl+D</tt>. The following is a sample interactive session in which the user invokes the [[prime]] command twice before using the <tt>quit</tt> command to terminate the session.

OpenSSL> prime -generate -bits 24
13467269
OpenSSL> prime -generate -bits 24
16651079
OpenSSL> quit

=Basic Tasks=

This section is a brief tutorial on performing the most basic tasks using OpenSSL. For a detailed explanation of the rationale behind the syntax and semantics of the commands shown here, see the section on [[#Commands|Commands]].

==Getting Help==

As mentioned previously, the general syntax of a command is <code>openssl command [ command_options ] [ command_arguments ]</code>. The help command is no different, but it does have its idiosyncrasies. To view the top-level help menu, you can call openssl as follows.

$ openssl help

This query will print all of the available commands, like so:

Standard commands
asn1parse ca ciphers cms
crl crl2pkcs7 dgst dhparam
dsa dsaparam ec ecparam
...

Note the above output was truncated, so only the first four lines of output are shown.

A help menu for each command may be requested in two different ways. First, the same command used above may be repeated, followed by the name of the command to print help for.

$ openssl help genpkey

The program will then display the valid options for the given command.

$ openssl help genpkey
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

The second way of requesting the help menu for a particular command is by using the first option in the output shown above, namely <code>openssl command -help</code>. Both commands will yield the same output; the help menu displayed will be exactly the same.

$ openssl genpkey -help
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

For additional information on the usage of a particular command, the project [https://www.openssl.org/docs/manpages.html manpages] are a great source of information. Another excellent source of information is the project perldocs. [https://perldoc.perl.org/5.30.0/perldoc.html perldoc] is a utility included with most if not all [https://www.perl.org/ Perl] distributions, and it's capable of displaying documentation information in a variety of formats, one of which is as manpages. Not surprisingly, the project documentation is generated from the pod files located in the <tt>doc</tt> directory of the source code.

==Getting Library Version Information==

$ openssl version
OpenSSL 1.1.1c 28 May 2019

As mentioned above, the <tt>version</tt> command's help menu may be queried for additional options like so:

$ openssl version -help
Usage: version [options]
Valid options are:
-help Display this summary
-a Show all data
-b Show build date
-d Show configuration directory
-e Show engines directory
-f Show compiler flags used
-o Show some internal datatype options
-p Show target build platform
-r Show random seeding options
-v Show library version

Using the <tt>-a</tt> option to show all version information yields the following output on my current machine:

$ openssl version -a
OpenSSL 1.1.1c 28 May 2019
built on: Tue May 28 16:23:39 2019 UTC
platform: linux-x86_64
options: bn(64,64) rc4(16x,int) des(int) idea(int) blowfish(ptr)
compiler: gcc -fPIC -pthread -m64 -Wa,--noexecstack -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wa,--noexecstack -D_FORTIFY_SOURCE=2 -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now -DOPENSSL_USE_NODELETE -DL_ENDIAN -DOPENSSL_PIC -DOPENSSL_CPUID_OBJ -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT -DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DKECCAK1600_ASM -DRC4_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM -DGHASH_ASM -DECP_NISTZ256_ASM -DX25519_ASM -DPOLY1305_ASM -DNDEBUG -D_FORTIFY_SOURCE=2
OPENSSLDIR: "/etc/ssl"
ENGINESDIR: "/usr/lib/engines-1.1"
Seeding source: os-specific

==Generating an RSA Private Key==

Generating a private key can be done in a variety of different ways depending on the type of key, algorithm, bits, and other options your specific use case may require. In this example, we are generating a private key using RSA and a key size of 2048 bits.

$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

To generate a password protected private key, the previous command may be slightly amended as follows:

$ openssl genpkey -aes256 -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

The addition of the <tt>-aes256</tt> option specifies the cipher to use to encrypt the private key file. For a list of available ciphers in the library, you can run the following command:

$ openssl list -cipher-algorithms

With your private key in hand, you can use the following command to see the key's details, such as its modulus and its constituent primes. Remember to change the name of the input file to the file name of your private key.

$ openssl pkey -in private-key.pem -text

The above command yields the following output in my specific case. Your output will differ but should be structurally similar.

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDZD6IMLRFk4CaF
w0rhRienwuE5EZ6xFE8e3C5TVi1+d9Enhi38RgkwD7UlWxPE6AWhp5T3kfrFWdak
1lZFVPp7/btOKLjKUru15nLoA4AKYtz9W9PhsM0dyzLc6FQ6K4ReQam5pHCqI2zF
82MwE+eIAduvuqyoQLKiI608EArWZqDtMUpBJzv0UVEYvRdnMWpCwfzpI+hPJywV
CcTlNCT/ctGgBKyIx+dDuZ7bR9MNmSW7GreJEbTH+R13xT3dd/JCka1+LYCl4h0q
oWhFPhOkvQzmmSzUmZlAlTDQLv2eAdJIrQcsnKZ3SsIOCC/3IpqwSzpid38Ill4O
xH6XIrVFAgMBAAECggEBAJ2MC0JrM8TULSHJrf/0u7O4b2DMuTIuW386sSUr17mD
nfviGF6TNvf7bq++e4rgHbZHvIg1HJ9Bpdne+J86HtUARYNlazru8fAFZEGiyLzB
JUV/8TpO6ZJGepR8zSWrkFgZsOddw6i6LalADy5GRDcjoiDajZdR3lZxLrv5qOQU
I1vKTf4Zs2Tl3gnaJ/Il1gBHIQ9W9xUH8jPBIwj51iXwCh8H0BiDPvFkU7cHIFCP
sJhGsGp6OS3uSwwQuSE+NqbuPfVilysCcwgZduknyio0QO1YfMBL6+XoKE/bFHsn
N+FzzczQg9sWyiwVR+3EeI9kp4JSElNh2nqG96i4QAECgYEA76OLUGrShHb4saoP
aYnBAKLEdWj5K483JdY6BSbdd5RkDbJG8ExmcbfTas/BGdKc4iVCkxV3ysxKnX18
PfxATHDLL8NMa+gGgZY5oTKUsrXEpS132HhCJ9T9LoesQjRb4kOZH8POVqm6O4Xf
lCt0y1+M1eQHI1NPO9CmPBgouEUCgYEA5+F4SS8RMyYRkU/kx195fwh0hhaOElzr
E8mZou3NFL/XT6/9t+2+7sMTuiQCP9zIa6s+/rrXdjWtrTcDp4WlDITas0UUgZhv
YVBQBF4vhHxIVwJxnT9Gwi4XM1JlFmVHofWD71P6DRe7jSWRS3CujP3AE9vmpWMx
tE1D9qLiWQECgYB445LzFYBvrKjWz4iI4CJKFNJwvGz+iXfzkXehg7KzkVtMAYSB
0rjXYzm3J2ktgq778nn8Qxc0agy2GEil6GvzY+9MgAQ8Z0do9gTKif6zjLjP7vkH
bdtJxsuWPoEqwMkdgqZrfNbJp0O4pVddovJ/agtdF3R2YJ+W+DH0HOfl1QKBgFnM
c2zEEYEhaQRBUHP1gXO0rouPCI4L9e2/0QPL2/QBJzzxBuzH4X1NhsI7V7OrqOIp
e0fiy7Y3q369I2ko1HY4rQln4z0c72VcWOCYKQbBqrInfCBNdPWWK93wNr2pk0gh
cGqqtteDLVrIBbCVfsOTMWN/cZ7y/zi4A23sPoQBAoGAEPzcIjOyoB97Pzd7iNim
Gin8RkwXIiFGSHo8vAh74CKBNokThM50OUNm5T2eJ4huzPpowQ+ID1mB5EjEai9n
JY9ll3cUpawiIIW/6uGTHyXfvZWNtqEYXrVJ6fcDaKcW4y3cplNj/SJaBW8HXsW7
YGHW3zHsgy7EOAOzPwlm9oE=
-----END PRIVATE KEY-----
RSA Private-Key: (2048 bit, 2 primes)
modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
publicExponent: 65537 (0x10001)
privateExponent:
00:9d:8c:0b:42:6b:33:c4:d4:2d:21:c9:ad:ff:f4:
bb:b3:b8:6f:60:cc:b9:32:2e:5b:7f:3a:b1:25:2b:
d7:b9:83:9d:fb:e2:18:5e:93:36:f7:fb:6e:af:be:
7b:8a:e0:1d:b6:47:bc:88:35:1c:9f:41:a5:d9:de:
f8:9f:3a:1e:d5:00:45:83:65:6b:3a:ee:f1:f0:05:
64:41:a2:c8:bc:c1:25:45:7f:f1:3a:4e:e9:92:46:
7a:94:7c:cd:25:ab:90:58:19:b0:e7:5d:c3:a8:ba:
2d:a9:40:0f:2e:46:44:37:23:a2:20:da:8d:97:51:
de:56:71:2e:bb:f9:a8:e4:14:23:5b:ca:4d:fe:19:
b3:64:e5:de:09:da:27:f2:25:d6:00:47:21:0f:56:
f7:15:07:f2:33:c1:23:08:f9:d6:25:f0:0a:1f:07:
d0:18:83:3e:f1:64:53:b7:07:20:50:8f:b0:98:46:
b0:6a:7a:39:2d:ee:4b:0c:10:b9:21:3e:36:a6:ee:
3d:f5:62:97:2b:02:73:08:19:76:e9:27:ca:2a:34:
40:ed:58:7c:c0:4b:eb:e5:e8:28:4f:db:14:7b:27:
37:e1:73:cd:cc:d0:83:db:16:ca:2c:15:47:ed:c4:
78:8f:64:a7:82:52:12:53:61:da:7a:86:f7:a8:b8:
40:01
prime1:
00:ef:a3:8b:50:6a:d2:84:76:f8:b1:aa:0f:69:89:
c1:00:a2:c4:75:68:f9:2b:8f:37:25:d6:3a:05:26:
dd:77:94:64:0d:b2:46:f0:4c:66:71:b7:d3:6a:cf:
c1:19:d2:9c:e2:25:42:93:15:77:ca:cc:4a:9d:7d:
7c:3d:fc:40:4c:70:cb:2f:c3:4c:6b:e8:06:81:96:
39:a1:32:94:b2:b5:c4:a5:2d:77:d8:78:42:27:d4:
fd:2e:87:ac:42:34:5b:e2:43:99:1f:c3:ce:56:a9:
ba:3b:85:df:94:2b:74:cb:5f:8c:d5:e4:07:23:53:
4f:3b:d0:a6:3c:18:28:b8:45
prime2:
00:e7:e1:78:49:2f:11:33:26:11:91:4f:e4:c7:5f:
79:7f:08:74:86:16:8e:12:5c:eb:13:c9:99:a2:ed:
cd:14:bf:d7:4f:af:fd:b7:ed:be:ee:c3:13:ba:24:
02:3f:dc:c8:6b:ab:3e:fe:ba:d7:76:35:ad:ad:37:
03:a7:85:a5:0c:84:da:b3:45:14:81:98:6f:61:50:
50:04:5e:2f:84:7c:48:57:02:71:9d:3f:46:c2:2e:
17:33:52:65:16:65:47:a1:f5:83:ef:53:fa:0d:17:
bb:8d:25:91:4b:70:ae:8c:fd:c0:13:db:e6:a5:63:
31:b4:4d:43:f6:a2:e2:59:01
exponent1:
78:e3:92:f3:15:80:6f:ac:a8:d6:cf:88:88:e0:22:
4a:14:d2:70:bc:6c:fe:89:77:f3:91:77:a1:83:b2:
b3:91:5b:4c:01:84:81:d2:b8:d7:63:39:b7:27:69:
2d:82:ae:fb:f2:79:fc:43:17:34:6a:0c:b6:18:48:
a5:e8:6b:f3:63:ef:4c:80:04:3c:67:47:68:f6:04:
ca:89:fe:b3:8c:b8:cf:ee:f9:07:6d:db:49:c6:cb:
96:3e:81:2a:c0:c9:1d:82:a6:6b:7c:d6:c9:a7:43:
b8:a5:57:5d:a2:f2:7f:6a:0b:5d:17:74:76:60:9f:
96:f8:31:f4:1c:e7:e5:d5
exponent2:
59:cc:73:6c:c4:11:81:21:69:04:41:50:73:f5:81:
73:b4:ae:8b:8f:08:8e:0b:f5:ed:bf:d1:03:cb:db:
f4:01:27:3c:f1:06:ec:c7:e1:7d:4d:86:c2:3b:57:
b3:ab:a8:e2:29:7b:47:e2:cb:b6:37:ab:7e:bd:23:
69:28:d4:76:38:ad:09:67:e3:3d:1c:ef:65:5c:58:
e0:98:29:06:c1:aa:b2:27:7c:20:4d:74:f5:96:2b:
dd:f0:36:bd:a9:93:48:21:70:6a:aa:b6:d7:83:2d:
5a:c8:05:b0:95:7e:c3:93:31:63:7f:71:9e:f2:ff:
38:b8:03:6d:ec:3e:84:01
coefficient:
10:fc:dc:22:33:b2:a0:1f:7b:3f:37:7b:88:d8:a6:
1a:29:fc:46:4c:17:22:21:46:48:7a:3c:bc:08:7b:
e0:22:81:36:89:13:84:ce:74:39:43:66:e5:3d:9e:
27:88:6e:cc:fa:68:c1:0f:88:0f:59:81:e4:48:c4:
6a:2f:67:25:8f:65:97:77:14:a5:ac:22:20:85:bf:
ea:e1:93:1f:25:df:bd:95:8d:b6:a1:18:5e:b5:49:
e9:f7:03:68:a7:16:e3:2d:dc:a6:53:63:fd:22:5a:
05:6f:07:5e:c5:bb:60:61:d6:df:31:ec:83:2e:c4:
38:03:b3:3f:09:66:f6:81

Keep in mind the above key was generated solely for pedagogical purposes; never give anyone access to your private keys.

==Generating a Public Key==

Having previously generated your private key, you may generate the corresponding public key using the following command.

$ openssl pkey -in private-key.pem -out public-key.pem -pubout

You may once again view the key details, using a slightly different command this time.

$ openssl pkey -in public-key.pem -pubin -text

The output for the public key will be shorter, as it carries much less information, and it will look something like this.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2Q+iDC0RZOAmhcNK4UYn
p8LhORGesRRPHtwuU1YtfnfRJ4Yt/EYJMA+1JVsTxOgFoaeU95H6xVnWpNZWRVT6
e/27Tii4ylK7teZy6AOACmLc/VvT4bDNHcsy3OhUOiuEXkGpuaRwqiNsxfNjMBPn
iAHbr7qsqECyoiOtPBAK1mag7TFKQSc79FFRGL0XZzFqQsH86SPoTycsFQnE5TQk
/3LRoASsiMfnQ7me20fTDZkluxq3iRG0x/kdd8U93XfyQpGtfi2ApeIdKqFoRT4T
pL0M5pks1JmZQJUw0C79ngHSSK0HLJymd0rCDggv9yKasEs6Ynd/CJZeDsR+lyK1
RQIDAQAB
-----END PUBLIC KEY-----
RSA Public-Key: (2048 bit)
Modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
Exponent: 65537 (0x10001)

For more information on generating keys, see the source code documentation, located in the <tt>doc/HOWTO/keys.txt</tt> file.

==Generating Keys Based on Elliptic Curves==

There are essentially two steps to generating a key:

# Generate the parameters for the specific curve you are using
# Use those parameters to generate the key

To see the list of curves instrinsically supported by openssl, you can use the <tt>-list_curves</t> option when calling the <tt>ecparam</tt> command.

$ openssl ecparam -list_curves
secp112r1 : SECG/WTLS curve over a 112 bit prime field
secp112r2 : SECG curve over a 112 bit prime field
secp128r1 : SECG curve over a 128 bit prime field
secp128r2 : SECG curve over a 128 bit prime field
secp160k1 : SECG curve over a 160 bit prime field
...

For this example I will use the <tt>prime256v1</tt> curve, which is an <tt>X9.62/SECG</tt> curve over a 256 bit prime field.

===Generating the Curve Parameters===

Having selected our curve, we now call <tt>ecparam</tt> to generate our parameters file.

$ openssl ecparam -name prime256v1 -out prime256v1.pem

====Printing Parameters to Standard Out====

You can print the generated curve parameters to the terminal output with the following command:

$ openssl ecparam -in prime256v1.pem -noout -text
ASN1 OID: prime256v1
NIST CURVE: P-256

====Printing Parameters as C Code====

Analogously, you may also output the generated curve parameters as C code. The parameters can then be loaded by calling the <tt>get_ec_group_XXX()</tt> function. To print the C code to the current terminal's output, the following command may be used:

$ openssl ecparam -in prime256v1.pem -noout -C

And here are the first few lines of the corresponding output:

EC_GROUP *get_ec_group_256(void)
{
static unsigned char ec_p_256[] = {
0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
...

===Generating the Key===

With the curve parameters in hand, we are now free to generate the key. Just as with the [#Generating an RSA Private Key|RSA] example above, we may optionally specify a cipher algorithm with which to encrypt the private key. The call to generate the key using the elliptic curve parameters generated in the example above looks like this:

$ openssl genpkey -aes256 -paramfile prime256v1.pem -out private-key.pem
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

===Putting it All Together===

The process of generation a curve based on elliptic-curves can be streamlined by calling the <tt>genpkey</tt> command directly and specifying both the algorithm and the name of the curve to use for parameter generation. In it's simplest form, the command to generate a key based on the same curve as in the example above looks like this:

$ openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256

This command will result in the generated key being printed to the terminal's output.

$ openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256

-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgqqYoJGowXJ5/GTkB
SRLnBMNWLoQ2RM/QxrY+bfDDGRahRANCAASPY4eTANkwIIAWhh32eoFl2YFLJSWy
bdITdZ82O5JDpDijmGmJ2hepe5afek9WVqxMPYjmbTwMPO3xMGbqUiJD
-----END PRIVATE KEY-----

Remember that you can specify a cipher algorithm to encrypt the key with, which something you may or may not want to do, depending on your specific use case. Here is a slightly more complete example showing a key generated with a password and written to a specific output file.

$ openssl genpkey -aes256 -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

Just as with the previous example, you can use the <tt>pkey</tt> command to inspect your newly-generated key.

$ openssl pkey -in private-key.pem -text
Enter pass phrase for private-key.pem:
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgEO7CxgTwi0hsjdbp
sXWuU2x2flLthxqXabYDOqOZCvuhRANCAAQVTLkeCBJdvMnqwZKYJxrPvTTuanrD
NkyAPQCARKsQ7bVrP6ky/5uAcAvjuZB0xKCcSp7roXLWRzD/y/ik8P5R
-----END PRIVATE KEY-----
Private-Key: (256 bit)
priv:
10:ee:c2:c6:04:f0:8b:48:6c:8d:d6:e9:b1:75:ae:
53:6c:76:7e:52:ed:87:1a:97:69:b6:03:3a:a3:99:
0a:fb
pub:
04:15:4c:b9:1e:08:12:5d:bc:c9:ea:c1:92:98:27:
1a:cf:bd:34:ee:6a:7a:c3:36:4c:80:3d:00:80:44:
ab:10:ed:b5:6b:3f:a9:32:ff:9b:80:70:0b:e3:b9:
90:74:c4:a0:9c:4a:9e:eb:a1:72:d6:47:30:ff:cb:
f8:a4:f0:fe:51
ASN1 OID: prime256v1
NIST CURVE: P-256

For more details on elliptic curve cryptography or key generation, check out the [https://www.openssl.org/docs/manpages.html manpages].

==Base64 Encoding Strings==

For simple string encoding, you can use "here string" syntax with the [[Base64 Encoding|base64]] command as below. Intuitively, the <tt>-e</tt> flag specifies the action to be encoding.

$ openssl base64 -e <<< 'Welcome to openssl wiki'
V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK

Similarly, the base64 command's <tt>-d</tt> flag may be used to indicate decoding mode.

$ openssl base64 -d <<< 'V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK'
Welcome to openssl wiki

==Generating a File Hash==

One of the most basic uses of the [[dgst]] command (short for digest) is viewing the hash of a given file. To do this, simply invoke the command with the specified digest algorithm to use. For this example, I will be hashing an arbitrary file on my system using the [[MD5]], [[SHA1]], and [[SHA384]] algorithms.

$ openssl dgst -md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl dgst -sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl dgst -sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

For a list of the available digest algorithms, you can use the following command.

$ openssl list -digest-algorithms
RSA-MD4 => MD4
RSA-MD5 => MD5
RSA-MDC2 => MDC2
RSA-RIPEMD160 => RIPEMD160
RSA-SHA1 => SHA1
RSA-SHA1-2 => RSA-SHA1
...

You can also use a similar command to see the available [[Digest Commands|digest commands]]:

$ openssl list -digest-commands
blake2b512 blake2s256 gost md4
md5 mdc2 rmd160 sha1
sha224 sha256 sha3-224 sha3-256
sha3-384 sha3-512 sha384 sha512
sha512-224 sha512-256 shake128 shake256
sm3

Below are three sample invocations of the [[md5]], [[sha1]], and [[sha384]] digest commands using the same file as the [[dgst]] command invocation above.

$ openssl md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

==File Encryption and Decryption==

The following example demonstrates a simple file encryption and decryption using the [[enc]] command. The first argument is the cipher algorithm to use for encrypting the file. For this example I carefully selected the [[AES-256]] algorithm in [[CBC Mode]] by looking up the available ciphers and picking out the first one I saw. To see the list of available ciphers, you can use the following command.

$ openssl enc -ciphers
Supported ciphers:
-aes-128-cbc -aes-128-cfb -aes-128-cfb1
-aes-128-cfb8 -aes-128-ctr -aes-128-ecb
-aes-128-ofb -aes-192-cbc -aes-192-cfb
-aes-192-cfb1 -aes-192-cfb8 -aes-192-ctr
...

You can also use the following command:

$ openssl list -cipher-algorithms
AES-128-CBC
AES-128-CBC-HMAC-SHA1
AES-128-CBC-HMAC-SHA256
id-aes128-CCM
AES-128-CFB
AES-128-CFB1
AES-128-CFB8
AES-128-CTR
...

Having selected an encryption algorithm, you must then specify whether the action you are taking is either encryption or decryption via the <tt>-e</tt> or <tt>-d</tt> flags, respectively. The <tt>-iter</tt> flag specifies the number of iterations on the password used for deriving the encryption key. A higher iteration count increases the time required to brute-force the resulting file. Using this option implies enabling use of the [[Password-Based Key Derivation Function 2]], usually set using the <tt>-pbkdf2</tt> flag. We then use the <tt>-salt</tt> flag to enable the use of a randomly generated salt in the key-derivation function.

Putting it all together, you can see the command to encrypt a file and the corresponding output below. Note that the passwords entered by the user are blank, just as they would usually be in a terminal session.

$ openssl enc -aes-256-cbc -e -iter 1000 -salt -in primes.dat -out primes.enc
enter aes-256-cbc encryption password:
Verifying - enter aes-256-cbc encryption password:

The analogous decryption command is as follows:

$ openssl enc -aes-256-cbc -d -iter 1000 -in primes.enc -out primes.dec
enter aes-256-cbc decryption password:

=Commands=

There are three different kinds of commands. These are [[Standard commands|standard commands]], [[Cipher commands|cipher commands]], and [[Digest comands|digest commands]]. Calling the OpenSSL top-level <tt>help</tt> command with no arguments will result in openssl printing all available commands by group, sorted alphabetically.

==Standard Commands==

{| class="wikitable" style="margin:auto; text-align: center; width: 65%;"
|+ Overview of OpenSSL's command line utilities
! style="width: 25%; padding: 4px;" | Command
! style="width: 75%; padding: 4px;" | Description
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/asn1parse.html asn1parse]
|style="padding: 4px;" | Parse an ASN.1 sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ca.html ca]
|style="padding: 4px;" | Certificate Authority (CA) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ciphers.html ciphers]
|style="padding: 4px;" | Cipher Suite Description Determination.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/cms.html cms]
|style="padding: 4px;" | CMS (Cryptographic Message Syntax) utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl.html crl]
|style="padding: 4px;" | Certificate Revocation List (CRL) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl2pkcs7.html crl2pkcs7]
|style="padding: 4px;" | CRL to PKCS#7 Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dgst.html dgst]
|style="padding: 4px;" | Message Digest calculation. MAC calculations are superseded by mac(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dhparam.html dhparam]
|style="padding: 4px;" | Generation and Management of Diffie-Hellman Parameters. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsa.html dsa]
|style="padding: 4px;" | DSA Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsaparam.html dsaparam]
|style="padding: 4px;" | DSA Parameter Generation and Management. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ec.html ec]
|style="padding: 4px;" | EC (Elliptic curve) key processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ecparam.html ecparam]
|style="padding: 4px;" | EC parameter manipulation and generation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/enc.html enc]
|style="padding: 4px;" | Encoding with Ciphers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/engine.html engine]
|style="padding: 4px;" | Engine (loadable module) information and manipulation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/errstr.html errstr]
|style="padding: 4px;" | Error Number to Error String Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/gendsa.html gendsa]
|style="padding: 4px;" | Generation of DSA Private Key from Parameters. Superseded by genpkey(1) and pkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genpkey.html genpkey]
|style="padding: 4px;" | Generation of Private Key or Parameters.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genrsa.html genrsa]
|style="padding: 4px;" | Generation of RSA Private Key. Superseded by genpkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/info.html info]
|style="padding: 4px;" | Display diverse information built into the OpenSSL libraries.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/kdf.html kdf]
|style="padding: 4px;" | Key Derivation Functions.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/mac.html mac]
|style="padding: 4px;" | Message Authentication Code Calculation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/nseq.html nseq]
|style="padding: 4px;" | Create or examine a Netscape certificate sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ocsp.html ocsp]
|style="padding: 4px;" | Online Certificate Status Protocol utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/passwd.html passwd]
|style="padding: 4px;" | Generation of hashed passwords.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs12.html pkcs12]
|style="padding: 4px;" | PKCS#12 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs7.html pkcs7]
|style="padding: 4px;" | PKCS#7 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs8.html pkcs8]
|style="padding: 4px;" | PKCS#8 format private key conversion tool.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkey.html pkey]
|style="padding: 4px;" | Public and private key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyparam.html pkeyparam]
|style="padding: 4px;" | Public key algorithm parameter management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyutl.html pkeyutl]
|style="padding: 4px;" | Public key algorithm cryptographic operation utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/prime.html prime]
|style="padding: 4px;" | Compute prime numbers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rand.html rand]
|style="padding: 4px;" | Generate pseudo-random bytes.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rehash.html rehash]
|style="padding: 4px;" | Create symbolic links to certificate and CRL files named by the hash values.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/req.html req]
|style="padding: 4px;" | PKCS#10 X.509 Certificate Signing Request (CSR) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsa.html rsa]
|style="padding: 4px;" | RSA key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsautl.html rsautl]
|style="padding: 4px;" | RSA utility for signing, verification, encryption, and decryption. Superseded by pkeyutl(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_client.html s_client]
|style="padding: 4px;" | This implements a generic SSL/TLS client which can establish a transparent connection to a remote server speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_server.html s_server]
|style="padding: 4px;" | This implements a generic SSL/TLS server which accepts connections from remote clients speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_time.html s_time]
|style="padding: 4px;" | SSL Connection Timer.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/sess_id.html sess_id]
|style="padding: 4px;" | SSL Session Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/smime.html smime]
|style="padding: 4px;" | S/MIME mail processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/speed.html speed]
|style="padding: 4px;" | Algorithm Speed Measurement.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/spkac.html spkac]
|style="padding: 4px;" | SPKAC printing and generating utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/srp.html srp]
|style="padding: 4px;" | Maintain SRP password file.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/storeutl.html storeutl]
|style="padding: 4px;" | Utility to list and display certificates, keys, CRLs, etc.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ts.html ts]
|style="padding: 4px;" | Time Stamping Authority tool (client/server).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/verify.html verify]
|style="padding: 4px;" | X.509 Certificate Verification.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/version.html version]
|style="padding: 4px;" | OpenSSL Version Information.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/x509.html x509]
|style="padding: 4px;" | X.509 Certificate Data Management.
|}

= Further reading =

* Paul Heinlein. [https://www.madboa.com/geek/openssl/ "OpenSSL Command-Line HOWTO"]. Has many quick cookbook-style recipes for doing common tasks using the "oppenssl" command-line application.

[[Category:Examples]]
[[Category:Shell level]]

Talk:Command Line Utilities

2019-07-30T15:27:51Z

Jflopezfernandez: Replying to thread

Command Line Utilities

2019-07-30T04:40:56Z

Jflopezfernandez: Corrected spelling of the prime command

The '''openssl''' program provides a rich variety of commands, each of which often has a wealth of options and arguments. Many commands use an external configuration file for some or all of their arguments and have a <code>-config</code> option to specify that file. The environment variable [[OPENSSL_CONF]] can be used to specify the location of the configuration file. If the environment variable is not specified, a default file is created in the default certificate storage area called '''openssl.cnf'''. The settings in this default configuration file depend on the flags set when the version of OpenSSL being used was built.

This article is an overview of the available tools provided by openssl. For all of the details on usage and implementation, you can find the [https://www.openssl.org/docs/manmaster/ manpages] which are automatically generated from the source code at the [https://www.openssl.org/ official OpenSSL project home]. Likewise, the source code itself may be found on the [https://www.openssl.org/source/ OpenSSL project home page], as well as on the [https://github.com/openssl/openssl OpenSSL Github]. The main OpenSSL site also includes an [https://www.openssl.org/docs/manmaster/man1/openssl.html overview of the command-line utilities], as well as links to all of their respective documentation.

=Getting Started=

The entry point for the OpenSSL library is the '''openssl''' binary, usually <tt>/usr/bin/openssl</tt> on Linux. The general syntax for calling openssl is as follows:

$ openssl command [ command_options ] [ command_arguments ]

Alternatively, you can call openssl without arguments to enter the interactive mode prompt. You may then enter commands directly, exiting with either a <code>quit</code> command or by issuing a termination signal with either <tt>Ctrl+C</tt> or <tt>Ctrl+D</tt>. The following is a sample interactive session in which the user invokes the [[prime]] command twice before using the <tt>quit</tt> command to terminate the session.

OpenSSL> prime -generate -bits 24
13467269
OpenSSL> prime -generate -bits 24
16651079
OpenSSL> quit

=Basic Tasks=

This section is a brief tutorial on performing the most basic tasks using OpenSSL. For a detailed explanation of the rationale behind the syntax and semantics of the commands shown here, see the section on [[#Commands|Commands]].

==Getting Help==

As mentioned previously, the general syntax of a command is <code>openssl command [ command_options ] [ command_arguments ]</code>. The help command is no different, but it does have its idiosyncrasies. To view the top-level help menu, you can call openssl as follows.

$ openssl help

This query will print all of the available commands, like so:

Standard commands
asn1parse ca ciphers cms
crl crl2pkcs7 dgst dhparam
dsa dsaparam ec ecparam
...

Note the above output was truncated, so only the first four lines of output are shown.

A help menu for each command may be requested in two different ways. First, the same command used above may be repeated, followed by the name of the command to print help for.

$ openssl help genpkey

The program will then display the valid options for the given command.

$ openssl help genpkey
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

The second way of requesting the help menu for a particular command is by using the first option in the output shown above, namely <code>openssl command -help</code>. Both commands will yield the same output; the help menu displayed will be exactly the same.

$ openssl genpkey -help
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

For additional information on the usage of a particular command, the project [https://www.openssl.org/docs/manpages.html manpages] are a great source of information. Another excellent source of information is the project perldocs. [https://perldoc.perl.org/5.30.0/perldoc.html perldoc] is a utility included with most if not all [https://www.perl.org/ Perl] distributions, and it's capable of displaying documentation information in a variety of formats, one of which is as manpages. Not surprisingly, the project documentation is generated from the pod files located in the <tt>doc</tt> directory of the source code.

==Getting Library Version Information==

$ openssl version
OpenSSL 1.1.1c 28 May 2019

As mentioned above, the <tt>version</tt> command's help menu may be queried for additional options like so:

$ openssl version -help
Usage: version [options]
Valid options are:
-help Display this summary
-a Show all data
-b Show build date
-d Show configuration directory
-e Show engines directory
-f Show compiler flags used
-o Show some internal datatype options
-p Show target build platform
-r Show random seeding options
-v Show library version

Using the <tt>-a</tt> option to show all version information yields the following output on my current machine:

$ openssl version -a
OpenSSL 1.1.1c 28 May 2019
built on: Tue May 28 16:23:39 2019 UTC
platform: linux-x86_64
options: bn(64,64) rc4(16x,int) des(int) idea(int) blowfish(ptr)
compiler: gcc -fPIC -pthread -m64 -Wa,--noexecstack -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wa,--noexecstack -D_FORTIFY_SOURCE=2 -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now -DOPENSSL_USE_NODELETE -DL_ENDIAN -DOPENSSL_PIC -DOPENSSL_CPUID_OBJ -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT -DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DKECCAK1600_ASM -DRC4_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM -DGHASH_ASM -DECP_NISTZ256_ASM -DX25519_ASM -DPOLY1305_ASM -DNDEBUG -D_FORTIFY_SOURCE=2
OPENSSLDIR: "/etc/ssl"
ENGINESDIR: "/usr/lib/engines-1.1"
Seeding source: os-specific

==Generating an RSA Private Key==

Generating a private key can be done in a variety of different ways depending on the type of key, algorithm, bits, and other options your specific use case may require. In this example, we are generating a private key using RSA and a key size of 2048 bits.

$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

To generate a password protected private key, the previous command may be slightly amended as follows:

$ openssl genpkey -aes256 -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

The addition of the <tt>-aes256</tt> option specifies the cipher to use to encrypt the private key file. For a list of available ciphers in the library, you can run the following command:

$ openssl list -cipher-algorithms

With your private key in hand, you can use the following command to see the key's details, such as its modulus and its constituent primes. Remember to change the name of the input file to the file name of your private key.

$ openssl pkey -in private-key.pem -text

The above command yields the following output in my specific case. Your output will differ but should be structurally similar.

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDZD6IMLRFk4CaF
w0rhRienwuE5EZ6xFE8e3C5TVi1+d9Enhi38RgkwD7UlWxPE6AWhp5T3kfrFWdak
1lZFVPp7/btOKLjKUru15nLoA4AKYtz9W9PhsM0dyzLc6FQ6K4ReQam5pHCqI2zF
82MwE+eIAduvuqyoQLKiI608EArWZqDtMUpBJzv0UVEYvRdnMWpCwfzpI+hPJywV
CcTlNCT/ctGgBKyIx+dDuZ7bR9MNmSW7GreJEbTH+R13xT3dd/JCka1+LYCl4h0q
oWhFPhOkvQzmmSzUmZlAlTDQLv2eAdJIrQcsnKZ3SsIOCC/3IpqwSzpid38Ill4O
xH6XIrVFAgMBAAECggEBAJ2MC0JrM8TULSHJrf/0u7O4b2DMuTIuW386sSUr17mD
nfviGF6TNvf7bq++e4rgHbZHvIg1HJ9Bpdne+J86HtUARYNlazru8fAFZEGiyLzB
JUV/8TpO6ZJGepR8zSWrkFgZsOddw6i6LalADy5GRDcjoiDajZdR3lZxLrv5qOQU
I1vKTf4Zs2Tl3gnaJ/Il1gBHIQ9W9xUH8jPBIwj51iXwCh8H0BiDPvFkU7cHIFCP
sJhGsGp6OS3uSwwQuSE+NqbuPfVilysCcwgZduknyio0QO1YfMBL6+XoKE/bFHsn
N+FzzczQg9sWyiwVR+3EeI9kp4JSElNh2nqG96i4QAECgYEA76OLUGrShHb4saoP
aYnBAKLEdWj5K483JdY6BSbdd5RkDbJG8ExmcbfTas/BGdKc4iVCkxV3ysxKnX18
PfxATHDLL8NMa+gGgZY5oTKUsrXEpS132HhCJ9T9LoesQjRb4kOZH8POVqm6O4Xf
lCt0y1+M1eQHI1NPO9CmPBgouEUCgYEA5+F4SS8RMyYRkU/kx195fwh0hhaOElzr
E8mZou3NFL/XT6/9t+2+7sMTuiQCP9zIa6s+/rrXdjWtrTcDp4WlDITas0UUgZhv
YVBQBF4vhHxIVwJxnT9Gwi4XM1JlFmVHofWD71P6DRe7jSWRS3CujP3AE9vmpWMx
tE1D9qLiWQECgYB445LzFYBvrKjWz4iI4CJKFNJwvGz+iXfzkXehg7KzkVtMAYSB
0rjXYzm3J2ktgq778nn8Qxc0agy2GEil6GvzY+9MgAQ8Z0do9gTKif6zjLjP7vkH
bdtJxsuWPoEqwMkdgqZrfNbJp0O4pVddovJ/agtdF3R2YJ+W+DH0HOfl1QKBgFnM
c2zEEYEhaQRBUHP1gXO0rouPCI4L9e2/0QPL2/QBJzzxBuzH4X1NhsI7V7OrqOIp
e0fiy7Y3q369I2ko1HY4rQln4z0c72VcWOCYKQbBqrInfCBNdPWWK93wNr2pk0gh
cGqqtteDLVrIBbCVfsOTMWN/cZ7y/zi4A23sPoQBAoGAEPzcIjOyoB97Pzd7iNim
Gin8RkwXIiFGSHo8vAh74CKBNokThM50OUNm5T2eJ4huzPpowQ+ID1mB5EjEai9n
JY9ll3cUpawiIIW/6uGTHyXfvZWNtqEYXrVJ6fcDaKcW4y3cplNj/SJaBW8HXsW7
YGHW3zHsgy7EOAOzPwlm9oE=
-----END PRIVATE KEY-----
RSA Private-Key: (2048 bit, 2 primes)
modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
publicExponent: 65537 (0x10001)
privateExponent:
00:9d:8c:0b:42:6b:33:c4:d4:2d:21:c9:ad:ff:f4:
bb:b3:b8:6f:60:cc:b9:32:2e:5b:7f:3a:b1:25:2b:
d7:b9:83:9d:fb:e2:18:5e:93:36:f7:fb:6e:af:be:
7b:8a:e0:1d:b6:47:bc:88:35:1c:9f:41:a5:d9:de:
f8:9f:3a:1e:d5:00:45:83:65:6b:3a:ee:f1:f0:05:
64:41:a2:c8:bc:c1:25:45:7f:f1:3a:4e:e9:92:46:
7a:94:7c:cd:25:ab:90:58:19:b0:e7:5d:c3:a8:ba:
2d:a9:40:0f:2e:46:44:37:23:a2:20:da:8d:97:51:
de:56:71:2e:bb:f9:a8:e4:14:23:5b:ca:4d:fe:19:
b3:64:e5:de:09:da:27:f2:25:d6:00:47:21:0f:56:
f7:15:07:f2:33:c1:23:08:f9:d6:25:f0:0a:1f:07:
d0:18:83:3e:f1:64:53:b7:07:20:50:8f:b0:98:46:
b0:6a:7a:39:2d:ee:4b:0c:10:b9:21:3e:36:a6:ee:
3d:f5:62:97:2b:02:73:08:19:76:e9:27:ca:2a:34:
40:ed:58:7c:c0:4b:eb:e5:e8:28:4f:db:14:7b:27:
37:e1:73:cd:cc:d0:83:db:16:ca:2c:15:47:ed:c4:
78:8f:64:a7:82:52:12:53:61:da:7a:86:f7:a8:b8:
40:01
prime1:
00:ef:a3:8b:50:6a:d2:84:76:f8:b1:aa:0f:69:89:
c1:00:a2:c4:75:68:f9:2b:8f:37:25:d6:3a:05:26:
dd:77:94:64:0d:b2:46:f0:4c:66:71:b7:d3:6a:cf:
c1:19:d2:9c:e2:25:42:93:15:77:ca:cc:4a:9d:7d:
7c:3d:fc:40:4c:70:cb:2f:c3:4c:6b:e8:06:81:96:
39:a1:32:94:b2:b5:c4:a5:2d:77:d8:78:42:27:d4:
fd:2e:87:ac:42:34:5b:e2:43:99:1f:c3:ce:56:a9:
ba:3b:85:df:94:2b:74:cb:5f:8c:d5:e4:07:23:53:
4f:3b:d0:a6:3c:18:28:b8:45
prime2:
00:e7:e1:78:49:2f:11:33:26:11:91:4f:e4:c7:5f:
79:7f:08:74:86:16:8e:12:5c:eb:13:c9:99:a2:ed:
cd:14:bf:d7:4f:af:fd:b7:ed:be:ee:c3:13:ba:24:
02:3f:dc:c8:6b:ab:3e:fe:ba:d7:76:35:ad:ad:37:
03:a7:85:a5:0c:84:da:b3:45:14:81:98:6f:61:50:
50:04:5e:2f:84:7c:48:57:02:71:9d:3f:46:c2:2e:
17:33:52:65:16:65:47:a1:f5:83:ef:53:fa:0d:17:
bb:8d:25:91:4b:70:ae:8c:fd:c0:13:db:e6:a5:63:
31:b4:4d:43:f6:a2:e2:59:01
exponent1:
78:e3:92:f3:15:80:6f:ac:a8:d6:cf:88:88:e0:22:
4a:14:d2:70:bc:6c:fe:89:77:f3:91:77:a1:83:b2:
b3:91:5b:4c:01:84:81:d2:b8:d7:63:39:b7:27:69:
2d:82:ae:fb:f2:79:fc:43:17:34:6a:0c:b6:18:48:
a5:e8:6b:f3:63:ef:4c:80:04:3c:67:47:68:f6:04:
ca:89:fe:b3:8c:b8:cf:ee:f9:07:6d:db:49:c6:cb:
96:3e:81:2a:c0:c9:1d:82:a6:6b:7c:d6:c9:a7:43:
b8:a5:57:5d:a2:f2:7f:6a:0b:5d:17:74:76:60:9f:
96:f8:31:f4:1c:e7:e5:d5
exponent2:
59:cc:73:6c:c4:11:81:21:69:04:41:50:73:f5:81:
73:b4:ae:8b:8f:08:8e:0b:f5:ed:bf:d1:03:cb:db:
f4:01:27:3c:f1:06:ec:c7:e1:7d:4d:86:c2:3b:57:
b3:ab:a8:e2:29:7b:47:e2:cb:b6:37:ab:7e:bd:23:
69:28:d4:76:38:ad:09:67:e3:3d:1c:ef:65:5c:58:
e0:98:29:06:c1:aa:b2:27:7c:20:4d:74:f5:96:2b:
dd:f0:36:bd:a9:93:48:21:70:6a:aa:b6:d7:83:2d:
5a:c8:05:b0:95:7e:c3:93:31:63:7f:71:9e:f2:ff:
38:b8:03:6d:ec:3e:84:01
coefficient:
10:fc:dc:22:33:b2:a0:1f:7b:3f:37:7b:88:d8:a6:
1a:29:fc:46:4c:17:22:21:46:48:7a:3c:bc:08:7b:
e0:22:81:36:89:13:84:ce:74:39:43:66:e5:3d:9e:
27:88:6e:cc:fa:68:c1:0f:88:0f:59:81:e4:48:c4:
6a:2f:67:25:8f:65:97:77:14:a5:ac:22:20:85:bf:
ea:e1:93:1f:25:df:bd:95:8d:b6:a1:18:5e:b5:49:
e9:f7:03:68:a7:16:e3:2d:dc:a6:53:63:fd:22:5a:
05:6f:07:5e:c5:bb:60:61:d6:df:31:ec:83:2e:c4:
38:03:b3:3f:09:66:f6:81

Keep in mind the above key was generated solely for pedagogical purposes; never give anyone access to your private keys.

==Generating a Public Key==

Having previously generated your private key, you may generate the corresponding public key using the following command.

$ openssl pkey -in private-key.pem -out public-key.pem -pubout

You may once again view the key details, using a slightly different command this time.

$ openssl pkey -in public-key.pem -pubin -text

The output for the public key will be shorter, as it carries much less information, and it will look something like this.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2Q+iDC0RZOAmhcNK4UYn
p8LhORGesRRPHtwuU1YtfnfRJ4Yt/EYJMA+1JVsTxOgFoaeU95H6xVnWpNZWRVT6
e/27Tii4ylK7teZy6AOACmLc/VvT4bDNHcsy3OhUOiuEXkGpuaRwqiNsxfNjMBPn
iAHbr7qsqECyoiOtPBAK1mag7TFKQSc79FFRGL0XZzFqQsH86SPoTycsFQnE5TQk
/3LRoASsiMfnQ7me20fTDZkluxq3iRG0x/kdd8U93XfyQpGtfi2ApeIdKqFoRT4T
pL0M5pks1JmZQJUw0C79ngHSSK0HLJymd0rCDggv9yKasEs6Ynd/CJZeDsR+lyK1
RQIDAQAB
-----END PUBLIC KEY-----
RSA Public-Key: (2048 bit)
Modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
Exponent: 65537 (0x10001)

For more information on generating keys, see the source code documentation, located in the <tt>doc/HOWTO/keys.txt</tt> file.

==Generating Keys Based on Elliptic Curves==

There are essentially two steps to generating a key:

# Generate the parameters for the specific curve you are using
# Use those parameters to generate the key

To see the list of curves instrinsically supported by openssl, you can use the <tt>-list_curves</t> option when calling the <tt>ecparam</tt> command.

$ openssl ecparam -list_curves
secp112r1 : SECG/WTLS curve over a 112 bit prime field
secp112r2 : SECG curve over a 112 bit prime field
secp128r1 : SECG curve over a 128 bit prime field
secp128r2 : SECG curve over a 128 bit prime field
secp160k1 : SECG curve over a 160 bit prime field
...

For this example I will use the <tt>prime256v1</tt> curve, which is an <tt>X9.62/SECG</tt> curve over a 256 bit prime field.

===Generating the Curve Parameters===

Having selected our curve, we now call <tt>ecparam</tt> to generate our parameters file.

$ openssl ecparam -name prime256v1 -out prime256v1.pem

====Printing Parameters to Standard Out====

You can print the generated curve parameters to the terminal output with the following command:

$ openssl ecparam -in prime256v1.pem -noout -text
ASN1 OID: prime256v1
NIST CURVE: P-256

====Printing Parameters as C Code====

Analogously, you may also output the generated curve parameters as C code. The parameters can then be loaded by calling the <tt>get_ec_group_XXX()</tt> function. To print the C code to the current terminal's output, the following command may be used:

$ openssl ecparam -in prime256v1.pem -noout -C

And here are the first few lines of the corresponding output:

EC_GROUP *get_ec_group_256(void)
{
static unsigned char ec_p_256[] = {
0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
...

===Generating the Key===

With the curve parameters in hand, we are now free to generate the key. Just as with the [#Generating an RSA Private Key|RSA] example above, we may optionally specify a cipher algorithm with which to encrypt the private key. The call to generate the key using the elliptic curve parameters generated in the example above looks like this:

$ openssl genpkey -aes256 -paramfile prime256v1.pem -out private-key.pem
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

==Base64 Encoding Strings==

For simple string encoding, you can use "here string" syntax with the [[Base64 Encoding|base64]] command as below. Intuitively, the <tt>-e</tt> flag specifies the action to be encoding.

$ openssl base64 -e <<< 'Welcome to openssl wiki'
V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK

Similarly, the base64 command's <tt>-d</tt> flag may be used to indicate decoding mode.

$ openssl base64 -d <<< 'V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK'
Welcome to openssl wiki

==Generating a File Hash==

One of the most basic uses of the [[dgst]] command (short for digest) is viewing the hash of a given file. To do this, simply invoke the command with the specified digest algorithm to use. For this example, I will be hashing an arbitrary file on my system using the [[MD5]], [[SHA1]], and [[SHA384]] algorithms.

$ openssl dgst -md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl dgst -sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl dgst -sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

For a list of the available digest algorithms, you can use the following command.

$ openssl list -digest-algorithms
RSA-MD4 => MD4
RSA-MD5 => MD5
RSA-MDC2 => MDC2
RSA-RIPEMD160 => RIPEMD160
RSA-SHA1 => SHA1
RSA-SHA1-2 => RSA-SHA1
...

You can also use a similar command to see the available [[Digest Commands|digest commands]]:

$ openssl list -digest-commands
blake2b512 blake2s256 gost md4
md5 mdc2 rmd160 sha1
sha224 sha256 sha3-224 sha3-256
sha3-384 sha3-512 sha384 sha512
sha512-224 sha512-256 shake128 shake256
sm3

Below are three sample invocations of the [[md5]], [[sha1]], and [[sha384]] digest commands using the same file as the [[dgst]] command invocation above.

$ openssl md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

==File Encryption and Decryption==

The following example demonstrates a simple file encryption and decryption using the [[enc]] command. The first argument is the cipher algorithm to use for encrypting the file. For this example I carefully selected the [[AES-256]] algorithm in [[CBC Mode]] by looking up the available ciphers and picking out the first one I saw. To see the list of available ciphers, you can use the following command.

$ openssl enc -ciphers
Supported ciphers:
-aes-128-cbc -aes-128-cfb -aes-128-cfb1
-aes-128-cfb8 -aes-128-ctr -aes-128-ecb
-aes-128-ofb -aes-192-cbc -aes-192-cfb
-aes-192-cfb1 -aes-192-cfb8 -aes-192-ctr
...

You can also use the following command:

$ openssl list -cipher-algorithms
AES-128-CBC
AES-128-CBC-HMAC-SHA1
AES-128-CBC-HMAC-SHA256
id-aes128-CCM
AES-128-CFB
AES-128-CFB1
AES-128-CFB8
AES-128-CTR
...

Having selected an encryption algorithm, you must then specify whether the action you are taking is either encryption or decryption via the <tt>-e</tt> or <tt>-d</tt> flags, respectively. The <tt>-iter</tt> flag specifies the number of iterations on the password used for deriving the encryption key. A higher iteration count increases the time required to brute-force the resulting file. Using this option implies enabling use of the [[Password-Based Key Derivation Function 2]], usually set using the <tt>-pbkdf2</tt> flag. We then use the <tt>-salt</tt> flag to enable the use of a randomly generated salt in the key-derivation function.

Putting it all together, you can see the command to encrypt a file and the corresponding output below. Note that the passwords entered by the user are blank, just as they would usually be in a terminal session.

$ openssl enc -aes-256-cbc -e -iter 1000 -salt -in primes.dat -out primes.enc
enter aes-256-cbc encryption password:
Verifying - enter aes-256-cbc encryption password:

The analogous decryption command is as follows:

$ openssl enc -aes-256-cbc -d -iter 1000 -in primes.enc -out primes.dec
enter aes-256-cbc decryption password:

=Commands=

There are three different kinds of commands. These are [[Standard commands|standard commands]], [[Cipher commands|cipher commands]], and [[Digest comands|digest commands]]. Calling the OpenSSL top-level <tt>help</tt> command with no arguments will result in openssl printing all available commands by group, sorted alphabetically.

==Standard Commands==

{| class="wikitable" style="margin:auto; text-align: center; width: 65%;"
|+ Overview of OpenSSL's command line utilities
! style="width: 25%; padding: 4px;" | Command
! style="width: 75%; padding: 4px;" | Description
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/asn1parse.html asn1parse]
|style="padding: 4px;" | Parse an ASN.1 sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ca.html ca]
|style="padding: 4px;" | Certificate Authority (CA) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ciphers.html ciphers]
|style="padding: 4px;" | Cipher Suite Description Determination.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/cms.html cms]
|style="padding: 4px;" | CMS (Cryptographic Message Syntax) utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl.html crl]
|style="padding: 4px;" | Certificate Revocation List (CRL) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl2pkcs7.html crl2pkcs7]
|style="padding: 4px;" | CRL to PKCS#7 Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dgst.html dgst]
|style="padding: 4px;" | Message Digest calculation. MAC calculations are superseded by mac(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dhparam.html dhparam]
|style="padding: 4px;" | Generation and Management of Diffie-Hellman Parameters. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsa.html dsa]
|style="padding: 4px;" | DSA Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsaparam.html dsaparam]
|style="padding: 4px;" | DSA Parameter Generation and Management. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ec.html ec]
|style="padding: 4px;" | EC (Elliptic curve) key processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ecparam.html ecparam]
|style="padding: 4px;" | EC parameter manipulation and generation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/enc.html enc]
|style="padding: 4px;" | Encoding with Ciphers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/engine.html engine]
|style="padding: 4px;" | Engine (loadable module) information and manipulation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/errstr.html errstr]
|style="padding: 4px;" | Error Number to Error String Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/gendsa.html gendsa]
|style="padding: 4px;" | Generation of DSA Private Key from Parameters. Superseded by genpkey(1) and pkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genpkey.html genpkey]
|style="padding: 4px;" | Generation of Private Key or Parameters.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genrsa.html genrsa]
|style="padding: 4px;" | Generation of RSA Private Key. Superseded by genpkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/info.html info]
|style="padding: 4px;" | Display diverse information built into the OpenSSL libraries.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/kdf.html kdf]
|style="padding: 4px;" | Key Derivation Functions.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/mac.html mac]
|style="padding: 4px;" | Message Authentication Code Calculation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/nseq.html nseq]
|style="padding: 4px;" | Create or examine a Netscape certificate sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ocsp.html ocsp]
|style="padding: 4px;" | Online Certificate Status Protocol utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/passwd.html passwd]
|style="padding: 4px;" | Generation of hashed passwords.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs12.html pkcs12]
|style="padding: 4px;" | PKCS#12 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs7.html pkcs7]
|style="padding: 4px;" | PKCS#7 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs8.html pkcs8]
|style="padding: 4px;" | PKCS#8 format private key conversion tool.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkey.html pkey]
|style="padding: 4px;" | Public and private key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyparam.html pkeyparam]
|style="padding: 4px;" | Public key algorithm parameter management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyutl.html pkeyutl]
|style="padding: 4px;" | Public key algorithm cryptographic operation utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/prime.html prime]
|style="padding: 4px;" | Compute prime numbers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rand.html rand]
|style="padding: 4px;" | Generate pseudo-random bytes.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rehash.html rehash]
|style="padding: 4px;" | Create symbolic links to certificate and CRL files named by the hash values.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/req.html req]
|style="padding: 4px;" | PKCS#10 X.509 Certificate Signing Request (CSR) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsa.html rsa]
|style="padding: 4px;" | RSA key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsautl.html rsautl]
|style="padding: 4px;" | RSA utility for signing, verification, encryption, and decryption. Superseded by pkeyutl(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_client.html s_client]
|style="padding: 4px;" | This implements a generic SSL/TLS client which can establish a transparent connection to a remote server speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_server.html s_server]
|style="padding: 4px;" | This implements a generic SSL/TLS server which accepts connections from remote clients speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_time.html s_time]
|style="padding: 4px;" | SSL Connection Timer.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/sess_id.html sess_id]
|style="padding: 4px;" | SSL Session Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/smime.html smime]
|style="padding: 4px;" | S/MIME mail processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/speed.html speed]
|style="padding: 4px;" | Algorithm Speed Measurement.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/spkac.html spkac]
|style="padding: 4px;" | SPKAC printing and generating utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/srp.html srp]
|style="padding: 4px;" | Maintain SRP password file.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/storeutl.html storeutl]
|style="padding: 4px;" | Utility to list and display certificates, keys, CRLs, etc.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ts.html ts]
|style="padding: 4px;" | Time Stamping Authority tool (client/server).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/verify.html verify]
|style="padding: 4px;" | X.509 Certificate Verification.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/version.html version]
|style="padding: 4px;" | OpenSSL Version Information.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/x509.html x509]
|style="padding: 4px;" | X.509 Certificate Data Management.
|}

= Further reading =

* Paul Heinlein. [https://www.madboa.com/geek/openssl/ "OpenSSL Command-Line HOWTO"]. Has many quick cookbook-style recipes for doing common tasks using the "oppenssl" command-line application.

[[Category:Examples]]
[[Category:Shell level]]

Talk:Command Line Utilities

2019-07-30T03:35:18Z

Jflopezfernandez: /* Pretty significant rewrite */ new section

Command Line Utilities

2019-07-30T03:35:14Z

Jflopezfernandez: Pretty significant rewrite, details in discussion

The '''openssl''' program provides a rich variety of commands, each of which often has a wealth of options and arguments. Many commands use an external configuration file for some or all of their arguments and have a <code>-config</code> option to specify that file. The environment variable [[OPENSSL_CONF]] can be used to specify the location of the configuration file. If the environment variable is not specified, a default file is created in the default certificate storage area called '''openssl.cnf'''. The settings in this default configuration file depend on the flags set when the version of OpenSSL being used was built.

This article is an overview of the available tools provided by openssl. For all of the details on usage and implementation, you can find the [https://www.openssl.org/docs/manmaster/ manpages] which are automatically generated from the source code at the [https://www.openssl.org/ official OpenSSL project home]. Likewise, the source code itself may be found on the [https://www.openssl.org/source/ OpenSSL project home page], as well as on the [https://github.com/openssl/openssl OpenSSL Github]. The main OpenSSL site also includes an [https://www.openssl.org/docs/manmaster/man1/openssl.html overview of the command-line utilities], as well as links to all of their respective documentation.

=Getting Started=

The entry point for the OpenSSL library is the '''openssl''' binary, usually <tt>/usr/bin/openssl</tt> on Linux. The general syntax for calling openssl is as follows:

$ openssl command [ command_options ] [ command_arguments ]

Alternatively, you can call openssl without arguments to enter the interactive mode prompt. You may then enter commands directly, exiting with either a <code>quit</code> command or by issuing a termination signal with either <tt>Ctrl+C</tt> or <tt>Ctrl+D</tt>. The following is a sample interactive session in which the user invokes the [[primes]] command twice before using the <tt>quit</tt> command to terminate the session.

OpenSSL> prime -generate -bits 24
13467269
OpenSSL> prime -generate -bits 24
16651079
OpenSSL> quit

=Basic Tasks=

This section is a brief tutorial on performing the most basic tasks using OpenSSL. For a detailed explanation of the rationale behind the syntax and semantics of the commands shown here, see the section on [[#Commands|Commands]].

==Getting Help==

As mentioned previously, the general syntax of a command is <code>openssl command [ command_options ] [ command_arguments ]</code>. The help command is no different, but it does have its idiosyncrasies. To view the top-level help menu, you can call openssl as follows.

$ openssl help

This query will print all of the available commands, like so:

Standard commands
asn1parse ca ciphers cms
crl crl2pkcs7 dgst dhparam
dsa dsaparam ec ecparam
...

Note the above output was truncated, so only the first four lines of output are shown.

A help menu for each command may be requested in two different ways. First, the same command used above may be repeated, followed by the name of the command to print help for.

$ openssl help genpkey

The program will then display the valid options for the given command.

$ openssl help genpkey
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

The second way of requesting the help menu for a particular command is by using the first option in the output shown above, namely <code>openssl command -help</code>. Both commands will yield the same output; the help menu displayed will be exactly the same.

$ openssl genpkey -help
Usage: genpkey [options]
Valid options are:
-help Display this summary
-out outfile Output file
-outform PEM|DER output format (DER or PEM)
-pass val Output file pass phrase source
-paramfile infile Parameters file
-algorithm val The public key algorithm
-pkeyopt val Set the public key algorithm option as opt:value
-genparam Generate parameters, not key
-text Print the in text
-* Cipher to use to encrypt the key
-engine val Use engine, possibly a hardware device
Order of options may be important! See the documentation.

For additional information on the usage of a particular command, the project [https://www.openssl.org/docs/manpages.html manpages] are a great source of information. Another excellent source of information is the project perldocs. [https://perldoc.perl.org/5.30.0/perldoc.html perldoc] is a utility included with most if not all [https://www.perl.org/ Perl] distributions, and it's capable of displaying documentation information in a variety of formats, one of which is as manpages. Not surprisingly, the project documentation is generated from the pod files located in the <tt>doc</tt> directory of the source code.

==Getting Library Version Information==

$ openssl version
OpenSSL 1.1.1c 28 May 2019

As mentioned above, the <tt>version</tt> command's help menu may be queried for additional options like so:

$ openssl version -help
Usage: version [options]
Valid options are:
-help Display this summary
-a Show all data
-b Show build date
-d Show configuration directory
-e Show engines directory
-f Show compiler flags used
-o Show some internal datatype options
-p Show target build platform
-r Show random seeding options
-v Show library version

Using the <tt>-a</tt> option to show all version information yields the following output on my current machine:

$ openssl version -a
OpenSSL 1.1.1c 28 May 2019
built on: Tue May 28 16:23:39 2019 UTC
platform: linux-x86_64
options: bn(64,64) rc4(16x,int) des(int) idea(int) blowfish(ptr)
compiler: gcc -fPIC -pthread -m64 -Wa,--noexecstack -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wa,--noexecstack -D_FORTIFY_SOURCE=2 -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now -DOPENSSL_USE_NODELETE -DL_ENDIAN -DOPENSSL_PIC -DOPENSSL_CPUID_OBJ -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT -DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DKECCAK1600_ASM -DRC4_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM -DGHASH_ASM -DECP_NISTZ256_ASM -DX25519_ASM -DPOLY1305_ASM -DNDEBUG -D_FORTIFY_SOURCE=2
OPENSSLDIR: "/etc/ssl"
ENGINESDIR: "/usr/lib/engines-1.1"
Seeding source: os-specific

==Generating an RSA Private Key==

Generating a private key can be done in a variety of different ways depending on the type of key, algorithm, bits, and other options your specific use case may require. In this example, we are generating a private key using RSA and a key size of 2048 bits.

$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

To generate a password protected private key, the previous command may be slightly amended as follows:

$ openssl genpkey -aes256 -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem

The addition of the <tt>-aes256</tt> option specifies the cipher to use to encrypt the private key file. For a list of available ciphers in the library, you can run the following command:

$ openssl list -cipher-algorithms

With your private key in hand, you can use the following command to see the key's details, such as its modulus and its constituent primes. Remember to change the name of the input file to the file name of your private key.

$ openssl pkey -in private-key.pem -text

The above command yields the following output in my specific case. Your output will differ but should be structurally similar.

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDZD6IMLRFk4CaF
w0rhRienwuE5EZ6xFE8e3C5TVi1+d9Enhi38RgkwD7UlWxPE6AWhp5T3kfrFWdak
1lZFVPp7/btOKLjKUru15nLoA4AKYtz9W9PhsM0dyzLc6FQ6K4ReQam5pHCqI2zF
82MwE+eIAduvuqyoQLKiI608EArWZqDtMUpBJzv0UVEYvRdnMWpCwfzpI+hPJywV
CcTlNCT/ctGgBKyIx+dDuZ7bR9MNmSW7GreJEbTH+R13xT3dd/JCka1+LYCl4h0q
oWhFPhOkvQzmmSzUmZlAlTDQLv2eAdJIrQcsnKZ3SsIOCC/3IpqwSzpid38Ill4O
xH6XIrVFAgMBAAECggEBAJ2MC0JrM8TULSHJrf/0u7O4b2DMuTIuW386sSUr17mD
nfviGF6TNvf7bq++e4rgHbZHvIg1HJ9Bpdne+J86HtUARYNlazru8fAFZEGiyLzB
JUV/8TpO6ZJGepR8zSWrkFgZsOddw6i6LalADy5GRDcjoiDajZdR3lZxLrv5qOQU
I1vKTf4Zs2Tl3gnaJ/Il1gBHIQ9W9xUH8jPBIwj51iXwCh8H0BiDPvFkU7cHIFCP
sJhGsGp6OS3uSwwQuSE+NqbuPfVilysCcwgZduknyio0QO1YfMBL6+XoKE/bFHsn
N+FzzczQg9sWyiwVR+3EeI9kp4JSElNh2nqG96i4QAECgYEA76OLUGrShHb4saoP
aYnBAKLEdWj5K483JdY6BSbdd5RkDbJG8ExmcbfTas/BGdKc4iVCkxV3ysxKnX18
PfxATHDLL8NMa+gGgZY5oTKUsrXEpS132HhCJ9T9LoesQjRb4kOZH8POVqm6O4Xf
lCt0y1+M1eQHI1NPO9CmPBgouEUCgYEA5+F4SS8RMyYRkU/kx195fwh0hhaOElzr
E8mZou3NFL/XT6/9t+2+7sMTuiQCP9zIa6s+/rrXdjWtrTcDp4WlDITas0UUgZhv
YVBQBF4vhHxIVwJxnT9Gwi4XM1JlFmVHofWD71P6DRe7jSWRS3CujP3AE9vmpWMx
tE1D9qLiWQECgYB445LzFYBvrKjWz4iI4CJKFNJwvGz+iXfzkXehg7KzkVtMAYSB
0rjXYzm3J2ktgq778nn8Qxc0agy2GEil6GvzY+9MgAQ8Z0do9gTKif6zjLjP7vkH
bdtJxsuWPoEqwMkdgqZrfNbJp0O4pVddovJ/agtdF3R2YJ+W+DH0HOfl1QKBgFnM
c2zEEYEhaQRBUHP1gXO0rouPCI4L9e2/0QPL2/QBJzzxBuzH4X1NhsI7V7OrqOIp
e0fiy7Y3q369I2ko1HY4rQln4z0c72VcWOCYKQbBqrInfCBNdPWWK93wNr2pk0gh
cGqqtteDLVrIBbCVfsOTMWN/cZ7y/zi4A23sPoQBAoGAEPzcIjOyoB97Pzd7iNim
Gin8RkwXIiFGSHo8vAh74CKBNokThM50OUNm5T2eJ4huzPpowQ+ID1mB5EjEai9n
JY9ll3cUpawiIIW/6uGTHyXfvZWNtqEYXrVJ6fcDaKcW4y3cplNj/SJaBW8HXsW7
YGHW3zHsgy7EOAOzPwlm9oE=
-----END PRIVATE KEY-----
RSA Private-Key: (2048 bit, 2 primes)
modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
publicExponent: 65537 (0x10001)
privateExponent:
00:9d:8c:0b:42:6b:33:c4:d4:2d:21:c9:ad:ff:f4:
bb:b3:b8:6f:60:cc:b9:32:2e:5b:7f:3a:b1:25:2b:
d7:b9:83:9d:fb:e2:18:5e:93:36:f7:fb:6e:af:be:
7b:8a:e0:1d:b6:47:bc:88:35:1c:9f:41:a5:d9:de:
f8:9f:3a:1e:d5:00:45:83:65:6b:3a:ee:f1:f0:05:
64:41:a2:c8:bc:c1:25:45:7f:f1:3a:4e:e9:92:46:
7a:94:7c:cd:25:ab:90:58:19:b0:e7:5d:c3:a8:ba:
2d:a9:40:0f:2e:46:44:37:23:a2:20:da:8d:97:51:
de:56:71:2e:bb:f9:a8:e4:14:23:5b:ca:4d:fe:19:
b3:64:e5:de:09:da:27:f2:25:d6:00:47:21:0f:56:
f7:15:07:f2:33:c1:23:08:f9:d6:25:f0:0a:1f:07:
d0:18:83:3e:f1:64:53:b7:07:20:50:8f:b0:98:46:
b0:6a:7a:39:2d:ee:4b:0c:10:b9:21:3e:36:a6:ee:
3d:f5:62:97:2b:02:73:08:19:76:e9:27:ca:2a:34:
40:ed:58:7c:c0:4b:eb:e5:e8:28:4f:db:14:7b:27:
37:e1:73:cd:cc:d0:83:db:16:ca:2c:15:47:ed:c4:
78:8f:64:a7:82:52:12:53:61:da:7a:86:f7:a8:b8:
40:01
prime1:
00:ef:a3:8b:50:6a:d2:84:76:f8:b1:aa:0f:69:89:
c1:00:a2:c4:75:68:f9:2b:8f:37:25:d6:3a:05:26:
dd:77:94:64:0d:b2:46:f0:4c:66:71:b7:d3:6a:cf:
c1:19:d2:9c:e2:25:42:93:15:77:ca:cc:4a:9d:7d:
7c:3d:fc:40:4c:70:cb:2f:c3:4c:6b:e8:06:81:96:
39:a1:32:94:b2:b5:c4:a5:2d:77:d8:78:42:27:d4:
fd:2e:87:ac:42:34:5b:e2:43:99:1f:c3:ce:56:a9:
ba:3b:85:df:94:2b:74:cb:5f:8c:d5:e4:07:23:53:
4f:3b:d0:a6:3c:18:28:b8:45
prime2:
00:e7:e1:78:49:2f:11:33:26:11:91:4f:e4:c7:5f:
79:7f:08:74:86:16:8e:12:5c:eb:13:c9:99:a2:ed:
cd:14:bf:d7:4f:af:fd:b7:ed:be:ee:c3:13:ba:24:
02:3f:dc:c8:6b:ab:3e:fe:ba:d7:76:35:ad:ad:37:
03:a7:85:a5:0c:84:da:b3:45:14:81:98:6f:61:50:
50:04:5e:2f:84:7c:48:57:02:71:9d:3f:46:c2:2e:
17:33:52:65:16:65:47:a1:f5:83:ef:53:fa:0d:17:
bb:8d:25:91:4b:70:ae:8c:fd:c0:13:db:e6:a5:63:
31:b4:4d:43:f6:a2:e2:59:01
exponent1:
78:e3:92:f3:15:80:6f:ac:a8:d6:cf:88:88:e0:22:
4a:14:d2:70:bc:6c:fe:89:77:f3:91:77:a1:83:b2:
b3:91:5b:4c:01:84:81:d2:b8:d7:63:39:b7:27:69:
2d:82:ae:fb:f2:79:fc:43:17:34:6a:0c:b6:18:48:
a5:e8:6b:f3:63:ef:4c:80:04:3c:67:47:68:f6:04:
ca:89:fe:b3:8c:b8:cf:ee:f9:07:6d:db:49:c6:cb:
96:3e:81:2a:c0:c9:1d:82:a6:6b:7c:d6:c9:a7:43:
b8:a5:57:5d:a2:f2:7f:6a:0b:5d:17:74:76:60:9f:
96:f8:31:f4:1c:e7:e5:d5
exponent2:
59:cc:73:6c:c4:11:81:21:69:04:41:50:73:f5:81:
73:b4:ae:8b:8f:08:8e:0b:f5:ed:bf:d1:03:cb:db:
f4:01:27:3c:f1:06:ec:c7:e1:7d:4d:86:c2:3b:57:
b3:ab:a8:e2:29:7b:47:e2:cb:b6:37:ab:7e:bd:23:
69:28:d4:76:38:ad:09:67:e3:3d:1c:ef:65:5c:58:
e0:98:29:06:c1:aa:b2:27:7c:20:4d:74:f5:96:2b:
dd:f0:36:bd:a9:93:48:21:70:6a:aa:b6:d7:83:2d:
5a:c8:05:b0:95:7e:c3:93:31:63:7f:71:9e:f2:ff:
38:b8:03:6d:ec:3e:84:01
coefficient:
10:fc:dc:22:33:b2:a0:1f:7b:3f:37:7b:88:d8:a6:
1a:29:fc:46:4c:17:22:21:46:48:7a:3c:bc:08:7b:
e0:22:81:36:89:13:84:ce:74:39:43:66:e5:3d:9e:
27:88:6e:cc:fa:68:c1:0f:88:0f:59:81:e4:48:c4:
6a:2f:67:25:8f:65:97:77:14:a5:ac:22:20:85:bf:
ea:e1:93:1f:25:df:bd:95:8d:b6:a1:18:5e:b5:49:
e9:f7:03:68:a7:16:e3:2d:dc:a6:53:63:fd:22:5a:
05:6f:07:5e:c5:bb:60:61:d6:df:31:ec:83:2e:c4:
38:03:b3:3f:09:66:f6:81

Keep in mind the above key was generated solely for pedagogical purposes; never give anyone access to your private keys.

==Generating a Public Key==

Having previously generated your private key, you may generate the corresponding public key using the following command.

$ openssl pkey -in private-key.pem -out public-key.pem -pubout

You may once again view the key details, using a slightly different command this time.

$ openssl pkey -in public-key.pem -pubin -text

The output for the public key will be shorter, as it carries much less information, and it will look something like this.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2Q+iDC0RZOAmhcNK4UYn
p8LhORGesRRPHtwuU1YtfnfRJ4Yt/EYJMA+1JVsTxOgFoaeU95H6xVnWpNZWRVT6
e/27Tii4ylK7teZy6AOACmLc/VvT4bDNHcsy3OhUOiuEXkGpuaRwqiNsxfNjMBPn
iAHbr7qsqECyoiOtPBAK1mag7TFKQSc79FFRGL0XZzFqQsH86SPoTycsFQnE5TQk
/3LRoASsiMfnQ7me20fTDZkluxq3iRG0x/kdd8U93XfyQpGtfi2ApeIdKqFoRT4T
pL0M5pks1JmZQJUw0C79ngHSSK0HLJymd0rCDggv9yKasEs6Ynd/CJZeDsR+lyK1
RQIDAQAB
-----END PUBLIC KEY-----
RSA Public-Key: (2048 bit)
Modulus:
00:d9:0f:a2:0c:2d:11:64:e0:26:85:c3:4a:e1:46:
27:a7:c2:e1:39:11:9e:b1:14:4f:1e:dc:2e:53:56:
2d:7e:77:d1:27:86:2d:fc:46:09:30:0f:b5:25:5b:
13:c4:e8:05:a1:a7:94:f7:91:fa:c5:59:d6:a4:d6:
56:45:54:fa:7b:fd:bb:4e:28:b8:ca:52:bb:b5:e6:
72:e8:03:80:0a:62:dc:fd:5b:d3:e1:b0:cd:1d:cb:
32:dc:e8:54:3a:2b:84:5e:41:a9:b9:a4:70:aa:23:
6c:c5:f3:63:30:13:e7:88:01:db:af:ba:ac:a8:40:
b2:a2:23:ad:3c:10:0a:d6:66:a0:ed:31:4a:41:27:
3b:f4:51:51:18:bd:17:67:31:6a:42:c1:fc:e9:23:
e8:4f:27:2c:15:09:c4:e5:34:24:ff:72:d1:a0:04:
ac:88:c7:e7:43:b9:9e:db:47:d3:0d:99:25:bb:1a:
b7:89:11:b4:c7:f9:1d:77:c5:3d:dd:77:f2:42:91:
ad:7e:2d:80:a5:e2:1d:2a:a1:68:45:3e:13:a4:bd:
0c:e6:99:2c:d4:99:99:40:95:30:d0:2e:fd:9e:01:
d2:48:ad:07:2c:9c:a6:77:4a:c2:0e:08:2f:f7:22:
9a:b0:4b:3a:62:77:7f:08:96:5e:0e:c4:7e:97:22:
b5:45
Exponent: 65537 (0x10001)

For more information on generating keys, see the source code documentation, located in the <tt>doc/HOWTO/keys.txt</tt> file.

==Generating Keys Based on Elliptic Curves==

There are essentially two steps to generating a key:

# Generate the parameters for the specific curve you are using
# Use those parameters to generate the key

To see the list of curves instrinsically supported by openssl, you can use the <tt>-list_curves</t> option when calling the <tt>ecparam</tt> command.

$ openssl ecparam -list_curves
secp112r1 : SECG/WTLS curve over a 112 bit prime field
secp112r2 : SECG curve over a 112 bit prime field
secp128r1 : SECG curve over a 128 bit prime field
secp128r2 : SECG curve over a 128 bit prime field
secp160k1 : SECG curve over a 160 bit prime field
...

For this example I will use the <tt>prime256v1</tt> curve, which is an <tt>X9.62/SECG</tt> curve over a 256 bit prime field.

===Generating the Curve Parameters===

Having selected our curve, we now call <tt>ecparam</tt> to generate our parameters file.

$ openssl ecparam -name prime256v1 -out prime256v1.pem

====Printing Parameters to Standard Out====

You can print the generated curve parameters to the terminal output with the following command:

$ openssl ecparam -in prime256v1.pem -noout -text
ASN1 OID: prime256v1
NIST CURVE: P-256

====Printing Parameters as C Code====

Analogously, you may also output the generated curve parameters as C code. The parameters can then be loaded by calling the <tt>get_ec_group_XXX()</tt> function. To print the C code to the current terminal's output, the following command may be used:

$ openssl ecparam -in prime256v1.pem -noout -C

And here are the first few lines of the corresponding output:

EC_GROUP *get_ec_group_256(void)
{
static unsigned char ec_p_256[] = {
0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
...

===Generating the Key===

With the curve parameters in hand, we are now free to generate the key. Just as with the [#Generating an RSA Private Key|RSA] example above, we may optionally specify a cipher algorithm with which to encrypt the private key. The call to generate the key using the elliptic curve parameters generated in the example above looks like this:

$ openssl genpkey -aes256 -paramfile prime256v1.pem -out private-key.pem
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

==Base64 Encoding Strings==

For simple string encoding, you can use "here string" syntax with the [[Base64 Encoding|base64]] command as below. Intuitively, the <tt>-e</tt> flag specifies the action to be encoding.

$ openssl base64 -e <<< 'Welcome to openssl wiki'
V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK

Similarly, the base64 command's <tt>-d</tt> flag may be used to indicate decoding mode.

$ openssl base64 -d <<< 'V2VsY29tZSB0byBvcGVuc3NsIHdpa2kK'
Welcome to openssl wiki

==Generating a File Hash==

One of the most basic uses of the [[dgst]] command (short for digest) is viewing the hash of a given file. To do this, simply invoke the command with the specified digest algorithm to use. For this example, I will be hashing an arbitrary file on my system using the [[MD5]], [[SHA1]], and [[SHA384]] algorithms.

$ openssl dgst -md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl dgst -sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl dgst -sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

For a list of the available digest algorithms, you can use the following command.

$ openssl list -digest-algorithms
RSA-MD4 => MD4
RSA-MD5 => MD5
RSA-MDC2 => MDC2
RSA-RIPEMD160 => RIPEMD160
RSA-SHA1 => SHA1
RSA-SHA1-2 => RSA-SHA1
...

You can also use a similar command to see the available [[Digest Commands|digest commands]]:

$ openssl list -digest-commands
blake2b512 blake2s256 gost md4
md5 mdc2 rmd160 sha1
sha224 sha256 sha3-224 sha3-256
sha3-384 sha3-512 sha384 sha512
sha512-224 sha512-256 shake128 shake256
sm3

Below are three sample invocations of the [[md5]], [[sha1]], and [[sha384]] digest commands using the same file as the [[dgst]] command invocation above.

$ openssl md5 primes.dat
MD5(primes.dat)= 7710839bb87d2c4c15a86c2b2c805664

$ openssl sha1 primes.dat
SHA1(primes.dat)= 5dfab70ce825591689f4a3f65910870a9022cd32

$ openssl sha384 primes.dat
SHA384(primes.dat)= 41399bdffe6850f5a44852d967f3db415654f20dc2eb6cd231772f6ea411876d85d44091ebbc6b1f4ce8673e64617271

==File Encryption and Decryption==

The following example demonstrates a simple file encryption and decryption using the [[enc]] command. The first argument is the cipher algorithm to use for encrypting the file. For this example I carefully selected the [[AES-256]] algorithm in [[CBC Mode]] by looking up the available ciphers and picking out the first one I saw. To see the list of available ciphers, you can use the following command.

$ openssl enc -ciphers
Supported ciphers:
-aes-128-cbc -aes-128-cfb -aes-128-cfb1
-aes-128-cfb8 -aes-128-ctr -aes-128-ecb
-aes-128-ofb -aes-192-cbc -aes-192-cfb
-aes-192-cfb1 -aes-192-cfb8 -aes-192-ctr
...

You can also use the following command:

$ openssl list -cipher-algorithms
AES-128-CBC
AES-128-CBC-HMAC-SHA1
AES-128-CBC-HMAC-SHA256
id-aes128-CCM
AES-128-CFB
AES-128-CFB1
AES-128-CFB8
AES-128-CTR
...

Having selected an encryption algorithm, you must then specify whether the action you are taking is either encryption or decryption via the <tt>-e</tt> or <tt>-d</tt> flags, respectively. The <tt>-iter</tt> flag specifies the number of iterations on the password used for deriving the encryption key. A higher iteration count increases the time required to brute-force the resulting file. Using this option implies enabling use of the [[Password-Based Key Derivation Function 2]], usually set using the <tt>-pbkdf2</tt> flag. We then use the <tt>-salt</tt> flag to enable the use of a randomly generated salt in the key-derivation function.

Putting it all together, you can see the command to encrypt a file and the corresponding output below. Note that the passwords entered by the user are blank, just as they would usually be in a terminal session.

$ openssl enc -aes-256-cbc -e -iter 1000 -salt -in primes.dat -out primes.enc
enter aes-256-cbc encryption password:
Verifying - enter aes-256-cbc encryption password:

The analogous decryption command is as follows:

$ openssl enc -aes-256-cbc -d -iter 1000 -in primes.enc -out primes.dec
enter aes-256-cbc decryption password:

=Commands=

There are three different kinds of commands. These are [[Standard commands|standard commands]], [[Cipher commands|cipher commands]], and [[Digest comands|digest commands]]. Calling the OpenSSL top-level <tt>help</tt> command with no arguments will result in openssl printing all available commands by group, sorted alphabetically.

==Standard Commands==

{| class="wikitable" style="margin:auto; text-align: center; width: 65%;"
|+ Overview of OpenSSL's command line utilities
! style="width: 25%; padding: 4px;" | Command
! style="width: 75%; padding: 4px;" | Description
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/asn1parse.html asn1parse]
|style="padding: 4px;" | Parse an ASN.1 sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ca.html ca]
|style="padding: 4px;" | Certificate Authority (CA) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ciphers.html ciphers]
|style="padding: 4px;" | Cipher Suite Description Determination.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/cms.html cms]
|style="padding: 4px;" | CMS (Cryptographic Message Syntax) utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl.html crl]
|style="padding: 4px;" | Certificate Revocation List (CRL) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/crl2pkcs7.html crl2pkcs7]
|style="padding: 4px;" | CRL to PKCS#7 Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dgst.html dgst]
|style="padding: 4px;" | Message Digest calculation. MAC calculations are superseded by mac(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dhparam.html dhparam]
|style="padding: 4px;" | Generation and Management of Diffie-Hellman Parameters. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsa.html dsa]
|style="padding: 4px;" | DSA Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/dsaparam.html dsaparam]
|style="padding: 4px;" | DSA Parameter Generation and Management. Superseded by genpkey(1) and pkeyparam(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ec.html ec]
|style="padding: 4px;" | EC (Elliptic curve) key processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ecparam.html ecparam]
|style="padding: 4px;" | EC parameter manipulation and generation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/enc.html enc]
|style="padding: 4px;" | Encoding with Ciphers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/engine.html engine]
|style="padding: 4px;" | Engine (loadable module) information and manipulation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/errstr.html errstr]
|style="padding: 4px;" | Error Number to Error String Conversion.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/gendsa.html gendsa]
|style="padding: 4px;" | Generation of DSA Private Key from Parameters. Superseded by genpkey(1) and pkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genpkey.html genpkey]
|style="padding: 4px;" | Generation of Private Key or Parameters.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/genrsa.html genrsa]
|style="padding: 4px;" | Generation of RSA Private Key. Superseded by genpkey(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/info.html info]
|style="padding: 4px;" | Display diverse information built into the OpenSSL libraries.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/kdf.html kdf]
|style="padding: 4px;" | Key Derivation Functions.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/mac.html mac]
|style="padding: 4px;" | Message Authentication Code Calculation.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/nseq.html nseq]
|style="padding: 4px;" | Create or examine a Netscape certificate sequence.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ocsp.html ocsp]
|style="padding: 4px;" | Online Certificate Status Protocol utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/passwd.html passwd]
|style="padding: 4px;" | Generation of hashed passwords.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs12.html pkcs12]
|style="padding: 4px;" | PKCS#12 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs7.html pkcs7]
|style="padding: 4px;" | PKCS#7 Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkcs8.html pkcs8]
|style="padding: 4px;" | PKCS#8 format private key conversion tool.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkey.html pkey]
|style="padding: 4px;" | Public and private key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyparam.html pkeyparam]
|style="padding: 4px;" | Public key algorithm parameter management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/pkeyutl.html pkeyutl]
|style="padding: 4px;" | Public key algorithm cryptographic operation utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/prime.html prime]
|style="padding: 4px;" | Compute prime numbers.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rand.html rand]
|style="padding: 4px;" | Generate pseudo-random bytes.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rehash.html rehash]
|style="padding: 4px;" | Create symbolic links to certificate and CRL files named by the hash values.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/req.html req]
|style="padding: 4px;" | PKCS#10 X.509 Certificate Signing Request (CSR) Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsa.html rsa]
|style="padding: 4px;" | RSA key management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/rsautl.html rsautl]
|style="padding: 4px;" | RSA utility for signing, verification, encryption, and decryption. Superseded by pkeyutl(1).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_client.html s_client]
|style="padding: 4px;" | This implements a generic SSL/TLS client which can establish a transparent connection to a remote server speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_server.html s_server]
|style="padding: 4px;" | This implements a generic SSL/TLS server which accepts connections from remote clients speaking SSL/TLS.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/s_time.html s_time]
|style="padding: 4px;" | SSL Connection Timer.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/sess_id.html sess_id]
|style="padding: 4px;" | SSL Session Data Management.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/smime.html smime]
|style="padding: 4px;" | S/MIME mail processing.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/speed.html speed]
|style="padding: 4px;" | Algorithm Speed Measurement.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/spkac.html spkac]
|style="padding: 4px;" | SPKAC printing and generating utility.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/srp.html srp]
|style="padding: 4px;" | Maintain SRP password file.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/storeutl.html storeutl]
|style="padding: 4px;" | Utility to list and display certificates, keys, CRLs, etc.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/ts.html ts]
|style="padding: 4px;" | Time Stamping Authority tool (client/server).
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/verify.html verify]
|style="padding: 4px;" | X.509 Certificate Verification.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/version.html version]
|style="padding: 4px;" | OpenSSL Version Information.
|-
|style="padding: 4px;" | [https://www.openssl.org/docs/manmaster/man1/x509.html x509]
|style="padding: 4px;" | X.509 Certificate Data Management.
|}

= Further reading =

* Paul Heinlein. [https://www.madboa.com/geek/openssl/ "OpenSSL Command-Line HOWTO"]. Has many quick cookbook-style recipes for doing common tasks using the "oppenssl" command-line application.

[[Category:Examples]]
[[Category:Shell level]]

Diffie-Hellman parameters

2019-07-29T20:54:33Z

Jflopezfernandez: Added page to examples category

To use [http://blog.ivanristic.com/2013/06/ssl-labs-deploying-forward-secrecy.html perfect forward secrecy] cipher suites, you must set up [[Diffie Hellman|Diffie-Hellman]] parameters ([http://www.mail-archive.com/openssl-users@openssl.org/msg71878.html on the server side]), or the PFS cipher suites will be silently ignored.

== Diffie-Hellman ==

<code>SSL_CTX_set_tmp_dh</code> is used to set the Diffie-Hellman parameters for a context. One of the easiest ways to get Diffie-Hellman parameters to use with this function is to generate random Diffie-Hellman parameters with the [https://www.openssl.org/docs/apps/dhparam.html dhparam] command-line program with the <code>-C</code> option, and embed the resulting code fragment in your program. For example, <code>openssl dhparam -C 2236</code> might result in:

<pre>
#ifndef HEADER_DH_H
#include <openssl/dh.h>
#endif
DH *get_dh2236()
{
static unsigned char dh2236_p[]={
0x0F,0x52,0xE5,0x24,0xF5,0xFA,0x9D,0xDC,0xC6,0xAB,0xE6,0x04,
0xE4,0x20,0x89,0x8A,0xB4,0xBF,0x27,0xB5,0x4A,0x95,0x57,0xA1,
0x06,0xE7,0x30,0x73,0x83,0x5E,0xC9,0x23,0x11,0xED,0x42,0x45,
0xAC,0x49,0xD3,0xE3,0xF3,0x34,0x73,0xC5,0x7D,0x00,0x3C,0x86,
0x63,0x74,0xE0,0x75,0x97,0x84,0x1D,0x0B,0x11,0xDA,0x04,0xD0,
0xFE,0x4F,0xB0,0x37,0xDF,0x57,0x22,0x2E,0x96,0x42,0xE0,0x7C,
0xD7,0x5E,0x46,0x29,0xAF,0xB1,0xF4,0x81,0xAF,0xFC,0x9A,0xEF,
0xFA,0x89,0x9E,0x0A,0xFB,0x16,0xE3,0x8F,0x01,0xA2,0xC8,0xDD,
0xB4,0x47,0x12,0xF8,0x29,0x09,0x13,0x6E,0x9D,0xA8,0xF9,0x5D,
0x08,0x00,0x3A,0x8C,0xA7,0xFF,0x6C,0xCF,0xE3,0x7C,0x3B,0x6B,
0xB4,0x26,0xCC,0xDA,0x89,0x93,0x01,0x73,0xA8,0x55,0x3E,0x5B,
0x77,0x25,0x8F,0x27,0xA3,0xF1,0xBF,0x7A,0x73,0x1F,0x85,0x96,
0x0C,0x45,0x14,0xC1,0x06,0xB7,0x1C,0x75,0xAA,0x10,0xBC,0x86,
0x98,0x75,0x44,0x70,0xD1,0x0F,0x20,0xF4,0xAC,0x4C,0xB3,0x88,
0x16,0x1C,0x7E,0xA3,0x27,0xE4,0xAD,0xE1,0xA1,0x85,0x4F,0x1A,
0x22,0x0D,0x05,0x42,0x73,0x69,0x45,0xC9,0x2F,0xF7,0xC2,0x48,
0xE3,0xCE,0x9D,0x74,0x58,0x53,0xE7,0xA7,0x82,0x18,0xD9,0x3D,
0xAF,0xAB,0x40,0x9F,0xAA,0x4C,0x78,0x0A,0xC3,0x24,0x2D,0xDB,
0x12,0xA9,0x54,0xE5,0x47,0x87,0xAC,0x52,0xFE,0xE8,0x3D,0x0B,
0x56,0xED,0x9C,0x9F,0xFF,0x39,0xE5,0xE5,0xBF,0x62,0x32,0x42,
0x08,0xAE,0x6A,0xED,0x88,0x0E,0xB3,0x1A,0x4C,0xD3,0x08,0xE4,
0xC4,0xAA,0x2C,0xCC,0xB1,0x37,0xA5,0xC1,0xA9,0x64,0x7E,0xEB,
0xF9,0xD3,0xF5,0x15,0x28,0xFE,0x2E,0xE2,0x7F,0xFE,0xD9,0xB9,
0x38,0x42,0x57,0x03,
};
static unsigned char dh2236_g[]={
0x02,
};
DH *dh;

if ((dh=DH_new()) == NULL) return(NULL);
dh->p=BN_bin2bn(dh2236_p,sizeof(dh2236_p),NULL);
dh->g=BN_bin2bn(dh2236_g,sizeof(dh2236_g),NULL);
if ((dh->p == NULL) || (dh->g == NULL))
{ DH_free(dh); return(NULL); }
return(dh);
}
</pre>

which can then be used like this:

<pre>
DH *dh = get_dh2236 ();
if (1 != SSL_CTX_set_tmp_dh (ctx, dh))
error ();
DH_free (dh);
</pre>

Be sure to choose a bit length [http://www.keylength.com/en/3/ appropriate to the security level you want to achieve], although keep in mind that Diffie-Hellman parameters longer than 2236 bits may be [https://bugzilla.mozilla.org/show_bug.cgi?id=636802 incompatible with older versions of NSS]. Even worse, it appears that [http://stackoverflow.com/questions/6851461/java-why-does-ssl-handshake-give-could-not-generate-dh-keypair-exception versions of Java prior to 1.7 don't support Diffie-Hellman parameters longer than 1024 bits]!

== Validating Parameters ==

The Diffie-Hellman parameters should be validated after loading. To perform paramter validation, you call <tt>DH_check</tt>. <tt>DH_check</tt> returns 0 or a bitmask values of the following:

* <tt>DH_CHECK_P_NOT_PRIME</tt> (0x01)
* <tt>DH_CHECK_P_NOT_SAFE_PRIME</tt> (0x02)
* <tt>DH_UNABLE_TO_CHECK_GENERATOR</tt> (0x04)
* <tt>DH_NOT_SUITABLE_GENERATOR</tt> (0x08)

The validation code might look as follows (error checking omitted for clarity):

<pre>BIO* bio = ...;
DH* dh = PEM_read_bio_DHparams(bio, NULL, NULL, NULL);

int rc, codes = 0;
rc = DH_check(dh, &codes);
assert(rc == 1);

if(BN_is_word(dh->g, DH_GENERATOR_2))
{
long residue = BN_mod_word(dh->p, 24);
if(residue == 11 || residue == 23) {
codes &= ~DH_NOT_SUITABLE_GENERATOR;
}
}

if (codes & DH_UNABLE_TO_CHECK_GENERATOR)
printf("DH_check: failed to test generator\n");

if (codes & DH_NOT_SUITABLE_GENERATOR)
printf("DH_check: g is not a suitable generator\n");

if (codes & DH_CHECK_P_NOT_PRIME)
printf("DH_check: p is not prime\n");

if (codes & DH_CHECK_P_NOT_SAFE_PRIME)
printf("DH_check: p is not a safe prime\n");</pre>

The additional call to <tt>BN_mod_word(dh->p, 24)</tt> (and unmasking of <tt>DH_NOT_SUITABLE_GENERATOR</tt>) is performed to ensure your program accepts IETF group parameters. OpenSSL checks the prime is congruent to 11 when <tt>g = 2</tt>; while the IETF's primes are congruent to 23 when <tt>g = 2</tt>. Without the test, the IETF parameters would fail validation. For details, see [http://crypto.stackexchange.com/questions/12961/diffie-hellman-parameter-check-when-g-2-must-p-mod-24-11 Diffie-Hellman Parameter Check (when g = 2, must p mod 24 == 11?)].

== Elliptic curve Diffie-Hellman ==

For [[Elliptic Curve Diffie Hellman|elliptic curve Diffie-Hellman]], you can do something like this:

<pre>
EC_KEY *ecdh = EC_KEY_new_by_curve_name (NID_X9_62_prime256v1);
if (! ecdh)
error ();
if (1 != SSL_CTX_set_tmp_ecdh (ctx, ecdh))
error ();
EC_KEY_free (ecdh);
</pre>

Or, in OpenSSL 1.0.2 (not yet released, as of Feb 2013) and higher, you should be able to do:

<pre>
SSL_CTX_set_ecdh_auto (ctx, 1)
</pre>

For more information, see [[Elliptic Curve Diffie Hellman]] and [[Elliptic Curve Cryptography]].

== RFC 3526 PEM Encoded Groups ==

Below are three Diffie-Hellman MODP groups specified in [http://tools.ietf.org/html/rfc3526 RFC 3526, More Modular Exponential (MODP) Diffie-Hellman groups for Internet Key Exchange (IKE)] (the 1024-bit parameter is from RFC 2409). They can be used with <tt>PEM_read_bio_DHparams</tt> and a memory <tt>BIO</tt>. RFC 3526 also offers 1536-bit, 6144-bit and 8192-bit primes.

<pre>static const char g_dh1024_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC\n"
"-----END DH PARAMETERS-----";

static const char g_dh1536_sz[] = "-----BEGIN DH PARAMETERS-----\n"
"MIHHAoHBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR\n"
"Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL\n"
"/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7ORbPcIAfLihY78FmNpINhxV05pp\n"
"Fj+o/STPX4NlXSPco62WHGLzViCFUrue1SkHcJaWbWcMNU5KvJgE8XRsCMojcyf/\n"
"/////////wIBAg==\n"
"-----END DH PARAMETERS-----";

static const char g_dh2048_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n"
"-----END DH PARAMETERS-----";

static const char g_dh3072_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIIBiAKCAYEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqTrS\n"
"yv//////////AgEC\n"
"-----END DH PARAMETERS-----";

static const char g_dh4096_sz[] =
"-----BEGIN DH PARAMETERS-----\n"
"MIICCAKCAgEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n"
"IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n"
"awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n"
"mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n"
"fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n"
"5RXSJhiY+gUQFXKOWoqqxC2tMxcNBFB6M6hVIavfHLpk7PuFBFjb7wqK6nFXXQYM\n"
"fbOXD4Wm4eTHq/WujNsJM9cejJTgSiVhnc7j0iYa0u5r8S/6BtmKCGTYdgJzPshq\n"
"ZFIfKxgXeyAMu+EXV3phXWx3CYjAutlG4gjiT6B05asxQ9tb/OD9EI5LgtEgqSEI\n"
"ARpyPBKnh+bXiHGaEL26WyaZwycYavTiPBqUaDS2FQvaJYPpyirUTOjbu8LbBN6O\n"
"+S6O/BQfvsqmKHxZR05rwF2ZspZPoJDDoiM7oYZRW+ftH2EpcM7i16+4G912IXBI\n"
"HNAGkSfVsFqpk7TqmI2P3cGG/7fckKbAj030Nck0BjGZ//////////8CAQI=\n"
"-----END DH PARAMETERS-----";</pre>

[[Category:Examples]]

Library Initialization

2019-07-29T20:52:52Z

Jflopezfernandez: Removed the empty errata section and added page to the examples category

This page discusses OpenSSL library initialization when using the <tt>libssl</tt> and <tt>libcrypto</tt> components.

There are two ways to initialize the OpenSSL library, and they depend on the version of the library you are using. If you are using OpenSSL 1.0.2 or below, then you would use <tt>SSL_library_init</tt>. If you are using OpenSSL 1.1.0 or above, then the library will initialize itself automatically. Optionally you can explicitly initialise it using <tt>OPENSSL_init_ssl</tt> or <tt>OPENSSL_init_crypto</tt>. A compatibility macro exists in <tt>ssl.h</tt> that maps <tt>SSL_library_init</tt> to <tt>OPENSSL_init_ssl</tt>, so you can continue to use <tt>SSL_library_init</tt> if desired. Also see ''[http://mta.openssl.org/pipermail/openssl-dev/2016-February/005491.html SSL_library_init]'' on the OpenSSL-dev mailing list.

The rest of this page discusses initializing the library in 1.0.2. If you are using 1.1.0 or above then you don't need to take any further steps.

If you fail to initialize the library in 1.0.2, then you will experience unexplained errors like <tt>SSL_CTX_new</tt> returning <tt>NULL</tt>, error messages like <tt>SSL_CTX_new:library has no ciphers</tt> and <tt>alert handshake failure</tt> with no shared ciphers.

Below is a list of some initialization calls you might encounter in code or documentation. Unfortunately, all the initialization function return a useless values (for example, always 1) or are void functions. There is no way to determine if a failure occurred.

* SSL_library_init
* OpenSSL_add_ssl_algorithms
* OpenSSL_add_all_algorithms
* SSL_load_error_strings
* ERR_load_crypto_strings
 

== libssl Initialization ==

<tt>libssl</tt> should be initialized with calls to <tt>SSL_library_init</tt> and <tt>SSL_load_error_strings</tt>. If your program is multi-threaded, you should install the static locks. If you need (or don't need) configuration from <tt>openssl.cnf</tt>, then you should call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt>.

If you are supporting both pre-1.1.0 and post-1.1.0 version of the OpenSSL library and you want to take control of <tt>SSL_library_init</tt> and <tt>OPENSSL_init_ssl</tt>, then you can perform:

<pre>#include <openssl/opensslv.h>
...

#if OPENSSL_VERSION_NUMBER < 0x10100000L
SSL_library_init();
#else
OPENSSL_init_ssl(0, NULL);
#endif</pre>

When you call <tt>libssl</tt>, the function will also initialize <tt>libcrypto</tt> components. There are two corner cases discussed in later sections. The first corner case is static locks, and second is <tt>OPENSSL_config</tt>.

<tt>OpenSSL_add_ssl_algorithms</tt> is a <tt>#define</tt> for <tt>SSL_library_init</tt>. You only need to call one or the other. If you want to print error strings using OpenSSL's built in functions, then call <tt>SSL_load_error_strings</tt>.

The <tt>SSL_library_init</tt> function loads the algorithms use by <tt>libssl</tt>. Below is an excerpt from <tt>ssl_algs.c</tt> (with some additional formatting for clarity).

<pre>int SSL_library_init(void)
{

#ifndef OPENSSL_NO_DES
EVP_add_cipher(EVP_des_cbc());
EVP_add_cipher(EVP_des_ede3_cbc());
#endif
#ifndef OPENSSL_NO_IDEA
EVP_add_cipher(EVP_idea_cbc());
#endif
...

#ifndef OPENSSL_NO_COMP
(void)SSL_COMP_get_compression_methods();
#endif

...

/* initialize cipher/digest methods table */
ssl_load_ciphers();

return(1);
}</pre>

The call to <tt>ssl_load_ciphers</tt> simply builds a table for use in the library. The following is from <tt>ssl_ciph.c</tt> (with some additional formatting for clarity).

<pre>void ssl_load_ciphers(void)
{
ssl_cipher_methods[SSL_ENC_DES_IDX] = EVP_get_cipherbyname(SN_des_cbc);
ssl_cipher_methods[SSL_ENC_3DES_IDX] = EVP_get_cipherbyname(SN_des_ede3_cbc);
...
ssl_digest_methods[SSL_MD_MD5_IDX] = EVP_get_digestbyname(SN_md5);
ssl_mac_secret_size[SSL_MD_MD5_IDX] = EVP_MD_size(ssl_digest_methods[SSL_MD_MD5_IDX]);
...
ssl_digest_methods[SSL_MD_SHA384_IDX] = EVP_get_digestbyname(SN_sha384);
ssl_mac_secret_size[SSL_MD_SHA384_IDX] = EVP_MD_size(ssl_digest_methods[SSL_MD_SHA384_IDX]);
...
}</pre>

=== Library Apps ===

The following examines how the OpenSSL development team uses initialization in the OpenSSL utilities.

<tt>s_client</tt> initializes itself with the following calls:
* OpenSSL_add_ssl_algorithms
* SSL_load_error_strings

<tt>s_server</tt> initializes itself with the following calls:
* SSL_load_error_strings();
* OpenSSL_add_ssl_algorithms();

<tt>s_time</tt> initializes itself with the following calls:
* OpenSSL_add_ssl_algorithms();

<tt>state_machine</tt> initializes itself with the following calls:
* SSL_library_init();
* OpenSSL_add_ssl_algorithms();
* SSL_load_error_strings();
* ERR_load_crypto_strings();

== libcrypto Initialization ==

<tt>libcrypto</tt> should be initialized with calls to <tt>OpenSSL_add_all_algorithms</tt> and <tt>ERR_load_crypto_strings</tt>. If your program is multi-threaded, you should install the static locks. If you need (or don't need) configuration from <tt>openssl.cnf</tt>, then you should call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt>.

The <tt>OPENSSL_add_all_algorithms</tt> function is <tt>#define</tt>'d to either <tt>OPENSSL_add_all_algorithms_conf</tt> or <tt>OPENSSL_add_all_algorithms_noconf</tt> depending upon the value of <tt>OPENSSL_LOAD_CONF</tt>. A typical installation does ''not'' define <tt>OPENSSL_LOAD_CONF</tt>, which means <tt>OPENSSL_add_all_algorithms_noconf</tt> is used. Below is an excerpt from <tt>c_all.c</tt> (with some additional formatting for clarity).

<pre>void OPENSSL_add_all_algorithms_noconf(void)
{
/*
* For the moment OPENSSL_cpuid_setup does something
* only on IA-32, but we reserve the option for all
* platforms...
*/
OPENSSL_cpuid_setup();
OpenSSL_add_all_ciphers();
OpenSSL_add_all_digests();
...
}</pre>

<tt>OpenSSL_add_all_ciphers</tt> looks a lot like <tt>SSL_library_init</tt> from the <tt>libssl</tt> initialization routines (sans the call to <tt>ssl_load_ciphers</tt>). Below is an excerpt from <tt>c_allc.c</tt> (with some additional formatting for clarity).

<pre>void OpenSSL_add_all_ciphers(void)
{

#ifndef OPENSSL_NO_DES
EVP_add_cipher(EVP_des_cfb());
EVP_add_cipher(EVP_des_cfb1());
EVP_add_cipher(EVP_des_cfb8());
EVP_add_cipher(EVP_des_ede_cfb());
EVP_add_cipher(EVP_des_ede3_cfb());
EVP_add_cipher(EVP_des_ede3_cfb1());
EVP_add_cipher(EVP_des_ede3_cfb8());
...
#endif

#ifndef OPENSSL_NO_RC4
EVP_add_cipher(EVP_rc4());
EVP_add_cipher(EVP_rc4_40());
# ifndef OPENSSL_NO_MD5
EVP_add_cipher(EVP_rc4_hmac_md5());
# endif
#endif

...

/* Note: there is no call to ssl_load_ciphers() here */
}</pre>

Finally, [http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html <tt>OpenSSL_add_all_algorithms(3)</tt>] offers the following advice:

<blockquote>Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a statically linked executable can be quite large. If this is important it is possible to just add the required ciphers and digests.</blockquote>

If you want the small footprint, then call <tt>EVP_add_cipher</tt> with the ciphers and algorithms you need (and nothing more).

=== Library Apps ===

The following examines how the OpenSSL development team uses initialization in the OpenSSL utilities.

<tt>enc</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();

<tt>dec</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();

<tt>pkcs8</tt> initializes itself with the following calls:
* ERR_load_crypto_strings();
* OpenSSL_add_all_algorithms();

<tt>cms_sign</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();
* ERR_load_crypto_strings();

<tt>cms_ver</tt> initializes itself with the following calls:
* OpenSSL_add_all_algorithms();
* ERR_load_crypto_strings();

== ENGINEs and RDRAND ==

A call to <tt>ENGINE_load_builtin_engines</tt> loads all built-in engines, including those for <tt>AES_NI</tt> instructions and <tt>RDRAND</tt>. After the call, OpenSSL will use the engines for AES encryption and random number generation, if available. In this case, <tt>RDRAND</tt> will be the only source of random numbers.

If you are concerned over possible <tt>RDRAND</tt> tampering, then you should explicitly call <tt>RAND_set_rand_engine(NULL)</tt> after loading all engines. If another module in the program happens to call <tt>ENGINE_load_builtin_engines</tt> again, then you will go back to using <tt>RDRAND</tt>.

You can also call <tt>ENGINE_unregister_RAND</tt> followed by <tt>ENGINE_register_all_complete</tt> to unregister <tt>RDRAND</tt> as default random number generator implementation.

To avoid accidental use of <tt>RDRAND</tt>, you can build OpenSSL with <tt>OPENSSL_NO_RDRAND</tt> defined. This is the preferred method to avoid all use of <tt>RDRAND</tt>.

Future version of the library will change the default behavior. That is, in the future, you will have to explicitly call <tt>ENGINE_load_rdrand</tt> if you want to use <tt>RDRAND</tt>. The change has been checked in, but its only available through <tt>git</tt> at the moment.

For the full discussion, see coderman's ''[http://seclists.org/fulldisclosure/2013/Dec/99 RDRAND used directly when default engines loaded in openssl-1.0.1-beta1 through openssl-1.0.1e]''.

== Static Locks ==

If your program is multi-threaded, then you will need to install the static locks. The static locks are used for extensively for <tt>libssl</tt>, and used in the random number generator for <tt>libcrypto</tt>. The locks should be installed '''''after''''' the calling:

* SSL_library_init
* OpenSSL_add_ssl_algorithms
* OpenSSL_add_all_algorithms
* SSL_load_error_strings
* ERR_load_crypto_strings

See [http://stackoverflow.com/a/42856544/608639 Multithreaded program using OpenSSL and locks randomly crashes] on Stack Overflow and [http://www.openssl.org/docs/crypto/threads.html threads(3)] for details until the wiki is updated with an example.

== OPENSSL_config ==

<tt>OPENSSL_config</tt> and <tt>OPENSSL_noconfig</tt> loads and unloads <tt>openssl.cnf</tt>. More correctly, a call to <tt>OPENSSL_config(NULL)</tt> loads the default configuration in <tt>openssl.cnf</tt>, <tt>OPENSSL_config(filename)</tt> loads another configuration, and <tt>OPENSSL_noconfig</tt> unlods a configuration.

<tt>OPENSSL_config</tt> may (or may not) be called depending upon how the OpenSSL library was configured, and it depends on whether <tt>OPENSSL_LOAD_CONF</tt> was defined. Because <tt>OPENSSL_config</tt> may (or may not) be called, your program may or may not need to make the call to <tt>OPENSSL_config</tt>. If, for example, your program is dynamically loading an ENGINE from <tt>OPENSSL_config</tt>, then you will need to ensure a call to <tt>OPENSSL_config</tt>.

You can check the value of <tt>OPENSSL_LOAD_CONF</tt> by <tt>cat</tt>'ing you<tt><nowiki><openssl/opensslconf.h></nowiki></tt>. You can then decide to call <tt>OPENSSL_config</tt> or <tt>OPENSSL_noconfig</tt> based upon the definition (or lack threof) for <tt>OPENSSL_LOAD_CONF</tt>.

<pre>$ cat /usr/local/ssl/include/openssl/opensslconf.h | grep -i load
$</pre>

Here are the rules you should observe. In either case, your program should not depend upon the OpenSSL library and get into a known state.

* If you need something from <tt>openssl.cnf</tt>, then call <tt>OPENSSL_config</tt>. Don't depend on the library to do it for you.
* If you don't need something from <tt>openssl.cnf</tt> (or its mucking up you program), then call <tt>OPENSSL_noconfig</tt>. The library may have called <tt>OPENSSL_config</tt> for you.

== Engines ==

If your application needs to use engines, then it should either call call <tt>ENGINE_load_builtin_engines</tt> or <tt>OPENSSL_config</tt> to load the built-in engines (including dynamically configured engines from <tt>openssl.cnf</tt>).

Engines are are automatically loaded (or not loaded) based on the definition of <tt>OPENSSL_LOAD_CONF</tt> (or lack of definition). You should not depend on library behavior, so you should call <tt>OPENSSL_config</tt> or <tt>ENGINE_load_builtin_engines</tt> if you need engines.

You can also load a particular engine if you know what you want to use. <tt>eng_all.c</tt> lists the built-in engines you can load. For example, the following loads the <tt>rdrand</tt> engine provided for some Intel CPUs.

<pre>unsigned long err = 0;
int rc = 0;

OPENSSL_cpuid_setup();
ENGINE_load_rdrand();

ENGINE* eng = ENGINE_by_id("rdrand");
if(NULL == eng) handleFailure();

rc = ENGINE_init(eng);
if(1 != rc) handleFailure();

rc = ENGINE_set_default(eng, ENGINE_METHOD_RAND);
if(1 != rc) handleFailure();

/* OK to proceed */
...

ENGINE_finish(eng);
ENGINE_free(eng);
ENGINE_cleanup();</pre>

If you want an engine to provide all incumbent functionality for the OpenSSL library, then then call <tt>ENGINE_register_complete</tt> after loading the engine. Incumbent functionality is determined by the manufacturer and includes includes RSA, DSA, DH, ECDH, MD, and RAND operations. See <tt>eng_all.c</tt>, <tt>eng_fat.c</tt>, and [http://www.openssl.org/docs/crypto/engine.html engine(3)] for details.

<pre>ENGINE* eng = ENGINE_by_id("XXX");
if(!(eng->flags & ENGINE_FLAGS_NO_REGISTER_ALL))
ENGINE_register_complete(eng);</pre>

== Cleanup ==

How to cleanup the library arises on occasion. Its often in the context of running a program under a memory checker like Valgrind.

OpenSSL does not provide a <tt>SSL_library_uninit</tt> or <tt>SSL_library_cleanup</tt> function (also see [http://rt.openssl.org/Ticket/Display.html?id=3824&user=guest&pass=guest Issue #3824, FEATURE: Please provide a function to unintialize the library]). To cleanup the library the library call the following functions:

* FIPS_mode_set(0);
* ENGINE_cleanup();
* CONF_modules_unload(1);
* EVP_cleanup();
* CRYPTO_cleanup_all_ex_data();
* ERR_remove_state();
* ERR_free_strings();

'''Note:''' ERR_remove_state() was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state() was introduced. ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the thread handling functionality was entirely rewritten.

<tt>CRYPTO_cleanup_all_ex_data</tt> and <tt>ERR_remove_state</tt> should be called on each thread, and not just the main thread.

The above list is a minimum to call. You will still need to cleanup Diffie-Hellman parameters, server contexts, static locks, etc.

After cleanup, you may have some memory leaks due to dynamic allocation of private static variables like <tt>ssl_comp_methods</tt>. This is a well known issue (see [http://rt.openssl.org/Ticket/Display.html?id=2561&user=guest&pass=guest Issue #2561, Memory leak with SSL built-in compressions]).

==Autoconf==

OpenSSL uses its own configuration system, and does not use Autoconf. However, a number of popular projects use both OpenSSL and Autoconf, and it would be usful to detect either <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt> from <tt>libssl</tt>. To craft a feature test for OpenSSL that recognizes both <tt>OPENSSL_init_ssl</tt> and <tt>SSL_library_init</tt>, you can use the following.

<pre>if test "$with_openssl" = yes ; then
dnl Order matters!
if test "$PORTNAME" != "win32"; then
AC_CHECK_LIB(crypto, CRYPTO_new_ex_data, [], [AC_MSG_ERROR([library 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_CHECK_LIB(ssl, OPENSSL_init_ssl, [FOUND_SSL_LIB="yes"])
AC_CHECK_LIB(ssl, SSL_library_init, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssl' is required for OpenSSL])])
else
AC_SEARCH_LIBS(CRYPTO_new_ex_data, eay32 crypto, [], [AC_MSG_ERROR([library 'eay32' or 'crypto' is required for OpenSSL])])
FOUND_SSL_LIB="no"
AC_SEARCH_LIBS(OPENSSL_init_ssl, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AC_SEARCH_LIBS(SSL_library_init, ssleay32 ssl, [FOUND_SSL_LIB="yes"])
AS_IF([test "x$FOUND_SSL_LIB" = xno], [AC_MSG_ERROR([library 'ssleay32' or 'ssl' is required for OpenSSL])])
fi
fi</pre>

Many thanks to the Postgres folks for donating part of their <tt>configure.in</tt>. Also see [http://stackoverflow.com/q/39285733 How to tell Autoconf “require symbol A or B” from LIB?] on Stack Overflow.

[[Category:Examples]]

Template:Expert Review

2019-07-29T20:50:59Z

Jflopezfernandez: Created template for request expert reviews

[[:Category:Expert Review|[Expert Review Required]]]

<noinclude>
==Overview==
The purpose of this template is to be able to quickly and efficiently group the articles that require attention from experts.

==Usage==
Generating random numbers is essential to cryptographically-secure applications<nowiki>{{Expert Review}}</nowiki>.
</noinclude>

Simple TLS Server

2019-07-29T20:10:41Z

Jflopezfernandez: Added page to the Examples and C level categories

The code below is a complete implementation of a minimal TLS server. The first thing we do is initialise openssl in the ''init_openssl()'' function by loading the strings used for error messages, and setting up the algorithms needed for TLS. We then create an ''SSL_CTX'' or SSL context. This is created using the ''SSLv23_server_method'' which despite its name actually creates a server that will negotiate the highest version of SSL/TLS supported by the client it is connecting to. The context is then configured - we use ''SSL_CTX_set_ecdh_auto'' to tell openssl to handle selecting the right elliptic curves for us (this function isn't available in older versions of openssl which required this to be done manually). The final step of configuring the context is to specify the certificate and private key to use.

Next we perform some normal socket programming and create a new server socket, there's nothing openssl specific about this code. Whenever we get a new connection we call ''accept'' as normal. To handle the TLS we create a new ''SSL'' structure, this holds the information related to this particular connection. We use ''SSL_set_fd'' to tell openssl the file descriptor to use for the communication. In this example, we call ''SSL_accept'' to handle the server side of the TLS handshake, then use ''SSL_write()'' to send our message. Finally we clean up the various structures.

<pre>

#include <stdio.h>
#include <unistd.h>
#include <string.h>
#include <sys/socket.h>
#include <arpa/inet.h>
#include <openssl/ssl.h>
#include <openssl/err.h>

int create_socket(int port)
{
int s;
struct sockaddr_in addr;

addr.sin_family = AF_INET;
addr.sin_port = htons(port);
addr.sin_addr.s_addr = htonl(INADDR_ANY);

s = socket(AF_INET, SOCK_STREAM, 0);
if (s < 0) {
perror("Unable to create socket");
exit(EXIT_FAILURE);
}

if (bind(s, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
perror("Unable to bind");
exit(EXIT_FAILURE);
}

if (listen(s, 1) < 0) {
perror("Unable to listen");
exit(EXIT_FAILURE);
}

return s;
}

void init_openssl()
{
SSL_load_error_strings();
OpenSSL_add_ssl_algorithms();
}

void cleanup_openssl()
{
EVP_cleanup();
}

SSL_CTX *create_context()
{
const SSL_METHOD *method;
SSL_CTX *ctx;

method = SSLv23_server_method();

ctx = SSL_CTX_new(method);
if (!ctx) {
perror("Unable to create SSL context");
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}

return ctx;
}

void configure_context(SSL_CTX *ctx)
{
SSL_CTX_set_ecdh_auto(ctx, 1);

/* Set the key and cert */
if (SSL_CTX_use_certificate_file(ctx, "cert.pem", SSL_FILETYPE_PEM) <= 0) {
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}

if (SSL_CTX_use_PrivateKey_file(ctx, "key.pem", SSL_FILETYPE_PEM) <= 0 ) {
ERR_print_errors_fp(stderr);
exit(EXIT_FAILURE);
}
}

int main(int argc, char **argv)
{
int sock;
SSL_CTX *ctx;

init_openssl();
ctx = create_context();

configure_context(ctx);

sock = create_socket(4433);

/* Handle connections */
while(1) {
struct sockaddr_in addr;
uint len = sizeof(addr);
SSL *ssl;
const char reply[] = "test\n";

int client = accept(sock, (struct sockaddr*)&addr, &len);
if (client < 0) {
perror("Unable to accept");
exit(EXIT_FAILURE);
}

ssl = SSL_new(ctx);
SSL_set_fd(ssl, client);

if (SSL_accept(ssl) <= 0) {
ERR_print_errors_fp(stderr);
}
else {
SSL_write(ssl, reply, strlen(reply));
}

SSL_free(ssl);
close(client);
}

close(sock);
SSL_CTX_free(ctx);
cleanup_openssl();
}

</pre>

== Session Reuse ==

According to Viktor Dukhovni at [http://mta.openssl.org/pipermail/openssl-users/2016-September/004564.html Possible to control session reuse from the client]:

<pre>> For performance testing purposes, I would like to turn off session
> reuse in the (homegrown) client I use for testing. Is there a function
> in the openssl library to do it?
>
> I tried googling for "openssl client don't send session id" but I didn't
> find anything useful.

Just do nothing. Client sessions are not reused unless you explicitly
arrange for reuse of a session by calling SSL_set_session() before
SSL_connect(). If you're trying to avoid wasting memory on storing
client-side sessions that you'll never reuse then this may help:

SSL_CTX_set_session_cache_mode(client_ctx, SSL_SESS_CACHE_OFF);

but note this is also the default state, so is also not needed unless
some other code has explicitly enabled client-side caching of sessions.

Only the server-side cache is enabled by default.</pre>

== 0-RTT ==

0-RTT is specified in XXX (TODO). 0-RTT allows an application to immediately resume a previous session at the expense of consuming unauthenticated data. You should avoid 0-RTT if possible. In fact, an organization's data security policy may not allow it for some higher data sensitivity levels.

Care should be taken if enabling 0-RTT at the server because a number of protections must be enabled. Additionally, some of the protections are required higher up in the stack, outside of the secure socket layer. Below is a list of potential problems from [http://www.ietf.org/mail-archive/web/tls/current/msg23561.html Closing on 0-RTT] on the IETF TLS working group mailing list.

* 0-RTT without stateful anti-replay allows for very high number of replays, breaking rate limiting systems, even high-performance ones, resulting in an opening for DDoS attacks.

* 0-RTT without stateful anti-replay allows for very high number of replays, allowing exploiting timing side channels for information leakage. Very few if any applications are engineered to mitigate or eliminate such side channels.

* 0-RTT without global anti-replay allows leaking information from the 0-RTT data via cache timing attacks. HTTP GET URLs sent to CDNs are especially vulnerable.

* 0-RTT without global anti-replay allows non-idempotent actions contained in 0-RTT data to be repeated potentially lots of times. Abuse of HTTP GET for non-idempotent actions is fairly common.

* 0-RTT allows easily reordering request with re-transmission from the client. This can lead to various unexpected application behavior if possibility of such reordering is not taken into account. "Eventually consistent" datastores are especially vulnerable.

* 0-RTT exporters are not safe for authentication unless the server does global anti-replay on 0-RTT.

[[Category:Examples]]
[[Category:C level]]

Talk:Multiprecision arithmetic internals

2019-07-29T14:58:19Z

Jflopezfernandez: Replying to thread

== BN Library Broken Link ==

It looks like [https://www.openssl.org/docs/man1.0.2/man3/bn.html this] is the documentation the first link was supposed to point to, but this documentation module is not in version 1.1.1. Since
I would assume this means either the module or the interface is deprecated, what is the recommendation in this scenario where we're updating the documentation regarding a deprecated function or library?
Should I keep the broken link notice and not even list it to prevent new users from using a deprecated feature, at least until we finish modernizing the documentation? Or do I add it in and simply
append a notice stating the feature is part of a deprecated API?

--[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 06:25, 29 July 2019 (UTC)

Actually the BN API is not deprecated. It's just that there's been quite a lot of work over time on trying to improve the documentation and lots of stuff got moved around. It looks like at some point this overview page got deleted - I'm not entirely sure why. I'd suggest we could direct users to some of the key BIGNUM pages instead, such as [https://www.openssl.org/docs/man1.1.1/man3/BN_new.html BN_new()], [https://www.openssl.org/docs/man1.1.1/man3/BN_add.html BN_add()], etc.

--[[User:Matt|Matt]] ([[User talk:Matt|talk]]) 07:57, 29 July 2019 (UTC)

: Ah, okay, that's good to know. I'll go ahead and add links to those pages.
:
:--[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 14:58, 29 July 2019 (UTC)

Template:Broken Link

2019-07-29T07:27:28Z

Jflopezfernandez: Added an overview for the template

RC4

2019-07-29T07:13:17Z

Jflopezfernandez: Added a source for the weaknesses in the WEP protocol

The '''RC4''' algorithm is a [[Stream Cipher|stream cipher]] developed by [https://en.wikipedia.org/wiki/Ron_Rivest Ron Rivest] in 1987. [https://en.wikipedia.org/wiki/RC4 RC4] was a trade secret [http://web.archive.org/web/20061024160937/http://cypherpunks.venona.com/date/1994/09/msg00304.html famously leaked] in 1994 to the [https://en.wikipedia.org/wiki/Cypherpunk cypherpunks] mailing list. A little over a year after RC4 was leaked, Andrew Roos posted a [https://netfuture.ch/1995/09/weak-keys-in-rc4/ paper] to the [https://en.wikipedia.org/wiki/Cryptography_newsgroups sci.crypt] newsgroup claiming he discovered a weakness in RC4's keystream generation. Specifically, Roo claimed to have found [https://blog.cryptographyengineering.com/2011/12/15/whats-deal-with-rc4/ evidence to suggest] the concatenated initialization vectors used by the stream cipher were a significant vulnerability. Roo was proven right years later, with the [https://en.wikipedia.org/wiki/Wired_Equivalent_Privacy#Weak_security infamous] [https://eprint.iacr.org/2007/471 failure] of the new (at the time) [https://en.wikipedia.org/wiki/Wired_Equivalent_Privacy WEP] standard.

[[Category:Cryptographic Algorithm]]
[[Category:Stream Cipher]]
[[Category:Secret Key Algorithm]]
[[Category:Legal]]

Stream Cipher

2019-07-29T06:58:28Z

Jflopezfernandez: Reorganized the page a bit

A '''stream cipher''' is a cipher operating on a flow of data (a ''stream''), as opposed to a block at a time.

==See Also==
* [[Block Cipher]]
* [[:Category:Block Cipher|Block Ciphers]]

[[Category:Cryptographic Algorithm]]

RC4

2019-07-29T06:54:36Z

Jflopezfernandez: Added some background information on RC4

The '''RC4''' algorithm is a [[Stream Cipher|stream cipher]] developed by [https://en.wikipedia.org/wiki/Ron_Rivest Ron Rivest] in 1987. [https://en.wikipedia.org/wiki/RC4 RC4] was a trade secret [http://web.archive.org/web/20061024160937/http://cypherpunks.venona.com/date/1994/09/msg00304.html famously leaked] in 1994 to the [https://en.wikipedia.org/wiki/Cypherpunk cypherpunks] mailing list. A little over a year after RC4 was leaked, Andrew Roos posted a [https://netfuture.ch/1995/09/weak-keys-in-rc4/ paper] to the [https://en.wikipedia.org/wiki/Cryptography_newsgroups sci.crypt] newsgroup claiming he discovered a weakness in RC4's keystream generation. Specifically, Roo claimed to have found [https://blog.cryptographyengineering.com/2011/12/15/whats-deal-with-rc4/ evidence to suggest] the concatenated initialization vectors used by the stream cipher were a significant vulnerability. Roo was proven right years later, with the [https://en.wikipedia.org/wiki/Wired_Equivalent_Privacy#Weak_security infamous failure] of the new (at the time) [https://en.wikipedia.org/wiki/Wired_Equivalent_Privacy WEP] standard.

[[Category:Cryptographic Algorithm]]
[[Category:Stream Cipher]]
[[Category:Secret Key Algorithm]]
[[Category:Legal]]

Talk:Multiprecision arithmetic internals

2019-07-29T06:25:19Z

Jflopezfernandez: /* BN Library Broken Link */ new section

Multiprecision arithmetic internals

2019-07-29T06:16:45Z

Jflopezfernandez: Added a second broken link note

OpenSSL includes an implementation of multiprecision arithmetic,
used for dealing with the large numbers used in public-key cryptography and a few other cryptographic algorithms.

[http://www.openssl.org/docs/crypto/bn.html "bn(3) overview"]{{Broken Link}}

[http://www.openssl.org/docs/crypto/bn_internal.html "bn_internal(3)"]{{Broken Link}},
BIGNUM library internal functions "to facilitate debugging and extending the library.
They are not to be used by applications."

Other popular [http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic multiprecision libraries and tools] that perhaps might be useful for testing OpenSSL's multiprecision implementation include:
[http://gmplib.org/ GMP],
the [http://en.wikipedia.org/wiki/bc_(programming_language) bc programming language],
etc.

Template:Broken Link

2019-07-29T06:00:59Z

Jflopezfernandez: Added Broken Links category link to facilitate tracking of pages with broken links

[[:Category:Broken Links|[Broken Link]]]

[[Category:Broken Links]]

Multiprecision arithmetic internals

2019-07-29T05:57:34Z

Jflopezfernandez: Added broken link note to bn(3) overview

OpenSSL includes an implementation of multiprecision arithmetic,
used for dealing with the large numbers used in public-key cryptography and a few other cryptographic algorithms.

[http://www.openssl.org/docs/crypto/bn.html "bn(3) overview"]{{Broken Link}}

[http://www.openssl.org/docs/crypto/bn_internal.html "bn_internal(3)"],
BIGNUM library internal functions "to facilitate debugging and extending the library.
They are not to be used by applications."

Other popular [http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic multiprecision libraries and tools] that perhaps might be useful for testing OpenSSL's multiprecision implementation include:
[http://gmplib.org/ GMP],
the [http://en.wikipedia.org/wiki/bc_(programming_language) bc programming language],
etc.

Category:Broken Links

2019-07-29T05:56:51Z

Jflopezfernandez: Created category for pages with broken links

Template:Broken Link

2019-07-29T05:56:41Z

Jflopezfernandez: Created template for broken links

[[:Category:Broken Links|[Broken Link]]]

Mailing Lists

2019-07-29T05:24:57Z

Jflopezfernandez: My previous rewrite sounded a little weird

We have several community mailing lists. See the OpenSSL Community [https://www.openssl.org/community/mailinglists.html Mailing Lists] page for more information.

Talk:Elliptic Curve Cryptography

2019-07-29T03:37:24Z

Jflopezfernandez: Replying to thread

== Source Code Highlighting ==

I messed around with the sample code and came up with some basic highlighting that I thought made the code easier to read. This is a sample of what I would be changing the sample code to:

<div>
#include <openssl/obj_mac.h>
#include <openssl/ec.h>

/* Other things up here... */

EC_GROUP *curve;

if(NULL == (curve = EC_GROUP_new_by_curve_name(NID_secp224r1)))
handleErrors();
</div>

I have no strong feelings towards the specific colors, I just picked something I thought was simple and clean. By all means if you have a suggestion regarding the theme I'm all ears. As I said, the point of this change is to make the code easier to read, and since I know theme selection and taste are pretty arbitrary and some people might prefer the code as it is, I thought it best to leave the sample code on live as it was for now.

[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 02:50, 29 July 2019 (UTC)

: I believe mediawiki has colorizers to do that; see [https://www.mediawiki.org/wiki/Category:Syntax_highlighting_extensions Syntax highlighting extensions]. Maybe you can ping Richard and ask him to install one.
: If there is a pain point, it will likely be CentOS. Red Hat provides ancient software (even with SCL enabled) so OpenSSL mediawiki software is old. You may have a hard time finding an acceptable extension because mediawiki is too old.
:
: [[User:Jwalton|Jwalton]] ([[User talk:Jwalton|talk]]) 03:24, 29 July 2019 (UTC)

:: I was wondering about that, actually. I did see there were extensions for this, but I wasn't sure whom to ask so I was about to send Matt an email to ask if he could point me in the
:: right direction. I'll send Richard an email and see what he says. Thanks for the heads up.
::
:: [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 03:37, 29 July 2019 (UTC)

Talk:Libcrypto API

2019-07-29T03:27:49Z

Jflopezfernandez: Replying to thread

==Current Discussions==

=== Initialization, OPENSSL_conf and engines? ===

Should the recommended initialization code include a call to ENGINE_load_builtin_engines? (Or to OPENSSL_config, which calls ENGINE_load_builtin_engines.) Otherwise, the RdRand engine for getting better random numbers from newer Intel chips (as one example) won't be used.

(My own thoughts on OpenSSL initialization are [https://en.wikibooks.org/wiki/OpenSSL/Initialization here].)

--[[User:Ppelleti|Ppelleti]] 18:05, 3 March 2013 (UTC)

Hmmm - I've not come across this as a recommendation before. What is the original source for your recommendation?

--[[User:Matt|Matt]] 22:15, 3 March 2013 (UTC)

It's not from any existing documentation source, other than gleaning some information from the [https://www.openssl.org/docs/crypto/engine.html#Application_requirements engine] manpage (see "Automatically using builtin ENGINE implementations") and the CHANGES file. But mostly it's my own conclusion, based on reading the source code and performing experiments.

The basic question I was trying to answer was, on modern Intel processors which support AES-NI and RdRand, is OpenSSL taking advantage of these hardware features. The answer appears to be different for the two different features. For AES-NI, it appears from the source code (and was recently [http://marc.info/?l=openssl-users&m=136209324829507&w=2 confirmed] on the mailing list) that AES-NI is automatically used if it is available, without needing to do anything special.

However, for RdRand, it appears that the answer is different. In the source code, there is a separate RdRand engine. If the RdRand engine is not used, then the default pool implementation in md_rand.c is used, and you don't get the benefits of RdRand.

From the section I already mentioned in the "engine" manpage, it sounded like no engines are used by default, and you must enable them by calling ENGINE_load_builtin_engines() followed by ENGINE_register_all_complete(). Although the CHANGES file partially contradicts this advice, saying:

<pre>
*) Add call to ENGINE_register_all_complete() to
ENGINE_load_builtin_engines(), so some implementations get used
automatically instead of needing explicit application support.
[Steve Henson]
</pre>

I did some experiments on a machine with RdRand. I wrote the following little bit of code:

<pre>
ENGINE *rnd = ENGINE_get_default_RAND ();
if (rnd)
printf ("default rand engine: %s\n", ENGINE_get_name (rnd));
else
printf ("no default rand engine\n");
</pre>

If I initialize OpenSSL the typical way:

<pre>
SSL_load_error_strings(); /* readable error messages */
SSL_library_init(); /* initialize library */
OpenSSL_add_all_algorithms();
</pre>

without calling any ENGINE functions, then my little code fragment will print "no default rand engine", indicating the implementation from md_rand.c is being used. But if I call ENGINE_load_builtin_engines() after the other initialization functions, and before my little test, it then prints out that RdRand is the default rand engine.

So, this is how I drew the conclusion that it's necessary to call ENGINE_load_builtin_engines() as part of your initialization, if you want to get RdRand support.

However, this is all made a little bit trickier by the fact that OpenSSL_add_all_algorithms() can actually mean one of two vastly different things, depending on a #define at compile time. If OPENSSL_LOAD_CONF is defined, then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_conf(), but if OPENSSL_LOAD_CONF is not defined (which is the default), then OpenSSL_add_all_algorithms() is really OPENSSL_add_all_algorithms_noconf().

OPENSSL_add_all_algorithms_conf() is a two-line function:

<pre>
void OPENSSL_add_all_algorithms_conf(void)
{
OPENSSL_add_all_algorithms_noconf();
OPENSSL_config(NULL);
}
</pre>

So the difference is that if OPENSSL_LOAD_CONF is defined, then OPENSSL_config() is called, when it otherwise wouldn't be. What does this have to do with RdRand? The thing is that OPENSSL_config() calls ENGINE_load_builtin_engines(). (And then ENGINE_load_builtin_engines() in turn calls ENGINE_register_all_complete(), as mentioned in the CHANGES entry.)

So, to get RdRand support, you can either #define OPENSSL_LOAD_CONF when building your program, or you can call either ENGINE_load_builtin_engines() or OPENSSL_config() in your initialization sequence. However, it appears that calling ENGINE_load_builtin_engines() more than once will leak memory, so ideally you don't want to call ENGINE_load_builtin_engines() if you also plan on calling OPENSSL_config(), or if you've defined OPENSSL_LOAD_CONF. (Of course, since it's just a small fixed-size leak at initialization, this wouldn't really be a practical problem, but still makes me feel icky.)

--[[User:Ppelleti|Ppelleti]] 04:33, 4 March 2013 (UTC)

: > For AES-NI, it appears from the source code
: > (and was recently confirmed on the mailing list)
: > that AES-NI is automatically used if it is
: > available, without needing to do anything special.
: > However, for RdRand, it appears that the answer is
: > different.
: Perhaps it is because the hardware support for AES-NI and RDRAND was provided at different times. Its somewhat odd the Change Log shows them being cut-in at the same time in March, 2012 (http://www.openssl.org/news/changelog.html).
: AES-NI and PCLMULQDQ was introduced with Sandy Bridge in January, 2011. Confer, http://en.wikipedia.org/wiki/Sandy_Bridge_(microarchitecture). RdRand was introduced with 3rd generation i5's and i7's via Ivy Bridge in April, 2012. Confer, http://en.wikipedia.org/wiki/Ivy_Bridge_(computer_processor).
: [[User:Jwalton|Jwalton]] 04:00, 7 March 2013 (UTC)

Note that the use of OPENSSL_config() '''is''' recommended during initialisation: this is mentioned in the manual page. Currently the routines associated with OPENSSL_config() can be used for adding OIDs and configuring ENGINEs. In future it may well do much more and calling OPENSSL_config() (or the actual conf library if finer control is needed) will automatically take advantage of that.

Here's an example of what I mean. Suppose you have a user who wants to do something weird with an ENGINE: perhaps load an unusual one that needs various ctrls to get it to work. Maybe they want to do something peculiar like use RSA with one ENGINE and DSA with another. You'd have to delve quite deep into the way ENGINE works to support that kind of thing and would it be worth it for something hardly anyone would use?

If instead you called OPENSSL_config() that user can just set up the config file to do what they want and the application writer doesn't have to worry about all the messy ENGINE calls.

--[[User:Steve|Steve]] 13:37, 4 March 2013 (UTC)

So, I've added a call to OPENSSL_config() during the initialisation example. This I think covers both Steve's point above, and Patrick's concern about loading the builtin engines.

--[[User:Matt|Matt]] 21:01, 4 March 2013 (UTC)

=== Return values ===

Note that not all of the libcrypto functions return 0 for error and 1 for success. There '''are''' exceptions which can trip up the unwary. For example if you want to check a signature with some functions you get 1 if the signature is correct, 0 if it is not correct and -1 if something bad happened like a memory allocation failure. So if you do:

<pre>
if (some_verify_function())
/* signature successful */
</pre>

and someone can induce the "something bad happened" condition you end up behaving as though a bad signature is good. This one cropped up in the library internals at one point and was fixed in a security release. Currently you should check the manual pages or the source to be sure. It would be '''really''' useful if the exceptions were all documented, double checking with the source.

--[[User:Steve|Steve]] 13:57, 4 March 2013 (UTC)

I've added this to the error handling section

--[[User:Matt|Matt]] 21:05, 4 March 2013 (UTC)

Yeah, I've noticed this, and in my own code I've chosen to always compare OpenSSL return values against 1 explicitly. In the spirit of "be bold", I've gone ahead and added this as a recommendation on the page itself. But if anyone thinks this is not a good approach, feel free to change it.

--[[User:Ppelleti|Ppelleti]] 00:37, 5 March 2013 (UTC)

I'm happy with that...but now I'm wondering whether for consistency we should use this throughout the examples that we post on the wiki.

Also, the way the page now reads it looks like we are only recommending your idiom for those functions which might return something other than 0 or 1. Would it not be better to recommend this for all functions even if they do only return 0 or 1. By getting into the habit of always checking in this way it probably means you are less likely to inadvertently go wrong.

Finally, is it not the case that most of the time the if statement is checking of an error condition. Therefore shouldn't we write the code more like this:

<pre>
if(1 != some_function())
/* handle the error */
</pre>
--[[User:Matt|Matt]] 22:31, 5 March 2013 (UTC)

I agree on both points. I'd meant "this idiom can be used to avoid having to worry about whether a particular function can return more than just 0 or 1 or not", and I always use that idiom in my own code for precisely that reason. But I don't think I made my meaning clear enough on the page. I've rephrased it a bit now, but the phrasing still feels a bit awkward, so feel free to improve it to be clearer.

And yes, I agree about flipping the sense of the check. I'd just been trying to be symmetrical with the example right above it.

But I've now flipped the sense, and I've also modified the earlier example (demonstrating "goto") to use the "1 !=" idiom.

--[[User:Ppelleti|Ppelleti]] 01:25, 6 March 2013 (UTC)

==Old Discussions==

=== Best practices for printing errors ===

I'm curious about the recommendation to do this:

<pre>
err:
unsigned long errCode;
while(errCode = ERR_get_error())
{
char *err = ERR_error_string(errCode, NULL);
printf("%s\n", err);
}
</pre>

Wouldn't it be much simpler to just do:

<pre>
err:
ERR_print_errors_fp(stderr);
</pre>

Or, if one really does want to iterate through each line of the error queue individually, wouldn't it still be better for us to recommend using ERR_error_string_n with an explicit buffer? ERR_error_string with a NULL argument is not thread-safe.

--[[User:Ppelleti|Ppelleti]] 18:12, 3 March 2013 (UTC)

Either way does the trick, but I agree yours is simpler. I'll change it.,

--[[User:Matt|Matt]] 22:16, 3 March 2013 (UTC)

ERR_print_errors_fp is the best "call it and forget it" method for errors if it
is appropriate to use an fp. Calling the ERR routines directly can be done but
it's trickier and the example given is incomplete: I'd have to check it further
to see how best to call all the routines. [per Steve Henson]

--[[User:Stevem|Stevem]] 14:27, 4 March 2013 (UTC)

== OPENSSL_config deprecated ==

The sample code includes a call to <code>OPENSSL_config</code> which was deprecated in 1.1.0. I'm still familiarizing myself with the codebase and the documentation, and I therefore do not have a replacement suggestion yet, but if anyone is willing to impart their wisdom I'd be much obliged.

/* Load config file, and other important initialisation */
OPENSSL_config(NULL);

[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 23:28, 26 July 2019 (UTC)

The preferred approach to loading the default config file is:

OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL);

This must be the first OpenSSL call you make (typically at the beginning of your application).

--[[User:Matt|Matt]] ([[User talk:Matt|talk]]) 09:38, 28 July 2019 (UTC)

: Hey, thanks, Matt, that helped a lot; I was able to use that to grep right to the file where this is all defined. I'll post back here again once I'm confident I have some sample code that's both simple enough to be digestible as an introduction, but not so contrived it isn't useful.

: [[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 03:27, 29 July 2019 (UTC)

Mailing Lists

2019-07-29T03:03:08Z

Jflopezfernandez: Fixed mismatched brace causing link to display incorrectly

We have several community mailing lists, see the OpenSSL Community [https://www.openssl.org/community/mailinglists.html Mailing Lists].

Talk:Elliptic Curve Cryptography

2019-07-29T02:50:05Z

Jflopezfernandez: /* Source Code Highlighting */ new section

Elliptic Curve Cryptography

2019-07-29T02:17:56Z

Jflopezfernandez: Added some links in the introduction and formatted the key size table. The changes to the sample code will be documented in the talk page

The OpenSSL '''EC''' library provides support for [https://en.wikipedia.org/wiki/Elliptic-curve_cryptography '''Elliptic Curve Cryptography'''] ('''ECC'''). It is the basis for the OpenSSL implementation of the [https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm Elliptic Curve Digital Signature Algorithm] (ECDSA) and [https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman Elliptic Curve Diffie-Hellman] (ECDH).

Note: This page provides an overview of what ECC is, as well as a description of the low-level OpenSSL API for working with Elliptic Curves. If all you need is support for normal ECDSA and ECDH operations then you should normally use the high-level [[EVP|EVP API]]. Refer to [[EVP Signing and Verifying]] for how to perform digital signature operations (including using ECDSA), [[EVP Key Derivation]] for how to derive shared secrets using Diffie-Hellman and Elliptic Curve Diffie-Hellman, and [[EVP Key and Parameter Generation]] for details of how to create EC Keys.

== Why use Elliptic Curves? ==

The primary advantage of using Elliptic Curve based cryptography is reduced key size and hence speed. Elliptic curve based algorithms use significantly smaller key sizes than their non elliptic curve equivalents. The difference in equivalent key sizes increases dramatically as the key sizes increase. The approximate equivalence in security strength for symmetric algorithms compared to standard asymmetric algorithms and elliptic curve algorithms is shown in the table below.

<div name="div-table" style="margin: 24px;">

{| class="wikitable" style="margin: auto; width: 40%; text-align: center; padding: 8px;" align="center"
|-
! Symmetric Key Length !! Standard asymmetric Key Length !! Elliptic Curve Key Length
|-
| 80 || 1024 || 160
|-
| 112 || 2048 || 224
|-
| 128 || 3072 || 256
|-
| 192 || 7680 || 384
|-
| 256 || 15360 || 512
|}

</div>

As can be seen, to get equivalent strength to a 256 bit symmetric key, a standard asymmetric algorithm would have to use an enormous key of 15360 bits. Keys of this size are typically not practical due to the amount of processing power that would be required, and therefore the speed of the operations. However, with elliptic curve algorithms, the equivalent key length is 512 bits, which is entirely practical.

== What is an Elliptic Curve? ==

First of all some terminology. We need to define what is meant by a field. In essence a field is a '''set''' of elements with operations defined for the elements of that set that equate to something like addition, substraction, multiplication and division. The elements could be numbers, or they could be something else entirely. In order to be a field the following conditions also have to be met:
* Both addition and multiplicaiton are closed over the set, so for example if a and b are in the set then so are a + b and a * b
* Addition and multiplication must be associative: so a + (b + c) = (a + b) + c and similarly for multiplication
* Addition and multiplication must be commutative: so a + b = b + a and similarly for multiplication
* Both addition and multiplication must have identity elements. So, for example 0 and 1 where: a + 0 = a, and a * 1 = a
* There must be additive and multiplicative inverses for all elements in the set. So, for example, for every element a in the set there is also a -a so that a + (-a) = 0 (where 0 is the identity element for addition). Similarly for multiplication.
* Multiplication distributes over addition. So if a, b and c are in the set then a * (b + c) = (a * b) + (a * c)

A finite field is simply a field where the set has a finite number of elements. So, for example, the set of all integers could not be used as the basis for a finite field because there are an infinite number of them. However the set of integers from 0 to 100 could form the basis of a finite field.

So now we can define what an Elliptic Curve is. In general an Elliptic Curve is one of the form:
y² = x³ + ax + b, where x, y, a and b are elements of some Field

In Elliptic Curve Cryptography we further restrict this such that x, y, a and b are elements of a '''finite''' field.

Contrary to its name Elliptic Curves do not form an ellipse!

Ok, so far so good - but now it gets a bit more complicated! As well as the points on our curve we add an additional "special" point known as infinity. Using this set of points (i.e. all the points on the curve and infinity), we can define some operations on this set, which we call Point Addition and Point Multiplication.

Points on a curve are given in terms of their x and y co-ordinates, (x, y). Point Addition is essentially an operation which takes any two given points on a curve and yields a third point which is also on the curve. The maths behind this gets a bit complicated but think of it in these terms. Plot two points on an elliptic curve. Now draw a straight line which goes through both points. That line will intersect the curve at some third point. That third point is the result of the addition operation. Point Doubling is similar and can be thought of as adding a point to itself. Imagine a point on the curve and draw a straight line which is a tangent to the curve at that point. The result of the Point Doubling operation is where that tangent line intersects the curve at some other point.

Point multiplication is the operation of taking a point on the curve and "multiplying" it by some number. In practice this is achieved through repeated addition and doubling operations.

So with our set of points on a curve (plus the special point, infinity) we can start doing something useful. First of all we pick a point on the curve called the '''generator''' (we'll call it g).

Now:
* 0g = infinity
* 1g = g
* 2g = g + g
* 3g = g + g + g (or 2g + g)
* and so on.

Remember g, 2g and 3g are all points on the curve, and '''+''' in this context means point addition as defined above. If you keep going in this way you will eventually come to some number (lets call it '''n'''), such that ng = infinity. The set of points generated by repeatedly adding g to itself, along with the Point Addition operation together form a mathematical structure known as a '''group'''.

If you are lucky then you may have chosen a curve and a g, such that continually adding g to itself will eventually visit all of the possible points on the curve - but often this is not the case. The number '''n''' as defined above, is called the '''order''' of g. For various complicated mathematical reasons it also turns out that the total number of points that exist on the curve is divisble by n. Dividing the total number of points by n gives you another number known as the cofactor.

The security of Elliptic Curve Cryptography comes from the fact that given some point on the curve kg, (where k is a number and g is the known generator point), it is difficult to work out what the value of '''k''' is. This is known as the '''discrete logarithm problem'''. In the Elliptic Curve Cryptography algorithms ECDH and ECDSA, the point kg would be a public key, and the number k would be the private key.

== Types of Field ==

In principle there are many different types of field that could be used for the values x and y of a point (x, y). In practice however there are two primary ones used, and these are the two that are supported by the OpenSSL EC library.

The simplest is typically referred to as the prime field Fp where p is a prime number. In cryptographic applications p must be a very large prime number. The elements of the set are simply the numbers 0 through to p-1, and addition and multiplication over the field have the normal meaning for modular (or clock) arithmetic. So, if p=7 then the elements of the set are {0, 1, 2, 3, 4, 5, 6} and:

0 + 1 = 1

2 + 3 = 5

3 + 3 = 6

4 + 3 = 0

5 + 4 = 2

and so on.

The next common type of field is referred to as the binary field F2m. Elements of a binary field are typically represented as polynomials and not as numbers. So for example an element could be:

x4+x2+1

This can then be expressed as a binary number ({1 0 1 0 1} in this case), where each term represents one bit in the binary representation. Addition of such polynomials is done as normal but with the result of each term reduced modulo 2. So for example:

(x2 + 1) + (x2 + x) = 2x2 + x + 1

Each term is then reduced modulo 2 to give an answer 0x2 + x +1 = x + 1

In binary representation this sum could be expressed as follows:

{1 0 1} + {1 1 0} = {0 1 1}

Note then that addition is just a simple XOR operation.

Multiplication in the binary field is done respective to an '''irreducible polynomial'''. Multiplication of polynomials is done in the normal way and the result is then divided by the irreducible polynomial. The remainder is the result of the multiplication. See [http://en.wikipedia.org/wiki/Finite_field_arithmetic Finite Field Arithmetic], for a discussion of binary field arithmetic.

== Defining Curves ==

The parameters necessary for performing cryptographic operations for ECDH and ECDSA are simply the parameters required to set up the curve. Namely, the type of field e.g. prime (Fp) or binary (F2m), the value p for a prime field, the irreducible polynomial for a binary field, the values a and b from the curve equation, the generator point (g), the order, and the cofactor.

Fortunately, unless you are defining a new curve (not recommended unless you know what you are doing), or you are using an unusual curve that OpenSSL does not have support for, you can usually utilise one of the '''named''' curves that are built-in to OpenSSL. These are a set of well known and widely used curves. The complete collection of curve parameters can be set in one go simply by selecting the appropriate named curve using [[Manual:EC_GROUP_new(3)|EC_GROUP_new_by_curve_name]].

<pre>#include <openssl/obj_mac.h>
#include <openssl/ec.h>
...

EC_GROUP *curve;

if(NULL == (curve = EC_GROUP_new_by_curve_name(NID_secp224r1)))
handleErrors();</pre>

If a custom curve needs to be created, then it can be done as follows. This example code creates the same curve as the code above, but creates it "manually". In this example a prime field is being used, and the prime number is provided in the variable p. If a binary field was being created instead then a bit string representing the irreducible polynomial would have been provided in the p variable. For further information on the low level EC functions being used refer to the [[Manual:Ec(3)|EC]] manual pages:

<div>
EC_GROUP *create_curve(void)
{
BN_CTX *ctx;
EC_GROUP *curve;
BIGNUM *a, *b, *p, *order, *x, *y;
EC_POINT *generator;

/* Binary data for the curve parameters */
unsigned char a_bin[28] =
{0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
0xFF,0xFF,0xFF,0xFF,0xFF,0xFE,0xFF,0xFF,0xFF,0xFF,
0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFE};
unsigned char b_bin[28] =
{0xB4,0x05,0x0A,0x85,0x0C,0x04,0xB3,0xAB,0xF5,0x41,
0x32,0x56,0x50,0x44,0xB0,0xB7,0xD7,0xBF,0xD8,0xBA,
0x27,0x0B,0x39,0x43,0x23,0x55,0xFF,0xB4};
unsigned char p_bin[28] =
{0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01};
unsigned char order_bin[28] =
{0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
0xFF,0xFF,0xFF,0xFF,0x16,0xA2,0xE0,0xB8,0xF0,0x3E,
0x13,0xDD,0x29,0x45,0x5C,0x5C,0x2A,0x3D };
unsigned char x_bin[28] =
{0xB7,0x0E,0x0C,0xBD,0x6B,0xB4,0xBF,0x7F,0x32,0x13,
0x90,0xB9,0x4A,0x03,0xC1,0xD3,0x56,0xC2,0x11,0x22,
0x34,0x32,0x80,0xD6,0x11,0x5C,0x1D,0x21};
unsigned char y_bin[28] =
{0xbd,0x37,0x63,0x88,0xb5,0xf7,0x23,0xfb,0x4c,0x22,
0xdf,0xe6,0xcd,0x43,0x75,0xa0,0x5a,0x07,0x47,0x64,
0x44,0xd5,0x81,0x99,0x85,0x00,0x7e,0x34};

/* Set up the BN_CTX */
if(NULL == (ctx = BN_CTX_new())) handleErrors();

/* Set the values for the various parameters */
if(NULL == (a = BN_bin2bn(a_bin, 28, NULL))) handleErrors();
if(NULL == (b = BN_bin2bn(b_bin, 28, NULL))) handleErrors();
if(NULL == (p = BN_bin2bn(p_bin, 28, NULL))) handleErrors();
if(NULL == (order = BN_bin2bn(order_bin, 28, NULL))) handleErrors();
if(NULL == (x = BN_bin2bn(x_bin, 28, NULL))) handleErrors();
if(NULL == (y = BN_bin2bn(y_bin, 28, NULL))) handleErrors();

/* Create the curve */
if(NULL == (curve = EC_GROUP_new_curve_GFp(p, a, b, ctx))) handleErrors();

/* Create the generator */
if(NULL == (generator = EC_POINT_new(curve))) handleErrors();
if(1 != EC_POINT_set_affine_coordinates_GFp(curve, generator, x, y, ctx))
handleErrors();

/* Set the generator and the order */
if(1 != EC_GROUP_set_generator(curve, generator, order, NULL))
handleErrors();

EC_POINT_free(generator);
BN_free(y);
BN_free(x);
BN_free(order);
BN_free(p);
BN_free(b);
BN_free(a);
BN_CTX_free(ctx);

return curve;
}
</div>

==Working with Keys==

Keys for ECDH and ECDSA are represented using an [[Manual:EC_KEY_new(3)|EC_KEY]] structure in the low level [[Manual:Ec(3)|EC]] API. If you are using the preferred high-level [[EVP]] API then this EC_KEY structure will be wrapped in an [[EVP#EVP Working with EVP_PKEYs|EVP_PKEY]] object.

Creating a new EC_KEY is a process of creating a curve as described above, creating a new EC_KEY object, and then setting the key to use the curve using the [[Manual:EC_KEY_new(3)|EC_KEY_set_group]] function. Alternatively, the creation of the curve and the key can be done in one step as shown below using [[Manual:EC_KEY_new(3)|EC_KEY_new_by_curve_name]]:

<pre>#include <openssl/obj_mac.h>
#include <openssl/ec.h>
...

EC_KEY *key;

if(NULL == (key = EC_KEY_new_by_curve_name(NID_secp224r1)))
handleErrors();</pre>

At this point the EC_KEY object has been set up and associated with the curve - but it is empty. There is no key data in it. In order to generate new keys for use with the EVP interface see [[EVP Key and Parameter Generation]]. To generate them using the low level API this can be done as follows:

<pre>
if(1 != EC_KEY_generate_key(key)) handleErrors();
</pre>

Note that this operation generates a public and private key '''pair'''. Alternatively you may already know either the private key, the public key, or both. Setting the private key and/or public key is done as follows:

<pre>BIGNUM *prv;
EC_POINT *pub;

/* Set up private key in prv */
/* Set up public key in pub */

if(1 != EC_KEY_set_private_key(key, prv)) handleErrors();
if(1 != EC_KEY_set_public_key(key, pub)) handleErrors();</pre>

If you set the private key then you '''must''' also set the public key. There have been occasional questions on the openssl-users email list from people who only have the private key but do not know the public key. Fortunately calculating the public key is simply a matter of multiplying the private key by the generator for the curve using [[Manual:EC_POINT_add(3)|EC_POINT_mul]]:

<pre>if (1 != EC_POINT_mul(curve, pub, prv, NULL, NULL, ctx))
handleErrors();</pre>

Finally, it is possible to convert a low-level EC_KEY object into an EVP_PKEY object using the EVP_PKEY_set1_EC_KEY function described in the manual here: [[Manual:EVP_PKEY_set1_RSA(3)]]

==Named Curves==

If you want to save a key and later load it with <tt>SSL_CTX_use_PrivateKey_file</tt>, then you '''must''' set the <tt>OPENSSL_EC_NAMED_CURVE</tt> flag on the key. You do that by calling <tt>EC_KEY_set_asn1_flag(ecKey, OPENSSL_EC_NAMED_CURVE)</tt>. Failure to do so will result in a SSL error of 0x1408a0c1 (no shared cipher) at the server.

As an example, the following creates a elliptic curve key and saves it using a named curve rather than an expanded list of group paramters:

<pre>EC_KEY *key = NULL;

key = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);
EC_KEY_set_asn1_flag(key, OPENSSL_EC_NAMED_CURVE);</pre>

If you want to detect the flags after reading a key or certificate from disk, then use the following code:

<pre>int EC_KEY_get_asn1_flag(const EC_KEY* key)
{
if (key)
{
const EC_GROUP* group = EC_KEY_get0_group(key);
if (group)
return EC_GROUP_get_asn1_flag(group);

return 0;
}
}
...

int flags = EC_KEY_get_asn1_flag(ecKey);
ASSERT(flags & OPENSSL_EC_NAMED_CURVE);</pre>

The certificates below were dumped with <tt>openssl x509 -in server-ecdsa-cert.pem -text -noout</tt>. The certificate on the left was created with a key using <tt>OPENSSL_EC_NAMED_CURVE</tt>, while the certificate on the right was not. Notice the certificate on the left includes '''ASN1 OID: prime256v1'''. The certificate on the left can be used with SSL server using ECDSA, but the certificate on the right cannot because it will result in 0x1408a0c1 at the server.

{| align="center"
| [[File:cert-with-flag.png|thumb|350px|Figure 1: Key with OPENSSL_EC_NAMED_CURVE]]
| [[File:cert-without-flag.png|thumb|350px|Figure 2: Key without OPENSSL_EC_NAMED_CURVE]]
|}

If you use a key or certificate without without the <tt>OPENSSL_EC_NAMED_CURVE</tt> flag (i.e., one that looks like the image on the right), then the SSL connection will fail with the following symptoms:

<pre>Client (s_client):

139925962778272:error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure:s3_pkt.c:1256:SSL alert number 40
139925962778272:error:1409E0E5:SSL routines:SSL3_WRITE_BYTES:ssl handshake failure:s3_pkt.c:596:</pre>

<pre>Server (s_server):

140339533272744:error:1408A0C1:SSL routines:SSL3_GET_CLIENT_HELLO:no shared cipher:s3_srvr.c:1353:</pre>

Note that OpenSSL's <tt>X509_verify</tt>, <tt>X509_verify_cert</tt>, <tt>SSL_CTX_check_private_key</tt>, <tt>SSL_CTX_use_PrivateKey_file</tt>, and <tt>SSL_CTX_use_certificate_chain_file</tt> will not return a failure when using a key or certificate in the wrong format.

==See also==
* [[Elliptic Curve Diffie Hellman]]
* [[Command Line Elliptic Curve Operations]]
* [[Manual:ec(3)]]

[[Category:C level]]
[[Category:Cryptographic Algorithm]]
[[Category:Examples]]

Random Numbers

2019-07-27T02:33:12Z

Jflopezfernandez: Corrected the second hyperlink I added

[[Random Numbers]] are a cryptographic primitive and cornerstone to nearly all cryptographic systems. They are used in almost all areas of cryptography, from key agreement and transport to session keys for bulk encryption. A quality source of random bits and proper use of OpenSSL APIs will help ensure your program is cryptographically sound. On the other hand, a poor source of randomness or incorrect library usage could result in loss of security. This article will help you use random number generation routines correctly when programming with the OpenSSL library.

OpenSSL provides a number of software based random number generators based on a variety of sources. A software based random number generator creates random numbers by executing a software algorithm. There are a number of algorithms specified by a number of standard bodies including NIST, ANSI X9 committee (X9.17 and X9.31) and XXX. In addition, the library can use custom hardware if the hardware has an <tt>ENIGNE</tt> interface.

Good random numbers are notoriously hard to produce from deterministic processes such as a computer executing instructions. A number of cryptographic attacks have been developed because they are so hard to acquire[https://wiki.openssl.org/index.php?title=Random_Numbers#References]. Especially vulnerable are headless servers, embedded devices, and mobile devices, and you may have to take extra steps to ensure an adequate supply of entropy is available[https://wiki.openssl.org/index.php?title=Random_Numbers#References]. The extra steps could include ''Hedging'' on a headless server or embedded device, and ''Finger Painting'' on a mobile device. For recent attacks on low entropy devices (such as headless servers and mobile devices), see for example, ''[http://pages.cs.wisc.edu/~rist/papers/sslhedge.html When Good Randomness Goes Bad: Virtual Machine Reset Vulnerabilities and Hedging Deployed Cryptography ]'', ''[https://factorable.net/paper.html Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices]'', and ''[http://www.csoonline.com/article/723229/traffic-sensor-flaw-that-could-allow-driver-tracking-fixed Traffic sensor flaw that could allow driver tracking fixed]''.

== Entropy ==

Entropy is the measure of "randomness" in a sequence of bits. Different sources have different entropy. For example, a physical process in nature may have 100% entropy which appears purely random. On the other hand, the written English language provides about 3 bits/byte (or character) which is at most 38%. Some estimates have shown English characters provide only 1 bit/byte (or 12%). Other sources used as a random stream will have different estimates of entropy, and you will have to determine the quality.

Random number generators require quality entropy for input (a ''seed'', discussed below) and must produce quality output (''quod vide''). When using OpenSSL's APIs, you will be asked to estimate entropy when seeding or reseeding (input). When estimating entropy you should error on the low side to ensure proper fitness of the generator. When receiving bytes, you will receive a code indicating the success/failure of the operation and quality of the bytes (output).

=== Sources ===

Sometimes the operating system offers block access to hardware random number generators via <tt>/dev/hwrng</tt>. <tt>/dev/hwrng</tt> can be a low volume device, and could potentially block. For example, the [http://www.portwell.com.tw/download/sbc/catalog/Intel_80802_FWH.pdf Intel 82802 Firmware Hub] used with the and i840 chipset produces one byte of data in its register. At other times, <tt>/dev/hwrng</tt> can be a high volume device, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology]. In virtualized environments, <tt>/dev/hwrng</tt> might actually be a [http://wiki.qemu.org/Features-Done/VirtIORNG VirtIO RNG].

Entropy is important for a healthy program, and you should investigate hardware modules to help acquire it, especially if poor entropy or entropy depletion are a concern. There are a number of inexpensive and high quality hardware modules on the market, including a $40UK [http://www.entropykey.co.uk EntropyKey]. There are also a number of high quality and high priced hardware modules and accelerators.

If you lack <tt>/dev/random</tt> and cannot procure a hardware random number generator, you can also consider an alternate entropy gather such as the [http://egd.sourceforge.net Entropy Gathering Daemon (EGD)]. EGD is an userspace substitute for <tt>/dev/random</tt>. OpenSSL provides native support for EGD via <tt>[[Manual:RAND_egd(3)|RAND_egd]]</tt> to connect to the Unix domain socket, and <tt>[[Manual:RAND_egd(3)|RAND_egd_bytes]]</tt> to extract bytes from the daemon.

=== Testing ===

It is not possible to assess whether a source of randomness is truly random by merely examining its bits. An "ideal" source of truly random data can be thought of as a sequence of binary digits where each 1 or 0 is the result of flipping a perfectly fair, unbiased coin. Such a sequence of digits would have the following properties:

* Each digit would have exactly 0.5 probability of being 1 and 0.5 probability of being 0
* The production of any one digit would be entirely independent of any other digits

Given any arbitrary sequence of binary digits it is possible to examine it using statistical techniques. There are various suites of statistical tests available such as STS (Statistical Test Suite) available from NIST's ''[http://csrc.nist.gov/groups/ST/toolkit/rng/index.html RANDOM NUMBER GENERATION]'' page. This suite provides a number of different tests including:

* The Frequency (Monobit) Test: Checks whether the proportion of 0s and 1s in a given sequence are approximately as one would expect
* The Runs Test: Tests whether the number of runs of consecutive identical digits of varying lengths within a given sequence is as expected
* The Longest Run of Ones in a block: Confirms whether the longest single run of ones within a sequence is as would be expected

Examining random data using the tests above cannot determine whether a data source is truly random or not. However, it '''can''' indicate whether data is '''likely''' to be non-random.

== Generators ==

By default, OpenSSL uses the <tt>md_rand</tt> generator. <tt>md_rand</tt> uses the MD5 hash as the pseudorandom function. The source code is located in <tt>crypto/rand/md_rand.c</tt>.

You can test for the generator with:

<pre>RAND_METHOD* rm = RAND_get_rand_method();
if(rm == RAND_SSLeay())
{
printf("Using default generator\n");
}</pre>

You can change the random method using the following.

<pre>RAND_METHOD* rm = ...;
if(rm != NULL)
{
rc = RAND_set_rand_method(rm);
ASSERT(rc == 1);
}</pre>

== Seeds ==

Most random number generators require a seed. A seed is a secret, unpredictable sequence of bytes that is transformed and then used to set the initial state of the generator. The seed ensures that each unique instance of a generator produces a unique stream of bits. No two generators should ever produce the same sequence of random numbers, even when faced with Virtual Machine (VM) rollback attacks (which could happen accidentally by a data center operator).

You should always seed a generator unless the docs state they don't require a seed. Even if the docs state a seed is not needed, you should seed it anyway. When seeding your generators, you should use at least 256 bits (32 bytes) of material. You can verify the required number of bits by grepping the source files for <tt>#define ENTROPY_NEEDED</tt>.

=== Initialization ===

OpenSSL will attempt to seed the random number generator automatically upon instantiation by calling <tt>RAND_poll</tt>. If the generator is not initialized and <tt>RAND_bytes</tt> is called, then the generator will also call <tt>RAND_poll</tt> (from <tt>ssleay_rand_bytes</tt> in <tt>crypto/rand/md_rand.c</tt>):

<pre>if (!initialized)
{
RAND_poll();
initialized = 1;
}</pre>

<tt>RAND_poll</tt> seeds the random number generator using a system-specific entropy source, which is <tt>/dev/urandom</tt> on UNIX-like operating systems, and is a combination of [http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx <tt>CryptGenRandom</tt>] and other sources of entropy on Windows.

Be careful when deferring to <tt>RAND_poll</tt> on some Unix systems because it does not seed the generator. See the code guarded with <tt>OPENSSL_SYS_VXWORKS</tt> in <tt>rand_unix.c</tt>. Additionally, <tt>RAND_poll</tt> can have negative interactions on newer Windows platforms, so your program could hang or crash depending on the potential issue. See [[#Windows_Issues|Windows Issues]] below.

The <tt>urandom</tt> device may lack sufficient entropy for your needs, and you might want to reseed it immediately from <tt>/dev/random</tt>. On Unix and other operating systems that provide the block device, you can use <tt>[[Manual:RAND_load_file(3)|RAND_load_file]]</tt> to load directly from <tt>/dev/random</tt>.

<pre>int rc = RAND_load_file("/dev/random", 32);
if(rc != 32) {
/* RAND_load_file failed */
}

/* OK to proceed */</pre>

=== Reseed ===

The OpenSSL API allows you to provide a seed and refresh the generator's state with reseeds at anytime during the program's execution. Two functions are provided for seeding and reseeding: <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> and <tt>[[Manual:RAND_add(3)|RAND_add]]</tt>. <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> accepts a buffer and size; while <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> accepts a buffer, size, and entropy estimate in bytes. <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> will call <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> assuming 100% entropy.

<tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> is shown below. The function is <tt>void</tt>, so it <nowiki>[apparently]</nowiki> cannot fail (or convey failures). Though the example uses the actual number of bytes written to the buffer, the entire buffer can be used to increase entropy with hopes the unused bytes in the buffer has entropy to extract. Even though you can use uninitialized bytes as input, you should not expect any entropy in the uninitialized bytes. Finally, the function <tt>get_random_bytes</tt> is a placeholder for an application supplied function which gathers random data.

<pre>byte buffer[32];
int written = get_random_bytes(buffer, sizeof(buffer));

RAND_seed(buffer, written);
/* OK to proceed */</pre>

<tt>[[Manual:RAND_add(3)|RAND_add]]</tt> is similar to <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> but requires an entropy estimate. The estimate should be the number of full bytes of entropy in the buffer. If you have a 32 byte buffer with about 50% entropy, you should provide 16 as the entropy estimate. <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> is also a <tt>void</tt> function, so it cannot fail (or convey failures). The example also uses the actual number of bytes written to the buffer, but the entire buffer can be used to increase entropy. Note that <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> takes a <tt>double</tt>, so be sure to '''avoid''' integer math. Otherwise, the entropy estimate calculation could result in 0.

<pre>char phrase[64];
int written = get_random_phrase(phrase, sizeof(phrase));

RAND_add(phrase, written, 0.12f * written /* 12% */);
/* OK to proceed */</pre>

On Windows machines, you can also use <tt>[[Manual:RAND_add(3)|RAND_screen]]</tt> and <tt>[[Manual:RAND_add(3)|RAND_event]]</tt>. <tt>[[Manual:RAND_add(3)|RAND_screen]]</tt> will mix the contents of the screen into the generator. <tt>[[Manual:RAND_add(3)|RAND_event]]</tt> can be used with programs that process [http://msdn.microsoft.com/en-us/library/windows/desktop/ff381405(v=vs.85).aspx Windows Messages]. Both methods should only be used with interactive programs, and not services nor drivers.

<tt>RAND_poll</tt> can be used to reseed the generator using the system entropy source.

=== Persisting ===

If you are worried about slow starts - or the time it takes to get the random number generator in good working order - you can write out a future seed and use it at next program execution. To save the future seed, use the library's <tt>RAND_write_file</tt> function. When using <tt>RAND_write_file</tt>, you only need to specify a filename. <tt>RAND_write_file</tt> returns the number of bytes written or -1 to indicate bytes were written without an appropriate seed (failure).

<pre>int written = RAND_write_file("prng.seed");
if(written <= 0)
/* RAND_write_file failed */

/* OK to proceed */</pre>

At program startup, you can attempt to read the saved seed with <tt>RAND_load_file</tt>. You can specify the number of bytes to read, or -1 to indicate the entire file should be used. The bytes read are automatically added to the generator. <tt>[[Manual:RAND_load_file(3)|RAND_load_file]]</tt> returns the number of bytes read.

<pre>int read = RAND_load_file("prng.seed", -1);
if(read <= 0)
/* RAND_load_file failed */

/* OK to proceed */</pre>

If possible, you should use protected storage offered by the operating system. For example, you should avoid writing the file and store the seed in the [http://developer.apple.com/library/ios/#documentation/security/Conceptual/keychainServConcepts/iPhoneTasks/iPhoneTasks.html iOS Keychain], [http://developer.android.com/reference/android/security/KeyChain.html Android KeyChain], or [http://msdn.microsoft.com/en-us/library/ms995355.aspx Windows DPAPI]. When writing the seed to the filesystem, be sure to protect the the seed through the file system's permission scheme (Linux has not realized userland needs help from the kernel when storing secrets).

<tt>RAND_load_file</tt> and <tt>RAND_write_file</tt> are documented at the [http://www.openssl.org/docs/manmaster/crypto/RAND_load_file.html <tt>RAND_load_file</tt> man page].

== Generation ==

After the generator has been seeded and is in good working order, you can extract bytes. You have three functions to extract bytes. First is <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> and the second is <tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt>. Both are software based and produce a pseudo-random stream. The third method is hardware based and it reuses <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt>.

If the random number generator is not properly seeded, then it will refuse to deliver random bytes and a "PRNG not seeded error" will occur.

=== Software ===

<tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> will fetch cryptographically strong random bytes. Cryptographically strong bytes are suitable for high integrity needs, such as long term key generation. If your generator is using a software algorithm, then the bytes will be pseudo-random (but still cryptographically strong). <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> returns 1 for success, and 0 otherwise. If you changed the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>[[Manual:ERR_get_error(3)|ERR_get_error]]</tt>.

<pre>byte buffer[128];

int rc = RAND_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 1) {
/* RAND_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

<tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt> returns pseudo-random bytes which ''can'' be cryptographically strong. The function returns 1 if the bytes are cryptographically strong, and 0 otherwise. If your application has high integrity requirements, it should ''not'' use <tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt>.

When using <tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt>, both 0 and 1 indicate success. If you change the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>[[Manual:ERR_get_error(3)|ERR_get_error]]</tt>.

<pre>byte buffer[32];

int rc = RAND_pseudo_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 0 && rc != 1) {
/* RAND_pseudo_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

=== Hardware ===

Hardware random number generators are almost always better to use than a software based generator. Hardware generators are often called True Random Number generators (TRNG) or Non-Deterministic Random Number Generators since they don't rely on the deterministic behavior of executing software instructions. Their bits streams are nearly always indistinguishable from random streams, and their entropy is always nearly 100%.

Some hardware generators are easier to use than other. For example, an [http://www.entropykey.co.uk EntropyKey] will provide a driver that replenishes <tt>/dev/random</tt>, so an application does not have to do anything special other than reading from the device. Other generators, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key], must be integrated into an application. When integrating generators using OpenSSL, you will use the library's <tt>ENGINE</tt> API.

To integrate a hardware based random number generator, you should load the apporpriate <tt>ENGINE</tt> for the hardware based implementation. Once loaded, set the engine's <tt>RAND_method</tt> method as default with <tt>ENGINE_METHOD_RAND</tt>. After you load the engine and set <tt>RAND_method</tt> for the hardware generator, you simply use <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> as discussed earlier. There are no special steps necessary after the configuration.

If you have OpenSSL 1.0.1 and a machine with [http://semiaccurate.com/2012/04/23/intel-launches-ivy-bridge-amid-crushing-marketing-buzzwords/ 3rd generation Core i5 or i7 processor (Ivy Bridge)], then the Intel [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology] (formerly called Bull Mountain) [[Commercial Product Disclaimer|<nowiki>[disclaimer]</nowiki>]] is available to you. The hardware generator is accessed through the <tt>ENGINE</tt> API and wraps the <tt>rdrand</tt> instruction. Also see [http://software.intel.com/en-us/blogs/2014/10/03/changes-to-rdrand-integration-in-openssl Changes to RDRAND integration in OpenSSL] on the Intel blog.

To ensure <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> uses the hardware engine, you must perform three steps:

* load the <tt>rdrand</tt> engine
* acquire a handle to the engine
* set the default <tt>RAND_method</tt> to the engine

The code below shows you how to load the Intel random number generator engine and set the default <tt>RAND_method</tt>. The code is available for download at [[Media:test-rdrand.c|test-rdrand.c]]. While you can call <tt>[[Manual:engine(3)|ENGINE_load_builtin_engines]]</tt> to make all engines available, the code below focuses on the one engine of interest and loads it via <tt>ENGINE_load_rdrand</tt>. Before the call to <tt>ENGINE_load_rdrand</tt>, be sure to call <tt>OPENSSL_cpuid_setup</tt> to load the proper CPU capabilities. See [[Manual:Engine(3)|OpenSSL's engine(3)]] for more details on engines, their loading, and operation.

Displaying the error code in hexadecimal gives you an error that is easily consumed by <tt>openssl errstr</tt>.

<pre> 1 unsigned long err = 0;
2 int rc = 0;
3
4 OPENSSL_cpuid_setup();
5 ENGINE_load_rdrand();
6
7 ENGINE* eng = ENGINE_by_id("rdrand");
8 err = ERR_get_error();
9
10 if(NULL == eng) {
11 fprintf(stderr, "ENGINE_load_rdrand failed, err = 0x%lx\n", err);
12 abort(); /* failed */
13 }
14
15 rc = ENGINE_init(eng);
16 err = ERR_get_error();
17
18 if(0 == rc) {
19 fprintf(stderr, "ENGINE_init failed, err = 0x%lx\n", err);
20 abort(); /* failed */
21 }
22
23 rc = ENGINE_set_default(eng, ENGINE_METHOD_RAND);
24 err = ERR_get_error();
25
26 if(0 == rc) {
27 fprintf(stderr, "ENGINE_set_default failed, err = 0x%lx\n", err);
28 abort(); /* failed */
29 }
30
31 /* OK to proceed */
32
33 ...
34 ENGINE_finish(eng);
35 ENGINE_free(eng);
36 ENGINE_cleanup();</pre>

If you hardware does not support the Intel generator, you will receive a <tt>NULL</tt> pointer at line 7 and encounter error 0x2606c043 at line 8. The error can then be fed to <tt>openssl errstr</tt>:

<pre>$ ./test-rdrand.exe
...
ENGINE_load_rdrand failed, err = 0x2606c043
$ openssl errstr 0x2606c043
error:2606C043:engine routines:ENGINE_FREE_UTIL:passed a null parameter</pre>

[[File:test-rdrand.png|thumb|250px|right|Verifying rdrand code path]] Line 13 attempts to set the default <tt>RAND_method</tt> to that provided by the engine using <tt>[[Manual:engine(3)|ENGINE_set_default]]</tt> with <tt>ENGINE_METHOD_RAND</tt>. Upon success, OpenSSL will internally use <tt>OPENSSL_ia32_rdrand</tt> for random number generation. To verify code correctness, simply set a breakpoint on the function and wait for the debugger to snap as shown in the figure to the right.

The 0x2606c043 error is actually caused by <tt>ENGINE_load_rdrand</tt>. The function will verify the capabilities of the hardware and load the generator's engine if available. <tt>ENGINE_load_rdrand</tt> is a <tt>void</tt> function, so it cannot fail or cannot convey failures (which we know is incorrect from a test run). The source code can be found in <tt>eng_rdrand.c</tt> and is shown below.

<pre>void ENGINE_load_rdrand (void)
{
extern unsigned int OPENSSL_ia32cap_P[];

if (OPENSSL_ia32cap_P[1] & (1<<(62-32)))
{
ENGINE *toadd = ENGINE_rdrand();
if(!toadd) return;
ENGINE_add(toadd);
ENGINE_free(toadd);
ERR_clear_error();
}
}</pre>

A patch is available to provide <tt>ENGINE_R_NO_SUCH_ENGINE</tt> error code for non-RdRand CPUs. See ''[https://rt.openssl.org/Ticket/Display.html?id=3143 <nowiki>[openssl.org #3143]: ENGINE_load_rdrand sane failure code</nowiki>]'' for details.

<pre>$ ./test-rdrand.exe
...
ENGINE_load_rdrand failed, err = 0x26077074
$ openssl errstr 0x26077074
error:26077074:engine routines:ENGINE_init:no such engine</pre>

According to [http://software.intel.com/en-us/articles/performance-impact-of-intel-secure-key-on-openssl Intel documentation], the random number generator does not need to be seeded via the <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> function because the generator is self-seeding. For optimal performance, code that is aware of the underlying random engine can forgo gathering entropy.

Additionally (or more importantly), the following will not cause a crash when using the hardware random number generator (and it fails silently so all looks good from outside the fishbowl):

<pre>/* Bad - don't do this in production */
byte seed[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
RAND_seed(seed, sizeof(seed));</pre>

Finally, you can test if your Mac OS X system has <tt>rdrand</tt> available with the following (thanks to Dave Zarzycki):

<pre>$ sysctl hw.optional.rdrand
hw.optional.rdrand: 1</pre>

On Linux, you can <tt>cat</tt> <tt>cpuinfo</tt>:
<pre>$ cat /proc/cpuinfo | grep -i rdrand
rdrand : 1</pre>

== Windows Issues ==

Windows platforms offer two potential problems to OpenSSL's <tt>RAND_poll</tt>. First is a hang due to the heap walk, and second is Application Verifier failures due to use of Windows' API call <tt>netstatget</tt>.

See [http://rt.openssl.org/Ticket/Display.html?id=2100&user=guest&pass=guest Bug 2100] for details on the heap walk issue. See [https://groups.google.com/forum/#!topic/mailing.openssl.users/uEO5roA55Wg UAC related errors on windows 7 64-bit with Application Verifier] for details and a workaround for the Application Verifier issue.

== Miscellaneous ==

Two miscellaneous items remaining are generator cleanup and status. <tt>[[Manual:RAND_cleanup(3)|RAND_cleanup]]</tt> securely erases the memory used by the random number generator.

You can query the generator's state with <tt>[[Manual:RAND_add(3)|RAND_status]]</tt>. <tt>[[Manual:RAND_add(3)|RAND_status]]</tt> returns 1 if the generator is in good working order. If your generator is not in good working order, you should reseed it with at least 256 bits (32 bytes) of entropy. The function [http://www.mail-archive.com/openssl-dev@openssl.org/msg04212.html purposefully hides the number of bytes needed] for the reseed operation.

On Android, take care to specify <tt>-mfloat-abi=softfp</tt> when building the library for use via JNI. If you specify <tt>-mfloat-abi=hard</tt> or <tt>-mhard-float</tt> (even if the hardware support a floating point unit), then the entropy estimate passed to <tt>RAND_add</tt> will always be 0.0f. See [https://groups.google.com/d/msg/android-ndk/NbUq9FDDZOo/TJJsAS6nM7wJ Hard-float and JNI] for details.

By default, OpenSSL will use the <tt>RDRANG</tt> engine to generate random numbers if the hardware is available. The behavior has been changed, but the change is only available through git at the moment. If you are concerned with <tt>RDRANG</tt> tampering, then see the discussion of [[Library_Initialization#ENGINEs_and_RDRAND | ENGINEs and RDRAND]].

== FIPS Mode ==

FIPS mode is a special mode of operation which specifies the library should operate according to the security policies and procedures specified in [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2]. The mode requires use of the FIPS Capable OpenSSL library, and must be enabled with a call to <tt>FIPS_mode_set</tt>. Once in FIPS mode, a ''default DRBG'' is used as specified in [http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf SP800-90].

The default DRBG is 256-bit CTR AES using a derivation function, and is decided by the application and not the library module. In the case of an OpenSSL application it is specified in <tt>rand_lib.c</tt> via the <tt>OPENSSL_DRBG_DEFAULT_TYPE</tt> and <tt>OPENSSL_DRBG_DEFAULT_FLAGS</tt> preprocessor macros to allow them to be overridden by local compilation options or at runtime.

To use the FIPS random number generator, simply use <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> as described earlier. Note that the call to <tt>FIPS_mode_set</tt> must succeed in order to operate in FIPS 140 mode.

== Thread Safety ==

The random number generators (among other parts of OpenSSL) are not thread safe by default. To ensure thread safety, you must call <tt>[[Manual:Threads(3)|CRYPTO_set_locking_callback]]</tt>.

== Fork Safety ==

OpenSSL's random number generator is not [[Random_fork-safety|fork-safe]], so the issue should be carefully understood and remediated if necessary. See [[Random_fork-safety|Random Fork-Safety]] for details.

[[Category:Expert Review]]

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [http://jbp.io/2014/01/16/openssl-rand-api/ Analysis of the OpenSSL random API]

==References==
# Lenstra, A. K., Hughes, J. P., Augier, M., Bos, J. W., Kleinjung, T., & Wachter, C. (2012, February 14). Ron was wrong, Whit is right. p.17. Retrieved from the Cryptology ePrint Archive: [https://eprint.iacr.org/2012/064 Report 2012/064].
# Heninger, N. (2012, February 15). New research: There’s no need to panic over factorable keys-just mind your Ps and Qs. Retrieved from [https://freedom-to-tinker.com/2012/02/15/new-research-theres-no-need-panic-over-factorable-keys-just-mind-your-ps-and-qs/ link].

[[Category:Cryptography]]
[[Category:Crypto API]]

Random Numbers

2019-07-27T02:31:56Z

Jflopezfernandez: Added two sources to the introduction for further reading

[[Random Numbers]] are a cryptographic primitive and cornerstone to nearly all cryptographic systems. They are used in almost all areas of cryptography, from key agreement and transport to session keys for bulk encryption. A quality source of random bits and proper use of OpenSSL APIs will help ensure your program is cryptographically sound. On the other hand, a poor source of randomness or incorrect library usage could result in loss of security. This article will help you use random number generation routines correctly when programming with the OpenSSL library.

OpenSSL provides a number of software based random number generators based on a variety of sources. A software based random number generator creates random numbers by executing a software algorithm. There are a number of algorithms specified by a number of standard bodies including NIST, ANSI X9 committee (X9.17 and X9.31) and XXX. In addition, the library can use custom hardware if the hardware has an <tt>ENIGNE</tt> interface.

Good random numbers are notoriously hard to produce from deterministic processes such as a computer executing instructions. A number of cryptographic attacks have been developed because they are so hard to acquire[https://wiki.openssl.org/index.php?title=Random_Numbers#References]. Especially vulnerable are headless servers, embedded devices, and mobile devices, and you may have to take extra steps to ensure an adequate supply of entropy is available[https://wiki.openssl.org/index.php?title=?Random_Numbers#References]. The extra steps could include ''Hedging'' on a headless server or embedded device, and ''Finger Painting'' on a mobile device. For recent attacks on low entropy devices (such as headless servers and mobile devices), see for example, ''[http://pages.cs.wisc.edu/~rist/papers/sslhedge.html When Good Randomness Goes Bad: Virtual Machine Reset Vulnerabilities and Hedging Deployed Cryptography ]'', ''[https://factorable.net/paper.html Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices]'', and ''[http://www.csoonline.com/article/723229/traffic-sensor-flaw-that-could-allow-driver-tracking-fixed Traffic sensor flaw that could allow driver tracking fixed]''.

== Entropy ==

Entropy is the measure of "randomness" in a sequence of bits. Different sources have different entropy. For example, a physical process in nature may have 100% entropy which appears purely random. On the other hand, the written English language provides about 3 bits/byte (or character) which is at most 38%. Some estimates have shown English characters provide only 1 bit/byte (or 12%). Other sources used as a random stream will have different estimates of entropy, and you will have to determine the quality.

Random number generators require quality entropy for input (a ''seed'', discussed below) and must produce quality output (''quod vide''). When using OpenSSL's APIs, you will be asked to estimate entropy when seeding or reseeding (input). When estimating entropy you should error on the low side to ensure proper fitness of the generator. When receiving bytes, you will receive a code indicating the success/failure of the operation and quality of the bytes (output).

=== Sources ===

Sometimes the operating system offers block access to hardware random number generators via <tt>/dev/hwrng</tt>. <tt>/dev/hwrng</tt> can be a low volume device, and could potentially block. For example, the [http://www.portwell.com.tw/download/sbc/catalog/Intel_80802_FWH.pdf Intel 82802 Firmware Hub] used with the and i840 chipset produces one byte of data in its register. At other times, <tt>/dev/hwrng</tt> can be a high volume device, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology]. In virtualized environments, <tt>/dev/hwrng</tt> might actually be a [http://wiki.qemu.org/Features-Done/VirtIORNG VirtIO RNG].

Entropy is important for a healthy program, and you should investigate hardware modules to help acquire it, especially if poor entropy or entropy depletion are a concern. There are a number of inexpensive and high quality hardware modules on the market, including a $40UK [http://www.entropykey.co.uk EntropyKey]. There are also a number of high quality and high priced hardware modules and accelerators.

If you lack <tt>/dev/random</tt> and cannot procure a hardware random number generator, you can also consider an alternate entropy gather such as the [http://egd.sourceforge.net Entropy Gathering Daemon (EGD)]. EGD is an userspace substitute for <tt>/dev/random</tt>. OpenSSL provides native support for EGD via <tt>[[Manual:RAND_egd(3)|RAND_egd]]</tt> to connect to the Unix domain socket, and <tt>[[Manual:RAND_egd(3)|RAND_egd_bytes]]</tt> to extract bytes from the daemon.

=== Testing ===

It is not possible to assess whether a source of randomness is truly random by merely examining its bits. An "ideal" source of truly random data can be thought of as a sequence of binary digits where each 1 or 0 is the result of flipping a perfectly fair, unbiased coin. Such a sequence of digits would have the following properties:

* Each digit would have exactly 0.5 probability of being 1 and 0.5 probability of being 0
* The production of any one digit would be entirely independent of any other digits

Given any arbitrary sequence of binary digits it is possible to examine it using statistical techniques. There are various suites of statistical tests available such as STS (Statistical Test Suite) available from NIST's ''[http://csrc.nist.gov/groups/ST/toolkit/rng/index.html RANDOM NUMBER GENERATION]'' page. This suite provides a number of different tests including:

* The Frequency (Monobit) Test: Checks whether the proportion of 0s and 1s in a given sequence are approximately as one would expect
* The Runs Test: Tests whether the number of runs of consecutive identical digits of varying lengths within a given sequence is as expected
* The Longest Run of Ones in a block: Confirms whether the longest single run of ones within a sequence is as would be expected

Examining random data using the tests above cannot determine whether a data source is truly random or not. However, it '''can''' indicate whether data is '''likely''' to be non-random.

== Generators ==

By default, OpenSSL uses the <tt>md_rand</tt> generator. <tt>md_rand</tt> uses the MD5 hash as the pseudorandom function. The source code is located in <tt>crypto/rand/md_rand.c</tt>.

You can test for the generator with:

<pre>RAND_METHOD* rm = RAND_get_rand_method();
if(rm == RAND_SSLeay())
{
printf("Using default generator\n");
}</pre>

You can change the random method using the following.

<pre>RAND_METHOD* rm = ...;
if(rm != NULL)
{
rc = RAND_set_rand_method(rm);
ASSERT(rc == 1);
}</pre>

== Seeds ==

Most random number generators require a seed. A seed is a secret, unpredictable sequence of bytes that is transformed and then used to set the initial state of the generator. The seed ensures that each unique instance of a generator produces a unique stream of bits. No two generators should ever produce the same sequence of random numbers, even when faced with Virtual Machine (VM) rollback attacks (which could happen accidentally by a data center operator).

You should always seed a generator unless the docs state they don't require a seed. Even if the docs state a seed is not needed, you should seed it anyway. When seeding your generators, you should use at least 256 bits (32 bytes) of material. You can verify the required number of bits by grepping the source files for <tt>#define ENTROPY_NEEDED</tt>.

=== Initialization ===

OpenSSL will attempt to seed the random number generator automatically upon instantiation by calling <tt>RAND_poll</tt>. If the generator is not initialized and <tt>RAND_bytes</tt> is called, then the generator will also call <tt>RAND_poll</tt> (from <tt>ssleay_rand_bytes</tt> in <tt>crypto/rand/md_rand.c</tt>):

<pre>if (!initialized)
{
RAND_poll();
initialized = 1;
}</pre>

<tt>RAND_poll</tt> seeds the random number generator using a system-specific entropy source, which is <tt>/dev/urandom</tt> on UNIX-like operating systems, and is a combination of [http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx <tt>CryptGenRandom</tt>] and other sources of entropy on Windows.

Be careful when deferring to <tt>RAND_poll</tt> on some Unix systems because it does not seed the generator. See the code guarded with <tt>OPENSSL_SYS_VXWORKS</tt> in <tt>rand_unix.c</tt>. Additionally, <tt>RAND_poll</tt> can have negative interactions on newer Windows platforms, so your program could hang or crash depending on the potential issue. See [[#Windows_Issues|Windows Issues]] below.

The <tt>urandom</tt> device may lack sufficient entropy for your needs, and you might want to reseed it immediately from <tt>/dev/random</tt>. On Unix and other operating systems that provide the block device, you can use <tt>[[Manual:RAND_load_file(3)|RAND_load_file]]</tt> to load directly from <tt>/dev/random</tt>.

<pre>int rc = RAND_load_file("/dev/random", 32);
if(rc != 32) {
/* RAND_load_file failed */
}

/* OK to proceed */</pre>

=== Reseed ===

The OpenSSL API allows you to provide a seed and refresh the generator's state with reseeds at anytime during the program's execution. Two functions are provided for seeding and reseeding: <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> and <tt>[[Manual:RAND_add(3)|RAND_add]]</tt>. <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> accepts a buffer and size; while <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> accepts a buffer, size, and entropy estimate in bytes. <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> will call <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> assuming 100% entropy.

<tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> is shown below. The function is <tt>void</tt>, so it <nowiki>[apparently]</nowiki> cannot fail (or convey failures). Though the example uses the actual number of bytes written to the buffer, the entire buffer can be used to increase entropy with hopes the unused bytes in the buffer has entropy to extract. Even though you can use uninitialized bytes as input, you should not expect any entropy in the uninitialized bytes. Finally, the function <tt>get_random_bytes</tt> is a placeholder for an application supplied function which gathers random data.

<pre>byte buffer[32];
int written = get_random_bytes(buffer, sizeof(buffer));

RAND_seed(buffer, written);
/* OK to proceed */</pre>

<tt>[[Manual:RAND_add(3)|RAND_add]]</tt> is similar to <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> but requires an entropy estimate. The estimate should be the number of full bytes of entropy in the buffer. If you have a 32 byte buffer with about 50% entropy, you should provide 16 as the entropy estimate. <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> is also a <tt>void</tt> function, so it cannot fail (or convey failures). The example also uses the actual number of bytes written to the buffer, but the entire buffer can be used to increase entropy. Note that <tt>[[Manual:RAND_add(3)|RAND_add]]</tt> takes a <tt>double</tt>, so be sure to '''avoid''' integer math. Otherwise, the entropy estimate calculation could result in 0.

<pre>char phrase[64];
int written = get_random_phrase(phrase, sizeof(phrase));

RAND_add(phrase, written, 0.12f * written /* 12% */);
/* OK to proceed */</pre>

On Windows machines, you can also use <tt>[[Manual:RAND_add(3)|RAND_screen]]</tt> and <tt>[[Manual:RAND_add(3)|RAND_event]]</tt>. <tt>[[Manual:RAND_add(3)|RAND_screen]]</tt> will mix the contents of the screen into the generator. <tt>[[Manual:RAND_add(3)|RAND_event]]</tt> can be used with programs that process [http://msdn.microsoft.com/en-us/library/windows/desktop/ff381405(v=vs.85).aspx Windows Messages]. Both methods should only be used with interactive programs, and not services nor drivers.

<tt>RAND_poll</tt> can be used to reseed the generator using the system entropy source.

=== Persisting ===

If you are worried about slow starts - or the time it takes to get the random number generator in good working order - you can write out a future seed and use it at next program execution. To save the future seed, use the library's <tt>RAND_write_file</tt> function. When using <tt>RAND_write_file</tt>, you only need to specify a filename. <tt>RAND_write_file</tt> returns the number of bytes written or -1 to indicate bytes were written without an appropriate seed (failure).

<pre>int written = RAND_write_file("prng.seed");
if(written <= 0)
/* RAND_write_file failed */

/* OK to proceed */</pre>

At program startup, you can attempt to read the saved seed with <tt>RAND_load_file</tt>. You can specify the number of bytes to read, or -1 to indicate the entire file should be used. The bytes read are automatically added to the generator. <tt>[[Manual:RAND_load_file(3)|RAND_load_file]]</tt> returns the number of bytes read.

<pre>int read = RAND_load_file("prng.seed", -1);
if(read <= 0)
/* RAND_load_file failed */

/* OK to proceed */</pre>

If possible, you should use protected storage offered by the operating system. For example, you should avoid writing the file and store the seed in the [http://developer.apple.com/library/ios/#documentation/security/Conceptual/keychainServConcepts/iPhoneTasks/iPhoneTasks.html iOS Keychain], [http://developer.android.com/reference/android/security/KeyChain.html Android KeyChain], or [http://msdn.microsoft.com/en-us/library/ms995355.aspx Windows DPAPI]. When writing the seed to the filesystem, be sure to protect the the seed through the file system's permission scheme (Linux has not realized userland needs help from the kernel when storing secrets).

<tt>RAND_load_file</tt> and <tt>RAND_write_file</tt> are documented at the [http://www.openssl.org/docs/manmaster/crypto/RAND_load_file.html <tt>RAND_load_file</tt> man page].

== Generation ==

After the generator has been seeded and is in good working order, you can extract bytes. You have three functions to extract bytes. First is <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> and the second is <tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt>. Both are software based and produce a pseudo-random stream. The third method is hardware based and it reuses <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt>.

If the random number generator is not properly seeded, then it will refuse to deliver random bytes and a "PRNG not seeded error" will occur.

=== Software ===

<tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> will fetch cryptographically strong random bytes. Cryptographically strong bytes are suitable for high integrity needs, such as long term key generation. If your generator is using a software algorithm, then the bytes will be pseudo-random (but still cryptographically strong). <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> returns 1 for success, and 0 otherwise. If you changed the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>[[Manual:ERR_get_error(3)|ERR_get_error]]</tt>.

<pre>byte buffer[128];

int rc = RAND_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 1) {
/* RAND_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

<tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt> returns pseudo-random bytes which ''can'' be cryptographically strong. The function returns 1 if the bytes are cryptographically strong, and 0 otherwise. If your application has high integrity requirements, it should ''not'' use <tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt>.

When using <tt>[[Manual:RAND_bytes(3)|RAND_pseudo_bytes]]</tt>, both 0 and 1 indicate success. If you change the <tt>RAND_METHOD</tt> and it is not supported, then the function will return -1. In case of error, you can call <tt>[[Manual:ERR_get_error(3)|ERR_get_error]]</tt>.

<pre>byte buffer[32];

int rc = RAND_pseudo_bytes(buffer, sizeof(buffer));
unsigned long err = ERR_get_error();

if(rc != 0 && rc != 1) {
/* RAND_pseudo_bytes failed */
/* `err` is valid */
}

/* OK to proceed */</pre>

=== Hardware ===

Hardware random number generators are almost always better to use than a software based generator. Hardware generators are often called True Random Number generators (TRNG) or Non-Deterministic Random Number Generators since they don't rely on the deterministic behavior of executing software instructions. Their bits streams are nearly always indistinguishable from random streams, and their entropy is always nearly 100%.

Some hardware generators are easier to use than other. For example, an [http://www.entropykey.co.uk EntropyKey] will provide a driver that replenishes <tt>/dev/random</tt>, so an application does not have to do anything special other than reading from the device. Other generators, such as Intel's [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key], must be integrated into an application. When integrating generators using OpenSSL, you will use the library's <tt>ENGINE</tt> API.

To integrate a hardware based random number generator, you should load the apporpriate <tt>ENGINE</tt> for the hardware based implementation. Once loaded, set the engine's <tt>RAND_method</tt> method as default with <tt>ENGINE_METHOD_RAND</tt>. After you load the engine and set <tt>RAND_method</tt> for the hardware generator, you simply use <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> as discussed earlier. There are no special steps necessary after the configuration.

If you have OpenSSL 1.0.1 and a machine with [http://semiaccurate.com/2012/04/23/intel-launches-ivy-bridge-amid-crushing-marketing-buzzwords/ 3rd generation Core i5 or i7 processor (Ivy Bridge)], then the Intel [http://software.intel.com/en-us/blogs/2012/05/14/what-is-intelr-secure-key-technology Secure Key Technology] (formerly called Bull Mountain) [[Commercial Product Disclaimer|<nowiki>[disclaimer]</nowiki>]] is available to you. The hardware generator is accessed through the <tt>ENGINE</tt> API and wraps the <tt>rdrand</tt> instruction. Also see [http://software.intel.com/en-us/blogs/2014/10/03/changes-to-rdrand-integration-in-openssl Changes to RDRAND integration in OpenSSL] on the Intel blog.

To ensure <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> uses the hardware engine, you must perform three steps:

* load the <tt>rdrand</tt> engine
* acquire a handle to the engine
* set the default <tt>RAND_method</tt> to the engine

The code below shows you how to load the Intel random number generator engine and set the default <tt>RAND_method</tt>. The code is available for download at [[Media:test-rdrand.c|test-rdrand.c]]. While you can call <tt>[[Manual:engine(3)|ENGINE_load_builtin_engines]]</tt> to make all engines available, the code below focuses on the one engine of interest and loads it via <tt>ENGINE_load_rdrand</tt>. Before the call to <tt>ENGINE_load_rdrand</tt>, be sure to call <tt>OPENSSL_cpuid_setup</tt> to load the proper CPU capabilities. See [[Manual:Engine(3)|OpenSSL's engine(3)]] for more details on engines, their loading, and operation.

Displaying the error code in hexadecimal gives you an error that is easily consumed by <tt>openssl errstr</tt>.

<pre> 1 unsigned long err = 0;
2 int rc = 0;
3
4 OPENSSL_cpuid_setup();
5 ENGINE_load_rdrand();
6
7 ENGINE* eng = ENGINE_by_id("rdrand");
8 err = ERR_get_error();
9
10 if(NULL == eng) {
11 fprintf(stderr, "ENGINE_load_rdrand failed, err = 0x%lx\n", err);
12 abort(); /* failed */
13 }
14
15 rc = ENGINE_init(eng);
16 err = ERR_get_error();
17
18 if(0 == rc) {
19 fprintf(stderr, "ENGINE_init failed, err = 0x%lx\n", err);
20 abort(); /* failed */
21 }
22
23 rc = ENGINE_set_default(eng, ENGINE_METHOD_RAND);
24 err = ERR_get_error();
25
26 if(0 == rc) {
27 fprintf(stderr, "ENGINE_set_default failed, err = 0x%lx\n", err);
28 abort(); /* failed */
29 }
30
31 /* OK to proceed */
32
33 ...
34 ENGINE_finish(eng);
35 ENGINE_free(eng);
36 ENGINE_cleanup();</pre>

If you hardware does not support the Intel generator, you will receive a <tt>NULL</tt> pointer at line 7 and encounter error 0x2606c043 at line 8. The error can then be fed to <tt>openssl errstr</tt>:

<pre>$ ./test-rdrand.exe
...
ENGINE_load_rdrand failed, err = 0x2606c043
$ openssl errstr 0x2606c043
error:2606C043:engine routines:ENGINE_FREE_UTIL:passed a null parameter</pre>

[[File:test-rdrand.png|thumb|250px|right|Verifying rdrand code path]] Line 13 attempts to set the default <tt>RAND_method</tt> to that provided by the engine using <tt>[[Manual:engine(3)|ENGINE_set_default]]</tt> with <tt>ENGINE_METHOD_RAND</tt>. Upon success, OpenSSL will internally use <tt>OPENSSL_ia32_rdrand</tt> for random number generation. To verify code correctness, simply set a breakpoint on the function and wait for the debugger to snap as shown in the figure to the right.

The 0x2606c043 error is actually caused by <tt>ENGINE_load_rdrand</tt>. The function will verify the capabilities of the hardware and load the generator's engine if available. <tt>ENGINE_load_rdrand</tt> is a <tt>void</tt> function, so it cannot fail or cannot convey failures (which we know is incorrect from a test run). The source code can be found in <tt>eng_rdrand.c</tt> and is shown below.

<pre>void ENGINE_load_rdrand (void)
{
extern unsigned int OPENSSL_ia32cap_P[];

if (OPENSSL_ia32cap_P[1] & (1<<(62-32)))
{
ENGINE *toadd = ENGINE_rdrand();
if(!toadd) return;
ENGINE_add(toadd);
ENGINE_free(toadd);
ERR_clear_error();
}
}</pre>

A patch is available to provide <tt>ENGINE_R_NO_SUCH_ENGINE</tt> error code for non-RdRand CPUs. See ''[https://rt.openssl.org/Ticket/Display.html?id=3143 <nowiki>[openssl.org #3143]: ENGINE_load_rdrand sane failure code</nowiki>]'' for details.

<pre>$ ./test-rdrand.exe
...
ENGINE_load_rdrand failed, err = 0x26077074
$ openssl errstr 0x26077074
error:26077074:engine routines:ENGINE_init:no such engine</pre>

According to [http://software.intel.com/en-us/articles/performance-impact-of-intel-secure-key-on-openssl Intel documentation], the random number generator does not need to be seeded via the <tt>[[Manual:RAND_add(3)|RAND_seed]]</tt> function because the generator is self-seeding. For optimal performance, code that is aware of the underlying random engine can forgo gathering entropy.

Additionally (or more importantly), the following will not cause a crash when using the hardware random number generator (and it fails silently so all looks good from outside the fishbowl):

<pre>/* Bad - don't do this in production */
byte seed[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
RAND_seed(seed, sizeof(seed));</pre>

Finally, you can test if your Mac OS X system has <tt>rdrand</tt> available with the following (thanks to Dave Zarzycki):

<pre>$ sysctl hw.optional.rdrand
hw.optional.rdrand: 1</pre>

On Linux, you can <tt>cat</tt> <tt>cpuinfo</tt>:
<pre>$ cat /proc/cpuinfo | grep -i rdrand
rdrand : 1</pre>

== Windows Issues ==

Windows platforms offer two potential problems to OpenSSL's <tt>RAND_poll</tt>. First is a hang due to the heap walk, and second is Application Verifier failures due to use of Windows' API call <tt>netstatget</tt>.

See [http://rt.openssl.org/Ticket/Display.html?id=2100&user=guest&pass=guest Bug 2100] for details on the heap walk issue. See [https://groups.google.com/forum/#!topic/mailing.openssl.users/uEO5roA55Wg UAC related errors on windows 7 64-bit with Application Verifier] for details and a workaround for the Application Verifier issue.

== Miscellaneous ==

Two miscellaneous items remaining are generator cleanup and status. <tt>[[Manual:RAND_cleanup(3)|RAND_cleanup]]</tt> securely erases the memory used by the random number generator.

You can query the generator's state with <tt>[[Manual:RAND_add(3)|RAND_status]]</tt>. <tt>[[Manual:RAND_add(3)|RAND_status]]</tt> returns 1 if the generator is in good working order. If your generator is not in good working order, you should reseed it with at least 256 bits (32 bytes) of entropy. The function [http://www.mail-archive.com/openssl-dev@openssl.org/msg04212.html purposefully hides the number of bytes needed] for the reseed operation.

On Android, take care to specify <tt>-mfloat-abi=softfp</tt> when building the library for use via JNI. If you specify <tt>-mfloat-abi=hard</tt> or <tt>-mhard-float</tt> (even if the hardware support a floating point unit), then the entropy estimate passed to <tt>RAND_add</tt> will always be 0.0f. See [https://groups.google.com/d/msg/android-ndk/NbUq9FDDZOo/TJJsAS6nM7wJ Hard-float and JNI] for details.

By default, OpenSSL will use the <tt>RDRANG</tt> engine to generate random numbers if the hardware is available. The behavior has been changed, but the change is only available through git at the moment. If you are concerned with <tt>RDRANG</tt> tampering, then see the discussion of [[Library_Initialization#ENGINEs_and_RDRAND | ENGINEs and RDRAND]].

== FIPS Mode ==

FIPS mode is a special mode of operation which specifies the library should operate according to the security policies and procedures specified in [http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf FIPS 140-2]. The mode requires use of the FIPS Capable OpenSSL library, and must be enabled with a call to <tt>FIPS_mode_set</tt>. Once in FIPS mode, a ''default DRBG'' is used as specified in [http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf SP800-90].

The default DRBG is 256-bit CTR AES using a derivation function, and is decided by the application and not the library module. In the case of an OpenSSL application it is specified in <tt>rand_lib.c</tt> via the <tt>OPENSSL_DRBG_DEFAULT_TYPE</tt> and <tt>OPENSSL_DRBG_DEFAULT_FLAGS</tt> preprocessor macros to allow them to be overridden by local compilation options or at runtime.

To use the FIPS random number generator, simply use <tt>[[Manual:RAND_bytes(3)|RAND_bytes]]</tt> as described earlier. Note that the call to <tt>FIPS_mode_set</tt> must succeed in order to operate in FIPS 140 mode.

== Thread Safety ==

The random number generators (among other parts of OpenSSL) are not thread safe by default. To ensure thread safety, you must call <tt>[[Manual:Threads(3)|CRYPTO_set_locking_callback]]</tt>.

== Fork Safety ==

OpenSSL's random number generator is not [[Random_fork-safety|fork-safe]], so the issue should be carefully understood and remediated if necessary. See [[Random_fork-safety|Random Fork-Safety]] for details.

[[Category:Expert Review]]

==See also==
* [[EVP]]
* [[Libcrypto API]]
* [http://jbp.io/2014/01/16/openssl-rand-api/ Analysis of the OpenSSL random API]

==References==
# Lenstra, A. K., Hughes, J. P., Augier, M., Bos, J. W., Kleinjung, T., & Wachter, C. (2012, February 14). Ron was wrong, Whit is right. p.17. Retrieved from the Cryptology ePrint Archive: [https://eprint.iacr.org/2012/064 Report 2012/064].
# Heninger, N. (2012, February 15). New research: There’s no need to panic over factorable keys-just mind your Ps and Qs. Retrieved from [https://freedom-to-tinker.com/2012/02/15/new-research-theres-no-need-panic-over-factorable-keys-just-mind-your-ps-and-qs/ link].

[[Category:Cryptography]]
[[Category:Crypto API]]

Template talk:TODO

2019-07-27T01:55:19Z

Jflopezfernandez: Added a border to the template and centered it at the top of the page.

I think tweaking this template to appear more like a notice or notification makes it look cleaner and more impactful. This is the current template for the <code>TODO</code> category:

{|
|-
|rowspan="2" align="left"|[[Image:Sticky.png|left|70px]]
|align="left" valign="bottom" style="font-size:1.5em; color:#777777;"|'''TODO'''
|-
|align="left" valign="top" style="color:#aaaaaa;"|{{{1|Please consider contributing to this section}}}.
|}

<includeonly>[[Category: TODO]]</includeonly>

This is the change I'm proposing:

{| style="border: 1px solid #A1A1A1; background-color: #FFFFFF; margin: auto; width: 30%; text-align: center;"
|-
|rowspan="2" align="center"|[[Image:Sticky.png|center|70px]]
|align="left" valign="bottom" style="font-size:1.5em; color:#777777;"|'''TODO'''
|-
|align="left" valign="top" style="color:#aaaaaa;"|{{{1|Please consider contributing to this section}}}.
|}

<includeonly>[[Category: TODO]]</includeonly>

[[User:Jflopezfernandez|Jflopezfernandez]] ([[User talk:Jflopezfernandez|talk]]) 01:55, 27 July 2019 (UTC)

Code Quality

2019-07-26T23:30:21Z

Jflopezfernandez: Fixed typos

Code Quality can be discussed.

Having a code of good quality should help to have a secure code.

Classical buffer overflows by example are a matter of good coding practice.
Maintaining Code is of course easier if code is readable.

Should discussions about code quality done in discussion tab or on dev mailling list or ... ?

Talk:Libcrypto API

2019-07-26T23:28:35Z

Jflopezfernandez: /* OPENSSL_config deprecated */ new section