Skip to content

Commit

Permalink
Rename manifest to host, introduce new manifest wrapper
Browse files Browse the repository at this point in the history
  • Loading branch information
@wrygiel
wrygiel committed Dec 4, 2017
1 parent 172d026 commit 58930bc
Show file tree
Hide file tree
Showing 2 changed files with 148 additions and 124 deletions.
219 changes: 110 additions & 109 deletions manifest-example.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,113 +45,114 @@
"
>
<!-- This example doesn't contain many comments, but its XML Schema does! -->

<ewp:admin-email>admin-or-developer@example.com</ewp:admin-email>
<ewp:admin-notes>It's not a real manifest. Just an example.</ewp:admin-notes>

<r:apis-implemented>
<!-- All API entries are defined in their own separate XML namespaces.
You need to use proper `xmlns` in order for them to be matched properly. -->

<!-- The entry for the Discovery Manifest API (a self-reference). -->
<discovery
xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-discovery/blob/stable-v5/manifest-entry.xsd"
version="5.0.0"
>
<url>https://example.com/manifest.xml</url>
</discovery>

<!-- Some other API, just for the purpose of example. Each API entry has a
different XML namespace and a different structure. These structures are often
quite similar to each other, but sometimes they're not. -->
<echo
xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v2/manifest-entry.xsd"
version="2.0.0"
>
<!-- Note, that ewp:admin-email and ewp:admin-notes can be defined both on the
global level, and on the API level. -->
<ewp:admin-email>usually-a-developer@example.com</ewp:admin-email>
<ewp:admin-email>some-other-developer@example.com</ewp:admin-email>
<ewp:admin-notes>Some notes which might be useful for client developers.</ewp:admin-notes>

<!-- Many APIs define the security requirements of their implementations with help
of elements like this one. See Echo API's manifest-entry.xsd file for details. -->
<http-security>
<sec:client-auth-methods>
<tlscert
xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-cliauth-tlscert/tree/stable-v1"
allows-self-signed="true"
/>
<httpsig xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-cliauth-httpsig/tree/stable-v1"/>
</sec:client-auth-methods>
<sec:server-auth-methods>
<tlscert xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-srvauth-tlscert/tree/stable-v1"/>
<httpsig xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-srvauth-httpsig/tree/stable-v1"/>
</sec:server-auth-methods>
</http-security>

<!-- The URL at which this Echo API is served. See Echo API's manifest-entry.xsd
file for details. -->
<url>https://example.com/ewp/echo</url>
</echo>
</r:apis-implemented>

<mf:institutions-covered xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-registry/tree/stable-v1">
<hei id="uw.edu.pl">
<other-id type="pic">999572294</other-id>
<other-id type="erasmus">PL WARSZAW01</other-id>
<name xml:lang="en">University of Warsaw</name>
</hei>
</mf:institutions-covered>

<client-credentials-in-use>

<!-- This one is used for TLS Client Authentication (optional) -->
<certificate>
MIIDuTCCAqGgAwIBAgIJAK5ps0mVHjvZMA0GCSqGSIb3DQEBCwUAMHIxCzAJBgNV
BAYTAlBMMRQwEgYDVQQIDAtNYXpvd2llY2tpZTERMA8GA1UEBwwIV2Fyc3phd2Ex
DDAKBgNVBAoMA0VXUDEsMCoGA1UEAwwjU2FtcGxlIFJTQSAyMDQ4IENlcnRpZmlj
YXRlIGZvciBFV1AwIBcNMTYwNjA5MjA0MzAzWhgPMjI5MDAzMjUyMDQzMDNaMHIx
CzAJBgNVBAYTAlBMMRQwEgYDVQQIDAtNYXpvd2llY2tpZTERMA8GA1UEBwwIV2Fy
c3phd2ExDDAKBgNVBAoMA0VXUDEsMCoGA1UEAwwjU2FtcGxlIFJTQSAyMDQ4IENl
cnRpZmljYXRlIGZvciBFV1AwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDaB2/WrqF3uMZquhlDAfSbmPwEDTpIwSVvx7rBD9S7H231E++Hp5YS8vHVrsaX
oxy/ADyK0acdSYKhMowatloycSoWMMu22iVvUNHYhcsGrXYBBev7+JJEYl688vdi
MGO98PeYj+orQtjSZINNUbiO3TfM+Y6AuAIO5mrcdSfBgijlUV6ia5GrfF6lysY6
xKEZ6lBtWzjqBApsBKl3iYOAR5fj1t0k7bFf/JacOdZYda1adfasgcfifq3P9nkB
tNMU7FHcQdchbFawIENjAgSz4sJvA8rooVA6TvSj4jVjkbtWo9Q3mwY+5UICZKM+
l6seNz7D5O+OXEzq9iSBy/ULAgMBAAGjUDBOMB0GA1UdDgQWBBQSkyNNL1JI4XSY
WUOf2c+psBT09TAfBgNVHSMEGDAWgBQSkyNNL1JI4XSYWUOf2c+psBT09TAMBgNV
HRMEBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQDViw6XUCdXIfZgoin5g7jr1txY
ZL1nCpHorwGMRezmwnfOg/4I+wPS9325eUmnFhjSVlYyIWcRWovpMEh0MEY2p6/K
yJEaFbSkpwNA0+c3qdQbz6/b6o2LnFU6e6mWsAwxURi6Mxf+Cs7NoU+Ef4MkcefE
k6edF2wZjJl58IEGnP7tY7BCqV87WYGKE9tRE7LYREHVbqNh1d+QUz3er0HRHD0l
YQWikBdQrF6xUnin7bA8eC1YV+G6rrxCKDeSTMQtC8mCzQUP4coGfrSaJETv1Lue
CAsLtNi5QyYgfvdPjvCOAS8s9t9iPSvJUvHBr01/oFZJ5aQQ3tclZcYw0mw/
</certificate>

