Class Reference
IRIS for UNIX 2019.4
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [%XML] >  [Security] >  [Signature]
Private  Storage   

class %XML.Security.Signature extends %SOAP.Security.Element

XML Signature element.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
3 14 19


Summary

Properties
Confirmed DigestMethodAlgorithm Id IsBodySigned
Key KeyInfo NodeId Object
OriginalElement PreProcessed ReferenceOption SignatureOptions
SignatureValue SignedInfo WasEncrypted X509Credentials

Methods
%%OIDGet %AddToSaveSet %BindExport %BuildObjectGraph
%ClassIsLatestVersion %ClassName %Close %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IncrementCount %IsA %IsModified
%New %NormalizeObject %ObjectModified %OriginalNamespace
%PackageName %RemoveFromSaveSet %SerializeObject %SetModified
%ValidateObject %XMLGenerate AddRM AddReference
ComputeSha1Digest Create CreateX509 GetDefaultMethods
GetId InitializeForService InitializeKey Perform
Reset SetDigestMethod SetSignatureMethod Sign
SignDocument SignStream ValidateDocument ValidateElement
XMLAfterExport XMLBeforeExport XMLDTD XMLExport
XMLExportInternal XMLExportToStream XMLExportToString XMLGetSchemaImports
XMLImport XMLImportInternal XMLIsObjectEmpty XMLNew
XMLSchema XMLSchemaNamespace XMLSchemaType


Parameters

• parameter ELEMENTQUALIFIED = 1;
ELEMENTQUALIFIED controls the format of exported XML. The ELEMENTQUALIFIED specification should be based on the elementFormDefault attribute of the schema that defines the type. To maintain compatibility, ELEMENTQUALIFIED will default to 1 (true) for literal format export and will default to 0 (false) for encoded or encoded12 format export. These were the values always previously assumed for the elementFormDefault attribute. NOTE: Direct use of XMLExport method does not support the ELEMENTQUALIFIED. The export must be done using %XML.Writer or SOAP support.
• parameter NAMESPACE = "http://www.w3.org/2000/09/xmldsig#";
NAMESPACE specifies the XML namespace to be used when projecting the class to XML. if NAMESPACE - "", the default namespace is used for the XML schema is used as the namespace for his class.
• parameter XMLFORMAT = "literal";
The XMLFORMAT parameter controls the generation of the XMLExport and XMLImport methods for XML enabled classes to include code for only literal or only encoded format. This allows the generated routines to be significantly smaller since usually both formats are not needed.
If XMLFORMAT="Literal", then only support for literal format import and export is generated.
If XMLFORMAT="Encoded", then only support for SOAP encoded format import and export is generated.
The default is to generate support for both literal and encoded format.

Properties

• property Confirmed as %Boolean(XMLPROJECTION="none");
If true, this signature has been confirmed by a WS-Security 1.1 SubjectConfirmation element.
• property DigestMethodAlgorithm as %String(XMLPROJECTION="none");
The default DigestMethod Algorithm for any references added to this Signature.
• property Id as %String(MAXLEN="",XMLPROJECTION="attribute");
Local Id attribute defined for XML Signature
• property IsBodySigned as %Boolean(XMLPROJECTION="none");
If true, then the SOAP Body is signed
• property Key as %Binary(XMLPROJECTION="none");
The symmetric key for hmac-sha1 signing.
• property KeyInfo as %XML.Security.KeyInfo;
• property NodeId as %String(XMLPROJECTION="none");
Save the node id of this element in the tree during import for canonicalizing later during signature verification.
• property Object as %XML.Security.Object;
• property PreProcessed as %Boolean(XMLPROJECTION="NONE") [ InitialExpression = 0 ];
The PreProcessed flag indicates whether the signature data in this signature is already valid and should not be recalculated when preparing a SOAP request for retransmission. In general this would only be useful when attempting to forward a specific signed entity such as a SAML assertion which contains a Signature element.
• property ReferenceOption as %String(XMLPROJECTION="none");
ReferenceOption argument from the Create call.
• property SignatureOptions as %Integer(XMLPROJECTION="none");
SignatureOptions specifies which parts of the message are to be signed. See %soap.inc definitions of $$$SOAPWSInclude.... for possibilities.
• property SignatureValue as %xsd.base64Binary(CANONICALXML=1);
• property SignedInfo as %XML.Security.SignedInfo;
• property X509Credentials as %RawString(XMLPROJECTION="none");
If signing is based on X509 certificate, this is the X509 certificate class. If signing is based on EncryptedKey, BinarySecret, DerivedKeyToken or SecurityContextToken element, then this element and Key property is defined.

