Класс XMLSignatureFactory

public abstract class XMLSignatureFactory
extends Object

Фабрика для создания объектов XMLSignature с нуля или для разбора объекта XMLSignature из соответствующего XML-представления.

Тип XMLSignatureFactory

Каждый экземпляр XMLSignatureFactory поддерживает определённый тип XML-механизма. Для создания XMLSignatureFactory, вызовите один из статических методов getInstance, передав желаемый тип XML-механизма, например:

XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");

Объекты, создаваемые этой фабрикой, будут основаны на DOM и подчиняться требованиям межплатформенной совместимости DOM, как определено в разделе Требованиях к механизму DOM обзора API. Список стандартных типов механизмов см. в разделе Поставщики сервисов обзора API.

Реализации XMLSignatureFactory регистрируются и загружаются с помощью механизма Provider. Например, поставщик сервиса, поддерживающий механизм DOM, будет указан в подклассе Provider следующим образом:

put("XMLSignatureFactory.DOM", "org.example.DOMXMLSignatureFactory");

Реализация ДОЛЖНА минимально поддерживать тип механизма по умолчанию: DOM.

Обратите внимание, что вызывающий код должен использовать один и тот же экземпляр XMLSignatureFactory для создания объектов XMLStructure конкретного XMLSignature , который должен быть сгенерирован. Поведение не определено, если объекты XMLStructure из разных поставщиков или разных типов механизмов используются вместе.

Кроме того, объекты XMLStructure, создаваемые этой фабрикой, могут содержать состояние, специфичное для XMLSignature, и не предназначены для повторного использования.

Создание XMLSignatures с нуля

После создания XMLSignatureFactory, объекты могут быть созданы путём вызова соответствующего метода. Например, экземпляр Reference можно создать, вызвав один из методов newReference.

Разбор XMLSignatures из XML

В качестве альтернативы, XMLSignature можно создать из существующего XML-представления, вызвав метод unmarshalXMLSignature и передав ему экземпляр XMLValidateContext, специфичный для механизма, содержащий XML-содержимое:

DOMValidateContext context = new DOMValidateContext(key, signatureElement);
 XMLSignature signature = factory.unmarshalXMLSignature(context);

Каждый XMLSignatureFactory должен поддерживать необходимые типы XMLValidateContext для этого типа фабрики, но может поддерживать и другие. DOM XMLSignatureFactory должен поддерживать объекты DOMValidateContext.

Подпись и преобразование XMLSignatures в XML

Каждый XMLSignature созданный фабрикой, также может быть преобразован в XML-представление и подписан путём вызова метода sign объекта XMLSignature и передачей ему объекта XMLSignContext, специфичного для механизма, содержащего ключ для подписи и параметры преобразования (см. DOMSignContext). Например:

DOMSignContext context = new DOMSignContext(privateKey, document);
    signature.sign(context);

Доступ к данным в многопоточном режиме

Статические методы этого класса гарантируют потокобезопасность. Несколько потоков могут одновременно вызывать статические методы, определенные в этом классе, без негативных последствий.

Однако это не относится к нестатическим методам, определенным в этом классе. Если не указано иное конкретным поставщиком, потоки, которые нуждаются в одновременном доступе к одному экземпляру XMLSignatureFactory , должны синхронизироваться между собой и обеспечить необходимую блокировку. Несколько потоков, каждый из которых манипулирует разными экземплярами XMLSignatureFactory , синхронизироваться не нужно.

Конструкторы

XMLSignatureFactory

protected XMLSignatureFactory()

Конструктор по умолчанию, для вызова подклассами.

Методы

getInstance

public static XMLSignatureFactory getInstance(String mechanismType)

Параметры:

mechanismType - тип механизма обработки XML и представления. Список стандартных типов механизмов см. в разделе «Поставщики служб» в обзоре API.

Возвращает:

новый XMLSignatureFactory

Исключения:

NullPointerException - если mechanismType является null

NoSuchMechanismException - если ни один Provider не поддерживает реализацию XMLSignatureFactory для указанного механизма

