One document matched: draft-hallambaker-omnibroker-03.xml

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd"[
  <!ENTITY rfc2629 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml'>
    <!ENTITY RFC1035 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1035.xml">
    <!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
    <!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
    <!ENTITY RFC5280 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5280.xml">
    <!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
    <!ENTITY RFC3642 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3642.xml">    
    <!ENTITY RFC4033 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4033.xml">
    <!ENTITY RFC4055 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4055.xml">
    <!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
    <!ENTITY RFC5395 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5395.xml">
  <!ENTITY RFC4366 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4366.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" docName="draft-hallambaker-omnibroker-03" ipr="trust200902">

  <front>
    <title abbrev="OmniBroker Protocol">OmniBroker Protocol</title>
    <author fullname="Phillip Hallam-Baker" initials="P. M." surname="Hallam-Baker">
      <organization>Comodo Group Inc.</organization>
      <address>
        <email>philliph@comodo.com</email>
      </address>
    </author>
 
    <date day="17" month="May" year="2013" />

    <area>General</area>

    <workgroup>Internet Engineering Task Force</workgroup>

    <abstract>
      <t>
        An Omnibroker is an agent chosen and trusted by an Internet user to
        provide information such as name and certificate status information
        that are in general trusted even if they are not trustworthy.
        Rather than acting as a mere conduit for information provided by
        existing services, an Omnibroker is responsible for curating those
        sources to protect the user.
      </t>
      <t>
        The Omnibroker Protocol (OBP) provides an aggregated interface to
        trusted Internet services including DNS, OCSP and various forms
        of authentication service. Multiple transport bindings are
        supported to permit efficient access in virtually every common
        deployment scenario and ensure access in any deployment
        scenario in which access is not being purposely denied.
      </t>

    </abstract>
  </front>

  <middle>
    <section title="Definitions">
      <section title="Requirements Language">
        <t>
          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
          "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
          document are to be interpreted as described in <xref target="RFC2119">RFC 2119</xref>.
        </t>
      </section>

    </section>
    <section title="Purpose">
      <t>
        An Omnibroker is an agent chosen and trusted by an Internet user to
        provide information such as name and certificate status information
        that are in general trusted even if they are not trustworthy.
        Rather than acting as a mere conduit for information provided by
        existing services, an Omnibroker is responsible for curating those
        sources and providing autheticated, curated results to the endpoint
        client.
      </t>
      <t>
        Unlike the traditional trusted information services that are expected
        to deliver the same response to a query regardless of who asks the
        question, OBP permits an Omnibroker to return a response that is
        tailored to the specific party asking the question. This permits the
        use of an authentication approach that has negligible impact
        on performance and permits an
        Omnibroker to answer questions that a traditional public Internet
        information service could not. In particular, an Omnibroker
        can broker peer to peer connections
      </t>
      <section title="A Curated Service">
        <t>
          In the traditional configuration, an Internet host accepts DNS service
          from the IP address specified by the local network provider, frequently
          the DNS server advertised by the local DHCP service. This approach
          creates an obvious security risk as DNS is clearly a trusted service
          and a random DNS service advertised by the local DNS is clearly not
          trustworthy.
        </t>
        <t>
          A policy of only using a chosen DNS service provides a reduction in
          risk but only a modest one since the standard DNS service does not
          provide authenticated results. Many local area networks intercept all
          DNS traffic and process it through the local DNS server regardless
          of the intended destination IP address. This practice is highly
          desirable if it would prevent a client from accessing an untrustworthy
          DNS service in place of a trustworthy local DNS service and
          extreemly undesirable in the contrary case.
        </t>
        <t>
          In addition to ensuring the authenticity of DNS resolution responses,
          such services frequently provide filtering of Internet addresses
          the network provider considers undesirable. Many workplaces block access
          to Web sites that are considered detrimental to productivity.
          Many parent subscribe to services that filter content they consider
          undesirable. While the value of such services is debatable they
          are services that those customers have chosen to deploy on their
          networks to meet their perceived security requirements. New security
          proposals that do not support such capabilities or seek to
          actually circumvent them will not be acceptable to those
          constituencies.
        </t>
        <t>
          While DNS filtering is a form of censorship, not all forms of
          DNS filering are intrinsically undesirable censorship. Spam filtering
          is also a form of censorship albeit one that is not normally
          regarded as such because it most Internet users now consider it to
          be an essential security control. Anti-Virus tools are also a form
          of censorship. DNS filtering tools that block access to sites that
          distribute malware are also a form of censorship and are rapidly
          gaining popularity for the same reason.
        </t>
        <t>
          While all forms of censorship raise civil liberties concerns,
          censorship should not automatically raise civil liberties objections.
          It is not the fact that filtering is taking place but
          the party that is in control of the filtering that should
          raise civil liberties concerns. In an Internet of
          2 billion users, all users are obliged to perform some filtering.
          OBP is designed to make the party that is in control of the
          filtering process apparent and provide the end user with the
          ability to select the Omnibroker of their choice.
        </t>
        <t>
          DNSSEC provides a means of determining that a DNS record is the
          authentic record published by the source but this capability alone
          does not meet the security requirements for DNS resolution services
          as they have come to be understood since the protocol was first proposed.
        </t>
        <t>
          Internet users want to be safe from all forms of attack, not just
          the DNS resolver mani-in-the-middle attack that 'end-to-end'
          deployment of DNSSEC is designed to address. An Internet user is
          far more likely to be directed to a site with a DNS name controlled
          by a criminal gang than be subject to a man-in-the-middle attack.
        </t>
        <t>
          Most users would prefer to have an Internet connection that is
          'curated' to remove at least some of the locations they consider
          to be undesirable. The fact that an organised criminal gang has put
          a host on the Internet does not mean that any other Internet user
          should be obliged to allow it to connect to any of the machines that
          they own.
        </t>
        <t>
          The same argument for curating the raw results applies to
          other forms of trusted information service. The fact that a
          Certificate Authority has issued a digital certificate and
          considers it to be valid should not mean that the end party
          is automatically considered trustworthy by anyone and for
          any purpose.
        </t>
        <t>
          The deployment of security policy capabilities presents another
          case in which direct reliance on raw data is undesirable. While
          security policies such as 'host always offers TLS' or 'mail
          server always signs outgoing mail with DKIM' can provide
          considerable security advantages, only some of the security
          policy information that is published is accurate and kept
          up to date. Curating such data sources typically proves
          essential if an unacceptable rate of false positives is
          to be avoided.
        </t>
        <t>
          Although a client is permitted to curate its own data sources
          it rarely has a sufficient amount of data to make decisions
          as accurately as a network service that can draw on a wide
          variety of additional data including tracking of communication
          patterns, historical data series and third party reputation
          services.
        </t>
        <t>
          Curation in the network offers better asgility than the client
          approach. Agility is an important consideration when an attacker
          changes their strategy rapidly and repeatedly to counter
          new defensive controls.
        </t>
        <t>
          While curating trusted data sources is an established and
          proven practice, current practice has been to curate each
          source individually. This approach avoids the need to write
          a new protocol but limits the information a curator can
          leverage to detect potential danger. Leveraging multiple
          data sources simultaneously allows better accuracy than
          applying each individually.
        </t>
      </section>

      <section title="Connection Broker">
        <t>
          The OBP service connection broker answers the query 'what connection
          parameters should be used to establish the best connection
          to interract with party X according to protocol Y. Where 'best'
          is determined by the Omnibroker which MAY take into account
          parameters specified by the relying party.
        </t>
        <section title="Service Connection Broker">
          <t>
            The OBP service connection broker supports and extends the traditional
            DNS resolution service that resolves a DNS name (e.g. www.example.com) to
            return an IP address (e.g. 10.1.2.3).
          </t>
          <t>
            When using an Omnibroker as a service connection broker, a client
            specifies both the DNS name (e.g. www.example.com) and the
            Internet protocol to be used (e.g. _http._tcp). The returned
            connection parameters MAY include:
          </t>
          <t>
            <list>
              <t>
                The IP protocol version, address and port number to
                establish a connection to.
              </t>
              <t>
                If appropriate, a security transport such as TLS or IPSEC.
              </t>
              <t>
                If appropriate, a description of a service credential such
                as a TLS certificate or a constraint on the type of certificates
                that the client should consider acceptable.
              </t>
              <t>
                If appropriate, application protocol details such as
                version and protocol options.
              </t>
            </list>
          </t>
          <t>
            If an attempt to connect with the parameters specified fails, a
            client MAY report the failure and request a new set of parameters.
          </t>

        </section>
        <section title="Peer Connection Broker">
          <t>
            Each OBP request identifies both the account under which the
            request is made and the device from which it is made. An OBP broker
            is thus capable of acting as a peer connection broker service
            or providing a gateway to such a service.
          </t>
          <t>
            When using Omnibroker as a peer connection broker, a client
            specifies the account name and DNS name of the party with which
            a connection is to be established (e.g. alice@example.com)
            and the connection protocol to be used (e.g. _xmpp-client._tcp)
          </t>
          <t>
            The returned
            connection parameters are similar to those returned in response to a
            service broker query.
          </t>
        </section>
        <section title="Connection Broker API">
          <t>
            In the traditional BSD sockets API a network client performs
            a series of calls to resolve a network name to a list of IP
            addresses, selects one and establishes an IP connection to
            a port specified by the chosen application protocol.
          </t>

          <t>
            OBP anticipates a higher level abstract API that encapsulates
            this complexity, hiding it from the application code.
          </t>
          <t>
            In the case that one (or more) OBP services are configured,
            the library supporting the SHOULD obtain connection parameters
            from the OBP service. Otherwise, it SHOULD establish a connection
            using the traditional calling sequence of resolving a host
            name to obtain an IP address, etc.
          </t>
        </section>
      </section>

      <section title="Service Advertisement">
        <t>
          Service advertisement is the converse of service resolution. An
          Internet application wishing to accept inbound connections specifies
          one or more sets of connection parameters for the Omnibroker to
          register with whatever naming, discovery or other services may
          be appropriate.
        </t>
        <t>

        </t>
        <section title="Connection Advertisement API">
          <t>
            OBP anticipates the use of a high level API for connection advertisement
            that is the converse of the Connection broker API. Instead
            of establishing a connection, the API is used to advertise
            that a connection is offered either as a service or a peer.
          </t>

          <t>
            An application MAY offer multiple types of connection with
            different connection properties (e.g. IPv4/IPv6, with and
            without SSL, etc.). This MAY be supported by marking certain
            properties as being optional and/or by permitting the
            API to be called multiple times with different properties
            specified.
          </t>
        </section>
      </section>
      <section title="Credential Validation Broker">
        <t>
          A credential validation broker reports on the validity and
          trustworthiness of credentials presented to a client by Internet
          services and/or peers.
        </t>
        <t>
          The service provided by OBP is similar to that provided by
          OCSP and SCVP. Like SCVP, OBP is an agent selected by the
          relying party to validate certificates and/or construct
          trust paths on its behalf.
        </t>
      </section>
      <section title="Authentication Gateway">
        <t>
          Every OBP request is strongly authenticated by means of a shared
          secret that is unique to the account and the device. This may be
          leveraged to permit use as an authentication gateway, providing
          access to other credentials that the client has established the
          right to use.
        </t>
        <t>
          An Authentication Gateway MAY provide access to account names and
          passwords that the account holder has chosen to store in the cloud for
          access to sites that do not support a stronger,
          cryptographically based form of
          authentication such as OAuth.
        </t>
      </section>
      <section title="Credential Announcement">
        <t>
          An Authentication Gateway can only provide access to credentials
          that it has notice of. A client uses the Credential Announcement
          transaction to advise the service of a new credential.
        </t>
      </section>
      
    </section>

 

    <section title="Omnibroker Query Service">
      <!-- Begin section of automatically generated text
