RSA Security logo

RSA BSAFE Cert-C
API Reference

certname.h File Reference

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

#include "basetype.h"

Go to the source code of this file.

Functions

int C_CreateNameObject (NAME_OBJ *nameObject)
 Creates a new name object, storing the result in nameObject. More...

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

int C_SetNameBER (NAME_OBJ nameObject, unsigned char *ber, unsigned int berLen)
 Modifies the value of nameObject to the BER-encoded name, ber, with the length, berLen. More...

int C_GetNameAVACount (NAME_OBJ nameObject, unsigned int *count)
 Obtains the number of AVAs in nameObject's AVA list, storing the result in count. More...

int C_GetNameAVA (NAME_OBJ nameObject, unsigned int index, unsigned char **type, unsigned int *typeLen, int *valueTag, unsigned char **value, unsigned int *valueLen, int *newLevel)
 Obtains the AVA indexed by index in nameObject's AVA list. More...

int C_AddNameAVA (NAME_OBJ nameObject, unsigned char *type, unsigned int typeLen, int valueTag, unsigned char *value, unsigned int valueLen, int newLevel, unsigned int *index)
 Adds an AVA to the end of nameObject's AVA list with the attribute type type, the attribute-value tag valueTag, and the attribute value value. More...

int C_IsSubjectSubordinateToIssuer (int *isSubordinate, NAME_OBJ subjectNameObject, NAME_OBJ issuerNameObject)
 Checks whether the subject is subordinate to the issuer. More...

int C_ResetNameObject (NAME_OBJ nameObject)
 Returns nameObject to the state it was in after it was created by C_CreateNameObject(), freeing any memory that was held by the object. More...

void C_DestroyNameObject (NAME_OBJ *nameObject)
 Destroys nameObject, freeing the memory the name object occupied and setting nameObject to (NAME_OBJ)NULL_PTR. More...

int C_GetNameStringReverse (NAME_OBJ nameObj, char **nameString)
 Returns a string form of the name object. More...

int C_GetNameString (NAME_OBJ nameObj, char **nameString)
 Returns a NUL-terminated UTF8-string form of the name object. More...

int C_SetNameString (NAME_OBJ nameObj, char *nameString)
 Replaces the value of nameObject with the value specified by a NUL-terminated UTF8-string form, nameString. More...

Function Documentation

int C_AddNameAVA (  NAME_OBJ    nameObject,
unsigned char *    type,
unsigned int    typeLen,
int    valueTag,
unsigned char *    value,
unsigned int    valueLen,
int    newLevel,
unsigned int *    index
)  ;
 

Adds an AVA to the end of nameObject's AVA list with the attribute type type, the attribute-value tag valueTag, and the attribute value value. If newLevel is non-zero, the AVA is placed on a new level further from the root than the previous entry. Otherwise, it is placed on the same level as the previous entry. An AVA added after a call to C_CreateNameObject() or C_ResetNameObject() becomes the first entry in the AVA list. The first entry in the AVA list is always on the first level after the root.

Parameters:
nameObject This is both an input and an output parameter. As an input parameter, it is the name object that Cert-C should update with a new AVA. As an output parameter, it is the updated AVA.
type This input parameter is the attribute type. It is essentially an OID. Separate copies of the attribute type and attribute value are allocated inside the name object so that type and value can be changed after the call to C_AddNameAVA().
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. Separate copies of the attribute type and attribute value are allocated inside the name object so that type and value can be changed after the call to C_AddNameAVA().
valueLen This input parameter is the length of the attribute value.
newLevel This input parameter is the flag that is set if this AVA starts a new level. If newLevel is non-zero, the AVA is placed on a new level further from the root than the previous entry. Otherwise, it is placed on the same level as the previous entry.
index This output parameter is the AVA list's index. The value of index is set to the index in the AVA list of the added entry. If you pass (unsigned int *)NULL_PTR for index, Cert-C will ignore it.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_CreateNameObject (  NAME_OBJ *    nameObject )  ;
 

Creates a new name object, storing the result in nameObject. If C_CreateNameObject() is unsuccessful, no memory is allocated and nameObject is set to (NAME_OBJ)NULL_PTR.

Parameters:
nameObject This output parameter points to the new name object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyNameObject (  NAME_OBJ *    nameObject )  ;
 

Destroys nameObject, freeing the memory the name object occupied and setting nameObject to (NAME_OBJ)NULL_PTR. If nameObject is already (NAME_OBJ)NULL_PTR, or it is not a valid name object, then no action is taken.

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

int C_GetNameAVA (  NAME_OBJ    nameObject,
unsigned int    index,
unsigned char **    type,
unsigned int *    typeLen,
int *    valueTag,
unsigned char **    value,
unsigned int *    valueLen,
int *    newLevel
)  ;
 

