docs/faq-2-user.txt

   1 Using the OpenSSL application
   2
   3 * Why do I get a "PRNG not seeded" error message?
   4
   5 Cryptographic software needs a source of unpredictable data to work
   6 correctly.  Many open source operating systems provide a "randomness
   7 device" (/dev/urandom or /dev/random) that serves this purpose.
   8 All OpenSSL versions try to use /dev/urandom by default; starting with
   9 version 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not
  10 available.
  11
  12 On other systems, applications have to call the RAND_add(3) or
  13 RAND_seed(3) function with appropriate data before generating keys or
  14 performing public key encryption. (These functions initialize the
  15 pseudo-random number generator, PRNG.)  Some broken applications do
  16 not do this.  As of version 0.9.5, the OpenSSL functions that need
  17 randomness report an error if the random number generator has not been
  18 seeded with at least 128 bits of randomness.  If this error occurs and
  19 is not discussed in the documentation of the application you are
  20 using, please contact the author of that application; it is likely
  21 that it never worked correctly.  OpenSSL 0.9.5 and later make the
  22 error visible by refusing to perform potentially insecure encryption.
  23
  24 On systems without /dev/urandom and /dev/random, it is a good idea to
  25 use the Entropy Gathering Demon (EGD); see the RAND_egd(3) manpage for
  26 details.  Starting with version 0.9.7, OpenSSL will automatically look
  27 for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and
  28 /etc/entropy.
  29
  30 Most components of the openssl command line utility automatically try
  31 to seed the random number generator from a file.  The name of the
  32 default seeding file is determined as follows: If environment variable
  33 RANDFILE is set, then it names the seeding file.  Otherwise if
  34 environment variable HOME is set, then the seeding file is $HOME/.rnd.
  35 If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will
  36 use file .rnd in the current directory while OpenSSL 0.9.6a uses no
  37 default seeding file at all.  OpenSSL 0.9.6b and later will behave
  38 similarly to 0.9.6a, but will use a default of "C:\" for HOME on
  39 Windows systems if the environment variable has not been set.
  40
  41 If the default seeding file does not exist or is too short, the "PRNG
  42 not seeded" error message may occur.
  43
  44 The openssl command line utility will write back a new state to the
  45 default seeding file (and create this file if necessary) unless
  46 there was no sufficient seeding.
  47
  48 Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work.
  49 Use the "-rand" option of the OpenSSL command line tools instead.
  50 The $RANDFILE environment variable and $HOME/.rnd are only used by the
  51 OpenSSL command line tools. Applications using the OpenSSL library
  52 provide their own configuration options to specify the entropy source,
  53 please check out the documentation coming the with application.
  54
  55 * Why do I get an "unable to write 'random state'" error message?
  56
  57 Sometimes the openssl command line utility does not abort with
  58 a "PRNG not seeded" error message, but complains that it is
  59 "unable to write 'random state'".  This message refers to the
  60 default seeding file (see previous answer).  A possible reason
  61 is that no default filename is known because neither RANDFILE
  62 nor HOME is set.  (Versions up to 0.9.6 used file ".rnd" in the
  63 current directory in this case, but this has changed with 0.9.6a.)
  64
  65 * How do I create certificates or certificate requests?
  66
  67 Check out the CA.pl(1) manual page. This provides a simple wrapper round
  68 the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check
  69 out the manual pages for the individual utilities and the certificate
  70 extensions documentation (in ca(1),
  71 req(1),
  72 and x509v3_config(5) ).
  73
  74 * Why can't I create certificate requests?
  75
  76 You typically get the error:
  77 <PRE>
  78     unable to find 'distinguished_name' in config
  79     problems making Certificate Request
  80 </PRE>
  81
  82 This is because it can't find the configuration file. Check out the
  83 DIAGNOSTICS section of req(1) for more information.
  84
  85 * Why does &lt;SSL program&gt; fail with a certificate verify error?
  86
  87 This problem is usually indicated by log messages saying something like
  88 "unable to get local issuer certificate" or "self signed certificate".
  89 When a certificate is verified its root CA must be "trusted" by OpenSSL
  90 this typically means that the CA certificate must be placed in a directory
  91 or file and the relevant program configured to read it. The OpenSSL program
  92 'verify' behaves in a similar way and issues similar error messages: check
  93 the verify(1) program manual page for more information.
  94
  95 * How can I create DSA certificates?
  96
  97 Check the CA.pl(1) manual page for a DSA certificate example.
  98
  99 * Why can't I make an SSL connection to a server using a DSA certificate?
 100
 101 Typically you'll see a message saying there are no shared ciphers when
 102 the same setup works fine with an RSA certificate. There are two possible
 103 causes. The client may not support connections to DSA servers most web
 104 browsers (including Netscape and MSIE) only support connections to servers
 105 supporting RSA cipher suites. The other cause is that a set of DH parameters
 106 has not been supplied to the server. DH parameters can be created with the
 107 dhparam(1) command and loaded using the
 108 SSL_CTX_set_tmp_dh(3) for example:
 109 check the source to s_server in apps/s_server.c for an example.
 110
 111 * How can I remove the passphrase on a private key?
 112
 113 Firstly you should be really *really* sure you want to do this. Leaving
 114 a private key unencrypted is a major security risk. If you decide that
 115 you do have to do this check the EXAMPLES sections of the rsa(1) and
 116 dsa(1) manual pages.
 117
 118 * Why can't I use OpenSSL certificates with SSL client authentication?
 119
 120 What will typically happen is that when a server requests authentication
 121 it will either not include your certificate or tell you that you have
 122 no client certificates (Netscape) or present you with an empty list box
 123 (MSIE). The reason for this is that when a server requests a client
 124 certificate it includes a list of CAs names which it will accept. Browsers
 125 will only let you select certificates from the list on the grounds that
 126 there is little point presenting a certificate which the server will
 127 reject.
 128
 129 The solution is to add the relevant CA certificate to your servers "trusted
 130 CA list". How you do this depends on the server software in uses. You can
 131 print out the servers list of acceptable CAs using the OpenSSL s_client tool:
 132
 133 <PRE>
 134     openssl s_client -connect www.some.host:443 -prexit
 135 </PRE>
 136
 137 If your server only requests certificates on certain URLs then you may need
 138 to manually issue an HTTP GET command to get the list when s_client connects:
 139
 140 <PRE>
 141     GET /some/page/needing/a/certificate.html
 142 </PRE>
 143
 144 If your CA does not appear in the list then this confirms the problem.
 145
 146 * Why does my browser give a warning about a mismatched hostname?
 147
 148 Browsers expect the server's hostname to match the value in the commonName
 149 (CN) field of the certificate. If it does not then you get a warning.
 150
 151 * How do I install a CA certificate into a browser?
 152
 153 The usual way is to send the DER encoded certificate to the browser as
 154 MIME type application/x-x509-ca-cert, for example by clicking on an appropriate
 155 link. On MSIE certain extensions such as .der or .cacert may also work, or you
 156 can import the certificate using the certificate import wizard.
 157
 158 You can convert a certificate to DER form using the command:
 159
 160 openssl x509 -in ca.pem -outform DER -out ca.der
 161
 162 Occasionally someone suggests using a command such as:
 163
 164 openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem
 165
 166 DO NOT DO THIS! This command will give away your CAs private key and
 167 reduces its security to zero: allowing anyone to forge certificates in
 168 whatever name they choose.
 169
 170 * Why is OpenSSL x509 DN output not conformant to RFC2253?
 171
 172 The ways to print out the oneline format of the DN (Distinguished Name) have
 173 been extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex(3)
 174 interface, the "-nameopt" option could be introduced. See the manual
 175 page of the "openssl x509" command line tool for details. The old behaviour
 176 has however been left as default for the sake of compatibility.
 177
 178 * Why does OpenSSL set the authority key identifier (AKID) extension incorrectly?
 179
 180 It doesn't: this extension is often the cause of confusion.
 181
 182 Consider a certificate chain A->B->C so that A signs B and B signs C. Suppose
 183 certificate C contains AKID.
 184
 185 The purpose of this extension is to identify the authority certificate B. This
 186 can be done either by including the subject key identifier of B or its issuer
 187 name and serial number.
 188
 189 In this latter case because it is identifying certificate B it must contain the
 190 issuer name and serial number of B.
 191
 192 It is often wrongly assumed that it should contain the subject name of B. If it
 193 did this would be redundant information because it would duplicate the issuer
 194 name of C.
 195
 196 * How can I set up a bundle of commercial root CA certificates?
 197
 198 The OpenSSL software is shipped without any root CA certificate as the
 199 OpenSSL project does not have any policy on including or excluding
 200 any specific CA and does not intend to set up such a policy. Deciding
 201 about which CAs to support is up to application developers or
 202 administrators.
 203
 204 Other projects do have other policies so you can for example extract the CA
 205 bundle used by Mozilla and/or modssl as described in this article:
 206 @@@https://www.mail-archive.com/modssl-users@modssl.org/msg16980.html@@@
 207
 208 * Some secure servers 'hang' with OpenSSL 1.0.1, is this a bug?
 209
 210 OpenSSL 1.0.1 is the first release to support TLS 1.2, among other things,
 211 this increases the size of the default ClientHello message to more than
 212 255 bytes in length. Some software cannot handle this and hangs.