	RSA BSAFE Micro Edition Suite	Streamlined security for mobile and embedded devices

Name Functions

This section lists the functions that manage certificate names.

Functions
int R_CDECL	R_CERT_NAME_new (R_CERT_CTX cert_ctx, R_CERT_NAME *name)
	Creates a new R_CERT_NAME structure and initializes the default values. More...
int R_CDECL	R_CERT_NAME_free (R_CERT_NAME *name)
	Removes all allocated memory for the R_CERT_NAME structure name including all R_CERT_NAME_ENTRY structures contained in name. More...
int R_CDECL	R_CERT_NAME_dup (R_CERT_NAME name, R_FLAG_SHARE flag, R_CERT_NAME *dup_name)
	Duplicates the R_CERT_NAME structure name. More...
int R_CDECL	R_CERT_NAME_from_binary (R_CERT_CTX cert_ctx, R_FLAG_SHARE flag, unsigned int max_buf_len, const unsigned char buf, unsigned int consumed_len, R_CERT_NAME *name)
	Creates an R_CERT_NAME structure from the specified binary encoded data in buf. More...
int R_CDECL	R_CERT_NAME_to_binary (R_CERT_NAME name, unsigned int max_buf_len, unsigned char buf, unsigned int *out_len)
	Creates binary encoded data from the specified R_CERT_NAME structure and places the binary output in buf. More...
int R_CDECL	R_CERT_NAME_to_string (R_CERT_NAME name, unsigned int max_str_len, char str)
	Returns a string representation of the R_CERT_NAME structure name. More...
int R_CDECL	R_CERT_NAME_to_MID_string (R_CERT_NAME *name, unsigned int max_str_len, R_UTF8 str)
	Returns a string representation of the R_CERT_NAME structure name that conforms to Java Specification Request (JSR) 118 for a Mobile Information Device (MID). More...
int R_CDECL	R_CERT_NAME_from_string (R_CERT_CTX cert_ctx, char str, R_CERT_NAME **name)
	Converts a string representation of a certificate name into an R_CERT_NAME structure name. More...
int R_CDECL	R_CERT_NAME_get_info (R_CERT_NAME name, R_CERT_NAME_INFO info_id, void value)
	Returns the requested information from the certificate name. More...
int R_CDECL	R_CERT_NAME_set_info (R_CERT_NAME name, R_CERT_NAME_INFO info_id, void value)
	Sets the certificate name information. More...
int R_CDECL	R_CERT_NAME_entry_to_R_CERT_NAME_ENTRY (R_CERT_NAME name, R_FLAG_SHARE flag, R_CERT_NAME_ENTRY_TYPE type, int index, R_CERT_NAME_ENTRY *entry)
	Returns the name entry that has the type specified in type. More...
int R_CDECL	R_CERT_NAME_compare_cb (R_CERT_NAME name1, R_CERT_NAME name2)
	Compares two certificate names name1 and name2. More...
int R_CDECL	R_CERT_NAME_is_equal (R_CERT_NAME name1, R_CERT_NAME name2)
	Checks whether the two certificate name structures name1 and name2 are binary equivalents. More...
int R_CDECL	R_CERT_NAME_ENTRY_new (R_CERT_NAME name, R_CERT_NAME_ENTRY *entry)
	Creates a new name entry. More...
int R_CDECL	R_CERT_NAME_ENTRY_free (R_CERT_NAME_ENTRY *entry)
	Removes all allocated memory for the R_CERT_NAME_ENTRY structure entry. More...
int R_CDECL	R_CERT_NAME_ENTRY_get_info (R_CERT_NAME_ENTRY entry, R_CERT_NAME_ENTRY_INFO info_id, void value)
	Returns the requested information from the certificate name entry. More...
int R_CDECL	R_CERT_NAME_ENTRY_set_info (R_CERT_NAME_ENTRY entry, R_CERT_NAME_ENTRY_INFO info_id, void value)
	Sets the certificate name entry information. More...

Function Documentation

int R_CDECL R_CERT_NAME_compare_cb ( R_CERT_NAME * name1,

R_CERT_NAME * name2

) ;

Compares two certificate names name1 and name2.
Parameters:

name1 [In] The first certificate name structure.

name2 [In] The second certificate name structure.

Returns:
The comparison result:
<0 indicates name1 is smaller than name2.
=0 indicates name1 is equal to name2.
>0 indicates name1 is greater than name2.

The certificate names name1 and name2 are processed as binary data.
This function is intended for use as the compare function for qsort, bsearch and a certificate store.
See also:
R_CERT_NAME_is_equal().

int R_CDECL R_CERT_NAME_dup ( R_CERT_NAME * name,

R_FLAG_SHARE flag,

R_CERT_NAME ** dup_name

) ;