Obtains the AVA indexed by index in nameObject's AVA list. If the attribute type is one of the recognized types, then type and typeLen equal one of the predefined pairs of values (for example, AT_COUNTRY and AT_COUNTRY_LEN). The type can be checked with the == operator. Otherwise, an application must check the type with a memory compare. In either case, never change the memory to which type points after the call to C_GetNameAVA(). Also, note that the memory is not defined after the name object is destroyed or when the name object is modified with C_SetNameBER() or C_AddNameAVA(). The value returned is an ASCII value.

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:
nameObject This input parameter is the name object.
index This input parameter is the AVA list's index.
type This output parameter is the attribute type.
typeLen This output parameter is the length of the attribute type.
valueTag This output parameter is the tag for the attribute value.
value This output parameter is the attribute value.
valueLen This output parameter is the length of the attribute value.
newLevel This output parameter is the flag that is set if this AVA starts a new level. newLevel is set to a non-zero value if the AVA at index is one level further from the root than the entry at index minus one. newLevel is set to zero if it is on the same level. For the entry at index zero, newLevel is always set to a non-zero value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetNameAVACount (  NAME_OBJ    nameObject,
unsigned int *    count
)  ;
 

Obtains the number of AVAs in nameObject's AVA list, storing the result in count.

Parameters:
nameObject This input parameter is the name object.
count This output parameter is the number of AVAs in the name object's AVA list.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetNameDER (  NAME_OBJ    nameObject,
unsigned char **    der,
unsigned int *    derLen
)  ;
 

Obtains the DER encoding of the value of nameObject, 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 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:
nameObject This input parameter is the name object.
der This output parameter is the name object's DER-encoded name.
derLen This output parameter is the length of the name object's DER-encoded name.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetNameString (  NAME_OBJ    nameObj,
char **    nameString
)  ;
 

Returns a NUL-terminated UTF8-string form of the name object. (Refer to RFC 2279 for a description of UTF8-string encoding.) The string conforms to the LDAP standard (refer to RFC 2253) for the string representation of distinguished names.

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:
nameObj This input parameter is the name object from which the string is created.
nameString This output parameter points to where the string form of the name is returned.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetNameStringReverse (  NAME_OBJ    nameObj,
char **    nameString
)  ;
 

Returns a string form of the name object. The string is a NUL-terminated UTF-8 string. (Refer to RFC 2279 for a description of UTF8-string encoding.) The string is similar to the LDAP standard (refer to RFC 2253) for the string representation of distinguished names, except the string has the most-significant RDN first, instead of least-significant first. This is the reverse order with respect to C_GetNameString(). This form may be useful in database service providers that use a string form of the name for index purposes.

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:
nameObj This input parameter is the name object from which the string is created.
nameString This output parameter points to the location where the string form of the name object is returned.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_IsSubjectSubordinateToIssuer (  int *    isSubordinate,
NAME_OBJ    subjectNameObject,
NAME_OBJ    issuerNameObject
)  ;
 

Checks whether the subject is subordinate to the issuer. Subordinate means that the issuer name is entirely contained within the subject name, exactly as it appears in the issuer name. If the subject is subordinate to the issuer, a non-zero value is assigned to isSubordinate. Otherwise, a 0 (zero) is assigned.

Parameters:
isSubordinate This output parameter stores the result of the subordinate check.
subjectNameObject This input parameter is the subject name object.
issuerNameObject This input parameter is the issuer name object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ResetNameObject (  NAME_OBJ    nameObject )  ;
 

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

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

int C_SetNameBER (  NAME_OBJ    nameObject,
unsigned char *    ber,
unsigned int    berLen
)  ;
 

Modifies the value of nameObject to the BER-encoded name, ber, with the length, berLen. A separate copy of the BER-encoded name is allocated inside the name object so that ber can be changed after the call to C_SetNameBER().

Parameters:
nameObject This is both an input and an output parameter; it is the name object.
ber This input parameter is the name object's BER-encoded name.
berLen This input parameter is the length of the object's BER-encoded name.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetNameString (  NAME_OBJ    nameObj,
char *    nameString
)  ;
 

Replaces the value of nameObject with the value specified by a NUL-terminated UTF8-string form, nameString. (Refer to RFC 2279 for a description of UTF8-string encoding.) The string conforms to the LDAP standard for the string representation of distinguished names. (Refer to RFC 2253 for more information on the LDAP standard.)

Parameters:
nameObj This is both an input and an output parameter; it is the name object.
nameString This input parameter is the UTF8-string representation of the name.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.


RSA BSAFE® Cert-C 2.7 API Reference