Changes between Version 4 and Version 5 of CredPrinterDocs


Ignore:
Timestamp:
May 24, 2011 10:33:47 AM (10 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CredPrinterDocs

    v4 v5  
    33The ''credential printer'' service is an XMLRPC service to convert [WikiStart ABAC] credentials encoded as X.509 certificates into a text format.  While [WikiStart libabac] is widely portable through swig, some programming environments cannot import the library, yet would like to see the contents of credentials.  The credential printer provides access.
    44
    5 == Installing the service ==
     5== The example code ==
     6
     7=== Installing the service ===
    68
    79We distribute the credential printer as a python application.  It depends on the standard installation and the M2Crypto package, available from several places.  It also depends on [source:doc/INSTALL libabac].
     
    2426}}}
    2527
    26 == Running the server ==
     28=== Running the server ===
    2729
    2830The server takes an optional argument, {{{--cert}}} and a certificate with which to identify itself under SSL/https.  If omitted, the server will run under http, unencrypted and unauthenticated.  If run under SSL, the server expects clients to supply a certificate, but does not vaildate it's authorization chain.  This is for future expansion using ABAC authorization to the server and self-certifying identities.  The directions for [http://fedd.deterlab.net/wiki/FeddConfig#MakingaFedidCertificate making a fedid certificate] will also create a valid certificate for this use.
     
    5658starts the server under http on port 13232.
    5759
    58 == Running the client ==
     60=== Running the client ===
    5961
    6062The client is primarily to demonstrate the server functionality, but may prove useful itself.  It takes 2 optional parameters and a list of filenames, and prints the decoded credentials on the standard output.
     
    102104
    103105
     106== The Interface ==
     107
     108The server expects an XMLRPC array of XMLRPC structs containing the credentials to represent.  In the input, each struct has two fields:
     109
     110 '''id'''::
     111  a string used to map from input to output credentials
     112 '''credential'''::
     113  a Binary object holding the credential bits
     114
     115The ids are free form strings used to map the input to the output.  The credential bits are also returned, but matching ids can be easier.  {{{cred_client.py}} uses 3 digit serial numbers (the first line of the output), but an application can use any unique identifier.  In fact, the server never confirms their uniqueness, but matching input to output can be tricky without it.
     116
     117The server validates and translates the credentials into text and returns them in a more complex array of structs.  Notice that the credentials must be validated.  To decode an attribute certificate, the identity credential of the issuer must be included in the request.
     118
     119The output is an array of structs with the following members:
     120
     121 '''id'''::
     122  a string used to map from input to output credentials (identical to input)
     123 '''credential'''::
     124  a Binary object holding the credential bits (identical to input)
     125 '''type'''::
     126  a string indicating what the credential encodes.  Will be one of be "identity", "attribute", or "unknown".
     127 '''str'''::
     128  a string, the representation of the attribute or identity in terms of keyids
     129 '''auxstr'''::
     130    a string, the representation of the attribute or identity in terms of hunam-readable names (CNs).  If CNs are missing or unresolvable, the keyids will be used.
     131 '''errcode'''::
     132    an integer, the [source:doc/API libabac return code] of the attempted conversion.  If this is non-zero, the '''str''' and '''auxstr''' contents are undefined.  ({{{cred_server.py}}} sets them to the empty string, but do not rely on that.)
     133
     134The output array is ''not'' guaranteed to be in the same order as the input array (and generally will not be).  Use the '''id''' member to match input and output.
     135
     136Just for concreteness, here is the python encoding for a simple request and response:
     137
     138Request
     139{{{
     140[
     141   {'credential': <xmlrpclib.Binary instance at 0x28b3dacc>, 'id': '000'},
     142   {'credential': <xmlrpclib.Binary instance at 0x28b3db6c>, 'id': '001'},
     143   {'credential': <xmlrpclib.Binary instance at 0x28b3db4c>, 'id': '002'}
     144]
     145}}}
     146
     147Three dicts/structs are encoded with a serial number as id and the binary of the credential.
     148
     149Response
     150{{{
     151[
     152   {'credential': <xmlrpclib.Binary instance at 0x28b3dacc>, 'errcode': 0, 'auxstr': 'Acme', 'str': '9b47d3669b99a4ce1d3a0055be002ea6a580041a', 'type': 'identity', 'id': '000'},
     153   {'credential': <xmlrpclib.Binary instance at 0x28b3db6c>, 'errcode': 0, 'auxstr': 'Acme.partner <- f923e9f69d33b52d8bbdfd19f2ec89dde7beedd7', 'str': '9b47d3669b99a4ce1d3a0055be002ea6a580041a.partner <- f923e9f69d33b52d8bbdfd19f2ec89dde7beedd7', 'type': 'attribute', 'id': '001'},
     154   {'credential': <xmlrpclib.Binary instance at 0x28b3db4c>, 'errcode': -1, 'auxstr': '', 'str': '', 'type': 'unknown', 'id': '002'}
     155]
     156}}}
     157
     158The first dict/struct is an identity, the second an attribute, and the third an invalid certificate.