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 *   Why do I get errors when trying to decrypt 1.0.2 data with 1.1.0?
  66
  67     A message digest is used to create the encrypt/decrypt key from
  68     a human-entered passphrase.  In OpenSSL 1.1.0 we changed from MD5 to
  69     SHA-256.  We did this as part of an overall change to move away from
  70     the now-insecure and broken MD5 algorithm.  If you have old files,
  71     use the "-md md5" flag to decrypt them.
  72
  73 *   How do I create certificates or certificate requests?
  74
  75     Check out the CA.pl(1) manual page. This provides a simple wrapper round
  76     the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check
  77     out the manual pages for the individual utilities and the certificate
  78     extensions documentation (in ca(1), req(1), and x509v3_config(5) ).
  79
  80 *   Why can't I create certificate requests?
  81
  82     You typically get the error:
  83
  84         unable to find 'distinguished_name' in config
  85         problems making Certificate Request
  86
  87     This is because it can't find the configuration file. Check out the
  88     DIAGNOSTICS section of req(1) for more information.
  89
  90 *   Why does &lt;SSL program&gt; fail with a certificate verify error?
  91
  92     This problem is usually indicated by log messages saying something like
  93     "unable to get local issuer certificate" or "self signed certificate".
  94     When a certificate is verified its root CA must be "trusted" by OpenSSL
  95     this typically means that the CA certificate must be placed in a directory
  96     or file and the relevant program configured to read it. The OpenSSL program
  97     'verify' behaves in a similar way and issues similar error messages: check
  98     the verify(1) program manual page for more information.
  99
 100 *   How can I create DSA certificates?
 101
 102     Check the CA.pl(1) manual page for a DSA certificate example.
 103
 104 *   Why can't I make an SSL connection to a server using a DSA certificate?
 105
 106     Typically you'll see a message saying there are no shared ciphers when
 107     the same setup works fine with an RSA certificate. There are two possible
 108     causes. The client may not support connections to DSA servers most web
 109     browsers (including Netscape and MSIE) only support connections to servers
 110     supporting RSA cipher suites. The other cause is that a set of DH parameters
 111     has not been supplied to the server. DH parameters can be created with the
 112     dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh(3) for example:
 113     check the source to s_server in apps/s_server.c for an example.
 114
 115 *   How can I remove the passphrase on a private key?
 116
 117     Firstly you should be really *really* sure you want to do this. Leaving
 118     a private key unencrypted is a major security risk. If you decide that
 119     you do have to do this check the EXAMPLES sections of the rsa(1) and
 120     dsa(1) manual pages.
 121
 122 *   Why can't I use OpenSSL certificates with SSL client authentication?
 123
 124     What will typically happen is that when a server requests authentication
 125     it will either not include your certificate or tell you that you have
 126     no client certificates (Netscape) or present you with an empty list box
 127     (MSIE). The reason for this is that when a server requests a client
 128     certificate it includes a list of CAs names which it will accept. Browsers
 129     will only let you select certificates from the list on the grounds that
 130     there is little point presenting a certificate which the server will
 131     reject.
 132
 133     The solution is to add the relevant CA certificate to your servers "trusted
 134     CA list". How you do this depends on the server software in uses. You can
 135     print out the servers list of acceptable CAs using the OpenSSL s_client tool:
 136
 137         openssl s_client -connect www.some.host:443 -prexit
 138
 139     If your server only requests certificates on certain URLs then you may need
 140     to manually issue an HTTP GET command to get the list when s_client connects:
 141
 142         GET /some/page/needing/a/certificate.html
 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
 155     appropriate link. On MSIE certain extensions such as .der or .cacert
 156     may also work, or you can import the certificate using the
 157     certificate import wizard.
 158
 159     You can convert a certificate to DER form using the command:
 160
 161         openssl x509 -in ca.pem -outform DER -out ca.der
 162
 163     Occasionally someone suggests using a command such as:
 164
 165         openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem
 166
 167     DO NOT DO THIS! This command will give away your CAs private key and
 168     reduces its security to zero: allowing anyone to forge certificates in
 169     whatever name they choose.
 170
 171 *   Why is OpenSSL x509 DN output not conformant to RFC2253?
 172
 173     The ways to print out the oneline format of the DN (Distinguished Name) have
 174     been extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex(3)
 175     interface, the "-nameopt" option could be introduced. See the manual
 176     page of the "openssl x509" command line tool for details. The old behaviour
 177     has however been left as default for the sake of compatibility.
 178
 179 *   Why does OpenSSL set the authority key identifier (AKID) extension
 180     incorrectly?
 181
 182     It doesn't: this extension is often the cause of confusion.
 183
 184     Consider a certificate chain A->B->C so that A signs B and B signs
 185     C. Suppose certificate C contains AKID.
 186
 187     The purpose of this extension is to identify the authority
 188     certificate B. This can be done either by including the subject key
 189     identifier of B or its issuer name and serial number.
 190
 191     In this latter case because it is identifying certificate B it must
 192     contain the issuer name and serial number of B.
 193
 194     It is often wrongly assumed that it should contain the subject name
 195     of B. If it did this would be redundant information because it would
 196     duplicate the issuer name of C.
 197
 198 *   How can I set up a bundle of commercial root CA certificates?
 199
 200     The OpenSSL software is shipped without any root CA certificate as the
 201     OpenSSL project does not have any policy on including or excluding
 202     any specific CA and does not intend to set up such a policy. Deciding
 203     about which CAs to support is up to application developers or
 204     administrators.
 205
 206     Other projects do have other policies so you can for example extract the CA
 207     bundle used by Mozilla and/or modssl as described in this article:
 208     https://www.mail-archive.com/modssl-users@modssl.org/msg16980.html
 209
 210 *   Some secure servers 'hang' with OpenSSL 1.0.1, is this a bug?
 211
 212     OpenSSL 1.0.1 is the first release to support TLS 1.2, among other things,
 213     this increases the size of the default ClientHello message to more than
 214     255 bytes in length. Some software cannot handle this and hangs.
 215
 216 *   Some secure servers emit an infinite loop of HTTP headers with an OpenSSL
 217     1.1.0 client, is this a bug?
 218
 219     OpenSSL 1.1.0 introduced support for several new TLS extensions, including
 220     encrypt-then-mac and extended-master-secret, both of which provide
 221     significant security improvements.  Unfortunately, some deployed TLS
 222     servers are severely broken and do not implement extensibility in a
 223     standards-compliant manner; these servers may exhibit strange behavior
 224     such as repeating the HTTP headers in a loop after receiving a ClientHello
 225     that includes such TLS extensions unknown to them.  While these new TLS
 226     extensions provide significant security benefits to clients and are
 227     accordingly enabled by default in modern TLS clients, if bringing the
 228     server into compliance is not possible, the extension(s) in question can
 229     be disabled on a per-connection basis when talking to the buggy server, by
 230     using SSL_set_options(3).