Problem

With IDM3.5 the Lotus Notes driver shim gains a number of new features. A major new feature of interest is the ability to finally set the password on the Notes ID file.

For those who do not know about Lotus Notes, it has a unique feature: it uses certificates in a very serious way for pretty much everything - which is a good thing.

The downside is that the authentication via the client is certificate-based, and the user's certificate is stored in the Notes ID file. The 'password' to login to the client is actually a password to decrypt the private key stored in the ID file.

Personally, I think users should never have their grubby little hands on their private key. In contrast, eDirectory stores the private key for every user in the directory as an attribute called Private Key. This is such an important part of the authentication system for eDirectory that pretty much any tool you want to use cannot touch the Private Key attribute. Try it with DSBrowse on a server, and you will see Private Key defined in Schema, but you will not be able to see it on a user. I imagine NTS with DSDump can get at it, but that is part of the reason we do not get to use DSDump, and only NTS does.

The developer, Perry Nuffer wrote a truly excellent article on how to use new feature, with much of all the steps involved. Check it out at:

https://community.microfocus.com/cyberres/idm/w/identity_mgr_tips/3361/upgrading-the-notes-driver-shim-in-idm-3-5

However, in trying to use that article I realized there are a number of things that are assumed you would do. One of them is that he assumes you have all the new polices that come in the default driver configuration with IDM 3.5. If you are upgrading an existing IDM 3.01 Notes driver, you probably will not blindly import the 3.5 config, since it may overwrite things you have customized.

Solution

Most important for the ID file password resetting to function is the Subscriber channel Command Transform, specifically the Password(Sub)-Transform Distribution Password rule.

From my perspective it looks like you can copy the XML from the new rule into your existing rules for the most part. In the IDM 3.5 default configuration, the new rule is now called the sub-ctp-TransformDistributionPassword rule.

The new rules add a number of things, and it looks like this:

 <rule>
  <description>Convert adds of the nspmDistributionPassword attribute to password element</description>
  <conditions>
    <and>
      <if-operation op="equal">add</if-operation>
      <if-op-attr name="nspmDistributionPassword" op="available"/>
    </and>
  </conditions>
  <actions>
    <!-- Change add-attr element for the nspmDistributionPassword attribute to password elements-->
    <do-set-dest-password>
      <arg-string>
        <token-op-attr name="nspmDistributionPassword"/>
      </arg-string>
    </do-set-dest-password>
    <!-- Remove add-attr element for the nspmDistributionPassword attribute -->
    <do-strip-op-attr name="nspmDistributionPassword"/>
  </actions>
</rule>

On an add event, if nspmDistributionPassword is available, it fires and says, use the set password function (which each shim handles dependant on what the target OS or application needs). Now the nspmDistributionPassword modify attribute is no longer neccasary, so it is stripped from the document.

<rule>
  <description>Convert modifies of a nspmDistributionPassword
attribute to a modify password operation</description>
  <conditions>
    <and>
      <if-operation op="equal">modify</if-operation>
      <if-class-name op="equal">User</if-class-name>
      <if-op-attr name="nspmDistributionPassword" op="available"/>
      <if-xpath op="true">modify-attr[@attr-name='nspmDistributionPassword']/remove-value/value</if-xpath>
    </and>
  </conditions>
  <actions>
    <do-set-dest-password>
      <arg-string>
        <token-op-attr name="nspmDistributionPassword"/>
      </arg-string>
    </do-set-dest-password>
    <do-set-xml-attr expression="../modify-password" name="allow-userid-password-set">
      <arg-string>
        <token-text>false</token-text>
      </arg-string>
    </do-set-xml-attr>
    <do-set-xml-attr expression="../modify-password" name="allow-http-password-set">
      <arg-string>
        <token-text>true</token-text>
      </arg-string>
    </do-set-xml-attr>
    <do-set-xml-attr expression="../modify-password" name="allow-adminp-support">
      <arg-string>
        <token-text>true</token-text>
      </arg-string>
    </do-set-xml-attr>
    <do-append-xml-element expression="../modify-password" name="old-password"/>
    <do-append-xml-text expression="../modify-password/old-password"
notrace="true">
      <arg-string>
        <token-xpath
expression="../modify/modify-attr[@attr-name='nspmDistributionPassword']/remove-value/value/text()"/>
      </arg-string>
    </do-append-xml-text>
    <!-- Add an event-id attribute to the modify-password command we
just added, required for operation data -->
    <do-set-xml-attr expression="../modify-password" name="event-id">
      <arg-string>
        <token-text>subscriber-password-set-1</token-text>
      </arg-string>
    </do-set-xml-attr>
    <!-- Remove modify-attr element for the nspmDistributionPassword
attribute -->
    <do-strip-op-attr name="nspmDistributionPassword"/>
  </actions>
</rule>

In the case of a modify event that includes the attribute nspmDistributionPassword, this rule fires.

What it does is a little more complex. The assumption is that you set your Engine Control Value, 'Use password event values' (ecnm_pevvl) to true, so that eDirectory provides two content-suppressed values for each password change. It looks something like this in the document:

<nds dtdversion="3.5" ndsversion="8.x">
  <source>
    <product version="3.5.1.20070411 ">DirXML</product>
    <contact>Novell, Inc.</contact>
  </source>
  <input>
    <modify class-name="User" event-id="pwd-publish"
qualified-src-dn="C=US\O=ACMEC\OU=idmusers\CN=TIzzy"
src-dn="\TIDM\US\ACEMEC\idmusers\TIzzy" src-entry-id="33486"
timestamp="1183149461#6">
      <association state="associated">tizzy</association>
    <modify-attr attr-name="nspmDistributionPassword"><!-- content
suppressed --><!-- content suppressed -->
    </modify-attr>
  </modify>
  </input>
</nds>

The first value is the old password and the second value is the new password. I think. The more I look at it, the more I get confused.

This test from the Condition part of the rule is just checking to make sure there are two values. If you drop a value of the modify-attr and there is still a value, ergo there were two when you started.

<if-xpath op="true">modify-attr[@attr-name='nspmDistributionPassword']/remove-value/value*lt;/if-xpath>

The rule does the same thing as in the Add rule, which is to call the set-password function, for the Application. The important thing this rule does that the previous IDM 3.01 configuration did not is to set the value of the <old-password> tag.

The Notes API being used to do this password changing on the ID file requires the old password to decrypt the private key, and the new password to re-encrypt the file. You can imagine that this is an impossible task without the old password.

Administrative password resets are non-trivial in the Notes world for all the above reasons.

The rules adds some settings that tell the driver to turn on some functionality, and adds some operation data payloads for tracking the events.

Finally the modify-attribute of nspmDistributionPassword is removed from the original document, which is basically an empty Modify document now.

Thus the final rule in the set, if there is an empty modify document, veto it to clean up after ourselves.

<rule>
		<description>Block empty modify operations</description>
		<conditions>
			<and>
				<if-operation op="equal">modify</if-operation>
				<if-xpath op="not-true">modify-attr</if-xpath>
			</and>
		</conditions>
		<actions>
			<!-- Veto empty modify -->
			<do-veto/>
		</actions>
	</rule>
</policy>

If you do not modify this set of rules, you will not get the old-password element and the password changes will not happen.

There is another twist, which is a story for another day, about setting the path to the actual Notes.ID files. They need to be accessible to the driver shim via the file system.