См. также:

Provider

getInstance

public static XMLSignatureFactory getInstance(String mechanismType,
                                              Provider provider)

Возвращает XMLSignatureFactory , поддерживающий запрашиваемый механизм обработки XML и тип представления (например, "DOM"), предоставленный указанным поставщиком. Обратите внимание, что указанный объект Provider не обязательно должен быть зарегистрирован в списке поставщиков.

Параметры:

mechanismType - тип механизма обработки XML и представления. Список стандартных типов механизмов см. в разделе «Поставщики служб» в обзоре API.

provider - объект Provider

Возвращает:

новый XMLSignatureFactory

Исключения:

NullPointerException - если provider или mechanismType является null

NoSuchMechanismException - если реализация XMLSignatureFactory для указанного механизма недоступна от указанного объекта Provider

См. также:

Provider

getInstance

public static XMLSignatureFactory getInstance(String mechanismType,
                                              String provider)
                                       throws NoSuchProviderException

Параметры:

mechanismType - тип механизма обработки XML и представления. Список стандартных типов механизмов см. в разделе «Поставщики служб» в обзоре API.

provider - строковое имя поставщика

Возвращает:

новый XMLSignatureFactory

Исключения:

NoSuchProviderException - если указанный поставщик не зарегистрирован в списке поставщиков безопасности

NullPointerException - если provider или mechanismType является null

NoSuchMechanismException - если реализация XMLSignatureFactory для указанного механизма недоступна от указанного поставщика

См. также:

Provider

getInstance

public static XMLSignatureFactory getInstance()

Возвращает:

новый XMLSignatureFactory

Исключения:

NoSuchMechanismException - если ни один Provider не поддерживает реализацию XMLSignatureFactory для механизма DOM

См. также:

Provider

getMechanismType

public final String getMechanismType()

Возвращает тип механизма обработки XML и представления, поддерживаемого этим XMLSignatureFactory (например, "DOM").

Возвращает:

тип механизма обработки XML, поддерживаемый этим XMLSignatureFactory

getProvider

public final Provider getProvider()

Возвращает поставщика этого XMLSignatureFactory.

Возвращает:

поставщик этого XMLSignatureFactory

newXMLSignature

public abstract XMLSignature newXMLSignature(SignedInfo si,
                                             KeyInfo ki)

Создает XMLSignature и инициализирует его содержимым указанных объектов SignedInfo и KeyInfo.

Параметры:

si - информация о подписанном документе

ki - информация о ключе (может быть null)

Возвращает:

объект XMLSignature

Исключения:

NullPointerException - если si является null

newXMLSignature

public abstract XMLSignature newXMLSignature(SignedInfo si,
                                             KeyInfo ki,
                                             List objects,
                                             String id,
                                             String signatureValueId)

Создает XMLSignature и инициализирует его указанными параметрами.

Параметры:

si - информация о подписанном документе

ki - информация о ключе (может быть null)

objects - список XMLObject (может быть пустым или null)

id - идентификатор (может быть null)

signatureValueId - идентификатор SignatureValue (может быть null)

Возвращает:

объект XMLSignature

Исключения:

NullPointerException - если si является null

ClassCastException - если какой-либо из objects не является объектом типа XMLObject

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm)

Создает Reference с указанным URI и методом хеширования.

Параметры:

uri - URI ссылки (может быть null)

dm - метод хеширования

Возвращает:

объект Reference

Исключения:

IllegalArgumentException - если uri не соответствует RFC 2396

NullPointerException - если dm является null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List transforms,
                                       String type,
                                       String id)

Создает Reference с указанными параметрами.

Параметры:

uri - URI ссылки (может быть null)

dm - метод хеширования

transforms - список Transform . Список копируется для защиты от последующих изменений. Может быть null или пустым.

type - тип ссылки в виде URI (может быть null)

id - идентификатор ссылки (может быть null)

Возвращает:

объект Reference

Исключения:

ClassCastException - если какой-либо из transforms не является объектом типа Transform

