.. _msencrypt:

*****************************************************************************
 msencrypt
*****************************************************************************


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:

::
  
    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]

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 :ref:`shp2img` utility!