Package org.certificateservices.messages.csmessages

Interface CSMessageParser

All Known Implementing Classes:

DefaultCSMessageParser, TestCSMessageParser

public interface CSMessageParser

Method Summary

Modifier and Type	Method	Description
CSMessageResponseData	genCSFailureResponse(java.lang.String relatedEndEntity, byte[] request, RequestStatus status, java.lang.String failureMessage, java.lang.String destinationID, Credential originator)	Method to generate a failure message response to a given request.
CSMessage	genCSMessage(java.lang.String version, java.lang.String payLoadVersion, java.lang.String requestName, java.lang.String messageId, java.lang.String destinationID, java.lang.String organisation, Credential originator, java.lang.Object payload, java.util.List<java.lang.Object> assertions)	Method that populates all fields except the signature of a CS message.
byte[]	generateCSRequestMessage(java.lang.String requestId, java.lang.String destinationId, java.lang.String organisation, java.lang.String payLoadVersion, java.lang.Object payload, java.util.List<java.lang.Object> assertions)	Method used to generate a CS Request message without any originator, i.e the signer of this message is the originator.
byte[]	generateCSRequestMessage(java.lang.String requestId, java.lang.String destinationId, java.lang.String organisation, java.lang.String payLoadVersion, java.lang.Object payload, Credential originator, java.util.List<java.lang.Object> assertions)	Method used to generate a CS Request message with any originator, used with relying a request message from another system.
CSMessageResponseData	generateCSResponseMessage(java.lang.String relatedEndEntity, CSMessage request, java.lang.String payLoadVersion, java.lang.Object payload)	Method to generate a CS Respone message from a request.
CSMessageResponseData	generateCSResponseMessage(java.lang.String relatedEndEntity, CSMessage request, java.lang.String payLoadVersion, java.lang.Object payload, boolean isForwarable)	Method to generate a CS Respone message from a request.
byte[]	generateGetApprovalRequest(java.lang.String requestId, java.lang.String destinationId, java.lang.String organisation, byte[] requestMessage, Credential originator, java.util.List<java.lang.Object> assertions)	Method generate a Get Approval Request,
CSMessageResponseData	generateGetApprovalResponse(java.lang.String relatedEndEntity, CSMessage request, java.lang.String approvalId, ApprovalStatus approvalStatus, java.util.List<java.lang.Object> assertions)	Method generate a Get Approved Response,
byte[]	generateIsApprovedRequest(java.lang.String requestId, java.lang.String destinationId, java.lang.String organisation, java.lang.String approvalId, Credential originator, java.util.List<java.lang.Object> assertions)	Method generate a Is Approved Request,
CSMessageResponseData	generateIsApprovedResponse(java.lang.String relatedEndEntity, CSMessage request, ApprovalStatus approvalStatus, java.util.List<java.lang.Object> assertions)	Method generate a Is Approved Response,
javax.xml.bind.Marshaller	getMarshaller(CSMessage message)	Method that fetches the related marshaller for a given message.
MessageSecurityProvider	getMessageSecurityProvider()	Help method to return the related message security provider.
Credential	getOriginatorFromRequest(CSMessage request)	Method to extract the originator credential from a message.
java.security.cert.X509Certificate	getSigningCertificate(byte[] request)	Fetches the signing certificate from the request.
CSMessageVersion	getVersionFromMessage(byte[] messageData)	Method that tries to parse the xml version from a message
void	init(MessageSecurityProvider securityProvider, java.util.Properties config)	Method that initializes the CSMessage parser with a security provider and properties.
byte[]	marshallAndSignCSMessage(CSMessage csMessage)	Method that generates the signature and marshalls the message to byte array in UTF-8 format.
byte[]	marshallCSMessage(CSMessage csMessage)	Method that marshalls the message to byte array in UTF-8 format without adding any signature.
CSMessage	parseMessage(byte[] messageData)	Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.
CSMessage	parseMessage(byte[] messageData, boolean performValidation)	Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.
CSMessage	parseMessage(byte[] messageData, boolean performValidation, boolean requireSignature)	Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.
CSMessage	parseMessage(org.w3c.dom.Document doc)	Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.
CSMessage	parseMessage(org.w3c.dom.Document doc, boolean performValidation)	Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.
CSMessage	parseMessage(org.w3c.dom.Document doc, boolean performValidation, boolean requireSignature)	Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.
byte[]	populateOriginatorAssertionsAndSignCSMessage(CSMessage message, java.lang.String destinationId, Credential originator, java.util.List<java.lang.Object> assertions)	Method to add an originator and assertions to a CSMessage and add a signature.
void	validatePayloadObject(CSMessageVersion version, java.lang.Object payLoadObject)	Method to validate a payload object separately, used for special cases such when validating GetApprovalRequest requestData etc.