Line wrap = 66
   -->

        <section title="Illustrative example">
  <t>
[For illustrative purposes, all the examples in this section
are shown using the Web Services Transport binding.  
Examples of other transport bindgins are shown in  
section [TBS].]
  </t>
          <t>
     The Alice of the previous example uses her Web browser to
 access the URL www.example.com://www.example.com/. Assuming this
   was done while
 the prior binding was still active (i.e. before the UnbindRequest
 message was sent), the Web browser would send a
  QueryConnectRequest  
 request to obtain the best connection parameters for the  
 http protocol at  
 www.example.com:
  </t>

          <figure>
            <artwork>
<![CDATA[Post / HTTP/1.1
Host: example.com
Cache-Control: no-store
Content-Type: Application/json;charset=UTF-8
Content-Length: 131
Content-Integrity:
  mac=9ZSkLYKFMYenvqt/MwkAtvetqvM7Nydh6Rc2bvbKTbM=;
  ticket=jpBXvI7/0WTmwI2NN4n7Vvw96nbS9LpSsSNMIkdapiUoLikSkjpgMrtbVK
    z5lHOPloCgAyZXxfZpQRsp4oPY4BcRaMw6F5na62IHnBVDeXg=

{
  "QueryConnectRequest": {
    "Identifier": {
      "Name": "http",
      "Service": "www.example.com",
      "Port": 80}}}]]>
            </artwork>
          </figure>

