[mapserver-commits] r7499 - trunk/docs/references/utilityreference

[svn at osgeo.org]

Author: jmckenna
Date: 2008-04-07 13:46:09 -0400 (Mon, 07 Apr 2008)
New Revision: 7499

Modified:
   trunk/docs/references/utilityreference/msencrypt.txt
Log:
update to include examples, from the MapServer User's Manual

Modified: trunk/docs/references/utilityreference/msencrypt.txt
===================================================================
--- trunk/docs/references/utilityreference/msencrypt.txt	2008-04-05 20:40:00 UTC (rev 7498)
+++ trunk/docs/references/utilityreference/msencrypt.txt	2008-04-07 17:46:09 UTC (rev 7499)
@@ -1,13 +1,110 @@
-:Purpose: Used to create an encryption key or to encrypt portions of connection strings for use in mapfiles (added in v4.10, see MS-RFC-18)
+:Purpose:
+  Used to create an encryption key or to encrypt portions of connection strings for 
+  use in mapfiles (added in v4.10) .  Typically you might want to encrypt portions of 
+  the CONNECTION parameter for a database connection.  The following CONNECTIONTYPEs 
+  are supported for using this encryption method:
+
+  ::
   
-:Syntax: 
+    OGR
+    Oracle Spatial
+    PostGIS
+    SDE
 
+:Syntax:
   To create a new encryption key:
-  :: 
-
+  
+  ::
+  
     msencrypt -keygen [key_filename]
-
+    
   To encrypt a string:
+  
   ::
+  
+    msencrypt -key [key_filename] [string_to_encrypt]
 
-    msencrypt -key [key_filename] [string_to_encrypt]
+:Use in Mapfile:
+  The location of the encryption key can be specified by two mechanisms, either by 
+  setting the environment variable MS_ENCRYPTION_KEY or using a CONFIG directive 
+  in the MAP object of your mapfile.  For example: 
+  
+  ::
+  
+	CONFIG MS_ENCRYPTION_KEY "/path/to/mykey.txt"
+	
+  Use the { and } characters as delimiters for encrypted strings inside database 
+  CONNECTIONs in your mapfile.  For example: 
+  
+  ::
+  
+	CONNECTIONTYPE ORACLESPATIAL
+	CONNECTION "user/{MIIBugIBAAKBgQCP0Yj+Seh8==}@service"
+	
+:Example:
+  (note: the following PostGIS example requires at least MapServer 5.0.3 or 5.2)  
+  Let's say we have a LAYER that uses a POSTGIS connection as follows:
+  
+  ::
+  
+    LAYER
+      NAME "provinces"
+      TYPE POLYGON
+      CONNECTIONTYPE POSTGIS
+      CONNECTION "host=127.0.0.1 dbname=gmap user=postgres password=iluvyou18 port=5432"
+      DATA "the_geom FROM province using SRID=42304"
+      STATUS DEFAULT
+      CLASS
+        NAME "Countries"
+        COLOR 255 0 0
+      END
+    END
+    
+  Here are the steps to encrypt the password in the above connection:
+  
+  1.Generate an encryption key (note that this key should not be stored anywhere within 
+    your web server's accessible directories):
+   
+    ::
+    
+      msencrypt -keygen "E:\temp\mykey.txt"
+
+    And this generated key file might contain something like: 
+    
+    ::
+    
+      2137FEFDB5611448738D9FBB1DC59055
+      
+  2.Encrypt the connection's password using that generated key:
+
+    ::
+    
+      msencrypt -key "E:\temp\mykey.txt" "iluvyou18"
+
+    Which returns the password encrypted, at the commandline (you'll 
+    use it in a second):
+
+    ::
+    
+      3656026A23DBAFC04C402EDFAB7CE714
+
+  3.Edit the mapfile to make sure the 'mykey.txt' can be found, using the 
+    "MS_ENCRYPTION_KEY" environment variable.  The CONFIG parameter inside the 
+    MAP object can be used to set an environment variable inside a mapfile:
+
+    ::
+    
+      MAP
+        ...
+        CONFIG "MS_ENCRYPTION_KEY" "E:/temp/mykey.txt"
+        ...
+      END #mapfile
+      
+  4.Modify the layer's CONNECTION to use the generated password key, 
+    making sure to use the “{}” brackets around the key:
+    
+    ::
+    
+      CONNECTION "host=127.0.0.1 dbname=gmap user=postgres password={3656026A23DBAFC04C402EDFAB7CE714} port=5432"
+ 
+  5.Done!  Give your new encrypted mapfile a try with the shp2img utility!