Method Detail

init

void init(MessageSecurityProvider securityProvider,
          java.util.Properties config)
   throws MessageProcessingException

Method that initializes the CSMessage parser with a security provider and properties.

Parameters:

securityProvider - the CSMessage security provider to use.

config - the configuration of the parser.

Throws:

MessageProcessingException - if configuration contained bad configuration of security provider.

parseMessage

CSMessage parseMessage(byte[] messageData)
                throws MessageContentException,
                       MessageProcessingException

Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.

This method always validates and authorizes the signing certificate.

Parameters:

messageData - the data to parse into a CSMessage

Returns:

a parsed CS Message object.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

parseMessage

CSMessage parseMessage(byte[] messageData,
                       boolean performValidation)
                throws MessageContentException,
                       MessageProcessingException

Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.

Signatures are required.

Parameters:

messageData - the data to parse into a CSMessage

performValidation - true if the message security provider should perform validate that the signing certificate is valid and authorized for related organisation. Otherwise must validation be performed manually after the message is parsed.

Returns:

a parsed CS Message object.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

parseMessage

CSMessage parseMessage(byte[] messageData,
                       boolean performValidation,
                       boolean requireSignature)
                throws MessageContentException,
                       MessageProcessingException

Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.

Parameters:

messageData - the data to parse into a CSMessage

performValidation - true if the message security provider should perform validate that the signing certificate is valid and authorized for related organisation. Otherwise must validation be performed manually after the message is parsed.

requireSignature - if signature should be required.

Returns:

a parsed CS Message object.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

parseMessage

CSMessage parseMessage(org.w3c.dom.Document doc)
                throws MessageContentException,
                       MessageProcessingException

Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.

This method always validates and authorizes the signing certificate.

Parameters:

doc - The Document data to parse into a CSMessage

Returns:

a parsed CS Message object.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

parseMessage

CSMessage parseMessage(org.w3c.dom.Document doc,
                       boolean performValidation)
                throws MessageContentException,
                       MessageProcessingException

Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.

Signatures are required.

Parameters:

doc - The Document data to parse into a CSMessage

performValidation - true if the message security provider should perform validate that the signing certificate is valid and authorized for related organisation. Otherwise must validation be performed manually after the message is parsed.

Returns:

a parsed CS Message object.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

parseMessage

CSMessage parseMessage(org.w3c.dom.Document doc,
                       boolean performValidation,
                       boolean requireSignature)
                throws MessageContentException,
                       MessageProcessingException

Method to parse a message into a CSMessage and verify that it fulfills the registred schemas.

Signatures are required.

Parameters:

doc - The Document data to parse into a CSMessage

performValidation - true if the message security provider should perform validate that the signing certificate is valid and authorized for related organisation. Otherwise must validation be performed manually after the message is parsed.

requireSignature - if signature should be required.

Returns:

a parsed CS Message object.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateCSRequestMessage

byte[] generateCSRequestMessage(java.lang.String requestId,
                                java.lang.String destinationId,
                                java.lang.String organisation,
                                java.lang.String payLoadVersion,
                                java.lang.Object payload,
                                java.util.List<java.lang.Object> assertions)
                         throws MessageContentException,
                                MessageProcessingException

Method used to generate a CS Request message without any originator, i.e the signer of this message is the originator.

Parameters:

requestId - id of request to send.

destinationId - the destination Id to use.

organisation - the related organisation (short name)

payLoadVersion - version of the pay load structure.

payload - the pay load object

assertions - a list of authorization assertions or null if no assertions should be inserted.

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateCSRequestMessage

byte[] generateCSRequestMessage(java.lang.String requestId,
                                java.lang.String destinationId,
                                java.lang.String organisation,
                                java.lang.String payLoadVersion,
                                java.lang.Object payload,
                                Credential originator,
                                java.util.List<java.lang.Object> assertions)
                         throws MessageContentException,
                                MessageProcessingException

Method used to generate a CS Request message with any originator, used with relying a request message from another system.

Parameters:

requestId - id of request to send.

destinationId - the destination Id to use.

organisation - the related organisation (short name)

payLoadVersion - version of the pay load structure.

payload - the payload object

originator - the credential of the original requester.

assertions - a list of authorization assertions or null if no assertions should be inserted.

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

