gsk_dn_to_name()

Converts a DN string to an X.509 name.

Format

   #include <gskcms.h>
 
   gsk_status gsk_dn_to_name (  
                               const char *         dn, 
                               x509_name *          name)

Parameters

dn: Specifies the distinguished name in the local code page.
name: Returns the X.509 name. The X.509 strings use UTF-8 encoding. The application should call the gsk_free_name() routine to release the name when it is no longer needed.

Results

The function return value will be 0 if no error is detected. Otherwise, it will be one of the return codes listed in the gskcms.h include file. These are some possible errors:

[ASN_ATTR_NOT_FOUND]: An attribute type is not recognized.
[ASN_CANT_CONVERT]: An encoded attribute value contains characters from the wrong character set.
[ASN_INVALID_VALUE]: An attribute value is not valid.
[ASN_NO_MEMORY]: Insufficient storage is available.
[ASN_WRONG_TYPE]: An encoded attribute value does not represent a character string.
[ASN_X500_NO_AVA_SEP]: An attribute value separator is missing.
[ASN_X500_OID_SYNTAX_ERROR]: An object identifier is not valid.
[ASN_X500_SYNTAX_ERROR]: The DN string format is not valid.

Usage

The gsk_dn_to_name() routine converts a distinguished name (DN) string to an X.509 name in accordance with RFC 2253: UTF-8 String Representation of Distinguished Names. The input string consists of single-byte characters in the local code page. A double-byte character is represented using the escaped UTF-8 encoding of the double-byte character in the Unicode character set.

Attribute types may be specified using either attribute names or numeric object identifiers. Attribute values must represent string values.

These DN attribute names are recognized by the System SSL run time. An error is returned if the DN contains an unrecognized attribute name.

Table 1. DN attribute names
	Name
C	Country
CN	Common name
DC	Domain component
DNQUALIFIER	Distinguished name qualifier
E	E-mail address
EMAIL	E-mail address (preferred)
EMAILADDRESS	E-mail address
GENERATIONQUALIFIER	Generation qualifier
GIVENNAME	Given name
INITIALS	Initials
L	Locality
MAIL	RFC 822 style address
NAME	Name
O	Organization name
OU	Organizational unit name
PC	Postal code
S	State or province
SERIALNUMBER	Serial number
SN	Surname
SP	State or province
ST	State or province (preferred)
STREET	Street
T	Title

This is an example of a DN using attribute names and string values:

CN=Ronald Hoffman,OU=Endicott,O=IBM,C=US

This is the same DN using object identifiers and encoded string values. The encoded string values represent the ASN.1 DER encoding of the string. The System SSL run time supports these ASN.1 string types: PRINTABLE, VISIBLE, TELETEX, IA5, UTF8, BMP, and UCS.

2.5.4.3=#130E526F6E616C6420486F66666D616E,2.5.4.11=#1308456E6469636F7474,
2.5.4.10=#130349424D,2.5.4.6=13025553

Individual characters can be represented using escape sequences. This is useful when the character cannot be represented in a single-byte character set. The hexadecimal value for the escape sequence is the UTF-8 encoding of the character in the Unicode character set.

Unicode Letter Description         10646 code    UTF-8     Quoted
===============================    ==========    ======    =======
LATIN CAPITAL LETTER L             U0000004C     0x4C      L
LATIN SMALL LETTER U               U00000075     0x75      u
LATIN SMALL LETTER C WITH CARON    U0000010D     0xC48D    \C4\8D
LATIN SMALL LETTER I               U00000069     0x69      i
LATIN SMALL LETTER C WITH ACUTE    U00000107     0xC487    \C4\87

SN=Lu\C4\8Di\C4\87

An escape sequence can also be used for special characters which are part of the name and are not to be interpreted as delimiters. For example:

CN=L. Eagle,OU=Jones\, Dale and Mian,O=IBM,C=US