<t>
The service responds with an ordered list of possible connections.
In this case the site is accessible via plain TCP transport or with
TLS. Since TLS is the preferred protocol, that connection is
listed first.
</t>
          <figure>
            <artwork>
<![CDATA[HTTP/1.1 200  
Content-Type: application/json;charset=UTF-8
Content-Length: 347
Content-Integrity:
  mac=1oFa8fNsRbKiCCnwd4feSqq+h/by+tCLbw2bzf235TU=;
  ticket=jpBXvI7/0WTmwI2NN4n7Vvw96nbS9LpSsSNMIkdapiUoLikSkjpgMrtbVK
    z5lHOPloCgAyZXxfZpQRsp4oPY4BcRaMw6F5na62IHnBVDeXg=

{
  "QueryConnectResponse": {
    "Status": 200,
    "Connection": [{
        "IPAddress": "10.3.2.1",
        "IPPort": 443,
        "Transport": "TLS",
        "TransportPolicy": "TLS=Optional",
        "ProtocolPolicy": "Strict"},
      {
        "IPAddress": "10.3.2.1",
        "IPPort": 80,
        "ProtocolPolicy": "Strict"}]}}]]>
            </artwork>
          </figure>

<t>
Although the QueryConnectResponse returned the hash of a PKIX
certificate considered valid for that connection, the server
returns a different certificate which the client verifies using
the ValidateRequest query.