genCSMessage

CSMessage genCSMessage(java.lang.String version,
                       java.lang.String payLoadVersion,
                       java.lang.String requestName,
                       java.lang.String messageId,
                       java.lang.String destinationID,
                       java.lang.String organisation,
                       Credential originator,
                       java.lang.Object payload,
                       java.util.List<java.lang.Object> assertions)
                throws MessageContentException,
                       MessageProcessingException

Method that populates all fields except the signature of a CS message.

Parameters:

version - , version of the CS Message

payLoadVersion - , version of the pay load structure.

requestName - the name in the a related request if this is a response message, or null if no related request exists

messageId - the id of the message, if null is a random id generated.

destinationID - the destination Id to use.

organisation - the related organisation

originator - the originator of the message if applicable.

payload - the payload object to set in the object

assertions - a list of authorization assertions used along with this message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateCSResponseMessage

CSMessageResponseData generateCSResponseMessage(java.lang.String relatedEndEntity,
                                                CSMessage request,
                                                java.lang.String payLoadVersion,
                                                java.lang.Object payload)
                                         throws MessageContentException,
                                                MessageProcessingException

Method to generate a CS Respone message from a request. CS Response message will be marked as non forwardable, which means not for use in data syncronization applications.

Parameters:

relatedEndEntity - the name of the related end entity (such as username of the related user)

request - the related request

payLoadVersion - version of the pay load structure.

payload - the payload object

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateCSResponseMessage

CSMessageResponseData generateCSResponseMessage(java.lang.String relatedEndEntity,
                                                CSMessage request,
                                                java.lang.String payLoadVersion,
                                                java.lang.Object payload,
                                                boolean isForwarable)
                                         throws MessageContentException,
                                                MessageProcessingException

Method to generate a CS Respone message from a request.

Parameters:

relatedEndEntity - the name of the related end entity (such as username of the related user)

request - the related request

payLoadVersion - version of the pay load structure.

payload - the payload object

isForwarable - if message will be marked as non forwardable, i.e. for use in data syncronization applications.

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateGetApprovalRequest

byte[] generateGetApprovalRequest(java.lang.String requestId,
                                  java.lang.String destinationId,
                                  java.lang.String organisation,
                                  byte[] requestMessage,
                                  Credential originator,
                                  java.util.List<java.lang.Object> assertions)
                           throws MessageContentException,
                                  MessageProcessingException

Method generate a Get Approval Request,

Parameters:

requestId - id of request to send.

destinationId - the destination Id to use.

organisation - the related organisation (short name)

requestMessage - the request message to get approval for.

originator - the credential of the original requester, null if this is the origin of the request.

assertions - a list of related authorization assertions, or null if no authorization assertions is available.

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateIsApprovedRequest

byte[] generateIsApprovedRequest(java.lang.String requestId,
                                 java.lang.String destinationId,
                                 java.lang.String organisation,
                                 java.lang.String approvalId,
                                 Credential originator,
                                 java.util.List<java.lang.Object> assertions)
                          throws MessageContentException,
                                 MessageProcessingException

Method generate a Is Approved Request,

Parameters:

requestId - id of request to send.

destinationId - the destination Id to use.

organisation - the related organisation (short name)

approvalId - the approval id to check.

originator - the credential of the original requester, null if this is the origin of the request.

assertions - a list of related authorization assertions, or null if no authorization assertions is available.

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateIsApprovedResponse

CSMessageResponseData generateIsApprovedResponse(java.lang.String relatedEndEntity,
                                                 CSMessage request,
                                                 ApprovalStatus approvalStatus,
                                                 java.util.List<java.lang.Object> assertions)
                                          throws MessageContentException,
                                                 MessageProcessingException

Method generate a Is Approved Response,

Parameters:

relatedEndEntity - the user name of related user in system.

request - the request data.

approvalStatus - the status of the related approval Id.

assertions - a list of related authorization assertions, or null if no authorization assertions is available.

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

generateGetApprovalResponse

CSMessageResponseData generateGetApprovalResponse(java.lang.String relatedEndEntity,
                                                  CSMessage request,
                                                  java.lang.String approvalId,
                                                  ApprovalStatus approvalStatus,
                                                  java.util.List<java.lang.Object> assertions)
                                           throws MessageContentException,
                                                  MessageProcessingException

Method generate a Get Approved Response,

Parameters:

relatedEndEntity - the user name of related user in system.

request - the request data.

approvalId - the approval id that was generated for the request

approvalStatus - the approval status

