Leiss 2.0-Lexs-Sr-Ip 1.0

Bureau of Immigration and Customs Enforcement

Department of Homeland SecurityOctober 3, 2008

LEISP Exchange Specifications 3.1LEISS Interop Profile (LEISS-2.0 LEXS-SR-IP 1.0)

LEISS 2.0 Web Service

(Law Enforcement Information Sharing System)

LEISS 2.0 LEXS SR InteroperabilityProfile(Leiss-2.0-LEXS-SR-IP 1.0)

for LEXS-SR 3.1

Revision3

October3, 2008

Change History

Revision / Date / Author / Description of Revision
1 / September 4, 2008 / Robert Leland / Initial Draft
2 / September 11, 2008 / Tim Lemasters / Clarified ORI
2 / October 3, 2008 / Ted Velkoff / Revision after receiving comments from LEXS Inter-operability Working Group

Table of Contents

1.Introduction

2.The “lexs:SRMessageMetadata” Element

2.1 lexs:LEXSVersion

2.2 lexs:MessageOriginMetadata

3.The “lexs:UserAssertion” Element

4.Interacting with LEISS LEXS SR Server

4.1 Scenarios

4.1.1Retrieving data items

4.2 Technical Specifications of the LEISS LEXS SR Implementation

4.2.1LEISS Service Data Exception and Error Handling

4.2.2LEISS Service Interoperability Modification

4.2.3LEISS Extensions

5.Working with Attachments

6.Supported Searches

Appendix A: Acronyms and Abbreviations

Appendix B: LEISS Extensions

Appendix C: Examples of Messages with LEISS Extensions

1.Introduction

The LEISS Web Service allows bi-directional sharing of data between regional law enforcement and Immigration and Customs Enforcement (ICE) agents. This will allow ICE case information to be shared with regional law enforcement agencies and allow ICE agents to access regional law enforcement data. Systems used by local law enforcement officials will be modified to query the LEISS web service in order to display ICE case information to end users and the ICEPIC system will be modified to allow ICE agents to query regional law enforcement data. This data exchange between ICEPIC and external agencies has been implemented with the Global Justice XML Data Model (GJXDM) and National Information Exchange Model (NIEM) compliant using the LEISP Exchange Specifications (LEXS) 3.1 data exchange interface.

The Logical EntityExchange Specifications (LEXS, pronounced "lex"), arestandards that support LEISP and are intended to address two aspects of information sharing:

define and consistently describe units of information to be shared
define interfaces and protocols to provide (publish) and request (search) such information

The term LEXSSR (Search and Retrieval) applies to the interface between partner systems. This document defines an interoperability profile for LEISS by providing specific values for metadata that must be part of a LEXS-SR 3.1.3 XML instance. For an XML instance that conforms to LEISS-2.0 LEXS-SR-IP 1.0.

Only mandatory elements that are not already identified as mandatory in the LEXS 3.1 User Guide (User Guide) or as required by the LEXS-SR 3.1 Schema (Schema) are listed here if they are required by LEISS business rules. Optional elements or domain attributes are also described in this document. If any specific elements are restricted to specific values due to business rules, these values are also identified in this document.

Security and integrity of data is ensured through a combination of technical and policy controls. The following security-related controls are adopted by LEISS:

Audit—Every LEXS SR request is audited and audit reports are reviewed weekly.
Established Trust Relationships —LEXS SR is predicated on an understanding between systems, users, and data owners. The trust relationships are manifested in agreed-upon and signed Memorandums of Understanding (MOU) between data owners and Interconnection Service Agreements (ISA).
Trust Policy—The LEISS Trust Policy is based on the following provisions:
LEISS will only accept requests from selected sites that are covered by the MOU.
LEISS will accept all user requests from a selected site that is covered by the MOU.
LEISS will not authenticate users but will trust the identity provided by the requesting system in the lexs:UserAssertion..
Technical Security Controls—The technical security controls implemented between LEISS and its partners depends on certificates of trust.

2.The “lexs:SRMessageMetadata” Element

This element applies to the Message that contains it. In addition to the elements required by the Schema and mandated in the User Guide, this element must contain the following sub-elements and/or specific values:

2.1lexs:LEXSVersion

