SecureTime API Toolkit
Toolkit Home  

DgsTSGetParam


The DgsTSGetParam function accepts an encoded TSTInfo and decodes the individual attributes.

DWORD DgsTSGetParam(
  BYTE *pbTSTInfo,        // in
  DWORD pcbTSTInfo,       // in
  DWORD dwParamType,      // in
  void *pvData,           // out
  DWORD *pcbData          // in/out

Parameters

pbTSTInfo
The encoded value of TSTInfo.  This is the eContent portion of EncapsulatedContentInfo.   Begins with the tag and length of the OCTET STRING.
If using the MicroSoft CryptoAPI then this is the handle to result of CryptMsgGetParam call using CMSG_CONTENT_PARAM.
pcbTSTInfo
The length of  pbTSTInfo
dwParamType
DWORD indicating the parameter types of data to be retrieved. The type of data to be retrieved determines the type of structure to use for pvData.
dwParamType value Meaning pvData type required
DGS_VERSION The IETF specification version used to encode time stamp token. The current release returns 1.
DGS_POLICY Object identifier for TSA policy under which the time stamp was issued. DigiStamp servers repond with policy 1.3.6.1.4.1.8291.1.1 This policy stipulates that the private key is not accessible to any party, the key is stored in NIST certified hardware (at minimum level 3), the time stamps are created inside this tamper detecting hardware. The complete policy is available from DigiStamp.
DGS_HASH_ALGORITHM Retrieves the hash algorithm associated with the HASH that has been time-stamped SHA-1, SHA256, SHA384, SHA512, Ripemd
DGS_HASH_ALGORITHM_PARAM Retrieve the parameters used by the hash algorithm
DGS_HASH_DATA Retrieves the hash value stored in the message when it was created. A BYTE buffer to receive the hash value.
DGS_SERIAL_NUMBER A unique serial number is part of each time stamp. A BYTE buffer to receive the DER encoded value of the serial number. See function DgsDecInt to decode.
DGS_GENERALIZED_TIME String representation of the GMT time of the time stamp creation.   In the form YYMMDDHHMMSS.SSSZ
DGS_ACCURACY_SECONDS The potential time deviation from official time source. seconds
DGS_ACCURACY_MILLIS The potential time deviation from official time source in addition to the seconds. milli seconds. Can be null.
DGS_ACCURACY_MICROS The potential time deviation from official time source in addition to the seconds and milli seconds. micro seconds. Can be null.
DGS_ORDERING Indicates if the order of multiple time stamps can be determined the the time value in GENERALIZE_TIME
DGS_NONCE A random integer value supplied by the client to be incorporated into the time stamp. This current version of the C toolkit only supports up to 4 bytes (the Java version support full 20 byte nonce.) A BYTE buffer to receive the DER encoded value of the nonce. See function DgsDecInt to decode.
DGS_TSA Additional information, can provide means to contact TSA. Always returns NULL in this release
DGS_EXTENSIONS Additional information, can be used for future extensions to protocol. Always returns NULL in this release


pvData
Pointer to a buffer that receives the data retrieved. The form of this data will vary, depending on the parameter type.  The caller of the function is responsible for deleting the memory allocated to hold this value.

When processing the data returned in this buffer, applications need to use the actual size of the data returned. The actual size can be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer. If pvData is passed in as a NULL pointer then the function returns the size of buffer needed in the pcbData parameter. It's recommended that the caller program allocate a buffer of 64 bytes and reuse the same buffer to get different parameters.

pcbData
Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pvData parameter. When the function returns, the variable pointed to by the pcbData parameter contains the number of bytes stored in the buffer.

Return Values

If the function succeeds, the return value is zero.  Return codes other that zero are describe below.  The numberical values are defined of the toolkit header files..

Error code Description
DGS_E_INVALID_PARAM_TYPE The parameter type is invalid.
DGS_FORMAT The message is not encoded as expected.

 

  28 January, 2005

Home   Feedback      Related Links   Contact Us   Mailing List    Privacy Statement
Copyright 2000-2005 DigiStamp, Inc.
All Rights Reserved
SecureTime, IPVault, IPProtector, and e-TimeStamp  are service marks of the DigiStamp, Inc.