SysLog Class

Properties Methods Events Config Settings Errors

The Syslog class is used to send and receive network system log packets.

Syntax

ipworks.syslog()

Remarks

The Syslog class implements a lightweight BSD syslog client as specified in RFC 3164 (UDP), RFC 5425 (SSL/TLS), and RFC 6587 (TCP). The class is used to send and receive BSD system network logging packets.

The first step in using the Syslog class is to set LocalHost and LocalPort to the interface and port on which the host will be receiving syslog packets, then set Active to True. For each packet, the class will parse the headers and message and fire a PacketIn event.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.


Active	Indicates whether the class is active.
LocalHost	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPort	The port in the local host where Syslog binds.
RemoteHost	Sets a specific host for outgoing log packets.
RemotePort	Sets a specific port for outgoing log packets.
SSLAcceptServerCert	Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.
SSLAuthenticateClients	If set to True, the server asks the client(s) for a certificate.
SSLCert	The certificate to be used during SSL negotiation.
SSLEnabled	Whether TLS/SSL is enabled.
SSLServerCert	The server certificate for the last established connection.
UseTCP	Whether to use TCP.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.


Activate	Enables sending and receiving of data.
Config	Sets or retrieves a configuration setting.
Deactivate	Disables sending and receive of data.
DoEvents	Processes events from the internal message queue.
Reset	Reset the class.
ResolveRemoteHost	Resolves the hostname in RemoteHost to an IP address.
SendPacket	Send a log packet to RemoteHost .

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.


Connected	Fired immediately after a connection completes (or fails).
ConnectionStatus	Fired to indicate changes in a connection state.
Disconnected	Fired when a connection is closed.
Error	Information about errors during data delivery.
PacketIn	Fires whenever a system log packet is received.
SSLClientAuthentication	Fired when the client presents its credentials to the server.
SSLServerAuthentication	Fires when connecting to the server.
SSLStatus	Shows the progress of the secure connection.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.


AcceptData	Whether the class can accept/receive data.
AppName	Sets the App-Name field in RFC 5424.
DelayHostResolution	Whether the hostname is resolved when RemoteHost is set.
MsgId	Sets the MsgId field in RFC 5424.
ProcId	Sets the ProcId field in RFC 5424.
ReceivedAppName	Returns the value of the App-Name field in RFC 5424.
ReceivedMsgId	Returns the value of the MsgId field in RFC 5424.
ReceivedProcId	Returns the value of the ProcId field in RFC 5424.
ReceivedSDElementCount	Returns the number of Structured-data elements in RFC 5424.
ReceivedSDElementId	Returns the Sd-Id value of the Sd-element with the specified SDElementIndex in RFC 5424.
ReceivedSDElementIndex	Returns the index of the Structured-Data element in RFC 5424.
ReceivedSDParamCount	Returns the number of the Sd-param values for the specified SDElementIndex in RFC 5424.
ReceivedSDParamName	Returns the name of the SD-Param field in RFC 5424.
ReceivedSDParamValue	Returns the value of the SD-Param field in RFC 5424.
SDElementCount	Sets the number of Structured-data elements in RFC 5424.
SDElementId	Sets the Sd-Id value of the Sd-element with the specified SDElementIndex in RFC 5424.
SDElementIndex	Sets the index of the Structured-Data element in RFC 5424.
SDParamCount	Sets the number of the Sd-param values for the specified SDElementIndex in RFC 5424.
SDParamName	Sets the name of the SD-Param field in RFC 5424.
SDParamValue	Sets the value of the SD-Param field in RFC 5424.
TCPMessageDelimiter	The message delimiter to use (if any) when sending and receiving over TCP.
UseHostname	Determines if the local host name or IP address is used in the Syslog header.
UseLocalTime	Indicates whether to use local time or GMT time for packet timestamps.
Version	Determines which Syslog version to use.
CaptureIPPacketInfo	Used to capture the packet information.
DelayHostResolution	Whether the hostname is resolved when RemoteHost is set.
DestinationAddress	Used to get the destination address from the packet information.
DontFragment	Used to set the Don't Fragment flag of outgoing packets.
LocalHost	The name of the local host through which connections are initiated or accepted.
LocalPort	The port in the local host where the class binds.
MaxPacketSize	The maximum length of the packets that can be received.
QOSDSCPValue	Used to specify an arbitrary QOS/DSCP setting (optional).
QOSTrafficType	Used to specify QOS/DSCP settings (optional).
ShareLocalPort	If set to True, allows more than one instance of the class to be active on the same local port.
UseConnection	Determines whether to use a connected socket.
UseIPv6	Whether or not to use IPv6.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallData	Used to send extra data to the firewall.
InBufferSize	The size in bytes of the incoming queue of the socket.
OutBufferSize	The size in bytes of the outgoing queue of the socket.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.

