From 27c817217b74cfbe274c5f9d10ecfad55ee8a6cd Mon Sep 17 00:00:00 2001 From: Sang Seok Lim Date: Thu, 23 Dec 2004 20:25:12 +0000 Subject: [PATCH] README updated --- contrib/slapd-modules/comp_match/README | 178 +++++++++++++++--------- 1 file changed, 110 insertions(+), 68 deletions(-) diff --git a/contrib/slapd-modules/comp_match/README b/contrib/slapd-modules/comp_match/README index 23d87cb95e..133757cdeb 100644 --- a/contrib/slapd-modules/comp_match/README +++ b/contrib/slapd-modules/comp_match/README @@ -1,85 +1,127 @@ 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. +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 -. +A copy of this license is available in the file LICENSE in +the top-level directory of the distribution or, alternatively, +at . -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 +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 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +A) Brief introduction about files in this directory +%%%%%%%%%%55%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 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. +module_init() and functions which are dynamically linked +into the main slapd codes. + +2) componentlib.c and componentlib.h +GSER and BER decoder library of each primitive ASN.1 type. +They use component representation to store ASN.1 values. + +3) certificate.c/.h authorityKeyIdentifier.c/.h +eSNACC generated BER and GSER decoder routines of the X.509 +certificate specification and one of its extensions, +authorityKeyIdentifier. 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. +An mapping table from ASN.1 types to corresponding Syntaxes, +matching rules, and component description in slapd. -How to compile and test the module with the certificate example +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +B) How to use Component Matching on X.509 certificates +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 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. +2) install the GSER-support eSNACC compiler. You can find +only in www.openldap.org. At least, you need the library +(libcasn1.a) and header files for compiling this module. +3) modify Makefile accordingly. then run make. you will get compmatch.la and other necessary files in ./libs 4) modify slapd.conf to include the following module command moduleload 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", the 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 +5) run slapd and perform search operations against +the attribute, userCertificate. You need to read through +RFC 3687 in order to understand how to compose component +filters. +Ex) component search filter examples +"(userCertificate:componentFilterMatch:=item:{ component +\"toBeSigned.serialNumber\", rule integerMatch, value 2 })" +You can find more examples in "test031-component-filter" +in the OpenLDAP source directory. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +C) How to add a new ASN.1 syntax +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +1) download and install the eSNACC compiler supporting +Component Matching. You can find the compiler only in +www.openldap.org. Before compiling, be sure to define +the "LDAP_COMPONENT" macro to obtain component +supported version of C library and back-ends of eSNACC. +Otherwise compiled library will fail to be linked to +the module. +2) using eSNACC, compile your ASN.1 specifications and +copy the generated .c and .h 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 partly supported(primitive types -used in an X.509 certificate) +3) modify example.c accordingly, seeing certificate.c +and certificate.asn as a reference. +- add init_module_xxx() located in generated .c file +into init_module() in init.c. +- modify the arguments of InstallOidDecoderMapping(...) +accordingly +- in the generated .c file, you need to write +"DecComponentxxxTop(...)" function for yourself. +You can copy BDecComponentCertificateTop in the +generated .c file and modify it accordingly. +4) register a new attribute syntax with a new OID +in a schema file +5) then goto 3) of B) section. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +D) How to configure Component Indexing +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +You can generate indices on each component of +a given attribute whose values are in either GSER or +BER. Currently primitive ASN.1 types, DN, and RDN +can be indexed for equality matching in BDB. +In order to generate indices, put following line +in the slapd configuration file, slapd.conf. + +index [attribute name].[component reference] eq + +Ex) +index userCertificate eq +index userCertificate.toBeSigned.issuer.rdnSequence eq +index userCertificate.toBeSigned.serialNumber eq +index userCertificate.toBeSigned.version eq + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +D) How to configure Attribute Alias +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +If your client is unable to use component filters, +attribute aliasing can be used instead. Attribute +Alias maps a virtual attribute type to an attribute +component and a component matching rule. +You can create your own aliases by following steps. + +1) register aliasing attributes in the schema file. +Sample aliasing attributes are in test.schema. +2) compose component filters for aliasing attributes +and put them in "preprocessed_comp_filter" array +in "init.c". +3) add "add_aa_entry" function calls in +"init_attribute_aliasing_table()" in "init.c" +4) perform searching against the aliasing attribute +Ex) +"(x509CertificateIssuer:distinguishedNameMatch= +cn=ray,L=yorktown,o=ibm,c=us)" -- 2.39.5