RSA Security logo

RSA BSAFE Cert-C
API Reference

certattr.h File Reference

This file defines the Cert-C attribute API and data types.

#include "basetype.h"
#include "asn1pub.h"

Go to the source code of this file.

Data Structures

struct  POSTAL_ADDRESS
 Corresponds to the postal-address attribute's value. More...


Functions

int C_CreateAttributesObject (ATTRIBUTES_OBJ *attributesObj)
 Creates a new attributes object, storing the result in attributesObj. More...

int C_GetAttributesDER (ATTRIBUTES_OBJ attributesObj, unsigned char **der, unsigned int *derLen)
 Obtains the DER encoding of the value of attributesObj, storing a pointer to the DER encoding in der, and its length in derLen. More...

int C_SetAttributesBER (ATTRIBUTES_OBJ attributesObj, unsigned char *ber, unsigned int berLen)
 Updates the value of attributesObj with the BER-encoded attribute set given in ber and berLen. More...

int C_GetAttributeTypeCount (ATTRIBUTES_OBJ attributesObj, unsigned int *count)
 Obtains the number of attributes in the attribute list for attributesObj, and stores the result in count. More...

int C_GetAttributeType (ATTRIBUTES_OBJ attributesObj, unsigned int index, unsigned char **type, unsigned int *typeLen)
 Obtains the type of the attribute indexed by index in attributesObj's attribute list, storing a pointer to the attribute type in type and its length in typeLen. More...

int C_GetAttributeValueCount (ATTRIBUTES_OBJ attributesObj, unsigned char *type, unsigned int typeLen, unsigned int *count)
 Obtains the number of values for the attribute, of the type given by type, in the attribute list for attributesObj, and stores the result in count. More...

int C_GetAttributeValueDER (ATTRIBUTES_OBJ attributesObj, unsigned char *type, unsigned int typeLen, unsigned int valueIndex, unsigned char **valueDER, unsigned int *valueDERLen)
 Obtains a pointer to the DER encoding of the value (indexed by valueIndex), in the attribute of the type given by type and typeLen, in the attribute list for attributesObj. More...

int C_GetStringAttribute (ATTRIBUTES_OBJ attributesObj, unsigned char *type, unsigned int typeLen, unsigned int valueIndex, int *valueTag, unsigned char **value, unsigned int *valueLen)
 Obtains the value tag and a pointer to the contents of the string-based value (indexed by valueIndex), in the attribute of the type given by type and typeLen, in the attribute list for attributesObj, and stores the tag in valueTag. More...

int C_DeleteAttributeType (ATTRIBUTES_OBJ attributesObj, unsigned char *type, unsigned int typeLen)
 Deletes the attribute with type type in the attribute list for attributesObj. More...

int C_AddAttributeValueBER (ATTRIBUTES_OBJ attributesObj, unsigned char *type, unsigned int typeLen, unsigned char *value, unsigned int valueLen)
 Adds an attribute value to the attribute list in attributesObj, using the BER encoding given in value. More...

int C_AddStringAttribute (ATTRIBUTES_OBJ attributesObj, unsigned char *type, unsigned int typeLen, int valueTag, unsigned char *value, unsigned int valueLen)
 Adds a string-based attribute value to the attribute with type type in the attribute list for attributesObj, using the tag valueTag and the string value given by value with length valueLen. More...

int C_GetAttributesURLEncoded (ATTRIBUTES_OBJ attributesObj, unsigned char **str, unsigned int *strLen)
 Obtains the URL encoding of the value of attributesObj, storing a pointer to the URL encoding in str and its length in strLen. More...

int C_GetAttributesNameValueEncoded (ATTRIBUTES_OBJ attributesObj, unsigned char *pInnerSep, unsigned char *pOuterSep, unsigned int flags, unsigned char **str, unsigned int *strLen)
 Obtains the URL encoding of the value of attributesObj, storing a pointer to the URL encoding in str and its length in strLen. More...

int C_SetAttributesURLEncoded (ATTRIBUTES_OBJ attributesObj, unsigned char *str, unsigned int strLen)
 Modifies the value of attributesObj with the URL-encoded attribute set given in str and strLen. More...

int C_SetAttributesNameValueEncoded (ATTRIBUTES_OBJ attributesObj, unsigned char *pInnerSep, unsigned char *pOuterSep, unsigned char *str, unsigned int strLen)
 Modifies the value of attributesObj with the URL-encoded attribute set given in str and strLen. More...