Methods

• method AddRM(service As %SOAP.WebBase)
Add reference to WS-ReliableMessaging headers
• method AddReference(reference As %XML.Security.Reference, doNotReuse As %Boolean = 0)
Add a reference to XML element using an %XML.Security.Reference. The reference may be created by using the ##class(%XML.Security.Reference).Create method. If doNotReuse is true, then this reference will be removed during Reset
• method ComputeSha1Digest(node As %XML.Node, signNodeId As %String, writer As %XML.Writer, prefixList As %String, bitlength As %Integer, isSTR As %Boolean, ByRef text As %FileBinaryStream, mimeAttachments As %Net.MIMEPart) as %xsd.base64Binary
Compute SHA1 digest of an element
• classmethod Create(keyElement As %RegisteredObject = "", signatureOptions As %Integer, referenceOption As %Integer = "") as %XML.Security.Signature
Create a Signature element that is to be signed using the hmac-sha1 algorithm with a symmetric key specified by its KeyInfo element.
  • keyElement is the Security element which will supply the symmetric key. keyElement is meaningful only when referenceOption specified. See referenceOption for details.
  • The signatureOptions argument specifies the parts of the SOAP message to be signed. The default is to sign all addressing header, body and timestamp. See %soap.inc definitions of $$$SOAPWSInlcude.... for possibilities.
  • The referenceOption argument specifies the type of reference which will be in the KeyInfo. If referenceOption is "" or not specified, no KeyInfo is created. This is the default.
    • $$$SOAPWSReferenceEncryptedKey is reference to an EncryptedKey element in this message. The keyElement argument must be specified and is the EncryptedKey element.
    • $$$SOAPWSReferenceEncryptedKeySHA1 is reference by the SHA1 hash of the key contained in the EncryptedKey element specified as the first argument. If the keyElement is not specified, the key from the first EncryptedKey element in the received message is used.
    • $$$SOAPWSReferenceDerivedKey is reference to a DerivedKeyToken element in this message. The keyElement argument must be specified and is the DerivedKeyToken element.
    • $$$SOAPWSReferenceSCT is reference by wsu:Id to a SecurityContextToken element in this message. The keyElement argument must be specified and is the SecurityContextToken element.
    • $$$SOAPWSReferenceSCTIdentifier is reference by Identifier and Instance to a SecurityContextToken element not necessarily in this message. The keyElement argument must be specified and is the SecurityContextToken element.
    • $$$SOAPWSSAML is reference to SAML Assertion which contains an EncryptedKey or BinarySecret element in the KeyInfo that is in the SubjectConfirmationData. The keyElement argument must be specified and is the SAML Assertion element.
