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
   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)"