int C_ResetAttributesObject (ATTRIBUTES_OBJ attributesObj)
 Returns attributesObj to the state it was in after it was created by C_CreateAttributesObject(), freeing any memory that was held by the object. More...

void C_DestroyAttributesObject (ATTRIBUTES_OBJ *attributesObj)
 Destroys attributesObj, freeing the memory it occupied, and sets it to (ATTRIBUTES_OBJ)NULL_PTR. More...

int C_DeleteSigningTimeAttribute (ATTRIBUTES_OBJ attributesObj)
 Deletes the signing-time attribute in the attribute list for attributesObj. More...

int C_GetSigningTimeAttribute (ATTRIBUTES_OBJ attributesObj, UINT4 *signingTime)
 Obtains the value of the signing-time attribute in the attribute list for attributesObj and stores the result in signingTime. More...

int C_SetSigningTimeAttribute (ATTRIBUTES_OBJ attributesObj, UINT4 signingTime)
 Sets the value of the signing-time attribute in the attribute list for attributesObj to signingTime. More...

int C_DeleteChallengePasswordAttrib (ATTRIBUTES_OBJ attributesObj)
 Deletes the challenge-password attribute in the attribute list for attributesObj. More...

int C_GetChallengePasswordAttribute (ATTRIBUTES_OBJ attributesObj, int *valueTag, unsigned char **value, unsigned int *valueLen)
 Obtains the value of the challenge-password attribute in the attribute list for attributesObj. More...

int C_SetChallengePasswordAttribute (ATTRIBUTES_OBJ attributesObj, int valueTag, unsigned char *value, unsigned int valueLen)
 Sets the value of the challenge-password attribute in the attribute list for attributesObj. More...

int C_AddPostalAddressValue (ATTRIBUTES_OBJ attributesObj, POSTAL_ADDRESS *postalAddress)
 Adds a value to the postal-address attribute in the attribute list for attributesObj, using the information in postalAddress, which points to a POSTAL_ADDRESS structure. More...

int C_DeletePostalAddressAttribute (ATTRIBUTES_OBJ attributesObj)
 Deletes the postal-address attribute in the attribute list for attributesObj. More...

int C_GetPostalAddressValue (POSTAL_ADDRESS *postalAddress, ATTRIBUTES_OBJ attributesObj, unsigned int valueIndex)
 Obtains the value indexed by valueIndex in the postal-address attribute in the attribute list for attributesObj, and stores a pointer to the POSTAL_ADDRESS structure in postalAddress. More...

int C_GetPostalAddressValueCount (unsigned int *valueCount, ATTRIBUTES_OBJ attributesObj)
 Obtains the number of values for the postal-address attribute in the attribute list for attributesObj, and stores the result in valueCount. More...

Function Documentation

int C_AddAttributeValueBER (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    type,
unsigned int    typeLen,
unsigned char *    value,
unsigned int    valueLen
)  ;
 

Adds an attribute value to the attribute list in attributesObj, using the BER encoding given in value.

  • If there is already an attribute with the given type in the attribute list, the value is added to the list of values for that attribute type.
  • Otherwise, a new attribute is added to the attribute list with the given type and value.
A separate copy of the attribute value's BER encoding is allocated inside the attributes object, so value can be changed after the call to C_AddAttributeValueBER().
Parameters:
attributesObj This is both an input and output parameter; it is the attributes object.
type This input parameter is the attribute type.
typeLen This input parameter is the length of the attribute type.
value This input parameter is the attribute value.
valueLen This input parameter is the length of the attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_AddPostalAddressValue (  ATTRIBUTES_OBJ    attributesObj,
POSTAL_ADDRESS *    postalAddress
)  ;
 

Adds a value to the postal-address attribute in the attribute list for attributesObj, using the information in postalAddress, which points to a POSTAL_ADDRESS structure.

Parameters:
attributesObj This is both an input and an output parameter. As an input parameter, it is the attributes object that Cert-C should update with a new postal-address attribute. As an output parameter, it is the updated postal address.
postalAddress This input parameter is the postal-address attribute value.
  • The value for each of the lines in the POSTAL_ADDRESS structure points to a caller-defined buffer. If a postal-address attribute already exists in the attribute list, Cert-C adds this postal-address attribute value to the list of postal-address values.
  • Otherwise, Cert-C adds a new postal-address attribute to the attribute list with the value given in attributesObj. Cert-C allocates a separate copy of the information in the POSTAL_ADDRESS structure inside the attributes object, so the postalAddress value can be changed after this call to C_AddPostalAddressValue().
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_AddStringAttribute (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    type,
unsigned int    typeLen,
int    valueTag,
unsigned char *    value,
unsigned int    valueLen
)  ;
 