SysLog.Active Property

Indicates whether the class is active.

Syntax


 isActive(): boolean;

Default Value

FALSE

Remarks

This property indicates whether the class is currently active and can send or receive data.

Note: Use the Activate or Deactivate method to control whether the class is active.

This property is not available at design time.

SysLog.LocalHost Property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax


 getLocalHost(): string;


 setLocalHost(localHost: string): void;

Default Value

Remarks

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

SysLog.LocalPort Property

The port in the local host where Syslog binds.

Syntax


 getLocalPort(): number;


 setLocalPort(localPort: number): void;

Default Value

514

Remarks

The LocalPort property must be set before Syslog is activated (Active is set to True). It instructs the class to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the TCP/IP stack to choose a port at random. The chosen port will be shown by the LocalPort property after the connection is established.

LocalPort cannot be changed once the class is Active. Any attempt to set the LocalPort property when the class is Active will generate an error.

The LocalPort property is useful when trying to connect to services that require a trusted port in the client side.

SysLog.RemoteHost Property

Sets a specific host for outgoing log packets.

Syntax


 getRemoteHost(): string;


 setRemoteHost(remoteHost: string): void;

Default Value

"255.255.255.255"

Remarks

When a call is made to the SendPacket method, the class will send it to whatever value is in RemoteHost. The default value is the broadcast address, "255.255.255.255".

SysLog.RemotePort Property

Sets a specific port for outgoing log packets.

Syntax


 getRemotePort(): number;


 setRemotePort(remotePort: number): void;

Default Value

514

Remarks

When a call is made to the SendPacket method, the class will send to RemoteHost on RemotePort. The default value is 514, the standard port as defined in the BSD syslog RFC 3164.

SysLog.SSLAcceptServerCert Property

Instructs the class to unconditionally accept the server certificate that matches the supplied certificate.

Syntax


 getSSLAcceptServerCert(): Certificate;


 setSSLAcceptServerCert(SSLAcceptServerCert: Certificate): void;

Default Value

Remarks

If it finds any issues with the certificate presented by the server, the class will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

SysLog.SSLAuthenticateClients Property

If set to True, the server asks the client(s) for a certificate.

Syntax


 isSSLAuthenticateClients(): boolean;


 setSSLAuthenticateClients(SSLAuthenticateClients: boolean): void;

Default Value

FALSE

Remarks

This property is used in conjunction with the SSLClientAuthentication event. Please refer to the documentation of the SSLClientAuthentication event for details.

SysLog.SSLCert Property

The certificate to be used during SSL negotiation.

Syntax


 getSSLCert(): Certificate;


 setSSLCert(SSLCert: Certificate): void;

Default Value

Remarks

The digital certificate that the class will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the field to the encoded certificate. To select a certificate, use the store and subject fields.

SysLog.SSLEnabled Property

Whether TLS/SSL is enabled.

Syntax


 isSSLEnabled(): boolean;


 setSSLEnabled(SSLEnabled: boolean): void;

Default Value

FALSE

Remarks

This setting specifies whether TLS/SSL is enabled in the class. When False (default) the class operates in plaintext mode. When True TLS/SSL is enabled.

Note: TLS/SSL can only be used when UseTCP is .

This property is not available at design time.

SysLog.SSLServerCert Property

The server certificate for the last established connection.

Syntax


 getSSLServerCert(): Certificate;

Default Value

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

SysLog.UseTCP Property

Whether to use TCP.

Syntax


 isUseTCP(): boolean;


 setUseTCP(useTCP: boolean): void;

Default Value

FALSE

Remarks

This property specifies whether TCP is used. By default this proprety is False and UDP is used. When set to True TCP will be used as the underlying protocol.

When set to True the following additional settings are also applicable:

SSLAuthenticateClients
SSLEnabled
SSLAcceptServerCert*
SSLCert*
SSLServerCert*
TCPMessageDelimiter

SysLog.activate Method

Enables sending and receiving of data.

Syntax

async syslog.activate(): Promise<void>

Remarks

