derhelp.h

voltage 公司提供的一个开发Ibe的工具包

   VoltTime *theTime
));

/* Utility function, decode a tag and len.
 * <p>This function will read the tag and return it at the address
 * given by theTag. It will determine the length of the length octets
 * and return that value at the address given by lengthLen. Finally, it
 * will determine what the length is and return it at the address given
 * by valueLen.
 * <p>If there is not enough data to complete a tag and len, the
 * routine will return VT_ERROR_INVALID_INPUT_LEN. If the function
 * determines that the data at encoding is not a tag and len, it will
 * return VT_ERROR_INVALID_ENCODING. This can happen if the length is
 * represented by a number that would not fit into an unsigned int.
 * <p>If the length is indefinite length, the function will return a
 * lengthLen of 1 and a valueLen of 0x80. It is the responsibility of
 * the caller to recognize that if valueLen is 0x80 and lengthLen is 1,
 * then the length is indefinite. If the length is definite and the
 * length is 0x80, then the lengthLen will be 2.
 * <p>The total number of bytes read is not returned because that will
 * be simply 1 + lengthLen.
 *
 * @param encoding
 * @param encodingLen
 * @param theTag
 * @param lengthLen
 * @param valueLen
 * @return an int, 0 if the function completed successfully or a
 * non-zero error code.
 */
int VOLT_CALLING_CONV VoltDecodeTagAndLen VOLT_PROTO_LIST ((
   unsigned char *encoding,
   unsigned int encodingLen,
   unsigned int *theTag,
   unsigned int *lengthLen,
   unsigned int *valueLen
));

/* Utility function: Determine the length of the L portion of a TLV
 * and then the V's length (TLV = tag len value).
 *
 * @param encoding
 * @param encodingLen
 * @param lengthLen
 * @param valueLen
 * @return an int, 0 if the function completed successfully or a
 * non-zero error code.
 */
int VOLT_CALLING_CONV VoltDecodeDerLength VOLT_PROTO_LIST ((
   unsigned char *encoding,
   unsigned int encodingLen,
   unsigned int *lengthLen,
   unsigned int *valueLen
));

/* Utility function, how long will the length octets be in a DER
 * encoding, if the length of the data is the amount given.
 * <p>The DER of an ASN.1 unit is
 *    tag len data.
 * The tag is one byte long. The len is 1, 2, 3, or more bytes long
 * depending on the length.
 *    0x00 - 0x7f    len is 1 byte long.
 *    0x80 - 0xff    len is 2 bytes long (81 len, e.g. 81 A2)
 *    0x100 - 0xffff len is 3 bytes long (82 len, e.g. 82 04 11)
 *      and so on.
 *
 * @param length The length of the data.
 * @return An unsigned int, the length of the length octets.
 */
unsigned int VOLT_CALLING_CONV VoltDetermineDerLengthLen VOLT_PROTO_LIST ((
   unsigned int length
));

/* Utility function, write out the tag and length in a "tag len" DER
 * encoding.
 * <p>This function does no argument checking, it is the caller's
 * responsibility to pass in a buffer big enough.
 * <p>See also VoltDetermineDerLengthLen.
 *
 * @param buf The buffer into which the function will place the length
 * octets.
 * @param tag The tag to place.
 * @param length The length to place.
 * @return The number of bytes placed into the buffer.
 */
unsigned int VOLT_CALLING_CONV VoltWriteDerTagAndLen VOLT_PROTO_LIST ((
   unsigned char *buf,
   unsigned int tag,
   unsigned int length
));

/* The element field is the buffer containing the element.
 * The elementSize field is how much memory allocated for the buffer.
 * The elementLen field is how much of the element is in there.
 * The tlvLen field is the length of the value.
 * The totalLen field is the length of the entire TLV.
 * The explicitTag field is what was captured from an encoding, if
 * there was an EXPLICIT.
 * The explicitLen field is what the EXPLICIT length is.
 * The complete field indicates whether an element has been captured,
 * if 0 it is not yet complete, if not zero, the element is done.
 * The EXPLICIT tag and explicitLen play no role in the computation of
 * totalLen, elementLen or tlvLen.
 * For example, for
 *   06 05 28 15 86 02 01
 * the tlvLen is 5, the totalLen is 7. If the full element is in the
 * buffer, the elementLen would also be 7. However, it is possible to
 * have only a partial element. For instance, for
 *   06 05 28 15
 * the tlvLen is still 5 (the decoder would be able to decode the
 * length), the totalLen is still 7, but for now the elementLen is 4.
 * It is possible a caller only wants a tag and len, so an element
 * would consist only of those octets. For example, for
 *   30 80 0b 2c
 * the tlvLen would be 2860 (0b 2c), the totalLen would be 4 and the
 * elementLen would be 4.
 * If elementLen and totalLen are equal, the element is completely
 * captured.
 */
typedef struct
{
  unsigned char *element;
  unsigned int elementSize;
  unsigned int elementLen;
  unsigned int tlvLen;
  unsigned int totalLen;
  unsigned int explicitTag;
  unsigned int explicitLen;
  unsigned int complete;
} VoltDerElement;

