git.sur5r.net Git - openldap/blob - contrib/slapd-modules/comp_match/README

   1 Copyright 2004 Sang Seok Lim, IBM . All rights reserved.
   2
   3 Redistribution and use in source and binary forms, with or without
   4 modification, are permitted only as authorized by the OpenLDAP
   5 Public License.
   6
   7 A copy of this license is available in the file LICENSE in the
   8 top-level directory of the distribution or, alternatively, at
   9 <http://www.OpenLDAP.org/license.html>.
  10
  11 This directory contains a Component Matching module
  12 and a X.509 Certificate example.
  13 In order to understand Component Matching, see RFC 3687
  14 and http://www.openldap.org/conf/odd-sandiego-2004/Sangseok.pdf
  15
  16 Brief introduction about files in this directory
  17
  18 1) init.c
  19 module_init() and four functions which are dynamically linked into the main slapd codes
  20 comp_convert_attr_to_comp : decode an attribute value into a component tree
  21 comp_convert_assert_to_comp : decode an assertion value  into a component tree
  22                               using the decoder of the extracted component.
  23 comp_convert_asn_to_ldap : transform ASN.1 type values into a LDAP string.
  24 comp_free_component : free memory allocated by GSER or BER decoders
  25
  26 2) componentlib.c and component.h
  27 GSER and BER decoder library of each ASN.1 type. They
  28 use component representation to store ASN.1 values.
  29
  30 3) certificate.c certificate.h cacert.pem
  31 eSNACC generated BER and GSER decoder routines of the X.509 certificate
  32 specification, or certificate.asn1 in the directory. cacert.pem
  33 is generated by openssl to test this module.
  34
  35 4) asn_to_syn_mr.c asn.h
  36 An mapping table from ASN.1 types to corresponding Syntaxes and
  37 matching rules in slapd. If the validate function of the mapped syntax
  38 exists, it will be called to validate the decoded ASN.1 value.
  39
  40 How to compile and test the module with the certificate example
  41
  42 1) be sure to configure slapd with enable-modules on.
  43 2) install an eSNACC compiler. At least, you should have library and
  44 header files to compile the module.
  45 3) modify Makefile accordingly. then execute make.
  46 you will get compmatch.la and other necessary files in ./libs
  47 4) modify slapd.conf to include the following module command
  48         moduleload <path to>compmatch.la
  49 5) run slapd and perform ldapsearch on the attribute, or componentCertificatea
  50 (preregistered example attribute defined by the certificate)
  51 --component search filter example
  52 "componentCertificate:componentCertificateMatch:=item:{ component
  53 \"tbsCertificate.serialNumber\", rule allComponentsMatch, value 2 }"
  54 You can find more examples in "test031-component-filter", the test script.
  55
  56 How to add a new ASN.1 syntax other than the example
  57
  58 1) download and install an eSNACC compiler supporting Component Matching
  59 in www.openldap.org.  Before compiling, be sure to define
  60 a "LDAP_COMPONENT" macro to obtain component
  61 supported version of C library and back-ends of eSNACC. Otherwise compiled
  62 library fails to be linked to module.
  63 2) using eSNACc, compile your ASN.1 specifications and copy the generated c files
  64 to this directory
  65 Ex) $ esnacc -E BER_COMP -E GSER -t -d -f example.asn
  66 For Component Matching, set BOTH BER_COMP and GSER on.
  67 After compiling, you will get example.c and example.h
  68 3) modify example.c accordingly, seeing certificate.c and certificate.asn
  69 as a reference.
  70 - modify parameters of add_OD_entry(...) in init_module_xxx(...) in example.c.
  71 you need a new OID to register this module into slapd.
  72 - add init_module_xxx() into init_module() in init.c
  73 4) modify asn.h and asn_to_syn_mr.c accordingly. add new enum ID.
  74 5) register a new attribute syntax with a new OID in a schema file
  75 6) then goto 3) above.
  76
  77 Current Status
  78 The generated functions such as GSER/BER decoders, extractor
  79 allComponentMatch for a X.509 certificate ASN.1 specification (certificate.asn)
  80 have been tested successfully. But this is currently under development.
  81 before using it, don't forget to check following status of development,
  82 1) Not all ASN.1 types are supported yet.
  83 See componentlib.c to check which ASN.1 types are currently supported
  84 2) Component version of GSER encoders are not supported yet
  85 3) Not all ComponentId of a component reference are supported yet
  86 supported : identifier, from-beginning, count, from-end, <all>
  87 not supported :  select, content