==============================================================================
 __        ______ .___  ___.      ___      .______     _______.        
|  |      /      ||   \/   |     /   \     |   _  \   /       |        
|  |     |  ,----'|  \  /  |    /  ^  \    |  |_)  | |   (----` ______ 
|  |     |  |     |  |\/|  |   /  /_\  \   |   ___/   \   \    |______|
|  `----.|  `----.|  |  |  |  /  _____  \  |  |   .----)   |           
|_______| \______||__|  |__| /__/     \__\ | _|   |_______/            
                                                                       
.______       _______     _______.___________.
|   _  \     |   ____|   /       |           |
|  |_)  |    |  |__     |   (----`---|  |----`
|      /     |   __|     \   \       |  |     
|  |\  \----.|  |____.----)   |      |  |     
| _| `._____||_______|_______/       |__|     
                                              

==============================================================================


Description:    a REST-API to LCMAPS
Author:         Oscar Koeroo, okoeroo at gmail () com
LICENCE:        Apache 2 licence

Purpose:        Provide Unix account mappings based on input credentials
                Currently LCMAPS is focussed on X.509 based credentials, 
                including RFC3820 and old-style proxy certificates.

Run-modes:
    Full SSL    :   Push the credentials to map in LCMAPS through SSL
    SSL+HTTP    :   Connect with SSL, push credentials in the HTTP headers
    HTTP        :   Push credentials with HTTP headers

Dependencies:
    libevhtp    :   https://github.com/ellzey/libevhtp
                    requires: libevent2, OpenSSL
    lcmaps      :   http://software.nikhef.nl/security/lcmaps/
                    requires: OpenSSL, and
                              Globus - http://www.globus.org
                              VOMS API - See EMI website for details
                    More info: http://www.nikhef.nl/pub/projects/grid/gridwiki/index.php/LCMAPS

Listening:
    8443 - The Full SSL-based interfaces listen on port 8443
        The expected input is a client certificate (chain) will feature classic
        and RFC3820 proxy certificate support.
    7443 - The session SSL-based interfaces listen on port 7443
        The expected input is the same as the plain-HTTP interfaces, being REST
        based using the query featured name/value pairs.
    8008 - The plain-HTTP (unsecured, but fast) interfaces listen on port 8008
        The expected input is REST based, meaning that the query featured
        name/value pairs are used for input. See below for details.
        
URI:
    https://localhost:8443/lcmaps/mapping/ssl
    https://localhost:7443/lcmaps/mapping/rest
    http://localhost:8008/lcmaps/mapping/rest

Queries for all URI:
    ?format=json        :   Mapping output in JSON 
                            (JSON is the default when absent)
    ?format=xml         :   Mapping output in XML
    ?format=html        :   Mapping output in HTML
    
Queries specific to the "/lcmaps/mapping/rest" URI:
    ?subjectdn=<value>  :   URL encoded (X.509) Subject DN.
    ?fqan=<value>       :   URL encoded VOMS FQANs.
                            Note: Add FQANs multiple times for mulitple group
                                  and role affiliations.
                            FQANs MUST be combined with a subjectdn=

Example input (based on certificates):
#using a certificate
curl \
    --capath /etc/grid-security/certificates/ \
    --cert `pwd`/.globus/terena/terena-cert.pem \
    --key `pwd`/.globus/terena/terena-key.pem \
    https://localhost:8443/lcmaps/mapping/ssl

#using a proxy certificate
curl \
    --capath /etc/grid-security/certificates/ \
    --cacert `pwd`/.globus/terena/terena-key.pem \
    --cert /tmp/x509up_u501 \
    --key /tmp/x509up_u501 \
    https://localhost:8443/lcmaps/mapping/ssl


JSON output:
    Content-Type: application/json
    Sample output JSON:
        {"lcmaps": {
            "mapping": {
                "posix": {
                    "uid": { "id": 501 },
                    "pgid": { "id": 501 },
                    "sgid": [
                        { "id": 31 },
                        { "id": 32 },
                        { "id": 79 },
                        { "id": 80 },
                        { "id": 81 },
                        { "id": 402 },
                        { "id": 403 },
                        { "id": 507 }
                            ]
                    }
                }
            }
        }

XML output:
    Content-Type: text/xml
    Sample output XML:
        <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
        <lcmaps>
          <mapping>
            <posix>
              <uid>
                <id>501</id>
              </uid>
              <pgid>
                <id>501</id>
              </pgid>
              <sgid>
                <array>
                  <id>31</id>
                  <id>32</id>
                  <id>79</id>
                  <id>80</id>
                  <id>81</id>
                  <id>402</id>
                  <id>403</id>
                  <id>507</id>
                </array>
              </sgid>
            </posix>
          </mapping>
        </lcmaps>

HTML output:
    Content-Type: text/html
    Sample output HTML (tentative to change):
        <html><body>
        uid: 501<br>
        gid: 501<br>
        secondary gid: 31<br>
        secondary gid: 32<br>
        secondary gid: 79<br>
        secondary gid: 80<br>
        secondary gid: 81<br>
        secondary gid: 402<br>
        secondary gid: 403<br>
        secondary gid: 507<br>
        </body></html>

To do:
    Proxy certificate support:
        Accept classic proxy certificates and RFC3820 certificates for
        authentication and as input to LCMAPS from the SSL handshake on the
        Full SSL URI.
    Add VOMS attribute parsing:
        The VOMS attributes can be encoded in the URI. This needs to be parsed
        and feed to the LCMAPS interface as input for a VOMS specific mapping
        decision.  Note: the Full SSL interfaces already features VOMS AC
        support.
    Full SSL + REST for Multi User Pilot Job use case:
        Combining the Full SSL interface with the REST based interface to
        support Multi User Pilot Job use cases in wLCG projects.