X509_MakeCertSelf

CryptoSys PKI Pro Manual

X509_MakeCertSelf

Creates a self-signed X.509 certificate.

VBA/VB6 Syntax


Public Declare Function X509_MakeCertSelf Lib "diCrPKI.dll" 
    (ByVal strNewCertFile As String, ByVal strPriKeyFile As String, 
    ByVal nCertNum As Long, ByVal nYearsValid As Long, 
    ByVal strDistName As String, ByVal strExtensions As String, 
    ByVal KeyUsageFlags As Long, 
    ByVal strPassword As String, ByVal nOptions As Long) As Long

nRet = X509_MakeCertSelf(strNewCertFile, strPriKeyFile, nCertNum, nYearsValid, strDistName, strExtensions, KeyUsageFlags, strPassword, nOptions)

C/C++ Syntax


long __stdcall X509_MakeCertSelf(const char *szNewCertFile, const char *szPriKeyFile, long nCertNum, long nYearsValid, const char *szDistName, const char *szExtensions, long nKeyUsageFlags, const char *szPassword, long nOptions);

Parameters

szNewCertFile

[in] Name of new certificate file to be created.

szPriKeyFile

[in] Name of issuer's private key file (encrypted or unencrypted) or a PEM string containing the key, or a valid internal key string.

nCertNum

[in] Serial number for new certificate. Ignored if serialNumber is set in szExtensions.

nYearsValid

[in] Number of years certificate is to be valid starting at current date and hour (can be changed with szExtensions).

szDistName

[in] Distinguished name string (required). See Specifying Distinguished Names for more details.

szExtensions

[in] Extensions: optional list of attribute-value pairs separated by semicolons (;). See X.509 Extensions Parameter. Specify "" or NULL to ignore.

nKeyUsageFlags

[in] Flags to set Key Usage extensions:

`PKI_X509_KEYUSAGE_DIGITALSIGNATURE`	to set `digitalSignature`
`PKI_X509_KEYUSAGE_NONREPUDIATION`	to set `nonRepudiation`
`PKI_X509_KEYUSAGE_KEYENCIPHERMENT`	to set `keyEncipherment`
`PKI_X509_KEYUSAGE_DATAENCIPHERMENT`	to set `dataEncipherment`
`PKI_X509_KEYUSAGE_KEYAGREEMENT`	to set `keyAgreement`
`PKI_X509_KEYUSAGE_KEYCERTSIGN`	to set `keyCertSign`
`PKI_X509_KEYUSAGE_CRLSIGN`	to set `cRLSign`
`PKI_X509_KEYUSAGE_ENCIPHERONLY`	to set `encipherOnly`
`PKI_X509_KEYUSAGE_DECIPHERONLY`	to set `decipherOnly`

Add to combine options. Specify zero to omit Key Usage extension.

szPassword

[in] containing password for Issuer'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_VERSION1 to generate a Version 1 certificate, i.e. no extensions (default = Version 3).
PKI_X509_CA_TRUE to set the basicConstraints subject type to be a CA (default = End Entity)
PKI_X509_NO_BASIC to disable the basicConstraints extension (default = include)
PKI_X509_UTF8 to encode the subject's DN fields as UTF8String (default = PrintableString)
PKI_X509_FORMAT_PEM to save the certificate in PEM format (default = DER-encoded binary)

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.MakeCertSelf Method

C++ (STL) Equivalent

static int dipki::X509::MakeCertSelf (const std::string &newCertFile, const std::string &priKeyFile, const std::string &password, int certNum, int yearsValid, const std::string distName, const std::string extns="", KeyUsageOptions keyUsageOptions=KeyUsageOptions::NoKeyUsageOption, SigAlg sigAlg=SigAlg::Default, CertOptions opts=CertOptions::Default_CertOpt)

Python Equivalent

static X509.make_cert_self(newcertfile, prikeyfile, password, certnum, yearsvalid, distname, extns="", keyusage=0, sigalg=0, opts=0)

Remarks

See the remarks for X509_MakeCert(). A self-signed certificate has the same Issuer and Subject distinguished name. Add the PKI_X509_UTF8 flag to encode the distinguished names in UTF-8. The BasicConstraints subject type will always be a CA for a version 3 self-signed certificate, unless explicitly excluded with the PKI_X509_NO_BASIC flag.

Example

Dim nRet As Long
Dim nKeyUsage As Long

nKeyUsage = PKI_X509_KEYUSAGE_DIGITALSIGNATURE + _
    PKI_X509_KEYUSAGE_KEYCERTSIGN + PKI_X509_KEYUSAGE_CRLSIGN
nRet = X509_MakeCertSelf("myca.cer", "myca.p8e", 99, 10, _
    "CN=My CA;O=Test Org;OU=Certificate Services", _
    "", nKeyUsage, "password", 0)
If nRet <> 0 Then
    Debug.Print nRet & " " & pkiGetLastError()
Else
    Debug.Print "Success"
End If

The above example will create a new self-signed X.509 certificate with filename myca.cer. The serial number will be 99. It will be valid from today for 10 years. The issuer's encrypted private key is in the file myca.p8e and has the password "password". The new certificate will be signed using the private key using the default sha1WithRSAEncryption algorithm.

The second example below shows how to specify a distinguished name using UTF-8-encoded CJK characters. The PKI_X509_UTF8 flag must be used in this case.

Dim nRet As Long
Dim nKeyUsage As Long
Dim strDN As String

' Specify DN using chinese characters in UTF-8
' CN=da wei (U+5927, U+536B)
' C=zhong guo (U+4E2D, U+56FD)
strDN = "CN=#xE5A4A7E58DAB;C=#xe4b8ade59bbd"
nKeyUsage = PKI_X509_KEYUSAGE_DIGITALSIGNATURE + PKI_X509_KEYUSAGE_KEYCERTSIGN + PKI_X509_KEYUSAGE_CRLSIGN
nRet = X509_MakeCertSelf("myca-chinadavid.cer", "myca.p8e", _
    &H888, 4, strDN, "", nKeyUsage, "password", PKI_X509_UTF8)
If nRet <> 0 Then
    Debug.Print nRet & " " & pkiGetLastError()
Else
    Debug.Print "Success"
End If