This method enables sending and receiving of data. When called the class will create a communication endpoint (socket) which can be used for sending and receiving UDP messages. This method must be called before using the class to send and receive data.

If the UseConnection configuration setting is set to , then a local association (connection) to the remote host is also created.

SysLog.config Method

Sets or retrieves a configuration setting.

Syntax

async syslog.config(configurationString : string): Promise<string>

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

SysLog.deactivate Method

Disables sending and receive of data.

Syntax

async syslog.deactivate(): Promise<void>

Remarks

This method disables sending and receiving of data. When called the class will destroy the existing socket and disable data communications.

SysLog.doEvents Method

Processes events from the internal message queue.

Syntax

async syslog.doEvents(): Promise<void>

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

SysLog.reset Method

Reset the class.

Syntax

async syslog.reset(): Promise<void>

Remarks

This method will reset the class's properties to their default values.

SysLog.resolveRemoteHost Method

Resolves the hostname in RemoteHost to an IP address.

Syntax

async syslog.resolveRemoteHost(): Promise<void>

Remarks

This method resolves the hostname specified by RemoteHost to an IP address. The resolved value is available in the RemoteHost property after this method returns.

In most cases calling this method is not necessary, the class will resolve the hostname automatically when necessary. If DelayHostResolution is this method may be called to manually resolve RemoteHost if desired.

SysLog.sendPacket Method

Send a log packet to RemoteHost .

Syntax

async syslog.sendPacket(facility : number, severity : number, message : string): Promise<void>

Remarks

System log packets are composed of three main sections, each of which can be broken down into two smaller pieces.

The first section is the PRI, which contains the originating Facility and Severity of the Message. Facility is a value from 0 to 23, with each value being a different part of the system:


0	Kernel messages
1	User-level messages
2	Mail system
3	System daemons
4	Security/authorization messages
5	Messages generated internally by syslogd
6	Line printer subsystem
7	Network news subsystem
8	UUCP subsystem
9	Clock daemon
10	Security/authorization messages
11	FTP daemon
12	NTP subsystem
13	Log audit
14	Log alert
15	Clock daemon
16	Local use
17	Local use
18	Local use
19	Local use
20	Local use
21	Local use
22	Local use
23	Local use

Severity is a value from 0 to 7 using the following convention:


0	Emergency - the system is unusable
1	Alert - action must be taken immediately
2	Critical - critical conditions exist
3	Error - error conditions exist
4	Warning - warning conditions exist
5	Notice - normal but significant condition
6	Informational - informative message
7	Debug - debug-level messages

The section sections contains a timestamp and hostname, both of which are automatically generated by the class. The third section is the Message itself.

SysLog.Connected Event

Fired immediately after a connection completes (or fails).

Syntax

syslog.on('Connected', listener: (e: {readonly remoteAddress: string, readonly remotePort: number, readonly statusCode: number, readonly description: string}) => void )

Remarks

This event fires after a connection completes or fails.

StatusCode is the value returned by the system TCP/IP stack. This will be 0 if the connection was successful.

Description contains a human readable description of the status. This will be "OK" if the connection was successful.

RemoteAddress is the IP address of the remote host.

RemotePort is the port on the remote host.

SysLog.ConnectionStatus Event

Fired to indicate changes in a connection state.

Syntax

syslog.on('ConnectionStatus', listener: (e: {readonly connectionEvent: string, readonly statusCode: number, readonly description: string}) => void )

Remarks

The ConnectionStatus event is fired when the connection state changes: for example, completion of a firewall or proxy connection or completion of a security handshake.

The ConnectionEvent parameter indicates the type of connection event. Values may include the following:


	Firewall connection complete.
	Secure Sockets Layer (SSL) or S/Shell handshake complete (where applicable).
	Remote host connection complete.
	Remote host disconnected.
	SSL or S/Shell connection broken.
	Firewall host disconnected.

StatusCode has the error code returned by the Transmission Control Protocol (TCP)/IP stack. Description contains a description of this code. The value of StatusCode is equal to the value of the error.

SysLog.Disconnected Event

Fired when a connection is closed.

Syntax

syslog.on('Disconnected', listener: (e: {readonly remoteAddress: string, readonly remotePort: number, readonly statusCode: number, readonly description: string}) => void )

Remarks

This event fires when a connection is closed.

StatusCode is the value returned by the system TCP/IP stack. This will be 0 if the connection was successful.