Duplicates the R_CERT_NAME structure name. This function is used when creating a certificate and in situations where a name from one certificate needs to be placed into a new certificate.
Parameters:

name [In] The name from which to copy.

flag [In] The share flag.
See Shared Flag Identifiers for valid values.

dup_name [Out] The name to copy to.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_NAME_new() and R_CERT_NAME_free().

int R_CDECL R_CERT_NAME_ENTRY_free ( R_CERT_NAME_ENTRY * entry ) ;

Removes all allocated memory for the R_CERT_NAME_ENTRY structure entry.
Parameters:

entry [In] The certificate name entry.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.

int R_CDECL R_CERT_NAME_ENTRY_get_info ( R_CERT_NAME_ENTRY * entry,

R_CERT_NAME_ENTRY_INFO info_id,

void * value

) ;

Returns the requested information from the certificate name entry.
Parameters:

entry [In] The certificate name entry from which to retrieve the information.

info_id [In] The information identifier.
See Name Entry Information Identifiers for valid values and the data type returned in value.

value [Out] The information value.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_NAME_ENTRY_set_info().

int R_CDECL R_CERT_NAME_ENTRY_new ( R_CERT_NAME * name,

R_CERT_NAME_ENTRY ** entry

) ;

Creates a new name entry.
Parameters:

name [In] The certificate name.

entry [Out] The certificate name entry.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.

int R_CDECL R_CERT_NAME_ENTRY_set_info ( R_CERT_NAME_ENTRY * entry,

R_CERT_NAME_ENTRY_INFO info_id,

void * value

) ;

Sets the certificate name entry information.
Parameters:

entry [In] The certificate name entry.

info_id [In] The identifier of information to set.
See Name Entry Information Identifiers for valid values and the data type specified in value.

value [In] The information value.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_NAME_ENTRY_get_info().

int R_CDECL R_CERT_NAME_entry_to_R_CERT_NAME_ENTRY ( R_CERT_NAME * name,

R_FLAG_SHARE flag,

R_CERT_NAME_ENTRY_TYPE type,

int index,

R_CERT_NAME_ENTRY ** entry

) ;

Returns the name entry that has the type specified in type.
Parameters:

name [In] The certificate name structure.

flag [In] The share flag. One of:
R_FLAG_SHARE_NONE.
R_FLAG_SHARE_DATA.
R_FLAG_SHARE_DEFAULT.

type [In] The type of the name entry.
See Name Entry Types for valid values.

index [In] The index of the name entry of the specified type.

entry [Out] The entry from the certificate name.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.

The index parameter is used in cases where there may be more than one certificate name entry with a particular type. To retrieve the first instance of that type set index to 0.
See also:
R_CERT_NAME_get_info().

int R_CDECL R_CERT_NAME_free ( R_CERT_NAME * name ) ;

Removes all allocated memory for the R_CERT_NAME structure name including all R_CERT_NAME_ENTRY structures contained in name.
Parameters:

name [In] The certificate name.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_NAME_new() and R_CERT_NAME_dup().
Samples:
cert.c, cert_smpl.c, cm_open_strm_cb.c, cm_vfy_strm_cb.c, ocsp_resp_find_key.c, req.c, req_smpl.c, reqgen.c, ss_cert_smpl.c, and store.c.

int R_CDECL R_CERT_NAME_from_binary ( R_CERT_CTX * cert_ctx,

R_FLAG_SHARE flag,

unsigned int max_buf_len,

const unsigned char * buf,

unsigned int * consumed_len,

R_CERT_NAME ** name

) ;

Creates an R_CERT_NAME structure from the specified binary encoded data in buf. The data is a Distinguished Encoding Rules (DER) encoded value of type X.500 Name.
Parameters:

cert_ctx [In] The certificate context.

flag [In] The share flag.
See Shared Flag Identifiers for valid values.

max_buf_len [In] The length of the buffer.

buf [In] The buffer of binary encoded data.

consumed_len [Out] The amount of data used in creating name.

name [Out] The created R_CERT_NAME structure.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.

The certificate name routines do not support multi-valued Relative Distinguished Names (RDNs) in certificate names. This means that certificate names can only have one data part for a particular name entry.
See also:
R_CERT_NAME_to_binary().
Samples:
cm_open_strm_cb.c, and cm_vfy_strm_cb.c.

int R_CDECL R_CERT_NAME_from_string ( R_CERT_CTX * cert_ctx,

char * str,

R_CERT_NAME ** name

) ;

Converts a string representation of a certificate name into an R_CERT_NAME structure name. This function is used to interpret a human readable format of the subject and issuer name.
Parameters:

cert_ctx [In] The certificate context.

