Certificate Type

The digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

effectiveDate
String

The date which this certificate becomes valid. Prior to this it is not valid. The following is an example of an encoded date illustrating the format:

23-Jan-2000 15:00:00.

encodedB
Data

The certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The Store and Subject properties may also be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate, otherwise Subject is set to empty string.

encoded
String

The certificate (PEM/base64 encoded). This property is used to assign a specific certificate. The Store and Subject properties may also be used to specify a certificate.

When Encoded is set, a search is initiated in the current Store for the private key of the certificate. If the key is found, Subject is updated to reflect the full subject of the selected certificate, otherwise Subject is set to empty string.

expirationDate
String

The date the certificate expires. Dates following this date, the certificate will no longer be valid. The following is an example of an encoded date illustrating the format:

23-Jan-2001 15:00:00.

extendedKeyUsage
String

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 Object-Identifiers (OIDs).

fingerprint
String

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

This is in the form:

bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

issuer
String

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

keyPassword
String

The password for the certificate's private key (if any).

Some certificate stores may individually protect certificates' private keys, separate from the standard protection offered by the StorePassword. KeyPassword. This can be used to read such password-protected private keys.

Note: this property defaults to the value of StorePassword. To clear it, you must set the property to the empty string (""). It can be set at any time, but must be set before calling PrivateKey when the private key's password is different from the store's.

privateKey
String

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The PrivateKey may be available, but not exportable. In this case, PrivateKey returns an empty string.

privateKeyAvailable
Bool

Shows whether a PrivateKey is available for the selected certificate. If PrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g. server authentication).

privateKeyContainer
String

The name of the PrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

publicKey
String

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

publicKeyAlgorithm
String

Textual description of the public key algorithm of the certificate. The property contains either the name of the algorithm (such as "RSA" or "RSA_DH"), or an object identifier (OID) string representing the algorithm.

publicKeyLength
Int32

The length of the certificate public key (in bits). Common values are 512, 1024, and 2048.

serialNumber
String

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, each two of them representing a byte of the serial number.

signatureAlgorithm
String

Text description of the signature algorithm of the certificate. The property contains either the name of the algorithm (such as "RSA" or "RSA_MD5RSA"), or an object identifier (OID) string representing the algorithm.

storeB
Data

The name of the certificate store for the client certificate.

The StoreType property specifies the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject property in order to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please refer to the Subject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

store
String

The name of the certificate store for the client certificate.

The StoreType property specifies the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject property in order to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please refer to the Subject property for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

storePassword
String

If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.

storeType
CertStoreTypes

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used the class will automatically determine the type. This property can take one of the following values:

0 (cstUser - default)For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note: this store type is not available in Java.
1 (cstMachine)For Windows, this specifies that the certificate store is a machine store. Note: this store type is not available in Java.
2 (cstPFXFile)The certificate store is the name of a PFX (PKCS12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or base64-encoded) representing a certificate store in PFX (PKCS12) format.
4 (cstJKSFile)The certificate store is the name of a Java Key Store (JKS) file containing certificates. Note: this store type is only available in Java.
5 (cstJKSBlob)The certificate store is a string (binary or base64-encoded) representing a certificate store in Java Key Store (JKS) format. Note: this store type is only available in Java.
6 (cstPEMKeyFile)The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)The certificate store is a string (binary or base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)The certificate store is a string (binary or base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)The certificate store is a string (binary or base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)The certificate store is the name of a PKCS7 file containing certificates.
12 (cstP7BBlob)The certificate store is a string (binary) representing a certificate store in PKCS7 format.
13 (cstSSHPublicKeyFile)The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)The certificate store is a string that contains a JWK (JSON Web Key).
20 (cstSecurityKey)The certificate is present on a physical security key accessible via a PKCS11 interface.

To use a security key the necessary data must first be collected using the CERTMGR class. The ListStoreCertificates method may be called after setting CertStoreType to cstSecurityKey, CertStorePassword to the PIN, and CertStore to the full path of the PKCS11 dll. The certificate information returned in the CertList event's CertEncoded parameter may be saved for later use.

When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN.

Code Example: SSH Authentication with Security Key

certmgr.CertStoreType = CertStoreTypes.cstSecurityKey;
certmgr.OnCertList += (s, e) => {
  secKeyBlob = e.CertEncoded;
};
certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll";
certmgr.CertStorePassword = "123456"; //PIN
certmgr.ListStoreCertificates();

sftp.SSHCert = new Certificate(CertStoreTypes.cstSecurityKey, secKeyBlob, "123456", "*");
sftp.SSHUser = "test";
sftp.SSHLogon("myhost", 22);

99 (cstAuto)The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

subject
String

The subject of the certificate used for client authentication.

This property must be set after all other certificate properites are set. When this property is set, a search is performed in the current certificate store certificate with matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For instance "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are displayed below.

FieldMeaning
CNCommon Name. This is commonly a host name like www.server.com.
OOrganization
OUOrganizational Unit
LLocality
SState
CCountry
EEmail Address

If a field value contains a comma it must be quoted.

subjectAltNames
String

A comma-separated lists of alternative subject names of the certificate.

thumbprintMD5
String

MD5 hash of the certificate. If the hash does not already exist, it is computed.

thumbprintSHA1
String

SHA1 hash of the certificate. If the hash does not already exist, it is computed.

thumbprintSHA256
String

SHA256 hash of the certificate. If the hash does not already exist, it is computed.

usage
String

Text description of UsageFlags.

The value will be of one or more of the following strings, separated by commas:

  • Digital Signatures
  • Key Authentication
  • Key Encryption
  • Data Encryption
  • Key Agreement
  • Certificate Signing
  • Key Signing

If the provider is OpenSSL, the value is a comma separated list of X509 certificate extension names.

usageFlags
Int32

Flags that show intended use for the certificate. The value of UsageFlags is a combination of the following flags:

0x80Digital Signatures
0x40Key Authentication
0x20Key Encryption
0x10Data Encryption
0x08Key Agreement
0x04Certificate Signing
0x02Key Signing

Please refer to the Usage property for a text representation of UsageFlags.

This functionality is currently not available when the provider is OpenSSL.

version
String

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

Constructors

public init()

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

public init(certificateFile: String)

Opens CertificateFile and reads out the contents as an X509 public key.

public init(certificateData: Data)

Parses CertificateData as an X509 public key.

public init(certStoreType: CertStoreTypes, store: String, storePassword: String, subject: String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public init(certStoreType: CertStoreTypes, store: String, storePassword: String, subject: String, configurationString: String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values are: "PersistPFXKey" - whether the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" - whether the platform (default) or internal security API is used when performing certificate related operations. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public init(certStoreType: CertStoreTypes, store: String, storePassword: String, encoded: Data)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public init(certStoreType: CertStoreTypes, storeBlob: Data, storePassword: String, subject: String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public init(certStoreType: CertStoreTypes, storeBlob: Data, storePassword: String, subject: String, configurationString: String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public init(certStoreType: CertStoreTypes, storeBlob: Data, storePassword: String, encoded: Data)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

 
 
Copyright (c) 2021 /n software inc. - All rights reserved.
Cloud Keys 2020 macOS Edition - Version 20.0 [Build 7876]