From 8daa158b1e2edfc056f3b0167cf8eff96a202251 Mon Sep 17 00:00:00 2001
From: Francesco Giacomini <giaco at cnaf dot infn dot it>
Date: Fri, 16 Mar 2018 13:32:46 +0100
Subject: [PATCH] document embedded variables

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 41 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 4c9d1db..57eb1ff 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,9 @@
 
 ## Description
 
-_ngx_http_voms_module_ is a module for the [NGINX web server](https://www.nginx.org/) that enables client-side authentication based on X.509 proxies augmented with Attribute Certificates, typically obtained through a [Virtual Organization Membership Service](https://italiangrid.github.io/voms/) (VOMS).
+_ngx_http_voms_module_ is a module for the [Nginx web server](https://www.nginx.org/) that enables client-side authentication based on X.509 proxies augmented with Attribute Certificates, typically obtained through a [Virtual Organization Membership Service](https://italiangrid.github.io/voms/) (VOMS).
+
+The module defines a set of [_embedded_ variables](~embedded-variables), whose values are extracted from the first Attribute Certificate found in the certificate chain.
 
 ## Installation
 
@@ -19,53 +21,75 @@ A Docker image is available for use in the context of the StoRM2 project, where
     % ./configure ${resty_config_options} --add-module=../ngx_http_voms_module
     % make && make install
 
-## Variables
-
-The module makes the following variables available for use in an NGINX configuration file:
+## Embedded Variables
 
-### voms_fqans
-
-A comma-separated list of _Fully Qualified Attribute Names_
+The module makes the following embedded variables available for use in an Nginx configuration file:
 
 ### voms_user
 
-user DN
+The Subject of the End-Entity certificate, used to sign the proxy.
+
+_Example_: ``/C=IT/O=IGI/CN=test0``
 
 ### voms_user_ca
 
-user CA
+The Issuer (Certificate Authority) of the End-Entity certificate.
+
+_Example_: ``/C=IT/O=IGI/CN=Test CA``
+
+### voms_fqans
+
+A comma-separated list of Fully Qualified Attribute Names. See [The VOMS Attribute Certificate Format](http://ogf.org/documents/GFD.182.pdf) for more details.
+
+_Example_: ``/test/exp1,/test/exp2,/test/exp3/Role=PIPPO``
 
 ### voms_server
 
-server DN
+The Subject of the VOMS server certificate, used to sign the Attribute Certificate.
+
+_Example_: ``/C=IT/O=IGI/CN=voms.example``
 
 ### voms_server_ca
 
-server CA
+The Issuer (Certificate Authority) of the VOMS server certificate.
+
+_Example_: ``/C=IT/O=IGI/CN=Test CA``
 
 ### voms_vo
 
-VO name
+The name of the Virtual Organization (VO) to which the End Entity belongs.
+
+_Example_: ``test.vo``
 
 ### voms_server_uri
 
-VOMS server URI
+The hostname and port of the VOMS network service that issued the Attribute Certificate, in the form _hostname_ :_port_.
+
+_Example_: ``voms.example:15000``
 
 ### voms_not_before
 
-not-before
+The date before which the Attribute Certificate is not yet valid, in the form _YYYYMMDDhhmmss_ ``Z``.
+
+_Example_: ``20180101000000Z``
 
 ### voms_not_after
 
-not-after
+The date after which the Attribute Certificate is not valid anymore, in the form _YYYYMMDDhhmmss_ ``Z``.
+
+_Example_: ``20180101120000Z``
 
 ### voms_generic_attributes
 
-generic attributes
+A comma-separated list of attributes, each defined by three properties and formatted as ``n=``_name_ ``v=``_value_ ``q=``_qualifier_. The qualifier typically coincides with the name of the VO.
+
+_Example_: ``n=nickname v=newland q=test.vo,n=nickname v=giaco q=test.vo``
 
 ### voms_serial
 
-serial number
+The serial number of the Attribute Certificate in hexadecimal format.
+
+_Example_: ``7B``
 
 ## Testing
 
-- 
GitLab