X509_CertSubjectName

CryptoSys PKI Pro Manual

X509_CertSubjectName

Extracts subject's distinguished name from X.509 certificate.

VBA/VB6 Syntax


Public Declare Function X509_CertSubjectName Lib "diCrPKI.dll" 
    (ByVal strCertFile As String, ByVal strOutput As String, 
    ByVal nOutChars As Long, ByVal strDelim As String, ByVal nOptions As Long) As Long

nRet = X509_CertSubjectName(strCertFile, strOutput, nOutChars, strDelim, nOptions)

C/C++ Syntax


long __stdcall X509_CertSubjectName(const char *szCertFile, char *szOutput, long nOutChars, const char *szDelim, long nOptions);

Parameters

szCertFile: [in] with the filename of the X.509 certificate (or base64 representation).
szOutput: [out] to receive the name string.
nOutChars: [in] specifying the maximum number of characters to be received.
szDelim: [in] specifying the character to use as a delimiter (default ";").
nOptions: [in] Option flags.
PKI_DEFAULT (0) (default)
PKI_X509_LDAP to output the LDAP string representation as per RFC 4514
PKI_X509_LATIN1 to try and convert Unicode/UTF-8/T.61 attribute strings to Latin-1 (8-bit ASCII)

Returns (VBA/C)

Returns the number of characters set in szOutput. If nOutChars is zero it returns the maximum number of characters required. C/C++ users should allocate one extra for the terminating NUL character. If an error occurs, it returns a negative error code.

.NET Equivalent

X509.CertSubjectName Method

Remarks

The distinguished name will be returned in a string expressed in the same format described in Distinguished Names, e.g. "C=AU;O=myorg;CN=Dave". Only the first character in szDelim is used. The default delimiter is a semi-colon (;) if an empty string or NULL is specified for szDelim. If the attribute key is not in our set of supported types, the OID will be expressed in dot notation, e.g. "2.5.4.4=My Surname".

If an attribute value is encoded in a multi-byte-character string format (such as UTF8String or BMPString), the value will be expressed as a hexadecimal-encoded string [NB changed in v3.9] preceded by the hash symbol ('#' U+0023) and small letter x ('x' U+0078), e.g.

"C=TW;O=E8 A1 8C E6 94 BF E9 99 A2" (v3.8 and earlier)
"C=TW;O=#xE8A18CE694BFE999A2" (v3.9 and later)

Use the PKI_X509_LATIN1 option to return the string encoded in Latin-1, if possible, so it will display properly on systems that cannot cope with UTF-8.

[New in v3.9] Use the PKI_X509_LDAP option to obtain the distinguished name in LDAP string form instead. The examples above would be returned as "CN=Dave,O=myorg,C=AU" and "O=\E8\A1\8C\E6\94\BF\E9\99\A2,C=TW", with commas as delimiters, the RDNs in reverse order, and non-printable-ASCII characters escaped in hexadecimal form "\xx" as per [RFC4514]. See LDAP string representation for more details. The szDelim parameter is ignored with the PKI_X509_LDAP option.

The output using the PKI_X509_LDAP option is suitable as content for an <X509SubjectName> node in an XML-DSIG document.

Example

Dim nRet As Long
Dim nLen As Long
Dim strCertName As String
Dim strOutput As String
 
strCertName = "dai.cer"
nLen = X509_CertIssuerName(strCertName, "", 0, ";", 0)
Debug.Print "X509_CertIssuerName returns " & nLen & " for " & strCertName
strOutput = String(nLen, " ")
nRet = X509_CertIssuerName(strCertName, strOutput, Len(strOutput), ";", 0)
Debug.Print "[" & strOutput & "]"

' Example outputting in LDAP format
nLen = X509_CertIssuerName(strCertName, "", 0, "", PKI_X509_LDAP)
Debug.Print "X509_CertIssuerName(LDAP) returns " & nLen & " for " & strCertName
strOutput = String(nLen, " ")
nRet = X509_CertIssuerName(strCertName, strOutput, Len(strOutput), "", PKI_X509_LDAP)
Debug.Print "[" & strOutput & "]"

nLen = X509_CertSubjectName(strCertName, "", 0, ";", 0)
Debug.Print "X509_CertSubjectName returns " & nLen & " for " & strCertName
strOutput = String(nLen, " ")
nRet = X509_CertSubjectName(strCertName, strOutput, Len(strOutput), ",", 0)
Debug.Print "[" & strOutput & "]"

' Example outputting in LDAP format
nLen = X509_CertSubjectName(strCertName, "", 0, "", PKI_X509_LDAP)
Debug.Print "X509_CertSubjectName(LDAP) returns " & nLen & " for " & strCertName
strOutput = String(nLen, " ")
nRet = X509_CertSubjectName(strCertName, strOutput, Len(strOutput), "", PKI_X509_LDAP)
Debug.Print "[" & strOutput & "]"

This example is for an old Thawte personal certificate. The output is as follows:

X509_CertIssuerName returns 100 for dai.cer
[C=ZA;ST=Western Cape;L=Cape Town;O=Thawte;OU=Certificate Services;CN=Personal Freemail RSA 2000.8.30]
X509_CertIssuerName(LDAP) returns 100 for dai.cer
[CN=Personal Freemail RSA 2000.8.30,OU=Certificate Services,O=Thawte,L=Cape Town,ST=Western Cape,C=ZA]
X509_CertSubjectName returns 76 for dai.cer
[SN=Ireland,G=David Alexander,CN=David Alexander Ireland,E=code@di-mgt.com.au]
X509_CertSubjectName(LDAP) returns 107 for dai.cer
[1.2.840.113549.1.9.1=code@di-mgt.com.au,CN=David Alexander Ireland,2.5.4.42=David Alexander,2.5.4.4=Ireland]