|
1 | | -<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.394 2007/12/23 03:10:04 momjian Exp $ --> |
| 1 | +<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.395 2007/12/25 04:00:44 momjian Exp $ --> |
2 | 2 |
|
3 | 3 | <chapter Id="runtime"> |
4 | 4 | <title>Operating System Environment</title> |
@@ -1373,6 +1373,42 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput |
1373 | 1373 | </important> |
1374 | 1374 | </sect1> |
1375 | 1375 |
|
| 1376 | + <sect1 id="preventing-server-spoofing"> |
| 1377 | + <title>Preventing Server Spoofing</title> |
| 1378 | + |
| 1379 | + <indexterm zone="preventing-server-spoofing"> |
| 1380 | + <primary>server spoofing</primary> |
| 1381 | + </indexterm> |
| 1382 | + |
| 1383 | + <para> |
| 1384 | + While the server is running, it is not possible for a malicious user |
| 1385 | + to interfere with client/server communications. However, when the |
| 1386 | + server is down it is possible for a local user to spoof the normal |
| 1387 | + server by starting their own server. The spoof server could read |
| 1388 | + passwords and queries sent by clients, but could not return any data |
| 1389 | + because the <varname>PGDATA</> directory would still be secure because |
| 1390 | + of directory permissions. Spoofing is possible because any user can |
| 1391 | + start a database server; a client cannot identify an invalid server |
| 1392 | + unless it is specially configured. |
| 1393 | + </para> |
| 1394 | + |
| 1395 | + <para> |
| 1396 | + The simplest way to prevent invalid servers for <literal>local</> |
| 1397 | + connections is to use a Unix domain socket directory (<xref |
| 1398 | + linkend="guc-unix-socket-directory">) that has write permission only |
| 1399 | + for a trusted local user. This prevents a malicious user from creating |
| 1400 | + their own socket file in that directory. For TCP connections the server |
| 1401 | + must accept only <literal>hostssl</> connections (<xref |
| 1402 | + linkend="auth-pg-hba-conf">) and have SSL |
| 1403 | + <filename>server.key</filename> (key) and |
| 1404 | + <filename>server.crt</filename> (certificate) files (<xref |
| 1405 | + linkend="ssl-tcp">). The TCP client must connect using |
| 1406 | + <literal>sslmode='require'</> (<xref linkend="libpq-connect">) and have |
| 1407 | + a <filename>~/.postgresql/root.crt</> SSL certificate (<xref |
| 1408 | + linkend="libpq-ssl">). |
| 1409 | + </para> |
| 1410 | + </sect1> |
| 1411 | + |
1376 | 1412 | <sect1 id="encryption-options"> |
1377 | 1413 | <title>Encryption Options</title> |
1378 | 1414 |
|
@@ -1545,97 +1581,105 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput |
1545 | 1581 | <productname>PostgreSQL</> server can be started with |
1546 | 1582 | <acronym>SSL</> enabled by setting the parameter |
1547 | 1583 | <xref linkend="guc-ssl"> to <literal>on</> in |
1548 | | - <filename>postgresql.conf</>. When |
1549 | | - starting in <acronym>SSL</> mode, the server will look for the |
1550 | | - files <filename>server.key</> and <filename>server.crt</> in the |
1551 | | - data directory, which must contain the server private key |
1552 | | - and certificate, respectively. These files must be set up correctly |
1553 | | - before an <acronym>SSL</>-enabled server can start. If the private key is |
1554 | | - protected with a passphrase, the server will prompt for the |
1555 | | - passphrase and will not start until it has been entered. |
| 1584 | + <filename>postgresql.conf</>. The server will listen for both standard |
| 1585 | + and <acronym>SSL</> connections on the same TCP port, and will negotiate |
| 1586 | + with any connecting client on whether to use <acronym>SSL</>. By |
| 1587 | + default, this is at the client's option; see <xref |
| 1588 | + linkend="auth-pg-hba-conf"> about how to set up the server to require |
| 1589 | + use of <acronym>SSL</> for some or all connections. |
1556 | 1590 | </para> |
1557 | 1591 |
|
1558 | 1592 | <para> |
1559 | | -The server will listen for both standard and <acronym>SSL</> |
1560 | | -connections on the same TCP port, and will negotiate with any |
1561 | | -connecting client on whether to use <acronym>SSL</>. By default, |
1562 | | -this is at the client's option; see <xref |
1563 | | -linkend="auth-pg-hba-conf"> about how to set up the server to |
1564 | | -require use of <acronym>SSL</> for some or all connections. |
| 1593 | +<productname>PostgreSQL</productname> reads the system-wide |
| 1594 | +<productname>OpenSSL</productname> configuration file. By default, this |
| 1595 | +file is named <filename>openssl.cnf</filename> and is located in the |
| 1596 | +directory reported by <literal>openssl version -d</>. |
| 1597 | +This default can be overridden by setting environment variable |
| 1598 | +<envar>OPENSSL_CONF</envar> to the name of the desired configuration file. |
1565 | 1599 | </para> |
1566 | 1600 |
|
1567 | 1601 | <para> |
1568 | 1602 | <productname>OpenSSL</productname> supports a wide range of ciphers |
1569 | | - and authentication algorithms, whose strength varies significantly. |
1570 | | - You can restrict the list of ciphers that can be used to connect to |
1571 | | - your server by adjusting the <xref linkend="guc-ssl-ciphers"> parameter. |
| 1603 | + and authentication algorithms, of varying strength. While a list of |
| 1604 | + ciphers can be specified in the <productname>OpenSSL</productname> |
| 1605 | + configuration file, you can specify ciphers specifically for use by |
| 1606 | + the database server by modifying <xref linkend="guc-ssl-ciphers"> in |
| 1607 | + <filename>postgresql.conf</>. |
1572 | 1608 | </para> |
1573 | 1609 |
|
1574 | 1610 | <para> |
1575 | | - <productname>PostgreSQL</productname> reads the system-wide |
1576 | | - <productname>OpenSSL</productname> configuration file. By default, this |
1577 | | - file is named <filename>openssl.cnf</filename> and is located in the |
1578 | | - directory reported by <literal>openssl version -d</>. |
1579 | | - This default can be overridden by setting environment variable |
1580 | | - <envar>OPENSSL_CONF</envar> to the name of the desired configuration file. |
| 1611 | + To start in <acronym>SSL</> mode, the files <filename>server.crt</> |
| 1612 | + and <filename>server.key</> must exist in the server's data directory. |
| 1613 | + These files should contain the server certificate and private key, |
| 1614 | + respectively. If the private key is protected with a passphrase, the |
| 1615 | + server will prompt for the passphrase and will not start until it has |
| 1616 | + been entered. |
| 1617 | + </para> |
| 1618 | + |
| 1619 | + <para> |
| 1620 | + To require the client to supply a trusted certificate, place |
| 1621 | + certificates of the certificate authorities (<acronym>CA</acronym>) |
| 1622 | + you trust in the file <filename>root.crt</filename> in the data |
| 1623 | + directory. A certificate will then be requested from the client during |
| 1624 | + SSL connection startup. (See <xref linkend="libpq-ssl"> for a |
| 1625 | + description of how to set up client certificates.) The server will |
| 1626 | + verify that the client's certificate is signed by one of the trusted |
| 1627 | + certificate authorities. Certificate Revocation List (CRL) entries |
| 1628 | + are also checked if the file <filename>root.crl</filename> exists. |
| 1629 | + </para> |
| 1630 | + |
| 1631 | + <para> |
| 1632 | + If the <filename>root.crt</filename> file is not present, client |
| 1633 | + certificates will not be requested or checked. In this mode, SSL |
| 1634 | + provides encrypted communication but not authentication. |
1581 | 1635 | </para> |
1582 | 1636 |
|
1583 | 1637 | <para> |
1584 | | - For details on how to create your server private key and certificate, |
1585 | | - refer to the <productname>OpenSSL</> documentation. A |
1586 | | - self-signed certificate can be used for testing, but a |
1587 | | - certificate signed by a certificate authority (<acronym>CA</>) |
1588 | | - (either one of the global |
1589 | | - <acronym>CAs</> or a local one) should be used in production so the |
1590 | | - client can verify the server's identity. To create a quick |
1591 | | - self-signed certificate, use the following |
1592 | | - <productname>OpenSSL</productname> command: |
| 1638 | + The files <filename>server.key</>, <filename>server.crt</>, |
| 1639 | + <filename>root.crt</filename>, and <filename>root.crl</filename> |
| 1640 | + are only examined during server start; so you must restart |
| 1641 | + the server for changes in them to take effect. |
| 1642 | + </para> |
| 1643 | + |
| 1644 | + <sect2 id="ssl-certificate"> |
| 1645 | + <title>Creating a Self-Signed Certificate</title> |
| 1646 | + |
| 1647 | + <para> |
| 1648 | + To create a quick self-signed certificate for the server, use the |
| 1649 | + following <productname>OpenSSL</productname> command: |
1593 | 1650 | <programlisting> |
1594 | 1651 | openssl req -new -text -out server.req |
1595 | 1652 | </programlisting> |
1596 | | - Fill out the information that <application>openssl</> asks for. Make sure |
1597 | | - you enter the local host name as <quote>Common Name</>; the challenge |
1598 | | - password can be left blank. The program will generate a key that is |
1599 | | - passphrase protected; it will not accept a passphrase that is less |
1600 | | - than four characters long. To remove the passphrase (as you must if |
1601 | | - you want automatic start-up of the server), run the commands: |
| 1653 | +Fill out the information that <application>openssl</> asks for. Make sure |
| 1654 | +you enter the local host name as <quote>Common Name</>; the challenge |
| 1655 | +password can be left blank. The program will generate a key that is |
| 1656 | +passphrase protected; it will not accept a passphrase that is less |
| 1657 | +than four characters long. To remove the passphrase (as you must if |
| 1658 | +you want automatic start-up of the server), run the commands: |
1602 | 1659 | <programlisting> |
1603 | 1660 | openssl rsa -in privkey.pem -out server.key |
1604 | 1661 | rm privkey.pem |
1605 | 1662 | </programlisting> |
1606 | | - Enter the old passphrase to unlock the existing key. Now do: |
| 1663 | +Enter the old passphrase to unlock the existing key. Now do: |
1607 | 1664 | <programlisting> |
1608 | 1665 | openssl req -x509 -in server.req -text -key server.key -out server.crt |
1609 | 1666 | chmod og-rwx server.key |
1610 | 1667 | </programlisting> |
1611 | | - to turn the certificate into a self-signed certificate and to copy the |
1612 | | - key and certificate to where the server will look for them. |
1613 | | - </para> |
| 1668 | + to turn the certificate into a self-signed certificate and to copy |
| 1669 | + the key and certificate to where the server will look for them. |
| 1670 | + For more details on how to create your server private key and |
| 1671 | + certificate, refer to the <productname>OpenSSL</> documentation. |
| 1672 | + </para> |
1614 | 1673 |
|
1615 | | - <para> |
1616 | | - If verification of client certificates is required, place the |
1617 | | - certificates of the <acronym>CA</acronym>(s) you wish to check for in |
1618 | | - the file <filename>root.crt</filename> in the data directory. When |
1619 | | - present, a client certificate will be requested from the client |
1620 | | - during SSL connection startup, and it must have been signed by one of |
1621 | | - the certificates present in <filename>root.crt</filename>. (See <xref |
1622 | | - linkend="libpq-ssl"> for a description of how to set up client |
1623 | | - certificates.) Certificate Revocation List (CRL) entries are also |
1624 | | - checked if the file <filename>root.crl</filename> exists. |
1625 | | - </para> |
| 1674 | + <para> |
| 1675 | + A self-signed certificate can be used for testing, but a certificate |
| 1676 | + signed by a certificate authority (<acronym>CA</>) (either one of the |
| 1677 | + global <acronym>CAs</> or a local one) should be used in production |
| 1678 | + so the client can verify the server's identity. |
| 1679 | + </para> |
1626 | 1680 |
|
1627 | | - <para> |
1628 | | - When the <filename>root.crt</filename> file is not present, client |
1629 | | - certificates will not be requested or checked. In this mode, SSL |
1630 | | - provides communication security but not authentication. |
1631 | | - </para> |
| 1681 | + </sect2> |
1632 | 1682 |
|
1633 | | - <para> |
1634 | | - The files <filename>server.key</>, <filename>server.crt</>, |
1635 | | - <filename>root.crt</filename>, and <filename>root.crl</filename> |
1636 | | - are only examined during server start; so you must restart |
1637 | | - the server to make changes in them take effect. |
1638 | | - </para> |
1639 | 1683 | </sect1> |
1640 | 1684 |
|
1641 | 1685 | <sect1 id="ssh-tunnels"> |
|