<!-- And this one is used for HTTP Signature Authentication -->
<rsa-public-key>
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkQojIPtX+BYGGC2f1zXr
U3ijq5oApW6YA+mSiB3p5pEQRUuvIHKbSKRXQaW/5hORYpWU1GzU2Wq99vykjX9b
8GQlM+0xbFP0cILIhjz23R0Q53mKcf2xAzQt2b3f56QOnjUaKbXsuB+ejTLAtQ4D
yKYSodCzUFkuUZUw+TK7G9ySMbcVHqrG8qDCw3/7CXkN0Wf9HpSnYP5fwd426fay
u6RXGeX5vUuX5BJkjsxoL8Smn7TB31LSFn3LbQLzG4UuxGaGgHWZCMSC35dX2d3z
4zcpZxgyN8LNWXCf4g95b20Ljsbnvk1dIUTJtRJJ29zbWXcgXgVl69UKQx8NxXIx
6wIDAQAB
</rsa-public-key>
</client-credentials-in-use>

<server-credentials-in-use>
<!-- Used for HTTP Signature Authentication -->
<rsa-public-key>
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkQojIPtX+BYGGC2f1zXr
U3ijq5oApW6YA+mSiB3p5pEQRUuvIHKbSKRXQaW/5hORYpWU1GzU2Wq99vykjX9b
8GQlM+0xbFP0cILIhjz23R0Q53mKcf2xAzQt2b3f56QOnjUaKbXsuB+ejTLAtQ4D
yKYSodCzUFkuUZUw+TK7G9ySMbcVHqrG8qDCw3/7CXkN0Wf9HpSnYP5fwd426fay
u6RXGeX5vUuX5BJkjsxoL8Smn7TB31LSFn3LbQLzG4UuxGaGgHWZCMSC35dX2d3z
4zcpZxgyN8LNWXCf4g95b20Ljsbnvk1dIUTJtRJJ29zbWXcgXgVl69UKQx8NxXIx
6wIDAQAB
</rsa-public-key>
</server-credentials-in-use>
<host>
<ewp:admin-email>admin-or-developer@example.com</ewp:admin-email>
<ewp:admin-notes>It's not a real manifest. Just an example.</ewp:admin-notes>

<r:apis-implemented>
<!-- All API entries are defined in their own separate XML namespaces.
You need to use proper `xmlns` in order for them to be matched properly. -->

<!-- The entry for the Discovery Manifest API (a self-reference). -->
<discovery
xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-discovery/blob/stable-v5/manifest-entry.xsd"
version="5.0.0"
>
<url>https://example.com/manifest.xml</url>
</discovery>

<!-- Some other API, just for the purpose of example. Each API entry has a
different XML namespace and a different structure. These structures are often
quite similar to each other, but sometimes they're not. -->
<echo
xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v2/manifest-entry.xsd"
version="2.0.0"
>
<!-- Note, that ewp:admin-email and ewp:admin-notes can be defined both on the
global level, and on the API level. -->
<ewp:admin-email>usually-a-developer@example.com</ewp:admin-email>
<ewp:admin-email>some-other-developer@example.com</ewp:admin-email>
<ewp:admin-notes>Some notes which might be useful for client developers.</ewp:admin-notes>