IllegalArgumentException - если uri не соответствует RFC 2396

NullPointerException - если dm является null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List transforms,
                                       String type,
                                       String id,
                                       byte[] digestValue)

Параметры:

uri — URI ссылки (может быть null)

dm — метод дайджеста

transforms — список Transformов. Список защищён от последующих изменений. Может быть null или пустым.

type — тип ссылки в виде URI (может быть null)

id — идентификатор ссылки (может быть null)

digestValue — значение дайджеста. Массив клонирован для защиты от последующих изменений.

Возвращает:

a Reference

Выбрасывает:

ClassCastException — если какой-либо из transforms не является Transform типа

IllegalArgumentException — если uri не соответствует RFC 2396

NullPointerException — если dm или digestValue имеют значение null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List appliedTransforms,
                                       Data result,
                                       List transforms,
                                       String type,
                                       String id)

Параметры:

uri — URI ссылки (может быть null)

dm — метод дайджеста

appliedTransforms — список Transformов, которые уже были применены. Список защищён от последующих изменений. Список должен содержать по крайней мере одну запись.

result — результат обработки последовательности appliedTransforms

transforms — список Transformов, которые должны быть применены при генерации подписи. Список защищён от последующих изменений. Может быть null или пустым.

type — тип ссылки в виде URI (может быть null)

id — идентификатор ссылки (может быть null)

Возвращает:

a Reference

Выбрасывает:

ClassCastException — если какое-либо из преобразований (в любом списке) не является Transform типа

IllegalArgumentException — если uri не соответствует RFC 2396 или appliedTransforms пусто

NullPointerException — если dm, appliedTransforms или result имеют значение null

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List references)

Создаёт SignedInfo с указанными методами канонизации и подписи, и списком одной или более ссылок.

Параметры:

cm — метод канонизации

sm — метод подписи

references — список одной или более Referenceов. Список защищён от последующих изменений.

Возвращает:

a SignedInfo

Выбрасывает:

ClassCastException — если какая-либо из ссылок не является Reference типа

IllegalArgumentException — если references пусто

NullPointerException — если какие-либо из параметров имеют null значения

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List references,
                                         String id)

Создаёт SignedInfo с указанными параметрами.

Параметры:

cm — метод канонизации

sm — метод подписи

references — список одной или более Referenceов. Список защищён от последующих изменений.

id — идентификатор (может быть null)

Возвращает:

a SignedInfo

Выбрасывает:

ClassCastException — если какая-либо из ссылок не является Reference типа

IllegalArgumentException — если references пусто

NullPointerException — если cm, sm, или references имеют null значения

newXMLObject

public abstract XMLObject newXMLObject(List content,
                                       String id,
                                       String mimeType,
                                       String encoding)

Создаёт XMLObject из указанных параметров.

Параметры:

content — список XMLStructureов. Список защищён от последующих изменений. Может быть null или пустым.

id — Id (может быть null)

mimeType — тип MIME (может быть null)

encoding — кодировка (может быть null)

Возвращает:

an XMLObject

Выбрасывает:

ClassCastException — если content содержит записи, которые не являются XMLStructure типа

newManifest

public abstract Manifest newManifest(List references)

Создаёт Manifest содержащий указанный список Referenceов.

Параметры:

references — список одной или более Reference. Список защищён от последующих изменений.

Возвращает:

a Manifest

Выбрасывает:

NullPointerException — если references имеет значение null

IllegalArgumentException — если references пусто

ClassCastException — если references содержит записи, которые не являются Reference типа

newManifest

public abstract Manifest newManifest(List references,
                                     String id)

Создаёт Manifest содержащий указанный список Referenceов и необязательный идентификатор.

Параметры:

references — список одной или более Reference. Список защищён от последующих изменений.

id — идентификатор (может быть null)

Возвращает:

a Manifest

Выбрасывает:

NullPointerException — если references имеет значение null

IllegalArgumentException — если references пусто

ClassCastException — если references содержит записи, которые не являются Reference типа

newSignatureProperty

