diff --git a/files/Atna.md b/files/Atna.md new file mode 100644 index 0000000..324b1fb --- /dev/null +++ b/files/Atna.md @@ -0,0 +1,256 @@ +# Audit logs + +When executing most of the transactions with the EPR, there is a requirement to send an audit log to the community +describing who did what and when, on the client's side. +The community also creates such an audit log, and both can be compared if the need arises. + +Since the audit logs may contain information about the transaction outcome, you have to wait for the community +response before creating the audit log. + +!!! warning + You have to do your best efforts to send the audit logs, even if the transaction has failed (network issue or + error 500 for example). + +## Specifications + +The base specification of the `#!xml ` format is given in [DICOM PS3.15](https://dicom.nema.org/medical/dicom/current/output/html/part15.html). +Additional requirements are described in: + +- For each transaction, in the 'Security Considerations' section of each transaction profile; +- In the [IHE Audit Trail and Node Authentication (ATNA) Profile](https://profiles.ihe.net/ITI/TF/Volume1/ch-9.html); +- In [IHE ITI-20](https://profiles.ihe.net/ITI/TF/Volume2/ITI-20.html); +- In [IHE ITI-40](https://profiles.ihe.net/ITI/TF/Volume2/ITI-40.html#3.40.4.2) §3.40.4.2; +- In the [Amendment 1 to Annex 5][annexes], §1.5 and §1.6.4.3.5.1; + +## Basic structure + +An audit log is simply wrapped in a `#!xml ` element. +No namespace is needed. + +The first child is a _EventIdentification_ element that describes the transaction: +```xml + + + + +``` +where: + +- `action_code`, `transaction_code`, `transaction_display`,`type_code` and `type_display` depend on the + transaction type and are defined in the IHE transaction profile, in the 'Security Considerations' section; +- `date_time` is the date and time at which the transaction was made. It shall be given in UTC, and shall follow the + xsd:dateTime format; +- `outcome` describes whether the transaction was successful or not: `0` is a success, `4` is a minor + failure, `8` is a serious failure and `12` is a major failure. The choice of the failure type is left to the + implementers. + +Then two _ActiveParticipants_ describe the source and destination participants. + +=== "First _ActiveParticipant_" + + The first _ActiveParticipant_ describes the source participant, which is the one that has sent the transaction. + It has the following content: + ```xml + + + + ``` + where: + + - `user_id` is required and can be filled as you want. It can be a process ID, a login name, or other identifiers; + - `alt_user_id` is the process ID as used within the local operating system in the local system logs; + - `nap_id` is the DNS name or IP address of the source; + - `nap_type` is `1` for machine (DNS) name, `2` for IP address. + + Other attributes are optional. + +=== "Second _ActiveParticipant_" + + The second _ActiveParticipant_ describes the destination participant, which is the one that has received the + transaction. + It has the following content: + ```xml + + + + ``` + where: + + - `user_id` is the SOAP endpoint URI; + - `nap_id` is the DNS name or IP address of the destination; + - `nap_type` is `1` for machine (DNS) name, `2` for IP address. + + Other attributes are optional. + +Following that is the `#!xml ` element. +It contains the following: +```xml + +``` +where `oid` is required and must be an OID of your OID hierarchy. +Please ask your community if it has requirements about the use of this OID. +Other attributes are optional. + +## Requirements for transactions secured by XUA + +If the transaction is secured by XUA (like ITI-18, ITI-41, ITI-43), then additional _ActiveParticipants_ shall be +specified. + +=== "First _ActiveParticipant_" + + The **first additional _ActiveParticipant_** is described in [IHE ITI-40](https://profiles.ihe.net/ITI/TF/Volume2/ITI-40.html#3.40.4.2), + §3.40.4.2. + It is required for all roles. + It shall contain: + ```xml + + ``` + where: + + - `user_id` is required and can be filled as you want. It can be a process ID, a login name, or other identifiers; + - `alias` (optional) is the SAML Assertion's `#!abnf Subject/NameID/@SPProvidedID` attribute; + - `user` (required) is the SAML Assertion's `#!abnf Subject/NameID` content; + - `issuer` (required) is the SAML Assertion's `#!abnf Issuer` content. + + The other attributes and subject role specification are optional. + +=== "Second _ActiveParticipant_" + + The **second additional _ActiveParticipant_** is described in the [Amendment 1 to Annex 5][annexes], §1.6.4.3.5.1. + It is required for all roles. + It shall contain: + ```xml + + + + ``` + where: + + - `user_id` (required) is the SAML Assertion's `#!abnf Subject/NameID` content; + - `user_name` (required) is the SAML Assertion's `#!abnf AttributeStatement/Attribute[@Name="urn:oasis:names:tc:xspa:1.0:subject:subject-id"]/AttributeValue` content; + - `code` (required) is the SAML Assertion's `#!abnf AttributeStatement/Attribute[@Name="urn:oasis:names:tc:xacml:2.0:subject:role"]/AttributeValue/Role/@code` attribute. + + Other attributes are optional. + +=== "Third _ActiveParticipant_" + + The **third additional _ActiveParticipant_** is described in the [Amendment 1 to Annex 5][annexes], §1.6.4.3.5.1. + It is only required for assistants and technical users. + It shall contain: + ```xml + + + + ``` + where: + + - `user_id` (required) is the SAML Assertion's `#!abnf Subject/SubjectConfirmation/NameID` content; + - `user_name` (required) is the SAML Assertion's `#!abnf Subject/SubjectConfirmation/SubjectConfirmationData/AttributeStatement/Attribute[@Name="urn:oasis:names:tc:xspa:1.0:subject:subject-id"]/AttributeValue` content; + - `code` (required) is either `TCU` or `ASS`. + +## Special parts + +Some _ParticipantObjectIdentification_ elements may be used to include additional details about the query content. + +### Query + +For ITI-18 transaction, the query content has to be included in the `#!xml ` element: +```xml + + + ★query_b64 + + +``` +where: + +- `participant_object_id` is the Stored Query ID for ITI-18, or optional for ITI-45 and ITI-47; +- `transaction_code` and `transaction_display` are the same as in `#!abnf EventIdentification/EventID`; +- `query_b64` is the XML representation of a part of the query, base64-encoded: + - For ITI-18, the `AdhocQueryRequest`; + - For ITI-45 and ITI-47, the `QueryByParameter` segment of the query; +- `query_encoding_b64` is the query encoding, encoded in base64. Usually `VVRGLTg=` (UTF-8). + +For ITI-18 transactions, an additional `#!xml ` is required inside, if the +homeCommunityID is specified in the query: +```xml + +``` +where `home_community_id_b64` is the value of the homeCommunityId, base64-encoded. + +### Patient + +```xml + + + +``` +where `patient_id` is the patient identifier encoded in HL7 CX format (e.g. `value^^^&1.2.3&aISO`). + +### Submission set + +For ITI-41 requests, a `#!xml ` is required to describe the Submission Set: +```xml + + + +``` +where `submission_set_unique_id` is the URN-encoded Submission Set unique ID. + +### Document + +For ITI-43 transactions, a `#!xml ` is required to describe the document to be +retrieved: +```xml + + + + +``` +where: + +- `document_unique_id` is the document unique ID; +- `repo_unique_id_b64` is the repository unique ID; +- `confidentiality_code` is the document confidentiality code, if known. The format is HL7v2 CE with the code + system OID as the code (e.g.: `1051000195109^normal^2.16.840.1.113883.6.96`). + +If the home community ID is known, another _ParticipantObjectDetail_ is required inside: +`#!xml `. +The value must be base64-encoded. + +## Requirements summary + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActiveParticipantParticipantObjectIdentification
TransactionEventIdentificationSourceDestinationXUAQueryPatientSubmission SetDocument
ITI-18✅✅✅✅✅✅❌❌
ITI-41✅✅✅✅❌✅✅❌
ITI-43✅✅✅✅❌✅❌✅
ITI-44✅✅✅❌❌✅❌❌
ITI-45✅✅✅❌✅✅❌❌
ITI-47✅✅✅❌✅✅❌❌
ITI-57✅✅✅✅❌✅✅❌
+ +## Sending an audit log + +[Amendment 1 to Annex 5][annexes], §1.5.1 diff --git a/files/index.md b/files/index.md index d7ef389..6e552e1 100644 --- a/files/index.md +++ b/files/index.md @@ -44,6 +44,10 @@ Please see section below for details on the available public test systems. [Provide X-User Assertion](ProvideXAssertion.md) - Use SAML 2.0 Assertion in transactions to authorize access +### Audit + +[Record Audit Event](Atna.md) - Send audit events to the EPR + ### Public Test Systems [EPR Playground](playground.md) - Public available test system to test transaction messages and complex use cases. diff --git a/files/media/ehealthsuisse.css b/files/media/ehealthsuisse.css index 96ac711..b21a934 100644 --- a/files/media/ehealthsuisse.css +++ b/files/media/ehealthsuisse.css @@ -75,7 +75,13 @@ .tabbed-content { padding: 0 1em; background: #f5f5f5; + border-left: 2px solid #1179bf; } .tabbed-content code { background: #e9e9e9; } +.md-typeset .tabbed-labels>label { + margin-right: 1rem; + border-bottom: 0.1rem solid #dcdcdc; + padding: .78125em .75em .625em; +} diff --git a/mkdocs.yml b/mkdocs.yml index 4abeaa3..d30ccdc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,8 @@ nav: - Authorization: - GetXAssertion.md - ProvideXAssertion.md + - Audit: + - Atna.md - "Public Test Systems": - playground.md - gazelle.md