Class %Net.X509Certificate

class %Net.X509Certificate extends %RegisteredObject

This class can be used to query the SSL PeerCertificate retrieved by %Net.HttpRequest when SSLCheckIdentityServer is enabled.
It also contains convenience wrappers for %SYSTEM.Encryption X509 methods.
Passing all the validity checks in this class does not mean the SSL Peer Certificate is valid.

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
	8	11

Summary

Properties
CAFile	CRLFile	CertChainCheck	Certificate	LifeSpanCheck
NotAfterCheck	NotBeforeCheck	SSLCNCheck

Methods
%AddToSaveSet	%ClassIsLatestVersion	%ClassName	%ConstructClone
%DispatchClassMethod	%DispatchGetModified	%DispatchGetProperty	%DispatchMethod
%DispatchSetModified	%DispatchSetMultidimProperty	%DispatchSetProperty	%Extends
%GetParameter	%IsA	%IsModified	%New
%NormalizeObject	%ObjectModified	%OriginalNamespace	%PackageName
%RemoveFromSaveSet	%SerializeObject	%SetModified	%ValidateObject
Extension	Field	RetrievePeerCertUsingJSON	RetrievePeerCertificate
RunVerificationChecks	VerifyCertChain	VerifyLifeSpan	VerifyNotAfter
VerifyNotBefore

Properties

• property CAFile as %String(MAXLEN="");

CAFile - Name of a file containing trusted Certificate Authority certificates
Used by VerifyCertChain

• property CRLFile as %String(MAXLEN="");

CRLFile - Name of a file containing Certificate Revocation lists (optional) Used by VerifyCertChain

• property CertChainCheck as %String(MAXLEN="");

Output from running $SYSTEM.Encryption.X509VerifyCertChain as executed by VerifyCertChain on Certificate with CAFile and optional CRLFile

• property Certificate as %Binary(MAXLEN="");

X.509 digital certificate

• property LifeSpanCheck as %Boolean;

Boolean test result of checking if the number of days between the ValidityNotBefore and the ValidityNotBefore fields in Certificate is less than the maximum number of days used by VerifyLifeSpan
The default maximum days is set to 730.

• property NotAfterCheck as %Boolean;

Boolean test result of checking if ValidityNotAfter field in Certificate is after or the same as the current time.

• property NotBeforeCheck as %Boolean;

Boolean test result of checking if ValidityNotBefore field in Certificate is before or the same as the current time.

• property SSLCNCheck as %Status;

Status returned by %Net.HttpRequest CheckSSLCN method when SSLCheckServerIdentity is true.
By examining the return from %Net.HttpRequest Send the RetrievePeerCertificate will set this to $$$OK if the return from Send is $$$OK or the errors SSLCertificateNoMatch or SSLNoCertificate as returned by %Net.HttpRequest Send
If a different error is returned then SSLCNCheck is left as empty

Methods

• method Extension(pX509Extension As %String, Output pStatus As %Status = $$$OK)

Convenience method to prepend Extension: to the pX509Extension before calling Field

• method Field(pX509Field As %String, Output pStatus As %Status = $$$OK)

Call X509GetField on the Certificate for the pX509Field
Returns in the pStatus status of the call.
See %SYSTEM.Encryption for documention on the X509GetField method.

• classmethod RetrievePeerCertUsingJSON(pHttpInfo As %DynamicObject, Output pHttpRequest As %Net.HttpRequest, Output pSSLPeerCert As %Net.X509Certificate) as %Status

Convenience method to call RetrievePeerCertificate using a %Library.DynamicObject to create the initial %Net.HttpRequest object and provide the other optional parameters.
The structure of the pHttpInfo dynamic object is:
{"url":,
{"verb":},
{"request":{"properties of %Net.HttpRequest...","Server":"docs.intersystems.com","SSLConfiguration":"ClientSSLConfig"}}

• classmethod RetrievePeerCertificate(ByRef pHttpRequest As %Net.HttpRequest, pURL As %String = "/", pVerb As %String = "OPTIONS", Output pSSLPeerCert As %Net.X509Certificate) as %Status

Convenience method to make an HTTPS Request that will populate the SSLPeerCertificate property of %Net.HttpRequest using a pre-existing %Net.HttpRequest object and instantiate pSSLPeerCert of type %Net.X509Certificate if the certificate was retrieved or Server identification check failed.
For convenience the property SSLCheckServerIdentity is set to true.
pURL defaults to /
pVerb defaults to OPTIONS
The status returned will be the status returned by the %Net.HttpRequest Send method unless the error is $$$SSLNoCertificate or $$$SSLCertificateNoMatch in which an $$$OK will be returned and the SSLCNCheck will contain SSL Server Identity Check error.

• method RunVerificationChecks(pVerifyCertChain As %Boolean = 1, pLifeSpanMaxDays As %Integer = 730) as %Boolean

Run the methods:
VerifyCertChain if pVerifyCertChains is true (the default is true)
VerifyLifeSpan using pLifeSpanMaxDays (the default is 730 days)
VerifyNotBefore
VerifyNotAfter
This method returns true if the checks that were run passed and and if the initial SSL Server Identity check (SSLCNCheck) passed.

• method VerifyCertChain() as %String

Output from running $SYSTEM.Encryption.X509VerifyCertChain as on Certificate with CAFile and optional CRLFile.
Also populates return in CertChainCheck

• method VerifyLifeSpan(pMaxDays As %Integer = 730) as %Boolean

Boolean test result of checking if the number of days between the ValidityNotBefore and the ValidityNotBefore fields in Certificate is less than the maximum number of days used by pMaxDays
The default maximum days is set to 730.
The result is also stored in LifeSpanCheck
If an error is encountered retrieving the value of ValidityNotBefore or ValidityNotAfter from the certificate the returned value is False.

• method VerifyNotAfter() as %Boolean

Boolean test result of checking if ValidityNotAfter field in Certificate is after or the same as the current time.
The result is also stored in NotBeforeAfter
If an error is encountered retrieving the value of ValidityNotAfter from the certificate the returned value is False.

• method VerifyNotBefore() as %Boolean

Boolean test result of checking if ValidityNotBefore field in Certificate is before or the same as the current time.
The result is also stored in NotBeforeCheck
If an error is encountered retrieving the value of ValidityNotBefore from the certificate the returned value is False.

Class Reference IRIS for UNIX 2024.1.2
Documentation Search