public abstract SignatureProperty newSignatureProperty(List content,
                                                       String target,
                                                       String id)

Создаёт SignatureProperty содержащий указанный список XMLStructureов, целевой URI и необязательный идентификатор.

Параметры:

content — список одной или более XMLStructure. Список защищён от последующих изменений.

target — целевой URI подписи, к которой относится данное свойство

id — идентификатор (может быть null)

Возвращает:

a SignatureProperty

Выбрасывает:

NullPointerException — если content или target имеют значение null

IllegalArgumentException — если content пусто

ClassCastException — если content содержит записи, которые не являются XMLStructure типа

newSignatureProperties

public abstract SignatureProperties newSignatureProperties(List properties,
                                                           String id)

Создаёт SignatureProperties содержащий указанный список SignaturePropertyов и необязательный идентификатор.

Параметры:

properties — список одной или более SignatureProperty. Список защищён от последующих изменений.

id — идентификатор (может быть null)

Возвращает:

a SignatureProperties

Выбрасывает:

NullPointerException — если properties имеет значение null

IllegalArgumentException — если properties пусто

ClassCastException — если properties содержит записи, которые не являются SignatureProperty типа

newDigestMethod

public abstract DigestMethod newDigestMethod(String algorithm,
                                             DigestMethodParameterSpec params)
                                      throws NoSuchAlgorithmException,
                                             InvalidAlgorithmParameterException

Создаёт DigestMethod для указанного URI алгоритма и параметров.

Параметры:

algorithm — URI, идентифицирующий алгоритм дайджеста

params — параметры дайджеста, специфичные для алгоритма (могут быть null)

Возвращает:

the DigestMethod

Выбрасывает:

InvalidAlgorithmParameterException — если указанные параметры неподходящие для запрошенного алгоритма

NoSuchAlgorithmException — если реализация указанного алгоритма не найдена

NullPointerException — если algorithm имеет значение null

newSignatureMethod

public abstract SignatureMethod newSignatureMethod(String algorithm,
                                                   SignatureMethodParameterSpec params)
                                            throws NoSuchAlgorithmException,
                                                   InvalidAlgorithmParameterException

Создаёт SignatureMethod для указанного URI алгоритма и параметров.

Параметры:

algorithm — URI, определяющий алгоритм подписи

params — параметры подписи, специфичные для алгоритма (могут быть null)

Возвращает:

SignatureMethod

Исключения:

InvalidAlgorithmParameterException — если указанные параметры неподходящие для запрошенного алгоритма

NoSuchAlgorithmException — если реализация указанного алгоритма не найдена

NullPointerException — если algorithm является null

newTransform

public abstract Transform newTransform(String algorithm,
                                       TransformParameterSpec params)
                                throws NoSuchAlgorithmException,
                                       InvalidAlgorithmParameterException

Создаёт Transform для указанного URI алгоритма и параметров.

Параметры:

algorithm — URI, определяющий алгоритм преобразования

params — параметры преобразования, специфичные для алгоритма (могут быть null)

Возвращает:

Transform

Исключения:

InvalidAlgorithmParameterException — если указанные параметры неподходящие для запрошенного алгоритма

NoSuchAlgorithmException — если реализация указанного алгоритма не найдена

NullPointerException — если algorithm является null

newTransform

public abstract Transform newTransform(String algorithm,
                                       XMLStructure params)
                                throws NoSuchAlgorithmException,
                                       InvalidAlgorithmParameterException

Создаёт Transform для указанного URI алгоритма и параметров. Параметры задаются как механизм-специфическая XMLStructure (например, DOMStructure). Этот метод полезен, когда параметры находятся в формате XML или не существует стандартного класса для их задания.

Параметры:

algorithm — URI, определяющий алгоритм преобразования

params — XML-структура, специфичная для механизма, из которой извлекать параметры (может быть null, если не требуется или необязательно)

Возвращает:

Transform

Исключения:

ClassCastException — если тип params неподходящий для этого XMLSignatureFactory

InvalidAlgorithmParameterException — если указанные параметры неподходящие для запрошенного алгоритма