The “lexs:LEXSVersion” element announces the major, minor and patch version of LEXS that the message conforms to. In order to comply with LEISS-2.0 LEXS-SR-IP 1.0,the submission must conform to LEXS-SR 3.1.3

All messages originated by LEISS specify 3.1.3 for the LEXSVersion element.However, LEISS does not use the value of the LEXSversion in messages sent to it and attempts to honor all request for information as long as other elements specified in this IP are satisfied..The value for this element is 3.1.3 and an example is shown below:

lexs:LEXSVersion3.1.3</lexs:LEXSVersion

2.2lexs:MessageOriginMetadata

The “lexs:MessageOriginMetadata” describes the origin of the message. LEISS does not require that this field be present.

3.The “lexs:UserAssertion” Element

The lexs:UserAssertion element describes the user on whose behalf the LEXS SR client is sending the message. Note that requests that come from applications, such as get capabilities, and get availability do not include a user assertion. This element is included in:

StructuredSearchRequestMessage (in a doStructuredSearchRequest)
TextSearchRequestMessage (in a doTextSearchRequest)
DataItemRequestMessage (in a getDataItemRequest)

4.Interacting with LEISS LEXS SRServer

4.1Scenarios

This section describes the typical usage for interacting with the LEISS LEXS SR Server.

4.1.1Retrievingdata items

Figure 41illustrates a typical interaction between a user performing a search, receiving a list of results, and selecting individual data items of interest. LEISS 2.0 Release 1.0 will not support attachments such as images and rendering instructions.

Figure 41: Retrieving entire data items

The order of the steps above is as follows:

The LEXS SR Client collects the search terms from the user and assembles an XML document that is passed to either the doTextSearch or doStructuredSearch operation.
The LEXS SR Server fulfills the search request and returns a doSearchResponse message that containssummaries of data items that match the search terms.
The LEXS SR Client presents these search results to the user and allows them to select one or more items to see more detail.
For each item that the user selects, the LEXS SR Client assembles an XML document that is passed to the getDataItem operation.
The LEXS SR Server fulfills the request and returns a getDataItemResponse message with the full details of that data item. For LEISS 2.0 Release 1 the message will not includes AttachmentLink elements.

4.2Technical Specifications of the LEISS LEXS SR Implementation

Input and outputs for all LEISS service methods are based on the LEXS 3.1.x standard. The data elements and types are defined in leissInbound.wsdl and the closure of XML schemas upon which it depends.

When search requests are sent to the EAS system, it sends back a list of possible matching entities based on the supplied search criteria. The ID for each of these entities is ephemeral. That is, after an ingestion is performed that affects that set of data of which the entity is a part, re-indexing is performed, and the entity IDs become invalid. There is no guaranteed time over which an entity ID supplied to clients will be valid. However, in the overwhelming majority of cases, the IDs should still be valid when clients try to use them. Still, a mechanism for detecting and reporting stale IDs had to be developed. This is the algorithm used.

When an entity ID is returned in a search response, the LEISS Web Service will append a timestamp to this ID, which it uses as the data item ID in the LEXS 3.1.x message.
When LEXS 3.1.x clients submit item detail requests, they submit one of the data item IDs they received in a search response. They do not tamper with the ID, so it is still time-stamped.
When transforming a detail request, the LEISS Web Service extracts the timestamp from the data item ID and passes it as a field in the IS_DETAIL message to EAS. (The data item ID, without the timestamp, is passed in a separate field.)
EAS uses the timestamp to determine if the data item ID has been invalidated or recycled, in which case a special response message is output (see section 4.2.1). Otherwise, normal IS_DETAIL processing occurs.

If this condition is encountered, the user should resubmit the original search request to obtain a fresh data item ID.

4.2.1LEISS Service Data Exception and Error Handling

Errors are reported by the LEISS service in the lexs:ResponseMetadata element. The lexs:ResultCode contains an enumeration indicating a problem (e.g. “Error”), and the lexs:Advisory provides additional detail. The lexs:AdvisoryCategory refines the classification of the error, and the lexs:AdvisoryText includes a human-readable message that describes the problem.

All errors are logged and all client requests to the service are audited. LEISS service query methods are non-transactional and therefore not subject to commit or rollback behavior in the case of errors. Delivery is via synchronous non-reliable messaging, so client systems are responsible for any guaranteed search delivery handling that may be required.