<!-- Many APIs define the security requirements of their implementations with help
of elements like this one. See Echo API's manifest-entry.xsd file for details. -->
<http-security>
<sec:client-auth-methods>
<tlscert
xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-cliauth-tlscert/tree/stable-v1"
allows-self-signed="true"
/>
<httpsig xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-cliauth-httpsig/tree/stable-v1"/>
</sec:client-auth-methods>
<sec:server-auth-methods>
<tlscert xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-srvauth-tlscert/tree/stable-v1"/>
<httpsig xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-srvauth-httpsig/tree/stable-v1"/>
</sec:server-auth-methods>
</http-security>

<!-- The URL at which this Echo API is served. See Echo API's manifest-entry.xsd
file for details. -->
<url>https://example.com/ewp/echo</url>
</echo>
</r:apis-implemented>

<mf:institutions-covered xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-registry/tree/stable-v1">
<hei id="uw.edu.pl">
<other-id type="pic">999572294</other-id>
<other-id type="erasmus">PL WARSZAW01</other-id>
<name xml:lang="en">University of Warsaw</name>
</hei>
</mf:institutions-covered>

<client-credentials-in-use>

<!-- This one is used for TLS Client Authentication (optional) -->
<certificate>
MIIDuTCCAqGgAwIBAgIJAK5ps0mVHjvZMA0GCSqGSIb3DQEBCwUAMHIxCzAJBgNV
BAYTAlBMMRQwEgYDVQQIDAtNYXpvd2llY2tpZTERMA8GA1UEBwwIV2Fyc3phd2Ex
DDAKBgNVBAoMA0VXUDEsMCoGA1UEAwwjU2FtcGxlIFJTQSAyMDQ4IENlcnRpZmlj
YXRlIGZvciBFV1AwIBcNMTYwNjA5MjA0MzAzWhgPMjI5MDAzMjUyMDQzMDNaMHIx
CzAJBgNVBAYTAlBMMRQwEgYDVQQIDAtNYXpvd2llY2tpZTERMA8GA1UEBwwIV2Fy
c3phd2ExDDAKBgNVBAoMA0VXUDEsMCoGA1UEAwwjU2FtcGxlIFJTQSAyMDQ4IENl
cnRpZmljYXRlIGZvciBFV1AwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDaB2/WrqF3uMZquhlDAfSbmPwEDTpIwSVvx7rBD9S7H231E++Hp5YS8vHVrsaX
oxy/ADyK0acdSYKhMowatloycSoWMMu22iVvUNHYhcsGrXYBBev7+JJEYl688vdi
MGO98PeYj+orQtjSZINNUbiO3TfM+Y6AuAIO5mrcdSfBgijlUV6ia5GrfF6lysY6
xKEZ6lBtWzjqBApsBKl3iYOAR5fj1t0k7bFf/JacOdZYda1adfasgcfifq3P9nkB
tNMU7FHcQdchbFawIENjAgSz4sJvA8rooVA6TvSj4jVjkbtWo9Q3mwY+5UICZKM+
l6seNz7D5O+OXEzq9iSBy/ULAgMBAAGjUDBOMB0GA1UdDgQWBBQSkyNNL1JI4XSY
WUOf2c+psBT09TAfBgNVHSMEGDAWgBQSkyNNL1JI4XSYWUOf2c+psBT09TAMBgNV
HRMEBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQDViw6XUCdXIfZgoin5g7jr1txY
ZL1nCpHorwGMRezmwnfOg/4I+wPS9325eUmnFhjSVlYyIWcRWovpMEh0MEY2p6/K
yJEaFbSkpwNA0+c3qdQbz6/b6o2LnFU6e6mWsAwxURi6Mxf+Cs7NoU+Ef4MkcefE
k6edF2wZjJl58IEGnP7tY7BCqV87WYGKE9tRE7LYREHVbqNh1d+QUz3er0HRHD0l
YQWikBdQrF6xUnin7bA8eC1YV+G6rrxCKDeSTMQtC8mCzQUP4coGfrSaJETv1Lue
CAsLtNi5QyYgfvdPjvCOAS8s9t9iPSvJUvHBr01/oFZJ5aQQ3tclZcYw0mw/
</certificate>