NoSuchAlgorithmException — если реализация указанного алгоритма не найдена

NullPointerException — если algorithm является null

newCanonicalizationMethod

public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm,
                                                                 C14NMethodParameterSpec params)
                                                          throws NoSuchAlgorithmException,
                                                                 InvalidAlgorithmParameterException

Создаёт CanonicalizationMethod для указанного URI алгоритма и параметров.

Параметры:

algorithm — URI, определяющий алгоритм канонизации

params — параметры канонизации, специфичные для алгоритма (могут быть null)

Возвращает:

CanonicalizationMethod

Исключения:

InvalidAlgorithmParameterException — если указанные параметры неподходящие для запрошенного алгоритма

NoSuchAlgorithmException — если реализация указанного алгоритма не найдена

NullPointerException — если algorithm является null

newCanonicalizationMethod

public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm,
                                                                 XMLStructure params)
                                                          throws NoSuchAlgorithmException,
                                                                 InvalidAlgorithmParameterException

Создаёт CanonicalizationMethod для указанного URI алгоритма и параметров. Параметры задаются как механизм-специфическая XMLStructure (например, DOMStructure). Этот метод полезен, когда параметры находятся в формате XML или не существует стандартного класса для их задания.

Параметры:

algorithm — URI, определяющий алгоритм канонизации

params — XML-структура, специфичная для механизма, из которой извлекать параметры (может быть null если не требуется или необязательно)

Возвращает:

CanonicalizationMethod

Исключения:

ClassCastException — если тип params неподходящий для этого XMLSignatureFactory

InvalidAlgorithmParameterException — если указанные параметры неподходящие для запрошенного алгоритма

NoSuchAlgorithmException — если реализация указанного алгоритма не найдена

NullPointerException — если algorithm является null

getKeyInfoFactory

public final KeyInfoFactory getKeyInfoFactory()

Возвращает KeyInfoFactory, который создаёт объекты KeyInfo. Возвращённый KeyInfoFactory имеет тот же тип механизма и провайдер, что и этот XMLSignatureFactory

Возвращает:

KeyInfoFactory

Исключения:

NoSuchMechanismException — если реализация KeyFactory с тем же типом механизма и провайдером недоступна

unmarshalXMLSignature

public abstract XMLSignature unmarshalXMLSignature(XMLValidateContext context)
                                            throws MarshalException

Распаковывает новый экземпляр XMLSignature из экземпляра XMLValidateContext, специфичного для механизма.

Параметры:

context — контекст, специфичный для механизма, из которого распаковать подпись

Возвращает:

XMLSignature

Исключения:

NullPointerException — если context является null

ClassCastException — если тип context неподходящий для этого фабрики

MarshalException — если возникает непреодолимое исключение во время распаковки

unmarshalXMLSignature

public abstract XMLSignature unmarshalXMLSignature(XMLStructure xmlStructure)
                                            throws MarshalException

Распаковывает новый экземпляр XMLSignature из экземпляра XMLStructure, специфичного для механизма. Этот метод полезен, если вы хотите только распаковать (и не валидировать) XMLSignature

Параметры:

xmlStructure — XML-структура, специфичная для механизма, из которой распаковать подпись

Возвращает:

XMLSignature

Исключения:

NullPointerException — если xmlStructure является null

ClassCastException — если тип xmlStructure неподходящий для этого фабрики

MarshalException — если возникает непреодолимое исключение во время распаковки

isFeatureSupported

public abstract boolean isFeatureSupported(String feature)

Указывает, поддерживается ли указанное свойство.

Параметры:

feature — имя свойства (как абсолютный URI)

Возвращает:

true если указанное свойство поддерживается, false в противном случае

Исключения:

NullPointerException — если feature является null

getURIDereferencer

public abstract URIDereferencer getURIDereferencer()

Возвращает ссылку на URIDereferencer, который используется по умолчанию для разыменования URI в объектах Reference.

Возвращает:

ссылка на URIDereferencer (никогда null)