derhelp.h

IBE是一种非对称密码技术

 * million terabytes or 18 billion Gigabytes).
 * <p>If the length is indefinite length, the function will return a
 * lengthLen of 1 and a valueLenLo of 0x80. It is the responsibility of
 * the caller to recognize that if valueLenLo 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.
 * <p>Because most calls to this function will expect to find small
 * lengths, you can tell the function to return an error if the length
 * is too large. That is the purpose of the sizeofResult arg. This
 * value can be 0, 2, 4, or 8. If you pass 0, the function returns the
 * LenLo and LenHi. If you pass 2, the function makes sure the
 * resulting length fits in 2 bytes (0 <= length <= 0xffff = 65535). If
 * you pass 4, the function makes sure the resulting length fits in 4
 * bytes. Passing 8 is equivalent to passing 0. In fact, passing any
 * value other than 2 or 4 is equivalent to passing 0 (note, if you
 * pass 3, the function will not check to make sure the resulting
 * length fits in 3 bytes, it will make sure it fits in 8).
 * <p>The function does not check the return args (theTag, lengthLen,
 * valueLenLo, and valueLenHi), it is the responsibility of the caller
 * to pass valid pointers.
 * <p>Whatever you pass for the sizeofResult, you must pass a valid
 * pointer to a UInt32 for the valueLenHi.
 *
 * @param libCtx
 * @param encoding
 * @param encodingLen
 * @param theTag
 * @param lengthLen
 * @param valueLenLo
 * @param valueLenHi
 * @param sizeofResult
 * @return an int, 0 if the function completed successfully or a
 * non-zero error code.
 */
int VOLT_CALLING_CONV VoltDecodeTagAndLen VOLT_PROTO_LIST ((
   VoltLibCtx *libCtx,
   unsigned char *encoding,
   unsigned int encodingLen,
   unsigned int *theTag,
   unsigned int *lengthLen,
   UInt32 *valueLenLo,
   UInt32 *valueLenHi,
   unsigned int sizeofResult
));

/* 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
 * <pre>
 * <code>
 *    tag len data.
 * </code>
 * </pre>
 * The tag is one byte long. The len is 1, 2, 3, or more bytes long
 * depending on the length.
 * <pre>
 * <code>
 *    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.
 * </code>
 * </pre>
 * <p>The caller passes the length in 64 bits, split into two 32-bit
 * values, lo and hi.
 *
 * @param valueLenLo The low part of the length of the data.
 * @param valueLenHi The high part of the length of the data.
 * @return An unsigned int, the length of the length octets.
 */
unsigned int VOLT_CALLING_CONV VoltDetermineDerLengthLen VOLT_PROTO_LIST ((
   UInt32 valueLenLo,
   UInt32 valueLenHi
));

/* 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. Use that function to
 * determine the required size.
 * <p>The length to write is given as a 64-bit value, split into two
 * 32-bit numbers.
 *
 * @param buf The buffer into which the function will place the length
 * octets.
 * @param tag The tag to place.
 * @param valueLenLo The low 32 bits of the length.
 * @param valueLenHi The high 32 bits of the length.
 * @return The number of bytes placed into the buffer.
 */
unsigned int VOLT_CALLING_CONV VoltWriteDerTagAndLen VOLT_PROTO_LIST ((
   unsigned char *buf,
   unsigned int tag,
   UInt32 valueLenLo,
   UInt32 valueLenHi
));

/* The element field is the buffer containing the element.
 * The elementSize field is how much memory is currently allocated for
 * the buffer.
 * The elementLen field is how much of the element is in there.
 * The valueLen field is the length of the value.
 * The totalLen field is the length of the entire TLV (value len plus 1
 * for the tag plus lengthLen).
 * 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 valueLen 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 valueLen 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 valueLen would be 2,860 (b2c), 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;
#if VT_64_BIT_LENGTH == 64
  VtUInt64        valueLen;
  VtUInt64        totalLen;
  VtUInt64        explicitLen;
#else
  unsigned int    valueLen;
  unsigned int    totalLen;
  unsigned int    explicitLen;
#endif
  unsigned int    explicitTag;
  unsigned int    tag;
  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 the 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, if 0, don't capture, if not 0, capture.
 * @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 */