• classmethod CreateX509(credentials As %SYS.X509Credentials = "", signatureOptions As %Integer, referenceOption As %Integer, Output status As %Status) as %XML.Security.Signature
Create a Signature element that is to be signed using the RSA private key that is associated with the specified X509 certificate.
  • The first argument can be a %SYS.X509Credentials instance, a %SAML.Assertion instance, or a %SOAP.Security.BinarySecurityToken instance. This argument indicates the X509 certificate to use.
    • If this argument is a %SYS.X509Credentials instance, the instance should refer to the X509 certificate to use.
    • If this argument is a %SAML.Assertion instance, its SubjectConfirmation should be based on the X.509 credentials to use.
    • If this argument is a %SOAP.Security.BinarySecurityToken instance, it should contain the X.509 certificate to use; this is the technique for a direct reference.
  • The signatureOptions argument specifies the parts of the SOAP message to be signed. The default is to sign all addressing header, body and timestamp. See %soap.inc definitions of $$$SOAPWSInlcude.... for possibilities.
  • The referenceOption argument specifies the type of reference to create. See %soap.inc definitions of $$$SOAPWSReference.... and $$$KeyInfoX509.... The default is to use a direct reference if the first argument is a binary security token or to use the Thumbprint if the first argument is a %SYS.X509Credentials instance.
  • If no signature is returned the status argument is set to the error %Status.
• classmethod GetDefaultMethods(Output digest As %String, Output signature As %String, Output hmac As %String)
Get default digest, signature and hmac methods
• private method GetNodeById(uri As %String, document As %XML.Document, node As %XML.Node) as %String
Get node based on id from URI. Return nodeId
• method InitializeForService(service As %SOAP.WebBase, header As %SOAP.Security.Header = "") as %Status
Initialize the signature based on the SignatureOptions of a web client or service. %XML.Security.Signature may be initialized directly by using calls to AddReference.
• private method InitializeValue(service As %SOAP.WebBase) as %Status
Validate correct size to the Signature element
• method Perform(messageStream As %BinaryStream, header As %SOAP.Security.Header) as %Status
Complete the Signature element and update the message stream with the new SignatureValue
• method Reset()
Reset the Signature element.
• method SetDigestMethod(algorithm As %String)
Set the digest method algorithm to be used for signing. The algorithm is reflected in the Algorithm attribute of the DigestMethod element of each Reference element of the SignedInfo element of the Signature element. Possible values for algortihm are $$$SOAPWSsha1, $$$SOAPWSsha256, $$$SOAPWSsha384 and $$$SOAPWSsha512.
• method SetSignatureMethod(algorithm As %String)
Set the signature method algorithm to be used for signing. The algorithm is reflected in the Algorithm attribute of the SignatureMethod element the SignedInfo element of the Signature element. Possible values for algortihm are $$$SOAPWSrsasha1, $$$SOAPWSrsasha256, $$$SOAPWSrsasha384 and $$$SOAPWSrsasha512.
• method Sign(document As %XML.Document, header As %SOAP.Security.Header, mimeAttachments As %Net.MIMEPart) as %Status
Complete the Signature element by adding the SignedInfo based on X509Credentials and compute the signature value.
• method SignDocument(document As %XML.Document, mimeAttachments As %Net.MIMEPart = "") as %Status
SignDocument completes the Signature element by adding the SignedInfo based on X509Credentials and computes the signature value for the parsed XML document to be signed. document is an %XML.Document obtained by parsing the stream ot be signed.

If the document is an MTOM document, then the optional mimeAttachments argument contains a single MIME part which has each MIME section as one of its child Parts.