</t>
          <figure>
            <artwork>
<![CDATA[Post / HTTP/1.1
Host: example.com
Cache-Control: no-store
Content-Type: Application/json;charset=UTF-8
Content-Length: 124
Content-Integrity:
  mac=S+xlW2U6z1REQmbNHiOnAw4xpUXP8wJXZiCJzMzQelc=;
  ticket=jpBXvI7/0WTmwI2NN4n7Vvw96nbS9LpSsSNMIkdapiUoLikSkjpgMrtbVK
    z5lHOPloCgAyZXxfZpQRsp4oPY4BcRaMw6F5na62IHnBVDeXg=

{
  "ValidateRequest": {
    "Credential": {
      "Type": "application/x-x509-server-cert",
      "Data": "AAECAwQ="}}}]]>
            </artwork>
          </figure>

<t>
The service validates the certificate according to the  
Omnibroker service policy.  
</t>
          <figure>
            <artwork>
<![CDATA[HTTP/1.1 200  
Content-Type: application/json;charset=UTF-8
Content-Length: 47
Content-Integrity:
  mac=jrsfxojksHBVs1WWxVbX3nn+CaIIix2JrrTTQn0X43k=;
  ticket=jpBXvI7/0WTmwI2NN4n7Vvw96nbS9LpSsSNMIkdapiUoLikSkjpgMrtbVK
    z5lHOPloCgAyZXxfZpQRsp4oPY4BcRaMw6F5na62IHnBVDeXg=

{
  "ValidateResponse": {
    "Status": 200}}]]>
            </artwork>
          </figure>

