X509_MakeCert

Creates an X.509 certificate using subject's public key and issuer's private key files.

VB6/VBA Syntax

nRet = X509_MakeCert(strNewCertFile, strIssuerCertFile, strSubjectPubKeyFile, strIssuerPvkInfoFile, nCertNum, nYearsValid, strDistName, strExtensions, KeyUsageFlags, strPassword, nOptions)

Parameters

strNewCertFile

[in] String with name of new certificate file to be created.

strIssuerCertFile

[in] String with name of issuer's X.509 certificate file (or base64 representation).

strSubjectPubKeyFile

[in] String with name of subject's public key file.

strIssuerPvkInfoFile

[in] String with name of issuer's encrypted private key file.

nCertNum

[in] Long Serial number for new certificate.

nYearsValid

[in] Long Number of years certificate is to be valid (certificate is always valid from current date and hour).

strDistName

[in] String specifying the subject's distinguished name as a set of attribute key=value pairs separated by semi-colons (;). See Specifying Distinguished Names for more details.

strExtensions

[in] String (optional) containing either just an RFC822-style email address to be included in a subjectAltName extension or [new in v3.3] one or more extension values in the form of attribute pairs type=value(;type=value)*. See X.509 Extensions Parameter.

KeyUsageFlags

[in] Long 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.

strPassword

[in] String containing password for Issuer's encrypted private key file.

nOptions

[in] Long Option flags. Choose one signature algorithm from:
PKI_SIG_SHA1RSA (0) to use sha1WithRSAEncryption (default)
PKI_SIG_MD5RSA to use md5WithRSAEncryption (not recommended)
PKI_SIG_MD2RSA to use md2WithRSAEncryption (definitely not recommended)
PKI_SIG_SHA224RSA to use sha224WithRSAEncryption
PKI_SIG_SHA256RSA to use sha256WithRSAEncryption
PKI_SIG_SHA384RSA to use sha384WithRSAEncryption
PKI_SIG_SHA512RSA to use sha512WithRSAEncryption
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)
PKI_X509_AUTHKEYID [new in v3.3] to add the issuer's KeyIdentifier, if present, as an AuthorityKeyIdentifer (default = do not add)

C/C++ Syntax

Returns (VB6/C)

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

.NET Equivalent

X509.MakeCert Method

Remarks

The signing key must be at least 368 bits long. At least one valid attribute for the subject's distinguished name (DN) must be included. A version 1 certificate created using the PKI_X509_VERSION1 flag will, by definition, exclude any version 3 extensions.

If the PKI_X509_UTF8 flag is set, each attribute of the subject's DN will be encoded as a UTF8String. Otherwise the default encoding will be PrintableString or, if a non-printable character is specified, then as either IA5String or T61String - see Specifying Distinguished Names for more details. The encoding of the issuer's DN will be as in the issuer's certficate.

If the PKI_X509_AUTHKEYID flag is set then an authorityKeyIdentifer extension will be set if there is a corresponding subjectKeyIdentifer in the issuer's certificate. Otherwise no such extension will be set.

The default validity period is from one minute ago by the system clock for a period of a whole number of years set by the nYearsValid parameter. This time will always have the seconds set to 01 [as of v3.5]. A different validity period can be set using the notBefore and notAfter attributes in the strExtensions parameter (see X509 Extensions Parameter.

The serial number can be set to be an integer in the range 1 to 2,147,483,647 using the nCertNum parameter, or (once you have used these up) it can be set to a larger value, perhaps a random hexadecimal string, using the serialNumber attribute in the strExtensions parameter (see X509 Extensions Parameter).

[New in v3.5]As an alternative, you can create a new X.509 certificate using a PKCS-10 certificate signing request (CSR) file. Pass the name of the CSR file in the strSubjectPubKeyFile parameter and set the strDistName empty "". The empty distinguished name parameter is a flag that a CSR file is being used. See the example below.

Example

Dim nRet As Long
Dim strNewCertFile As String
Dim strIssuerCert As String
Dim strSubjectPubKeyFile As String
Dim strIssuerPriKeyFile As String
Dim strPassword As String
Dim nCertNum As Long
Dim nYearsValid As Long
Dim strDistName As String
Dim strEmail As String
strNewCertFile = "myuser.cer"
strIssuerCert = "myca.cer"
strSubjectPubKeyFile = "mykey.pub"
strIssuerPriKeyFile = "myca.epk"
strPassword = "password"  '!!
nCertNum = &H101
nYearsValid = 4
strDistName = "CN=My User;O=Test Org;OU=Unit;C=AU;L=My Town;S=State;E=myuser@testorg.com"
strEmail = "myuser@testorg.com"

nRet = X509_MakeCert(strNewCertFile, strIssuerCert, strSubjectPubKeyFile, strIssuerPriKeyFile, _
    nCertNum, nYearsValid, strDistName, strEmail, 0, strPassword, 0)
If nRet <> 0 Then
    Debug.Print nRet & " " & pkiErrorLookup(nRet)
Else
    Debug.Print "Success, created X.509 cert " & strNewCertFile
End If

The above example will create a new X.509 certificate with filename myuser.cer. The certificate will be issued by "myca" with serial number 257 (0x101) for the subject with common name "My User", etc. It will be valid from one minute ago today for 4 years. The subject's public key in file mykey.pub will be included and it will be signed by the issuer with certificate myca.cer and private key in file myca.epk.

The next example in C uses the advanced strExtensions parameter to re-create exactly Alice's certificate from the S/MIME examples [SMIME-EX].

char *certname;
char *issuercert = "CarlRSASelf.cer";
char *pubfile = "AlicePubRSA.pub";
char *epkfile = "CarlPrivRSASign.epk";
char *password = "password";

char *certfile = "AliceRSA-dup.cer";
char *dn = "CN=AliceRSA";
char *extns = "rfc822name=AliceRSA@example.com;"
	"serialNumber=46346BC7800056BC11D36E2EC410B3B0;"
	"subjectKeyIdentifier=77D2B4D1B74C8A8AA3CE459DCEEC3CA03AE3FF50;"
	"notBefore=1999-09-19T01:08:47;"
	"notAfter=2039-12-31;"
	;
long keyUsage = PKI_X509_KEYUSAGE_DIGITALSIGNATURE + PKI_X509_KEYUSAGE_NONREPUDIATION;
long lRet;
char digest[PKI_SHA1_CHARS+1];

/* Make an end-user cert identical to RFC4134 AliceRSASignByCarl.cer */
certname = certfile;
lRet = X509_MakeCert(certname, issuercert, pubfile, epkfile, 
	0, 99, dn, extns, keyUsage, password, PKI_X509_AUTHKEYID);
assert(lRet == 0);
printf("Created end-user X.509 certificate '%s'\n", certname);

/* Check its SHA-1 thumbprint */
X509_CertThumb(certname, digest, sizeof(digest)-1, 0);
printf("SHA-1 Thumb=%s\n", digest);

This should give the output

Created end-user X.509 certificate 'C:\Test\AliceRSA-dup.cer'
SHA-1 Thumb=b30c48855055c2e64ce3196492d4b83831a6b3cb

See Also

X509_MakeCertSelf

[Contents] [Index]