Improve wording of new documentation section on encryption, and move it
authorBruce Momjian
Mon, 9 May 2005 17:13:04 +0000 (17:13 +0000)
committerBruce Momjian
Mon, 9 May 2005 17:13:04 +0000 (17:13 +0000)
a few sections up.

doc/src/sgml/runtime.sgml

index 2677b8272dec608ca76407e191dcd4025f1b0209..11274a35bcafa0cdd815595e58404b0357e3c2d8 100644 (file)
@@ -1,5 +1,5 @@
 
 
 
@@ -4954,6 +4954,161 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
    
  
 
+  Use of Encryption in <productname>PostgreSQL</productname>
+
+  
+   encryption
+  
+
+  
+   PostgreSQL offers encryption at several
+   levels, and provides flexibility in protecting data from disclosure
+   due to database server theft, unscrupulous administrators, and
+   insecure networks. Encryption might also be required by government
+   regulation, for example, for medical records or financial
+   transactions.
+  
+   
+  
+
+  
+   Password Storage Encryption
+   
+
+    
+     By default, database user passwords are stored as MD5 hashes, so
+     the administrator can not determine the actual password assigned
+     to the user. If MD5 encryption is used for client authentication,
+     the unencrypted password is never even temporarily present on the
+     server because the client MD5 encrypts it before being sent across
+     the network. MD5 is a one-way encryption --- there is no
+     decryption algorithm.
+    
+   
+  
+
+  
+   Encryption For Specific Columns
+
+   
+    
+     The /contrib function library
+     pgcrypto allows certain fields to be stored
+     encrypted. This is useful if only some of the data is sensitive.
+     The client supplies the decryption key and the data is decrypted
+     on the server and then sent to the client.
+    
+     
+    
+     The decrypted data and the decryption key are present on the
+     server for a brief time while it is being decrypted and
+     communicated between the client and server. This presents a brief
+     moment where the data and keys can be intercepted by someone with
+     complete access to the database server, such as the system
+     administrator.
+    
+   
+  
+
+  
+   Data Partition Encryption
+
+   
+    
+     On Linux, encryption can be layered on top of a filesystem mount
+     using a loopback device. This allows an entire
+     filesystem partition be encrypted on disk, and decrypted by the
+     operating system. On FreeBSD, the equivalent facility is called
+     GEOM Based Disk Encryption, or gbde.
+    
+
+    
+     This mechanism prevents unecrypted data from being read from the
+     drives if the drives or the entire computer is stolen. This
+     mechanism does nothing to protect against attacks while the
+     filesystem is mounted, because when mounted, the operating system
+     provides a unencrypted view of the data. However, to mount the
+     filesystem, you need some way for the encryption key to be passed
+     to the operating system, and sometimes the key is stored somewhere
+     on the host that mounts the disk.
+    
+   
+  
+
+  
+   Encrypting Passwords Across A Network
+
+   
+     
+      The MD5 authentication method double-encrypts the
+      password on the client before sending it to the server. It first
+      MD5 encrypts it based on the user name, and then encrypts it
+      based on a random salt sent by the server when the database
+      connection was made. It is this double-encrypted value that is
+      sent over the network to the server. Double-encryption not only
+      prevents the password from being discovered, it also prevents
+      another connection from replaying the same double-encryption
+      value in a later connection.
+     
+    
+  
+
+  
+   Encrypting Data Across A Network
+
+    
+     
+      SSL connections encrypt all data sent across the network: the
+      password, the queries, and the data returned. The
+      pg_hba.conf file allows administrators to specify
+      which hosts can use non-encrypted connections (host)
+      and which require SSL-encrypted connections
+      (hostssl). Also, clients can specify that they
+      connect to servers only via SSL. Stunnel or
+      SSH can also be used to encrypt transmissions.
+     
+    
+  
+
+  
+   SSL Host Authentication
+
+   
+     
+     It is possible for both the client and server to provide SSL keys
+     or certificates to each other. It takes some extra configuration
+     on each side, but this provides stronger verification of identity
+     than the mere use of passwords. It prevent a computer from
+     pretending to be the server just long enough to read the password
+     send by the client. It also helps prevent 'man in the middle"
+     attacks where a computer between the client and server pretends to
+     be the server and reads and passes all data between the client and
+     server.
+    
+   
+  
+
+  
+   Client-Side Encryption
+
+   
+    
+     If the system administrator can not be trusted, it is necessary
+     for the client to encrypt the data; this way, unencrypted data
+     never appears on the database server. Data is encrypted on the
+     client before being sent to the server, and database results have
+     to be decrypted on the client before being used. Peter Wayner's
+     book, Translucent Databases, discusses how to
+     do this in considerable detail.
+    
+   
+  
+
+  
+
+
  
   Secure TCP/IP Connections with SSL
 