</section>


<!-- End section of automatically generated text -->

      



<section title="OBPQuery">


<section title="Message: Payload">


<!-- No parameters -->

</section>
<section title="Message: Message">


<!-- No parameters -->

</section>
<section title="Message: Request">

<t>
Every query request contains the following common elements:
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Index : Integer [0..1]   " />
<t>
Index used to request a specific response when multiple 
responses are available.
</t>
</list></t>

</section>
<section title="Message: Response">

<t>
Every Query Response contains the following common elements:
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Status : Integer [1..1]   " />
<t>
Status return code value
</t>
<t hangText="Index : Integer [0..1]   " />
<t>
Index of the current response.
</t>
<t hangText="Count : Integer [0..1]   " />
<t>
Number of responses available.
</t>
</list></t>

</section>
<section title="Structure: Identifier">

<t>
Specifies an Internet service by means of a DNS address and either a
DNS service prefix, an IP port number or both. An Internet peer 
connection MAY be specified by additionally specifying an account.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Name : Name [1..1]   " />
<t>
The DNS name of the service to connect to.
</t>
<t>
Internationalized DNS names MUST be encoded in punycode
encoding.
</t>
<t hangText="Account : Label [0..1]   " />
<t>
Identifies the account to connect to in the case that a peer connection
is to be established.
</t>
<t hangText="Service : Name [0..1]   " />
<t>
The DNS service prefix defined for use with DNS records that
take a service prefix including SRV.
</t>
<t hangText="Port : Integer [0..1]   " />
<t>
IP Port number.
</t>
<t>
A service identifier MUST specify either a service or a port or both.						
</t>
</list></t>

</section>
<section title="Structure: Connection">


<t> <list style="hanging" hangIndent="6">
<t hangText="IPVersion : Integer [0..1]   " />
<t>
Contains the IP version field. If absent, IPv4 is assumed.
</t>
<t hangText="IPProtocol : Integer [0..1]   " />
<t>
Contains the IP protocol field. If absent, TCP is assumed.
</t>
<t hangText="IPAddress : Binary [0..1]   " />
<t>
IP address in network byte order. This will normally be an 
IPv4 (32 bit) or IPv6 (128 bit) address.
</t>
<t hangText="IPPort : Integer [0..1]   " />
<t>
IP port. 1-65535
</t>
<t hangText="TransportPolicy : String [0..1]   " />
<t>
Transport security policy as specified in [TBS]
</t>
<t hangText="ProtocolPolicy : String [0..1]   " />
<t>
Application security policy specification as specified by 
the application protocol.
</t>
<t hangText="Advice : Advice [0..1]   " />
<t>
Additional information that a service MAY return to support
a service connection identification. 
</t>
</list></t>

</section>
<section title="Structure: Advice">

<t>
Additional information that a service MAY return to support
a service connection identification. For example, DNSSEC 
signatures chains, SAML assertions, DANE records, 
Certificate Transparency proof chains, etc.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Type : Label [0..1]   " />
<t>
The IANA MIME type of the content type
</t>
<t hangText="Data : Binary [0..1]   " />
<t>
The advice data.
</t>
</list></t>