Adds a string-based attribute value to the attribute with type type in the attribute list for attributesObj, using the tag valueTag and the string value given by value with length valueLen.

Parameters:
attributesObj This is both an input and output parameter; it is the attributes object.
type This input parameter is the attribute type.
typeLen This input parameter is the length of the attribute type.
valueTag This input parameter is the tag for the attribute value.
value This input parameter is the attribute value. A string-based value is a simple format with a tag such as VT_PRINTABLE_STRING or VT_T61_STRING and a single-byte array for the contents, as opposed to a structured type such as a postal address. If there is already an attribute with the given type in the attribute list, Cert-C adds this value to the list of values for that attribute type. Otherwise, Cert-C adds a new attribute to the attribute list with the given type and value. Cert-C allocates a separate copy of the information inside the attributes object, so value can be changed after this call to C_AddStringAttribute().
valueLen This input parameter is the length of the attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_CreateAttributesObject (  ATTRIBUTES_OBJ *    attributesObj )  ;
 

Creates a new attributes object, storing the result in attributesObj. If C_CreateAttributesObject() is unsuccessful, no memory is allocated and attributesObj is set to (ATTRIBUTES_OBJ)NULL_PTR. Note that a new attributes object is not ready for use until its value has been set by a function such as C_SetAttributesBER(), C_AddAttributeValueBER(), or C_AddStringAttribute().

Parameters:
attributesObj This output parameter points to the location of the newly created attributes object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_DeleteAttributeType (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    type,
unsigned int    typeLen
)  ;
 

Deletes the attribute with type type in the attribute list for attributesObj. The attribute type is represented by the contents octets of its full DER encoding. If there is no attribute with the given type in the attribute list, an error is returned.

Parameters:
attributesObj This is both an input and output parameter; it is the attributes object.
type This input parameter is the attribute type.
typeLen This input parameter is the length of the attribute type.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_DeleteChallengePasswordAttrib (  ATTRIBUTES_OBJ    attributesObj )  ;
 

Deletes the challenge-password attribute in the attribute list for attributesObj. If the attribute is not in the attribute list, an error is returned.

Parameters:
attributesObj This is both an input and output parameter; it is the attributes object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_DeletePostalAddressAttribute (  ATTRIBUTES_OBJ    attributesObj )  ;
 

Deletes the postal-address attribute in the attribute list for attributesObj. If there is no postal-address attribute in the attribute list, an error is returned.

Parameters:
attributesObj This is both an input and output parameter; it is the attributes object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_DeleteSigningTimeAttribute (  ATTRIBUTES_OBJ    attributesObj )  ;
 

Deletes the signing-time attribute in the attribute list for attributesObj. If there is not already a signing-time attribute in the attribute list, an error is returned.

Parameters:
attributesObj This is both an input and output parameter; it is the attributes object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyAttributesObject (  ATTRIBUTES_OBJ *    attributesObj )  ;
 

Destroys attributesObj, freeing the memory it occupied, and sets it to (ATTRIBUTES_OBJ)NULL_PTR. If attributesObj is already (ATTRIBUTES_OBJ)NULL_PTR, or if it is not a valid attributes object, then no action is taken.

Parameters:
attributesObj This is both an input and an output parameter. As an input parameter, it is the attributes object that Cert-C should destroy. As an output parameter, it is (ATTRIBUTES_OBJ)NULL_PTR.
Returns:
None.

int C_GetAttributesDER (  ATTRIBUTES_OBJ    attributesObj,
unsigned char **    der,
unsigned int *    derLen
)  ;
 

Obtains the DER encoding of the value of attributesObj, storing a pointer to the DER encoding in der, and its length in derLen. Note: The fields returned from this function are read-only. You do not need to create any objects or items before calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
attributesObj This input parameter is the attributes object.
der This output parameter is a pointer to the DER-encoded attribute value in the attributes object.
derLen This output parameter is the length of the DER-encoded attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetAttributesNameValueEncoded (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    pInnerSep,
unsigned char *    pOuterSep,
unsigned int    flags,
unsigned char **    str,
unsigned int *    strLen
)  ;
 

