MakeSelfSignedCertificate

Description: Creates a new self-signed certificate.
Returns: Buffer. The SHA1 thumbprint of the new certificate.
Usage: Script Only.
Function Groups: Certificates
Related to: AddCertificate | CheckCertificateChain | FindCertificate | GetCertificateInfo | ListCertificates | RemoveCertificate | SetCertificateProperty
Format: MakeSelfSignedCertificate(MachineStore, StoreName, Subject [, KeyAlgorithm, HashAlgorithm, ValidityPeriod, KeyStrength, KeyUsage, EKU, SAN])
Parameters:  

MachineStore
Required Boolean. If TRUE (non-zero) attempts to find the certificate in a store in the Local Computer certificate hive. If FALSE (zero) attempts to find a certificate in a store in the Current User certificate hive.
StoreName
Required text. The name of the store in which to search for the certificate.
Subject
Required text. The subject that will be written into the certificate.
KeyAlgorithm
Optional text. The name of the algorithm used with the public / private key pair and to sign the certificate.
HashAlgorithm
Optional text. The name of the algorithm used to hash the certificate prior to signing.
ValidityPeriod
Optional numeric. The number of days for which the new certificate will be valid.
KeyStrength
Optional numeric. The key strength in bits.
KeyUsage
Optional numeric. The permitted usages for the private / public key pair.
EKU
Optional text or array of text values. The Extended Key Usages permitted for the private / public key pair.
SAN
Optional text or array of text values. A set of Subject Alternative Names to be written into the certificate.
Comments

This statement creates a self-signed certificate. A self-signed certificate is one that has no chain of trust and, hence, to be trusted requires to be installed in a trusted root store or (better) the software that uses it is explicitly allowed to trust it.

The issuer name written into the self-signed certificate is the same as the Common Name field in the Subject parameter.

 

The Subject parameter has a familiar form to many other certificate generation packages. It is a sequence of:

<identifier>=<value>

separated by semi-colons, where identifier is one of the RFC 5280/X.520-specified fields. For example:

CN=LPoint;O=Trihedral;OU=Engineering

defining the Common Name as "LPoint", the Organization as "Trihedral" and the Organizational Unit as "Engineering".

 

The KeyAlgorithm and HashAlgorithm are the Microsoft Cryptography Next Generation (CNG) algorithm names. For example "RSA" is a valid KeyAlgorithm and "SHA256" is a valid HashAlgorithm.

 

The ValidityPeriod is expressed in days from the time of certificate creation.

 

KeyStrength specifies the length of the key, in bits. For RSA this should be at least 2048 bits. Larger sizes are permitted but not commonly used at present.

 

KeyUsage is a set of bit values that specify the intended usages for the private / public key pair. These are defined as:

  Constant #KeyUsageSignature        = 0x80;
  Constant #KeyUsageNonRepudiation   = 0x40;
  Constant #KeyUsageKeyEncipherment  = 0x20;
  Constant #KeyUsageDataEncipherment = 0x10;
  Constant #KeyUsageKeyAgreement     = 0x08;
  Constant #KeyUsageCertSign         = 0x04;
  Constant #KeyUsageCRLSign          = 0x02;
  Constant #KeyEncipherOnly          = 0x01;

These bits are combined for use with a certificate. RFC 5280 describes these bits and their purpose. For example, a combination of 0xF0 is typically used for client authentication purposes.

 

EKU is a text value or an array of text values that define Extended Key Usages (sometimes called Enhanced Key Usages) that the keys are intended for. The text values are Object Identifiers (OIDs). Commonly used ones include:

Server authentication	1.3.6.1.5.5.7.3.1
Client authentication	1.3.6.1.5.5.7.3.2
Code signing	        1.3.6.1.5.5.7.3.3

SAN is a text value or an array of text values that define Subject Alternative Names to be written into the certificate. These are specified in the form:

<identifier>=<value>

where <Identifier> is one of "DNS" or "URL". Support for other types may be added in the future. Value is a string representing the value.

Example:

SANArray = New(2);
    SANArray[0] = "URL=urn:localhost:Trihedral:VTScada:MyApplication";
    SANArray[1] = "DNS=demoserver.trihedral.com";
    NewCertThumbprint = MakeSelfsignedCertificate(FALSE,
                                                  "My",
                                                  "CN=LPoint;O=Trihedral"
                                                  "RSA",
                                                  "SHA256",
                                                  90,
                                                  2048,
                                                  #KeyUsageSignature +
                                                  #KeyUsageNonRepudiation +
                                                  #KeyUsageKeyEncipherment + 
                                                  #KeyUsageDataEncipherment,
                                                  "1.3.6.1.5.5.7.3.2",
                                                  SANArray);

This will create a self-signed certificate in the current user’s Personal store with a 2048-bit RSA private/public key pair, hashed with a SHA256 algorithm (and then signed RSA key). The certificate name will be LPoint, the organization name Trihedral and it will be valid for 90 days from today. The public key is intended for client authentication and should only be used for signing, non-repudiation, key and enciphering data. The SAN will hold one URL and one DNS entry.