4.2.2LEISS Service Interoperability Modification

The LEISS service accepts address search requests with the street address specified in either of two ways:

The street address is supplied in the nc:StreetFullText element. For example:

<nc: StreetFullText123 W. MAIN ST. N.E.</nc:StreetFullText>

The street address is supplied as components of the nc:LocationStreet. For example:

<nc:LocationStreet>

<nc:StreetNumberText>123</nc:StreetNumberText>

<nc:StreetPredirectionalText>W.</nc:StreetPredirectionalText>

<nc:StreetName>MAIN</nc:StreetName>

<nc:StreetCategoryText>ST.</nc:StreetCategoryText>

<nc:StreetPostdirectionalText>N.E.</nc:StreetPostdirectionalText>

</nc:LocationStreet>

Responses from the LEISS service provide the street asnc:StreetFullText.

LEISS treats the entity ID as a unique id only within the XML message. For example:

lexsdigest:Person s:id=”P-2” ... </lexsdigest:Person>

Responses from the LEISS service include alexs:MessageSequenceNumberthat is unique to the responding server, but is not guaranteed to be unique across all servers. For example:

lexs:MessageSequenceNumber20080803134736</lexs:MessageSequenceNumber>

The lexs:DataItemDate contains the date on which the data item was created in the source system. Note that this date is not the same as the timestamp appended to the identifier in the lexs:DataItemID, which is the last time the entity was known to be valid. For example:

lexs:DataItemDate>2007-06-08</lexs:DataItemDate>

lexs:DataItemID12345;2007-11-15 16:30:20</lexs:DataItemID>

4.2.3LEISS Extensions

LEISS extends the NIEM data model with data types that are unique to ICE. These elements may be included in a lexs:StructuredQuery and may be returned within a lexs:StructuredPayload. The schema (leiss.xsd) is included <here> and example XML fragments are shown <there>.

5.Working with Attachments

This section is a placeholder. Later releases of LEISS will support attachments and this section will contain technical information on retrieving and rendering attachments.

6.Supported Searches

Not all valid LEXS queries are supported by LEISS. LEISS imposes restrictions on query parameters in order to match the ICEPIC data model and enable efficient searching. The rules that specify valid LEISS queries are as follows:

