	RSA BSAFE Cert-C	Certificate Components for C
		Crypto-C 6.2.1 Developer's Guide
		Search

certname.h File Reference

This file contains 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 nameObj. More...

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

Obtains the DER encoding of the value of nameObject, and stores 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, and stores 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 nameObj'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 nameObj'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 nameObj 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 nameObj, frees the memory the name object occupied and sets nameObj 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 nameObj,

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 nameObj'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:

nameObj [In, Out] 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 [In] 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 this function.

typeLen [In] The length of the attribute type.

valueTag [In] The tag for the attribute value.

value [In] 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 this function.

valueLen [In] The length of the attribute value.

newLevel [In] 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 [Out] The AVA list's index. The value of index is set to the index in the AVA list of the added entry.
Ignored if this parameter is (unsigned int *)NULL_PTR.

Returns:
0 indicates success.
See Errors for error information.
Samples:
cmp.c, and nameutil.c.

int C_CreateNameObject ( NAME_OBJ * nameObj ) ;

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

nameObj [Out] A pointer to the new name object.

Returns:
0 indicates success.
See Errors for error information.
Samples:
certutil.c, cmp.c, cmpreq.c, crmf.c, demo.c, genreq.c, kcscrs.c, kcsscep.c, ldap.c, ldap2.c, name.c, nameutil.c, p10util.c, pkcs11db.c, pkiutil.c, smplsaltnm.c, and verisign.c.

void C_DestroyNameObject ( NAME_OBJ * nameObj ) ;

Destroys nameObj, frees the memory the name object occupied and sets nameObj to (NAME_OBJ)NULL_PTR. No action is taken if nameObj is already (NAME_OBJ)NULL_PTR, or it is not a valid name object.
Parameters:

nameObj [In, Out] As an input parameter, it is the name object that Cert-C should destroy. As an output parameter, it is (NAME_OBJ)NULL_PTR.

Samples:
certutil.c, cmp.c, cmpreq.c, crmf.c, demo.c, genreq.c, kcscrs.c, kcsscep.c, ldap.c, ldap2.c, name.c, nameutil.c, p10util.c, pkcs11db.c, pkiutil.c, smplsaltnm.c, and verisign.c.

int C_GetNameAVA ( NAME_OBJ nameObj,

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 nameObj'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</tt>. Otherwise, an application must check the type with a memory comparison. In either case, never change the memory to which type points after the call to this function. The memory is not defined after the name object is destroyed or when the name object is modified with C_SetNameBER() or C_AddNameAVA(). This function returns an ASCII value.
Parameters:
nameObj [In] The name object. index [In] The AVA list's index. type [Out] The attribute type. typeLen [Out] The length of the attribute type. valueTag [Out] The tag for the attribute value. value [Out] The attribute value. valueLen [Out] The length of the attribute value. newLevel [Out] 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:
0 indicates success. See Errors for error information.
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, such as C_Destroy*, that modify these fields.
Samples:
nameutil.c.

int C_GetNameAVACount ( NAME_OBJ nameObj,

unsigned int * count

) ;

Obtains the number of AVAs in nameObject's AVA list, and stores the result in count.
Parameters:

nameObj [In] The name object.

count [Out] The number of AVAs in the name object's AVA list.

Returns:
0 indicates success.
See Errors for error information.
Samples:
myprint.c, and nameutil.c.

int C_GetNameDER ( NAME_OBJ nameObj,

unsigned char ** der,

unsigned int * derLen

) ;

Obtains the DER encoding of the value of nameObject, and stores a pointer to the DER encoding in der and its length in derLen.
Parameters:

nameObj [In] The name object.

der [Out] The name object's DER-encoded name.

derLen [Out] The length of the name object's DER-encoded name.

Returns:
0 indicates success.
See Errors for error information.

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, such as C_Destroy*, that modify these fields.
Samples:
cert.c, cmp.c, crl.c, fulfill.c, kcscrs.c, kcsscep.c, name.c, nameutil.c, pkcs10.c, and verisign.c.

int C_GetNameString ( NAME_OBJ nameObj,

char ** s

) ;

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.
Parameters:

nameObj [In] The name object from which the string is created.

s [Out] A pointer to where the string form of the name is returned.

Returns:
0 indicates success.
See Errors for error information.

This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
certutil.c, crlutil.c, and name.c.

int C_GetNameStringReverse ( NAME_OBJ nameObj,

char ** s

) ;

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.
Parameters:

nameObj [In] The name object from which the string is created.

s [Out] A pointer to the location where the string form of the name object is returned.

Returns:
0 indicates success.
See Errors for error information.

This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
cert.c, certutil.c, name.c, and pkcs10.c.

int C_IsSubjectSubordinateToIssuer ( int * isSubordinate,

NAME_OBJ subjectNameObj,

NAME_OBJ issuerNameObj

) ;

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. A non-zero value is assigned to isSubordinate if the subject is subordinate to the issuer. Otherwise, a 0 (zero) is assigned.
Parameters:

isSubordinate [Out] The result of the checking process.

subjectNameObj [In] The subject name object.

issuerNameObj [In] The issuer name object.

Returns:
0 indicates success.
See Errors for error information.

int C_ResetNameObject ( NAME_OBJ nameObj ) ;

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

nameObj [In, Out] 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:
0 indicates success.
See Errors for error information.
Samples:
cftest.c, and fulfill.c.

int C_SetNameBER ( NAME_OBJ nameObj,

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 this function.
Parameters:

nameObj [In, Out] The name object.

ber [In] The name object's BER-encoded name.

berLen [In] The length of the object's BER-encoded name.

Returns:
0 indicates success.
See Errors for error information.
Samples:
cmp.c, fulfill.c, kcscrs.c, kcsscep.c, name.c, nameutil.c, pkcs10.c, and verisign.c.

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 [In, Out] The name object.

nameString [In] The UTF8-string representation of the name.

Returns:
0 indicates success.
See Errors for error information.
Samples:
name.c.

Functions
int	C_CreateNameObject (NAME_OBJ *nameObject)
	Creates a new name object, storing the result in nameObj. More...
int	C_GetNameDER (NAME_OBJ nameObject, unsigned char *der, unsigned int derLen)
	Obtains the DER encoding of the value of nameObject, and stores 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, and stores 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 nameObj'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 nameObj'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 nameObj 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 nameObj, frees the memory the name object occupied and sets nameObj 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...