Skip to content

Commit 89517a2

Browse files
bmomjianbmomjian
committed
Improve wording of new documentation section on encryption, and move it
a few sections up.
1 parent 1580f6c commit 89517a2

File tree

1 file changed

+156
-127
lines changed

1 file changed

+156
-127
lines changed

‎doc/src/sgml/runtime.sgml

Lines changed: 156 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.316 2005/05/08 03:29:06 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.317 2005/05/09 17:13:04 momjian Exp $
33
-->
44

55
<chapter Id="runtime">
@@ -4954,6 +4954,161 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
49544954
</important>
49554955
</sect1>
49564956

4957+
<sect1 id="encryption-approaches">
4958+
<title>Use of Encryption in <productname>PostgreSQL</productname></title>
4959+
4960+
<indexterm zone="encryption-approaches">
4961+
<primary>encryption</primary>
4962+
</indexterm>
4963+
4964+
<para>
4965+
<productname>PostgreSQL</productname> offers encryption at several
4966+
levels, and provides flexibility in protecting data from disclosure
4967+
due to database server theft, unscrupulous administrators, and
4968+
insecure networks. Encryption might also be required by government
4969+
regulation, for example, for medical records or financial
4970+
transactions.
4971+
</para>
4972+
4973+
<variablelist>
4974+
4975+
<varlistentry>
4976+
<term>Password Storage Encryption</term>
4977+
<listitem>
4978+
4979+
<para>
4980+
By default, database user passwords are stored as MD5 hashes, so
4981+
the administrator can not determine the actual password assigned
4982+
to the user. If MD5 encryption is used for client authentication,
4983+
the unencrypted password is never even temporarily present on the
4984+
server because the client MD5 encrypts it before being sent across
4985+
the network. MD5 is a one-way encryption --- there is no
4986+
decryption algorithm.
4987+
</para>
4988+
</listitem>
4989+
</varlistentry>
4990+
4991+
<varlistentry>
4992+
<term>Encryption For Specific Columns</term>
4993+
4994+
<listitem>
4995+
<para>
4996+
The <filename>/contrib</> function library
4997+
<function>pgcrypto</function> allows certain fields to be stored
4998+
encrypted. This is useful if only some of the data is sensitive.
4999+
The client supplies the decryption key and the data is decrypted
5000+
on the server and then sent to the client.
5001+
</para>
5002+
5003+
<para>
5004+
The decrypted data and the decryption key are present on the
5005+
server for a brief time while it is being decrypted and
5006+
communicated between the client and server. This presents a brief
5007+
moment where the data and keys can be intercepted by someone with
5008+
complete access to the database server, such as the system
5009+
administrator.
5010+
</para>
5011+
</listitem>
5012+
</varlistentry>
5013+
5014+
<varlistentry>
5015+
<term>Data Partition Encryption</term>
5016+
5017+
<listitem>
5018+
<para>
5019+
On Linux, encryption can be layered on top of a filesystem mount
5020+
using a <quote>loopback device</quote>. This allows an entire
5021+
filesystem partition be encrypted on disk, and decrypted by the
5022+
operating system. On FreeBSD, the equivalent facility is called
5023+
GEOM Based Disk Encryption, or <acronym>gbde</acronym>.
5024+
</para>
5025+
5026+
<para>
5027+
This mechanism prevents unecrypted data from being read from the
5028+
drives if the drives or the entire computer is stolen. This
5029+
mechanism does nothing to protect against attacks while the
5030+
filesystem is mounted, because when mounted, the operating system
5031+
provides a unencrypted view of the data. However, to mount the
5032+
filesystem, you need some way for the encryption key to be passed
5033+
to the operating system, and sometimes the key is stored somewhere
5034+
on the host that mounts the disk.
5035+
</para>
5036+
</listitem>
5037+
</varlistentry>
5038+
5039+
<varlistentry>
5040+
<term>Encrypting Passwords Across A Network</term>
5041+
5042+
<listitem>
5043+
<para>
5044+
The <literal>MD5</> authentication method double-encrypts the
5045+
password on the client before sending it to the server. It first
5046+
MD5 encrypts it based on the user name, and then encrypts it
5047+
based on a random salt sent by the server when the database
5048+
connection was made. It is this double-encrypted value that is
5049+
sent over the network to the server. Double-encryption not only
5050+
prevents the password from being discovered, it also prevents
5051+
another connection from replaying the same double-encryption
5052+
value in a later connection.
5053+
</para>
5054+
</listitem>
5055+
</varlistentry>
5056+
5057+
<varlistentry>
5058+
<term>Encrypting Data Across A Network</term>
5059+
5060+
<listitem>
5061+
<para>
5062+
SSL connections encrypt all data sent across the network: the
5063+
password, the queries, and the data returned. The
5064+
<filename>pg_hba.conf</> file allows administrators to specify
5065+
which hosts can use non-encrypted connections (<literal>host</>)
5066+
and which require SSL-encrypted connections
5067+
(<literal>hostssl</>). Also, clients can specify that they
5068+
connect to servers only via SSL. <application>Stunnel</> or
5069+
<application>SSH</> can also be used to encrypt transmissions.
5070+
</para>
5071+
</listitem>
5072+
</varlistentry>
5073+
5074+
<varlistentry>
5075+
<term>SSL Host Authentication</term>
5076+
5077+
<listitem>
5078+
<para>
5079+
It is possible for both the client and server to provide SSL keys
5080+
or certificates to each other. It takes some extra configuration
5081+
on each side, but this provides stronger verification of identity
5082+
than the mere use of passwords. It prevent a computer from
5083+
pretending to be the server just long enough to read the password
5084+
send by the client. It also helps prevent 'man in the middle"
5085+
attacks where a computer between the client and server pretends to
5086+
be the server and reads and passes all data between the client and
5087+
server.
5088+
</para>
5089+
</listitem>
5090+
</varlistentry>
5091+
5092+
<varlistentry>
5093+
<term>Client-Side Encryption</term>
5094+
5095+
<listitem>
5096+
<para>
5097+
If the system administrator can not be trusted, it is necessary
5098+
for the client to encrypt the data; this way, unencrypted data
5099+
never appears on the database server. Data is encrypted on the
5100+
client before being sent to the server, and database results have
5101+
to be decrypted on the client before being used. Peter Wayner's
5102+
book, <citation>Translucent Databases</citation>, discusses how to
5103+
do this in considerable detail.
5104+
</para>
5105+
</listitem>
5106+
</varlistentry>
5107+
5108+
</variablelist>
5109+
5110+
</sect1>
5111+
49575112
<sect1 id="ssl-tcp">
49585113
<title>Secure TCP/IP Connections with SSL</title>
49595114