/* This function collects the next DER element into the element buffer
 * of the derElement struct.. The function will collect the tag/length
 * and optionally value of the DER TLV. If the valueFlag is 0, don't
 * collect the value, just the tag/len. If valueFlag is not 0, collect
 * the value as well.
 * <p>The function will also check to see if the tag of the element is
 * the expectedTag. If not, the function returns an error.
 * <p>If this function encounters indefinite length, it will return an
 * error.
 * <p>The routine will collect what it can. If an entire element is not
 * available, it will store whatever part of the encoding is there.
 * <p>The function will set the complete field of the derElement to 0
 * if it was not able to completely capture the element, and to a
 * non-zero value if it was able to completely capture the element.
 * <p>The function will also deposit at the address given by bytesRead
 * the number of bytes from the encoding the function collected.
 * <p>After an element has been captured, it is the responsibility of
 * the caller to reset the struct so that it can be used for another
 * capture. The function VoltResetDerElement will do this.
 * <p>It is also the responsibility of the caller to free the memory
 * allocated for element by this function.
 * <p>If the explicitFlag is set, the function will check to make sure
 * the EXPLICIT tag is correct, then check to make sure the actual tag
 * is correct. If the explicitTag is set and the valueFlag is 0, the
 * function will set the explicitTag field of the derElement to the tag
 * and set the explictLen to the length. It will then load into the
 * element buffer the tag/len of the regular tag. If the valueFlag is
 * not 0, the function will return the entire regular element. The
 * totalLen will NOT include the length of the EXPLICIT tag and len,
 * only the length of the regular tag and len, and, if requested the
 * length of the value.
 * <p>To collect only the EXPLICIT tag and len, leave explicitTag at 0,
 * and set expectedTag to the EXPLICIT value.
 *
 * @param libCtx The libCtx to use.
 * @param encoding The buffer containing the DER encoding.
 * @param encodingLen The max number of bytes from which to extract the
 * element.
 * @param explicitTag If 0, don't look for an EXPLICIT. If not zero, it
 * will be the expected EXPLICIT tag.
 * @param expectedTag What tag the caller is expecting to find.
 * @param valueFlag Indicates whether the function should capture the
 * value of the TLV or not.
 * @param derElement Where the element is to be stored.
 * @param bytesRead The address where the function will deposit the
 * number of bytes copied from encoding to the derElement struct.
 * @return an int, 0 if the function completed successfully or a
 * non-zero error code.
 */
int VOLT_CALLING_CONV VoltGetNextDerElement VOLT_PROTO_LIST ((
   VoltLibCtx *libCtx,
   unsigned char *encoding,
   unsigned int encodingLen,
   unsigned int explicitTag,
   unsigned int expectedTag,
   unsigned int valueFlag,
   VoltDerElement *derElement,
   unsigned int *bytesRead
));

#define VOLT_BOOLEAN_TAG         0x01
#define VOLT_INTEGER_TAG         0x02
#define VOLT_BIT_STRING_TAG      0x03
#define VOLT_OCTET_STRING_TAG    0x04
#define VOLT_OID_TAG             0x06
#define VOLT_UTF8_STRING_TAG     0x0c
#define VOLT_PRINT_STRING_TAG    0x13
#define VOLT_TELETEX_STRING_TAG  0x14
#define VOLT_SEQUENCE_TAG        0x30
#define VOLT_SET_TAG             0x31
#define VOLT_UTC_TIME_TAG        0x17
#define VOLT_GEN_TIME_TAG        0x18

/* Reset the derElement to a state where it can collect a new element.
 * <p>This function will not free or overwrite the element buffer, only
 * reset the various length or tag fields.
 * <p>This function does not check the validity of the input argument,
 * it is the responsibility of the caller not to pass a NULL and to
 * pass a valid DerElement.
 *
 * @param derElement The VoltDerElement to reset.
 * @return none.
 */
void VOLT_CALLING_CONV VoltResetDerElement VOLT_PROTO_LIST ((
   VoltDerElement *derElement
));

/* A memcpy to call from inside Asn1 objects. They don't have access to
 * the libCtx.
 * <p>The two buffers should not overlap.
 *
 * @param dest The destination buffer into which the bytes will be
 * copied.
 * @param source The originating buffer from which the bytes will be
 * copied.
 * @param count How many bytes to copy.
 * @return none
 */
void VOLT_CALLING_CONV Asn1Memcpy VOLT_PROTO_LIST ((
   unsigned char *dest,
   unsigned char *source,
   unsigned int count
));

/* A memset to call from inside Asn1 objects. They don't have access to
 * the libCtx.
 *
 * @param dest The destination buffer which will be set.
 * @param value The value to set, the function will use the low order
 * byte and ignore the rest of this unsigned int.
 * @param count How many bytes to set.
 * @return none
 */
void VOLT_CALLING_CONV Asn1Memset VOLT_PROTO_LIST ((
   unsigned char *dest,
   unsigned int value,
   unsigned int count
));

#ifdef __cplusplus
}
#endif

#endif /* _DER_HELP_H */