Home | History | Annotate | Line # | Download | only in comp_match 
      1 Copyright 2004 Sang Seok Lim, IBM . All rights reserved.
      2 
      3 Redistribution and use in source and binary forms, with
      4 or without modification, are permitted only as authorized
      5 by the OpenLDAP Public License.
      6 
      7 A copy of this license is available in the file LICENSE in
      8 the top-level directory of the distribution or, alternatively,
      9 at <http://www.OpenLDAP.org/license.html>.
     10 
     11 This directory contains a Component Matching module and
     12 a X.509 Certificate example.  In order to understand Component
     13 Matching, see RFC 3687 and
     14 http://www.openldap.org/conf/odd-sandiego-2004/Sangseok.pdf
     15 
     16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     17 A) Brief introduction about files in this directory
     18 %%%%%%%%%%55%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     19 
     20 1) init.c
     21 module_init() and functions which are dynamically linked
     22 into the main slapd codes.
     23 
     24 2) componentlib.c and componentlib.h
     25 GSER and BER decoder library of each primitive ASN.1 type.
     26 They use component representation to store ASN.1 values.
     27 
     28 3) certificate.c/.h authorityKeyIdentifier.c/.h
     29 eSNACC generated BER and GSER decoder routines of the X.509
     30 certificate specification and one of its extensions,
     31 authorityKeyIdentifier.
     32 
     33 4) asn_to_syn_mr.c asn.h
     34 An mapping table from ASN.1 types to corresponding Syntaxes,
     35 matching rules, and component description in slapd.
     36 
     37 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     38 B) How to use Component Matching on X.509 certificates
     39 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     40 
     41 1) be sure to configure slapd with enable-modules on.
     42 2) install the GSER-support eSNACC compiler. You can find
     43 only in www.openldap.org. At least, you need the library
     44 (libcasn1.a) and header files for compiling this module.
     45 3) modify Makefile accordingly. then run 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 search operations against
     50 the attribute, userCertificate. You need to read through
     51 RFC 3687 in order to understand how to compose component
     52 filters.
     53 Ex) component search filter examples
     54 "(userCertificate:componentFilterMatch:=item:{ component
     55 \"toBeSigned.serialNumber\", rule integerMatch, value 2 })"
     56 You can find more examples in "test031-component-filter"
     57 in the OpenLDAP source directory.
     58 
     59 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     60 C) How to add a new ASN.1 syntax
     61 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     62 
     63 1) download and install the eSNACC compiler supporting
     64 Component Matching. You can find the compiler only in
     65 www.openldap.org.  Before compiling, be sure to define
     66 the "LDAP_COMPONENT" macro to obtain component
     67 supported version of C library and back-ends of eSNACC.
     68 Otherwise compiled library will fail to be linked to
     69 the module.
     70 2) using eSNACC, compile your ASN.1 specifications and
     71 copy the generated .c and .h files to this directory
     72 Ex)
     73 $ esnacc -E BER_COMP -E GSER -t -d -f example.asn 
     74 For Component Matching, set BOTH BER_COMP and GSER on.
     75 After compiling, you will get example.c and example.h
     76 3) modify example.c accordingly, seeing certificate.c
     77 and certificate.asn as a reference.
     78 - add init_module_xxx() located in generated .c file
     79 into init_module() in init.c.
     80 - modify the arguments of InstallOidDecoderMapping(...)
     81 accordingly
     82 - in the generated .c file, you need to write
     83 "DecComponentxxxTop(...)" function for yourself.
     84 You can copy BDecComponentCertificateTop in the 
     85 generated .c file and modify it accordingly.
     86 4) register a new attribute syntax with a new OID
     87 in a schema file
     88 5) then goto 3) of B) section.
     89 
     90 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     91 D) How to configure Component Indexing
     92 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     93 You can generate indices on each component of
     94 a given attribute whose values are in either GSER or
     95 BER. Currently primitive ASN.1 types, DN, and RDN
     96 can be indexed for equality matching in BDB.
     97 In order to generate indices, put following line
     98 in the slapd configuration file, slapd.conf.
     99 
    100 index [attribute name].[component reference] eq
    101 
    102 Ex)
    103 index userCertificate eq
    104 index userCertificate.toBeSigned.issuer.rdnSequence eq
    105 index userCertificate.toBeSigned.serialNumber eq
    106 index userCertificate.toBeSigned.version eq
    107 
    108 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    109 D) How to configure Attribute Alias
    110 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    111 If your client is unable to use component filters,
    112 attribute aliasing can be used instead. Attribute
    113 Alias maps a virtual attribute type to an attribute
    114 component and a component matching rule.
    115 You can create your own aliases by following steps.
    116 
    117 1) register aliasing attributes in the schema file.
    118 Sample aliasing attributes are in test.schema.
    119 2) compose component filters for aliasing attributes
    120 and put them in "preprocessed_comp_filter" array
    121 in "init.c".
    122 3) add "add_aa_entry" function calls in
    123 "init_attribute_aliasing_table()" in "init.c"
    124 4) perform searching against the aliasing attribute
    125 Ex)
    126 "(x509CertificateIssuer:distinguishedNameMatch=
    127 cn=ray,L=yorktown,o=ibm,c=us)"
    128