Description contains a human readable description of the status. This will be "OK" if the connection was successful.

RemoteAddress is the IP address of the remote host.

RemotePort is the port on the remote host.

SysLog.Error Event

Information about errors during data delivery.

Syntax

syslog.on('Error', listener: (e: {readonly errorCode: number, readonly description: string}) => void )

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class .

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

SysLog.PacketIn Event

Fires whenever a system log packet is received.

Syntax

syslog.on('PacketIn', listener: (e: {readonly facilityCode: number, readonly facility: string, readonly severityCode: number, readonly severity: string, readonly timestamp: string, readonly hostname: string, readonly message: string, readonly conforms: boolean, readonly packet: string, readonly packetB: Uint8Array, readonly sourceAddress: string, readonly sourcePort: number}) => void )

Remarks

System log packets are composed of three main sections, each of which can be broken down into two smaller pieces.

The first section is the PRI, which contains the originating FacilityCode and SeverityCode of the Message. FacilityCode is a value from 0 to 23, with each value being a different part of the system. Facility is a string representation of FacilityCode based on the following convention:


0	Kernel messages
1	User-level messages
2	Mail system
3	System daemons
4	Security/authorization messages
5	Messages generated internally by syslogd
6	Line printer subsystem
7	Network news subsystem
8	UUCP subsystem
9	Clock daemon
10	Security/authorization messages
11	FTP daemon
12	NTP subsystem
13	Log audit
14	Log alert
15	Clock daemon
16	Local use
17	Local use
18	Local use
19	Local use
20	Local use
21	Local use
22	Local use
23	Local use

SeverityCode is a value from 0 to 7. Severity is a string representation of SeverityCode using the following convention:


0	Emergency - the system is unusable.
1	Alert - action must be taken immediately.
2	Critical - critical conditions exist.
3	Error - error conditions exist.
4	Warning - warning conditions exist.
5	Notice - normal but significant condition.
6	Informational - informative message.
7	Debug - debug-level messages.

The second section contains the Timestamp and Hostname. Timestamp is a string that should conform to the standard structure "MMM DD, HH:MM:SS". The class will search for the Timestamp and verify that it conforms. If it conforms, the class will set Hostname, otherwise, everything after the PRI will be placed in Message.

If Conforms is TRUE, then the original syslog packet conforms to the syslog RFC and Timestamp, Hostname, and Message will all have valid values. Otherwise, you should parse the contents of Packet to verify the fields manually.

SourceAddress and SourcePort are the address and port from which Packet was sent. This can be an intermediate syslog server that is simply forwarding packets from the original host.

SysLog.SSLClientAuthentication Event

Fired when the client presents its credentials to the server.

Syntax

syslog.on('SSLClientAuthentication', listener: (e: {readonly remoteAddress: string, readonly remotePort: number, readonly certEncoded: string, readonly certEncodedB: Uint8Array, readonly certSubject: string, readonly certIssuer: string, readonly status: string, accept: boolean}) => void )

Remarks

This event fires when a client connects to the class and presents a certificate for authentication. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether to continue or not.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string "OK").

RemoteAddress is the IP address of the connecting client.

RemotePort is the source port of the connecting client.

CertEncoded is the base64 encoded certificate presented by the client.

CertSubject is the subject of the certificate presented by the client.

CertIssuer is the subject of the issuer of the certificate presented by the client.

Status is the stauts of the certificate.

Accept defines whether the certificate is accepted.

SysLog.SSLServerAuthentication Event

Fires when connecting to the server.

Syntax

syslog.on('SSLServerAuthentication', listener: (e: {readonly remoteAddress: string, readonly remotePort: number, readonly certEncoded: string, readonly certEncodedB: Uint8Array, readonly certSubject: string, readonly certIssuer: string, readonly status: string, accept: boolean}) => void )

Remarks

This event is where the client can decide whether to continue with the connection process or not. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether to continue or not.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string "OK"). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

RemoteAddress is the IP address of the server.

RemotePort is the source port of the server.

CertEncoded is the base64 encoded certificate presented by the server.

CertSubject is the subject of the certificate presented by the server.

CertIssuer is the subject of the issuer of the certificate presented by the server.

Status is the stauts of the certificate.

Accept defines whether the certificate is accepted.

SysLog.SSLStatus Event

Shows the progress of the secure connection.

Syntax

syslog.on('SSLStatus', listener: (e: {readonly remoteAddress: string, readonly remotePort: number, readonly message: string}) => void )

