upstream/openldap
1
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2025-12-26 01:29:59 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

README updated

Browse source
This commit is contained in:
Sang Seok Lim 2004-12-23 20:25:12 +00:00
parent 7198e9e4b9
commit 27c817217b
1 changed files with 105 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

168
contrib/slapd-modules/comp_match/README
View file

@ -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
<http://www.OpenLDAP.org/license.html>.
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
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
module_init() and functions which are dynamically linked
into the main slapd codes.
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.
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 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.
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 <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", the test script.
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.
How to add a new ASN.1 syntax other than the example
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
C) How to add a new ASN.1 syntax
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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
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.
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.
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)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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)"