Community articleGetDataByPath function (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 function retrieves a piece of data from a signature object.

Function

   Function GetDataByPath(
      thePath As String, 
      tagData As Boolean, 
      encoded As Boolean
      ) As String


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".
encodedBooleanTrue if the return data is base 64 encoded, or False if not. The function 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 function 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 function 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 an exception if an error occurs.

Example

The following function uses DereferenceEx and GetLiteralByRefEx to locate the signature item in a form. It then uses GetEngineCertificateList and GetDataByPath to locate a server signing certificate. Next, it uses GetSignature and GetDataByPath to get the signer's common name. Finally, it uses ValidateHMACWithSecret to determine if the HMAC signature is valid, and returns "Valid" or "Invalid", as appropriate.
   Function ValidateHMACSig(Form)
 
      Dim SigObject, XFDL  ' Objects
      Dim TheCerts  ' CertificateList
      Dim Cert, SigningCert  ' ICertificate
      Dim SignerName, SharedSecret, CommonName, SigItemRef  ' Strings
      Dim Validation  ' Integer
      Dim TempNode, SigNode  ' IFormNodeP
 
      Set TempNode = Form
      ' Get the SignatureButton node
      
      Set TempNode = Form.DereferenceEx(vbNullString, _
         "PAGE1.HMACSignatureButton", 0, UFL_ITEM_REFERENCE, Nothing)
 
      ' Get the name of the signature item
 
      SigItemRef = TempNode.GetLiteralByRefEx(vbNullString, "signature", _
         0, vbNullString, Nothing)
 
      ' Get the signature item node
 
      Set SigNode = TempNode.DereferenceEx(vbNullString, SigItemRef, 0, _
         UFL_ITEM_REFERENCE, Nothing)
 
      ' Get available server certificates for Generic RSA signing
 
      Set XFDL = CreateObject("PureEdge.xfdl_XFDL")
      Set TheCerts = XFDL.GetEngineCertificateList("Generic RSA", 1) 
         ' vbNull
 
      ' Locate the certificate that has a common name of "User1-CP.02.01".
      ' This is the certificate we will use when verifying the signature.
 
      For Each Cert in TheCerts
         CommonName = Cert.GetDataByPath("HMACSigner: CN", _
            False, 1) ' vbNull
         If CommonName = "User1-CP.02.01" Then
            Set SigningCert = Cert
         End If
 
      Next
 
      ' Get the signature object from the signature node
 
      Set SigObject = SigNode.GetSignature
 
      ' Get the signer's name from the signature object
 
      SignerName = SigObject.GetDataByPath("HMACSigner: CN", _
         False, 1) ' vbNull
 
      ' Include code that matches the signer's identity to a shared secret,
      ' and sets SharedSecret to match. In most cases, this would be a
      ' database lookup. For the purposes of this example, we will simply
      ' assign a value to SharedSecret.
 
      SharedSecret = "secret"
 
      ' Validate the signature
 
      Validation = SigNode.ValidateHMACWithSecret(SharedSecret, _
         SigningCert, 1) ' vbNull
 
      ' Check the validation code and return either "Valid" or "Invalid"
 
      If Validation = UFL_DS_OK Then
         ValidateHMACSig = "Valid"
      Else
         ValidateHMACSig = "Invalid"
      End If
 
   End Function


Parent topic:
Signature functions