|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.opensaml.xml.encryption.Decrypter
public class Decrypter
Supports decryption of XMLObjects which represent data encrypted according to the XML Encryption specification, version 20021210.
Details on the components specified as constructor options are as follows:
newResolver
: This KeyInfoCredentialResolver
instance is used to resolve keys (as Credentials)
based on the KeyInfo of EncryptedData elements. While it could in theory be used to handle the complete process of
resolving the data decryption key, including decrypting any necessary EncryptedKey's, it would typically
be used in cases where encrypted key transport via an EncryptedKey is not being employed.
This corresponds to scenarios where decryption is instead based on resolving the (presumably shared secret)
symmetric data decryption key directly, based on either context or information present in the
EncryptedData's KeyInfo. In cases where the data decryption key is to be resolved by decrypting an EncryptedKey,
this resolver would typically not be used and may be null
.
newKEKResolver
: This KeyInfoCredentialResolver
instance is used to resolve keys (as Credentials)
used to decrypt EncryptedKey elements, based on the KeyInfo information contained within the EncryptedKey element
(also known as a Key Encryption Key or KEK). For asymmetric key transport of encrypted keys, this would entail
resolving the private key which corresponds to the public key which was used to encrypt the EncryptedKey.
newEncKeyResolver
: This EncryptedKeyResolver
instance is responsible for resolving
the EncryptedKey element(s) which hold(s) the encrypted data decryption key which would be used to
decrypt an EncryptedData element.
XML Encryption can encrypt either a single Element
or the contents of an Element. The caller of this class
must select the decryption method which is most appropriate for their specific use case.
Note that the type of plaintext data contained by an EncryptedData
can be checked prior to decryption by
examining that element's type
attribute (EncryptedType.getType()
). This (optional) attribute
may contain one of the following two constant values to aid in the decryption process:
EncryptionConstants.TYPE_ELEMENT
or EncryptionConstants.TYPE_CONTENT
.
By nature the fundamental output of XML decryption is a DOM DocumentFragment
with 1 or more immediate
top-level DOM Node
children. This case is reflected in the method decryptDataToDOM(EncryptedData)
.
It is up to the caller to properly process the DOM Nodes which are the children of this document fragment. The
DocumentFragment and its Node children will be owned by the DOM Document
which owned the original
EncryptedData before decryption. Note, however, that the Node children will not be a part of the tree of Nodes rooted
at that Document's document element.
A typical use case will be that the content which was encrypted contained solely Element
nodes. For this use
case a convenience method is provided as decryptDataToList(EncryptedData)
, which returns a list of
XMLObject
's which are the result of unmarshalling each of the child Elements of the decrypted
DocumentFragment.
Another typical use case is that the content which was encrypted was a single Element. For this use case a
convenience method is provided as decryptData(EncryptedData)
, which returns a single XMLObject which was
the result of unmarshalling this decrypted Element.
In both of these cases the underlying DOM Element which is represented by each of the returned XMLObjects will be
owned by the DOM Document which also owns the original EncrytpedData Element. However, note that these cached DOM
Elements are not part of the tree of Nodes rooted at that Document's document element. If these
returned XMLObjects are then inserted as the children of other XMLObjects, it is up to the caller to ensure that the
XMLObject tree is then remarshalled if the relationship of the cached DOM nodes is important (e.g. resolution of
ID-typed attributes via Document.getElementById(String)
).
For some use cases where the returned XMLObjects will not necessarily be stored back as children of another parent
XMLObject, it may still necessary for the DOM Elements of the resultant XMLObjects to exist within the tree of Nodes
rooted at a DOM Document's document element (e.g. signature verification on the standalone decrypted XMLObject). For
these cases these method variants may be used: decryptDataToList(EncryptedData, boolean)
and
decryptData(EncryptedData, boolean)
. The rootInNewDocument
parameter is explained below.
A default value for this parameter, for the overloaded convenience methods
which do not take this parameter explicitly, may be set via setRootInNewDocument(boolean)
.
This default value is initialized to false
.
If the boolean option rootInNewDocument
is true at the time of decryption,
then for each top-level child Element of the decrypted DocumentFragment, the following will occur:
Note that new Document creation, node adoption and rooting the new document element are potentially very expensive. This should only be done where the caller's use case really requires it.
Field Summary | |
---|---|
private boolean |
defaultRootInNewDocument
Flag to determine whether by default the Element which backs the underlying decrypted SAMLObject will be the root of a new DOM document. |
private EncryptedKeyResolver |
encKeyResolver
Resolver for EncryptedKey instances which contain the encrypted data encryption key. |
private String |
jcaProviderName
The name of the JCA security provider to use. |
private KeyInfoCredentialResolver |
kekResolver
Resolver for key encryption keys. |
private CriteriaSet |
kekResolverCriteria
Additional criteria to use when resolving credentials based on an EncryptedKey's KeyInfo. |
private Logger |
log
Class logger. |
private BasicParserPool |
parserPool
ParserPool used in parsing decrypted data. |
private KeyInfoCredentialResolver |
resolver
Resolver for data encryption keys. |
private CriteriaSet |
resolverCriteria
Additional criteria to use when resolving credentials based on an EncryptedData's KeyInfo. |
private UnmarshallerFactory |
unmarshallerFactory
Unmarshaller factory, used in decryption of EncryptedData objects. |
Constructor Summary | |
---|---|
Decrypter(KeyInfoCredentialResolver newResolver,
KeyInfoCredentialResolver newKEKResolver,
EncryptedKeyResolver newEncKeyResolver)
Constructor. |
Method Summary | |
---|---|
private CriteriaSet |
buildCredentialCriteria(EncryptedType encryptedType,
CriteriaSet staticCriteria)
Utility method to build a new set of credential criteria based on the KeyInfo of an EncryptedData or EncryptedKey, and any additional static criteria which might have been supplied to the decrypter. |
private KeyAlgorithmCriteria |
buildKeyAlgorithmCriteria(String encAlgorithmURI)
Dynamically construct key algorithm credential criteria based on the specified algorithm URI. |
private Set<Criteria> |
buildKeyCriteria(EncryptedType encryptedType)
Build decryption key credential criteria according to information in the encrypted type object. |
private KeyLengthCriteria |
buildKeyLengthCriteria(String encAlgorithmURI)
Dynamically construct key length credential criteria based on the specified algorithm URI. |
protected void |
checkAndMarshall(XMLObject xmlObject)
Ensure that the XMLObject is marshalled. |
XMLObject |
decryptData(EncryptedData encryptedData)
This is a convenience method for calling decryptData(EncryptedData, boolean) ,
with the rootInNewDocument parameter value supplied by isRootInNewDocument() . |
XMLObject |
decryptData(EncryptedData encryptedData,
boolean rootInNewDocument)
Decrypts the supplied EncryptedData and returns the resulting XMLObject. |
DocumentFragment |
decryptDataToDOM(EncryptedData encryptedData)
Decrypts the supplied EncryptedData and returns the resulting DOM DocumentFragment . |
DocumentFragment |
decryptDataToDOM(EncryptedData encryptedData,
Key dataEncKey)
Decrypts the supplied EncryptedData using the specified key, and returns the resulting DOM DocumentFragment . |
List<XMLObject> |
decryptDataToList(EncryptedData encryptedData)
This is a convenience method for calling decryptDataToList(EncryptedData, boolean) ,
with the rootInNewDocument parameter value supplied by isRootInNewDocument() . |
List<XMLObject> |
decryptDataToList(EncryptedData encryptedData,
boolean rootInNewDocument)
Decrypts the supplied EncryptedData and returns the resulting list of XMLObjects. |
Key |
decryptKey(EncryptedKey encryptedKey,
String algorithm)
Attempts to decrypt the supplied EncryptedKey and returns the resulting Java security Key object. |
Key |
decryptKey(EncryptedKey encryptedKey,
String algorithm,
Key kek)
Decrypts the supplied EncryptedKey and returns the resulting Java security Key object. |
private DocumentFragment |
decryptUsingResolvedEncryptedKey(EncryptedData encryptedData,
String algorithm)
Attempt to decrypt by resolving the decryption key by first resolving EncryptedKeys, and using the KEK credential resolver to resolve the key decryption for each. |
private DocumentFragment |
decryptUsingResolvedKey(EncryptedData encryptedData)
Attempt to decrypt by resolving the decryption key using the standard credential resolver. |
EncryptedKeyResolver |
getEncryptedKeyResolver()
Get the encrypted key resolver. |
String |
getJCAProviderName()
Get the Java Cryptography Architecture (JCA) security provider name that should be used to provide the decryption support. |
KeyInfoCredentialResolver |
getKEKResolver()
Get the key encryption key credential resolver. |
CriteriaSet |
getKEKResolverCriteria()
Get the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedKey element. |
KeyInfoCredentialResolver |
getKeyResolver()
Get the data encryption key credential resolver. |
boolean |
isRootInNewDocument()
Get the flag which indicates whether by default the DOM Element which backs a decrypted SAML object will be the root of a new DOM document. |
private DocumentFragment |
parseInputStream(InputStream input,
Document owningDocument)
Parse the specified input stream in a DOM DocumentFragment, owned by the specified Document. |
protected void |
preProcessEncryptedKey(EncryptedKey encryptedKey,
String algorithm,
Key kek)
Preprocess the EncryptedKey. |
void |
setEncryptedKeyResolver(EncryptedKeyResolver newResolver)
Set a new encrypted key resolver. |
void |
setJCAProviderName(String providerName)
Set the Java Cryptography Architecture (JCA) security provider name that should be used to provide the decryption support. |
void |
setKEKResolver(KeyInfoCredentialResolver newKEKResolver)
Set a new key encryption key credential resolver. |
void |
setKEKResolverCriteria(CriteriaSet newCriteria)
Set the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedKey element. |
void |
setKeyResolver(KeyInfoCredentialResolver newResolver)
Set a new data encryption key credential resolver. |
CriteriaSet |
setKeyResolverCriteria()
Get the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedData element. |
void |
setKeyResolverCriteria(CriteriaSet newCriteria)
Set the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedData element. |
void |
setRootInNewDocument(boolean flag)
Set the flag which indicates whether by default the DOM Element which backs a decrypted SAML object will be the root of a new DOM document. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
private final BasicParserPool parserPool
private UnmarshallerFactory unmarshallerFactory
private final Logger log
private KeyInfoCredentialResolver resolver
private KeyInfoCredentialResolver kekResolver
private EncryptedKeyResolver encKeyResolver
private CriteriaSet resolverCriteria
private CriteriaSet kekResolverCriteria
private String jcaProviderName
private boolean defaultRootInNewDocument
Constructor Detail |
---|
public Decrypter(KeyInfoCredentialResolver newResolver, KeyInfoCredentialResolver newKEKResolver, EncryptedKeyResolver newEncKeyResolver)
newResolver
- resolver for data encryption keys.newKEKResolver
- resolver for key encryption keys.newEncKeyResolver
- resolver for EncryptedKey elementsMethod Detail |
---|
public boolean isRootInNewDocument()
public void setRootInNewDocument(boolean flag)
flag
- the current value of the flag for this decrypter instancepublic String getJCAProviderName()
null
, which means that the first registered provider which supports the indicated
encryption algorithm URI will be used.
public void setJCAProviderName(String providerName)
null
, which means that the first registered provider which supports the indicated
encryption algorithm URI will be used.
providerName
- the JCA provider name to usepublic KeyInfoCredentialResolver getKeyResolver()
public void setKeyResolver(KeyInfoCredentialResolver newResolver)
newResolver
- the new data encryption key resolverpublic KeyInfoCredentialResolver getKEKResolver()
public void setKEKResolver(KeyInfoCredentialResolver newKEKResolver)
newKEKResolver
- the new key encryption key resolverpublic EncryptedKeyResolver getEncryptedKeyResolver()
public void setEncryptedKeyResolver(EncryptedKeyResolver newResolver)
newResolver
- the new encrypted key resolverpublic CriteriaSet setKeyResolverCriteria()
public void setKeyResolverCriteria(CriteriaSet newCriteria)
newCriteria
- the static criteria set to usepublic CriteriaSet getKEKResolverCriteria()
public void setKEKResolverCriteria(CriteriaSet newCriteria)
newCriteria
- the static criteria set to usepublic XMLObject decryptData(EncryptedData encryptedData) throws DecryptionException
decryptData(EncryptedData, boolean)
,
with the rootInNewDocument
parameter value supplied by isRootInNewDocument()
.
encryptedData
- encrypted data element containing the data to be decrypted
DecryptionException
- exception indicating a decryption error, possibly because the decrypted data
contained more than one top-level Element, or some non-Element Node type.public XMLObject decryptData(EncryptedData encryptedData, boolean rootInNewDocument) throws DecryptionException
encryptedData
- encrypted data element containing the data to be decryptedrootInNewDocument
- if true, root the underlying Element of the returned XMLObject in a new Document as
described in Decrypter
DecryptionException
- exception indicating a decryption error, possibly because the decrypted data
contained more than one top-level Element, or some non-Element Node type.public List<XMLObject> decryptDataToList(EncryptedData encryptedData) throws DecryptionException
decryptDataToList(EncryptedData, boolean)
,
with the rootInNewDocument
parameter value supplied by isRootInNewDocument()
.
encryptedData
- encrypted data element containing the data to be decrypted
DecryptionException
- exception indicating a decryption error, possibly because the decrypted data
contained DOM nodes other than type of Elementpublic List<XMLObject> decryptDataToList(EncryptedData encryptedData, boolean rootInNewDocument) throws DecryptionException
encryptedData
- encrypted data element containing the data to be decryptedrootInNewDocument
- if true, root the underlying Elements of the returned XMLObjects in a new Document as
described in Decrypter
DecryptionException
- exception indicating a decryption error, possibly because the decrypted data
contained DOM nodes other than type of Elementpublic DocumentFragment decryptDataToDOM(EncryptedData encryptedData) throws DecryptionException
DocumentFragment
.
encryptedData
- encrypted data element containing the data to be decrypted
DocumentFragment
DecryptionException
- exception indicating a decryption errorpublic DocumentFragment decryptDataToDOM(EncryptedData encryptedData, Key dataEncKey) throws DecryptionException
DocumentFragment
.
encryptedData
- encrypted data element containing the data to be decrypteddataEncKey
- Java Key with which to attempt decryption of the encrypted data
DocumentFragment
DecryptionException
- exception indicating a decryption errorpublic Key decryptKey(EncryptedKey encryptedKey, String algorithm) throws DecryptionException
encryptedKey
- encrypted key element containing the encrypted key to be decryptedalgorithm
- the algorithm associated with the decrypted key
DecryptionException
- exception indicating a decryption errorpublic Key decryptKey(EncryptedKey encryptedKey, String algorithm, Key kek) throws DecryptionException
encryptedKey
- encrypted key element containing the encrypted key to be decryptedalgorithm
- the algorithm associated with the decrypted keykek
- the key encryption key with which to attempt decryption of the encrypted key
DecryptionException
- exception indicating a decryption errorprotected void preProcessEncryptedKey(EncryptedKey encryptedKey, String algorithm, Key kek) throws DecryptionException
encryptedKey
- encrypted key element containing the encrypted key to be decryptedalgorithm
- the algorithm associated with the decrypted keykek
- the key encryption key with which to attempt decryption of the encrypted key
DecryptionException
- exception indicating a decryption errorprivate DocumentFragment decryptUsingResolvedKey(EncryptedData encryptedData)
encryptedData
- the encrypted data to decrypt
private DocumentFragment decryptUsingResolvedEncryptedKey(EncryptedData encryptedData, String algorithm)
encryptedData
- the encrypted data to decryptalgorithm
- the algorithm of the key to be decrypted
private DocumentFragment parseInputStream(InputStream input, Document owningDocument) throws DecryptionException
input
- the InputStream to parseowningDocument
- the Document which will own the returned DocumentFragment
DecryptionException
- thrown if there is an error parsing the input streamprivate CriteriaSet buildCredentialCriteria(EncryptedType encryptedType, CriteriaSet staticCriteria)
encryptedType
- an EncryptedData or EncryptedKey for which to resolve decryption credentialsstaticCriteria
- static set of credential criteria to add to the new criteria set
private Set<Criteria> buildKeyCriteria(EncryptedType encryptedType)
encryptedType
- the encrypted type from which to deduce decryption key criteria
private KeyAlgorithmCriteria buildKeyAlgorithmCriteria(String encAlgorithmURI)
encAlgorithmURI
- the algorithm URI
private KeyLengthCriteria buildKeyLengthCriteria(String encAlgorithmURI)
encAlgorithmURI
- the algorithm URI
protected void checkAndMarshall(XMLObject xmlObject) throws DecryptionException
xmlObject
- the object to check and marshall
DecryptionException
- thrown if there is an error when marshalling the XMLObject
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |