.. index::
   pair: Utility; msencrypt
    
.. index::
   single: Encryption key
    
.. index::
   single: Encrypting
    
.. _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!