Obtains the URL encoding of the value of attributesObj, storing a pointer to the URL encoding in str and its length in strLen. You must free the data returned by this function. The encoding format is described in Section 2.2 of RFC 1738. This function is used by some PKI service providers, and can also be used as a utility function. You can use an arbitrary string of characters to separate the name and the value in each name-value pair, and a different arbitrary string of characters to separate the name-value pairs from each other. This function is similar to the C_GetAttributesURLEncoded() function. The C_GetAttributesNameValueEncoded() function allows you to specify the separator characters in the URL encoding. The C_GetAttributesURLEncoded() function uses default values for the separator characters.

Parameters:
attributesObj This input parameter is the attributes object.
pInnerSep This input parameter specifies the character string that separates the name and the value in each name-value pair.
pOuterSep This input parameter specifies the character string that separates the name-value pairs from each other.
flags This input parameter specifies whether one of the following flags is used:
Flag Description
NV_FLAGS_SORTED Sort names by ASCII value. Sort longer names after shorter names when a shorter name is an exact prefix of a longer name.
NV_FLAGS_SUPPRESS_FINAL_SEP Suppress the final separator in the URL encoding.
str This output parameter is a pointer to the URL-encoded attribute value in the attributes object. A non-NULL pointer containing only a single NUL character is returned in *str, even if strLen==0. You must free this data.
strLen This output parameter is the length of the URL-encoded attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetAttributesURLEncoded (  ATTRIBUTES_OBJ    attributesObj,
unsigned char **    str,
unsigned int *    strLen
)  ;
 

Obtains the URL encoding of the value of attributesObj, storing a pointer to the URL encoding in str and its length in strLen. You must free the data returned by this function. The encoding format is described in Section 2.2 of RFC 1738. The C_GetAttributesURLEncoded() function is a variant of the C_GetAttributesNameValueEncoded() function that uses the following values for the separator characters and flags:
Separator Characters and Flags Value
Between name and value (pInnerSep) =
Between name-value pairs (pOuterSep) &
Flags (flags) NV_FLAGS_SORTED | NV_FLAGS_SUPPRESS_FINAL_SEP

Parameters:
attributesObj This input parameter is the attributes object.
str This output parameter is a pointer to the URL-encoded attribute value in the attributes object. A non-NULL pointer containing only a single NULL character is returned in *str, even if strLen==0. You must free this data.
strLen This output parameter is the length of the URL-encoded attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetAttributeType (  ATTRIBUTES_OBJ    attributesObj,
unsigned int    index,
unsigned char **    type,
unsigned int *    typeLen
)  ;
 

Obtains the type of the attribute indexed by index in attributesObj's attribute list, storing a pointer to the attribute type in type and its length in typeLen. The attribute type is represented by the contents octets of its full DER encoding.

Note: The fields returned from this function are read-only. You do not need to create any objects or items prior to calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
attributesObj This input parameter is the attributes object.
index This input parameter is the index of the attribute in the attribute list.
type This output parameter is a pointer to the attribute type at the indicated index in the attributes object.
typeLen This output parameter is the length of the attribute type.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetAttributeTypeCount (  ATTRIBUTES_OBJ    attributesObj,
unsigned int *    count
)  ;
 

Obtains the number of attributes in the attribute list for attributesObj, and stores the result in count.

Parameters:
attributesObj This input parameter is the attributes object.
count This output parameter is the number of attributes in the attribute list.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetAttributeValueCount (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    type,
unsigned int    typeLen,
unsigned int *    count
)  ;
 

Obtains the number of values for the attribute, of the type given by type, in the attribute list for attributesObj, and stores the result in count. The attribute type is represented by the contents octets of its full DER encoding.

Parameters:
attributesObj This input parameter is the attributes object.
type This input parameter is the attribute type.
typeLen This input parameter is the length of the attribute type.
count This output parameter is the number of attribute values in the attribute list.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetAttributeValueDER (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    type,
unsigned int    typeLen,
unsigned int    valueIndex,
unsigned char **    valueDER,
unsigned int *    valueDERLen
)  ;
 

Obtains a pointer to the DER encoding of the value (indexed by valueIndex), in the attribute of the type given by type and typeLen, in the attribute list for attributesObj. A pointer to the DER encoding is stored in valueDER and its length in valueDERLen. The value index starts at 0 (zero). The attribute type is represented by the contents octets of its full DER encoding.

