From wyllys@sac.sfbay.sun.com Tue May 18 13:16:03 2010 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o4IKG3sg023996 for ; Tue, 18 May 2010 13:16:03 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail2sca.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o4IKG3nS029940; Tue, 18 May 2010 13:16:03 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0L2M00H2NTMRL500@nwk-avmta-1.sfbay.Sun.COM>; Tue, 18 May 2010 13:16:03 -0700 (PDT) Received: from dm-sfbay-02.sfbay.sun.com ([129.146.11.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0L2M00DRITMQBO70@nwk-avmta-1.sfbay.Sun.COM>; Tue, 18 May 2010 13:16:02 -0700 (PDT) Received: from sac.sfbay.sun.com (sac.SFBay.Sun.COM [129.146.226.132]) by dm-sfbay-02.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o4IKG0Yr026818; Tue, 18 May 2010 13:16:00 -0700 (PDT) Received: from sac.sfbay.sun.com (localhost [127.0.0.1]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o4IKFxwB023983; Tue, 18 May 2010 13:15:59 -0700 (PDT) Received: (from wyllys@localhost) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8/Submit) id o4IKFxM3023979; Tue, 18 May 2010 13:15:59 -0700 (PDT) Date: Tue, 18 May 2010 13:15:59 -0700 (PDT) From: Wyllys Ingersoll Subject: KMF Certificate Name mapping extensions [PSARC/2010/177 FastTrack timeout 05/25/2010] To: PSARC-ext@sun.com Cc: jan.pechanec@sun.com Message-id: <201005182015.o4IKFxM3023979@sac.sfbay.sun.com> Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 17701 Template Version: @(#)sac_nextcase 1.70 03/30/10 SMI This information is Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. 1. Introduction 1.1. Project/Component Working Name: KMF Certificate Name mapping extensions 1.2. Name of Document Author/Supplier: Author: Jan Pechanec 1.3 Date of This Document: 18 May, 2010 4. Technical Description Certificate to name mapping extension to the Key Management Framework ===================================================================== Motivation ---------- When applications work with user or host certificates the validating side needs to find out which user or which host was the certificate issued for. The most commonly used way may be to put the name into the Common Name (CN) attribute. However, there are other ways of supplying the information, be it rfc822Name, iPAddress, or dNSName from the subjectAltName extension. We can also hash the certificate and find the mapped name in an external database. We might use the whole DN string to map the certificate to a name using an external database again. Another use might be also to strip the domain name from rfc822Name to get a user name, or we might want to ignore case sensitiveness. We might also somehow translate information harvested from the certificate to something else following a merge of two administrative domains, thus solving name space conflicts between them. The list of possible uses could continue. All of this is quite independent of the application and to avoid a situation where every application does its own certficate to name mapping, we think that KMF would be the best place to put this functionality. What's more, we think that this feature should be extensible and Solaris itself should provide a few basic mapping schemes. Who needs that now ------------------ SSH/X.509 project (6357779 SSHv2 x.509 support desired) needs a way to map a certificate to a hostname for the server authentication, and to map a certificate to a user name for the user authentication. Overview -------- The mapping scheme in effect would be tied to the KMF session. If a different mapping should be used for the session, the mapping must be reinitialized. It's enough to initialize a new mapping, KMF will automatically finalize the current one if mapper supports the finalize function. The mapping itself corresponds to an object called a "mapper". It is a shared object that KMF would dlopen() upon mapping initialization. The mapper object would provide 5 functions. The set would contain a function to initialize the mapping, map a certificate to a name, a convenience function that would provide an answer if the certificate matches a name provided, a finalization function, and a function to provide more information should other functions result in an error internal to the specific mapper. Mapper internals must be designed so that the same mapper can be used from multiple KMF sessions from the same process. The set of these 5 functions would be an interface between the KMF and the mappers. The programmer using the libkmf(3lib) library would use 5 functions correspending to the mapper fuctions described above. The mapper programmer can also use 4 more KMF functions that work with the mapper state as part of the libkmf(3lib). Relevant CRs ------------ 6942888 KMF should provide certificate to name mapping capabilities 6950204 STC-2 KMF test suite need to test certificate to name mapping Delivering mappers ------------------ Listing mappers is not part of this ARC case and will not be part of the initial push. While all the functionality has been already tested against the CN mapper prototype (mapping a certificate to the contents of the Common Name attribute), we will deliver mappers in separate pushes. New tests for kmfcfg(1) will be part of the 1st phase of the project, tests for cert-to-name mapping functions will be part of the 2nd phase which will deliver the CN mapper. KMF API extension ----------------- There are 9 new functions representing the public interface an application or mapper programmer could use. Note that the existing KMF_DATA structure is defined like this: typedef struct kmf_data { size_t Length; /* in bytes */ uchar_t *Data; } KMF_DATA; KMF_RETURN kmf_cert_to_name_mapping_initialize( KMF_HANDLE_T handle, int numattr, KMF_ATTRIBUTE *attrlist) supported attributes are all (char *) pointers to ASCII strings: KMF_MAPPER_NAME_ATTR - mapper name (kmf_mapper_.so) KMF_DIRPATH_ATTR - default is /lib/crypto where all existing KMF plugins already reside KMF_MAPPER_FILENAME_ATTR - full path to the mapper shared object, overrides the name and directory KMF_MAPPER_OPTIONS_ATTR - mapper specific options in a string. KMF does not know the inner structure of the string. However, we expect a comma separated list of option names will be used. The function is called once internally when the policy is processed in the "kmf_initialize" function. If the policy has no mapping set the call has no effect on KMF. If the consumer needs to use a different mapping later, this function can be called with the proper attributes and the old one mapper will be closed and the new one opened. The name, mapper path, and options in the policy database can be always overridden using the attributes. Also, the directory attribute is always tied to the specific mapper name. If only a mapper name is set in the function attributes, the default KMF mapper directory will be used no matter how the mapper directory is set in the policy file. Re-initializing an already initialized mapper is allowed and the mapper can get new options by that, for example. The init function from the mapper is always called again if it does exist. If initialization of a mapper fails while there was already an initialized mapper, the state of the current mapping is undefined. The application is expected to initialize the mapping again before proceeding. return values: KMF_OK - OK KMF_ERR_BAD_PARAMETER - handle is NULL or some attributes are missing, either in the attrlist or in the policy file KMF_ERR_MEMORY - out of memory during memory allocation KMF_ERR_MAPPER_OPEN - dlopen() failed KMF_ERR_MAPPER_NOT_FOUND - mapper not found or set KMF_ERR_INTERNAL - an error occured in the mapper module; a missing mapper config file or badly formatted config settings string, for example - in this case, user can call kmf_get_mapper_error_str() to get a more specific error message KMF_RETURN kmf_cert_to_name_mapping_finalize(KMF_HANDLE_T handle) Frees up any local memory in the KMF policy handle associated with the mapper and calls "dlclose()" on the mappers descriptor. If the mapper has a finalize function called "mapper_finalize", this function will look it up and call it prior to calling "dlclose()". return values: KMF_OK - OK KMF_RETURN kmf_get_mapper_error_str(KMF_HANDLE_T handle, char **errstr) If the mapper returns KMF_ERR_INTERNAL the application may ask for the internal mapper error string. The caller is expected to free the returned string later with kmf_free_str(). KMF_RETURN kmf_map_cert_to_name( KMF_HANDLE_T handle, KMF_DATA *cert, KMF_DATA *name); Maps the certificate to a name. We intentionally use KMF_DATA for the output "name" parameter so that the certificate can be mapped to any data, possibly even binary. The mapper fills out its Data and Length fields. The caller is responsible for freeing the Data buffer when done using it. The "name" output parameter will be zeroized in case of any error, effectively returning a NULL string. return values: KMF_OK - OK KMF_ERR_BAD_PARAMETER - handle is NULL KMF_ERR_MAPPER_NOT_FOUND - same as in the init function KMF_ERR_FUNCTION_NOT_FOUND - the mapping function not found in the mapper KMF_ERR_INTERNAL - same as in the init function KMF_ERR_MEMORY - memory shortage in the KMF or the mapper function KMF_ERR_MAPPING_FAILED - generic error when the module doesn't want to provide more information through the KMF_ERR_INTERNAL error KMF_ERR_BAD_CERT_FORMAT - is not cert in ASN.1 format KMF_RETURN kmf_match_cert_to_name( KMF_HANDLE_T handle, KMF_DATA *cert, KMF_DATA *name_to_match, KMF_DATA *mapped_name) The function returns KMF_OK if the certificate matches the name in "name_to_match". It also provides the mapped name if "mapped_name" is not NULL. This should make the user's life easier - if the match failure is not expected, the "mapped_name" can be immediatelly used in the debug, warning, or error message. Technically, we could have just used the map function. For mapping, we would ignore the KMF_ERR_CERT_TO_NAME_NO_MATCH error code. However, it's cleaner to separate those. We expect that internally in the mappers the match function will be implemented mostly using the mapping function anyway. return values: KMF_OK - the certificate matches the provided name KMF_ERR_NAME_NOT_MATCHED - mapper must return this return code when the certificate does not match the provided name Other error codes same as in kmf_map_cert_to_name(). The next four functions are helper functions that work with the mapper state related to the KMF handle. We expect that users can write their own mappers but since the KMF session handle is an opaque structure, we must provide a way to access the last mapper internal error code and the options. Both are tied to the KMF session so it's logical to store them together with the KMF session handle. void kmf_set_mapper_lasterror(KMF_HANDLE_T handle, uint32_t err); uint32_t kmf_get_mapper_lasterror(KMF_HANDLE_T handle); Note that the next 2 functions are not about handling the option string from the policy database or from the attribute to the kmf_cert_to_name_mapping_initialize function. It is solely about keeping the pointer to the mapper-specific option info with the KMF session handle. void kmf_set_mapper_options(KMF_HANDLE_T h, void *options) void *kmf_get_mapper_options(KMF_HANDLE_T h); KMF-Mapper API interface ------------------------ The naming convention for mappers is "kmf_mapper_%s.so". For example, the CN mapper will use kmf_mapper_cn.so. By default, the mapper libraries will be installed in the same directory as other KMF plugins (/lib/crypto and /lib/crypto/$ISA). However, the policy definition (mapper-directory) or the KMF_DIRPATH_ATTR attribute to the kmf_cert_to_name_mapping_initialize function may specify an alternate location. Every mapper can provide up to 5 functions to be used from KMF. From those 5, 3 are mandatory. Since the mappers are more or less part of KMF they should make use of KMF as much as possible. The mapper interface to KMF is through the following functions: KMF_RETURN mapper_initialize(KMF_HANDLE_T h, int num_attr, char *options) - mapper library initialization function. The attribute "options" delivers the current options whether those came from the attribute to the kmf_cert_to_name_mapping_initialize() function or from the policy database. - this function is NOT mandatory void mapper_finalize(KMF_HANDLE_T h) - mapper library cleanup function - this function is NOT mandatory KMF_RETURN mapper_map_cert_to_name(KMF_HANDLE *handle, KMF_DATA *cert, KMF_DATA *name); - maps the certificate to a name KMF_RETURN mapper_match_cert_to_name(KMF_HANDLE_T h, KMF_DATA *cert, KMF_DATA *name_to_match, KMF_DATA *mapped_name) - tries to match the provided name to a certificate - if mapped_name name is not NULL, the function allocates memory for Data, copies the mapped name there, and updates the Lenght. The name should be NULL terminated if it is a string. mapper_get_error_string(KMF_HANDLE *handle, char **errstr) - translate local mapper-specific error codes into human readable text for logging and error messages. - the local mapper function should allocate the string and return its pointer to the caller. The caller is responsible for freeing it using kmf_free_str(). See respective KMF functions for the list of expected return values. kmfcfg(1) --------- "create" and "modify" subcommands will be extended with: mapper-name mapper-directory mapper-path mapper-options "mapper-options" is opaque to KMF, its limit is 255 characters and its contents restricted to US ASCII (0-127). "mapper-options" is expected to contain comma separated list of attributes that affect the mapping operation, for example: mapper-options="ignorecase,ignoredomain" For some mappers, the "mapper-options" may be expected to contain attr/value pairs such as: config=/usr/local/kmf/mappers/xxx-mapping.conf The exact structure of mapper-options attribute is enforced by the mapper library, not KMF or the KMF Policy engine. kmfpolicy.dtd ------------- Will be extended the way that the policy file can contain something like this: or, Attributes "mapper-path" and "mapper-name" (possibly with mapper-directory) are mutually exclusive, kmfcfg(1) will not allow users to set both. The "mapper-name" contains the name that is to replace the %s substring in "(/lib/crypto/)kmf_mapper_%s.so". "mapper-options" %attribute can be present only if "mapper-path" or "mapper-name" is present. "mapper-directory" can be present only if "mapper-name" is present. The mappers provided by Solaris ------------------------------- Such mappers are not part of this case. If an ARC case (or cases) for those are needed they will be filed separatedly. We plan to deliver the CN mapper as the 1st one. Man page changes ---------------- 6951981 libkmf(3lib) will need an update after the delivery of 6942888 libkmf(3lib) only contains a list of public functions. We will add all 9 functions there. kmf_cert_to_name_mapping_finalize kmf_cert_to_name_mapping_initialize kmf_get_mapper_error_str kmf_get_mapper_lasterror kmf_get_mapper_options kmf_map_cert_to_name kmf_match_cert_to_name kmf_set_mapper_lasterror kmf_set_mapper_options 6951979 kmfcfg(1) will need an update after the delivery of 6942888 --- kmfcfg.1 Thu May 13 14:47:43 2010 +++ kmfcfg.1.new Thu May 13 14:47:43 2010 @@ -66,6 +66,10 @@ ipsecUser | timeStamping | OCSPSigning],[...] [ekuoids=OID,OID,OID...] + [mapper-name=name of the mapper] + [mapper-dir=dir where mapper library resides] + [mapper-path=full pathname of mapper library] + [mapper-options=mapper options] The create subcommand supports the following options: @@ -283,6 +287,30 @@ attributes need to be set, if the value of ignore- trust-anchor attribute is false. + mapper-name=name + mapper-dir=directory + mapper-path=path + mapper-options=options + + These four options support the certificate to + name mapping. mapper-name provides the name of + the mapper. For example, the "cn" name + represents the mapper object kmf_mapper_cn.so. + mapper-dir overrides the default mapper directory + /lib/crypto. mapper-path specifies the full path + to the mapper object. mapper-options is an ASCII + only string of maximum of 255 bytes long. Its + format is mapper specific but mappers are + expected to accept a comma separated list of + options, for example "ignorecase,ignoredomain". + mapper-path and mapper-name are mutually + exclusive. mapper-dir can be set only if + mapper-name is set. mapper-options can be set + only if mapper-name or mapper-path is set. Trying + to use any of the above mentioned incorrect + settings will result in an error and the policy + database will not be modified. + delete Deletes any policy matching the indicated policy name. @@ -430,6 +458,10 @@ OCSPSigning],[...] [ekuoids=OID,OID,OID] [eku-none=true|false] + [mapper-name=name of the mapper] + [mapper-dir=dir where mapper library resides] + [mapper-path=full pathname of mapper library] + [mapper-options=mapper options] The modify subcommand supports many of the same options as the create subcommand. For descriptions of shared @@ -488,6 +520,12 @@ database cannot be modi- fied. + mapper-name=name, mapper-dir=directory, mapper-path=path + mapper-options=options + See the "create" + subcommand for more + information. + Plugin Subcommands install keystore=keystore_name modulepath=pathname\ [option=option_str] The mappers will have their own manual page. We will deliver documentation together with the mappers. Interface stability ------------------- Private Release Binding --------------- Patch 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: ON 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open From sacadmin Wed May 19 08:28:50 2010 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o4JFSoSr004293 for ; Wed, 19 May 2010 08:28:50 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o4JFSc2H008064 for <@sunmail2sca.sfbay.sun.com:psarc@sun.com>; Wed, 19 May 2010 08:28:50 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0L2O00L05B01AE00@brm-avmta-1.central.sun.com> for psarc@sun.com (ORCPT psarc@sun.com); Wed, 19 May 2010 09:28:49 -0600 (MDT) Received: from gmp-eb-inf-2.sun.com ([192.18.6.24]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0L2O00HE3AZYHV40@brm-avmta-1.central.sun.com> for psarc@sun.com (ORCPT psarc@sun.com); Wed, 19 May 2010 09:28:47 -0600 (MDT) Received: from fe-emea-13.sun.com (gmp-eb-lb-1-fe1.eu.sun.com [192.18.6.7] (may be forged)) by gmp-eb-inf-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id o4JFSjPN019680 for ; Wed, 19 May 2010 15:28:46 +0000 (GMT) Received: from conversion-daemon.fe-emea-13.sun.com by fe-emea-13.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0L2O00M00AZ1EN00@fe-emea-13.sun.com> for psarc@sun.com (ORCPT psarc@sun.com); Wed, 19 May 2010 16:28:31 +0100 (BST) Received: from rejewski ([unknown] [10.18.138.121]) by fe-emea-13.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0L2O00M97AZJ4LB0@fe-emea-13.sun.com> for psarc@sun.com (ORCPT psarc@sun.com); Wed, 19 May 2010 16:28:31 +0100 (BST) Date: Wed, 19 May 2010 17:28:15 +0200 (CEST) From: Jan Pechanec Subject: KMF Certificate Name mapping extensions [PSARC/2010/177 FastTrack timeout 05/25/2010] Sender: Jan.Pechanec@sun.com X-X-Sender: jp161948@rejewski To: psarc@sun.com Cc: Wyllys Ingersoll Message-id: MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_+9zbQZSfu9CbGYJ9Sifi/g)" X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 20897 This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --Boundary_(ID_+9zbQZSfu9CbGYJ9Sifi/g) Content-type: TEXT/PLAIN; CHARSET=US-ASCII Content-transfer-encoding: 7BIT hi, we were suggested to resend the case to the internal PSARC alias. I've also updated the material, the diff is attached. The only important change is that we intend to deliver the KMF cert-to-name mapping framework and the 1st mapper together in the same push. Template Version: @(#)sac_nextcase 1.70 03/30/10 SMI This information is Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. 1. Introduction 1.1. Project/Component Working Name: KMF Certificate Name mapping extensions 1.2. Name of Document Author/Supplier: Author: Jan Pechanec 1.3 Date of This Document: 18 May, 2010 4. Technical Description Certificate to name mapping extension to the Key Management Framework ===================================================================== Motivation ---------- When applications work with user or host certificates the validating side needs to find out which user or which host was the certificate issued for. The most commonly used way may be to put the name into the Common Name (CN) attribute. However, there are other ways of supplying the information, be it rfc822Name, iPAddress, or dNSName from the subjectAltName extension. We can also hash the certificate and find the mapped name in an external database. We might use the whole DN string to map the certificate to a name using an external database again. Another use might be also to strip the domain name from rfc822Name to get a user name, or we might want to ignore case sensitiveness. We might also somehow translate information harvested from the certificate to something else following a merge of two administrative domains, thus solving name space conflicts between them. The list of possible uses could continue. All of this is quite independent of the application and to avoid a situation where every application does its own certficate to name mapping, we think that KMF would be the best place to put this functionality. What's more, we think that this feature should be extensible and Solaris itself should provide a few basic mapping schemes. Who needs that now ------------------ SSH/X.509 project (6357779 SSHv2 x.509 support desired) needs a way to map a certificate to a hostname for the server authentication, and to map a certificate to a user name for the user authentication. Overview -------- The mapping scheme in effect would be tied to the KMF session. If a different mapping should be used for the session, the mapping must be reinitialized. It's enough to initialize a new mapping, KMF will automatically finalize the current one if mapper supports the finalize function. The mapping itself corresponds to an object called a "mapper". It is a shared object that KMF would dlopen() upon mapping initialization. The mapper object would provide 5 functions. The set would contain a function to initialize the mapping, map a certificate to a name, a convenience function that would provide an answer if the certificate matches a name provided, a finalization function, and a function to provide more information should other functions result in an error internal to the specific mapper. Mapper internals must be designed so that the same mapper can be used from multiple KMF sessions from the same process. The set of these 5 functions would be an interface between the KMF and the mappers. The programmer using the libkmf(3lib) library would use 5 functions correspending to the mapper fuctions described above. The mapper programmer can also use 4 more KMF functions that work with the mapper state as part of the libkmf(3lib). Relevant CRs ------------ 6942888 KMF should provide certificate to name mapping capabilities 6950204 STC-2 KMF test suite need to test certificate to name mapping Delivering mappers ------------------ Listing all possible mappers we might need in the future (aside from those mentioned in the Motivation section) is not part of this ARC case but the Common Name (CN) mapper will be part of the initial push. The CN mapper is specified in a separate case PSARC/2010/178. New tests for kmfcfg(1) and tests using the CN mapper will be part of the planned set of pushes. KMF API extension ----------------- There are 9 new functions representing the public interface an application or mapper programmer could use. Note that the existing KMF_DATA structure is defined like this: typedef struct kmf_data { size_t Length; /* in bytes */ uchar_t *Data; } KMF_DATA; KMF_RETURN kmf_cert_to_name_mapping_initialize( KMF_HANDLE_T handle, int numattr, KMF_ATTRIBUTE *attrlist) supported attributes are all (char *) pointers to ASCII strings: KMF_MAPPER_NAME_ATTR - mapper name (kmf_mapper_.so) KMF_DIRPATH_ATTR - default is /lib/crypto where all existing KMF plugins already reside KMF_MAPPER_FILENAME_ATTR - full path to the mapper shared object, overrides the name and directory KMF_MAPPER_OPTIONS_ATTR - mapper specific options in a string. KMF does not know the inner structure of the string. However, we expect a comma separated list of option names will be used. The function is called once internally when the policy is processed in the "kmf_initialize" function. If the policy has no mapping set the call has no effect on KMF. If the consumer needs to use a different mapping later, this function can be called with the proper attributes and the old one mapper will be closed and the new one opened. The name, mapper path, and options in the policy database can be always overridden using the attributes. Also, the directory attribute is always tied to the specific mapper name. If only a mapper name is set in the function attributes, the default KMF mapper directory will be used no matter how the mapper directory is set in the policy file. Re-initializing an already initialized mapper is allowed and the mapper can get new options by that, for example. The init function from the mapper is always called again if it does exist. If initialization of a mapper fails while there was already an initialized mapper, the state of the current mapping is undefined. The application is expected to initialize the mapping again before proceeding. return values: KMF_OK - OK KMF_ERR_BAD_PARAMETER - handle is NULL or some attributes are missing, either in the attrlist or in the policy file KMF_ERR_MEMORY - out of memory during memory allocation KMF_ERR_MAPPER_OPEN - dlopen() failed KMF_ERR_MAPPER_NOT_FOUND - mapper not found or set KMF_ERR_INTERNAL - an error occured in the mapper module; a missing mapper config file or badly formatted config settings string, for example - in this case, user can call kmf_get_mapper_error_str() to get a more specific error message KMF_RETURN kmf_cert_to_name_mapping_finalize(KMF_HANDLE_T handle) Frees up any local memory in the KMF policy handle associated with the mapper and calls "dlclose()" on the mappers descriptor. If the mapper has a finalize function called "mapper_finalize", this function will look it up and call it prior to calling "dlclose()". return values: KMF_OK - OK KMF_RETURN kmf_get_mapper_error_str(KMF_HANDLE_T handle, char **errstr) If the mapper returns KMF_ERR_INTERNAL the application may ask for the internal mapper error string. The caller is expected to free the returned string later with kmf_free_str(). KMF_RETURN kmf_map_cert_to_name( KMF_HANDLE_T handle, KMF_DATA *cert, KMF_DATA *name); Maps the certificate to a name. We intentionally use KMF_DATA for the output "name" parameter so that the certificate can be mapped to any data, possibly even binary. The mapper fills out its Data and Length fields. The caller is responsible for freeing the Data buffer when done using it. The "name" output parameter will be zeroized in case of any error, effectively returning a NULL string. return values: KMF_OK - OK KMF_ERR_BAD_PARAMETER - handle is NULL KMF_ERR_MAPPER_NOT_FOUND - same as in the init function KMF_ERR_FUNCTION_NOT_FOUND - the mapping function not found in the mapper KMF_ERR_INTERNAL - same as in the init function KMF_ERR_MEMORY - memory shortage in the KMF or the mapper function KMF_ERR_MAPPING_FAILED - generic error when the module doesn't want to provide more information through the KMF_ERR_INTERNAL error KMF_ERR_BAD_CERT_FORMAT - is not cert in ASN.1 format KMF_RETURN kmf_match_cert_to_name( KMF_HANDLE_T handle, KMF_DATA *cert, KMF_DATA *name_to_match, KMF_DATA *mapped_name) The function returns KMF_OK if the certificate matches the name in "name_to_match". It also provides the mapped name if "mapped_name" is not NULL. This should make the user's life easier - if the match failure is not expected, the "mapped_name" can be immediatelly used in the debug, warning, or error message. Technically, we could have just used the map function. For mapping, we would ignore the KMF_ERR_CERT_TO_NAME_NO_MATCH error code. However, it's cleaner to separate those. We expect that internally in the mappers the match function will be implemented mostly using the mapping function anyway. return values: KMF_OK - the certificate matches the provided name KMF_ERR_NAME_NOT_MATCHED - mapper must return this return code when the certificate does not match the provided name Other error codes same as in kmf_map_cert_to_name(). The next four functions are helper functions that work with the mapper state related to the KMF handle. We expect that users can write their own mappers but since the KMF session handle is an opaque structure, we must provide a way to access the last mapper internal error code and the options. Both are tied to the KMF session so it's logical to store them together with the KMF session handle. void kmf_set_mapper_lasterror(KMF_HANDLE_T handle, uint32_t err); uint32_t kmf_get_mapper_lasterror(KMF_HANDLE_T handle); Note that the next 2 functions are not about handling the option string from the policy database or from the attribute to the kmf_cert_to_name_mapping_initialize function. It is solely about keeping the pointer to the mapper-specific option info with the KMF session handle. void kmf_set_mapper_options(KMF_HANDLE_T h, void *options) void *kmf_get_mapper_options(KMF_HANDLE_T h); KMF-Mapper API interface ------------------------ The naming convention for mappers is "kmf_mapper_%s.so". For example, the CN mapper will use kmf_mapper_cn.so. By default, the mapper libraries will be installed in the same directory as other KMF plugins (/lib/crypto and /lib/crypto/$ISA). However, the policy definition (mapper-directory) or the KMF_DIRPATH_ATTR attribute to the kmf_cert_to_name_mapping_initialize function may specify an alternate location. Every mapper can provide up to 5 functions to be used from KMF. From those 5, 3 are mandatory. Since the mappers are more or less part of KMF they should make use of KMF as much as possible. The mapper interface to KMF is through the following functions: KMF_RETURN mapper_initialize(KMF_HANDLE_T h, int num_attr, char *options) - mapper library initialization function. The attribute "options" delivers the current options whether those came from the attribute to the kmf_cert_to_name_mapping_initialize() function or from the policy database. - this function is NOT mandatory void mapper_finalize(KMF_HANDLE_T h) - mapper library cleanup function - this function is NOT mandatory KMF_RETURN mapper_map_cert_to_name(KMF_HANDLE *handle, KMF_DATA *cert, KMF_DATA *name); - maps the certificate to a name KMF_RETURN mapper_match_cert_to_name(KMF_HANDLE_T h, KMF_DATA *cert, KMF_DATA *name_to_match, KMF_DATA *mapped_name) - tries to match the provided name to a certificate - if mapped_name name is not NULL, the function allocates memory for Data, copies the mapped name there, and updates the Lenght. The name should be NULL terminated if it is a string. mapper_get_error_string(KMF_HANDLE *handle, char **errstr) - translate local mapper-specific error codes into human readable text for logging and error messages. - the local mapper function should allocate the string and return its pointer to the caller. The caller is responsible for freeing it using kmf_free_str(). See respective KMF functions for the list of expected return values. kmfcfg(1) --------- "create" and "modify" subcommands will be extended with: mapper-name mapper-directory mapper-path mapper-options "mapper-options" is opaque to KMF, its limit is 255 characters and its contents restricted to US ASCII (0-127). "mapper-options" is expected to contain comma separated list of attributes that affect the mapping operation, for example: mapper-options="casesensitive,ignoredomain" For some mappers, the "mapper-options" may be expected to contain attr/value pairs such as: config=/usr/local/kmf/mappers/xxx-mapping.conf The exact structure of mapper-options attribute is enforced by the mapper library, not KMF or the KMF Policy engine. kmfpolicy.dtd ------------- Will be extended the way that the policy file can contain something like this: or, Attributes "mapper-path" and "mapper-name" (possibly with mapper-directory) are mutually exclusive, kmfcfg(1) will not allow users to set both. The "mapper-name" contains the name that is to replace the %s substring in "(/lib/crypto/)kmf_mapper_%s.so". "mapper-options" %attribute can be present only if "mapper-path" or "mapper-name" is present. "mapper-directory" can be present only if "mapper-name" is present. The mappers provided by Solaris ------------------------------- Such mappers are not part of this case. If an ARC case (or cases) for those are needed they will be filed separatedly. We plan to deliver the CN mapper as the 1st one. Man page changes ---------------- 6951981 libkmf(3lib) will need an update after the delivery of 6942888 libkmf(3lib) only contains a list of public functions. We will add all 9 functions there. kmf_cert_to_name_mapping_finalize kmf_cert_to_name_mapping_initialize kmf_get_mapper_error_str kmf_get_mapper_lasterror kmf_get_mapper_options kmf_map_cert_to_name kmf_match_cert_to_name kmf_set_mapper_lasterror kmf_set_mapper_options 6951979 kmfcfg(1) will need an update after the delivery of 6942888 --- kmfcfg.1 Thu May 13 14:47:43 2010 +++ kmfcfg.1.new Thu May 13 14:47:43 2010 @@ -66,6 +66,10 @@ ipsecUser | timeStamping | OCSPSigning],[...] [ekuoids=OID,OID,OID...] + [mapper-name=name of the mapper] + [mapper-dir=dir where mapper library resides] + [mapper-path=full pathname of mapper library] + [mapper-options=mapper options] The create subcommand supports the following options: @@ -283,6 +287,30 @@ attributes need to be set, if the value of ignore- trust-anchor attribute is false. + mapper-name=name + mapper-dir=directory + mapper-path=path + mapper-options=options + + These four options support the certificate to + name mapping. mapper-name provides the name of + the mapper. For example, the "cn" name + represents the mapper object kmf_mapper_cn.so. + mapper-dir overrides the default mapper directory + /lib/crypto. mapper-path specifies the full path + to the mapper object. mapper-options is an ASCII + only string of maximum of 255 bytes long. Its + format is mapper specific but mappers are + expected to accept a comma separated list of + options, for example "casesensitive,ignoredomain". + mapper-path and mapper-name are mutually + exclusive. mapper-dir can be set only if + mapper-name is set. mapper-options can be set + only if mapper-name or mapper-path is set. Trying + to use any of the above mentioned incorrect + settings will result in an error and the policy + database will not be modified. + delete Deletes any policy matching the indicated policy name. @@ -430,6 +458,10 @@ OCSPSigning],[...] [ekuoids=OID,OID,OID] [eku-none=true|false] + [mapper-name=name of the mapper] + [mapper-dir=dir where mapper library resides] + [mapper-path=full pathname of mapper library] + [mapper-options=mapper options] The modify subcommand supports many of the same options as the create subcommand. For descriptions of shared @@ -488,6 +520,12 @@ database cannot be modi- fied. + mapper-name=name, mapper-dir=directory, mapper-path=path + mapper-options=options + See the "create" + subcommand for more + information. + Plugin Subcommands install keystore=keystore_name modulepath=pathname\ [option=option_str] The mappers will have their own manual page. We will deliver documentation together with the mappers. Interface stability ------------------- Private Release Binding --------------- Patch 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: ON 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open -- Jan Pechanec http://blogs.sun.com/janp --Boundary_(ID_+9zbQZSfu9CbGYJ9Sifi/g) Content-id: Content-type: TEXT/PLAIN; CHARSET=US-ASCII; name=changes.diff Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=changes.diff Content-description: --- mapping.new.txt Wed May 19 17:23:56 2010 +++ mapping.txt Wed May 19 17:16:42 2010 @@ -79,13 +79,15 @@ Delivering mappers ------------------ -Listing all possible mappers we might need in the future (aside from -those mentioned in the Motivation section) is not part of this ARC case -but the Common Name (CN) mapper will be part of the initial push. The CN -mapper is specified in a separate case PSARC/2010/178. +Listing mappers is not part of this ARC case and will not be part of the +initial push. While all the functionality has been already tested +against the CN mapper prototype (mapping a certificate to the contents +of the Common Name attribute), we will deliver mappers in separate +pushes. -New tests for kmfcfg(1) and tests using the CN mapper will be part of -the planned set of pushes. +New tests for kmfcfg(1) will be part of the 1st phase of the project, +tests for cert-to-name mapping functions will be part of the 2nd phase +which will deliver the CN mapper. KMF API extension ----------------- @@ -344,7 +346,7 @@ contain comma separated list of attributes that affect the mapping operation, for example: -mapper-options="casesensitive,ignoredomain" +mapper-options="ignorecase,ignoredomain" For some mappers, the "mapper-options" may be expected to contain attr/value pairs such as: config=/usr/local/kmf/mappers/xxx-mapping.conf @@ -361,13 +363,13 @@ + mapper-options="ignorecase,ignoredomain"> or, + mapper-options="ignorecase,ignoredomain"> Attributes "mapper-path" and "mapper-name" (possibly with mapper-directory) are mutually exclusive, kmfcfg(1) will not allow users @@ -437,7 +439,7 @@ + only string of maximum of 255 bytes long. Its + format is mapper specific but mappers are + expected to accept a comma separated list of -+ options, for example "casesensitive,ignoredomain". ++ options, for example "ignorecase,ignoredomain". + mapper-path and mapper-name are mutually + exclusive. mapper-dir can be set only if + mapper-name is set. mapper-options can be set --Boundary_(ID_+9zbQZSfu9CbGYJ9Sifi/g)-- From sacadmin Wed May 19 08:35:37 2010 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o4JFZbZG004376 for ; Wed, 19 May 2010 08:35:37 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o4JFZZDH014275; Wed, 19 May 2010 08:35:35 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0L2O00L05BBBWM00@brm-avmta-1.central.sun.com>; Wed, 19 May 2010 09:35:35 -0600 (MDT) Received: from sca-ea-mail-2.sun.com ([192.18.43.25]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0L2O00HG9BBAHR40@brm-avmta-1.central.sun.com>; Wed, 19 May 2010 09:35:34 -0600 (MDT) Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by sca-ea-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id o4JFZXoZ004625; Wed, 19 May 2010 15:35:33 +0000 (GMT) Received: from acsmt353.oracle.com (acsmt353.oracle.com [141.146.40.153]) by acsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o4JFTTAt015018; Wed, 19 May 2010 15:35:32 +0000 (GMT) Received: from abhmt003.oracle.com by acsmt353.oracle.com with ESMTP id 250914161274283290; Wed, 19 May 2010 08:34:50 -0700 Received: from [129.148.19.4] (/129.148.19.4) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 19 May 2010 08:34:50 -0700 Date: Wed, 19 May 2010 11:34:45 -0400 From: Sebastien Roy Subject: Re: KMF Certificate Name mapping extensions [PSARC/2010/177 FastTrack timeout 05/25/2010] In-reply-to: To: Jan Pechanec Cc: psarc@sun.com, Wyllys Ingersoll Message-id: <4BF40515.7070001@oracle.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 X-Source-IP: acsmt353.oracle.com [141.146.40.153] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A0B0206.4BF40545.0166:SCFMA4539814,ss=1,fgs=0 References: User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.9.1.8) Gecko/20100412 Lightning/1.0b1 Thunderbird/3.0.3 Status: RO Content-Length: 346 On 05/19/10 11:28 AM, Jan Pechanec wrote: > > hi, we were suggested to resend the case to the internal PSARC > alias. Who made this suggestion? This is unnecessary and merely generates duplicate messages in the case log. The appropriate internal lists receive messages sent to psarc-ext@sun.com. What are you actually trying to do? -Seb From Darren.Moffat@oracle.com Wed May 26 03:46:30 2010 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o4QAkUrm026319 for ; Wed, 26 May 2010 03:46:30 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail2sca.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o4QAkSmd021802; Wed, 26 May 2010 03:46:29 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0L3000E05WLGE800@nwk-avmta-1.sfbay.Sun.COM>; Wed, 26 May 2010 03:46:28 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0L30005CPWLG1Y90@nwk-avmta-1.sfbay.Sun.COM>; Wed, 26 May 2010 03:46:28 -0700 (PDT) Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id o4QAkRP6025403; Wed, 26 May 2010 10:46:27 +0000 (GMT) Received: from acsmt353.oracle.com (acsmt353.oracle.com [141.146.40.153]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id o4Q9aPU6021295; Wed, 26 May 2010 10:46:27 +0000 (GMT) Received: from abhmt016.oracle.com by acsmt354.oracle.com with ESMTP id 269386181274870672; Wed, 26 May 2010 03:44:32 -0700 Received: from [10.7.251.221] (/10.7.251.221) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 26 May 2010 03:44:32 -0700 Date: Wed, 26 May 2010 11:44:30 +0100 From: Darren J Moffat Subject: PSARC 2010/177 KMF Certificate Name mapping extensions To: PSARC-ext@sun.com, Jan Pechanec Message-id: <4BFCFB8E.1060606@Oracle.COM> Organization: Oracle Solaris Security MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 X-Source-IP: acsmt353.oracle.com [141.146.40.153] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4BFCFC03.0095:SCFMA4539814,ss=1,fgs=0 User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.9.1.8) Gecko/20100412 Lightning/1.0b1 OracleBeehiveExtension/1.0.0.0pre3 Thunderbird/3.0.3 Status: RO Content-Length: 233 I'm happy with the technical content of this case so it gets my +1 on the understanding that the project team will be delivering this with PSARC/2010/178 so that there is a mapper delivered with the framework. -- Darren J Moffat From Jan.Pechanec@Sun.COM Wed May 26 03:48:13 2010 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o4QAmDVg026342 for ; Wed, 26 May 2010 03:48:13 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail2sca.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o4QAmD6k023068 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 26 May 2010 03:48:13 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0L3000E0HWODX100@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 26 May 2010 03:48:13 -0700 (PDT) Received: from gmp-eb-inf-1.sun.com ([192.18.6.21]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0L300050PWOB27A0@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 26 May 2010 03:48:12 -0700 (PDT) Received: from fe-emea-13.sun.com (gmp-eb-lb-1-fe1.eu.sun.com [192.18.6.7] (may be forged)) by gmp-eb-inf-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id o4QAmBWh018531 for ; Wed, 26 May 2010 10:48:11 +0000 (GMT) Received: from conversion-daemon.fe-emea-13.sun.com by fe-emea-13.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0L3000700WJYE400@fe-emea-13.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 26 May 2010 11:47:53 +0100 (BST) Received: from rejewski ([unknown] [10.18.138.121]) by fe-emea-13.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0L300075JWNS29E0@fe-emea-13.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 26 May 2010 11:47:53 +0100 (BST) Date: Wed, 26 May 2010 12:47:34 +0200 (CEST) From: Jan Pechanec Subject: Re: PSARC 2010/177 KMF Certificate Name mapping extensions In-reply-to: <4BFCFB8E.1060606@Oracle.COM> Sender: Jan.Pechanec@Sun.COM X-X-Sender: jp161948@rejewski To: Darren J Moffat Cc: PSARC-ext@Sun.COM Message-id: MIME-version: 1.0 Content-type: TEXT/PLAIN; CHARSET=US-ASCII Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4BFCFB8E.1060606@Oracle.COM> Status: RO Content-Length: 340 On Wed, 26 May 2010, Darren J Moffat wrote: > I'm happy with the technical content of this case so it gets my +1 on the > understanding that the project team will be delivering this with PSARC/2010/178 > so that there is a mapper delivered with the framework. yes, that is correct. Thanks, J. -- Jan Pechanec http://blogs.sun.com/janp