Community articlegetDataByPath method (Signature)
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Description

This method retrieves a piece of data from a signature object.

Method

   public String getDataByPath(
      String thePath,
      boolean tagData,
      BooleanHolder encoded,
      ) throws UWIException;


Parameters

ExpressionTypeDescription
thePathStringThe path to the data you want to retrieve. See the Notes section for more information on data paths.
tagDatabooleantrue if the path should be prepended to the data, or false if not. If the path is prepended, an equals sign (=) is used as a separator.
For example, suppose the path is "Signing Cert: Issuer: CN" and the data is "IBM®". If true, the path will be prepended, producing "CN=IBM". If false, the path will not be prepended, and the result will be "IBM".
encodedBooleanHoldertrue if the return data is base 64 encoded, or false if not. The method returns binary data in base 64 encoding.


Notes

About Data Paths
Data paths describe the location of information within a signature, just like file paths describe the location of files on a disk. You describe the path with a series of colon separated tags. Each tag represents either a piece of data, or an object that contains further pieces of data (just like directories can contain files and subdirectories).
For example, to retrieve the version of a signature, you would use the following data path:
   Demographics

However, to retrieve the signer's common name, you first need to locate the signing certificate, then the subject, then finally the common name within the subject, as follows:
   SigningCert: Subject: CN

Some tags may contain more than one piece of information. For example, the issuer's organizational unit may contain a number of entries. You can either retrieve all of the entries as a comma separated list, or you can specify a specific entry by using a zero-indexed element number.
For example, the following path would retrieve a comma separated list:
   SigningCert: Issuer: OU

Adding an element number of 0 would retrieve the first organizational unit in the list, as shown:
   SingingCert: Issuer: OU: 0

Signature Tags
The following table lists the tags available in a signature object. Note that Clickwrap and HMAC Clickwrap signatures have additional tags, (detailed in Clickwrap Signature Tags and HMAC Clickwrap Tags ).
Table 2. signature tags
TagDescription
EngineThe security engine used to create the signature. This is an object that contains further information, as detailed in Security Engine Tags.
SigningCertThe certificate used to create the signature. This is an object that contains further information, as detailed in Certificate Tags. Note that this object does not exist for Clickwrap or HMAC Clickwrap signatures.
HashAlgThe hash algorithm used to create the signature.
CreateDateThe date on which the signature was created.
DemographicsA string describing the signature.
LastVerificationStatusA short representing the verification status of the signature. This is updated whenever the signature is verified. See verifySignature method for a complete list of the possible values.


Clickwrap Signature Tags
The following table lists additional tags available in both Clickwrap and HMAC Clickwrap signatures. Note that HMAC Clickwrap signatures have further tags (detailed in HMAC Clickwrap Tags ).
Table 3. clickwrap signature tags
TagDescription
TitleTextThe text for the Windows® title bar of the signature dialog box.
MainPromptThe text for the title portion of the signature dialog box.
MainTextThe text for the text portion of the signature dialog box.
Question1TextThe first question in the signature dialog box.
Answer1TextThe signer's answer.
Question2TextThe second question in the signature dialog box.
Answer2TextThe signer's answer.
Question3TextThe third question in the signature dialog box.
Answer3TextThe signer's answer.
Question4TextThe fourth question in the signature dialog box.
Answer4TextThe signer's answer.
Question5TextThe fifth question in the signature dialog box.
Answer5TextThe signer's answer.
EchoPromptText that the signer must echo to create a signature.
EchoTextThe signer's response to the echo text.
ButtonPromptThe text that provides instructions for the Clickwrap signature buttons.
AcceptTextThe text for the accept signature button.
RejectTextThe text for the reject signature button.


Certificate Tags
The following table lists the tags available in a certificate object. Note that Clickwrap and HMAC Clickwrap signatures do not contain these tags.
Table 4. certificate tags
TagDescription
SubjectThe subject's distinguished name. This is an object that contains further information, as detailed in Distinguished Name Tags .
IssuerThe issuer's distinguished name. This is an object that contains further information, as detailed in Distinguished Name Tags .
IssuerCertThe issuer's certificate. This is an object that contains the complete list of certificate tags.
EngineThe security engine that generated the certificate. This is an object that contains further information, as detailed in Security Engine Tags .
VersionThe certificate version.
BeginDateThe date on which the certificate became valid.
EndDateThe date on which the certificate expires.
SerialThe certificate's serial number.
SignatureAlgThe signature algorithm used to sign the certificate.
PublicKeyThe certificate's public key.
FriendlyNameThe certificate's friendly name.


Distinguished Name Tags
The following table lists the tags available in a distinguished name object. Note that Clickwrap and HMAC Clickwrap signatures do not contain these tags.
Table 5. distinguished name tags
TagDescription
CNThe common name.
EThe email address.
TThe title.
OThe organization.
OUThe organizational unit.
CThe country.
LThe locality.
STThe state.
AllThe entire distinguished name.


HMAC Clickwrap Tags
The following table lists the tags available in HMAC Clickwrap signature. Note that these tags are in addition to both the regular Signature Tags and the Clickwrap Signature Tags .
Table 6. HMAC clickwrap tags
TagDescription
HMACSignerA string indicating which answers store the signer's ID.
HMACSecretA string indicating which answers store the signer's secret.
NotarizationThe notarizing signatures. This is one or more signature objects that contain further information, as detailed in Signature Tags . There can be any number of notarizing signatures. Use an element number to retrieve a specific signature. For example, to get the first notarizing signature use:
   Notarization: 0

If no element number is provided, the data will be retrieved from the first valid notarizing signature found. If no valid notarizing signatures are found, the method will return null.


Security Engine Tags
The following table lists the tags available in the security engine object:
Table 7. security engine tags
TagDescription
NameThe name of the security engine used by the server.
HelpThe help text for the security engine.
HashAlgA hash algorithm supported by the security engine.


Returns

A string containing the certificate data (null if no data is found), or throws a generic exception (UWIException) if an error occurs.

Example

The following example uses getSignature to get the signature object from the signature node, and uses getDataByPath to get the signer's identity from the signature object. It then calls validateHMACWithSecret to validate the signature.
   public short checkSignature(FormNodeP theSignatureNode, Certificate 
      theServerCert)
   {
   Signature theSignatureObject;
   String theSecret;
   String signerCommonName;
   BooleanHolder encodedData;
   IntHolder theStatus;
   short validation;
   
      theSignatureObject = theSignatureNode.getSignature();
      encodedData = new BooleanHolder();
      if ((signerCommonName = theSignatureObject.getDataByPath(
         "HMACSigner: CN", false, encodedData)) == null)
      {
         throw new UWIException("Could not determine signer's name.");
      }
 
      /* Include external code that matches the signer's identity to a shared 
         secret, and sets theSecret to match.  This is most likely a
         database lookup. */
 
      theStatus = new IntHolder();
      
      validation = theSignatureNode.validateHMACWithSecret(theSecret, 
         theServerCert, theStatus);
 
      /* Check the status in case the process required user input. */
 
      if (theStatus.value != SecurityUserStatusType.SUSTATUS_OK)
      {
         throw new UWIException("Validation required user input.");
      }
      
      theSignatureObject.release();
      return(validation);
   }


Parent topic:
Signature class