Skip to content

Commit

Permalink
Merge pull request #30 from arpa2/validation
Browse files Browse the repository at this point in the history
Validation
  • Loading branch information
vanrein authored Jun 19, 2016
2 parents 49bf115 + 6970391 commit 5a62066
Show file tree
Hide file tree
Showing 31 changed files with 4,051 additions and 102 deletions.
82 changes: 57 additions & 25 deletions doc/databases.rst
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ This is a duplicate hash database; one key may hold multiple values.

**Key** is the DoNAI of the local user.

**Value** is a binary compositions of the following elements:
**Values** each are a binary composition of the following elements:

* A 32-bit value in network byte order, containing ``LID_xxx`` flags;
* A `PKCS #11 URI`_ referencing the private key for the identity;
Expand All @@ -110,6 +110,15 @@ There are a few more flags in the initial word of an entry:
* ``LID_ROLE_SERVER`` is set if this entry can be used in TLS servers;
* Both may be set, and indeed this may be common for OpenPGP keys.

A special form of the localid entry is for an validation expression that
may be applied to the local identity represented in the key; this is
setup as ``LID_TYPE_VALEXP``. Its PKCS #11 string is abused to hold the
validation expression, and it has the following 0x00 byte as a C-style
string terminator. There is no binary value stored for this type of entry.
Note that the same validation expression applies to all the forms of
identifying as the local identity. When this entry is absent, it is
considered to permit anything, as were the validation expression "1".


Identity disclosure database
----------------------------
Expand Down Expand Up @@ -158,22 +167,28 @@ back even in the presence of a database entry, then all the
entries found will be reported and a choice can be made by that tool.


**TODO:** We should probably also define a validation expression in
the disclosure database, to mark restrictions on contact with those
particular remote selections. If that is done, we should also apply
this validation expression to the case where the remote is a client!
We might terminate the first entry with a NUL character to indicate
a validation expression, for instance; that is invalid DoNAI syntax.


Trust database
--------------

**TODO:** Complete

The default name of this database is ``trust.db``.

The purpose of this database is to establish trust in credentials such as
certificates. It may hold several methods to establish this trust:
certificates or Kerberos principal names. It may hold several methods to
establish this trust:

- Trust anchors, notably X.509 root certificates and trusted OpenPGP public keys
- X.509 certificate chains of OpenPGP public key paths leading to a trust anchor
- Pinned public credentials for individual peer identities
- Withdrawal descriptors to express explicit loss of trust
- Validation requirements for anything subordinate this entry
* Trust anchors, notably X.509 root certificates and trusted OpenPGP public keys
* X.509 certificate chains of OpenPGP public key paths leading to a trust anchor
* Pinned ending time stamps (must-change and may-change, if provided)
* Withdrawal descriptors to express explicit loss of trust
* Validation requirements for anything subordinate this entry

Entries in this database are accessible to parties other than the TLS Pool;
this means that it would be possible to control the TLS Pool centrally by
Expand All @@ -186,20 +201,37 @@ as OCSP or DANE could be used to retrieve information to be automaically
inserted into this database. This might be done from a central location,
and both simplify and speedup the management of provisioned setups.


Policy database
---------------

**TODO:** Complete

The default name of this database is ``policy.db``.

The purpose of this database is to store the current policy settings, and
to permit dynamic changes to these settings in a way that is automatically
picked up by the TLS Pool.

Lookups in this database are based on local/remote identities, which are
searched through iteration with a DoNAI selector that gradually moves from
concrete identity to the most abstract one.

**Key** is a binary representation of data to be found:

* The `AuthorityKeyIdentifier` [Section 4.2.1.1 of RFC 5280] that must
be used in all CA-signed certificates other than a root certificate.
* The 64-bit v4 key ID [Section 12.2 of RFC 4880] of a PGP public key.
* The SHA-256 fingerprint of a pinned endpoint credential.

**Values** each are a binary composition of the following elements:

* A 32-bit flag field in network-byte order,
including the type of material represented in the key, according to
the database entry at hand (each type has separate entries), one of the
flags is used to indicate revocation rather than confirmation;
* A NUL-terminated string holding a validation expression (the least of
which would be "1", or 0x30 0x00); this is meaningful for signing entries;
* The parameters for the given type; usually, a credential to use for
validation:

- For X.509 root certificates, a CA root key; intermediate keys are
assumed to have been passed from remote to local.
- For PGP keys, a trusted signing key in PGP public key transport
format; these may be looked up with key IDs of Issuer subpackets found
in signatures; note that only one-level PGP signing is supported,
but PGP's potential diversity of signers is fully supported.
- There are revocation entries (whose validation expression is ignored)
with times for an update (and the next) and a sequence of certificate
serial numbers. These revocation entries are stored under the same
key as a trusted entry, after this principal trusted entry.
- For pinning, there are a few flavours; a 32-bit type field defines
the type of data. Since a secure hash has matched, there is no
further mention of the unfolded pinning information. Following is a
NUL-terminated string holding the remote identity established with
the pinned end entity credential.

187 changes: 187 additions & 0 deletions doc/steamworks-config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
Configuring TLS Pool over SteamWorks
====================================

> *This document details what data the TLS Pool needs to be able to pull from
> SteamWorks, and it describes how this leads to a general format that
> SteamWorks should support. The data structures are considered flexible,
> because Pulley can mix & match what it finds in various parts of the LDAP
> structures.*
Information need for the TLS Pool
---------------------------------

- The TLS Pool needs to be able to fill its databases. The various database
must be kept as independent as they currently are.

- The settings are meant to be added to any local settings that may have been
created in the databases by the TLS Pool user. It may be useful to ban
certain values, but this does not seem easily possible.

- This comes down to the following data sets:

- *remoteid to localids.* This mapping is used to decide what local
identity to present to a remote. The remote is generally not represented
by a Domain-or-Network-Access-Identifier or DoNAI, but by a DoNAI
Selector (see http://donai.arpa2.net). A trust validation expression
may be included for each remote identity DoNAI Selector.

- *localid to credentials.* This mapping is used to store various
credential forms, such as certificates, PGP public keys, and so on. The
PKCS \#11 URIs will be included. A trust validation expression may be
included for each local identity DoNAI.

- *trust settings.* This mapping is used to create trust bases, such as
root certificates and pinning information. Each trust setting includes
a trust validation expression.

General information model for SteamWorks
----------------------------------------

- SteamWorks is meant to store configuration information in LDAP.

- Anything described here for SteamWorks can be used in other LDAP contexts as
well.

- Configuration information should use existing LDAP structures whenever
possible.

- Objects in LDAP are defined to hold one atomic unit of configuration.

- Units of configuration may be combined as desired, for instance
hierarchically.

- There are likely to be “configuration sections” and “options with values”.

- Access control will be exercised to reveal configuration only to desirable
parties.

Specific model for TLS Pool
---------------------------

- Configuration information is more accurate when poored into dedicated
structures

- Access control is easier to apply on dedicated data; and this really helps
security

- Those TLS Pool specifics are constrained to an in-house /controlled
environment

- So… we are going to make special definitions for the TLS Pool in LDAP

LocalID
-------

We represent the `localid.db` with an LDAP object per entry; multiple entries
may share one key so we need to be somewhat careful; we cannot just use the
local identity to identify the LDAP object. We can however add extra attributes,
in the DN or even in the RDN of the object, to signify the entry in the
database; specifically, `credentialType` and `supportedRole`, and perhaps more
in future incarnations of this schema. During updates and removals, clients
should look for entries that match the entire RDN, with the exception of local
additons such as derived flags. This problem does not exist for the
`disclose.db` whose entries can be enumerated as a list of DoNAIs.



We will not define a syntax and matching rules for DoNAI and DoNAI Selector, as
in

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# syntax ( TODO
# DESC 'DoNAI, Domain or Netwerk Access Identifier, see http://donai.arpa2.net' )
# syntax ( TODO
# DESC 'DoNAI Selector, see http://donai.arpa2.net/selector.html' )
# matchingrule ( TODO
# DESC 'Compare if a DoNAI matches a DoNAI Selector'
# SYNTAX TODO )
# matchingrule ( TODO
# DESC 'Compare if a DoNAI Selector matches a DoNAI'
# SYNTAX TODO )
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Instead, we will treat the DoNAI as an IA5String and restrict the syntax through
comments.



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
attributetype ( 1.3.6.1.4.1.44469.666.11.443.1.1
NAME 'tlsPoolCredentialType'
DESC 'Short standardised string to describe the kind of credential: x509, openpgp, openssh, krb5, srp11, ...'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 # IA5String
EQUALITY 1.3.6.1.4.1.1466.109.114.2 # caseIgnoreIA5Match
)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
attributetype ( 1.3.6.1.4.1.44469.666.11.443.1.2
NAME 'tlsPoolSupportedRole'
DESC 'A role that this object can play; usually values are limited to "client" and "server" but symmetric peers may set both values using two supportedRole attributes in the same object'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 # IA5String
EQUALITY 1.3.6.1.4.1.1466.109.114.2 # caseIgnoreIA5Match
)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
attributetype ( 1.3.6.1.4.1.44469.666.11.443.1.3
NAME 'tlsPoolValidationExpression'
DESC 'An expression in the validation logic of the TLS Pool'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 # IA5String
EQUALITY 1.3.6.1.4.1.1466.109.114.2 # caseIgnoreIA5Match
SINGLE-VALUE
)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
objectclass ( 1.3.6.1.4.1.44469.666.11.443.1.6
NAME 'tlsPoolTrustedIssuer'
DESC 'A credential that is considered trustworthy under the given validation expression'
SUP distinguishedName
MUST ( tlsPoolCredentialType $ tlsPoolSupportedRole )
)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
objectclass ( 1.3.6.1.4.1.44469.666.11.443.1.7
NAME 'tlsPoolLocalUserCredential'
DESC 'A (key,value) entry in the TLS Pool database of Local Identities'
SUP pkcs11PrivateKeyObject STRUCTURAL
MUST ( tlsPoolCredentialType $ tlsPoolSupportedRole )
)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
objectclass ( 1.3.6.1.4.1.44469.666.11.443.1.8
NAME 'tlsPoolIdentityDisclosure'
DESC 'A (key,value) entry in the TLS Pool database for Disclosure of Local Identities; the group name is in the "cn" attribute and group members are denoted as "cn=" RDN values in the "member" attributes'
SUP groupOfNames STRUCTURAL
MUST ( cn $ member )
)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
objectclass ( 1.3.6.1.4.1.44469.666.11.443.1.9
NAME 'tlsPoolValidationRequirements'
DESC 'Requirements imposed on or by the described object'
AUXILIARY
MUST ( tlsPoolValidationExpression )
)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


26 changes: 19 additions & 7 deletions doc/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,19 @@ These *2 or 3 sources of constraints* for remote ID validation can all be looked
up in databases. They are combined to one expression, in such a way that they
all apply.

**NOTE:** Mention of validation expressions in multiple sources is currently
not supported; setup either in `localid.db` or `trust.db` to avoid landing
the TLS Pool in undefined territory. See
[reported issue](https://github.com/arpa2/tlspool/issues/27).

Constraint Language
-------------------

**Note:** Not all the predicates defined below have been (completely)
implemented. Checkout
[the issue](https://github.com/arpa2/tlspool/issues/29)
for up-to-date information.

The following constructs are supported; consider them as stack manipulation
operations:

Expand All @@ -100,13 +110,15 @@ operations:
distinction between these three levels, even their ordering, is a local
policy setting.

- `I` ensures that the remote peer provides an identity. The variation `i`
requests an identity from the remote, but will not enforce it. This will
often be used by a local ID that desires to know the remote ID of its
counterpart. Note that this request may also be made by the TLS Pool client,
so flagging it in a validation expression is only useful to establish
authentication for all interactions regardless of their usefulness for end
points.
- `I` and `i` ensure that the remote peer provides an identity, and that it
does not contradict the remote identity requested by an application.
This will often be used by a local ID that desires to know the remote ID
if its counterpart. The remote identity reported back to the application
may be enhanced with identity information from the remote certification.
The form `I` requires that the domain and username match (where absense
of username in both is acceptable) whereas the `i` form permits a
remote domain identity to speak on behalf of users underneath that
domain without certifying for the username part.

- `F` ensures that forward secrecy is employed to protect the connection. This
property is only ensured by `TLS_DHE_`, `TLS_ECDHE_`, `TLS_SRP_` and our own
Expand Down
4 changes: 4 additions & 0 deletions etc/tlspool.conf
Original file line number Diff line number Diff line change
Expand Up @@ -129,10 +129,14 @@ deny_facilities
# db_disclose is the filename of a database, defaults to "disclose.db".
# When dbenv_dir is set, this is relative to that directory.
#
# db_trust is the filename of a database, defaults to "trust.db".
# When dbenv_dir is set, this is relative to that directory.
#

dbenv_dir ../testdata/tlspool.env
db_localid ../localid.db
db_disclose ../disclose.db
db_trust ../trust.db

#
# The TLS Pool is an application layer over PKCS #11. Configure which
Expand Down
Loading

0 comments on commit 5a62066

Please sign in to comment.