@@ -5109,132 +5264,6 @@ psql -h localhost -p 3333 template1
51095264

51105265
</sect1>
51115266

5112-
<sect1 id="encryption-approaches">
5113-
<title>Use of Encryption in <productname>PostgreSQL</productname></title>
5114-
<indexterm zone="encryption-approaches">
5115-
<primary>encryption</primary>
5116-
</indexterm>
5117-
5118-
<para> There is increasing interest in having verifiable mechanisms
5119-
to maintain the privacy of data in databases. In the United
5120-
States, legislation called <acronym>HIPAA</acronym> (Health
5121-
Insurance Portability and Accountability Act) requires that
5122-
personal health information is handled securely. The European
5123-
Union has similarly been developing directives as to how personal
5124-
data is to be managed there.</para>
5125-
5126-
<para> Questions frequently come up as to what functionality
5127-
<productname>PostgreSQL</productname> offers with regard to
5128-
supporting the use of data encryption. It uses and provides use of
5129-
encryption tools in several ways that may be useful to provide
5130-
protection against certain classes of attacks.</para>
5131-
5132-
<itemizedlist>
5133-
5134-
<listitem><para> Passwords stored in MD5 form </para>
5135-
5136-
<para> Passwords are normally not stored in
5137-
<quote>plaintext</quote> form in the database; they are hashed
5138-
using the built-in MD5 function, and <emphasis>that</emphasis> is
5139-
what is stored in the database. </para>
5140-
5141-
<programlisting>
5142-
sample=# alter user foo password 'some dumb value';
5143-
ALTER USER
5144-
sample=# select usename, passwd from pg_shadow where usename = 'foo';
5145-
usename | passwd
5146-
---------+-------------------------------------
5147-
foo | md5740daa4aaa084d85eb97648084a43bbb
5148-
(1 row)
5149-
</programlisting>
5150-
5151-
</listitem>
5152-
5153-
<listitem><para> Connections protected using SSL</para>
5154-
5155-
<para> There are various options to control how mandatory it is
5156-
to use SSL to protect data connections. At the most
5157-
<quote>paranoid</quote> end of the spectrum, you can configure
5158-
<filename>pg_hba.conf</filename> to have the database reject
5159-
connections that do <emphasis>not</emphasis> come in via
5160-
SSL.</para>
5161-
5162-
<para> The use of SSL, alone, is useful for protecting
5163-
communications against interception. It may not be necessary
5164-
for connections that take place across a carefully controlled
5165-
network; if connections are coming in from less controlled
5166-
sources, its use is highly recommended.</para></listitem>
5167-
5168-
<listitem><para> Connections authenticated using SSL</para>
5169-
5170-
<para> It is possible for both the client and server to provide
5171-
to one another SSL keys or certificates. It takes some extra
5172-
configuration on each side where these are used, but this likely
5173-
provides stronger verification of identity than the mere use of a
5174-
text password. </para></listitem>
5175-
5176-
<listitem><para> Using OS level encryption for entire database
5177-
partitions</para>
5178-
5179-
<para> On Linux, encryption can be layered on top of a filesystem
5180-
mount using what is called a <quote>loopback device;</quote> this
5181-
permits having a whole filesystem partition be encrypted on disk,
5182-
decrypted by the operating system. On FreeBSD, the equivalent
5183-
facility is called GEOM Based Disk Encryption, or
5184-
<acronym>gbde</acronym>.</para>
5185-
5186-
<para> This mechanism may be expected to be useful for protecting
5187-
against the threat that someone might pull disk drives out and
5188-
try to install them somewhere else to draw data off of them.
5189-
</para>
5190-
5191-
<para> In contrast, this mechanism does nothing to protect
5192-
against attacks when the filesystem is mounted, because when
5193-
mounted, the OS provides a <quote>view</quote> of the filesystem
5194-
accessible in plain text form. Furthermore, you need some way
5195-
for the encryption key to be passed to the operating system in
5196-
order to mount the filesystems, which encourages having the key
5197-
accessible somewhere on the host that mounts the disk.
5198-
</para></listitem>
5199-
5200-
<listitem><para> Using the contrib function library
5201-
<function>pgcrypto</function> so the database engine manages
5202-
encryption of certain fields.</para>
5203-
5204-
<para>If much of the data can be in plain text form, and only a
5205-
subset is particularly sensitive, this mechanism supports
5206-
treating them differently. The encrypted data is only ever
5207-
presented in <quote>unencrypted</quote> form while it is being
5208-
communicated between client and server, and the use of an SSL
5209-
layer of <quote>superencryption</quote> alleviates that
5210-
problem.</para>
5211-
5212-
<para> Unfortunately, in this approach, the encryption keys need
5213-
to be present on the server, even if only for a moment, which
5214-
presents the possibility of them being intercepted by someone
5215-
with access to the database server. As a result, this mechanism
5216-
is not suitable for storage of data that is too sensitive for
5217-
system administrators to have access to it. </para></listitem>
5218-
5219-
<listitem><para> Using cryptographic tools on the client </para>
5220-
5221-
<para> If it is not safe to trust the system administrators at
5222-
least somewhat, you may find it necessary to encrypt data at the
5223-
client level such that unencrypted data never appears on the
5224-
database server. This sort of <quote>paranoia</quote> is quite
5225-
appropriate for applications where it would be damaging for data
5226-
to be seen by inappropriate readers that might generally be
5227-
considered trustworthy, as can be the case with
5228-
medical and legal records.</para>
5229-
5230-
<para> Peter Wayner's book, <citation>Translucent
5231-
Databases</citation>, discusses how to do this in considerable
5232-
detail.</para></listitem>
5233-
5234-
</itemizedlist>
5235-
5236-
</sect1>
5237-
52385267
</chapter>
52395268

52405269
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)