X509_CertRequest

CryptoSys PKI Pro Manual

X509_CertRequest

Creates a PKCS #10 certificate signing request (CSR) using the subject's private key file.

VBA/VB6 Syntax


Public Declare Function X509_CertRequest Lib "diCrPKI.dll"
    (ByVal strReqFile As String, ByVal strPriKeyFile As String,
    ByVal strDistName As String, ByVal strExtensions As String,
    ByVal strPassword As String, ByVal nOptions As Long) As Long

nRet = X509_CertRequest(strReqFile, strPriKeyFile, strDistName, strExtensions, strPassword, nOptions)

C/C++ Syntax


long __stdcall X509_CertRequest(const char *szNewReqFile, const char *szPriKeyFile, const char *szDistName, const char *szExtensions, const char *szPassword, long nOptions);

Parameters

szNewReqFile: [in] Name of new certificate request file to be created.
szPriKeyFile: [in] Name of subject's private key file (encrypted or unencrypted) or a PEM string containing the key.
szDistName: [in] Distinguished name string. See Specifying Distinguished Names for more details.
szExtensions: [in] (optional) Extensions: a list of attribute-value pairs separated by semicolons (;) to be added to an extensionRequest element. See X.509 Extensions Parameter. [New in v10.0].
szPassword: [in] Password for subject's encrypted private key file. Specify the empty string "" if key not encrypted [New in v12.0].
nOptions: [in] Option flags. Choose one signature algorithm from:
PKI_SIG_SHA1RSA (0) to use sha1WithRSAEncryption (default - CAUTION)
PKI_SIG_SHA224RSA to use sha224WithRSAEncryption
PKI_SIG_SHA256RSA to use sha256WithRSAEncryption [minimum recommended]
PKI_SIG_SHA384RSA to use sha384WithRSAEncryption
PKI_SIG_SHA512RSA to use sha512WithRSAEncryption
PKI_SIG_MD5RSA to use md5WithRSAEncryption [legacy, not recommended]
PKI_SIG_MD2RSA to use md2WithRSAEncryption [legacy, definitely not recommended]
PKI_SIG_RSA_PSS_SHA1 to use RSA-PSS-SHA1
PKI_SIG_RSA_PSS_SHA224 to use RSA-PSS-SHA224
PKI_SIG_RSA_PSS_SHA256 to use RSA-PSS-SHA256
PKI_SIG_RSA_PSS_SHA384 to use RSA-PSS-SHA384
PKI_SIG_RSA_PSS_SHA512 to use RSA-PSS-SHA512
PKI_SIG_ECDSA_SHA1 to use ecdsaWithSHA1
PKI_SIG_ECDSA_SHA224 to use ecdsaWithSHA224
PKI_SIG_ECDSA_SHA256 to use ecdsaWithSHA256
PKI_SIG_ECDSA_SHA384 to use ecdsaWithSHA384
PKI_SIG_ECDSA_SHA512 to use ecdsaWithSHA512
PKI_SIG_ED25519 to use Ed25519 [New in v20.0]
PKI_SIG_ED448 to use Ed448 [New in v22.0]

And add any combination of these:-
PKI_X509_FORMAT_BIN to create a BER-encoded binary file (default = base64 PEM format)
PKI_X509_REQ_KLUDGE to create a request with the "kludge" that omits the strictly mandatory attributes completely (default = include attributes with zero-length field)
PKI_X509_UTF8 to encode the DN as UTF8String (default = PrintableString)

Specialist options:-
PKI_PSS_SALTLEN_ZERO to use a zero-length salt in an RSA-PSS signature.
PKI_SIG_DETERMINISTIC to use the deterministic digital signature generation procedure of [RFC6979] for an ECDSA signature.

Returns (VBA/C)

If successful, the return value is zero; otherwise it returns a nonzero error code.

.NET Equivalent

X509.CertRequest Method

C++ (STL) Equivalent

static int dipki::X509::CertRequest (const std::string &newFile, const std::string &priKeyFile, const std::string &password, const std::string distName, const std::string extns="", SigAlg sigAlg=SigAlg::Default, CsrOptions opts=CsrOptions::Default_CsrOpt)

Python Equivalent

static X509.cert_request(newcsrfile, prikeyfile, password, distname, extns="", sigalg=0, opts=0)

Remarks

The default output is a base64 PEM format CSR file ready for sending to the issuer of your choice. Any existing file of the same name will be overwritten without warning.

Example

This example will create a new certificate request with filename myreq.p10.txt. for the subject with common name "myuser", etc. The subject's encrypted private key is in the file mykey.p8e and has the password "password". The certificate request will be signed using the subject's private key using the default sha1WithRSAEncryption algorithm.

Dim nRet As Long
nRet = X509_CertRequest("myreq.p10.txt", "mykey.p8e", _
  "CN=myuser;O=Test Org;C=AU;L=Sydney;S=NSW", "", "password", 0)
If nRet <> 0 Then
  Debug.Print nRet & " " & pkiGetLastError()
Else
  Debug.Print "Success"
End If

This should produce an output file similar to:

The next example duplicates the certificate request in Sections 3.1 to 3.3 of "Some Examples of the PKCS Standards" [PKCS-EX]. It uses the 508-bit private key to sign the request, which is stored in the file rsa508.p8e with the password "password". The signature algorithm is md2WithRSAEncryption and the output is in binary format. To reproduce this example requires the non-strict "kludge". The output should exactly match the CertificationRequest value in section 3.2 of PKCS-EX.

Dim nRet As Long
nRet = X509_CertRequest("pkcs_ex_req.bin", "rsa508.p8e", _
  "C=US;O=Example Organization;CN=Test User 1", "", "password", _
  PKI_SIG_MD2RSA + PKI_X509_FORMAT_BIN + PKI_X509_REQ_KLUDGE)
If nRet <> 0 Then
  Debug.Print nRet & " " & pkiGetLastError()
Else
  Debug.Print "Success"
End If

The latter example is just to demonstrate the replication of an old but known test vector, not to demonstrate good practice.