How to use the AIB Hub.
The AIB Hub does five things:
The AIB Hub web site.
Test process and file specifications.
For accessing the hub web site you will need to download the aib certificate authority root certificate.
Client registries need to exchange messages to support the export of certificates. The exporting registry sends certificate details to the importing registry, and the importing registry acknowledges the file. The Hub sits in the middle of this process. The exporting registry actually sends a signed and encrypted message to the Hub, the Hub identifies the recipient, and the Hub forwards the message, unchanged and newly signed and encrypted. Similarly, the acknowledgment from the recipient is sent to the Hub and forwarded in its turn.
The Hub provides the following functions:
The Hub provides a set of screens where you, a client registry user, may:
The test environment is a cut-down registry with its own URI. Messages are forwarded through the Hub in the normal way.
The test process:
The test has two phases:
Test client registry understanding of file formats
The test facility sends a set of files to the client registry. Some files contain deliberate errors, and others do not. The client registry returns acknowledgment files and the test facility records whether the acknowledgments match the expected response.
Test client registry file generation
The client registry sends a set of files to the test facility. The test facility responds with acknowledgments as appropriate. The expected result is that all files will be error free.
As an additional test of client response to NAK responses, the test facility selects a random response file and returns NAK instead of ACK. The user for the client registry must be able to correctly identify the message ID associated with the NAK.
Tests are divided into classes to address different formats of XML file (different schemas). These classes generally correspond to different chapters of the AIB Principles and Rules of Operation.
Test process and file specifications are described in more detail here.
Tests are initiated by you as a user for your client registry. Only one set of tests is active at any one time, so you must either complete a set of tests or abandon them.
You can enter the message number of the randomly selected message that received a NAK under the second phase of the tests.
The PKI facility allows you to generate your own public/private key pairs for us in transferring files to and from the Hub. The system is a Certificate Authority for the AIB and provides keys based on a self-generated root key held within the system. You install the public root key in your own environments so that the security process can recognise the encryption key used by the Hub.
You are also able to download the Hub's own public key.
You are responsible for keeping your certificate up to date and you may request a new certificate at any time. The name information on the certificate is taken from the details of your registry. You must give a start date for the validity of the certificate, and a password to be used on the private key.
The resulting certificate pair is emailed to you at the registry's notification address.
The certificates generated are not used immediately. You must install the certificate explicitly for it to be used. This allows you to create a certificate valid in a few days time that can then be installed at a suitable changeover point.
The schema repository is provided as publicly accessible files through an HTTP interface.
In order to use the AIB Hub you must have a registry that conforms to the AIB file transfer specifications specified in "The Principles and Rules of Operation" (the PRO). The specification for the files that can be transferred, their format, and the protocols for file transfer are all specified in the appropriate subsidiary document.
You need to be registered to be able to use the Hub. It is not possible to simply send messages to the Hub and have them forwarded to some other registry. This registration involves setting up basic details of your registry and creating a user who will have responsibility for managing key data about your new registry.
Before you can use the Hub for transferring live certificates you will also need to test your registry software. The Hub provides a test facility for this. You must register a test registry with the Hub to go through the test process. Once this process is complete, you may ask for your test registry to be re-classified as a live registry, or you may ask to register a new registry for live transfers. If you ask for a new registry you will be asked to confirm that the software is essentially the same software as you used for the test registry.
To set up a new registry you need the following information:
An email address for notifications and error messages. This is an email address to be used for sending notifications from the Hub to a responsible person within your organisation. Mostly these relate to transfers that have passed through the Hub, and, specifically, messages about problems with the format of transfer files. This email address is also used to send your private key when you generate a new security certificate for your transfers. You may change this as required.
An email address for messages. This is the email address that the Hub expects you to use when you send transfer files, and it is the email address the Hub uses to send transfer files to you. You may change this as required.
The Hub will check certificate transfer messages that you send to see that they come from the address you set here. If they do not then the Hub will simply ignore them.
The security certificate that you use must also match this address. If you change the address then you must also generate a new security key.
One or more URI style identifiers. These are valid URI identifiers that can be used in the header of the XML transfer files to identify you. You may enter more than one URI. The Hub will recognise you by any of these entries.
The URI must correspond exactly to the expected content of the <r:to> or <r:from> field. For example, if the content of the relevant field is uri:ean:99999999 then one of the URIs entered in the Hub must be uri:ean:99999999. The text is matched exactly.
The process for setting up a new registry follows these steps.
You are now ready to use the Hub. All of the screens are described in the user manual, and there is extra material covering testing in the test file description.
If you already have a registry that has been used for transferring certificates under the peer-to-peer protocol, there are, in principle, very few changes that you have to make.
The file formats do not change.
You need to install the Hub public key certificate and the AIB ca root certificate.
You must ensure that the generated files contain the appropriate valid URIs in the <r:to> and <r:from> fields in the file headers.
You should configure the Hub to use the old email address of your target registry as one of the valid URIs. This will allow the email addresses to be used in the header fields and may be convenient for registries that do not currently have a separate URI field as part of their other registry information.
You use messaging@system.aib-net.org as the target email address for sending.
You will be given a login name and password by your registry administrator. When you first access the site you will see a panel on the left. Enter your user name and password, and click 'Sign in'.
The panel on the left will be replaced by a menu showing the functions that you are able to use. The last item on this menu is the Logout function. Click on this when you have finished.
The browser holds a temporary cookie to record the fact that you are logged in. This cookie is deleted when the browser closes. This means that you can continue to use the system without having to log in again for as long as you have a browser window active. When you close all of your browser windows, when you close down your computer, for example, you will automatically be logged off.
The registry section holds basic details of your registry.
These details are:
Registry Short Name
This is the mnemonic that is used within the system to identify your registry. This name is used to create file names and database entries that are used to store your registry details. This name is allocated by the site administrator when your registry is first recorded on the system. You are not able to change it.
Registry Long Name
This is a full text, readable, name for your registry. You may change this as required.
email address for notification
This is an email address to be used for sending notifications from the Hub to a responsible person within your organisation. Mostly these relate to transfers that have passed through the Hub, and, specifically, messages about problems with the format of transfer files. This email address is also used to send your private key when you generate a new security certificate for your transfers. You may change this as required.
email address for messages
This is the email address that the Hub expects you to use when you send transfer files, and it is the email address the Hub uses to send transfer files to you. You may change this as required.
The Hub will check certificate transfer messages that you send to see that they come from the address you set here. If they do not then the Hub will simply ignore them.
The security certificate that you use must also match this address. If you change the address then you must also generate a new security key.
file location for certificates
This is an administrative field that is used by the message handling routines. It is set by the site administrator.
Live or Test indicator
A registry is either a live registry, holding real certificates, or it may be a test or demonstration registry that does not hold real certificates. The Hub prevents certificates from a live registry being sent to a test registry, and vice versa. You may change this as required.
Transport method
This is always set to SMTP. The field is reserved for future extensions,
URI
This field contains the URI that will be used in the header of the XML transfer files to identify you. You may enter more than one URI. The Hub will recognise you by any of these entries.
The URI must correspond exactly to the expected content of the <r:to> or <r:from> field. For example, if the content of the relevant field is uri:ean:99999999 then one of the URIs entered in the Hub must be uri:ean:99999999. The text is matched exactly.
This section gives you the ability to review file transfers that have been processed by the Hub. This is particularly important for reviewing error messages that have arisen from incorrectly formatted transfer files.
You must select a registry that is to be the focus of the transfer review. You have signed on as a user for a specific registry, so your registry is automatically pre-selected.
You can select transfers either to your registry, or from your registry, but not both at the same time.
The list focuses on the initial transfer files. The acknowledgment files are linked to their original transfer files and the status of the transfer indicates whether or not an acknowledgment file has been seen by the Hub.
To restrict the set of transfers displayed you may enter selection criteria in one or more fields on the selection screen. Press the List button when you have made your selection. The system will respond with a list of transfers. You may click on an entry in the list to see the details in the form underneath the list on the screen.
Some transfer attempts may not appear in the list. Any file that is sufficiently badly formatted that the address information cannot be read, or any file sent from an unrecognised email address will not progress beyond the file input processing and will not be seen here.
Registry
This is set to the registry that has been selected.
Sender
Here you select a filter for transfer files that have been sent to you.
This drop down list gives you a set of three choices:
- None - means that you do not wish to see files sent to you. The system will look at the Recipient field instead.
- Any - means you wish to review files sent to you by any other registry.
- A registry name - The remainder of the list is built up of all of the registries that have sent transfer files to you. You may select a specific registry.
Recipient
Here you select a filter for transfer files that have been sent by you.
This drop down list gives you a set of three choices:
- None - means that you do not wish to see files sent by you. The system will look at the Sender field instead.
- Any - means you wish to review files sent by you to any other registry.
- A registry name - The remainder of the list is built up of all of the registries that you have sent transfer files to. You may select a specific registry.
File ID
You may enter a specific file ID if you know exactly what you are looking for, This file ID is generated internally by the sending registry, so you may need to look inside the XML file to find this detail. This field is useful in looking for a delayed acknowledgment or looking back at error messages when the file ID has been identified.
Sent on or after
Enter a date. The date picker icon on the right hand end of the field provides a convenient way of entering a valid date. The system will select transfers that were seen by the Hub on or after that date.
Sent before
Enter a date. The date picker icon on the right hand end of the field provides a convenient way of entering a valid date. The system will select transfers that were seen by the Hub before that date.
File Identifier
The file ID generated by the sending registry and used to identify this particular exchange.
Sending Registry
The name of the registry that sent the original transfer.
URI of Sender
The URI that was used by the sender in the address header.
Receiving Registry
The name of the registry the file was sent to.
URI of Recipient
The URI that the sender used in the address header to identify the recipient
Status
This shows what has happened to the transfer:
- 'exp forwarded' - The original transfer file was sent on to the recipient and no response has been seen.
- 'nak response' - The original transfer file had an error detected by the Hub. The Hub has returned a NAK directly to the sender without forwarding the message to the recipient.
- 'ack forwarded' - The recipient has returned a positive acknowledgment for the transfer file. The ACK response has been forwarded to the original sender.
- 'nak forwarded' - The recipient has returned a negative acknowledgment for the transfer file. The ACK response has been forwarded to the original sender.
Date of transfer
The date the transfer was processed by the Hub.
Date of response
The date the response was processed by the Hub. This will be empty if no response has been processed.
Path to file
The internal location of the transfer file. This is used by the site administrator to answer questions on XML format problems when, for example, the Hub returns a NAK directly.
Transfer Messages
A text area showing all of the system messages that have been generated in processing this transfer. If the Hub identifies a problem and returns an immediate NAK these messages will indicate where the problem was found.
This area is where you manage tests. You can create a new test set, initiate the test, and enter the NAK file result. You can also review the status of tests.
Each test involves a number of transfer files. These files may be reviewed individually in the Test Files area.
You must select a registry that is to be the focus of the transfer review. You have signed on as a user for a specific registry, so your registry is automatically pre-selected.
To restrict the set of tests displayed you may enter selection criteria in one or more fields on the selection screen. Press the List button when you have made your selection. The system will respond with a list of tests. You may click on an entry in the list to see the details in the form underneath the list on the screen.
Registry
This is set to the registry that has been selected.
Scope of test (Target Chapter)
You can select a particular test class from the drop down list.
Type of test
You can select a particular type of test form the drop down list.
The form below the test selection list shows the details of the selected test.
Test Identifier (Auto allocation)
The identifier created automatically by the system when you created the test.
Scope of test (Target Chapter)
The set of test files that have been requested.
Type of test
The type that you used to designate this test.
Date test initiated
This date when you initiated the test.
File ID for NAK test
The transfer file ID you entered in response to the unexpected NAK sent by the test facility.
Test Completion Status
The current status of the test. This field is filled in automatically by the system as the test progresses.
The status indicates whether or not some files are yet to be processed and whether any responses were incorrect. For details of responses to individual test files, see the Test Files area.
The form below the test selection list can be used to add a new test. Ensure that there is no current selection by clicking then clear button. Enter the relevant details for the new test.
Test Identifier (Auto allocation)
This field is filled in automatically by the system when you create the test.
Scope of test (Target Chapter)
Select a particular test class from the drop down list.
Type of test
Select a particular type of test form the drop down list.
The type does not have any formal significance. It is a convenience to allow you to manage your own testing process.
Date test initiated
This field is filled in automatically by the system when you initiate the test.
Status
This field is filled in automatically by the system as the test progresses.
Select a test that you have not yet initiated. The detail screen will display the test details and an 'initiate' button.
Pressing the initiate button causes the test processor to send the predefined set of test files to your registry. The test processor will then also be able to receive test files from your registry.
The test files are being sent through the Hub. Because the hub_tester registry has been defined as a test registry, you must ensure that the registry you are using has also been defined as a test registry. If this is not done the Hub will not transfer files in either direction.
Use "hub_tester@system.aib-net.org" as the URI for the hub_tester registry when sending files to the Hub.
Select a test that you have initiated. The detail screen will display the test details. The NAK response field will be enabled and you may enter the file ID for the test file where you received an unexpected NAK.
The form displays a test completion status that indicates what is outstanding or what problems may have arisen. The following messages are shown here:
One or more input files have not been received:
This means that the test facility has not received at least one of the files it is expecting from you. If you have sent files, these may have been rejected by the Hub itself when the files were being forwarded, or the files do not correspond to the expected file structures for the test. (See the test file description for more information)
One or more output files have not been acknowledged:
The Hub Test Facility is waiting for you to respond to one or more of the files you were sent.
One or more output files has an error:
Your response to a file you were sent was ACK when NAK was expected, or NAK when ACK was expected.
The NAK test file ID has not been entered:
You have not yet enetered the File ID for the file you sent that was given a NAK response instead of the expected ACK. (This message also appears if you have entered a File ID but you have not yet sent any files. That is, there are no files to test your entered value against)
The NAK test file ID is not the one expected:
You have entered a File ID but the Hub Test Facility has not been able to match it against any of the files you have sent, or, the File ID matches a file that received an ACK response.
This area provides details for individual test files in the currently selected test set.
The files in the test set are listed for you and you click on a specific file to see the details in the form below the list.
There are three types of entry in this selection list, indicated by the text 'out', 'rcpt' and 'in' under the 'in/out' heading.
- out:
- These refer to files sent by the Hub Test Facility to you. The 'status' column indicates whether the Hub Test Facility has received an acknowledgement from you, and what type of acknowledgement it was.
- rcpt:
- These refer to files you have sent and that the Hub Test Facility has received. The 'status' column gives the name of the template that your file has been matched against. If your file did not match any template then the status shows 'nak'.
- in:
These refer to files that the Hub Test Facility is expecting to receive from you. The lines do not contain any information other than the 'status' column. This column shows 'ack' if you have sent a file that the Hub Test Facility has recognised and properly matched against that particular expected file.
Selecting one of these 'in' lines does not display any further detail.
Test Instance
The test identifier allocated by the system.
File Identifier
The file ID for the specific file.
Input/Output
Whether this this file has been received from you or output from the test facility to you.
File Path
The location of the file in the system. This is used for administration and support only.
File Name
The name of the file. This identifies the original file in the test set template.
Date/Time of transfer
The date and time when the file was sent or received by the test facility.
Actual Response
The actual response to the transfer.
- rcpt:
This shows the name of the template that the file matched. If the file did not match a template then it shows 'nak'.
It is quite possible for you to sent more than one file that matches a given template. This is not a problem, and all the files you send will be listed. It is, however, only actually necessary to send one file that matches a template and additional files are redundant.
- out:
This shows the type of response the Hub Test Facility has received from you.
Expected Response
The response expected for this file according to the test definition. The expected response and the actual response must be the same for the test to succeed.
This area is restricted to users with an appropriate privilege setting.
The available security certificates are listed for you, and you click on a specific certificate to enable the installation screen.
The currently installed certificate is indicated in the list.
This form is only visible if there is no currently selected certificate. Click the clear button if necessary.
When you have completed the required fields, click the add button. The new certificate will be generated and it will appear in the displayed list of available certificates. The private key will be sent to your notification email address at the same time. Please keep the private key safe. It will be possible to recover it from the system when you install the certificate, but this facility is provided for safety only. You will generally want to coordinate the installation of the private key with the activation of the public key on the Hub.
You will also want to download the AIB certificate authority root certificate and install this as a trusted certificate authority.
Intended Start Date
You must enter a start date for the certificate. The date picker icon on the right hand end of the field provides a convenient way of entering a valid date.
Intended End Date
You may enter an expiry date. The date picker icon on the right hand end of the field provides a convenient way of entering a valid date.
If you do not enter an expiry date the system will automatically create a certificate with a life time of 365 days.
Your password for the private key
You must enter a password of eight (8) characters or more. This password is used to protect the private key that the system generates. The system does not keep a record of this password, so you must remember the password yourself. You will need the password when you install the private key in your own system.
The system does not enforce any particular password scheme other than a minimum length. Although the process of generating the password and passing it to you is reasonably secure, it is not perfect. You may wish to use a longer password with numeric characters and a mix of upper and lower case.
Your password again
You must enter your chosen password again as an assurance against typing errors.
This form shows the identifier for the selected certificate and provides an install button.
Click on the button to activate the certificate. At this point the public key part will become active in the Hub, so that transfers will use the new certificate in communications with your registry.
For convenience the associated private key is emailed to your notification email address at the same time.
The structure of the XML files is described in the relevant PRO appendix.
Files are sent from one registry to another through the Hub:
This process works for any file that jas to be transferred, whether an export file, and acknowledgment or some other file that may be introduced in the future.
Each registry needs its own private key, and the Hub needs the corresponding public key certificate. See Security Certificates
Each registry also needs the Hub public key certificate. This either messaging.crt or messaging.p7c depending on how your system handles these keys.
No other security certificates are needed.
The file formats do not change.
You need to install the Hub public key certificate and the AIB ca root certificate..
You must ensure that the generated files contain the approprite valid URIs in the <r:to> and <r:from> fields in the file headers.
You should configure the Hub to use the old email address of your target regisrty as one of the valid URIs. This will allow the email addresses to be used in the header fields and may be convenient for registries that do not currently have a separate URI field as part of their other registry information.
You use messaging@system.aib-net.org as the target email address for sending.
2008/04/01 - Expand on the implications for the email address for messages
2007/10/20 - Add a section for New Users
2007/06/07 - Add a link to test file description
2007/03/27 - First version installed