The following example creates a stream which contains an XML document whose root object is is given by the oref obj. This oref is assumed to be an instance of an XML-enabled class that has the following properties:
  • A property that is projected to XML as the Id attribute. In this example, this is the Signed.Id property.
  • property that is intended to contain the signature itself and that is projected to XML as the element. In this example, this is the Signature property.
	set writer=##class(%XML.Writer).%New()
	set stream=##class(%FileBinaryStream).%New()
	set status=writer.OutputToStream(stream)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
	set status=writer.RootObject(obj)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
		
	set x509=##class(%SYS.X509Credentials).GetByAlias("MyCredentials")
	set signature=##class(%XML.Security.Signature).CreateX509(
	                x509,$$$SOAPWSIncludeNone,$$$KeyInfoX509Certificate)
	// Signature based on id of contained Signed element 
	// Note that name Signed is arbitrary.
	do signature.AddReference(
	  ##class(%XML.Security.Reference).Create(obj.Signed.id))
	// We parse the stream to create a document which we will sign.
	set status=
	  ##class(%XML.Document).GetDocumentFromStream(stream,.document)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
	set status=signature.SignDocument(document)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
	// Signature element is property of any name
	// Signature is arbitrary property name
	set obj.Signature=signature
	// Output the signed stream now that the signature is computed.
	set stream=##class(%FileBinaryStream).%New()
	set status=writer.OutputToStream(stream)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
	set status=writer.RootObject(obj)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
• method SignStream(messageStream As %BinaryStream, mimeAttachments As %Net.MIMEPart = "") as %Status
SignStream completes the Signature element by adding the SignedInfo based on X509Credentials and computes the signature value for the XML stream to be signed. messageStream is a stream containing the XML to be signed.

If the document is an MTOM document, then the optional mimeAttachments argument contains a single MIME part which has each MIME section as one of its child Parts.

The following example creates a stream which contains an XML document whose root object is is given by the oref obj. This oref is assumed to be an instance of an XML-enabled class that has the following properties:
  • A property that is projected to XML as the Id attribute. In this example, this is the Signed.Id property.
  • property that is intended to contain the signature itself and that is projected to XML as the element. In this example, this is the Signature property.
	set writer=##class(%XML.Writer).%New()
	set stream=##class(%FileBinaryStream).%New()
	set status=writer.OutputToStream(stream)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
	set status=writer.RootObject(obj)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
		
	set x509 = ##class(%SYS.X509Credentials).GetByAlias("MyCredentials")
	set signature=##class(%XML.Security.Signature).CreateX509(
	                x509,$$$SOAPWSIncludeNone,$$$KeyInfoX509Certificate)
	// Signature based on id of contained Signed element
	// Note that the name Signed is arbitrary.
	do signature.AddReference(
	  ##class(%XML.Security.Reference).Create(obj.Signed.id))
	set status=signature.SignStream(stream)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
	// Signature element is property of any name
	// Signature is an arbitrary property name
	set obj.Signature=signature
	// Output the signed stream now that the signature is computed.
	set stream=##class(%FileBinaryStream).%New()
	set status=writer.OutputToStream(stream)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
	set status=writer.RootObject(obj)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
• method ValidateDocument(document As %XML.Document, mimeAttachments As %Net.MIMEPart = "", CAFile As %String = "") as %Status
Validate a %XML.Document containing a parsed XML document which contains a signature. The %XML.Signature element must be obtained from the same instance of %XML.Document that you are validating. If invalid return an error %Status.

If the document is an MTOM document, then the optional mimeAttachments argument contains a single MIME part which has each MIME section as one of its child Parts.

The CAFile argument is the full path of file which contains the certificate authority certificates which are to be used to validate the signing certificate.

The following example assumes a single argument web service method with the argument named arg. This will usually be the case with an entire message being the argument since Parameter ARGUMENTSTYLE = "message". The document to validate is the SOAP message whose %XML.Document is contained in the ImportHandler property of the service. Also exclusive canonicalization must be used because the entire SOAP envelope is represented in ..Importhandler. If inclusive canonicalization needs to be used, then the ProcessBody or ProcessBodyNode methods must be used which allows access to just the Body contents as a document.
	// Signature element is property of any name.
	// Signature is arbitrary property name
	set signature=arg.Signature
	set status=signature.ValidateDocument(..ImportHandler)
	if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
• method ValidateElement(document As %XML.Document, service As %SOAP.WebBase = "", mimeAttachments As %Net.MIMEPart = "", CAFile As %String = "") as %String
Validate the security header element. If invalid return an error code.

If the document is an MTOM document, then the optional mimeAttachments argument contains a single MIME part which has each MIME section as one of its child Parts.

The CAFile argument is the full path of file which contains the certificate authority certificates which are to be used to validate the signing certificate.

• classmethod XMLNew(document As %XML.Document, nodeId As %Integer, containerOref As %RegisteredObject = "") as %RegisteredObject
Save the node if when getting a new class instance.


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.