Note: The fields returned from this function are read-only. You do not need to create any objects or items prior to calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
attributesObj This input parameter is the attributes object.
type This input parameter is the attribute type.
typeLen This input parameter is the length of the attribute type.
valueIndex This input parameter is the index of the valueDER in the list of values for this attribute type.
valueDER This output parameter is the object's DER-encoded value.
valueDERLen This output parameter is the length of the object's DER-encoded value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetChallengePasswordAttribute (  ATTRIBUTES_OBJ    attributesObj,
int *    valueTag,
unsigned char **    value,
unsigned int *    valueLen
)  ;
 

Obtains the value of the challenge-password attribute in the attribute list for attributesObj. It then stores the value tag for the challenge password in valueTag, and a pointer to the attribute value and length in value and valueLen. If there is no challenge-password attribute in the attribute list, an error is returned.

Note: The fields returned from this function are read-only. You do not need to create any objects or items prior to calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
attributesObj This input parameter is the attributes object.
valueTag This output parameter is the tag for the attribute value. It is either VT_PRINTABLE_STRING or VT_T61_STRING.
value This output parameter is the attribute value.
valueLen This output parameter is the length of the attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPostalAddressValue (  POSTAL_ADDRESS *    postalAddress,
ATTRIBUTES_OBJ    attributesObj,
unsigned int    valueIndex
)  ;
 

Obtains the value indexed by valueIndex in the postal-address attribute in the attribute list for attributesObj, and stores a pointer to the POSTAL_ADDRESS structure in postalAddress. The value index starts at 0 (zero).

Note: The fields returned from this function are read-only. You do not need to create any objects or items prior to calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
postalAddress This output parameter is the postal-address attribute value. postalAddress is a read-only value; do not delete or modify it. It is undefined after the attribute is modified or after attributesObj is modified or destroyed.
attributesObj This input parameter is the attributes object.
valueIndex This input parameter is the attribute list's value index.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetPostalAddressValueCount (  unsigned int *    valueCount,
ATTRIBUTES_OBJ    attributesObj
)  ;
 

Obtains the number of values for the postal-address attribute in the attribute list for attributesObj, and stores the result in valueCount.

Parameters:
valueCount This output parameter is the number of attribute values.
attributesObj This input parameter is the attributes object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetSigningTimeAttribute (  ATTRIBUTES_OBJ    attributesObj,
UINT4 *    signingTime
)  ;
 

Obtains the value of the signing-time attribute in the attribute list for attributesObj and stores the result in signingTime. The time is given as the number of seconds since 12:00 A.M. GMT, January 1, 1970. If there is no signing-time attribute in the attributes list, an error is returned.

Parameters:
attributesObj This input parameter is the attributes object.
signingTime This output parameter is the signing time. That is, the time at which the signature was created.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetStringAttribute (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    type,
unsigned int    typeLen,
unsigned int    valueIndex,
int *    valueTag,
unsigned char **    value,
unsigned int *    valueLen
)  ;
 

Obtains the value tag and a pointer to the contents of the string-based value (indexed by valueIndex), in the attribute of the type given by type and typeLen, in the attribute list for attributesObj, and stores the tag in valueTag. The value index starts at 0 (zero). A string-based value is a simple format, with a tag such as VT_PRINTABLE_STRING or VT_T61_STRING and a single-byte array for the contents.

Note: The fields returned from this function are read-only. You do not need to create any objects or items prior to calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
attributesObj This input parameter is the attributes object.
type This input parameter is the attribute type.
typeLen This input parameter is the length of the attribute type.
valueIndex This input parameter is the attributes list's value index.
valueTag This output parameter stores the string value's tag.
value This output parameter is a pointer to the string value.
valueLen This output parameter is the length of the string value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ResetAttributesObject (  ATTRIBUTES_OBJ    attributesObj )  ;
 

Returns attributesObj to the state it was in after it was created by C_CreateAttributesObject(), freeing any memory that was held by the object.

Parameters:
attributesObj This is both an input and output parameter. As an input parameter, it is the attributes object that Cert-C should reset. As an output parameter, it is the reset attributes object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetAttributesBER (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    ber,
unsigned int    berLen
)  ;
 

Updates the value of attributesObj with the BER-encoded attribute set given in ber and berLen. A separate copy of the BER-encoded attribute set is allocated inside the attributes object, so ber can be changed after the call to C_SetAttributesBER().