Every clause of the query (//lexs:StructuredQuery/lexs:DigestQueryStatement) must be valid.
Each clause of the query must be a valid person (lexs:DigestQueryField/lexsdigest:EntityPerson), location (lexs:DigestQueryField/lexsdigest:EntityLocation) or telephone number (lexs:DigestQueryField/lexsdigest:EntityTelephoneNumber).
A person clause is valid if it contains one valid name (lexsdigest:Person/nc:PersonName), or one or more valid aliases (lexsdigest:Person/nc:PersonAlternateName) or one or more valid person identifiers and no invalid names or identifiers.
A location clause is valid if it contains a valid address (nc:Location/nc:LocationAddress).
A telephone number clause is valid if it contains a full telephone number (lexsdigest:TelephoneNumber/nc:FullTelephoneNumber), or a NANP telephone number (lexsdigest:TelephoneNumber/nc:NANPTelephoneNumber), or an international telephone number (lexsdigest:TelephoneNumber/nc:InternationalTelephoneNumber).
A person name or alias is valid if it contains a full name (nc:PersonFullName) or a first and last name (nc:PersonSurName and nc:PersonGivenName), or a middle and last name (nc:PersonSurName and nc:PersonMiddleName).
A person identifier is valid if it is

A valid passport (lexsdigest:Person/nc:PersonPassportIdentification[1]), or
A valid driver’s license (lexsdigest:Person/j:PersonAugmentation/nc:DriverLicense[1]/ nc:DriverLicenseIdentification[1]), or
A valid state fingerprint (lexsdigest:Person/j:PersonAugmentation/ j:PersonStateFingerprintIdentification[1]), or
A valid FBI number (lexsdigest:Person/j:PersonAugmentation/j:PersonFBIIdentification[1]), or
A valid alien number (lexsdigest:Person/lexsdigest:PersonAugmentation/im:AlienNumber[1]), or
A valid social security number (lexsdigest:Person/nc:PersonSSNIdentification[1])

Driver’s licenses and state fingerprints are valid only if they also include a jurisdiction (nc:IdentificationJurisdictionFIPS10-4Code[1] or nc:IdentificationJurisdictionText[1]).
An address is valid if

It is a full street text (nc:LocationStreet/nc:StreetFullText) with city (nc:LocationCityName) and state (nc:LocationStateName), or
It is a full street text (nc:LocationStreet/nc:StreetFullText) with postal code (nc:LocationPostalCode), or
It is a street name (nc:LocationStreet/nc:StreetName) with city (nc:LocationCityName) and state (nc:LocationStateName), or
It is a street name (nc:LocationStreet/nc:StreetName) with postal code (nc:LocationPostalCode)

Structured queries on identifiers contained within LEISS-specific person information (lexs:StructuredPayloadQueryField/leissPerson/ leiss:personAugmentation) are always valid.

Appendix A:
Acronyms and Abbreviations

Exhibit 1: Abbreviations and Acronyms

Abbreviation / Acronym / Explanation
AES / Advanced Encryption Standard
CA / Certificate Authority
DES / Data Encryption Standard
DOM / Document Object Model
DSA / Digital Signature Algorithm
DTD / Document Type Definition
HTTP/S / Hypertext Transfer Protocol / Secure
ICEPIC / Immigration and Customs Enforcement Pattern Information Collection system
LEISS / Law Enforcement Information Sharing System
LEISP / Law Enforcement Information Sharing Program
LEXS / LEISP Exchange Specifications
MD5 / Message Digest 5
NIEM / National Information Exchange Model
PKCS / Public Key Cryptography Standards
PKI / Public Key Infrastructure
SAML / Security Assertion Markup Language
SHA1 / Secure Hash Algorithm 1
SOA / Service-oriented architecture
SOAP / Simple Object Access Protocol
SSL / Secure Socket Layer
TCP/IP / Transmission Control Protocol/Internet Protocol
URI / Uniform resource identifier
URL / Uniform resource locator
URN / Uniform resource name
W3C / World Wide Web Consortium
WSDL / Web Services Description Language
WSS / Web Service Security
WSS4J / Web Service Security For Java
XML / eXtensible Markup Language
XPATH / XML Path Language
Xslt / eXtensible Stylesheet Language Transformations

Appendix B:
LEISS Extensions

?xml version="1.0" encoding="UTF-8"?
xsd:schema targetNamespace="
xmlns:leiss="
xmlns:lexslib="
xmlns:s="
xmlns:niem-xsd="
xmlns:xsd="
xmlns:nc="
xmlns:i="
xsd:annotation
xsd:appinfo
i:ConformantIndicatortrue/i:ConformantIndicator
/xsd:appinfo
/xsd:annotation
xsd:import schemaLocation="../../library/3.1/library.xsd"
namespace="
xsd:import schemaLocation="../../niem-constrained/niem-core/2.0/niem-core.xsd"
namespace="
xsd:import schemaLocation="../../niem-constrained/structures/2.0/structures.xsd"
namespace="
xsd:import schemaLocation="../../niem-constrained/proxy/xsd/2.0/xsd.xsd"
namespace="
xsd:complexType name="AugmentationType"
xsd:annotation
xsd:documentationA data type for augmentation of top level LEISS Entity elements.

Type includes LEXS SameAsDigestReference so that each new augmentation type doesn't

have to include it./xsd:documentation
xsd:appinfo
i:Base i:namespace=

i:name="AugmentationType"/
/xsd:appinfo
/xsd:annotation
xsd:complexContent
xsd:extension base="s:AugmentationType"
xsd:sequence
xsd:element ref="lexslib:SameAsDigestReference"/
/xsd:sequence
/xsd:extension
/xsd:complexContent
/xsd:complexType
xsd:complexType name="EntitiesType"
xsd:annotation
xsd:documentationContainer of LEISS Entity elements./xsd:documentation
/xsd:annotation
xsd:complexContent
xsd:extension base="s:ComplexObjectType"
xsd:sequence
xsd:element ref="leiss:Entity" minOccurs="0" maxOccurs="unbounded"/
/xsd:sequence
/xsd:extension
/xsd:complexContent
/xsd:complexType
xsd:complexType name="PersonAugmentationType"
xsd:annotation
xsd:documentationA data type that supplements nc:PersonType./xsd:documentation
xsd:appinfo
i:Base i:namespace=

i:name="AugmentationType"/
/xsd:appinfo
/xsd:annotation
xsd:complexContent
xsd:extension base="leiss:AugmentationType"
xsd:sequence
xsd:element ref="leiss:PersonAdmissionIdentification"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonCreditCardIdentification"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonEmployment"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonIDENTIdentification"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonPetitionIdentification"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonPilotIdentification"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonPlaceOfBirth"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonPrisonStatus"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonSEVISIdentification"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonSpecialInstruction"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:PersonTECSCaseIdentification"

minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:LeissTECSSubject"

minOccurs="0" maxOccurs="unbounded"/
/xsd:sequence
/xsd:extension
/xsd:complexContent
/xsd:complexType
xsd:complexType name="PersonEmploymentType"
xsd:annotation
xsd:documentationEmployment information about a person./xsd:documentation
/xsd:annotation
xsd:complexContent
xsd:extension base="s:ComplexObjectType"
xsd:sequence
xsd:element ref="leiss:EmploymentOccupation" minOccurs="0"/
xsd:element ref="leiss:EmploymentJobTitle" minOccurs="0"/
xsd:element ref="leiss:EmploymentDate" minOccurs="0"/
/xsd:sequence
/xsd:extension
/xsd:complexContent
/xsd:complexType
xsd:complexType name="PersonType"
xsd:annotation
xsd:documentationA data type for a human being.

Builds upon a LEXS Digest Person./xsd:documentation
xsd:appinfo
i:Base i:namespace=" i:name="PersonType"/
/xsd:appinfo
/xsd:annotation
xsd:complexContent
xsd:extension base="nc:PersonType"
xsd:sequence
xsd:element ref="leiss:PersonAugmentation" minOccurs="0"/
/xsd:sequence
/xsd:extension
/xsd:complexContent
/xsd:complexType
xsd:complexType name="TECSCaseInformationType"
xsd:annotation
xsd:documentationInformation from a TECS case./xsd:documentation
/xsd:annotation
xsd:complexContent
xsd:extension base="s:ComplexObjectType"
xsd:sequence
xsd:element ref="leiss:PersonTECSCaseIdentification" minOccurs="0"/
xsd:element ref="leiss:CaseStatus" minOccurs="0" maxOccurs="unbounded"/
xsd:element ref="leiss:JTTFCase" minOccurs="0"/
xsd:element ref="leiss:CaseShortDescription" minOccurs="0"/
/xsd:sequence
/xsd:extension
/xsd:complexContent
/xsd:complexType
xsd:complexType name="TECSSubjectInformationType"
xsd:annotation
xsd:documentationInformation about a TECS subject./xsd:documentation
/xsd:annotation
xsd:complexContent
xsd:extension base="s:ComplexObjectType"
xsd:sequence
xsd:element ref="leiss:PersonTECSSubjectIdentification" minOccurs="0"/
xsd:element ref="leiss:TECSSubjectCreationDate" minOccurs="0"/
/xsd:sequence
/xsd:extension
/xsd:complexContent
/xsd:complexType
xsd:element name="CaseShortDescription" type="niem-xsd:string" nillable="true"
xsd:annotation
xsd:documentationExtract from a TECS case./xsd:documentation
/xsd:annotation
/xsd:element
xsd:element name="CaseStatus" type="niem-xsd:string" nillable="true"
xsd:annotation
xsd:documentationStatus of a TECS case./xsd:documentation
/xsd:annotation
/xsd:element
xsd:element name="EmploymentDate" type="niem-xsd:date" nillable="true"
xsd:annotation
xsd:documentationDate of employment./xsd:documentation
/xsd:annotation
/xsd:element
xsd:element name="EmploymentJobTitle" type="niem-xsd:string" nillable="true"
xsd:annotation
xsd:documentationName of job title./xsd:documentation
/xsd:annotation
/xsd:element
xsd:element name="EmploymentOccupation" type="niem-xsd:string" nillable="true"
xsd:annotation
xsd:documentationName of occupation./xsd:documentation
/xsd:annotation
/xsd:element
xsd:element name="Entities" type="leiss:EntitiesType" nillable="true"
xsd:annotation
xsd:documentationCollection of entities.