</section>
<section title="Structure: Service">

<t>
Describes a service connection
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Identifier : Identifier [0..Many]   " />
<t>
Internet addresses to which the service is to be bound.
</t>
<t hangText="Connection : Connection [0..1]   " />
<t>
Service connection parameters.
</t>
</list></t>

</section>
<section title="QueryConnect">

<t>
Requests a connection context to connect to a specified Internet service
or peer.
</t>

</section>
<section title="Message: QueryConnectRequest">

<t>
Specifies the Internet
service or peer that a connection is to be established to and the
acceptable security policies.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Identifier : Identifier [0..1]   " />
<t>
Identifies the service or peer to which a connection is 
requested.
</t>
<t hangText="Policy : Label [0..Many]   " />
<t>
Acceptable credential validation policy.
</t>
<t hangText="ProveIt : Boolean [0..1]   " />
<t>
If set the broker SHOULD send advice to permit the client to
validate the proposed connection context.
</t>
</list></t>

</section>
<section title="Message: QueryConnectResponse">

<t>
Returns one or more connection contexts in response to a 
QueryConnectRequest Message.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Connection : Connection [0..Many]   " />
<t>
An ordered list of connection contexts with the preferred
connection context listed first.
</t>
<t hangText="Advice : Advice [0..1]   " />
<t>
Proof information to support the proposed connection context.
</t>
<t hangText="Policy : Label [0..Many]   " />
<t>
Policy under which the credentials have been verified.	
</t>
</list></t>

</section>
<section title="Advertise">

<t>
Advises a broker that one or more Internet services are 
being offered with particular attributes.
</t>

</section>
<section title="Message: AdvertiseRequest">

<t>
Specifies the connection(s) to be established.
</t>
<t>
The attributes required depend on the infrastructure(s) that the 
broker is capable of registering the service with.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Service : Service [0..Many]   " />
<t>
Describes a connection to be established.
</t>
</list></t>

</section>
<section title="Message: AdvertiseResponse">

<t>
Specifies the connection(s)
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Service : Service [0..Many]   " />
<t>
Describes a connection that was established.
</t>
</list></t>

</section>
<section title="Validate">

<t>
The Validate query requests validation of credentials
presented to establish a connection. For example credentials
presented by a server in the process of setting up a 
TLS session.
</t>

</section>
<section title="Message: ValidateRequest">

<t>
Specifies the credentials to be validated and the purpose
for which they are to be used.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Service : Service [0..1]   " />
<t>
Describes the service for which the credentials 
are presented for access.
</t>
<t hangText="Credential : Credential [0..1]   " />
<t>
List of credentials for which validation is requested.
</t>
<t hangText="Policy : Label [0..Many]   " />
<t>
Policy under which the credentials have been verified.	
</t>
</list></t>

</section>
<section title="Message: ValidateResponse">

<t>
Reports the status of the credential presented.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Policy : Label [0..Many]   " />
<t>
Policy under which the credentials have been verified.	
</t>
</list></t>

</section>
<section title="QueryCredentialPassword">

<t>
The QueryCredentialPassword query is used to request a password credential
that the user has previously chosen to store at the broker.
</t>

</section>
<section title="Message: CredentialPasswordRequest">

<t>
Requests a password for the specified account.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Account : String [0..1]   " />
<t>
The account for which a password is requested.
</t>
</list></t>

</section>
<section title="Message: CredentialPasswordResponse">

<t>
Returns a password for the specified account.
</t>

<t> <list style="hanging" hangIndent="6">
<t hangText="Password : String [0..1]   " />
<t>
The requested password.
</t>
</list></t>

</section>

