openldap/contrib/slapd-modules/comp_match

Copyright 2004 Sang Seok Lim, IBM . All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted only as authorized by the OpenLDAP
Public License.

A copy of this license is available in the file LICENSE in the
top-level directory of the distribution or, alternatively, at
<http://www.OpenLDAP.org/license.html>.

This directory contains a Component Matching module
and a X.509 Certificate example.
In order to understand Component Matching, see RFC 3687
and http://www.openldap.org/conf/odd-sandiego-2004/Sangseok.pdf

Brief introduction about files in this directory

1) init.c
module_init() and four functions which are dynamically linked into the main slapd codes
comp_convert_attr_to_comp : decode an attribute value into a component tree
comp_convert_assert_to_comp : decode an assertion value  into a component tree
			      using the decoder of the extracted component.
comp_convert_asn_to_ldap : transform ASN.1 type values into a LDAP string.
comp_free_component : free memory allocated by GSER or BER decoders

2) componentlib.c and component.h
GSER and BER decoder library of each ASN.1 type. They
use component representation to store ASN.1 values.

3) certificate.c certificate.h cacert.pem
eSNACC generated BER and GSER decoder routines of the X.509 certificate
specification, or certificate.asn1 in the directory. cacert.pem
is generated by openssl to test this module.

4) asn_to_syn_mr.c asn.h
An mapping table from ASN.1 types to corresponding Syntaxes and
matching rules in slapd. If the validate function of the mapped syntax
exists, it will be called to validate the decoded ASN.1 value.

How to compile and test the module with the certificate example

1) be sure to configure slapd with enable-modules on.
2) install an eSNACC compiler. At least, you should have library and
header files to compile the module.
3) modify Makefile accordingly. then execute make.
you will get compmatch.la and other necessary files in ./libs
4) modify slapd.conf to include the following module command
	moduleload <path to>compmatch.la
5) run slapd and perform ldapsearch on the attribute, or componentCertificatea
(preregistered example attribute defined by the certificate)
--component search filter example
"componentCertificate:componentCertificateMatch:=item:{ component
\"tbsCertificate.serialNumber\", rule allComponentsMatch, value 2 }"
You can find more examples in "test031-component-filter", a test script.

How to add a new ASN.1 syntax other than the example

1) download and install an eSNACC compiler supporting Component Matching
in www.openldap.org.  Before compiling, be sure to define
a "LDAP_COMPONENT" macro to obtain component
supported version of C library and back-ends of eSNACC. Otherwise compiled
library fails to be linked to module.
2) using eSNACc, compile your ASN.1 specifications and copy the generated c files
to this directory
Ex) $ esnacc -E BER_COMP -E GSER -t -d -f example.asn 
For Component Matching, set BOTH BER_COMP and GSER on.
After compiling, you will get example.c and example.h
3) modify example.c accordingly, seeing certificate.c and certificate.asn
as a reference.
- modify parameters of add_OD_entry(...) in init_module_xxx(...) in example.c.
you need a new OID to register this module into slapd.
- add init_module_xxx() into init_module() in init.c
4) modify asn.h and asn_to_syn_mr.c accordingly. add new enum ID.
5) register a new attribute syntax with a new OID in a schema file
6) then goto 3) above.

Current Status
The generated functions such as GSER/BER decoders, extractor
allComponentMatch for a X.509 certificate ASN.1 specification (certificate.asn)
have been tested successfully. But this is currently under development.
before using it, don't forget to check following status of development, 
1) Not all ASN.1 types are supported yet.
See componentlib.c to check which ASN.1 types are currently supported
2) Component version of GSER encoders are not supported yet
3) Not all ComponentId of a component reference are supported yet
supported : identifier, from-beginning, count, from-end
not supported :  all, select, content