assertions - a list of related authorization assertions, or null if no authorization assertions is available.

Returns:

a generated and signed (if configured) message.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

populateOriginatorAssertionsAndSignCSMessage

byte[] populateOriginatorAssertionsAndSignCSMessage(CSMessage message,
                                                    java.lang.String destinationId,
                                                    Credential originator,
                                                    java.util.List<java.lang.Object> assertions)
                                             throws MessageContentException,
                                                    MessageProcessingException

Method to add an originator and assertions to a CSMessage and add a signature. If signature exists it is removed.

Parameters:

message - the message to populate.

destinationId - the updated destination, null for unchanged.

originator - the originator to add, null for no originator

assertions - the assertions to add, null for no assertions.

Returns:

a populated and signed CSMessage.

Throws:

MessageContentException - if input data contained invalid format.

MessageProcessingException - if internal problems occurred processing the cs message.

genCSFailureResponse

CSMessageResponseData genCSFailureResponse(java.lang.String relatedEndEntity,
                                           byte[] request,
                                           RequestStatus status,
                                           java.lang.String failureMessage,
                                           java.lang.String destinationID,
                                           Credential originator)
                                    throws MessageContentException,
                                           MessageProcessingException

Method to generate a failure message response to a given request.

Parameters:

relatedEndEntity - the user name of related user in system.

request - the request data.

status - the request status of the response

failureMessage - a readable failure message.

destinationID - the destination id of the message. If null will destination id be extracted from request data.

originator - originator of the request, null if no originator could be found.

Returns:

Throws:

MessageProcessingException - if internal error occurred parsing the certificate.

MessageContentException

getSigningCertificate

java.security.cert.X509Certificate getSigningCertificate(byte[] request)
                                                  throws MessageContentException,
                                                         MessageProcessingException

Fetches the signing certificate from the request.

Parameters:

request - the request to parse the certificate from.

Returns:

the signer certificate of null if no certificate is required by the parser.

Throws:

MessageProcessingException - if internal error occurred parsing the certificate.

MessageContentException

marshallAndSignCSMessage

byte[] marshallAndSignCSMessage(CSMessage csMessage)
                         throws MessageProcessingException,
                                MessageContentException

Method that generates the signature and marshalls the message to byte array in UTF-8 format.

Parameters:

csMessage - the CSMessage to sign and marshall, never null.

Returns:

a marshalled and signed message.

Throws:

MessageProcessingException - if problems occurred when processing the message.

MessageContentException

marshallCSMessage

byte[] marshallCSMessage(CSMessage csMessage)
                  throws MessageProcessingException,
                         MessageContentException

Method that marshalls the message to byte array in UTF-8 format without adding any signature.

Parameters:

csMessage - the CSMessage to marshall, never null.

Returns:

a marshalled message.

Throws:

MessageProcessingException - if problems occurred when processing the message.

MessageContentException

validatePayloadObject

void validatePayloadObject(CSMessageVersion version,
                           java.lang.Object payLoadObject)
                    throws MessageContentException

Method to validate a payload object separately, used for special cases such when validating GetApprovalRequest requestData etc.

Parameters:

version - the versions of a CS message.

payLoadObject - the pay load object to validate schema for.

Throws:

MessageProcessingException

MessageContentException - if the message contained invalid XML.

getVersionFromMessage

CSMessageVersion getVersionFromMessage(byte[] messageData)
                                throws MessageContentException,
                                       MessageProcessingException

Method that tries to parse the xml version from a message

Parameters:

messageData - the messageData to extract version from.

Returns:

the version in the version and payLoadVersion attributes of the message.

Throws:

MessageContentException - didn't contains a valid version attribute.

MessageProcessingException - if internal problems occurred.

getOriginatorFromRequest

Credential getOriginatorFromRequest(CSMessage request)

Method to extract the originator credential from a message.

Parameters:

request - the request message to extract the originator from.

Returns:

the originator credential from the message or null if no originator was found.

getMessageSecurityProvider

MessageSecurityProvider getMessageSecurityProvider()

Help method to return the related message security provider.

Returns:

the related message security provider, never null.

getMarshaller

javax.xml.bind.Marshaller getMarshaller(CSMessage message)
                                 throws MessageContentException,
                                        MessageProcessingException

Method that fetches the related marshaller for a given message.

Parameters:

message - the message to fetch related marshaller for.

Returns:

the marshaller

Throws:

MessageContentException - if message content was faulty or no related marshaller could be found.

MessageProcessingException - if internal error occurred processing the message.