@@ -5109,132 +5264,6 @@ psql -h localhost -p 3333 template1
 
  
 
-   Use of Encryption in <productname>PostgreSQL</productname>
-   
-    encryption
-   
-
-    There is increasing interest in having verifiable mechanisms
-    to maintain the privacy of data in databases.  In the United
-    States, legislation called HIPAA (Health
-    Insurance Portability and Accountability Act) requires that
-    personal health information is handled securely.  The European
-    Union has similarly been developing directives as to how personal
-    data is to be managed there.
-   
-    Questions frequently come up as to what functionality
-    PostgreSQL offers with regard to
-    supporting the use of data encryption.  It uses and provides use of
-    encryption tools in several ways that may be useful to provide
-    protection against certain classes of attacks.
-   
-   
-
-     Passwords stored in MD5 form 
-
-      Passwords are normally not stored in
-      plaintext form in the database; they are hashed
-      using the built-in MD5 function, and that is
-      what is stored in the database.  
-     
-
-sample=# alter user foo password 'some dumb value';
-ALTER USER
-sample=# select usename, passwd from pg_shadow where usename = 'foo';
- usename |               passwd                
----------+-------------------------------------
- foo     | md5740daa4aaa084d85eb97648084a43bbb
-(1 row)
-
-
-
-
-     Connections protected using SSL
-
-       There are various options to control how mandatory it is
-      to use SSL to protect data connections.  At the most
-      paranoid end of the spectrum, you can configure
-      pg_hba.conf to have the database reject
-      connections that do not come in via
-      SSL.
-
-       The use of SSL, alone, is useful for protecting
-      communications against interception.  It may not be necessary
-      for connections that take place across a carefully controlled
-      network; if connections are coming in from less controlled
-      sources, its use is highly recommended.
-
-     Connections authenticated using SSL
-
-      It is possible for both the client and server to provide
-      to one another SSL keys or certificates.  It takes some extra
-      configuration on each side where these are used, but this likely
-      provides stronger verification of identity than the mere use of a
-      text password. 
-
-     Using OS level encryption for entire database
-      partitions
-
-      On Linux, encryption can be layered on top of a filesystem
-      mount using what is called a loopback device; this
-      permits having a whole filesystem partition be encrypted on disk,
-      decrypted by the operating system.  On FreeBSD, the equivalent
-      facility is called GEOM Based Disk Encryption, or
-      gbde.
-
-      This mechanism may be expected to be useful for protecting
-      against the threat that someone might pull disk drives out and
-      try to install them somewhere else to draw data off of them.
-     
-
-      In contrast, this mechanism does nothing to protect
-      against attacks when the filesystem is mounted, because when
-      mounted, the OS provides a view of the filesystem
-      accessible in plain text form.  Furthermore, you need some way
-      for the encryption key to be passed to the operating system in
-      order to mount the filesystems, which encourages having the key
-      accessible somewhere on the host that mounts the disk.
-     
-
-     Using the contrib function library
-      pgcrypto so the database engine manages
-      encryption of certain fields.
-
-     If much of the data can be in plain text form, and only a
-      subset is particularly sensitive, this mechanism supports
-      treating them differently.  The encrypted data is only ever
-      presented in unencrypted form while it is being
-      communicated between client and server, and the use of an SSL
-      layer of superencryption alleviates that
-      problem.
-     
-      Unfortunately, in this approach, the encryption keys need
-      to be present on the server, even if only for a moment, which
-      presents the possibility of them being intercepted by someone
-      with access to the database server.  As a result, this mechanism
-      is not suitable for storage of data that is too sensitive for
-      system administrators to have access to it. 
-
-     Using cryptographic tools on the client 
-
-      If it is not safe to trust the system administrators at
-      least somewhat, you may find it necessary to encrypt data at the
-      client level such that unencrypted data never appears on the
-      database server.  This sort of paranoia is quite
-      appropriate for applications where it would be damaging for data
-      to be seen by inappropriate readers that might generally be
-      considered trustworthy, as can be the case with
-      medical and legal records.
-
-      Peter Wayner's book, Translucent
-       Databases, discusses how to do this in considerable
-      detail.
-
-   
-
-  
-