%XML.Security.EncryptedData
class %XML.Security.EncryptedData extends %XML.Security.EncryptedType
For details on using this class, see Encrypting XML Documents. and Encrypting SOAP Security Headers.
XML Encryption element.Property Inventory
Method Inventory
Parameters
parameter ELEMENTQUALIFIED = 1;
Inherited description: 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/2001/04/xmlenc#;
Inherited description: 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;
Inherited description: 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 CipherData as %XML.Security.CipherDataStream (XMLREF = 1) [ Required ];
Override of %XML.Security.EncryptedType property to allow > 32k of data
Property methods: CipherDataGet(), CipherDataGetSwizzled(), CipherDataIsValid(), CipherDataNewObject(), CipherDataSet()
property EncryptionProperties as %XML.Security.EncryptionProperties (XMLREF = 1);
Unchanged override of %XML.Security.EncryptedType property to maintain element position.
Property methods: EncryptionPropertiesGet(), EncryptionPropertiesGetSwizzled(), EncryptionPropertiesIsValid(), EncryptionPropertiesNewObject(), EncryptionPropertiesSet()
Methods
classmethod Create(keyElement As %XML.Security.EncryptedKey = "", elementToEncrypt As %SOAP.Security.Element, referenceOption As %Integer = "") as %XML.Security.EncryptedData
Create a EncryptedData element that is to be referenced from a ReferenceList Security element and
that is to carry content encrypted 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 elementToEncrypt argument specifies the oref of the element to be encrypted. It is currently only valid to encrypt the body or a Security element. The default is "" which means to encrypt the body.
- 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. The key size to be used for this EncryptedData element must be specified by setting the Algorithm property or by setting the Length property of the DerivedKey.
- $$$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.
method EncryptStream(messageStream As %BinaryStream, encryptedKeys As %ListOfObjects(ELEMENTTYPE="%XML.Security.EncryptedKey")) as %Status
EncryptStream encrypts messageStream and stores the encrypted content of
messageStream as the CipherData.
This completed EncryptedData instance may be exported using %XML.Writer to create an EncyptedData
element as required by the XML Encryption specification.
messageStream is the stream containing the data to be encrypted. messageStream must be positioned before calling EncryptStream -- for example by calling Rewind first.
encryptedKeys is a %ListOfObjects of instances of %XML.Security.EncryptedKey. The EncyptedStream method will compute a common random, symmetric key for all the elements in encryptedKeys and store the encrypted symmetric key in the EncryptedKey instance. Encryption of the symmetric key is done using the public key from the X.509 credentials associated with the EncyptedKey instance. The result is that messageStream may be decrypted by any recipient that has the private key associated with the X.509 certificate in one of the EncryptedKey instances.
The default value of any property of EncryptedData, such as Algorithm, Type and RequireBestEntropy, may be overridden before calling EncryptStream.
The following example encrypts messageStream based on the certifcates in the credentials called cred1 and cred2.
messageStream is the stream containing the data to be encrypted. messageStream must be positioned before calling EncryptStream -- for example by calling Rewind first.
encryptedKeys is a %ListOfObjects of instances of %XML.Security.EncryptedKey. The EncyptedStream method will compute a common random, symmetric key for all the elements in encryptedKeys and store the encrypted symmetric key in the EncryptedKey instance. Encryption of the symmetric key is done using the public key from the X.509 credentials associated with the EncyptedKey instance. The result is that messageStream may be decrypted by any recipient that has the private key associated with the X.509 certificate in one of the EncryptedKey instances.
The default value of any property of EncryptedData, such as Algorithm, Type and RequireBestEntropy, may be overridden before calling EncryptStream.
The following example encrypts messageStream based on the certifcates in the credentials called cred1 and cred2.
set encryptedKeys=##class(%ListOfObjects).%New()
set x5091 = ##class(%SYS.X509Credentials).GetByAlias("cred1")
do encryptedKeys.Insert(##class(#XML.Security.EncryptedKey).CreateX509(
x5091,,$$$KeyInfoX509SKI))
set x5092 = ##class(%SYS.X509Credentials).GetByAlias("cred2")
do encryptedKeys.Insert(##class(#XML.Security.EncryptedKey).CreateX509(
x5092,,$$$KeyInfoX509SKI))
set encryptedData=##class(#XML.Security.EncryptedData).%New()
set encryptedData.Algorithm=$$$SOAPWSaes256cbc ; default is $$$SOAPWSaes128cbc
set encryptedData.Type=$$$SOAPWSEncryptElement ; default is $$$SOAPWSEncryptContent
do messageStream.Rewind()
set status=encryptedData.EncryptStream(messageStream, encryptedKeys)
if $$$ISERR(status) .... handle error ....
method Reset()
Reset the element.
classmethod ValidateDocument(ByRef document As %XML.Document, encryptedKeys As %ListOfObjects(ELEMENTTYPE="%XML.Security.EncryptedKey")) as %Boolean
Validate a %XML.Document containing a parsed XML document which contains an EncryptedData
element and EncryptedKey elements.
document is the parsed document.
If decryption is valid, the document argument is updated with a new document which has the EncryptedData element replaced by the decypted text and true (1) is returned. If invalid return false (0).
encryptedKeys is a %ListOfObjects of instances of %XML.Security.EncryptedKey. The ValidateDocument method will decrypt the CipherData in the EncryptedData element found in the document based on one of the EncryptedKey elements in encryptedKeys. Any EncryptedKey elemetns which do not result in successful decryption are ignored. The result is that the EncryptedData in document may be decrypted by any recipient that has the private key associated with the X.509 certificate in one of the EncryptedKey instances.
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 EncryptedData to validate and decrypt is the SOAP message whose %XML.Document is contained in the ImportHandler property of the service.
If decryption is valid, the document argument is updated with a new document which has the EncryptedData element replaced by the decypted text and true (1) is returned. If invalid return false (0).
encryptedKeys is a %ListOfObjects of instances of %XML.Security.EncryptedKey. The ValidateDocument method will decrypt the CipherData in the EncryptedData element found in the document based on one of the EncryptedKey elements in encryptedKeys. Any EncryptedKey elemetns which do not result in successful decryption are ignored. The result is that the EncryptedData in document may be decrypted by any recipient that has the private key associated with the X.509 certificate in one of the EncryptedKey instances.
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 EncryptedData to validate and decrypt is the SOAP message whose %XML.Document is contained in the ImportHandler property of the service.
// Keys element is property containing a list of EncryptedKey elements.
// Keys is an arbitrary property name
set document=..ImportHandler
if ##class(%XML.Security.EncryptedData).ValidateDocument(.document,arg.Keys) {
set reader=##class(%XML.Reader).%New()
set reader.Document=document ; updated document to a reader instance
do reader.Correlate(.... ; Use reader to create classes
... Use Next loop to process payload ...
} else {
... process error ...
}
Inherited Members
Inherited Properties
Inherited 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()
- SetEncryptionMethod()
- XMLDTD()
- XMLExport()
- XMLExportToStream()
- XMLExportToString()
- XMLNew()
- XMLSchema()
- XMLSchemaNamespace()
- XMLSchemaType()