X509_CertSubjectName

CryptoSys PKI Toolkit Manual

X509_CertSubjectName

Extracts subject's name from X.509 certificate.

VB6/VBA 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)

Parameters

strCertFile: [in] String with the filename of the X.509 certificate (or base64 representation).
strOutput: [out] String to receive the name string.
nOutChars: [in] Long specifying the maximum number of characters to be received.
strDelim: [in] String specifying the character to use as a delimiter (default ";").
nOptions: [in] Long Option flags. Select one of:
PKI_DEFAULT (0) (default)
PKI_X509_LATIN1 to try and convert Unicode/UTF-8/T.61 attribute strings to Latin-1 (8-bit ASCII)

C/C++ Syntax


long _stdcall X509_CertSubjectName(const char *szCertFile, char *szOutput, long nOutChars, const char *szDelim, long flags);

Returns (VB6/C)

Long: Returns the number of characters set in strOutput. 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 strDelim is used. The default delimiter is a semi-colon (;) if an empty string or NULL is specified for strDelim. If the attribute key is not in our set, the OID will be expressed in dot notation, e.g. "2.5.4.4=My Surname".

If an attribute is encoded in an multi-byte-character string format (such as UTF8String or BMPString), the value will be expressed as a hexadecimal-encoded string, e.g. "C=TW;O=E8 A1 8C E6 94 BF E9 99 A2". Use the PKI_X509_LATIN1 option return the string encoded in Latin-1, if possible, so it will display properly.

Example

Dim nRet As Long
Dim nLen As Long
Dim strCertName As String
Dim strOutput As String
 
strCertName = "C:\Test\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 "X509_CertIssuerName returns " & nRet & " for " & strCertName
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 "X509_CertSubjectName returns " & nRet & " for " & strCertName
Debug.Print "[" & strOutput & "]"

This result is for an old Thawte personal certificate. Note the different delimiter characters used and what happens with unrecognised OID attribute names like "surname" and "givenName":

X509_CertIssuerName returns 100 for C:\Test\dai.cer
X509_CertIssuerName returns 100 for C:\Test\dai.cer
[C=ZA;ST=Western Cape;L=Cape Town;O=Thawte;OU=Certificate Services;
CN=Personal Freemail RSA 2000.8.30]
X509_CertSubjectName returns 88 for C:\Test\dai.cer
X509_CertSubjectName returns 88 for C:\Test\dai.cer
[2.5.4.4=Ireland,2.5.4.42=David Alexander,CN=David Alexander Ireland,
E=code@di-mgt.com.au]

[Updated in v3.3]: these particular OIDs are now recognized.