X509_ReadCertStringFromP7Chain

CryptoSys PKI Pro Manual

X509_ReadCertStringFromP7Chain

Reads an X.509 certificate into a base64 string from PKCS-7 "certs-only" data.

VBA/VB6 Syntax


Public Declare Function X509_ReadCertStringFromP7Chain Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strP7cFile As String, ByVal nIndex As Long, ByVal nOptions As Long) As Long

nRet = X509_ReadCertStringFromP7Chain(strOutput, nOutChars, strP7cFile, nIndex, nOptions) As Long

C/C++ Syntax


long __stdcall X509_ReadCertStringFromP7Chain(char *szOutput, long nOutChars, const char *szP7cFile, long nIndex, long nOptions);

Parameters

szOutput: [out] string buffer to receive the output.
nOutChars: [in] size of the output buffer in bytes.
szP7cFile: [in] filename of a PKCS-7 "certs-only" file, or a string containing its PEM textual representation.
nIndex: [in] specifying which certificate (1,2,...) in the chain to extract, or (deprecated) 0 to return the count of certificates in the set.
nOptions: [in] option flags: not used in this release. Specify zero.

Returns (VBA/C)

If successful and nIndex is greater than zero, the return value is a positive number indicating the number of characters in or required for the output string, which may be zero if no certificate could be found at the given index. However, if nIndex is zero, it returns the count of certificates found in the list. If an error occurred, it returns a negative error code.

VBA Wrapper Syntax

Public Function x509ReadCertStringFromP7Chain (szP7cFile As String, nIndex As Long, Optional nOptions As Long = 0) As String

.NET Equivalent

X509.ReadCertStringFromP7Chain Method

C++ (STL) Equivalent

static std::string dipki::X509::ReadCertStringFromP7Chain (const std::string &inputFile, int index)

Python Equivalent

static X509.read_cert_string_from_p7chain(inputfile, index)

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

The output is a base64 string representation of the extracted X.509 certificate.

If nIndex is specified as a number greater than zero, the nIndex'th certificate found in the list, if any, will be extracted to a base64-encoded string which can be used to represent the X.509 certificate directly in this Toolkit. This function will also extract certificates from CMS signed data objects, too.

[New in v12.2] To find the number of certificates in the chain, use X509_GetCertCountInP7Chain. The old (deprecated) way to find the count of certificates was to set nIndex to zero.

Example (VBA core function)

The following example shows how to extract all the certificates from a PKCS-7 CertList file represented as a PEM string. All transactions are carried out in memory.

Dim strP7 As String
Dim nCerts As Long
Dim nChars As Long
Dim nIndex As Long
Dim strCert As String
Dim strDigest As String * PKI_SHA1_CHARS
Dim strQuery As String * 128

' Input is a P7 chain file in PEM format
' bob.p7b (contains 2 X.509 certs: BobRSA and CarlRSA)
strP7 = "-----BEGIN PKCS7-----" & _
    "MIIERQYJKoZIhvcNAQcCoIIENjCCBDICAQExADALBgkqhkiG9w0BBwGgggQaMIICJzCCAZCgAwIB" & _
    "AgIQRjRrx4AAVrwR024uzV1x0DANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4X" & _
    "DTk5MDkxOTAxMDkwMloXDTM5MTIzMTIzNTk1OVowETEPMA0GA1UEAxMGQm9iUlNBMIGfMA0GCSqG" & _
    "SIb3DQEBAQUAA4GNADCBiQKBgQCp4WeYPznVX/Kgk0FepnmJhcg1XZqRW/sdAdoZcCYXD72lItA1" & _
    "hW16mGYUQVzPt7cIOwnJkbgZaTdt+WUee9mpMySjfzu7r0YBhjY0MssHA1lS/IWLMQS4zBgIFEjm" & _
    "Txz7XWDE4FwfU9N/U9hpAfEF+Hpw0b6Dxl84zxwsqmqn6wIDAQABo38wfTAMBgNVHRMBAf8EAjAA" & _
    "MA4GA1UdDwEB/wQEAwIFIDAfBgNVHSMEGDAWgBTp4JAnrHggeprTTPJCN04irp44uzAdBgNVHQ4E" & _
    "FgQU6PS4Z9izlqQq8xGqKdOVWoYWtCQwHQYDVR0RBBYwFIESQm9iUlNBQGV4YW1wbGUuY29tMA0G" & _
    "CSqGSIb3DQEBBQUAA4GBAHuOZsXxED8QIEyIcat7QGshM/pKld6dDltrlCEFwPLhfirNnJOIh/uL" & _
    "t359QWHh5NZt+eIEVWFFvGQnRMChvVl52R1kPCHWRbBdaDOS6qzxV+WBfZjmNZGjOd539OgcOync" & _
    "f1EHl/M28FAK3Zvetl44ESv7V+qJba3JiNiPzyvTMIIB6zCCAVSgAwIBAgIQRjRrx4AAVrwR024u" & _
    "n/JQIDANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4XDTk5MDgxODA3MDAwMFoX" & _
    "DTM5MTIzMTIzNTk1OVowEjEQMA4GA1UEAxMHQ2FybFJTQTCBnzANBgkqhkiG9w0BAQEFAAOBjQAw" & _
    "gYkCgYEA5Ev/GLgkV/R3/25ze5NxXLwzGpKSciPYQUbQzRE6BLOOr4KdvVEeF3rydiwrhjmnvdeN" & _
    "GlPs5ADV6OyiNrHt4lDiMgmKP5+ZJY+4Tqu5fdWWZdoWoMW+Dq5EW+9e9Kcpy4LdrETpqpOUKQ74" & _
    "GNbIV17ydsTyEWA4uRs8HZfJavECAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E" & _
    "BAMCAYYwHQYDVR0OBBYEFOngkCeseCB6mtNM8kI3TiKunji7MA0GCSqGSIb3DQEBBQUAA4GBALee" & _
    "1ATT7Snk/4mJFS5M2wzwSA8yYe7EBOwSXS3/D2RZfgrD7Rj941ZAN6cHtfA4EmFQ7e/dP+MLuGGl" & _
    "pJs85p6cVJq2ldbabDu1LUU1nUkBdvq5uTH5+WsSU6D1FGCbfco+8lNrsDdvreZ019v6WuoUQWNd" & _
    "zb7IDsHaao1TNBgCMQA=" & _
    "-----END PKCS7-----"