Parameters:
attributesObj This is both an input and an output parameter. As an input parameter, it is the attributes object that Cert-C should update with a new attribute value. As an output parameter, it is the updated attributes object.
ber This input parameter is the BER-encoded attribute value.
berLen This input parameter is the length of the BER-encoded attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetAttributesNameValueEncoded (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    pInnerSep,
unsigned char *    pOuterSep,
unsigned char *    str,
unsigned int    strLen
)  ;
 

Modifies the value of attributesObj with the URL-encoded attribute set given in str and strLen. A separate copy of the URL-encoded attribute set is allocated inside the attributes object, so str can be changed or freed after the call to C_SetAttributesNameValueEncoded(). The information returned from this function supplements the information in attributesObject rather than replacing it. The function uses the encoding format described in Section 2.2 of RFC 1738. This function is used by some PKI service providers, and can also be used as a utility function. You can use an arbitrary string of characters to separate the name and the value in each name-value pair, and a different arbitrary string of characters to separate the name-value pairs from each other. This function is similar to the C_SetAttributesURLEncoded() function. The C_SetAttributesNameValueEncoded() function allows you to specify the separator characters in the URL encoding. The C_SetAttributesURLEncoded() function uses default values for the separator characters.

Parameters:
attributesObj This is both an input and an output parameter. As an input parameter, it is the attributes object that is updated with additional attributes. As an output parameter, it is the updated attributes object.
pInnerSep This input parameter specifies a NUL-terminated string that separates the name and the value in each name-value pair.
pOuterSep This input parameter specifies a NUL-terminated string that separates the name-value pairs from each other.
str This input parameter points to a URL-encoded attribute value that will be added to the attributes object.
strLen This input parameter is the length of the URL-encoded attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetAttributesURLEncoded (  ATTRIBUTES_OBJ    attributesObj,
unsigned char *    str,
unsigned int    strLen
)  ;
 

Modifies the value of attributesObj with the URL-encoded attribute set given in str and strLen. A separate copy of the URL-encoded attribute set is allocated inside the attributes object, so str can be changed after the call to C_SetAttributesURLEncoded(). The information returned from this function supplements the information in attributesObject rather than replacing it. The encoding format is described in Section 2.2 of RFC 1738. The C_SetAttributesURLEncoded() function is a variant of the C_SetAttributesNameValueEncoded() function that uses the following values for the separator characters:
Separator Characters and Flags Value
Between name and value (pInnerSep) =                                                                                              
Between name-value pairs (pOuterSep) &

Parameters:
attributesObj This is both an input and an output parameter. As an input parameter, it is the attributes object that Cert-C should update with a new attribute value. As an output parameter, it is the updated attributes object.
str This input parameter is the URL-encoded attribute value.
strLen This input parameter is the length of the URL-encoded attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetChallengePasswordAttribute (  ATTRIBUTES_OBJ    attributesObj,
int    valueTag,
unsigned char *    value,
unsigned int    valueLen
)  ;
 

Sets the value of the challenge-password attribute in the attribute list for attributesObj. It sets the value and length given by value and valueLen, and the value tag given by valueTag. If there is already a challenge-password attribute in the attribute list, its value is updated. The challenge password is represented as a NUL-terminated string.

Parameters:
attributesObj This is both an input and an output parameter. As an input parameter, it is the attributes object that Cert-C should update with a new attribute value. As an output parameter, it is the updated attributes object.
valueTag This input parameter is the tag for the attribute value. valueTag must be either VT_PRINTABLE_STRING or VT_T61_STRING.
value This input parameter is the attribute value. If valueTag is VT_PRINTABLE_STRING, value must conform to the printable string character set.
valueLen This input parameter is the length of the attribute value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetSigningTimeAttribute (  ATTRIBUTES_OBJ    attributesObj,
UINT4    signingTime
)  ;
 

Sets the value of the signing-time attribute in the attribute list for attributesObj to signingTime. If there is already a signing-time attribute in the attribute list, its value is updated. The time is specified as the number of seconds since 12:00 A.M. GMT, January 1, 1970.

Parameters:
attributesObj This is both an input and an output parameter. As an input parameter, it is the attributes object that Cert-C should update. As an output parameter, it is the updated attributes object.
signingTime This input parameter is the time at which the signature was created, the signing time.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.


RSA BSAFE® Cert-C 2.7 API Reference