<!-- And this one is used for HTTP Signature Authentication -->
<rsa-public-key>
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkQojIPtX+BYGGC2f1zXr
U3ijq5oApW6YA+mSiB3p5pEQRUuvIHKbSKRXQaW/5hORYpWU1GzU2Wq99vykjX9b
8GQlM+0xbFP0cILIhjz23R0Q53mKcf2xAzQt2b3f56QOnjUaKbXsuB+ejTLAtQ4D
yKYSodCzUFkuUZUw+TK7G9ySMbcVHqrG8qDCw3/7CXkN0Wf9HpSnYP5fwd426fay
u6RXGeX5vUuX5BJkjsxoL8Smn7TB31LSFn3LbQLzG4UuxGaGgHWZCMSC35dX2d3z
4zcpZxgyN8LNWXCf4g95b20Ljsbnvk1dIUTJtRJJ29zbWXcgXgVl69UKQx8NxXIx
6wIDAQAB
</rsa-public-key>
</client-credentials-in-use>

<server-credentials-in-use>
<!-- Used for HTTP Signature Authentication -->
<rsa-public-key>
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkQojIPtX+BYGGC2f1zXr
U3ijq5oApW6YA+mSiB3p5pEQRUuvIHKbSKRXQaW/5hORYpWU1GzU2Wq99vykjX9b
8GQlM+0xbFP0cILIhjz23R0Q53mKcf2xAzQt2b3f56QOnjUaKbXsuB+ejTLAtQ4D
yKYSodCzUFkuUZUw+TK7G9ySMbcVHqrG8qDCw3/7CXkN0Wf9HpSnYP5fwd426fay
u6RXGeX5vUuX5BJkjsxoL8Smn7TB31LSFn3LbQLzG4UuxGaGgHWZCMSC35dX2d3z
4zcpZxgyN8LNWXCf4g95b20Ljsbnvk1dIUTJtRJJ29zbWXcgXgVl69UKQx8NxXIx
6wIDAQAB
</rsa-public-key>
</server-credentials-in-use>
</host>
</manifest>
53 changes: 38 additions & 15 deletions manifest.xsd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,19 +38,42 @@
<xs:documentation>
EWP Discovery Manifest.

Defines a single EWP Host - a set of relationships between HEIs, APIs, server
administrators and client credentials. One EWP Host defines a single Cartesian
product of all these sets. (E.g. if a client certificate X and a HEI Y are
present in the same host, then it means that server which signs its requests
with X is allowed to request resources visible to HEI Y. Similar statement is
true for every other pair of sets.)

Most partners will need exactly one manifest. However, in some cases, you might
need to have more than one. For example, when you server covers two HEIs, but
one of your APIs is available for only one of these two HEIs, then it's
impossible to describe such relationship with a single Cartesian product. You
will need to use a sum of at least two Cartesian products (which is expressed
by two `host` entries).
Manifest files describe a set of EWP Hosts. Manifest files are usually read by
the EWP Registry Service only.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element ref="host" minOccurs="1" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
One v5 manifest file can describe multiple EWP Hosts (this is the primary
difference between v4 and v5 of Discovery API).
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:element name="host">
<xs:annotation>
<xs:documentation>
Defines a single EWP Host.

EWP Host defines relationships between HEIs, APIs, server administrators and
client credentials. One EWP Host defines a single Cartesian product (a "join")
of all these sets. (E.g. if a client certificate X and a HEI Y is present in
the same host, then it means that server which signs its requests with X is
allowed to request resources visible to HEI Y. Similar statement is true for
every other pair of sets.)

Most partners will have exactly one `host` entry. However, in some cases you
might be needed to describe more than one. For example, when you server covers
two HEIs, but one of your APIs is available for only one of these two HEIs,
then it's impossible to describe such relationship with a single Cartesian
product. You will need to use a sum of at least two Cartesian products. (which
is expressed by two `host` entries).
</xs:documentation>
</xs:annotation>
<xs:complexType>
Expand All @@ -63,8 +86,8 @@
server errors, etc.). Multiple addresses may be provided.

Please note, that additional `admin-email` elements can also be included inside
specific APIs sections (this allows you to bind extra admins to specific APIs
without the need of creating dedicated manifest files).
specific APIs sections (this allows you to add extra admins to specific APIs
without the need of creating extra `host` entries).
</xs:documentation>
</xs:annotation>
</xs:element>
Expand Down

0 comments on commit 58930bc

Please sign in to comment.