' Get count of certs in P7 chain - new function in [v12.2]
nIndex = 0
nCerts = X509_GetCertCountInP7Chain(strP7, 0)
Debug.Print "nCerts=" & nCerts
' Read all certs
For nIndex = 1 To nCerts
' Find required length of buffer
nChars = X509_ReadCertStringFromP7Chain(ByVal 0&, 0, strP7, nIndex, 0)
Debug.Print "X509_ReadCertStringFromP7Chain(" & nIndex & ") returns " & nChars
' Allocate memory/pre-dimension
strCert = String(nChars, " ")
nChars = X509_ReadCertStringFromP7Chain(strCert, Len(strCert), strP7, nIndex, 0)
' Cert is in a base64 string
Debug.Print Left(strCert, 150) & "..."
' Query the cert for subject name
nChars = X509_QueryCert(strQuery, Len(strQuery), strCert, "subjectName", 0)
Debug.Print "subjectName='" & Left(strQuery, nChars) & "'"
' Compute the SHA-1 thumbprint of the cert
nChars = X509_CertThumb(strCert, strDigest, Len(strDigest), 0)
Debug.Print "SHA-1(cert)=" & Left(strDigest, nChars)
Next

This should result in output as follows:

nCerts=2
X509_ReadCertStringFromP7Chain(1) returns 740
MIICJzCCAZCgAwIBAgIQRjRrx4AAVrwR024uzV1x0DANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4XDTk5MDkxOTAxMDkwMloXDTM5MTIzMTIzNTk1OVowETEPMA0GA1UEAxMGQm...
subjectName='CN=BobRSA'
SHA-1(cert)=63f046d2dd7042e51fdc26a511ef7c81ea622d8b
X509_ReadCertStringFromP7Chain(2) returns 660
MIIB6zCCAVSgAwIBAgIQRjRrx4AAVrwR024un/JQIDANBgkqhkiG9w0BAQUFADASMRAwDgYDVQQDEwdDYXJsUlNBMB4XDTk5MDgxODA3MDAwMFoXDTM5MTIzMTIzNTk1OVowEjEQMA4GA1UEAxMHQ2...
subjectName='CN=CarlRSA'
SHA-1(cert)=4110908f77c64c0edfc2de6273bfa9a98a9c5ce5

Example (VBA wrapper function)

Dim strCertString As String
strCertString = x509ReadStringFromFile("AliceRSASignByCarl.cer")
Debug.Print strCertString
Debug.Print "CertThumb=" & x509CertThumb(strCertString)
strCertString = x509ReadCertStringFromP7Chain("alice_bob_carl_certs.p7c", 3)
Debug.Print strCertString
Debug.Print "CertThumb=" & x509CertThumb(strCertString)
Debug.Print "HashIssuerAndSN=" & x509HashIssuerAndSN(strCertString, PKI_HASH_SHA256)

'Invalid index
strCertString = x509ReadCertStringFromP7Chain("alice_bob_carl_certs.p7c", 0)
Debug.Print "[" & strCertString & "]"

Dim strP7File As String
Dim nIndex As Long
Dim nCerts As Long
strP7File = "alice_bob_carl_certs.p7c"
' Call core fn with zero index to find count
nCerts = X509_ReadCertStringFromP7Chain("", 0, strP7File, 0, 0)
Debug.Print "nCerts=" & nCerts
For nIndex = 1 To nCerts
    strCertString = x509ReadCertStringFromP7Chain(strP7File, nIndex)
    Debug.Print "subjectName: " & x509QueryCert(strCertString, "subjectName")
Next