</section>



    </section>

    <section title="Transport Bindings">
      <t>
        To achieve an optimal balance of efficiency and availability,
        three transport bindings are defined:
      </t>
      <t>
        <list>
          <t hangText="HTTP over TLS">Supports all forms of OBP
          transaction in all network environments.</t>
          <t hangText="DNS Tunnelling">Provides efficient support for a subset
          of OBP query transactions that is accessible in most network
          environments.</t>
          <t hangText="UDP">
            Provides efficient support for all OBP query transactions 
            and is accessible in most network environments.
          </t>
        </list>
      </t>
      <t>
        Support for the HTTP over TLS binding is REQUIRED.
      </t>
      <t>
        An OBP message consists of three parts:
        <list style="hanging">
          <t hangText="Ticket [As necessary]">
            If specified, identifies the cryptographic key and algorithm parameters to be used
            to secure the message payload.
          </t>
          <t hangText="Payload [Required]">
            If the ticket context does not specify use of an encryption algorithm,
            contains the message data. Otherwise contains the 
            message data encrypted under the 
            encryption algorithm and key specified in the ticket context.
          </t>
          <t hangText="Authenticator [Optional]">
            If the ticket context specifies use of a Message Authentication 
            Code (MAC), contains the MAC value calculated over the payload data
            using the authentication key bound to the ticket.
          </t>
        </list>
      </t>
      <t>
        Note that although each of the transport bindings defined in this specification
        entail the use of a JSON encoding for the message data, this is not a 
        necessary requirement for a transport binding. 
      </t>


      <section title="HTTP over TLS">
        <t>
          OBP requests and responses are mapped to HTTP POST requests
          and responses respectively. Java Script Object Notation (JSON)
          encoding is used to encode requests and responses.
        </t>
        <section title="Message Encapsulation">
          <t>
            Requests and responses are mapped to HTTP POST transactions. 
            The content of the HTTP message is the message payload.
            The Content-Type
            MUST be specified as application/json. The Character set MUST
            be specified as UTF-8.
          </t>
          <t>
            The Ticket and Authenticator are specified using the Integrity
            header as follows:
          </t>
          <t>
            Integrity: <base64 (authenticator)> ; ticket=<base64 (ticket)>
          </t>
        </section>     
        <section title="Example">
          <t>
            [To be generated from spec]
          </t>
        </section>
      </section>
      <section title="DNS Tunnel">
        <t>
          The DNS Tunnel mode of operation makes use of DNS TXT resource record
          requests and responses to tunnel OBP Query requests. Due to the constraints
          of this particular mode of operation, use of this transport is in
          practice limited to supporting transactions that can be
          expressed within 500 bytes. These include the QueryConnect
          and ValidateRequest interactions.
        </t>
        <section title="Request">
          <t>Requests are mapped to DNS TXT queries. The request is mapped onto
          the DNS name portion of the query by encoding the Ticket, Authenticator 
          and JSON encoded Payload using Base32 encoding and appending the result to the
          service prefix to create a DNS name as follows:
        </t>
          
            <t>
              <base32(payload)>.<base32(authenticator)>.<base32(ticket)>.Suffix
                
              </t>
          <t>
            The payload MAY be split across multiple DNS labels at any point.
          </t>
        </section>
        <section title="Response">
          <t>
            Responses are mapped to DNS TXT records by encoding the Authenticator
            and JSON encoded Payload using Base64 encoding and cocatenating the result
            with a periods as a separator as follows:
          </t>
        <t>
          <base32(payload)>.<base32(authenticator)>
        </t>
          
        </section>
        <section title="Example">
          <t>
            [To be generated from spec]
          </t>
        </section>
      </section>
      <section title="UDP">
        <t>
          The UDP transport MAY be used for transactions where the request 
          fits into a single UDP packet and the response can be accomadated in
          16 UDP packets.
          As with the Web Service Binding, Java Script Object Notation (JSON)
          encoding is used to encode requests and responses.
        </t>
        <section title="Request">
          <t>The request consists of four message segments containing a Header, 
          Ticket, Payload and Authenticator. Each message segment begins with a 
          two byte field that specified the length of the following data segment
          in network byte order. The Payload is encoded in JSON encoding and the
          remaining fields as binary data without additional encoding.
        </t>
          <t>
            The header field for this version of the protocol (1.0) contains two 
            bytes that specify the Major and Minor version number of the transport 
            protocol being 1 and 0 respectively. Future versions of the transport 
            protocol MAY specify additional data fields.
          </t>
          <t>
            [TBS diagram]
          </t>          
        </section>
        <section title="Response">
          <t>The response consists of a sequence of packets. Each packet consists 
          of a header section and a data section.</t>
          <t>
            The header section consists of a two byte length field followed by two 
            bytes that speciofy the Major and Minor version number of the transport 
            protocol (1 and 0), two bytes that specify the frame number
            and the total number of frames and two bytes that specify the message 
            identifier.
          </t>
          <t>
            [TBS diagram]
          </t>
          <t>
            [Question, should the authenticator be over the whole message 
            or should each packet have its own authenticator?]
          </t>
        </section>
        <section title="Example">
          <t>
            [To be generated from spec]
          </t>
        </section>
      </section>
    </section>
    <section title="Acknowledgements">
      <t>
        [List of contributors]
      </t>
    </section>
    <section title="Security Considerations">

      <section title="Denial of Service">
      </section>
      <section title="Breach of Trust">
      </section>
      <section title="Coercion">
      </section>

    </section>
    <section title="To do">
      <t>

        <list>
          <t>
            The specification should define and use a JSON security object.
          </t>
          <t>Formatting of the abstract data items needs to be improved</t>
          <t>
            Need to specify the UDP transport binding
          </t>
          <t>
            Should specify how each data item is represented in JSON format 
            somewhere. This is obvious for some of the data types but needs 
            to be fully specified for things like DateTime.
          </t>
          <t>
            Run the code to produce proper examples.
          </t>
          <t>
            Write a tool to transclude the example and other xml data into 
            the document source.
          </t>
          <t>
            Fully document the API section.
          </t>
        </list>
      </t>
    </section>

    <section title="IANA Considerations">
      <t>
        [TBS list out all the code points that require an IANA
        registration]
      </t>
    </section>

  </middle>



  <back>


    <references title="Normative References">
      &RFC1035;
      &RFC2119;
      &RFC4366;

      <reference anchor="X.509">
        <front>
          <title>
            ITU-T Recommendation X.509 (11/2008): Information
            technology - Open systems interconnection - The
            Directory: Public-key and attribute certificate
            frameworks
          </title>
          <author>
            <organization>
              International Telecommunication Union
            </organization>
          </author>
          <date month="November" year="2008" />
        </front>
        <seriesInfo name="ITU-T Recommendation" value="X.509" />
        <format type="HTML" target="http://www.itu.int/itu-t/recommendations/rec.aspx?rec=X.509" />
      </reference>
      <reference anchor="X.680">
        <front>
          <title>
            ITU-T Recommendation X.680 (11/2008): Information
            technology - Abstract Syntax Notation One (ASN.1):
            Specification of basic notation
          </title>
          <author>
            <organization>
              International Telecommunication Union
            </organization>
          </author>
          <date month="November" year="2008" />
        </front>
        <seriesInfo name="ITU-T Recommendation" value="X.680" />
        <format type="HTML" target="http://www.itu.int/itu-t/recommendations/rec.aspx?rec=X.680" />
      </reference>

    </references>
    <!--<references title="Non Normative References">

        </references>-->

    <section title="Example Data.">
      <t>

      </t>
      <section title="Ticket A">
        <t>

        </t>
      </section>
      <section title="Ticket B">
        <t>

        </t>
      </section>
    </section>

  </back>
</rfc>