Remarks

The event is fired for informational and logging purposes only. It is used to track the progress of the connection.

RemoteAddress is the IP address of the remote machine.

RemotePort is the port of the remote machine.

Message is the log message.

Certificate Type

This is 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

This is the date on which this certificate becomes valid. Before this date, it is not valid. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

Encoded
Uint8Array

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

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

EncodedB
byte[]

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

ExpirationDate
string

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

23-Jan-2001 15:00:00.

ExtendedKeyUsage
string

This is a comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

Fingerprint
string

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

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

FingerprintSHA1
string

This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

FingerprintSHA256
string

This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

Issuer
string

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

KeyPassword
string

This is 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 . . This field can be used to read such password-protected private keys.

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

PrivateKey
string

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

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

PrivateKeyAvailable
boolean

This property shows whether a is available for the selected certificate. If is True, the certificate may be used for authentication purposes (e.g., server authentication).

PrivateKeyContainer
string

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

PublicKey
string

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

PublicKeyAlgorithm
string

This property contains the textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

PublicKeyLength
number

This is the length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

SerialNumber
string

This is the serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

SignatureAlgorithm
string

The property contains the text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

Store
Uint8Array

This is the name of the certificate store for the client certificate.

The property denotes the type of the certificate store specified by . If the store is password protected, specify the password in .

is used in conjunction with the property to specify client certificates. If has a value, and or is set, a search for a certificate is initiated. Please see the 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:


MY	A certificate store holding personal certificates with their associated private keys.
CA	Certifying authority certificates.
ROOT	Root 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).

StoreB
byte[]

This is the name of the certificate store for the client certificate.

The property denotes the type of the certificate store specified by . If the store is password protected, specify the password in .

is used in conjunction with the property to specify client certificates. If has a value, and or is set, a search for a certificate is initiated. Please see the 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:


MY	A certificate store holding personal certificates with their associated private keys.
CA	Certifying authority certificates.
ROOT	Root certificates.

StorePassword
string

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

StoreType
CertStoreTypes

This is 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 and set 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);`
21 (cstBCFKSFile)	The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store). Note: this store type is only available in Java and .NET.
22 (cstBCFKSBlob)	The certificate store is a string (binary or base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format. Note: this store type is only available in Java and .NET.
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

This is 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.


Field	Meaning
CN	Common Name. This is commonly a host name like www.server.com.
O	Organization
OU	Organizational Unit
L	Locality
S	State
C	Country
E	Email Address

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

SubjectAltNames
string

This property contains comma-separated lists of alternative subject names for the certificate.

ThumbprintMD5
string

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

ThumbprintSHA1
string

This property contains the SHA-1 hash of the certificate. If the hash does not already exist, it is computed.

ThumbprintSHA256
string

This property contains the SHA-256 hash of the certificate. If the hash does not already exist, it is computed.

Usage
string

This property contains the text description of .

This value will be of one or more of the following strings and will be 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 X.509 certificate extension names.

UsageFlags
number

This property contains the flags that show intended use for the certificate. The value of is a combination of the following flags:


0x80	Digital Signatures
0x40	Key Authentication
0x20	Key Encryption
0x10	Data Encryption
0x08	Key Agreement
0x04	Certificate Signing
0x02	Key Signing

Please see the property for a text representation of .

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

Version
string

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

Constructors

public Certificate();

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

public Certificate(String certificateFile);

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

public Certificate(byte[] certificateData);

Parses CertificateData as an X509 public key.

public Certificate(int certStoreType, String store, String storePassword, String subject);

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 class 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 Certificate(int certStoreType, String store, String storePassword, String subject, String configurationString);

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 include "PersistPFXKey", which shows whether or not 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" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the class 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 Certificate(int certStoreType, String store, String storePassword, byte[] encoded);

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 class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject);

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 class 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 Certificate(int certStoreType, byte[] storeBlob, String storePassword, String subject, String configurationString);

public Certificate(int certStoreType, byte[] storeBlob, String storePassword, byte[] encoded);

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 class will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

Config Settings (class ipworks.syslog)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

Syslog Config Settings

AcceptData: Whether the component can accept/receive data.

When set to false the class will no longer be able to accept any data. The PacketIn event will not fire.

The default is true.

AppName: Sets the App-Name field in RFC 5424.

This setting specifies the App-Name field of the message as defined in RFC 5424