str [In] The buffer for human readable name output.

name [Out] The certificate name.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.

The output format of a certificate name string is always UTF-8. 7-bit ASCII and wide characters are not supported.
The string representations of the Object Identifiers (OIDs) that can be interpreted by this function are not case-sensitive.
See also:
R_CERT_NAME_from_binary() and R_CERT_NAME_to_string().
Samples:
cert_smpl.c, req.c, req_smpl.c, reqgen.c, and ss_cert_smpl.c.

int R_CDECL R_CERT_NAME_get_info ( R_CERT_NAME * name,

R_CERT_NAME_INFO info_id,

void * value

) ;

Returns the requested information from the certificate name.
Parameters:

name [In] The certificate name from which to retrieve the information.

info_id [In] The information identifier.
See Name Information Identifiers for valid values and the data type returned in value.

value [Out] The information value.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_NAME_set_info().
Samples:
cert.c.

int R_CDECL R_CERT_NAME_is_equal ( R_CERT_NAME * name1,

R_CERT_NAME * name2

) ;

Checks whether the two certificate name structures name1 and name2 are binary equivalents.
Parameters:

name1 [In] The first certificate name structure.

name2 [In] The second certificate name structure.

Returns:
The comparison result:
0 indicates name1 is not equal to name2.
1 indicates name1 is equal to name2.

The certificate names name1 and name2 are processed as binary data.
See also:
R_CERT_NAME_compare_cb().
Samples:
ocsp_resp_find_key.c.

int R_CDECL R_CERT_NAME_new ( R_CERT_CTX * cert_ctx,

R_CERT_NAME ** name

) ;

Creates a new R_CERT_NAME structure and initializes the default values. R_CERT_NAME is used for the subject and issuer fields of a certificate, and encapsulates different forms for storing the name.
Parameters:

cert_ctx [In] The certificate name context.

name [Out] The created certificate name structure.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_NAME_free() and R_CERT_NAME_dup().

int R_CDECL R_CERT_NAME_set_info ( R_CERT_NAME * name,

R_CERT_NAME_INFO info_id,

void * value

) ;

Sets the certificate name information.
Parameters:

name [In] The certificate name.

info_id [In] The identifier of the information to set.
See Name Information Identifiers for valid values and the data type specified in value.

value [In] The information value.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_NAME_get_info().

int R_CDECL R_CERT_NAME_to_binary ( R_CERT_NAME * name,

unsigned int max_buf_len,

unsigned char * buf,

unsigned int * out_len

) ;

Creates binary encoded data from the specified R_CERT_NAME structure and places the binary output in buf. This function is used when writing fields of a certificate to a file or buffer.
Parameters:

name [In] The R_CERT_NAME structure.

max_buf_len [In] The length allocated for the data buffer.

buf [Out] The buffer in which to put the name. This argument may be NULL. If this argument is NULL, out_len will still be returned.

out_len [Out] The length of the name binary data. If buf is NULL, this is the size of the buffer required to hold the name.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.

Only the size of the R_CERT_NAME binary data is returned if buf is NULL.
See also:
R_CERT_NAME_from_binary().

int R_CDECL R_CERT_NAME_to_MID_string ( R_CERT_NAME * name,

unsigned int max_str_len,

R_UTF8 str

) ;

Returns a string representation of the R_CERT_NAME structure name that conforms to Java Specification Request (JSR) 118 for a Mobile Information Device (MID). This function is used to generate a UTF-8 encoded string that can be used for comparison purposes.
Parameters:

name [In] The certificate name.

max_str_len [In] The amount of memory allocated to string.

str [Out] The buffer for JSR 118 name output.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.

This function only supports X.509 certificate names.
See also:
R_CERT_NAME_to_string() and R_CERT_NAME_from_string().
Samples:
cert.c.

int R_CDECL R_CERT_NAME_to_string ( R_CERT_NAME * name,

unsigned int max_str_len,

char * str

) ;

Returns a string representation of the R_CERT_NAME structure name. This function is used to generate a human readable format of the subject and issuer name.
Parameters:

name [In] The certificate name.

max_str_len [In] The amount of memory allocated to string.

str [Out] The buffer for human readable name output.

Returns:
R_ERROR_NONE indicates success.
R_ERROR_BUFFER_TOO_SMALL if the output string buffer is not large enough for the generated string.
See Identifiers for valid values.

This function should only be used for user feedback because two R_CERT_NAME structures (with different binary representation produced by R_CERT_NAME_to_binary()) can be encoded into the same string.
The output format of a certificate name string is always UTF-8. Wide characters are not supported.

See also:
R_CERT_NAME_to_binary() and R_CERT_NAME_from_string().
Samples:
ocsp_resp_find_key.c.